User-facing functions for serializing and deserializing MQTT 3.1.1 packets. This header should be included for building a lighter weight MQTT client than the managed CSDK MQTT library API in core_mqtt.h, by using the serializer and de-serializer functions exposed in this file's API. More...

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include "core_mqtt_config.h"
#include "core_mqtt_config_defaults.h"
#include "transport_interface.h"

Data Structures
struct	MQTTFixedBuffer_t
	Buffer passed to MQTT library. More...

struct	MQTTConnectInfo_t
	MQTT CONNECT packet parameters. More...

struct	MQTTSubscribeInfo_t
	MQTT SUBSCRIBE packet parameters. More...

struct	MQTTPublishInfo_t
	MQTT PUBLISH packet parameters. More...

struct	MQTTPacketInfo_t
	MQTT incoming packet parameters. More...

Macros
#define	MQTT_PACKET_TYPE_CONNECT ( ( uint8_t ) 0x10U )
	CONNECT (client-to-server).

#define	MQTT_PACKET_TYPE_CONNACK ( ( uint8_t ) 0x20U )
	CONNACK (server-to-client).

#define	MQTT_PACKET_TYPE_PUBLISH ( ( uint8_t ) 0x30U )
	PUBLISH (bidirectional).

#define	MQTT_PACKET_TYPE_PUBACK ( ( uint8_t ) 0x40U )
	PUBACK (bidirectional).

#define	MQTT_PACKET_TYPE_PUBREC ( ( uint8_t ) 0x50U )
	PUBREC (bidirectional).

#define	MQTT_PACKET_TYPE_PUBREL ( ( uint8_t ) 0x62U )
	PUBREL (bidirectional).

#define	MQTT_PACKET_TYPE_PUBCOMP ( ( uint8_t ) 0x70U )
	PUBCOMP (bidirectional).

#define	MQTT_PACKET_TYPE_SUBSCRIBE ( ( uint8_t ) 0x82U )
	SUBSCRIBE (client-to-server).

#define	MQTT_PACKET_TYPE_SUBACK ( ( uint8_t ) 0x90U )
	SUBACK (server-to-client).

#define	MQTT_PACKET_TYPE_UNSUBSCRIBE ( ( uint8_t ) 0xA2U )
	UNSUBSCRIBE (client-to-server).

#define	MQTT_PACKET_TYPE_UNSUBACK ( ( uint8_t ) 0xB0U )
	UNSUBACK (server-to-client).

#define	MQTT_PACKET_TYPE_PINGREQ ( ( uint8_t ) 0xC0U )
	PINGREQ (client-to-server).

#define	MQTT_PACKET_TYPE_PINGRESP ( ( uint8_t ) 0xD0U )
	PINGRESP (server-to-client).

#define	MQTT_PACKET_TYPE_DISCONNECT ( ( uint8_t ) 0xE0U )
	DISCONNECT (client-to-server).

#define	MQTT_PUBLISH_ACK_PACKET_SIZE ( 4UL )
	The size of MQTT PUBACK, PUBREC, PUBREL, and PUBCOMP packets, per MQTT spec.

Enumerations
enum	MQTTStatus_t { MQTTSuccess = 0 , MQTTBadParameter , MQTTNoMemory , MQTTSendFailed , MQTTRecvFailed , MQTTBadResponse , MQTTServerRefused , MQTTNoDataAvailable , MQTTIllegalState , MQTTStateCollision , MQTTKeepAliveTimeout , MQTTNeedMoreBytes }
	Return codes from MQTT functions. More...

enum	MQTTQoS_t { MQTTQoS0 = 0 , MQTTQoS1 = 1 , MQTTQoS2 = 2 }
	MQTT Quality of Service values. More...

Functions
MQTTStatus_t	MQTT_GetConnectPacketSize (const MQTTConnectInfo_t pConnectInfo, const MQTTPublishInfo_t pWillInfo, size_t pRemainingLength, size_t pPacketSize)
	Get the size and Remaining Length of an MQTT CONNECT packet. More...

MQTTStatus_t	MQTT_SerializeConnect (const MQTTConnectInfo_t pConnectInfo, const MQTTPublishInfo_t pWillInfo, size_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
	Serialize an MQTT CONNECT packet in the given fixed buffer `pFixedBuffer`. More...

MQTTStatus_t	MQTT_GetSubscribePacketSize (const MQTTSubscribeInfo_t pSubscriptionList, size_t subscriptionCount, size_t pRemainingLength, size_t *pPacketSize)
	Get packet size and Remaining Length of an MQTT SUBSCRIBE packet. More...

MQTTStatus_t	MQTT_SerializeSubscribe (const MQTTSubscribeInfo_t pSubscriptionList, size_t subscriptionCount, uint16_t packetId, size_t remainingLength, const MQTTFixedBuffer_t pFixedBuffer)
	Serialize an MQTT SUBSCRIBE packet in the given buffer. More...

MQTTStatus_t	MQTT_GetUnsubscribePacketSize (const MQTTSubscribeInfo_t pSubscriptionList, size_t subscriptionCount, size_t pRemainingLength, size_t *pPacketSize)
	Get packet size and Remaining Length of an MQTT UNSUBSCRIBE packet. More...

MQTTStatus_t	MQTT_SerializeUnsubscribe (const MQTTSubscribeInfo_t pSubscriptionList, size_t subscriptionCount, uint16_t packetId, size_t remainingLength, const MQTTFixedBuffer_t pFixedBuffer)
	Serialize an MQTT UNSUBSCRIBE packet in the given buffer. More...

MQTTStatus_t	MQTT_GetPublishPacketSize (const MQTTPublishInfo_t pPublishInfo, size_t pRemainingLength, size_t *pPacketSize)
	Get the packet size and remaining length of an MQTT PUBLISH packet. More...

MQTTStatus_t	MQTT_SerializePublish (const MQTTPublishInfo_t pPublishInfo, uint16_t packetId, size_t remainingLength, const MQTTFixedBuffer_t pFixedBuffer)
	Serialize an MQTT PUBLISH packet in the given buffer. More...

MQTTStatus_t	MQTT_SerializePublishHeaderWithoutTopic (const MQTTPublishInfo_t pPublishInfo, size_t remainingLength, uint8_t pBuffer, size_t *headerSize)
	Serialize an MQTT PUBLISH packet header without the topic string in the given buffer. This function will add the topic string length to the provided buffer. This helps reduce an unnecessary copy of the topic string into the buffer. More...

MQTTStatus_t	MQTT_SerializePublishHeader (const MQTTPublishInfo_t pPublishInfo, uint16_t packetId, size_t remainingLength, const MQTTFixedBuffer_t pFixedBuffer, size_t *pHeaderSize)
	Serialize an MQTT PUBLISH packet header in the given buffer. More...

MQTTStatus_t	MQTT_SerializeAck (const MQTTFixedBuffer_t *pFixedBuffer, uint8_t packetType, uint16_t packetId)
	Serialize an MQTT PUBACK, PUBREC, PUBREL, or PUBCOMP into the given buffer. More...

MQTTStatus_t	MQTT_GetDisconnectPacketSize (size_t *pPacketSize)
	Get the size of an MQTT DISCONNECT packet. More...

MQTTStatus_t	MQTT_SerializeDisconnect (const MQTTFixedBuffer_t *pFixedBuffer)
	Serialize an MQTT DISCONNECT packet into the given buffer. More...

MQTTStatus_t	MQTT_GetPingreqPacketSize (size_t *pPacketSize)
	Get the size of an MQTT PINGREQ packet. More...

MQTTStatus_t	MQTT_SerializePingreq (const MQTTFixedBuffer_t *pFixedBuffer)
	Serialize an MQTT PINGREQ packet into the given buffer. More...

MQTTStatus_t	MQTT_DeserializePublish (const MQTTPacketInfo_t pIncomingPacket, uint16_t pPacketId, MQTTPublishInfo_t *pPublishInfo)
	Deserialize an MQTT PUBLISH packet. More...

MQTTStatus_t	MQTT_DeserializeAck (const MQTTPacketInfo_t pIncomingPacket, uint16_t pPacketId, bool *pSessionPresent)
	Deserialize an MQTT CONNACK, SUBACK, UNSUBACK, PUBACK, PUBREC, PUBREL, PUBCOMP, or PINGRESP. More...

MQTTStatus_t	MQTT_GetIncomingPacketTypeAndLength (TransportRecv_t readFunc, NetworkContext_t pNetworkContext, MQTTPacketInfo_t pIncomingPacket)
	Extract the MQTT packet type and length from incoming packet. More...

MQTTStatus_t	MQTT_ProcessIncomingPacketTypeAndLength (const uint8_t pBuffer, const size_t pIndex, MQTTPacketInfo_t *pIncomingPacket)
	Extract the MQTT packet type and length from incoming packet. More...

Detailed Description

User-facing functions for serializing and deserializing MQTT 3.1.1 packets. This header should be included for building a lighter weight MQTT client than the managed CSDK MQTT library API in core_mqtt.h, by using the serializer and de-serializer functions exposed in this file's API.

Function Documentation

◆ MQTT_GetConnectPacketSize()

MQTTStatus_t MQTT_GetConnectPacketSize	(	const MQTTConnectInfo_t *	pConnectInfo,
		const MQTTPublishInfo_t *	pWillInfo,
		size_t *	pRemainingLength,
		size_t *	pPacketSize
	)

Get the size and Remaining Length of an MQTT CONNECT packet.

This function must be called before MQTT_SerializeConnect in order to get the size of the MQTT CONNECT packet that is generated from MQTTConnectInfo_t and optional MQTTPublishInfo_t. The size of the MQTTFixedBuffer_t supplied to MQTT_SerializeConnect must be at least pPacketSize. The provided pConnectInfo and pWillInfo are valid for serialization with MQTT_SerializeConnect only if this function returns MQTTSuccess. The remaining length returned in pRemainingLength and the packet size returned in pPacketSize are valid only if this function returns MQTTSuccess.

Parameters

[in]	pConnectInfo	MQTT CONNECT packet parameters.
[in]	pWillInfo	Last Will and Testament. Pass NULL if not used.
[out]	pRemainingLength	The Remaining Length of the MQTT CONNECT packet.
[out]	pPacketSize	The total size of the MQTT CONNECT packet.

Returns: MQTTBadParameter if the packet would exceed the size allowed by the MQTT spec; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTConnectInfo_t connectInfo = { 0 };
MQTTPublishInfo_t willInfo = { 0 };
size_t remainingLength = 0, packetSize = 0;
 
// Initialize the connection info, the details are out of scope for this example.
initializeConnectInfo( &connectInfo );
 
// Initialize the optional will info, the details are out of scope for this example.
initializeWillInfo( &willInfo );
 
// Get the size requirement for the connect packet.
status = MQTT_GetConnectPacketSize(
     &connectInfo, &willInfo, &remainingLength, &packetSize
);
 
if( status == MQTTSuccess )
{
     // The application should allocate or use a static #MQTTFixedBuffer_t
     // of size >= packetSize to serialize the connect request.
}

◆ MQTT_SerializeConnect()

MQTTStatus_t MQTT_SerializeConnect	(	const MQTTConnectInfo_t *	pConnectInfo,
		const MQTTPublishInfo_t *	pWillInfo,
		size_t	remainingLength,
		const MQTTFixedBuffer_t *	pFixedBuffer
	)

Serialize an MQTT CONNECT packet in the given fixed buffer pFixedBuffer.

MQTT_GetConnectPacketSize should be called with pConnectInfo and pWillInfo before invoking this function to get the size of the required MQTTFixedBuffer_t and remainingLength. The remainingLength must be the same as returned by MQTT_GetConnectPacketSize. The MQTTFixedBuffer_t must be at least as large as the size returned by MQTT_GetConnectPacketSize.

Parameters

[in]	pConnectInfo	MQTT CONNECT packet parameters.
[in]	pWillInfo	Last Will and Testament. Pass NULL if not used.
[in]	remainingLength	Remaining Length provided by MQTT_GetConnectPacketSize.
[out]	pFixedBuffer	Buffer for packet serialization.

Returns: MQTTNoMemory if pFixedBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTConnectInfo_t connectInfo = { 0 };
MQTTPublishInfo_t willInfo = { 0 };
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ BUFFER_SIZE ];
size_t remainingLength = 0, packetSize = 0;
 
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = BUFFER_SIZE;
 
// Assume connectInfo and willInfo are initialized. Get the size requirement for
// the connect packet.
status = MQTT_GetConnectPacketSize(
     &connectInfo, &willInfo, &remainingLength, &packetSize
);
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
 
// Serialize the connect packet into the fixed buffer.
status = MQTT_SerializeConnect( &connectInfo, &willInfo, remainingLength, &fixedBuffer );
 
if( status == MQTTSuccess )
{
     // The connect packet can now be sent to the broker.
}

◆ MQTT_GetSubscribePacketSize()

MQTTStatus_t MQTT_GetSubscribePacketSize	(	const MQTTSubscribeInfo_t *	pSubscriptionList,
		size_t	subscriptionCount,
		size_t *	pRemainingLength,
		size_t *	pPacketSize
	)

Get packet size and Remaining Length of an MQTT SUBSCRIBE packet.

This function must be called before MQTT_SerializeSubscribe in order to get the size of the MQTT SUBSCRIBE packet that is generated from the list of MQTTSubscribeInfo_t. The size of the MQTTFixedBuffer_t supplied to MQTT_SerializeSubscribe must be at least pPacketSize. The provided pSubscriptionList is valid for serialization with MQTT_SerializeSubscribe only if this function returns MQTTSuccess. The remaining length returned in pRemainingLength and the packet size returned in pPacketSize are valid only if this function returns MQTTSuccess.

Parameters

[in]	pSubscriptionList	List of MQTT subscription info.
[in]	subscriptionCount	The number of elements in pSubscriptionList.
[out]	pRemainingLength	The Remaining Length of the MQTT SUBSCRIBE packet.
[out]	pPacketSize	The total size of the MQTT SUBSCRIBE packet.

Returns: MQTTBadParameter if the packet would exceed the size allowed by the MQTT spec; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTSubscribeInfo_t subscriptionList[ NUMBER_OF_SUBSCRIPTIONS ] = { 0 };
size_t remainingLength = 0, packetSize = 0;
// This is assumed to be a list of filters we want to subscribe to.
const char * filters[ NUMBER_OF_SUBSCRIPTIONS ];
 
// Set each subscription.
for( int i = 0; i < NUMBER_OF_SUBSCRIPTIONS; i++ )
{
     subscriptionList[ i ].qos = MQTTQoS0;
     // Each subscription needs a topic filter.
     subscriptionList[ i ].pTopicFilter = filters[ i ];
     subscriptionList[ i ].topicFilterLength = strlen( filters[ i ] );
}
 
// Get the size requirement for the subscribe packet.
status = MQTT_GetSubscribePacketSize(
     &subscriptionList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, &remainingLength, &packetSize
);
 
if( status == MQTTSuccess )
{
     // The application should allocate or use a static #MQTTFixedBuffer_t
     // of size >= packetSize to serialize the subscribe request.
}

◆ MQTT_SerializeSubscribe()

MQTTStatus_t MQTT_SerializeSubscribe	(	const MQTTSubscribeInfo_t *	pSubscriptionList,
		size_t	subscriptionCount,
		uint16_t	packetId,
		size_t	remainingLength,
		const MQTTFixedBuffer_t *	pFixedBuffer
	)

Serialize an MQTT SUBSCRIBE packet in the given buffer.

MQTT_GetSubscribePacketSize should be called with pSubscriptionList before invoking this function to get the size of the required MQTTFixedBuffer_t and remainingLength. The remainingLength must be the same as returned by MQTT_GetSubscribePacketSize. The MQTTFixedBuffer_t must be at least as large as the size returned by MQTT_GetSubscribePacketSize.

Parameters

[in]	pSubscriptionList	List of MQTT subscription info.
[in]	subscriptionCount	The number of elements in pSubscriptionList.
[in]	packetId	packet ID generated by MQTT_GetPacketId.
[in]	remainingLength	Remaining Length provided by MQTT_GetSubscribePacketSize.
[out]	pFixedBuffer	Buffer for packet serialization.

Returns: MQTTNoMemory if pFixedBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTSubscribeInfo_t subscriptionList[ NUMBER_OF_SUBSCRIPTIONS ] = { 0 };
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ BUFFER_SIZE ];
size_t remainingLength = 0, packetSize = 0;
uint16_t packetId;
 
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = BUFFER_SIZE;
 
// Function to return a valid, unused packet identifier. The details are out of
// scope for this example.
packetId = getNewPacketId();
 
// Assume subscriptionList has been initialized. Get the subscribe packet size.
status = MQTT_GetSubscribePacketSize(
     &subscriptionList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, &remainingLength, &packetSize
);
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
 
// Serialize the subscribe packet into the fixed buffer.
status = MQTT_SerializeSubscribe(
     &subscriptionList[ 0 ],
     NUMBER_OF_SUBSCRIPTIONS,
     packetId,
     remainingLength,
     &fixedBuffer
);
 
if( status == MQTTSuccess )
{
     // The subscribe packet can now be sent to the broker.
}

◆ MQTT_GetUnsubscribePacketSize()

MQTTStatus_t MQTT_GetUnsubscribePacketSize	(	const MQTTSubscribeInfo_t *	pSubscriptionList,
		size_t	subscriptionCount,
		size_t *	pRemainingLength,
		size_t *	pPacketSize
	)

Get packet size and Remaining Length of an MQTT UNSUBSCRIBE packet.

This function must be called before MQTT_SerializeUnsubscribe in order to get the size of the MQTT UNSUBSCRIBE packet that is generated from the list of MQTTSubscribeInfo_t. The size of the MQTTFixedBuffer_t supplied to MQTT_SerializeUnsubscribe must be at least pPacketSize. The provided pSubscriptionList is valid for serialization with MQTT_SerializeUnsubscribe only if this function returns MQTTSuccess. The remaining length returned in pRemainingLength and the packet size returned in pPacketSize are valid only if this function returns MQTTSuccess.

Parameters

[in]	pSubscriptionList	List of MQTT subscription info.
[in]	subscriptionCount	The number of elements in pSubscriptionList.
[out]	pRemainingLength	The Remaining Length of the MQTT UNSUBSCRIBE packet.
[out]	pPacketSize	The total size of the MQTT UNSUBSCRIBE packet.

Returns: MQTTBadParameter if the packet would exceed the size allowed by the MQTT spec; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTSubscribeInfo_t subscriptionList[ NUMBER_OF_SUBSCRIPTIONS ] = { 0 };
size_t remainingLength = 0, packetSize = 0;
 
// Initialize the subscribe info. The details are out of scope for this example.
initializeSubscribeInfo( &subscriptionList[ 0 ] );
 
// Get the size requirement for the unsubscribe packet.
status = MQTT_GetUnsubscribePacketSize(
     &subscriptionList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, &remainingLength, &packetSize
);
 
if( status == MQTTSuccess )
{
     // The application should allocate or use a static #MQTTFixedBuffer_t
     // of size >= packetSize to serialize the unsubscribe request.
}

◆ MQTT_SerializeUnsubscribe()

MQTTStatus_t MQTT_SerializeUnsubscribe	(	const MQTTSubscribeInfo_t *	pSubscriptionList,
		size_t	subscriptionCount,
		uint16_t	packetId,
		size_t	remainingLength,
		const MQTTFixedBuffer_t *	pFixedBuffer
	)

Serialize an MQTT UNSUBSCRIBE packet in the given buffer.

MQTT_GetUnsubscribePacketSize should be called with pSubscriptionList before invoking this function to get the size of the required MQTTFixedBuffer_t and remainingLength. The remainingLength must be the same as returned by MQTT_GetUnsubscribePacketSize. The MQTTFixedBuffer_t must be at least as large as the size returned by MQTT_GetUnsubscribePacketSize.

Parameters

[in]	pSubscriptionList	List of MQTT subscription info.
[in]	subscriptionCount	The number of elements in pSubscriptionList.
[in]	packetId	packet ID generated by MQTT_GetPacketId.
[in]	remainingLength	Remaining Length provided by MQTT_GetUnsubscribePacketSize.
[out]	pFixedBuffer	Buffer for packet serialization.

Returns: MQTTNoMemory if pFixedBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTSubscribeInfo_t subscriptionList[ NUMBER_OF_SUBSCRIPTIONS ] = { 0 };
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ BUFFER_SIZE ];
size_t remainingLength = 0, packetSize = 0;
uint16_t packetId;
 
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = BUFFER_SIZE;
 
// Function to return a valid, unused packet identifier. The details are out of
// scope for this example.
packetId = getNewPacketId();
 
// Assume subscriptionList has been initialized. Get the unsubscribe packet size.
status = MQTT_GetUnsubscribePacketSize(
     &subscriptionList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, &remainingLength, &packetSize
);
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
 
// Serialize the unsubscribe packet into the fixed buffer.
status = MQTT_SerializeUnsubscribe(
     &subscriptionList[ 0 ],
     NUMBER_OF_SUBSCRIPTIONS,
     packetId,
     remainingLength,
     &fixedBuffer
);
 
if( status == MQTTSuccess )
{
     // The unsubscribe packet can now be sent to the broker.
}

◆ MQTT_GetPublishPacketSize()

MQTTStatus_t MQTT_GetPublishPacketSize	(	const MQTTPublishInfo_t *	pPublishInfo,
		size_t *	pRemainingLength,
		size_t *	pPacketSize
	)

Get the packet size and remaining length of an MQTT PUBLISH packet.

This function must be called before MQTT_SerializePublish in order to get the size of the MQTT PUBLISH packet that is generated from MQTTPublishInfo_t. The size of the MQTTFixedBuffer_t supplied to MQTT_SerializePublish must be at least pPacketSize. The provided pPublishInfo is valid for serialization with MQTT_SerializePublish only if this function returns MQTTSuccess. The remaining length returned in pRemainingLength and the packet size returned in pPacketSize are valid only if this function returns MQTTSuccess.

Parameters

[in]	pPublishInfo	MQTT PUBLISH packet parameters.
[out]	pRemainingLength	The Remaining Length of the MQTT PUBLISH packet.
[out]	pPacketSize	The total size of the MQTT PUBLISH packet.

Returns: MQTTBadParameter if the packet would exceed the size allowed by the MQTT spec or if invalid parameters are passed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPublishInfo_t publishInfo = { 0 };
size_t remainingLength = 0, packetSize = 0;
 
// Initialize the publish info.
publishInfo.qos = MQTTQoS0;
publishInfo.pTopicName = "/some/topic/name";
publishInfo.topicNameLength = strlen( publishInfo.pTopicName );
publishInfo.pPayload = "Hello World!";
publishInfo.payloadLength = strlen( "Hello World!" );
 
// Get the size requirement for the publish packet.
status = MQTT_GetPublishPacketSize(
     &publishInfo, &remainingLength, &packetSize
);
 
if( status == MQTTSuccess )
{
     // The application should allocate or use a static #MQTTFixedBuffer_t
     // of size >= packetSize to serialize the publish.
}

◆ MQTT_SerializePublish()

MQTTStatus_t MQTT_SerializePublish	(	const MQTTPublishInfo_t *	pPublishInfo,
		uint16_t	packetId,
		size_t	remainingLength,
		const MQTTFixedBuffer_t *	pFixedBuffer
	)

Serialize an MQTT PUBLISH packet in the given buffer.

This function will serialize complete MQTT PUBLISH packet into the given buffer. If the PUBLISH payload can be sent separately, consider using MQTT_SerializePublishHeader, which will serialize only the PUBLISH header into the buffer.

MQTT_GetPublishPacketSize should be called with pPublishInfo before invoking this function to get the size of the required MQTTFixedBuffer_t and remainingLength. The remainingLength must be the same as returned by MQTT_GetPublishPacketSize. The MQTTFixedBuffer_t must be at least as large as the size returned by MQTT_GetPublishPacketSize.

Parameters

[in]	pPublishInfo	MQTT PUBLISH packet parameters.
[in]	packetId	packet ID generated by MQTT_GetPacketId.
[in]	remainingLength	Remaining Length provided by MQTT_GetPublishPacketSize.
[out]	pFixedBuffer	Buffer for packet serialization.

Returns: MQTTNoMemory if pFixedBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPublishInfo_t publishInfo = { 0 };
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ BUFFER_SIZE ];
size_t remainingLength = 0, packetSize = 0;
uint16_t packetId;
 
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = BUFFER_SIZE;
 
// A packet identifier is unused for QoS 0 publishes. Otherwise, a valid, unused packet
// identifier must be used.
packetId = 0;
 
// Assume publishInfo has been initialized. Get publish packet size.
status = MQTT_GetPublishPacketSize(
     &publishInfo, &remainingLength, &packetSize
);
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
 
// Serialize the publish packet into the fixed buffer.
status = MQTT_SerializePublish(
     &publishInfo,
     packetId,
     remainingLength,
     &fixedBuffer
);
 
if( status == MQTTSuccess )
{
     // The publish packet can now be sent to the broker.
}

◆ MQTT_SerializePublishHeaderWithoutTopic()

MQTTStatus_t MQTT_SerializePublishHeaderWithoutTopic	(	const MQTTPublishInfo_t *	pPublishInfo,
		size_t	remainingLength,
		uint8_t *	pBuffer,
		size_t *	headerSize
	)

Serialize an MQTT PUBLISH packet header without the topic string in the given buffer. This function will add the topic string length to the provided buffer. This helps reduce an unnecessary copy of the topic string into the buffer.

Parameters

[in]	pPublishInfo	MQTT PUBLISH packet parameters.
[in]	remainingLength	Remaining Length provided by MQTT_GetPublishPacketSize.
[out]	pBuffer	Buffer for packet serialization.
[out]	headerSize	Size of the serialized MQTT PUBLISH header.

Returns: MQTTSuccess if the serialization is successful. Otherwise, MQTTBadParameter.

◆ MQTT_SerializePublishHeader()

MQTTStatus_t MQTT_SerializePublishHeader	(	const MQTTPublishInfo_t *	pPublishInfo,
		uint16_t	packetId,
		size_t	remainingLength,
		const MQTTFixedBuffer_t *	pFixedBuffer,
		size_t *	pHeaderSize
	)

Serialize an MQTT PUBLISH packet header in the given buffer.

This function serializes PUBLISH header in to the given buffer. The payload for PUBLISH will not be copied over to the buffer. This will help reduce the memory needed for the buffer and avoid an unwanted copy operation of the PUBLISH payload into the buffer. If the payload also would need to be part of the serialized buffer, consider using MQTT_SerializePublish.

MQTT_GetPublishPacketSize should be called with pPublishInfo before invoking this function to get the size of the required MQTTFixedBuffer_t and remainingLength. The remainingLength must be the same as returned by MQTT_GetPublishPacketSize. The MQTTFixedBuffer_t must be at least as large as the size returned by MQTT_GetPublishPacketSize.

Parameters

[in]	pPublishInfo	MQTT PUBLISH packet parameters.
[in]	packetId	packet ID generated by MQTT_GetPacketId.
[in]	remainingLength	Remaining Length provided by MQTT_GetPublishPacketSize.
[out]	pFixedBuffer	Buffer for packet serialization.
[out]	pHeaderSize	Size of the serialized MQTT PUBLISH header.

Returns: MQTTNoMemory if pFixedBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPublishInfo_t publishInfo = { 0 };
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ BUFFER_SIZE ];
size_t remainingLength = 0, packetSize = 0, headerSize = 0;
uint16_t packetId;
int32_t bytesSent;
 
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = BUFFER_SIZE;
 
// A packet identifier is unused for QoS 0 publishes. Otherwise, a valid, unused packet
// identifier must be used.
packetId = 0;
 
// Assume publishInfo has been initialized. Get the publish packet size.
status = MQTT_GetPublishPacketSize(
     &publishInfo, &remainingLength, &packetSize
);
assert( status == MQTTSuccess );
// The payload will not be serialized, so the the fixed buffer does not need to hold it.
assert( ( packetSize - publishInfo.payloadLength ) <= BUFFER_SIZE );
 
// Serialize the publish packet header into the fixed buffer.
status = MQTT_SerializePublishHeader(
     &publishInfo,
     packetId,
     remainingLength,
     &fixedBuffer,
     &headerSize
);
 
if( status == MQTTSuccess )
{
     // The publish header and payload can now be sent to the broker.
     // mqttSocket here is a socket descriptor created and connected to the MQTT
     // broker outside of this function.
     bytesSent = send( mqttSocket, ( void * ) fixedBuffer.pBuffer, headerSize, 0 );
     assert( bytesSent == headerSize );
     bytesSent = send( mqttSocket, publishInfo.pPayload, publishInfo.payloadLength, 0 );
     assert( bytesSent == publishInfo.payloadLength );
}

◆ MQTT_SerializeAck()

MQTTStatus_t MQTT_SerializeAck	(	const MQTTFixedBuffer_t *	pFixedBuffer,
		uint8_t	packetType,
		uint16_t	packetId
	)

Serialize an MQTT PUBACK, PUBREC, PUBREL, or PUBCOMP into the given buffer.

Parameters

[out]	pFixedBuffer	Buffer for packet serialization.
[in]	packetType	Byte of the corresponding packet fixed header per the MQTT spec.
[in]	packetId	Packet ID of the publish.

Returns: MQTTBadParameter, MQTTNoMemory, or MQTTSuccess.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ BUFFER_SIZE ];
uint16_t packetId;
uint8_t packetType;
 
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = BUFFER_SIZE;
// The fixed buffer must be large enough to hold 4 bytes.
assert( BUFFER_SIZE >= MQTT_PUBLISH_ACK_PACKET_SIZE );
 
// The packet ID must be the same as the original publish packet.
packetId = publishPacketId;
 
// The byte representing a packet of type ACK. This function accepts PUBACK, PUBREC, PUBREL, or PUBCOMP.
packetType = MQTT_PACKET_TYPE_PUBACK;
 
// Serialize the publish acknowledgment into the fixed buffer.
status = MQTT_SerializeAck( &fixedBuffer, packetType, packetId );
 
if( status == MQTTSuccess )
{
     // The publish acknowledgment can now be sent to the broker.
}

◆ MQTT_GetDisconnectPacketSize()

MQTTStatus_t MQTT_GetDisconnectPacketSize ( size_t * pPacketSize )

Get the size of an MQTT DISCONNECT packet.

Parameters

[out] pPacketSize The size of the MQTT DISCONNECT packet.

Returns: MQTTSuccess, or MQTTBadParameter if pPacketSize is NULL.

Example

// Variables used in this example.
MQTTStatus_t status;
size_t packetSize = 0;
 
// Get the size requirement for the disconnect packet.
status = MQTT_GetDisconnectPacketSize( &packetSize );
assert( status == MQTTSuccess );
assert( packetSize == 2 );
 
// The application should allocate or use a static #MQTTFixedBuffer_t of
// size >= 2 to serialize the disconnect packet.

◆ MQTT_SerializeDisconnect()

MQTTStatus_t MQTT_SerializeDisconnect ( const MQTTFixedBuffer_t * pFixedBuffer )

Serialize an MQTT DISCONNECT packet into the given buffer.

The input MQTTFixedBuffer_t.size must be at least as large as the size returned by MQTT_GetDisconnectPacketSize.

Parameters

[out] pFixedBuffer Buffer for packet serialization.

Returns: MQTTNoMemory if pFixedBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ BUFFER_SIZE ];
 
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = BUFFER_SIZE;
 
// Get the disconnect packet size.
status = MQTT_GetDisconnectPacketSize( &packetSize );
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
 
// Serialize the disconnect into the fixed buffer.
status = MQTT_SerializeDisconnect( &fixedBuffer );
 
if( status == MQTTSuccess )
{
     // The disconnect packet can now be sent to the broker.
}

◆ MQTT_GetPingreqPacketSize()

MQTTStatus_t MQTT_GetPingreqPacketSize ( size_t * pPacketSize )

Get the size of an MQTT PINGREQ packet.

Parameters

[out] pPacketSize The size of the MQTT PINGREQ packet.

Returns: MQTTSuccess or MQTTBadParameter if pPacketSize is NULL.

Example

// Variables used in this example.
MQTTStatus_t status;
size_t packetSize = 0;
 
// Get the size requirement for the ping request packet.
status = MQTT_GetPingreqPacketSize( &packetSize );
assert( status == MQTTSuccess );
assert( packetSize == 2 );
 
// The application should allocate or use a static #MQTTFixedBuffer_t of
// size >= 2 to serialize the ping request.

◆ MQTT_SerializePingreq()

MQTTStatus_t MQTT_SerializePingreq ( const MQTTFixedBuffer_t * pFixedBuffer )

Serialize an MQTT PINGREQ packet into the given buffer.

The input MQTTFixedBuffer_t.size must be at least as large as the size returned by MQTT_GetPingreqPacketSize.

Parameters

[out] pFixedBuffer Buffer for packet serialization.

Returns: MQTTNoMemory if pFixedBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ BUFFER_SIZE ];
 
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = BUFFER_SIZE;
 
// Get the ping request packet size.
status = MQTT_GetPingreqPacketSize( &packetSize );
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
 
// Serialize the ping request into the fixed buffer.
status = MQTT_SerializePingreq( &fixedBuffer );
 
if( status == MQTTSuccess )
{
     // The ping request can now be sent to the broker.
}

◆ MQTT_DeserializePublish()

MQTTStatus_t MQTT_DeserializePublish	(	const MQTTPacketInfo_t *	pIncomingPacket,
		uint16_t *	pPacketId,
		MQTTPublishInfo_t *	pPublishInfo
	)

Deserialize an MQTT PUBLISH packet.

Parameters

[in]	pIncomingPacket	MQTTPacketInfo_t containing the buffer.
[out]	pPacketId	The packet ID obtained from the buffer.
[out]	pPublishInfo	Struct containing information about the publish.

Returns: MQTTBadParameter, MQTTBadResponse, or MQTTSuccess.

Example

// TransportRecv_t function for reading from the network.
int32_t socket_recv(
     NetworkContext_t * pNetworkContext,
     void * pBuffer,
     size_t bytesToRecv
);
// Some context to be used with the above transport receive function.
NetworkContext_t networkContext;
 
// Other variables used in this example.
MQTTStatus_t status;
MQTTPacketInfo_t incomingPacket;
MQTTPublishInfo_t publishInfo = { 0 };
uint16_t packetId;
 
int32_t bytesRecvd;
// A buffer to hold remaining data of the incoming packet.
uint8_t buffer[ BUFFER_SIZE ];
 
// Populate all fields of the incoming packet.
status = MQTT_GetIncomingPacketTypeAndLength(
     socket_recv,
     &networkContext,
     &incomingPacket
);
assert( status == MQTTSuccess );
assert( incomingPacket.remainingLength <= BUFFER_SIZE );
bytesRecvd = socket_recv(
     &networkContext,
     ( void * ) buffer,
     incomingPacket.remainingLength
);
incomingPacket.pRemainingData = buffer;
 
// Deserialize the publish information if the incoming packet is a publish.
if( ( incomingPacket.type & 0xF0 ) == MQTT_PACKET_TYPE_PUBLISH )
{
     status = MQTT_DeserializePublish( &incomingPacket, &packetId, &publishInfo );
     if( status == MQTTSuccess )
     {
         // The deserialized publish information can now be used from `publishInfo`.
     }
}

◆ MQTT_DeserializeAck()

MQTTStatus_t MQTT_DeserializeAck	(	const MQTTPacketInfo_t *	pIncomingPacket,
		uint16_t *	pPacketId,
		bool *	pSessionPresent
	)

Deserialize an MQTT CONNACK, SUBACK, UNSUBACK, PUBACK, PUBREC, PUBREL, PUBCOMP, or PINGRESP.

Parameters

[in]	pIncomingPacket	MQTTPacketInfo_t containing the buffer.
[out]	pPacketId	The packet ID of obtained from the buffer. Not used in CONNACK or PINGRESP.
[out]	pSessionPresent	Boolean flag from a CONNACK indicating present session.

Returns: MQTTBadParameter, MQTTBadResponse, MQTTServerRefused, or MQTTSuccess.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPacketInfo_t incomingPacket;
// Used for SUBACK, UNSUBACK, PUBACK, PUBREC, PUBREL, and PUBCOMP.
uint16_t packetId;
// Used for CONNACK.
bool sessionPresent;
 
// Receive an incoming packet and populate all fields. The details are out of scope
// for this example.
receiveIncomingPacket( &incomingPacket );
 
// Deserialize ack information if the incoming packet is not a publish.
if( ( incomingPacket.type & 0xF0 ) != MQTT_PACKET_TYPE_PUBLISH )
{
     status = MQTT_DeserializeAck( &incomingPacket, &packetId, &sessionPresent );
     if( status == MQTTSuccess )
     {
         // The packet ID or session present flag information is available. For
         // ping response packets, the only information is the status code.
     }
}

◆ MQTT_GetIncomingPacketTypeAndLength()

MQTTStatus_t MQTT_GetIncomingPacketTypeAndLength	(	TransportRecv_t	readFunc,
		NetworkContext_t *	pNetworkContext,
		MQTTPacketInfo_t *	pIncomingPacket
	)

Extract the MQTT packet type and length from incoming packet.

This function must be called for every incoming packet to retrieve the MQTTPacketInfo_t.type and MQTTPacketInfo_t.remainingLength. A MQTTPacketInfo_t is not valid until this routine has been invoked.

Parameters

[in]	readFunc	Transport layer read function pointer.
[in]	pNetworkContext	The network context pointer provided by the application.
[out]	pIncomingPacket	Pointer to MQTTPacketInfo_t structure. This is where type, remaining length and packet identifier are stored.

Returns: MQTTSuccess on successful extraction of type and length, MQTTBadParameter if pIncomingPacket is invalid, MQTTRecvFailed on transport receive failure, MQTTBadResponse if an invalid packet is read, and MQTTNoDataAvailable if there is nothing to read.

Example

// TransportRecv_t function for reading from the network.
int32_t socket_recv(
     NetworkContext_t * pNetworkContext,
     void * pBuffer,
     size_t bytesToRecv
);
// Some context to be used with above transport receive function.
NetworkContext_t networkContext;
 
// Struct to hold the incoming packet information.
MQTTPacketInfo_t incomingPacket;
MQTTStatus_t status = MQTTSuccess;
int32_t bytesRecvd;
// Buffer to hold the remaining data of the incoming packet.
uint8_t buffer[ BUFFER_SIZE ];
 
// Loop until data is available to be received.
do{
     status = MQTT_GetIncomingPacketTypeAndLength(
         socket_recv,
         &networkContext,
         &incomingPacket
     );
} while( status == MQTTNoDataAvailable );
 
assert( status == MQTTSuccess );
 
// Receive the rest of the incoming packet.
assert( incomingPacket.remainingLength <= BUFFER_SIZE );
bytesRecvd = socket_recv(
     &networkContext,
     ( void * ) buffer,
     incomingPacket.remainingLength
);
 
// Set the remaining data field.
incomingPacket.pRemainingData = buffer;

◆ MQTT_ProcessIncomingPacketTypeAndLength()

MQTTStatus_t MQTT_ProcessIncomingPacketTypeAndLength	(	const uint8_t *	pBuffer,
		const size_t *	pIndex,
		MQTTPacketInfo_t *	pIncomingPacket
	)

Extract the MQTT packet type and length from incoming packet.

This function must be called for every incoming packet to retrieve the MQTTPacketInfo_t.type and MQTTPacketInfo_t.remainingLength. A MQTTPacketInfo_t is not valid until this routine has been invoked.

Parameters

[in]	pBuffer	The buffer holding the raw data to be processed
[in]	pIndex	Pointer to the index within the buffer to marking the end of raw data available.
[out]	pIncomingPacket	Structure used to hold the fields of the incoming packet.

Returns: MQTTSuccess on successful extraction of type and length, MQTTBadParameter if pIncomingPacket is invalid, MQTTBadResponse if an invalid packet is read, and MQTTNoDataAvailable if there is nothing to read.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Function Documentation

◆ MQTT_GetConnectPacketSize()

◆ MQTT_SerializeConnect()

◆ MQTT_GetSubscribePacketSize()

◆ MQTT_SerializeSubscribe()

◆ MQTT_GetUnsubscribePacketSize()

◆ MQTT_SerializeUnsubscribe()

◆ MQTT_GetPublishPacketSize()

◆ MQTT_SerializePublish()

◆ MQTT_SerializePublishHeaderWithoutTopic()

◆ MQTT_SerializePublishHeader()

◆ MQTT_SerializeAck()

◆ MQTT_GetDisconnectPacketSize()

◆ MQTT_SerializeDisconnect()

◆ MQTT_GetPingreqPacketSize()

◆ MQTT_SerializePingreq()

◆ MQTT_DeserializePublish()

◆ MQTT_DeserializeAck()

◆ MQTT_GetIncomingPacketTypeAndLength()

◆ MQTT_ProcessIncomingPacketTypeAndLength()