MQTT API Reference
MQTT 3.1.1 client library
|
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... | |
Implements functions that generate and decode MQTT network packets.
#define UINT16_DECODE | ( | ptr | ) |
Macro for decoding a 2-byte unsigned int from a sequence of bytes.
[in] | ptr | A uint8_t* that points to the high byte. |
#define UINT8_SET_BIT | ( | x, | |
position | |||
) | ( x = ( uint8_t ) ( x | ( 0x01 << position ) ) ) |
Macro for setting a bit in a 1-byte unsigned int.
[in] | x | The unsigned int to set. |
[in] | position | Which bit to set. |
#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.
[in] | x | The unsigned int to check. |
[in] | position | Which bit to check. |
#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.
|
static |
Generate and return a 2-byte packet identifier.
This packet identifier will be nonzero.
|
static |
Calculate the number of bytes required to encode an MQTT "Remaining length" field.
[in] | length | The value of the "Remaining length" to encode. |
1
, 2
, 3
, or 4
.
|
static |
Encode the "Remaining length" field per MQTT spec.
[out] | pDestination | Where to write the encoded "Remaining length". |
[in] | length | The "Remaining length" to encode. |
pDestination
.pDestination
! Ensure that pDestination
is large enough to hold the encoded "Remaining length" using the function _remainingLengthEncodedSize to avoid buffer overflows.
|
static |
Encode a C string as a UTF-8 string, per MQTT 3.1.1 spec.
[out] | pDestination | Where to write the encoded string. |
[in] | source | The string to encode. |
[in] | sourceLength | The length of source. |
sourceLength+2
bytes greater than pDestination
.pDestination
! Ensure that pDestination
is large enough to hold sourceLength+2
bytes to avoid a buffer overflow.
|
static |
Calculate the size and "Remaining length" of a CONNECT packet generated from the given parameters.
[in] | pConnectInfo | User-provided CONNECT information struct. |
[out] | pRemainingLength | Output for calculated "Remaining length" field. |
[out] | pPacketSize | Output for calculated total packet size. |
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.
|
static |
Calculate the size and "Remaining length" of a PUBLISH packet generated from the given parameters.
[in] | pPublishInfo | User-provided PUBLISH information struct. |
[out] | pRemainingLength | Output for calculated "Remaining length" field. |
[out] | pPacketSize | Output for calculated total packet size. |
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.
|
static |
Calculate the size and "Remaining length" of a SUBSCRIBE or UNSUBSCRIBE packet generated from the given parameters.
[in] | type | Either IOT_MQTT_SUBSCRIBE or IOT_MQTT_UNSUBSCRIBE. |
[in] | pSubscriptionList | User-provided array of subscriptions. |
[in] | subscriptionCount | Size of pSubscriptionList . |
[out] | pRemainingLength | Output for calculated "Remaining length" field. |
[out] | pPacketSize | Output for calculated total packet size. |
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. uint8_t _IotMqtt_GetPacketType | ( | void * | pNetworkConnection, |
const IotNetworkInterface_t * | pNetworkInterface | ||
) |
Get the MQTT packet type from a stream of bytes off the network.
[in] | pNetworkConnection | Reference to the network connection. |
[in] | pNetworkInterface | Function pointers used to interact with the network. |
size_t _IotMqtt_GetRemainingLength | ( | void * | pNetworkConnection, |
const IotNetworkInterface_t * | pNetworkInterface | ||
) |
Get the remaining length from a stream of bytes off the network.
[in] | pNetworkConnection | Reference to the network connection. |
[in] | pNetworkInterface | Function pointers used to interact with the network. |
IotMqttError_t _IotMqtt_SerializeConnect | ( | const IotMqttConnectInfo_t * | pConnectInfo, |
uint8_t ** | pConnectPacket, | ||
size_t * | pPacketSize | ||
) |
Generate a CONNECT packet from the given parameters.
[in] | pConnectInfo | User-provided CONNECT information. |
[out] | pConnectPacket | Where the CONNECT packet is written. |
[out] | pPacketSize | Size of the packet written to pConnectPacket . |
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.
[in,out] | pConnack | Pointer to an MQTT packet struct representing a CONNACK. |
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.
[in] | pPublishInfo | User-provided PUBLISH information. |
[out] | pPublishPacket | Where the PUBLISH packet is written. |
[out] | pPacketSize | Size of the packet written to pPublishPacket . |
[out] | pPacketIdentifier | The packet identifier generated for this PUBLISH. |
[out] | pPacketIdentifierHigh | Where the high byte of the packet identifier is written. |
void _IotMqtt_PublishSetDup | ( | uint8_t * | pPublishPacket, |
uint8_t * | pPacketIdentifierHigh, | ||
uint16_t * | pNewPacketIdentifier | ||
) |
Set the DUP bit in a QoS 1 PUBLISH packet.
[in] | pPublishPacket | Pointer to the PUBLISH packet to modify. |
[in] | pPacketIdentifierHigh | The high byte of any packet identifier to modify. |
[out] | pNewPacketIdentifier | Since 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. |
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.
[in,out] | pPublish | Pointer to an MQTT packet struct representing a PUBLISH. |
IotMqttError_t _IotMqtt_SerializePuback | ( | uint16_t | packetIdentifier, |
uint8_t ** | pPubackPacket, | ||
size_t * | pPacketSize | ||
) |
Generate a PUBACK packet for the given packet identifier.
[in] | packetIdentifier | The packet identifier to place in PUBACK. |
[out] | pPubackPacket | Where the PUBACK packet is written. |
[out] | pPacketSize | Size of the packet written to pPubackPacket . |
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.
[in,out] | pPuback | Pointer to an MQTT packet struct representing a PUBACK. |
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.
[in] | pSubscriptionList | User-provided array of subscriptions. |
[in] | subscriptionCount | Size of pSubscriptionList . |
[out] | pSubscribePacket | Where the SUBSCRIBE packet is written. |
[out] | pPacketSize | Size of the packet written to pSubscribePacket . |
[out] | pPacketIdentifier | The packet identifier generated for this SUBSCRIBE. |
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.
[in,out] | pSuback | Pointer to an MQTT packet struct representing a SUBACK. |
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.
[in] | pSubscriptionList | User-provided array of subscriptions to remove. |
[in] | subscriptionCount | Size of pSubscriptionList . |
[out] | pUnsubscribePacket | Where the UNSUBSCRIBE packet is written. |
[out] | pPacketSize | Size of the packet written to pUnsubscribePacket . |
[out] | pPacketIdentifier | The packet identifier generated for this UNSUBSCRIBE. |
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.
[in,out] | pUnsuback | Pointer to an MQTT packet struct representing an UNSUBACK. |
IotMqttError_t _IotMqtt_SerializePingreq | ( | uint8_t ** | pPingreqPacket, |
size_t * | pPacketSize | ||
) |
Generate a PINGREQ packet.
[out] | pPingreqPacket | Where the PINGREQ packet is written. |
[out] | pPacketSize | Size of the packet written to pPingreqPacket . |
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.
[in,out] | pPingresp | Pointer to an MQTT packet struct representing a PINGRESP. |
IotMqttError_t _IotMqtt_SerializeDisconnect | ( | uint8_t ** | pDisconnectPacket, |
size_t * | pPacketSize | ||
) |
Generate a DISCONNECT packet.
[out] | pDisconnectPacket | Where the DISCONNECT packet is written. |
[out] | pPacketSize | Size of the packet written to pDisconnectPacket . |
void _IotMqtt_FreePacket | ( | uint8_t * | pPacket | ) |
Free a packet generated by the serializer.
[in] | pPacket | The packet to free. |