coreMQTT  v1.0.0
MQTT 3.1.1 Client Library
core_mqtt_serializer.c File Reference

Implements the user-facing functions in core_mqtt_serializer.h. More...

#include <string.h>
#include <assert.h>
#include "core_mqtt_serializer.h"

Macros

#define MQTT_VERSION_3_1_1   ( ( uint8_t ) 4U )
 MQTT protocol version 3.1.1.
 
#define MQTT_PACKET_CONNECT_HEADER_SIZE   ( 10UL )
 Size of the fixed and variable header of a CONNECT packet.
 
#define MQTT_CONNECT_FLAG_CLEAN   ( 1 )
 Clean session.
 
#define MQTT_CONNECT_FLAG_WILL   ( 2 )
 Will present.
 
#define MQTT_CONNECT_FLAG_WILL_QOS1   ( 3 )
 Will QoS 1.
 
#define MQTT_CONNECT_FLAG_WILL_QOS2   ( 4 )
 Will QoS 2.
 
#define MQTT_CONNECT_FLAG_WILL_RETAIN   ( 5 )
 Will retain.
 
#define MQTT_CONNECT_FLAG_PASSWORD   ( 6 )
 Password present.
 
#define MQTT_CONNECT_FLAG_USERNAME   ( 7 )
 User name present.
 
#define MQTT_PUBLISH_FLAG_RETAIN   ( 0 )
 MQTT PUBLISH retain flag.
 
#define MQTT_PUBLISH_FLAG_QOS1   ( 1 )
 MQTT PUBLISH QoS1 flag.
 
#define MQTT_PUBLISH_FLAG_QOS2   ( 2 )
 MQTT PUBLISH QoS2 flag.
 
#define MQTT_PUBLISH_FLAG_DUP   ( 3 )
 MQTT PUBLISH duplicate flag.
 
#define MQTT_DISCONNECT_PACKET_SIZE   ( 2UL )
 The size of MQTT DISCONNECT packets, per MQTT spec.
 
#define MQTT_PACKET_PINGREQ_SIZE   ( 2U )
 A PINGREQ packet is always 2 bytes in size, defined by MQTT 3.1.1 spec.
 
#define MQTT_DISCONNECT_REMAINING_LENGTH   ( ( uint8_t ) 0 )
 The Remaining Length field of MQTT disconnect packets, per MQTT spec.
 
#define MQTT_PACKET_CONNACK_REMAINING_LENGTH   ( ( uint8_t ) 2U )
 A CONNACK packet always has a "Remaining length" of 2.
 
#define MQTT_PACKET_CONNACK_SESSION_PRESENT_MASK   ( ( uint8_t ) 0x01U )
 The "Session Present" bit is always the lowest bit.
 
#define MQTT_PACKET_SIMPLE_ACK_REMAINING_LENGTH   ( ( uint8_t ) 2 )
 PUBACK, PUBREC, PUBREl, PUBCOMP, UNSUBACK Remaining length.
 
#define MQTT_PACKET_PINGRESP_REMAINING_LENGTH   ( 0U )
 A PINGRESP packet always has a "Remaining length" of 0.
 
#define MQTT_MAX_REMAINING_LENGTH   ( 268435455UL )
 Per the MQTT 3.1.1 spec, the largest "Remaining Length" of an MQTT packet is this value, 256 MB.
 
#define UINT8_SET_BIT(x, position)   ( ( x ) = ( uint8_t ) ( ( x ) | ( 0x01U << ( position ) ) ) )
 Set a bit in an 8-bit unsigned integer.
 
#define UINT8_CHECK_BIT(x, position)   ( ( ( x ) & ( 0x01U << ( position ) ) ) == ( 0x01U << ( position ) ) )
 Macro for checking if a bit is set in a 1-byte unsigned int. More...
 
#define UINT16_HIGH_BYTE(x)   ( ( uint8_t ) ( ( x ) >> 8 ) )
 Get the high byte of a 16-bit unsigned integer.
 
#define UINT16_LOW_BYTE(x)   ( ( uint8_t ) ( ( x ) & 0x00ffU ) )
 Get the low byte of a 16-bit unsigned integer.
 
#define UINT16_DECODE(ptr)
 Macro for decoding a 2-byte unsigned int from a sequence of bytes. More...
 
#define MQTT_REMAINING_LENGTH_INVALID   ( ( size_t ) 268435456 )
 A value that represents an invalid remaining length. More...
 
#define MQTT_MIN_PUBLISH_REMAINING_LENGTH_QOS0   ( 3U )
 The minimum remaining length for a QoS 0 PUBLISH. More...
 

Enumerations

enum  MQTTSubscriptionType_t { MQTT_SUBSCRIBE, MQTT_UNSUBSCRIBE }
 MQTT Subscription packet types. More...
 

Functions

static void serializePublishCommon (const MQTTPublishInfo_t *pPublishInfo, size_t remainingLength, uint16_t packetIdentifier, const MQTTFixedBuffer_t *pFixedBuffer, bool serializePayload)
 Serializes MQTT PUBLISH packet into the buffer provided. More...
 
static bool calculatePublishPacketSize (const MQTTPublishInfo_t *pPublishInfo, size_t *pRemainingLength, size_t *pPacketSize)
 Calculates the packet size and remaining length of an MQTT PUBLISH packet. More...
 
static MQTTStatus_t calculateSubscriptionPacketSize (const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, size_t *pRemainingLength, size_t *pPacketSize, MQTTSubscriptionType_t subscriptionType)
 Calculates the packet size and remaining length of an MQTT SUBSCRIBE or UNSUBSCRIBE packet. More...
 
static MQTTStatus_t validateSubscriptionSerializeParams (const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId, size_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
 Validates parameters of MQTT_SerializeSubscribe or MQTT_SerializeUnsubscribe. More...
 
static void serializeConnectPacket (const MQTTConnectInfo_t *pConnectInfo, const MQTTPublishInfo_t *pWillInfo, size_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
 Serialize an MQTT CONNECT packet in the given buffer. More...
 
static void logConnackResponse (uint8_t responseCode)
 Prints the appropriate message for the CONNACK response code if logs are enabled. More...
 
static uint8_t * encodeRemainingLength (uint8_t *pDestination, size_t length)
 Encodes the remaining length of the packet using the variable length encoding scheme provided in the MQTT v3.1.1 specification. More...
 
static size_t remainingLengthEncodedSize (size_t length)
 Retrieve the size of the remaining length if it were to be encoded. More...
 
static uint8_t * encodeString (uint8_t *pDestination, const char *pSource, uint16_t sourceLength)
 Encode a string whose size is at maximum 16 bits in length. More...
 
static size_t getRemainingLength (TransportRecv_t recvFunc, const NetworkContext_t *pNetworkContext)
 Retrieves and decodes the Remaining Length from the network interface by reading a single byte at a time. More...
 
static bool incomingPacketValid (uint8_t packetType)
 Check if an incoming packet type is valid. More...
 
static MQTTStatus_t checkPublishRemainingLength (size_t remainingLength, MQTTQoS_t qos, size_t qos0Minimum)
 Check the remaining length of an incoming PUBLISH packet against some value for QoS 0, or for QoS 1 and 2. More...
 
static MQTTStatus_t processPublishFlags (uint8_t publishFlags, MQTTPublishInfo_t *pPublishInfo)
 Process the flags of an incoming PUBLISH packet. More...
 
static MQTTStatus_t deserializeConnack (const MQTTPacketInfo_t *pConnack, bool *pSessionPresent)
 Deserialize a CONNACK packet. More...
 
static MQTTStatus_t readSubackStatus (size_t statusCount, const uint8_t *pStatusStart)
 Decode the status bytes of a SUBACK packet to a MQTTStatus_t. More...
 
static MQTTStatus_t deserializeSuback (const MQTTPacketInfo_t *pSuback, uint16_t *pPacketIdentifier)
 Deserialize a SUBACK packet. More...
 
static MQTTStatus_t deserializePublish (const MQTTPacketInfo_t *pIncomingPacket, uint16_t *pPacketId, MQTTPublishInfo_t *pPublishInfo)
 Deserialize a PUBLISH packet received from the server. More...
 
static MQTTStatus_t deserializeSimpleAck (const MQTTPacketInfo_t *pAck, uint16_t *pPacketIdentifier)
 Deserialize an UNSUBACK, PUBACK, PUBREC, PUBREL, or PUBCOMP packet. More...
 
static MQTTStatus_t deserializePingresp (const MQTTPacketInfo_t *pPingresp)
 Deserialize a PINGRESP packet. More...
 
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_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, const NetworkContext_t *pNetworkContext, MQTTPacketInfo_t *pIncomingPacket)
 Extract the MQTT packet type and length from incoming packet. More...
 

Detailed Description

Implements the user-facing functions in core_mqtt_serializer.h.

Macro Definition Documentation

◆ UINT8_CHECK_BIT

#define UINT8_CHECK_BIT (   x,
  position 
)    ( ( ( x ) & ( 0x01U << ( position ) ) ) == ( 0x01U << ( position ) ) )

Macro for checking if a bit is set in a 1-byte unsigned int.

Parameters
[in]xThe unsigned int to check.
[in]positionWhich bit to check.

◆ UINT16_DECODE

#define UINT16_DECODE (   ptr)
Value:
( uint16_t ) ( ( ( ( uint16_t ) ( *( ptr ) ) ) << 8 ) | \
( ( uint16_t ) ( *( ( ptr ) + 1 ) ) ) )

Macro for decoding a 2-byte unsigned int from a sequence of bytes.

Parameters
[in]ptrA uint8_t* that points to the high byte.

◆ MQTT_REMAINING_LENGTH_INVALID

#define MQTT_REMAINING_LENGTH_INVALID   ( ( size_t ) 268435456 )

A value that represents an invalid remaining length.

This value is greater than what is allowed by the MQTT specification.

◆ MQTT_MIN_PUBLISH_REMAINING_LENGTH_QOS0

#define MQTT_MIN_PUBLISH_REMAINING_LENGTH_QOS0   ( 3U )

The minimum remaining length for a QoS 0 PUBLISH.

Includes two bytes for topic name length and one byte for topic name.

Enumeration Type Documentation

◆ MQTTSubscriptionType_t

MQTT Subscription packet types.

Enumerator
MQTT_SUBSCRIBE 

The type is a SUBSCRIBE packet.

MQTT_UNSUBSCRIBE 

The type is a UNSUBSCRIBE packet.

Function Documentation

◆ serializePublishCommon()

static void serializePublishCommon ( const MQTTPublishInfo_t pPublishInfo,
size_t  remainingLength,
uint16_t  packetIdentifier,
const MQTTFixedBuffer_t pFixedBuffer,
bool  serializePayload 
)
static

Serializes MQTT PUBLISH packet into the buffer provided.

This function serializes MQTT PUBLISH packet into MQTTFixedBuffer_t.pBuffer. Copy of the payload into the buffer is done as part of the serialization only if serializePayload is true.

param[in] pPublishInfo Publish information.

param[in] remainingLength Remaining length of the PUBLISH packet.

param[in] packetIdentifier Packet identifier of PUBLISH packet.

param[in, out] pFixedBuffer Buffer to which PUBLISH packet will be serialized.

param[in] serializePayload Copy payload to the serialized buffer only if true. Only PUBLISH header will be serialized if false.

Returns
Total number of bytes sent; -1 if there is an error.

◆ calculatePublishPacketSize()

static bool calculatePublishPacketSize ( const MQTTPublishInfo_t pPublishInfo,
size_t *  pRemainingLength,
size_t *  pPacketSize 
)
static

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

Parameters
[in]pPublishInfoMQTT PUBLISH packet parameters.
[out]pRemainingLengthThe Remaining Length of the MQTT PUBLISH packet.
[out]pPacketSizeThe total size of the MQTT PUBLISH packet.
Returns
false if the packet would exceed the size allowed by the MQTT spec; true otherwise.

◆ calculateSubscriptionPacketSize()

static MQTTStatus_t calculateSubscriptionPacketSize ( const MQTTSubscribeInfo_t pSubscriptionList,
size_t  subscriptionCount,
size_t *  pRemainingLength,
size_t *  pPacketSize,
MQTTSubscriptionType_t  subscriptionType 
)
static

Calculates the packet size and remaining length of an MQTT SUBSCRIBE or UNSUBSCRIBE packet.

Parameters
[in]pSubscriptionListList of MQTT subscription info.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[out]pRemainingLengthThe Remaining Length of the MQTT SUBSCRIBE or UNSUBSCRIBE packet.
[out]pPacketSizeThe total size of the MQTT MQTT SUBSCRIBE or UNSUBSCRIBE packet.
[in]subscriptionTypeMQTT_SUBSCRIBE or MQTT_UNSUBSCRIBE.

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

◆ validateSubscriptionSerializeParams()

static MQTTStatus_t validateSubscriptionSerializeParams ( const MQTTSubscribeInfo_t pSubscriptionList,
size_t  subscriptionCount,
uint16_t  packetId,
size_t  remainingLength,
const MQTTFixedBuffer_t pFixedBuffer 
)
static

Validates parameters of MQTT_SerializeSubscribe or MQTT_SerializeUnsubscribe.

Parameters
[in]pSubscriptionListList of MQTT subscription info.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[in]packetIdPacket identifier.
[in]remainingLengthRemaining length of the packet.
[in]pFixedBufferBuffer for packet serialization.
Returns
MQTTNoMemory if pBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

◆ serializeConnectPacket()

static void serializeConnectPacket ( const MQTTConnectInfo_t pConnectInfo,
const MQTTPublishInfo_t pWillInfo,
size_t  remainingLength,
const MQTTFixedBuffer_t pFixedBuffer 
)
static

Serialize an MQTT CONNECT packet in the given buffer.

Parameters
[in]pConnectInfoMQTT CONNECT packet parameters.
[in]pWillInfoLast Will and Testament. Pass NULL if not used.
[in]remainingLengthRemaining Length of MQTT CONNECT packet.
[out]pFixedBufferBuffer for packet serialization.

◆ logConnackResponse()

static void logConnackResponse ( uint8_t  responseCode)
static

Prints the appropriate message for the CONNACK response code if logs are enabled.

Parameters
[in]responseCodeMQTT standard CONNACK response code.

◆ encodeRemainingLength()

static uint8_t * encodeRemainingLength ( uint8_t *  pDestination,
size_t  length 
)
static

Encodes the remaining length of the packet using the variable length encoding scheme provided in the MQTT v3.1.1 specification.

Parameters
[out]pDestinationThe destination buffer to store the encoded remaining length.
[in]lengthThe remaining length to encode.
Returns
The location of the byte following the encoded value.

◆ remainingLengthEncodedSize()

static size_t remainingLengthEncodedSize ( size_t  length)
static

Retrieve the size of the remaining length if it were to be encoded.

Parameters
[in]lengthThe remaining length to be encoded.
Returns
The size of the remaining length if it were to be encoded.

◆ encodeString()

static uint8_t * encodeString ( uint8_t *  pDestination,
const char *  pSource,
uint16_t  sourceLength 
)
static

Encode a string whose size is at maximum 16 bits in length.

Parameters
[out]pDestinationDestination buffer for the encoding.
[in]pSourceThe source string to encode.
[in]sourceLengthThe length of the source string to encode.
Returns
A pointer to the end of the encoded string.

◆ getRemainingLength()

static size_t getRemainingLength ( TransportRecv_t  recvFunc,
const NetworkContext_t pNetworkContext 
)
static

Retrieves and decodes the Remaining Length from the network interface by reading a single byte at a time.

Parameters
[in]recvFuncNetwork interface receive function.
[in]pNetworkContextNetwork interface context to the receive function.
Returns
The Remaining Length of the incoming packet.

◆ incomingPacketValid()

static bool incomingPacketValid ( uint8_t  packetType)
static

Check if an incoming packet type is valid.

Parameters
[in]packetTypeThe packet type to check.
Returns
true if the packet type is valid; false otherwise.

◆ checkPublishRemainingLength()

static MQTTStatus_t checkPublishRemainingLength ( size_t  remainingLength,
MQTTQoS_t  qos,
size_t  qos0Minimum 
)
static

Check the remaining length of an incoming PUBLISH packet against some value for QoS 0, or for QoS 1 and 2.

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

Parameters
[in]remainingLengthRemaining length of the PUBLISH packet.
[in]qosThe QoS of the PUBLISH.
[in]qos0MinimumMinimum possible remaining length for a QoS 0 PUBLISH.
Returns
MQTTSuccess or MQTTBadResponse.

◆ processPublishFlags()

static MQTTStatus_t processPublishFlags ( uint8_t  publishFlags,
MQTTPublishInfo_t pPublishInfo 
)
static

Process the flags of an incoming PUBLISH packet.

Parameters
[in]publishFlagsFlags of an incoming PUBLISH.
[in,out]pPublishInfoPointer to MQTTPublishInfo_t struct where output will be written.
Returns
MQTTSuccess or MQTTBadResponse.

◆ deserializeConnack()

static MQTTStatus_t deserializeConnack ( const MQTTPacketInfo_t pConnack,
bool *  pSessionPresent 
)
static

Deserialize a CONNACK packet.

Converts the packet from a stream of bytes to an MQTTStatus_t.

Parameters
[in]pConnackPointer to an MQTT packet struct representing a CONNACK.
[out]pSessionPresentWhether a previous session was present.
Returns
MQTTSuccess if CONNACK specifies that CONNECT was accepted; MQTTServerRefused if CONNACK specifies that CONNECT was rejected; MQTTBadResponse if the CONNACK packet doesn't follow MQTT spec.

◆ readSubackStatus()

static MQTTStatus_t readSubackStatus ( size_t  statusCount,
const uint8_t *  pStatusStart 
)
static

Decode the status bytes of a SUBACK packet to a MQTTStatus_t.

Parameters
[in]statusCountNumber of status bytes in the SUBACK.
[in]pStatusStartThe first status byte in the SUBACK.
Returns
MQTTSuccess, MQTTServerRefused, or MQTTBadResponse.

◆ deserializeSuback()

static MQTTStatus_t deserializeSuback ( const MQTTPacketInfo_t pSuback,
uint16_t *  pPacketIdentifier 
)
static

Deserialize a SUBACK packet.

Converts the packet from a stream of bytes to an MQTTStatus_t and extracts the packet identifier.

Parameters
[in]pSubackPointer to an MQTT packet struct representing a SUBACK.
[out]pPacketIdentifierPacket ID of the SUBACK.
Returns
MQTTSuccess if SUBACK is valid; MQTTBadResponse if SUBACK packet doesn't follow the MQTT spec.

◆ deserializePublish()

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

Deserialize a PUBLISH packet received from the server.

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

Parameters
[in]pIncomingPacketPointer to an MQTT packet struct representing a PUBLISH.
[out]pPacketIdPacket identifier of the PUBLISH.
[out]pPublishInfoPointer to MQTTPublishInfo_t where output is written.
Returns
MQTTSuccess if PUBLISH is valid; MQTTBadResponse if the PUBLISH packet doesn't follow MQTT spec.

◆ deserializeSimpleAck()

static MQTTStatus_t deserializeSimpleAck ( const MQTTPacketInfo_t pAck,
uint16_t *  pPacketIdentifier 
)
static

Deserialize an UNSUBACK, PUBACK, PUBREC, PUBREL, or PUBCOMP packet.

Converts the packet from a stream of bytes to an MQTTStatus_t and extracts the packet identifier.

Parameters
[in]pAckPointer to the MQTT packet structure representing the packet.
[out]pPacketIdentifierPacket ID of the ack type packet.
Returns
MQTTSuccess if UNSUBACK, PUBACK, PUBREC, PUBREL, or PUBCOMP is valid; MQTTBadResponse if the packet doesn't follow the MQTT spec.

◆ deserializePingresp()

static MQTTStatus_t deserializePingresp ( const MQTTPacketInfo_t pPingresp)
static

Deserialize a PINGRESP packet.

Converts the packet from a stream of bytes to an MQTTStatus_t.

Parameters
[in]pPingrespPointer to an MQTT packet struct representing a PINGRESP.
Returns
MQTTSuccess if PINGRESP is valid; MQTTBadResponse if the PINGRESP packet doesn't follow MQTT spec.

◆ 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]pConnectInfoMQTT CONNECT packet parameters.
[in]pWillInfoLast Will and Testament. Pass NULL if not used.
[out]pRemainingLengthThe Remaining Length of the MQTT CONNECT packet.
[out]pPacketSizeThe 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.
&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]pConnectInfoMQTT CONNECT packet parameters.
[in]pWillInfoLast Will and Testament. Pass NULL if not used.
[in]remainingLengthRemaining Length provided by MQTT_GetConnectPacketSize.
[out]pFixedBufferBuffer 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.
&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]pSubscriptionListList of MQTT subscription info.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[out]pRemainingLengthThe Remaining Length of the MQTT SUBSCRIBE packet.
[out]pPacketSizeThe 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.
&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]pSubscriptionListList of MQTT subscription info.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[in]packetIdpacket ID generated by MQTT_GetPacketId.
[in]remainingLengthRemaining Length provided by MQTT_GetSubscribePacketSize.
[out]pFixedBufferBuffer 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.
&subscriptionList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, &remainingLength, &packetSize
);
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
// Serialize the subscribe packet into the fixed buffer.
&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]pSubscriptionListList of MQTT subscription info.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[out]pRemainingLengthThe Remaining Length of the MQTT UNSUBSCRIBE packet.
[out]pPacketSizeThe 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.
&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]pSubscriptionListList of MQTT subscription info.
[in]subscriptionCountThe number of elements in pSubscriptionList.
[in]packetIdpacket ID generated by MQTT_GetPacketId.
[in]remainingLengthRemaining Length provided by MQTT_GetUnsubscribePacketSize.
[out]pFixedBufferBuffer 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.
&subscriptionList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, &remainingLength, &packetSize
);
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
// Serialize the unsubscribe packet into the fixed buffer.
&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]pPublishInfoMQTT PUBLISH packet parameters.
[out]pRemainingLengthThe Remaining Length of the MQTT PUBLISH packet.
[out]pPacketSizeThe 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.
&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]pPublishInfoMQTT PUBLISH packet parameters.
[in]packetIdpacket ID generated by MQTT_GetPacketId.
[in]remainingLengthRemaining Length provided by MQTT_GetPublishPacketSize.
[out]pFixedBufferBuffer 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.
&publishInfo, &remainingLength, &packetSize
);
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
// Serialize the publish packet into the fixed buffer.
&publishInfo,
packetId,
remainingLength,
&fixedBuffer
);
if( status == MQTTSuccess )
{
// The publish packet can now be sent to the broker.
}

◆ 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]pPublishInfoMQTT PUBLISH packet parameters.
[in]packetIdpacket ID generated by MQTT_GetPacketId.
[in]remainingLengthRemaining Length provided by MQTT_GetPublishPacketSize.
[out]pFixedBufferBuffer for packet serialization.
[out]pHeaderSizeSize 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.
&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.
&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]pFixedBufferBuffer for packet serialization.
[in]packetTypeByte of the corresponding packet fixed header per the MQTT spec.
[in]packetIdPacket 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.
// 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]pPacketSizeThe 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]pFixedBufferBuffer 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]pPacketSizeThe 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]pFixedBufferBuffer 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]pIncomingPacketMQTTPacketInfo_t containing the buffer.
[out]pPacketIdThe packet ID obtained from the buffer.
[out]pPublishInfoStruct 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.
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]pIncomingPacketMQTTPacketInfo_t containing the buffer.
[out]pPacketIdThe packet ID of obtained from the buffer. Not used in CONNACK or PINGRESP.
[out]pSessionPresentBoolean 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,
const 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]readFuncTransport layer read function pointer.
[in]pNetworkContextThe network context pointer provided by the application.
[out]pIncomingPacketPointer 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;
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{
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;
MQTTSubscribeInfo_t
MQTT SUBSCRIBE packet parameters.
Definition: core_mqtt_serializer.h:195
MQTT_GetPingreqPacketSize
MQTTStatus_t MQTT_GetPingreqPacketSize(size_t *pPacketSize)
Get the size of an MQTT PINGREQ packet.
Definition: core_mqtt_serializer.c:2162
MQTTPacketInfo_t::pRemainingData
uint8_t * pRemainingData
Remaining serialized data in the MQTT packet.
Definition: core_mqtt_serializer.h:268
MQTTPublishInfo_t::topicNameLength
uint16_t topicNameLength
Length of topic name.
Definition: core_mqtt_serializer.h:241
MQTTConnectInfo_t
MQTT CONNECT packet parameters.
Definition: core_mqtt_serializer.h:148
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.
Definition: core_mqtt_serializer.c:1835
MQTT_SerializeDisconnect
MQTTStatus_t MQTT_SerializeDisconnect(const MQTTFixedBuffer_t *pFixedBuffer)
Serialize an MQTT DISCONNECT packet into the given buffer.
Definition: core_mqtt_serializer.c:2119
MQTTFixedBuffer_t::pBuffer
uint8_t * pBuffer
Pointer to buffer.
Definition: core_mqtt_serializer.h:139
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.
Definition: core_mqtt_serializer.c:2044
MQTT_PUBLISH_ACK_PACKET_SIZE
#define MQTT_PUBLISH_ACK_PACKET_SIZE
The size of MQTT PUBACK, PUBREC, PUBREL, and PUBCOMP packets, per MQTT spec.
Definition: core_mqtt_serializer.h:91
MQTT_PACKET_TYPE_PUBACK
#define MQTT_PACKET_TYPE_PUBACK
PUBACK (bidirectional).
Definition: core_mqtt_serializer.h:74
MQTTNoDataAvailable
@ MQTTNoDataAvailable
Definition: core_mqtt_serializer.h:113
MQTTPacketInfo_t
MQTT incoming packet parameters.
Definition: core_mqtt_serializer.h:259
MQTTSubscribeInfo_t::pTopicFilter
const char * pTopicFilter
Topic filter to subscribe to.
Definition: core_mqtt_serializer.h:204
NetworkContext_t
struct NetworkContext NetworkContext_t
The NetworkContext is an incomplete type. An implementation of this interface must define struct Netw...
Definition: transport_interface.h:155
MQTTFixedBuffer_t
Buffer passed to MQTT library.
Definition: core_mqtt_serializer.h:138
MQTTPublishInfo_t::pPayload
const void * pPayload
Message payload.
Definition: core_mqtt_serializer.h:246
MQTTFixedBuffer_t::size
size_t size
Size of buffer.
Definition: core_mqtt_serializer.h:140
MQTT_SerializePingreq
MQTTStatus_t MQTT_SerializePingreq(const MQTTFixedBuffer_t *pFixedBuffer)
Serialize an MQTT PINGREQ packet into the given buffer.
Definition: core_mqtt_serializer.c:2182
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.
Definition: core_mqtt_serializer.c:2262
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.
Definition: core_mqtt_serializer.c:1482
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.
Definition: core_mqtt_serializer.c:1640
MQTTStatus_t
MQTTStatus_t
Return codes from MQTT functions.
Definition: core_mqtt_serializer.h:105
MQTT_PACKET_TYPE_PUBLISH
#define MQTT_PACKET_TYPE_PUBLISH
PUBLISH (bidirectional).
Definition: core_mqtt_serializer.h:73
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.
Definition: core_mqtt_serializer.c:1582
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.
Definition: core_mqtt_serializer.c:1784
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.
Definition: core_mqtt_serializer.c:1739
MQTTPublishInfo_t::pTopicName
const char * pTopicName
Topic name on which the message is published.
Definition: core_mqtt_serializer.h:236
MQTT_DeserializePublish
MQTTStatus_t MQTT_DeserializePublish(const MQTTPacketInfo_t *pIncomingPacket, uint16_t *pPacketId, MQTTPublishInfo_t *pPublishInfo)
Deserialize an MQTT PUBLISH packet.
Definition: core_mqtt_serializer.c:2225
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.
Definition: core_mqtt_serializer.c:1961
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.
Definition: core_mqtt_serializer.c:1876
MQTTSubscribeInfo_t::topicFilterLength
uint16_t topicFilterLength
Length of subscription topic filter.
Definition: core_mqtt_serializer.h:209
MQTTSubscribeInfo_t::qos
MQTTQoS_t qos
Quality of Service for subscription.
Definition: core_mqtt_serializer.h:199
MQTTPacketInfo_t::type
uint8_t type
Type of incoming MQTT packet.
Definition: core_mqtt_serializer.h:263
MQTTPublishInfo_t::qos
MQTTQoS_t qos
Quality of Service for message.
Definition: core_mqtt_serializer.h:221
MQTTSuccess
@ MQTTSuccess
Definition: core_mqtt_serializer.h:106
MQTTPublishInfo_t
MQTT PUBLISH packet parameters.
Definition: core_mqtt_serializer.h:217
MQTT_GetDisconnectPacketSize
MQTTStatus_t MQTT_GetDisconnectPacketSize(size_t *pPacketSize)
Get the size of an MQTT DISCONNECT packet.
Definition: core_mqtt_serializer.c:2099
MQTTPacketInfo_t::remainingLength
size_t remainingLength
Length of remaining serialized data.
Definition: core_mqtt_serializer.h:273
MQTTPublishInfo_t::payloadLength
size_t payloadLength
Message payload length.
Definition: core_mqtt_serializer.h:251
MQTT_GetIncomingPacketTypeAndLength
MQTTStatus_t MQTT_GetIncomingPacketTypeAndLength(TransportRecv_t readFunc, const NetworkContext_t *pNetworkContext, MQTTPacketInfo_t *pIncomingPacket)
Extract the MQTT packet type and length from incoming packet.
Definition: core_mqtt_serializer.c:2338
MQTTQoS0
@ MQTTQoS0
Definition: core_mqtt_serializer.h:125
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.
Definition: core_mqtt_serializer.c:1685