MQTT API Reference
MQTT 3.1.1 client library
iot_mqtt_serialize.c File Reference

Implements functions that generate and decode MQTT network packets. More...

#include "iot_config.h"
#include <string.h>
#include "private/iot_error.h"
#include "private/iot_mqtt_internal.h"
#include "platform/iot_threads.h"
#include "iot_atomic.h"

Macros

#define UINT16_HIGH_BYTE(x)   ( ( uint8_t ) ( x >> 8 ) )
 Get high byte.
 
#define UINT16_LOW_BYTE(x)   ( ( uint8_t ) ( x & 0x00ff ) )
 Get low byte.
 
#define UINT16_DECODE(ptr)
 Macro for decoding a 2-byte unsigned int from a sequence of bytes. More...
 
#define UINT8_SET_BIT(x, position)   ( x = ( uint8_t ) ( x | ( 0x01 << position ) ) )
 Macro for setting a bit in a 1-byte unsigned int. More...
 
#define UINT8_CHECK_BIT(x, position)   ( ( x & ( 0x01 << position ) ) == ( 0x01 << position ) )
 Macro for checking if a bit is set in a 1-byte unsigned int. More...
 
#define MQTT_CONNECT_FLAG_CLEAN   ( 1 )
 Clean session.
 
#define MQTT_CONNECT_FLAG_WILL   ( 2 )
 Will present.
 
#define MQTT_CONNECT_FLAG_WILL_QOS1   ( 3 )
 Will QoS1.
 
#define MQTT_CONNECT_FLAG_WILL_QOS2   ( 4 )
 Will QoS2.
 
#define MQTT_CONNECT_FLAG_WILL_RETAIN   ( 5 )
 Will retain.
 
#define MQTT_CONNECT_FLAG_PASSWORD   ( 6 )
 Password present.
 
#define MQTT_CONNECT_FLAG_USERNAME   ( 7 )
 Username present.
 
#define MQTT_PUBLISH_FLAG_RETAIN   ( 0 )
 Message retain flag.
 
#define MQTT_PUBLISH_FLAG_QOS1   ( 1 )
 Publish QoS 1.
 
#define MQTT_PUBLISH_FLAG_QOS2   ( 2 )
 Publish QoS 2.
 
#define MQTT_PUBLISH_FLAG_DUP   ( 3 )
 Duplicate message.
 
#define MQTT_VERSION_3_1_1   ( ( uint8_t ) 4U )
 The constant specifying MQTT version 3.1.1. Placed in the CONNECT packet.
 
#define MQTT_MAX_REMAINING_LENGTH   ( 268435455UL )
 Per the MQTT 3.1.1 spec, the largest "Remaining Length" of an MQTT packet is this value.
 
#define MQTT_PACKET_CONNECT_MAX_SIZE   ( 327700UL )
 The maximum possible size of a CONNECT packet. More...
 
#define MQTT_PACKET_CONNACK_REMAINING_LENGTH   ( ( uint8_t ) 2 )
 A CONNACK packet always has a "Remaining length" of 2.
 
#define MQTT_PACKET_CONNACK_SESSION_PRESENT_MASK   ( ( uint8_t ) 0x01 )
 The "Session Present" bit is always the lowest bit.
 
#define MQTT_PACKET_PUBACK_SIZE   ( 4 )
 A PUBACK packet is always 4 bytes in size.
 
#define MQTT_PACKET_PUBACK_REMAINING_LENGTH   ( ( uint8_t ) 2 )
 A PUBACK packet always has a "Remaining length" of 2.
 
#define MQTT_PACKET_SUBACK_MINIMUM_SIZE   ( 5 )
 The size of the smallest valid SUBACK packet.
 
#define MQTT_PACKET_UNSUBACK_REMAINING_LENGTH   ( ( uint8_t ) 2 )
 An UNSUBACK packet always has a "Remaining length" of 2.
 
#define MQTT_PACKET_PINGREQ_SIZE   ( 2 )
 A PINGREQ packet is always 2 bytes in size.
 
#define MQTT_PACKET_PINGRESP_REMAINING_LENGTH   ( 0 )
 A PINGRESP packet always has a "Remaining length" of 0.
 
#define MQTT_PACKET_DISCONNECT_SIZE   ( 2 )
 A DISCONNECT packet is always 2 bytes in size.
 
#define AWS_IOT_METRICS_USERNAME   "?SDK=C&Version=4.0.0"
 Specify C SDK and version.
 
#define AWS_IOT_METRICS_USERNAME_LENGTH   ( ( uint16_t ) sizeof( AWS_IOT_METRICS_USERNAME ) - 1 )
 The length of AWS_IOT_METRICS_USERNAME.
 

Functions

static uint16_t _nextPacketIdentifier (void)
 Generate and return a 2-byte packet identifier. More...
 
static size_t _remainingLengthEncodedSize (size_t length)
 Calculate the number of bytes required to encode an MQTT "Remaining length" field. More...
 
static uint8_t * _encodeRemainingLength (uint8_t *pDestination, size_t length)
 Encode the "Remaining length" field per MQTT spec. More...
 
static uint8_t * _encodeString (uint8_t *pDestination, const char *source, uint16_t sourceLength)
 Encode a C string as a UTF-8 string, per MQTT 3.1.1 spec. More...
 
static bool _connectPacketSize (const IotMqttConnectInfo_t *pConnectInfo, size_t *pRemainingLength, size_t *pPacketSize)
 Calculate the size and "Remaining length" of a CONNECT packet generated from the given parameters. More...
 
static bool _publishPacketSize (const IotMqttPublishInfo_t *pPublishInfo, size_t *pRemainingLength, size_t *pPacketSize)
 Calculate the size and "Remaining length" of a PUBLISH packet generated from the given parameters. More...
 
static bool _subscriptionPacketSize (IotMqttOperationType_t type, const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, size_t *pRemainingLength, size_t *pPacketSize)
 Calculate the size and "Remaining length" of a SUBSCRIBE or UNSUBSCRIBE packet generated from the given parameters. More...
 
uint8_t _IotMqtt_GetPacketType (void *pNetworkConnection, const IotNetworkInterface_t *pNetworkInterface)
 Get the MQTT packet type from a stream of bytes off the network. More...
 
size_t _IotMqtt_GetRemainingLength (void *pNetworkConnection, const IotNetworkInterface_t *pNetworkInterface)
 Get the remaining length from a stream of bytes off the network. More...
 
IotMqttError_t _IotMqtt_SerializeConnect (const IotMqttConnectInfo_t *pConnectInfo, uint8_t **pConnectPacket, size_t *pPacketSize)
 Generate a CONNECT packet from the given parameters. More...
 
IotMqttError_t _IotMqtt_DeserializeConnack (_mqttPacket_t *pConnack)
 Deserialize a CONNACK packet. More...
 
IotMqttError_t _IotMqtt_SerializePublish (const IotMqttPublishInfo_t *pPublishInfo, uint8_t **pPublishPacket, size_t *pPacketSize, uint16_t *pPacketIdentifier, uint8_t **pPacketIdentifierHigh)
 Generate a PUBLISH packet from the given parameters. More...
 
void _IotMqtt_PublishSetDup (uint8_t *pPublishPacket, uint8_t *pPacketIdentifierHigh, uint16_t *pNewPacketIdentifier)
 Set the DUP bit in a QoS 1 PUBLISH packet. More...
 
IotMqttError_t _IotMqtt_DeserializePublish (_mqttPacket_t *pPublish)
 Deserialize a PUBLISH packet received from the server. More...
 
IotMqttError_t _IotMqtt_SerializePuback (uint16_t packetIdentifier, uint8_t **pPubackPacket, size_t *pPacketSize)
 Generate a PUBACK packet for the given packet identifier. More...
 
IotMqttError_t _IotMqtt_DeserializePuback (_mqttPacket_t *pPuback)
 Deserialize a PUBACK packet. More...
 
IotMqttError_t _IotMqtt_SerializeSubscribe (const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint8_t **pSubscribePacket, size_t *pPacketSize, uint16_t *pPacketIdentifier)
 Generate a SUBSCRIBE packet from the given parameters. More...
 
IotMqttError_t _IotMqtt_DeserializeSuback (_mqttPacket_t *pSuback)
 Deserialize a SUBACK packet. More...
 
IotMqttError_t _IotMqtt_SerializeUnsubscribe (const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint8_t **pUnsubscribePacket, size_t *pPacketSize, uint16_t *pPacketIdentifier)
 Generate an UNSUBSCRIBE packet from the given parameters. More...
 
IotMqttError_t _IotMqtt_DeserializeUnsuback (_mqttPacket_t *pUnsuback)
 Deserialize a UNSUBACK packet. More...
 
IotMqttError_t _IotMqtt_SerializePingreq (uint8_t **pPingreqPacket, size_t *pPacketSize)
 Generate a PINGREQ packet. More...
 
IotMqttError_t _IotMqtt_DeserializePingresp (_mqttPacket_t *pPingresp)
 Deserialize a PINGRESP packet. More...
 
IotMqttError_t _IotMqtt_SerializeDisconnect (uint8_t **pDisconnectPacket, size_t *pPacketSize)
 Generate a DISCONNECT packet. More...
 
void _IotMqtt_FreePacket (uint8_t *pPacket)
 Free a packet generated by the serializer. More...
 

Detailed Description

Implements functions that generate and decode MQTT network packets.

Macro Definition Documentation

◆ 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.

◆ UINT8_SET_BIT

#define UINT8_SET_BIT (   x,
  position 
)    ( x = ( uint8_t ) ( x | ( 0x01 << position ) ) )

Macro for setting a bit in a 1-byte unsigned int.

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

◆ UINT8_CHECK_BIT

#define UINT8_CHECK_BIT (   x,
  position 
)    ( ( x & ( 0x01 << position ) ) == ( 0x01 << 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.

◆ MQTT_PACKET_CONNECT_MAX_SIZE

#define MQTT_PACKET_CONNECT_MAX_SIZE   ( 327700UL )

The maximum possible size of a CONNECT packet.

All strings in a CONNECT packet are constrained to 2-byte lengths, giving a maximum length smaller than the max "Remaining Length" constant above.

Function Documentation

◆ _nextPacketIdentifier()

static uint16_t _nextPacketIdentifier ( void  )
static

Generate and return a 2-byte packet identifier.

This packet identifier will be nonzero.

Returns
The packet identifier.

◆ _remainingLengthEncodedSize()

static size_t _remainingLengthEncodedSize ( size_t  length)
static

Calculate the number of bytes required to encode an MQTT "Remaining length" field.

Parameters
[in]lengthThe value of the "Remaining length" to encode.
Returns
The size of the encoding of length. This is always 1, 2, 3, or 4.

◆ _encodeRemainingLength()

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

Encode the "Remaining length" field per MQTT spec.

Parameters
[out]pDestinationWhere to write the encoded "Remaining length".
[in]lengthThe "Remaining length" to encode.
Returns
Pointer to the end of the encoded "Remaining length", which is 1-4 bytes greater than pDestination.
Warning
This function does not check the size of pDestination! Ensure that pDestination is large enough to hold the encoded "Remaining length" using the function _remainingLengthEncodedSize to avoid buffer overflows.

◆ _encodeString()

static uint8_t * _encodeString ( uint8_t *  pDestination,
const char *  source,
uint16_t  sourceLength 
)
static

Encode a C string as a UTF-8 string, per MQTT 3.1.1 spec.

Parameters
[out]pDestinationWhere to write the encoded string.
[in]sourceThe string to encode.
[in]sourceLengthThe length of source.
Returns
Pointer to the end of the encoded string, which is sourceLength+2 bytes greater than pDestination.
Warning
This function does not check the size of pDestination! Ensure that pDestination is large enough to hold sourceLength+2 bytes to avoid a buffer overflow.

◆ _connectPacketSize()

static bool _connectPacketSize ( const IotMqttConnectInfo_t pConnectInfo,
size_t *  pRemainingLength,
size_t *  pPacketSize 
)
static

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

Parameters
[in]pConnectInfoUser-provided CONNECT information struct.
[out]pRemainingLengthOutput for calculated "Remaining length" field.
[out]pPacketSizeOutput for calculated total packet size.
Returns
true if the packet is within the length allowed by MQTT 3.1.1 spec; false otherwise. If this function returns false, the output parameters should be ignored.

◆ _publishPacketSize()

static bool _publishPacketSize ( const IotMqttPublishInfo_t pPublishInfo,
size_t *  pRemainingLength,
size_t *  pPacketSize 
)
static

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

Parameters
[in]pPublishInfoUser-provided PUBLISH information struct.
[out]pRemainingLengthOutput for calculated "Remaining length" field.
[out]pPacketSizeOutput for calculated total packet size.
Returns
true if the packet is within the length allowed by MQTT 3.1.1 spec; false otherwise. If this function returns false, the output parameters should be ignored.

◆ _subscriptionPacketSize()

static bool _subscriptionPacketSize ( IotMqttOperationType_t  type,
const IotMqttSubscription_t pSubscriptionList,
size_t  subscriptionCount,
size_t *  pRemainingLength,
size_t *  pPacketSize 
)
static

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

Parameters
[in]typeEither IOT_MQTT_SUBSCRIBE or IOT_MQTT_UNSUBSCRIBE.
[in]pSubscriptionListUser-provided array of subscriptions.
[in]subscriptionCountSize of pSubscriptionList.
[out]pRemainingLengthOutput for calculated "Remaining length" field.
[out]pPacketSizeOutput for calculated total packet size.
Returns
true if the packet is within the length allowed by MQTT 3.1.1 spec; false otherwise. If this function returns false, the output parameters should be ignored.

◆ _IotMqtt_GetPacketType()

uint8_t _IotMqtt_GetPacketType ( void *  pNetworkConnection,
const IotNetworkInterface_t pNetworkInterface 
)

Get the MQTT packet type from a stream of bytes off the network.

Parameters
[in]pNetworkConnectionReference to the network connection.
[in]pNetworkInterfaceFunction pointers used to interact with the network.
Returns
One of the server-to-client MQTT packet types.
Note
This function is only used for incoming packets, and may not work correctly for outgoing packets.

◆ _IotMqtt_GetRemainingLength()

size_t _IotMqtt_GetRemainingLength ( void *  pNetworkConnection,
const IotNetworkInterface_t pNetworkInterface 
)

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

Parameters
[in]pNetworkConnectionReference to the network connection.
[in]pNetworkInterfaceFunction pointers used to interact with the network.
Returns
The remaining length; MQTT_REMAINING_LENGTH_INVALID on error.

◆ _IotMqtt_SerializeConnect()

IotMqttError_t _IotMqtt_SerializeConnect ( const IotMqttConnectInfo_t pConnectInfo,
uint8_t **  pConnectPacket,
size_t *  pPacketSize 
)

Generate a CONNECT packet from the given parameters.

Parameters
[in]pConnectInfoUser-provided CONNECT information.
[out]pConnectPacketWhere the CONNECT packet is written.
[out]pPacketSizeSize of the packet written to pConnectPacket.
Returns
IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_DeserializeConnack()

IotMqttError_t _IotMqtt_DeserializeConnack ( _mqttPacket_t pConnack)

Deserialize a CONNACK packet.

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

Parameters
[in,out]pConnackPointer to an MQTT packet struct representing a CONNACK.
Returns
IOT_MQTT_SUCCESS if CONNACK specifies that CONNECT was accepted; IOT_MQTT_SERVER_REFUSED if CONNACK specifies that CONNECT was rejected; IOT_MQTT_BAD_RESPONSE if the CONNACK packet doesn't follow MQTT spec.

◆ _IotMqtt_SerializePublish()

IotMqttError_t _IotMqtt_SerializePublish ( const IotMqttPublishInfo_t pPublishInfo,
uint8_t **  pPublishPacket,
size_t *  pPacketSize,
uint16_t *  pPacketIdentifier,
uint8_t **  pPacketIdentifierHigh 
)

Generate a PUBLISH packet from the given parameters.

Parameters
[in]pPublishInfoUser-provided PUBLISH information.
[out]pPublishPacketWhere the PUBLISH packet is written.
[out]pPacketSizeSize of the packet written to pPublishPacket.
[out]pPacketIdentifierThe packet identifier generated for this PUBLISH.
[out]pPacketIdentifierHighWhere the high byte of the packet identifier is written.
Returns
IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_PublishSetDup()

void _IotMqtt_PublishSetDup ( uint8_t *  pPublishPacket,
uint8_t *  pPacketIdentifierHigh,
uint16_t *  pNewPacketIdentifier 
)

Set the DUP bit in a QoS 1 PUBLISH packet.

Parameters
[in]pPublishPacketPointer to the PUBLISH packet to modify.
[in]pPacketIdentifierHighThe high byte of any packet identifier to modify.
[out]pNewPacketIdentifierSince AWS IoT does not support the DUP flag, a new packet identifier is generated and should be written here. This parameter is only used when connected to an AWS IoT MQTT server.
Note
See IotMqttPublishInfo_t for caveats with retransmission to the AWS IoT MQTT server.

◆ _IotMqtt_DeserializePublish()

IotMqttError_t _IotMqtt_DeserializePublish ( _mqttPacket_t pPublish)

Deserialize a PUBLISH packet received from the server.

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

Parameters
[in,out]pPublishPointer to an MQTT packet struct representing a PUBLISH.
Returns
IOT_MQTT_SUCCESS if PUBLISH is valid; IOT_MQTT_BAD_RESPONSE if the PUBLISH packet doesn't follow MQTT spec.

◆ _IotMqtt_SerializePuback()

IotMqttError_t _IotMqtt_SerializePuback ( uint16_t  packetIdentifier,
uint8_t **  pPubackPacket,
size_t *  pPacketSize 
)

Generate a PUBACK packet for the given packet identifier.

Parameters
[in]packetIdentifierThe packet identifier to place in PUBACK.
[out]pPubackPacketWhere the PUBACK packet is written.
[out]pPacketSizeSize of the packet written to pPubackPacket.
Returns
IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_DeserializePuback()

IotMqttError_t _IotMqtt_DeserializePuback ( _mqttPacket_t pPuback)

Deserialize a PUBACK packet.

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

Parameters
[in,out]pPubackPointer to an MQTT packet struct representing a PUBACK.
Returns
IOT_MQTT_SUCCESS if PUBACK is valid; IOT_MQTT_BAD_RESPONSE if the PUBACK packet doesn't follow MQTT spec.

◆ _IotMqtt_SerializeSubscribe()

IotMqttError_t _IotMqtt_SerializeSubscribe ( const IotMqttSubscription_t pSubscriptionList,
size_t  subscriptionCount,
uint8_t **  pSubscribePacket,
size_t *  pPacketSize,
uint16_t *  pPacketIdentifier 
)

Generate a SUBSCRIBE packet from the given parameters.

Parameters
[in]pSubscriptionListUser-provided array of subscriptions.
[in]subscriptionCountSize of pSubscriptionList.
[out]pSubscribePacketWhere the SUBSCRIBE packet is written.
[out]pPacketSizeSize of the packet written to pSubscribePacket.
[out]pPacketIdentifierThe packet identifier generated for this SUBSCRIBE.
Returns
IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_DeserializeSuback()

IotMqttError_t _IotMqtt_DeserializeSuback ( _mqttPacket_t pSuback)

Deserialize a SUBACK packet.

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

Parameters
[in,out]pSubackPointer to an MQTT packet struct representing a SUBACK.
Returns
IOT_MQTT_SUCCESS if SUBACK is valid; IOT_MQTT_BAD_RESPONSE if the SUBACK packet doesn't follow MQTT spec.

◆ _IotMqtt_SerializeUnsubscribe()

IotMqttError_t _IotMqtt_SerializeUnsubscribe ( const IotMqttSubscription_t pSubscriptionList,
size_t  subscriptionCount,
uint8_t **  pUnsubscribePacket,
size_t *  pPacketSize,
uint16_t *  pPacketIdentifier 
)

Generate an UNSUBSCRIBE packet from the given parameters.

Parameters
[in]pSubscriptionListUser-provided array of subscriptions to remove.
[in]subscriptionCountSize of pSubscriptionList.
[out]pUnsubscribePacketWhere the UNSUBSCRIBE packet is written.
[out]pPacketSizeSize of the packet written to pUnsubscribePacket.
[out]pPacketIdentifierThe packet identifier generated for this UNSUBSCRIBE.
Returns
IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_DeserializeUnsuback()

IotMqttError_t _IotMqtt_DeserializeUnsuback ( _mqttPacket_t pUnsuback)

Deserialize a UNSUBACK packet.

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

Parameters
[in,out]pUnsubackPointer to an MQTT packet struct representing an UNSUBACK.
Returns
IOT_MQTT_SUCCESS if UNSUBACK is valid; IOT_MQTT_BAD_RESPONSE if the UNSUBACK packet doesn't follow MQTT spec.

◆ _IotMqtt_SerializePingreq()

IotMqttError_t _IotMqtt_SerializePingreq ( uint8_t **  pPingreqPacket,
size_t *  pPacketSize 
)

Generate a PINGREQ packet.

Parameters
[out]pPingreqPacketWhere the PINGREQ packet is written.
[out]pPacketSizeSize of the packet written to pPingreqPacket.
Returns
Always returns IOT_MQTT_SUCCESS.

◆ _IotMqtt_DeserializePingresp()

IotMqttError_t _IotMqtt_DeserializePingresp ( _mqttPacket_t pPingresp)

Deserialize a PINGRESP packet.

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

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

◆ _IotMqtt_SerializeDisconnect()

IotMqttError_t _IotMqtt_SerializeDisconnect ( uint8_t **  pDisconnectPacket,
size_t *  pPacketSize 
)

Generate a DISCONNECT packet.

Parameters
[out]pDisconnectPacketWhere the DISCONNECT packet is written.
[out]pPacketSizeSize of the packet written to pDisconnectPacket.
Returns
Always returns IOT_MQTT_SUCCESS.

◆ _IotMqtt_FreePacket()

void _IotMqtt_FreePacket ( uint8_t *  pPacket)

Free a packet generated by the serializer.

Parameters
[in]pPacketThe packet to free.