Platform abstraction layer

Documentation of the types and calls required to port MQTT-C to a new platform. More...

Macros
#define	MQTT_PAL_HTONS(s)
	host-to-network endian conversion for uint16_t.
#define	MQTT_PAL_NTOHS(s)
	network-to-host endian conversion for uint16_t.
#define	MQTT_PAL_TIME()
	returns [type: mqtt_pal_time_t] current time in seconds.
#define	MQTT_PAL_MUTEX_INIT(mtx_ptr)
	macro that initializes the mutex pointed to by mtx_ptr.
#define	MQTT_PAL_MUTEX_LOCK(mtx_ptr)
	macro that locks the mutex pointed to by mtx_ptr.
#define	MQTT_PAL_MUTEX_UNLOCK(mtx_ptr)
	macro that unlocks the mutex pointed to by mtx_ptr.

Typedefs
typedef void	mqtt_pal_time_t
	return type of MQTT_PAL_TIME()
typedef void	mqtt_pal_mutex_t
	type of the argument that is passed to MQTT_PAL_MUTEX_INIT(), MQTT_PAL_MUTEX_LOCK() and MQTT_PAL_MUTEX_UNLOCK().

Functions
ssize_t	mqtt_pal_sendall (mqtt_pal_socket_handle fd, const void *buf, size_t len, int flags)
	Sends all the bytes in a buffer.
ssize_t	mqtt_pal_recvall (mqtt_pal_socket_handle fd, void *buf, size_t bufsz, int flags)
	Non-blocking receive all the byte available.

Detailed Description

Documentation of the types and calls required to port MQTT-C to a new platform.

mqtt_pal.h is the only header file included in mqtt.c. Therefore, to port MQTT-C to a new platform the following types, functions, constants, and macros must be defined in mqtt_pal.h:

• Types:
  • size_t, ssize_t
  • uint8_t, uint16_t, uint32_t
  • va_list
  • mqtt_pal_time_t
  • mqtt_pal_mutex_t
• Functions:
  • memcpy, strlen
  • va_start, va_arg, va_end
• Constants:
  • INT_MIN

Additionally, six macro's are required:

• MQTT_PAL_HTONS(s)
• MQTT_PAL_NTOHS(s)
• MQTT_PAL_TIME()
• MQTT_PAL_MUTEX_INIT(mtx_ptr)
• MQTT_PAL_MUTEX_LOCK(mtx_ptr)
• MQTT_PAL_MUTEX_UNLOCK(mtx_ptr)

Lastly, mqtt_pal_sendall and mqtt_pal_recvall, must be implemented in mqtt_pal.c for sending and receiving data using the platforms socket calls.

Function Documentation

mqtt_pal_recvall()

ssize_t mqtt_pal_recvall	(	mqtt_pal_socket_handle	fd,
		void *	buf,
		size_t	bufsz,
		int	flags )

Non-blocking receive all the byte available.

Parameters

[in]	fd	The file-descriptor (or handle) of the socket.
[in]	buf	A pointer to the receive buffer.
[in]	bufsz	The max number of bytes that can be put into buf.
[in]	flags	Flags which are passed to the underlying socket.

Returns

The number of bytes received if successful, an MQTTErrors otherwise.

Note about the error handling:

• On an error, if some bytes have been processed already, this function should return the number of bytes successfully processed. (partial success)
• Otherwise, if the error is an equivalent of EAGAIN, return 0.
• Otherwise, return MQTT_ERROR_SOCKET_ERROR.

mqtt_pal_sendall()

ssize_t mqtt_pal_sendall	(	mqtt_pal_socket_handle	fd,
		const void *	buf,
		size_t	len,
		int	flags )

Sends all the bytes in a buffer.

Parameters

[in]	fd	The file-descriptor (or handle) of the socket.
[in]	buf	A pointer to the first byte in the buffer to send.
[in]	len	The number of bytes to send (starting at buf).
[in]	flags	Flags which are passed to the underlying socket.

Returns

The number of bytes sent if successful, an MQTTErrors otherwise.

Note about the error handling:

• On an error, if some bytes have been processed already, this function should return the number of bytes successfully processed. (partial success)
• Otherwise, if the error is an equivalent of EAGAIN, return 0.
• Otherwise, return MQTT_ERROR_SOCKET_ERROR.