Implements most user-facing functions of the MQTT library. More...

#include "iot_config.h"
#include <string.h>
#include <limits.h>
#include "types/iot_mqtt_types.h"
#include "private/iot_mqtt_helper.h"
#include "iot_mqtt_lightweight.h"
#include "iot_logging_setup.h"

Macros
#define	IotMqtt_Assert(expression)
	Assertion macro for the MQTT library. More...

Functions
static size_t	_getRemainingLength (IotNetworkConnection_t pNetworkConnection, IotMqttGetNextByte_t getNextByte)
	Get the remaining length from a stream of bytes off the network. More...

static IotMqttError_t	_deserializeConnack (IotMqttPacketInfo_t *pConnack)
	Deserialize a CONNACK packet. More...

static IotMqttError_t	_deserializeSuback (IotMqttPacketInfo_t *pSuback)
	Deserialize a SUBACK packet. More...

static IotMqttError_t	_deserializePuback (IotMqttPacketInfo_t *pPuback)
	Deserialize a PUBACK packet. More...

static IotMqttError_t	_deserializePingresp (IotMqttPacketInfo_t *pPingresp)
	Deserialize a PINGRESP packet. More...

static IotMqttError_t	_deserializeUnsuback (IotMqttPacketInfo_t *pUnsuback)
	Deserialize a UNSUBACK packet. More...

static IotMqttError_t	_deserializePublish (IotMqttPacketInfo_t *pPublish)
	Deserialize a PUBLISH packet received from the server. More...

static IotMqttError_t	_readSubackStatus (size_t statusCount, const uint8_t *pStatusStart)
	Decode the status bytes of a SUBACK packet. More...

static IotMqttError_t	_checkPublishRemainingLength (const IotMqttPacketInfo_t *pPublish, IotMqttQos_t qos, size_t qos0Minimum)
	Check the remaining length of incoming Publish against some value for QoS 0 or QoS 1/2. More...

IotMqttError_t	IotMqtt_GetConnectPacketSize (const IotMqttConnectInfo_t pConnectInfo, size_t pRemainingLength, size_t *pPacketSize)
	Calculate the size and "Remaining length" of a CONNECT packet generated from the given parameters. More...

IotMqttError_t	IotMqtt_SerializeConnect (const IotMqttConnectInfo_t pConnectInfo, size_t remainingLength, uint8_t pBuffer, size_t bufferSize)
	Generate a CONNECT packet from the given parameters. More...

IotMqttError_t	IotMqtt_GetSubscriptionPacketSize (IotMqttOperationType_t type, const IotMqttSubscription_t pSubscriptionList, size_t subscriptionCount, size_t pRemainingLength, size_t *pPacketSize)
	Calculate the size and "Remaining length" of a SUBSCRIBE or UNSUBSCRIBE packet generated from the given parameters. More...

IotMqttError_t	IotMqtt_SerializeSubscribe (const IotMqttSubscription_t pSubscriptionList, size_t subscriptionCount, size_t remainingLength, uint16_t pPacketIdentifier, uint8_t *pBuffer, size_t bufferSize)
	Generate a SUBSCRIBE packet from the given parameters. More...

IotMqttError_t	IotMqtt_GetIncomingMQTTPacketTypeAndLength (IotMqttPacketInfo_t *pIncomingPacket, IotMqttGetNextByte_t getNextByte, IotNetworkConnection_t pNetworkConnection)
	Extract MQTT packet type and length from incoming packet. More...

IotMqttError_t	IotMqtt_GetPublishPacketSize (const IotMqttPublishInfo_t pPublishInfo, size_t pRemainingLength, size_t *pPacketSize)
	Calculate the size and "Remaining length" of a PUBLISH packet generated from the given parameters. More...

IotMqttError_t	IotMqtt_SerializePublish (const IotMqttPublishInfo_t pPublishInfo, size_t remainingLength, uint16_t pPacketIdentifier, uint8_t *pPacketIdentifierHigh, uint8_t pBuffer, size_t bufferSize)
	Generate a PUBLISH packet from the given parameters. More...

IotMqttError_t	IotMqtt_SerializeUnsubscribe (const IotMqttSubscription_t pSubscriptionList, size_t subscriptionCount, size_t remainingLength, uint16_t pPacketIdentifier, uint8_t *pBuffer, size_t bufferSize)
	Generate a UNSUBSCRIBE packet from the given parameters. More...

IotMqttError_t	IotMqtt_SerializeDisconnect (uint8_t *pBuffer, size_t bufferSize)
	Generate a DISCONNECT packet. More...

IotMqttError_t	IotMqtt_SerializePingreq (uint8_t *pBuffer, size_t bufferSize)
	Generate a PINGREQ packet. More...

IotMqttError_t	IotMqtt_DeserializePublish (IotMqttPacketInfo_t *pMqttPacket)
	Deserialize incoming publish packet. More...

IotMqttError_t	IotMqtt_DeserializeResponse (IotMqttPacketInfo_t *pMqttPacket)
	Deserialize incoming ack packets. More...

Detailed Description

Implements most user-facing functions of the MQTT library.

Macro Definition Documentation

◆ IotMqtt_Assert

#define IotMqtt_Assert ( expression )

Assertion macro for the MQTT library.

Set IOT_MQTT_ENABLE_ASSERTS to 1 to enable assertions in the MQTT library.

Parameters

[in] expression Expression to be evaluated.

Function Documentation

◆ _getRemainingLength()

static size_t _getRemainingLength	(	IotNetworkConnection_t	pNetworkConnection,
		IotMqttGetNextByte_t	getNextByte
	)

static

Get the remaining length from a stream of bytes off the network.

Parameters

[in]	pNetworkConnection	Reference to the network connection.
[in]	getNextByte	Function pointer used to interact with the network to get next byte.

Returns: The remaining length; MQTT_REMAINING_LENGTH_INVALID on error.

Note: This function is similar to _IotMqtt_GetRemainingLength() but it uses user provided getNextByte function to parse the stream instead of using _IotMqtt_GetNextByte(). pNetworkConnection is implementation dependent and user provided function makes use of it.

◆ _deserializeConnack()

static IotMqttError_t _deserializeConnack ( IotMqttPacketInfo_t * pConnack )

static

Deserialize a CONNACK packet.

Converts the packet from a stream of bytes to an IotMqttError_t. Also prints out debug log messages about the packet.

Parameters

[in,out] pConnack Pointer to an MQTT packet struct representing a CONNACK.

Returns: IOT_MQTT_SUCCESS if CONNACK specifies that CONNECT was accepted; IOT_MQTT_SERVER_REFUSED if CONNACK specifies that CONNECT was rejected; IOT_MQTT_BAD_RESPONSE if the CONNACK packet doesn't follow MQTT spec.

◆ _deserializeSuback()

static IotMqttError_t _deserializeSuback ( IotMqttPacketInfo_t * pSuback )

static

Deserialize a SUBACK packet.

Converts the packet from a stream of bytes to an IotMqttError_t and extracts the packet identifier. Also prints out debug log messages about the packet.

Parameters

[in,out] pSuback Pointer to an MQTT packet struct representing a SUBACK.

Returns: IOT_MQTT_SUCCESS if SUBACK is valid; IOT_MQTT_BAD_RESPONSE if the SUBACK packet doesn't follow MQTT spec.

◆ _deserializePuback()

static IotMqttError_t _deserializePuback ( IotMqttPacketInfo_t * pPuback )

static

Deserialize a PUBACK packet.

Converts the packet from a stream of bytes to an IotMqttError_t and extracts the packet identifier. Also prints out debug log messages about the packet.

Parameters

[in,out] pPuback Pointer to an MQTT packet struct representing a PUBACK.

Returns: IOT_MQTT_SUCCESS if PUBACK is valid; IOT_MQTT_BAD_RESPONSE if the PUBACK packet doesn't follow MQTT spec.

◆ _deserializePingresp()

static IotMqttError_t _deserializePingresp ( IotMqttPacketInfo_t * pPingresp )

static

Deserialize a PINGRESP packet.

Converts the packet from a stream of bytes to an IotMqttError_t. Also prints out debug log messages about the packet.

Parameters

[in,out] pPingresp Pointer to an MQTT packet struct representing a PINGRESP.

Returns: IOT_MQTT_SUCCESS if PINGRESP is valid; IOT_MQTT_BAD_RESPONSE if the PINGRESP packet doesn't follow MQTT spec.

◆ _deserializeUnsuback()

static IotMqttError_t _deserializeUnsuback ( IotMqttPacketInfo_t * pUnsuback )

static

Deserialize a UNSUBACK packet.

Converts the packet from a stream of bytes to an IotMqttError_t and extracts the packet identifier. Also prints out debug log messages about the packet.

Parameters

[in,out] pUnsuback Pointer to an MQTT packet struct representing an UNSUBACK.

Returns: IOT_MQTT_SUCCESS if UNSUBACK is valid; IOT_MQTT_BAD_RESPONSE if the UNSUBACK packet doesn't follow MQTT spec.

◆ _deserializePublish()

static IotMqttError_t _deserializePublish ( IotMqttPacketInfo_t * pPublish )

static

Deserialize a PUBLISH packet received from the server.

Converts the packet from a stream of bytes to an IotMqttPublishInfo_t and extracts the packet identifier. Also prints out debug log messages about the packet.

Parameters

[in,out] pPublish Pointer to an MQTT packet struct representing a PUBLISH.

Returns: IOT_MQTT_SUCCESS if PUBLISH is valid; IOT_MQTT_BAD_RESPONSE if the PUBLISH packet doesn't follow MQTT spec.

◆ _readSubackStatus()

static IotMqttError_t _readSubackStatus	(	size_t	statusCount,
		const uint8_t *	pStatusStart
	)

static

Decode the status bytes of a SUBACK packet.

Parameters

[in]	statusCount	Number of status bytes in the SUBACK.
[in]	pStatusStart	The first status byte in the SUBACK.

Returns: IOT_MQTT_SUCCESS, IOT_MQTT_SERVER_REFUSED, or IOT_MQTT_BAD_RESPONSE.

◆ _checkPublishRemainingLength()

static IotMqttError_t _checkPublishRemainingLength	(	const IotMqttPacketInfo_t *	pPublish,
		IotMqttQos_t	qos,
		size_t	qos0Minimum
	)

static

Check the remaining length of incoming Publish against some value for QoS 0 or QoS 1/2.

The remaining length for a QoS 1/2 will always be two greater than for a QoS 0.

Parameters

[in]	pPublish	Pointer to an MQTT packet struct representing a PUBLISH.
[in]	qos	The QoS of the PUBLISH.
[in]	qos0Minimum	Minimum possible remaining length for a QoS 0 PUBLISH.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_BAD_RESPONSE.

◆ IotMqtt_GetConnectPacketSize()

IotMqttError_t IotMqtt_GetConnectPacketSize	(	const IotMqttConnectInfo_t *	pConnectInfo,
		size_t *	pRemainingLength,
		size_t *	pPacketSize
	)

Calculate the size and "Remaining length" of a CONNECT packet generated from the given parameters.

Parameters

[in]	pConnectInfo	User-provided CONNECT information struct.
[out]	pRemainingLength	Output for calculated "Remaining length" field.
[out]	pPacketSize	Output for calculated total packet size.

Returns: IOT_MQTT_SUCCESS if the packet is within the length allowed by MQTT 3.1.1 spec; IOT_MQTT_BAD_PARAMETER otherwise. If this function returns IOT_MQTT_BAD_PARAMETER, the output parameters should be ignored.

Note: This call is part of serializer API used for implementing light-weight MQTT client.

Example

// Example code below shows how IotMqtt_GetConnectPacketSize() should be used to calculate
// the size of connect request.
IotMqttConnectInfo_t xConnectInfo;
size_t xRemainingLength = 0;
size_t xPacketSize = 0;
IotMqttError_t xResult;
// start with everything set to zero
memset( ( void * ) &xConnectInfo, 0x00, sizeof( xConnectInfo ) );
// Initialize connection info, details are out of scope for this example.
_initializeConnectInfo( &xConnectInfo );
// Get size requirement for the connect packet
xResult = IotMqtt_GetConnectPacketSize( &xConnectInfo, &xRemainingLength, &xPacketSize );
IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
 // Application should allocate buffer with size == xPacketSize or use static buffer
 // with size >= xPacketSize to serialize connect request.

◆ IotMqtt_SerializeConnect()

IotMqttError_t IotMqtt_SerializeConnect	(	const IotMqttConnectInfo_t *	pConnectInfo,
		size_t	remainingLength,
		uint8_t *	pBuffer,
		size_t	bufferSize
	)

Generate a CONNECT packet from the given parameters.

Parameters

[in]	pConnectInfo	User-provided CONNECT information.
[in]	remainingLength	remaining length of the packet to be serialized.
[in,out]	pBuffer	User provided buffer where the CONNECT packet is written.
[in]	bufferSize	Size of the buffer pointed to by pBuffer.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

Note: pBuffer must be allocated by caller. Use IotMqtt_GetConnectPacketSize to determine the required size.; This call is part of serializer API used for implementing light-weight MQTT client.

Example

// Example code below shows how IotMqtt_SerializeConnect() should be used to serialize
// MQTT connect packet and send it to MQTT broker.
// Example uses static memory but dynamically allocated memory can be used as well.
// Get size requirement for the connect packet.
#define mqttexampleSHARED_BUFFER_SIZE 100
static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];
void sendConnectPacket( int xMQTTSocket )
{
   IotMqttConnectInfo_t xConnectInfo;
   size_t xRemainingLength = 0;
   size_t xPacketSize = 0;
   IotMqttError_t xResult;
   size_t xSentBytes = 0;
   // Get size requirement for MQTT connect packet.
   xResult = IotMqtt_GetConnectPacketSize( &xConnectInfo, &xRemainingLength, &xPacketSize );
   IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
   // Make sure the packet size is less than static buffer size
   IotMqtt_Assert( xPacketSize < mqttexampleSHARED_BUFFER_SIZE );
   // Serialize MQTT connect packet into provided buffer
   xResult = IotMqtt_SerializeConnect( &xConnectInfo, xRemainingLength, ucSharedBuffer, xPacketSize );
   IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
   // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.
   xSentBytes = send( xMQTTSocket, ( void * ) ucSharedBuffer, xPacketSize, 0 );
   IotMqtt_Assert( xSentBytes == xPacketSize );
}

◆ IotMqtt_GetSubscriptionPacketSize()

IotMqttError_t IotMqtt_GetSubscriptionPacketSize	(	IotMqttOperationType_t	type,
		const IotMqttSubscription_t *	pSubscriptionList,
		size_t	subscriptionCount,
		size_t *	pRemainingLength,
		size_t *	pPacketSize
	)

Calculate the size and "Remaining length" of a SUBSCRIBE or UNSUBSCRIBE packet generated from the given parameters.

Parameters

[in]	type	Either IOT_MQTT_SUBSCRIBE or IOT_MQTT_UNSUBSCRIBE.
[in]	pSubscriptionList	User-provided array of subscriptions.
[in]	subscriptionCount	Size of `pSubscriptionList`.
[out]	pRemainingLength	Output for calculated "Remaining length" field.
[out]	pPacketSize	Output for calculated total packet size.

Returns: IOT_MQTT_SUCCESS if the packet is within the length allowed by MQTT 3.1.1 spec; IOT_MQTT_BAD_PARAMETER otherwise. If this function returns IOT_MQTT_BAD_PARAMETER, the output parameters should be ignored.

Note: This call is part of serializer API used for implementing light-weight MQTT client.

Example

// Example code below shows how IotMqtt_GetSubscriptionPacketSize() should be used to calculate
// the size of subscribe or unsubscribe request.
IotMqttError_t xResult;
IotMqttSubscription_t xMQTTSubscription[ 1 ];
size_t xRemainingLength = 0;
size_t xPacketSize = 0;
// Initialize Subscribe parameters. Details are out of scope for this example.
// It will involve setting QOS, topic filter  and topic filter length.
 _initializeSubscribe( xMQTTSubscription );
xResult = IotMqtt_GetSubscriptionPacketSize( IOT_MQTT_SUBSCRIBE,
                                             xMQTTSubscription,
                                             sizeof( xMQTTSubscription ) / sizeof( IotMqttSubscription_t ),
                                             &xRemainingLength, &xPacketSize );
IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
// Application should allocate buffer with size == xPacketSize or use static buffer
// with size >= xPacketSize to serialize connect request.

◆ IotMqtt_SerializeSubscribe()

IotMqttError_t IotMqtt_SerializeSubscribe	(	const IotMqttSubscription_t *	pSubscriptionList,
		size_t	subscriptionCount,
		size_t	remainingLength,
		uint16_t *	pPacketIdentifier,
		uint8_t *	pBuffer,
		size_t	bufferSize
	)

Generate a SUBSCRIBE packet from the given parameters.

Parameters

[in]	pSubscriptionList	User-provided array of subscriptions.
[in]	subscriptionCount	Size of `pSubscriptionList`.
[in]	remainingLength	remaining length of the packet to be serialized.
[out]	pPacketIdentifier	The packet identifier generated for this SUBSCRIBE.
[in,out]	pBuffer	User provide buffer where the SUBSCRIBE packet is written.
[in]	bufferSize	Size of the buffer pointed to by pBuffer.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

Note: pBuffer must be allocated by caller.; This call is part of serializer API used for implementing light-weight MQTT client. Example
// Example code below shows how IotMqtt_SerializeSubscribe() should be used to serialize
// MQTT Subscribe packet and send it to MQTT broker.
// Example uses static memory, but dynamically allocated memory can be used as well.
// Get size requirement for the MQTT subscribe packet.
#define mqttexampleSHARED_BUFFER_SIZE 100
static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];
void sendSubscribePacket( int xMQTTSocket )
{
IotMqttSubscription_t xMQTTSubscription[ 1 ];
size_t xRemainingLength = 0;
size_t xPacketSize = 0;
IotMqttError_t xResult;
size_t xSentBytes = 0;
// Initialize Subscribe parameters. Details are out of scope for this example.
// It will involve setting QOS, topic filter and topic filter length.
_initializeSubscribe( xMQTTSubscription );
// Get size requirement for MQTT Subscribe packet.
xResult = IotMqtt_GetSubscriptionPacketSize( IOT_MQTT_SUBSCRIBE,
xMQTTSubscription,
sizeof( xMQTTSubscription ) / sizeof( IotMqttSubscription_t ),
&xRemainingLength, &xPacketSize );
IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
// Make sure the packet size is less than static buffer size.
IotMqtt_Assert( xPacketSize < mqttexampleSHARED_BUFFER_SIZE );
// Serialize subscribe into statically allocated ucSharedBuffer.
xResult = IotMqtt_SerializeSubscribe( xMQTTSubscription,
sizeof( xMQTTSubscription ) / sizeof( IotMqttSubscription_t ),
xRemainingLength,
&usPacketIdentifier,
ucSharedBuffer,
xPacketSize );
IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
// xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.
xSentBytes = send( xMQTTSocket, ( void * ) ucSharedBuffer, xPacketSize, 0 );
IotMqtt_Assert( xSentBytes == xPacketSize );
}

◆ IotMqtt_GetIncomingMQTTPacketTypeAndLength()

IotMqttError_t IotMqtt_GetIncomingMQTTPacketTypeAndLength	(	IotMqttPacketInfo_t *	pIncomingPacket,
		IotMqttGetNextByte_t	getNextByte,
		IotNetworkConnection_t	pNetworkConnection
	)

Extract MQTT packet type and length from incoming packet.

Parameters

[in,out]	pIncomingPacket	Pointer to IotMqttPacketInfo_t structure where type, remaining length and packet identifier are stored.
[in]	getNextByte	Pointer to platform specific function which is used to extract type and length from incoming received stream (see example ).
[in]	pNetworkConnection	Pointer to platform specific network connection which is used by getNextByte to receive network data

Returns: IOT_MQTT_SUCCESS on successful extraction of type and length, IOT_MQTT_BAD_RESPONSE on failure.

Note: This call is part of serializer API used for implementing light-weight MQTT client.

Example

// Example code below shows how to implement getNextByte function with posix sockets.
// Note: IotMqttGetNextByte_t typedef IotMqttError_t (* IotMqttGetNextByte_t)( IotNetworkConnection_t pNetworkContext,
//                                              uint8_t * pNextByte );
// Note: It is assumed that socket is already created and connected,
IotMqttError_t getNextByte( IotNetworkConnection_t pContext,
                          uint8_t * pNextByte )
{
     int socket = ( int ) ( *pvContext );
     int receivedBytes;
     IotMqttError_t result;
     receivedBytes = recv( socket, ( void * ) pNextByte, sizeof( uint8_t ), 0 );
     if( receivedBytes == sizeof( uint8_t ) )
     {
         result = IOT_MQTT_SUCCESS;
     }
     else
     {
         result = IOT_MQTT_TIMEOUT;
     }
      return result;
}
// Example below shows how IotMqtt_GetIncomingMQTTPacketTypeAndLength() is used to extract type
// and length from incoming ping response.
// xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.
void getTypeAndLengthFromIncomingMQTTPingResponse( int xMQTTSocket )
{
   IotMqttPacketInfo_t xIncomingPacket;
   IotMqttError_t xResult = IotMqtt_GetIncomingMQTTPacketTypeAndLength( &xIncomingPacket, getNextByte, ( IotNetworkConnection_t ) xMQTTSocket );
   IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
   IotMqtt_Assert( xIncomingPacket.type == MQTT_PACKET_TYPE_PINGRESP );
}

◆ IotMqtt_GetPublishPacketSize()

IotMqttError_t IotMqtt_GetPublishPacketSize	(	const IotMqttPublishInfo_t *	pPublishInfo,
		size_t *	pRemainingLength,
		size_t *	pPacketSize
	)

Calculate the size and "Remaining length" of a PUBLISH packet generated from the given parameters.

Parameters

[in]	pPublishInfo	User-provided PUBLISH information struct.
[out]	pRemainingLength	Output for calculated "Remaining length" field.
[out]	pPacketSize	Output for calculated total packet size.

Returns: IOT_MQTT_SUCCESS if the packet is within the length allowed by MQTT 3.1.1 spec; IOT_MQTT_BAD_PARAMETER otherwise. If this function returns IOT_MQTT_BAD_PARAMETER, the output parameters should be ignored.

Note: This call is part of serializer API used for implementing light-weight MQTT client.

Example

// Example code below shows how IotMqtt_GetPublishPacketSize() should be used to calculate
// the size of MQTT publish request.
IotMqttError_t xResult;
IotMqttPublishInfo_t xMQTTPublishInfo;
size_t xRemainingLength = 0;
size_t xPacketSize = 0;
// Initialize Publish parameters. Details are out of scope for this example.
// It will involve setting QOS, topic filter, topic filter length, payload
// payload length
 _initializePublish( &xMQTTPublishInfo );
// Find out length of Publish packet size.
xResult = IotMqtt_GetPublishPacketSize( &xMQTTPublishInfo, &xRemainingLength, &xPacketSize );
IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
// Application should allocate buffer with size == xPacketSize or use static buffer
// with size >= xPacketSize to serialize connect request.

◆ IotMqtt_SerializePublish()

IotMqttError_t IotMqtt_SerializePublish	(	const IotMqttPublishInfo_t *	pPublishInfo,
		size_t	remainingLength,
		uint16_t *	pPacketIdentifier,
		uint8_t **	pPacketIdentifierHigh,
		uint8_t *	pBuffer,
		size_t	bufferSize
	)

Generate a PUBLISH packet from the given parameters.

Parameters

[in]	pPublishInfo	User-provided PUBLISH information.
[in]	remainingLength	remaining length of the packet to be serialized.
[out]	pPacketIdentifier	The packet identifier generated for this PUBLISH.
[out]	pPacketIdentifierHigh	Where the high byte of the packet identifier is written.
[in,out]	pBuffer	User provide buffer where the PUBLISH packet is written.
[in]	bufferSize	Size of the buffer pointed to by pBuffer.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_BAD_PARAMETER.

Note: pBuffer must be allocated by caller.; This call is part of serializer API used for implementing light-weight MQTT client.

Example

// Example code below shows how IotMqtt_SerializePublish() should be used to serialize
// MQTT Publish packet and send it to broker.
// Example uses static memory, but dynamically allocated memory can be used as well.
#define mqttexampleSHARED_BUFFER_SIZE 100
static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];
void sendUnsubscribePacket( int xMQTTSocket )
{
   IotMqttError_t xResult;
   IotMqttPublishInfo_t xMQTTPublishInfo;
   size_t xRemainingLength = 0;
   size_t xPacketSize = 0;
   size_t xSentBytes = 0;
   uint16_t usPacketIdentifier;
   uint8_t * pusPacketIdentifierHigh;
   // Initialize Publish parameters. Details are out of scope for this example.
   // It will involve setting QOS, topic filter, topic filter length, payload
   // payload length.
   _initializePublish( &xMQTTPublishInfo );
   // Find out length of Publish packet size.
   xResult = IotMqtt_GetPublishPacketSize( &xMQTTPublishInfo, &xRemainingLength, &xPacketSize );
   IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
   // Make sure the packet size is less than static buffer size
   IotMqtt_Assert( xPacketSize < mqttexampleSHARED_BUFFER_SIZE );
   xResult = IotMqtt_SerializePublish( &xMQTTPublishInfo,
                                    xRemainingLength,
                                    &usPacketIdentifier,
                                    &pusPacketIdentifierHigh,
                                    ucSharedBuffer,
                                    xPacketSize );
   IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
   // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.
   xSentBytes = send( xMQTTSocket, ( void * ) ucSharedBuffer, xPacketSize, 0 );
   IotMqtt_Assert( xSentBytes == xPacketSize );
}

◆ IotMqtt_SerializeUnsubscribe()

IotMqttError_t IotMqtt_SerializeUnsubscribe	(	const IotMqttSubscription_t *	pSubscriptionList,
		size_t	subscriptionCount,
		size_t	remainingLength,
		uint16_t *	pPacketIdentifier,
		uint8_t *	pBuffer,
		size_t	bufferSize
	)

Generate a UNSUBSCRIBE packet from the given parameters.

Parameters

[in]	pSubscriptionList	User-provided array of subscriptions to remove.
[in]	subscriptionCount	Size of `pSubscriptionList`.
[in]	remainingLength	remaining length of the packet to be serialized.
[out]	pPacketIdentifier	The packet identifier generated for this UNSUBSCRIBE.
[in,out]	pBuffer	User provide buffer where the UNSUBSCRIBE packet is written.
[in]	bufferSize	Size of the buffer pointed to by pBuffer.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

Note: pBuffer must be allocated by caller.; This call is part of serializer API used for implementing light-weight MQTT client.

Example

// Example code below shows how IotMqtt_SerializeUnsubscribe() should be used to serialize
// MQTT unsubscribe packet and send it to MQTT broker.
// Example uses static memory, but dynamically allocated memory can be used as well.
// Get size requirement for the Unsubscribe packet.
#define mqttexampleSHARED_BUFFER_SIZE 100
static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];
void sendUnsubscribePacket( int xMQTTSocket )
{
   // Following example shows one topic example.
   IotMqttSubscription_t xMQTTSubscription[ 1 ];
   size_t xRemainingLength = 0;
   size_t xPacketSize = 0;
   IotMqttError_t xResult;
   size_t xSentBytes = 0;
   // Get size requirement for MQTT unsubscribe packet.
   xResult = IotMqtt_GetSubscriptionPacketSize( IOT_MQTT_UNSUBSCRIBE,
                                             xMQTTSubscription,
                                             sizeof( xMQTTSubscription ) / sizeof( IotMqttSubscription_t ),
                                             &xRemainingLength, &xPacketSize );
   IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
   // Make sure the packet size is less than static buffer size.
   IotMqtt_Assert( xPacketSize < mqttexampleSHARED_BUFFER_SIZE );
   // Serialize subscribe into statically allocated ucSharedBuffer.
    xResult = IotMqtt_SerializeUnsubscribe( xMQTTSubscription,
                                      sizeof( xMQTTSubscription ) / sizeof( IotMqttSubscription_t ),
                                      xRemainingLength,
                                      &usPacketIdentifier,
                                      ucSharedBuffer,
                                      xPacketSize );
   IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
   // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.
   xSentBytes = send( xMQTTSocket, ( void * ) ucSharedBuffer, xPacketSize, 0 );
   IotMqtt_Assert( xSentBytes == xPacketSize );
}

◆ IotMqtt_SerializeDisconnect()

IotMqttError_t IotMqtt_SerializeDisconnect	(	uint8_t *	pBuffer,
		size_t	bufferSize
	)

Generate a DISCONNECT packet.

Parameters

[in,out]	pBuffer	User provide buffer where the DISCONNECT packet is written.
[in]	bufferSize	Size of the buffer pointed to by pBuffer.

Returns: returns IOT_MQTT_SUCCESS or IOT_MQTT_BAD_PARAMETER

Note: This call is part of serializer API used for implementing light-weight MQTT client.

Example

// Example below shows how IotMqtt_SerializeDisconnect() should be used.
#define mqttexampleSHARED_BUFFER_SIZE 100
static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];
void sendDisconnectRequest( int xMQTTSocket )
{
    size_t xSentBytes = 0;
   // Disconnect is fixed length packet, therefore there is no need to calculate the size,
   // just makes sure static buffer can accommodate disconnect request.
   IotMqtt_Assert( MQTT_PACKET_DISCONNECT_SIZE <= mqttexampleSHARED_BUFFER_SIZE );
   // Serialize Disconnect packet into static buffer (dynamically allocated buffer can be used as well)
   xResult = IotMqtt_SerializeDisconnect( ucSharedBuffer, MQTT_PACKET_DISCONNECT_SIZE );
   IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
   // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.
   xSentByte = send( xMQTTSocket, ( void * ) ucSharedBuffer, MQTT_PACKET_DISCONNECT_SIZE, 0 );
   IotMqtt_Assert( xSentByte == MQTT_PACKET_DISCONNECT_SIZE );
}

◆ IotMqtt_SerializePingreq()

IotMqttError_t IotMqtt_SerializePingreq	(	uint8_t *	pBuffer,
		size_t	bufferSize
	)

Generate a PINGREQ packet.

Parameters

[in,out]	pBuffer	User provide buffer where the PINGREQ packet is written.
[in]	bufferSize	Size of the buffer pointed to by pBuffer.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_BAD_PARAMETER.

Note: This call is part of serializer API used for implementing light-weight MQTT client.

Example

// Example below shows how IotMqtt_SerializePingReq() should be used.
#define mqttexampleSHARED_BUFFER_SIZE 100
static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];
void sendPingRequest( int xMQTTSocket )
{
   size_t xSentBytes = 0;
   // PingReq is fixed length packet, therefore there is no need to calculate the size,
   // just makes sure static buffer can accommodate Ping request.
   IotMqtt_Assert( MQTT_PACKET_PINGREQ_SIZE <= mqttexampleSHARED_BUFFER_SIZE );
   xResult = IotMqtt_SerializePingreq( ucSharedBuffer, MQTT_PACKET_PINGREQ_SIZE );
   IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
   // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.
   xSentByte = send( xMQTTSocket, ( void * ) ucSharedBuffer, MQTT_PACKET_DISCONNECT_SIZE, 0 );
   IotMqtt_Assert( xSentByte ==  MQTT_PACKET_PINGREQ_SIZE);
}

◆ IotMqtt_DeserializePublish()

IotMqttError_t IotMqtt_DeserializePublish ( IotMqttPacketInfo_t * pMqttPacket )

Deserialize incoming publish packet.

Parameters

[in,out] pMqttPacket The caller of this API sets type, remainingLength and pRemainingData. On success, packetIdentifier and pubInfo will be set by the function.

Returns

One of the following:

Note: This call is part of serializer API used for implementing light-weight MQTT client.

Example

// Example below shows how IotMqtt_DeserializePublish() used to extract contents of incoming
// Publish.  xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.
void processIncomingPublish( int xMQTTSocket )
{
   IotMqttError_t xResult;
   IotMqttPacketInfo_t xIncomingPacket;
   xResult = IotMqtt_GetIncomingMQTTPacketTypeAndLength( &xIncomingPacket, getNextByte, ( void * ) xMQTTSocket );
   IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
   IotMqtt_Assert( ( xIncomingPacket.type & 0xf0 ) == MQTT_PACKET_TYPE_PUBLISH );
   IotMqtt_Assert( xIncomingPacket.remainingLength <= mqttexampleSHARED_BUFFER_SIZE );
   // Receive the remaining bytes.
   if( recv( xMQTTSocket, ( void * ) ucSharedBuffer, xIncomingPacket.remainingLength, 0 ) ==  xIncomingPacket.remainingLength )
   {
    xIncomingPacket.pRemainingData = ucSharedBuffer;
    if( IotMqtt_DeserializePublish( &xIncomingPacket ) != IOT_MQTT_SUCCESS )
    {
        xResult = IOT_MQTT_BAD_RESPONSE;
    }
    else
    {
        // Process incoming Publish.
        IotLogInfo( "Incoming QOS : %d\n", xIncomingPacket.pubInfo.qos );
        IotLogInfo( "Incoming Publish Topic Name: %.*s\n", xIncomingPacket.pubInfo.topicNameLength, xIncomingPacket.pubInfo.pTopicName );
        IotLogInfo( "Incoming Publish Message : %.*s\n", xIncomingPacket.pubInfo.payloadLength, xIncomingPacket.pubInfo.pPayload  );
    }
   }
   else
   {
    xResult = IOT_MQTT_NETWORK_ERROR;
   }
 IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
}

◆ IotMqtt_DeserializeResponse()

IotMqttError_t IotMqtt_DeserializeResponse ( IotMqttPacketInfo_t * pMqttPacket )

Deserialize incoming ack packets.

Parameters

[in,out] pMqttPacket The caller of this API sets type, remainingLength and pRemainingData. On success, packetIdentifier will be set.

Returns

One of the following:

Note: This call is part of serializer API used for implementing light-weight MQTT client.

Example

// Example below shows how  IotMqtt_DeserializeResponse() is used to process unsubscribe ack.
// xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.
void processUnsubscribeAck( int xMQTTSocket )
{
     IotMqttError_t xResult;
     IotMqttPacketInfo_t xIncomingPacket;
     xResult = IotMqtt_GetIncomingMQTTPacketTypeAndLength( &xIncomingPacket, getNextByte, ( void * ) xMQTTSocket );
    IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
    IotMqtt_Assert( xIncomingPacket.type == MQTT_PACKET_TYPE_UNSUBACK );
    IotMqtt_Assert( xIncomingPacket.remainingLength <= sizeof( ucSharedBuffer ) );
    // Receive the remaining bytes.
    if( recv( xMQTTSocket, ( void * ) ucSharedBuffer, xIncomingPacket.remainingLength, 0 ) == xIncomingPacket.remainingLength )
    {
        xIncomingPacket.pRemainingData = ucSharedBuffer;
        if( IotMqtt_DeserializeResponse( &xIncomingPacket ) != IOT_MQTT_SUCCESS )
        {
            xResult = IOT_MQTT_BAD_RESPONSE;
        }
    }
    else
    {
        xResult = IOT_MQTT_NETWORK_ERROR;
    }
     IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );
}

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ IotMqtt_Assert

Function Documentation

◆ _getRemainingLength()

◆ _deserializeConnack()

◆ _deserializeSuback()

◆ _deserializePuback()

◆ _deserializePingresp()

◆ _deserializeUnsuback()

◆ _deserializePublish()

◆ _readSubackStatus()

◆ _checkPublishRemainingLength()

◆ IotMqtt_GetConnectPacketSize()

◆ IotMqtt_SerializeConnect()

◆ IotMqtt_GetSubscriptionPacketSize()

◆ IotMqtt_SerializeSubscribe()

◆ IotMqtt_GetIncomingMQTTPacketTypeAndLength()

◆ IotMqtt_GetPublishPacketSize()

◆ IotMqtt_SerializePublish()

◆ IotMqtt_SerializeUnsubscribe()

◆ IotMqtt_SerializeDisconnect()

◆ IotMqtt_SerializePingreq()

◆ IotMqtt_DeserializePublish()

◆ IotMqtt_DeserializeResponse()