core_mqtt_serializer.h File Reference

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

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

Go to the source code of this file.

Data Structures
struct	MQTTFixedBuffer_t
	Buffer passed to MQTT library. More...
struct	MQTTConnectInfo_t
	MQTT CONNECT packet parameters. More...
struct	MQTTSubscribeInfo_t
	MQTT SUBSCRIBE packet parameters. More...
struct	MQTTPublishInfo_t
	MQTT PUBLISH packet parameters. More...
struct	MQTTPacketInfo_t
	MQTT incoming packet parameters. More...
struct	MQTTPropBuilder_t
	Property builder for MQTT packets. More...
struct	MQTTReasonCodeInfo_t
	Struct to hold reason codes. More...
struct	MQTTConnectionProperties_t
	Struct to hold connect and connack properties. More...
struct	MQTTUserProperty_t
	Struct to hold user property. More...

Macros
#define	MQTT_PACKET_TYPE_CONNECT   ( ( uint8_t ) 0x10U )
	CONNECT (client-to-server).
#define	MQTT_PACKET_TYPE_CONNACK   ( ( uint8_t ) 0x20U )
	CONNACK (server-to-client).
#define	MQTT_PACKET_TYPE_PUBLISH   ( ( uint8_t ) 0x30U )
	PUBLISH (bidirectional).
#define	MQTT_PACKET_TYPE_PUBACK   ( ( uint8_t ) 0x40U )
	PUBACK (bidirectional).
#define	MQTT_PACKET_TYPE_PUBREC   ( ( uint8_t ) 0x50U )
	PUBREC (bidirectional).
#define	MQTT_PACKET_TYPE_PUBREL   ( ( uint8_t ) 0x62U )
	PUBREL (bidirectional).
#define	MQTT_PACKET_TYPE_PUBCOMP   ( ( uint8_t ) 0x70U )
	PUBCOMP (bidirectional).
#define	MQTT_PACKET_TYPE_SUBSCRIBE   ( ( uint8_t ) 0x82U )
	SUBSCRIBE (client-to-server).
#define	MQTT_PACKET_TYPE_SUBACK   ( ( uint8_t ) 0x90U )
	SUBACK (server-to-client).
#define	MQTT_PACKET_TYPE_UNSUBSCRIBE   ( ( uint8_t ) 0xA2U )
	UNSUBSCRIBE (client-to-server).
#define	MQTT_PACKET_TYPE_UNSUBACK   ( ( uint8_t ) 0xB0U )
	UNSUBACK (server-to-client).
#define	MQTT_PACKET_TYPE_PINGREQ   ( ( uint8_t ) 0xC0U )
	PINGREQ (client-to-server).
#define	MQTT_PACKET_TYPE_PINGRESP   ( ( uint8_t ) 0xD0U )
	PINGRESP (server-to-client).
#define	MQTT_PACKET_TYPE_DISCONNECT   ( ( uint8_t ) 0xE0U )
	DISCONNECT (client-to-server).
#define	MQTT_PACKET_TYPE_AUTH   ( ( uint8_t ) 0xF0U )
	AUTH (bidirectional).
#define	MQTT_PUBLISH_ACK_PACKET_SIZE   ( 4UL )
	The size of MQTT PUBACK, PUBREC, PUBREL, and PUBCOMP packets, per MQTT spec.
#define	MQTT_SUBSCRIBE_QOS1   ( 0U )
	MQTT SUBSCRIBE QoS1 flag.
#define	MQTT_SUBSCRIBE_QOS2   ( 1U )
	MQTT SUBSCRIBE QoS2 flag.
#define	MQTT_SUBSCRIBE_NO_LOCAL   ( 2U )
	MQTT SUBSCRIBE no local flag.
#define	MQTT_SUBSCRIBE_RETAIN_AS_PUBLISHED   ( 3U )
	MQTT SUBSCRIBE retain as published flag.
#define	MQTT_SUBSCRIBE_RETAIN_HANDLING1   ( 4U )
	MQTT SUBSCRIBE Retain Handling Option 1.
#define	MQTT_SUBSCRIBE_RETAIN_HANDLING2   ( 5U )
	Retain Handling Option 2 -> in core_mqtt_serializer.c.
#define	MQTT_SESSION_EXPIRY_ID   ( 0x11U )
	Session expiry id.
#define	MQTT_RECEIVE_MAX_ID   ( 0x21U )
	Receive maximum id.
#define	MQTT_MAX_PACKET_SIZE_ID   ( 0x27U )
	Maximum packet size id.
#define	MQTT_TOPIC_ALIAS_MAX_ID   ( 0x22U )
	Topic alias size id.
#define	MQTT_REQUEST_RESPONSE_ID   ( 0x19U )
	Request response id.
#define	MQTT_REQUEST_PROBLEM_ID   ( 0x17U )
	Request problem id.
#define	MQTT_USER_PROPERTY_ID   ( 0x26U )
	User property id.
#define	MQTT_AUTH_METHOD_ID   ( 0x15U )
	Authentication method id.
#define	MQTT_AUTH_DATA_ID   ( 0x16U )
	Authentication data id.
#define	MQTT_WILL_DELAY_ID   ( 0x18U )
	Will delay id.
#define	MQTT_PAYLOAD_FORMAT_ID   ( 0x01U )
	Payload format id.
#define	MQTT_MSG_EXPIRY_ID   ( 0x02U )
	Message Expiry id.
#define	MQTT_CONTENT_TYPE_ID   ( 0x03U )
	Content type id.
#define	MQTT_RESPONSE_TOPIC_ID   ( 0x08U )
	Response topic id.
#define	MQTT_CORRELATION_DATA_ID   ( 0x09U )
	Correlation data id.
#define	MQTT_TOPIC_ALIAS_ID   ( 0x23U )
	Topic alias id.
#define	MQTT_MAX_QOS_ID   ( 0x24U )
	Max qos id.
#define	MQTT_RETAIN_AVAILABLE_ID   ( 0x25U )
	Retain available id.
#define	MQTT_ASSIGNED_CLIENT_ID   ( 0x12U )
	Assigned client identifier id.
#define	MQTT_REASON_STRING_ID   ( 0x1FU )
	Reason string id.
#define	MQTT_WILDCARD_ID   ( 0x28U )
	Wildcard available id.
#define	MQTT_SUB_AVAILABLE_ID   ( 0x29U )
	Subscription available id.
#define	MQTT_SHARED_SUB_ID   ( 0x2AU )
	Shared subscription id.
#define	MQTT_SERVER_KEEP_ALIVE_ID   ( 0x13U )
	Server keep alive id.
#define	MQTT_RESPONSE_INFO_ID   ( 0x1AU )
	Response information id.
#define	MQTT_SERVER_REF_ID   ( 0x1CU )
	Server reference id.
#define	MQTT_SUBSCRIPTION_ID_ID   ( 0x0BU )
	Subscription ID id.

Enumerations
enum	MQTTStatus_t {   MQTTSuccess = 0 , MQTTBadParameter , MQTTNoMemory , MQTTSendFailed ,   MQTTRecvFailed , MQTTBadResponse , MQTTServerRefused , MQTTNoDataAvailable ,   MQTTIllegalState , MQTTStateCollision , MQTTKeepAliveTimeout , MQTTNeedMoreBytes ,   MQTTEndOfProperties , MQTTStatusConnected , MQTTStatusNotConnected , MQTTStatusDisconnectPending ,   MQTTPublishStoreFailed , MQTTPublishRetrieveFailed , MQTTEventCallbackFailed }
	Return codes from MQTT functions. More...
enum	MQTTQoS_t { MQTTQoS0 = 0 , MQTTQoS1 = 1 , MQTTQoS2 = 2 }
	MQTT Quality of Service values. More...
enum	MQTTRetainHandling_t { retainSendOnSub = 0 , retainSendOnSubIfNotPresent = 1 , retainDoNotSendonSub = 2 }
	Retain Handling types. More...
enum	MQTTSuccessFailReasonCode_t {   MQTT_REASON_PUBACK_SUCCESS = 0x00U , MQTT_REASON_PUBACK_NO_MATCHING_SUBSCRIBERS = 0x10U , MQTT_REASON_PUBACK_UNSPECIFIED_ERROR = 0x80U , MQTT_REASON_PUBACK_IMPLEMENTATION_SPECIFIC_ERROR = 0x83U ,   MQTT_REASON_PUBACK_NOT_AUTHORIZED = 0x87U , MQTT_REASON_PUBACK_TOPIC_NAME_INVALID = 0x90U , MQTT_REASON_PUBACK_PACKET_IDENTIFIER_IN_USE = 0x91U , MQTT_REASON_PUBACK_QUOTA_EXCEEDED = 0x97U ,   MQTT_REASON_PUBACK_PAYLOAD_FORMAT_INVALID = 0x99U , MQTT_REASON_PUBREC_SUCCESS = 0x00U , MQTT_REASON_PUBREC_NO_MATCHING_SUBSCRIBERS = 0x10U , MQTT_REASON_PUBREC_UNSPECIFIED_ERROR = 0x80U ,   MQTT_REASON_PUBREC_IMPLEMENTATION_SPECIFIC_ERROR = 0x83U , MQTT_REASON_PUBREC_NOT_AUTHORIZED = 0x87U , MQTT_REASON_PUBREC_TOPIC_NAME_INVALID = 0x90U , MQTT_REASON_PUBREC_PACKET_IDENTIFIER_IN_USE = 0x91U ,   MQTT_REASON_PUBREC_QUOTA_EXCEEDED = 0x97U , MQTT_REASON_PUBREC_PAYLOAD_FORMAT_INVALID = 0x99U , MQTT_REASON_PUBREL_SUCCESS = 0x00U , MQTT_REASON_PUBREL_PACKET_IDENTIFIER_NOT_FOUND = 0x92U ,   MQTT_REASON_PUBCOMP_SUCCESS = 0x00U , MQTT_REASON_PUBCOMP_PACKET_IDENTIFIER_NOT_FOUND = 0x92U , MQTT_REASON_CONNACK_SUCCESS = 0x00U , MQTT_REASON_CONNACK_UNSPECIFIED_ERROR = 0x80U ,   MQTT_REASON_CONNACK_MALFORMED_PACKET = 0x81U , MQTT_REASON_CONNACK_PROTOCOL_ERROR = 0x82U , MQTT_REASON_CONNACK_IMPLEMENTATION_SPECIFIC_ERROR = 0x83U , MQTT_REASON_CONNACK_UNSUPPORTED_PROTOCOL_VERSION = 0x84U ,   MQTT_REASON_CONNACK_CLIENT_IDENTIFIER_NOT_VALID = 0x85U , MQTT_REASON_CONNACK_BAD_USER_NAME_OR_PASSWORD = 0x86U , MQTT_REASON_CONNACK_NOT_AUTHORIZED = 0x87U , MQTT_REASON_CONNACK_SERVER_UNAVAILABLE = 0x88U ,   MQTT_REASON_CONNACK_SERVER_BUSY = 0x89U , MQTT_REASON_CONNACK_BANNED = 0x8AU , MQTT_REASON_CONNACK_BAD_AUTHENTICATION_METHOD = 0x8CU , MQTT_REASON_CONNACK_TOPIC_NAME_INVALID = 0x90U ,   MQTT_REASON_CONNACK_PACKET_TOO_LARGE = 0x95U , MQTT_REASON_CONNACK_QUOTA_EXCEEDED = 0x97U , MQTT_REASON_CONNACK_PAYLOAD_FORMAT_INVALID = 0x99U , MQTT_REASON_CONNACK_RETAIN_NOT_SUPPORTED = 0x9AU ,   MQTT_REASON_CONNACK_QOS_NOT_SUPPORTED = 0x9BU , MQTT_REASON_CONNACK_USE_ANOTHER_SERVER = 0x9CU , MQTT_REASON_CONNACK_SERVER_MOVED = 0x9DU , MQTT_REASON_CONNACK_CONNECTION_RATE_EXCEEDED = 0x9FU ,   MQTT_REASON_SUBACK_GRANTED_QOS0 = 0x00U , MQTT_REASON_SUBACK_GRANTED_QOS1 = 0x01U , MQTT_REASON_SUBACK_GRANTED_QOS2 = 0x02U , MQTT_REASON_SUBACK_UNSPECIFIED_ERROR = 0x80U ,   MQTT_REASON_SUBACK_IMPLEMENTATION_SPECIFIC_ERROR = 0x83U , MQTT_REASON_SUBACK_NOT_AUTHORIZED = 0x87U , MQTT_REASON_SUBACK_TOPIC_FILTER_INVALID = 0x8FU , MQTT_REASON_SUBACK_PACKET_IDENTIFIER_IN_USE = 0x91U ,   MQTT_REASON_SUBACK_QUOTA_EXCEEDED = 0x97U , MQTT_REASON_SUBACK_SHARED_SUBSCRIPTIONS_NOT_SUPPORTED = 0x9EU , MQTT_REASON_SUBACK_SUBSCRIPTION_IDENTIFIERS_NOT_SUPPORTED = 0xA1U , MQTT_REASON_SUBACK_WILDCARD_SUBSCRIPTIONS_NOT_SUPPORTED = 0xA2U ,   MQTT_REASON_UNSUBACK_SUCCESS = 0x00U , MQTT_REASON_UNSUBACK_NO_SUBSCRIPTION_EXISTED = 0x11U , MQTT_REASON_UNSUBACK_UNSPECIFIED_ERROR = 0x80U , MQTT_REASON_UNSUBACK_IMPLEMENTATION_SPECIFIC_ERROR = 0x83U ,   MQTT_REASON_UNSUBACK_NOT_AUTHORIZED = 0x87U , MQTT_REASON_UNSUBACK_TOPIC_FILTER_INVALID = 0x8FU , MQTT_REASON_UNSUBACK_PACKET_IDENTIFIER_IN_USE = 0x91U , MQTT_REASON_DISCONNECT_NORMAL_DISCONNECTION = 0x00U ,   MQTT_REASON_DISCONNECT_DISCONNECT_WITH_WILL_MESSAGE = 0x04U , MQTT_REASON_DISCONNECT_UNSPECIFIED_ERROR = 0x80U , MQTT_REASON_DISCONNECT_MALFORMED_PACKET = 0x81U , MQTT_REASON_DISCONNECT_PROTOCOL_ERROR = 0x82U ,   MQTT_REASON_DISCONNECT_IMPLEMENTATION_SPECIFIC_ERROR = 0x83U , MQTT_REASON_DISCONNECT_NOT_AUTHORIZED = 0x87U , MQTT_REASON_DISCONNECT_SERVER_BUSY = 0x89U , MQTT_REASON_DISCONNECT_SERVER_SHUTTING_DOWN = 0x8BU ,   MQTT_REASON_DISCONNECT_BAD_AUTHENTICATION_METHOD = 0x8CU , MQTT_REASON_DISCONNECT_KEEP_ALIVE_TIMEOUT = 0x8DU , MQTT_REASON_DISCONNECT_SESSION_TAKEN_OVER = 0x8EU , MQTT_REASON_DISCONNECT_TOPIC_FILTER_INVALID = 0x8FU ,   MQTT_REASON_DISCONNECT_TOPIC_NAME_INVALID = 0x90U , MQTT_REASON_DISCONNECT_RECEIVE_MAXIMUM_EXCEEDED = 0x93U , MQTT_REASON_DISCONNECT_TOPIC_ALIAS_INVALID = 0x94U , MQTT_REASON_DISCONNECT_PACKET_TOO_LARGE = 0x95U ,   MQTT_REASON_DISCONNECT_MESSAGE_RATE_TOO_HIGH = 0x96U , MQTT_REASON_DISCONNECT_QUOTA_EXCEEDED = 0x97U , MQTT_REASON_DISCONNECT_ADMINISTRATIVE_ACTION = 0x98U , MQTT_REASON_DISCONNECT_PAYLOAD_FORMAT_INVALID = 0x99U ,   MQTT_REASON_DISCONNECT_RETAIN_NOT_SUPPORTED = 0x9AU , MQTT_REASON_DISCONNECT_QOS_NOT_SUPPORTED = 0x9BU , MQTT_REASON_DISCONNECT_USE_ANOTHER_SERVER = 0x9CU , MQTT_REASON_DISCONNECT_SERVER_MOVED = 0x9DU ,   MQTT_REASON_DISCONNECT_SHARED_SUBSCRIPTIONS_NOT_SUPPORTED = 0x9EU , MQTT_REASON_DISCONNECT_CONNECTION_RATE_EXCEEDED = 0x9FU , MQTT_REASON_DISCONNECT_MAXIMUM_CONNECT_TIME = 0xA0U , MQTT_REASON_DISCONNECT_SUBSCRIPTION_IDENTIFIERS_NOT_SUPPORTED = 0xA1U ,   MQTT_REASON_DISCONNECT_WILDCARD_SUBSCRIPTIONS_NOT_SUPPORTED = 0xA2U , MQTT_INVALID_REASON_CODE = 0xFF }
	MQTT reason codes. More...
enum	MQTTSubscriptionType_t { MQTT_TYPE_SUBSCRIBE , MQTT_TYPE_UNSUBSCRIBE }
	MQTT Subscription packet types. More...

Functions
MQTTStatus_t	MQTT_GetConnectPacketSize (const MQTTConnectInfo_t *pConnectInfo, const MQTTPublishInfo_t *pWillInfo, const MQTTPropBuilder_t *pConnectProperties, const MQTTPropBuilder_t *pWillProperties, uint32_t *pRemainingLength, uint32_t *pPacketSize)
	Get the size and Remaining Length of an MQTT Version 5 CONNECT packet.
MQTTStatus_t	MQTT_SerializeConnect (const MQTTConnectInfo_t *pConnectInfo, const MQTTPublishInfo_t *pWillInfo, const MQTTPropBuilder_t *pConnectProperties, const MQTTPropBuilder_t *pWillProperties, uint32_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
	Serialize an MQTT CONNECT packet in the given fixed buffer pFixedBuffer.
MQTTStatus_t	MQTT_GetSubscribePacketSize (const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, const MQTTPropBuilder_t *pSubscribeProperties, uint32_t *pRemainingLength, uint32_t *pPacketSize, uint32_t maxPacketSize)
	Get packet size and Remaining Length of an MQTT SUBSCRIBE packet.
MQTTStatus_t	MQTT_SerializeSubscribe (const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, const MQTTPropBuilder_t *pSubscribeProperties, uint16_t packetId, uint32_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
	Serialize an MQTT SUBSCRIBE packet in the given buffer.
MQTTStatus_t	MQTT_GetUnsubscribePacketSize (const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, const MQTTPropBuilder_t *pUnsubscribeProperties, uint32_t *pRemainingLength, uint32_t *pPacketSize, uint32_t maxPacketSize)
	Get packet size and Remaining Length of an MQTT UNSUBSCRIBE packet.
MQTTStatus_t	MQTT_SerializeUnsubscribe (const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, const MQTTPropBuilder_t *pUnsubscribeProperties, uint16_t packetId, uint32_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
	Serialize an MQTT UNSUBSCRIBE packet with properties in the given buffer.
MQTTStatus_t	MQTT_GetPublishPacketSize (const MQTTPublishInfo_t *pPublishInfo, const MQTTPropBuilder_t *pPublishProperties, uint32_t *pRemainingLength, uint32_t *pPacketSize, uint32_t maxPacketSize)
	Get the packet size and remaining length of an MQTT PUBLISH packet.
MQTTStatus_t	MQTT_SerializePublish (const MQTTPublishInfo_t *pPublishInfo, const MQTTPropBuilder_t *pPublishProperties, uint16_t packetId, uint32_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
	Serialize an MQTT PUBLISH packet in the given buffer.
MQTTStatus_t	MQTT_SerializePublishHeaderWithoutTopic (const MQTTPublishInfo_t *pPublishInfo, uint32_t remainingLength, uint8_t *pBuffer, size_t *headerSize)
	Serialize an MQTT PUBLISH packet header without the topic string in the given buffer. This function will add the topic string length to the provided buffer. This helps reduce an unnecessary copy of the topic string into the buffer.
MQTTStatus_t	MQTT_SerializePublishHeader (const MQTTPublishInfo_t *pPublishInfo, const MQTTPropBuilder_t *pPublishProperties, uint16_t packetId, uint32_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer, size_t *pHeaderSize)
	Serialize an MQTT PUBLISH packet header in the given buffer.
MQTTStatus_t	MQTT_SerializeAck (const MQTTFixedBuffer_t *pFixedBuffer, uint8_t packetType, uint16_t packetId, const MQTTPropBuilder_t *pAckProperties, const MQTTSuccessFailReasonCode_t *pReasonCode)
	Serialize an MQTT PUBACK, PUBREC, PUBREL, or PUBCOMP into the given buffer.
MQTTStatus_t	MQTT_GetDisconnectPacketSize (const MQTTPropBuilder_t *pDisconnectProperties, uint32_t *pRemainingLength, uint32_t *pPacketSize, uint32_t maxPacketSize, const MQTTSuccessFailReasonCode_t *pReasonCode)
	Get the size of an MQTT DISCONNECT packet.
MQTTStatus_t	MQTT_SerializeDisconnect (const MQTTPropBuilder_t *pDisconnectProperties, const MQTTSuccessFailReasonCode_t *pReasonCode, uint32_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
	Serialize an MQTT DISCONNECT packet into the given buffer.
MQTTStatus_t	MQTT_GetPingreqPacketSize (uint32_t *pPacketSize)
	Get the size of an MQTT PINGREQ packet.
MQTTStatus_t	MQTT_SerializePingreq (const MQTTFixedBuffer_t *pFixedBuffer)
	Serialize an MQTT PINGREQ packet into the given buffer.
MQTTStatus_t	MQTT_DeserializePublish (const MQTTPacketInfo_t *pIncomingPacket, uint16_t *pPacketId, MQTTPublishInfo_t *pPublishInfo, MQTTPropBuilder_t *propBuffer, uint32_t maxPacketSize, uint16_t topicAliasMax)
	Deserialize an MQTT PUBLISH packet.
MQTTStatus_t	MQTT_DeserializeAck (const MQTTPacketInfo_t *pIncomingPacket, uint16_t *pPacketId, MQTTReasonCodeInfo_t *pReasonCode, MQTTPropBuilder_t *pPropBuffer, const MQTTConnectionProperties_t *pConnectProperties)
	Deserialize an MQTT PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, or PINGRESP.
MQTTStatus_t	MQTT_DeserializeConnAck (const MQTTPacketInfo_t *pIncomingPacket, bool *pSessionPresent, MQTTPropBuilder_t *pPropBuffer, MQTTConnectionProperties_t *pConnectProperties)
	Deserialize an MQTT CONNACK.
MQTTStatus_t	MQTT_GetIncomingPacketTypeAndLength (TransportRecv_t readFunc, NetworkContext_t *pNetworkContext, MQTTPacketInfo_t *pIncomingPacket)
	Extract the MQTT packet type and length from incoming packet.
MQTTStatus_t	MQTT_ProcessIncomingPacketTypeAndLength (const uint8_t *pBuffer, const size_t *pIndex, MQTTPacketInfo_t *pIncomingPacket)
	Extract the MQTT packet type and length from incoming packet.
MQTTStatus_t	MQTT_UpdateDuplicatePublishFlag (uint8_t *pHeader, bool set)
	Update the duplicate publish flag within the given header of the publish packet.
MQTTStatus_t	MQTT_InitConnect (MQTTConnectionProperties_t *pConnectProperties)
	Initialize an MQTTConnectionProperties_t.
MQTTStatus_t	MQTTPropertyBuilder_Init (MQTTPropBuilder_t *pPropertyBuilder, uint8_t *buffer, size_t length)
	Initialize the property builder.
MQTTStatus_t	MQTT_ValidateWillProperties (const MQTTPropBuilder_t *pPropertyBuilder)
	Validates the properties specified for WILL Properties in the MQTT CONNECT packet.
MQTTStatus_t	MQTT_ValidateConnectProperties (const MQTTPropBuilder_t *pPropertyBuilder, bool *isRequestProblemInfoSet, uint32_t *pPacketMaxSizeValue)
	Validate the properties in a CONNECT packet.
MQTTStatus_t	MQTTPropAdd_SubscriptionId (MQTTPropBuilder_t *pPropertyBuilder, uint32_t subscriptionId, const uint8_t *pOptionalMqttPacketType)
	Adds a Subscription Identifier property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_UserProp (MQTTPropBuilder_t *pPropertyBuilder, const MQTTUserProperty_t *userProperty, const uint8_t *pOptionalMqttPacketType)
	Adds User Property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_SessionExpiry (MQTTPropBuilder_t *pPropertyBuilder, uint32_t sessionExpiry, const uint8_t *pOptionalMqttPacketType)
	Adds Session Expiry Interval property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_ReceiveMax (MQTTPropBuilder_t *pPropertyBuilder, uint16_t receiveMax, const uint8_t *pOptionalMqttPacketType)
	Adds Receive Maximum property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_MaxPacketSize (MQTTPropBuilder_t *pPropertyBuilder, uint32_t maxPacketSize, const uint8_t *pOptionalMqttPacketType)
	Adds Maximum Packet Size property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_TopicAliasMax (MQTTPropBuilder_t *pPropertyBuilder, uint16_t topicAliasMax, const uint8_t *pOptionalMqttPacketType)
	Adds Topic Alias Maximum property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_RequestRespInfo (MQTTPropBuilder_t *pPropertyBuilder, bool requestResponseInfo, const uint8_t *pOptionalMqttPacketType)
	Adds Request Response Information property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_RequestProbInfo (MQTTPropBuilder_t *pPropertyBuilder, bool requestProblemInfo, const uint8_t *pOptionalMqttPacketType)
	Adds Request Problem Information property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_AuthMethod (MQTTPropBuilder_t *pPropertyBuilder, const char *authMethod, size_t authMethodLength, const uint8_t *pOptionalMqttPacketType)
	Adds Authentication Method property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_AuthData (MQTTPropBuilder_t *pPropertyBuilder, const char *authData, size_t authDataLength, const uint8_t *pOptionalMqttPacketType)
	Adds Authentication Data property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_PayloadFormat (MQTTPropBuilder_t *pPropertyBuilder, bool payloadFormat, const uint8_t *pOptionalMqttPacketType)
	Adds Payload Format Indicator property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_MessageExpiry (MQTTPropBuilder_t *pPropertyBuilder, uint32_t messageExpiry, const uint8_t *pOptionalMqttPacketType)
	Adds Message Expiry Interval property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_WillDelayInterval (MQTTPropBuilder_t *pPropertyBuilder, uint32_t willDelayInterval, const uint8_t *pOptionalMqttPacketType)
	Adds Will Delay Interval property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_TopicAlias (MQTTPropBuilder_t *pPropertyBuilder, uint16_t topicAlias, const uint8_t *pOptionalMqttPacketType)
	Adds Topic Alias property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_ResponseTopic (MQTTPropBuilder_t *pPropertyBuilder, const char *responseTopic, size_t responseTopicLength, const uint8_t *pOptionalMqttPacketType)
	Adds Response Topic property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_CorrelationData (MQTTPropBuilder_t *pPropertyBuilder, const void *pCorrelationData, size_t correlationLength, const uint8_t *pOptionalMqttPacketType)
	Adds Correlation Data property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_ContentType (MQTTPropBuilder_t *pPropertyBuilder, const char *contentType, size_t contentTypeLength, const uint8_t *pOptionalMqttPacketType)
	Adds Content Type property to the MQTT property builder.
MQTTStatus_t	MQTTPropAdd_ReasonString (MQTTPropBuilder_t *pPropertyBuilder, const char *pReasonString, size_t reasonStringLength, const uint8_t *pOptionalMqttPacketType)
	Adds Reason String property to the MQTT property builder.
MQTTStatus_t	MQTT_ValidateSubscribeProperties (bool isSubscriptionIdAvailable, const MQTTPropBuilder_t *propBuilder)
	Validates the properties of a SUBSCRIBE packet.
MQTTStatus_t	updateContextWithConnectProps (const MQTTPropBuilder_t *pPropBuilder, MQTTConnectionProperties_t *pConnectProperties)
	Updates the MQTT context with connect properties from the property builder.
MQTTStatus_t	MQTT_GetNextPropertyType (const MQTTPropBuilder_t *pPropertyBuilder, const size_t *currentIndex, uint8_t *property)
	Get the property type at the current index in the property builder.
MQTTStatus_t	MQTT_SkipNextProperty (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex)
	Skip the next property in the property builder without extracting its value.
MQTTStatus_t	MQTTPropGet_UserProp (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, MQTTUserProperty_t *pUserProperty)
	Get User Property from property builder.
MQTTStatus_t	MQTTPropGet_SessionExpiry (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint32_t *pSessionExpiry)
	Get Session Expiry Interval property from property builder.
MQTTStatus_t	MQTTPropGet_ReceiveMax (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint16_t *pReceiveMax)
	Get Receive Maximum property from property builder.
MQTTStatus_t	MQTTPropGet_MaxQos (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint8_t *pMaxQos)
	Get Maximum QoS property from property builder.
MQTTStatus_t	MQTTPropGet_RetainAvailable (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint8_t *pRetainAvailable)
	Get Retain Available property from property builder.
MQTTStatus_t	MQTTPropGet_MaxPacketSize (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint32_t *pMaxPacketSize)
	Get Maximum Packet Size property from property builder.
MQTTStatus_t	MQTTPropGet_AssignedClientId (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, const char **pClientId, size_t *pClientIdLength)
	Get Assigned Client Identifier property from property builder.
MQTTStatus_t	MQTTPropGet_TopicAliasMax (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint16_t *pTopicAliasMax)
	Get Topic Alias Maximum property from property builder.
MQTTStatus_t	MQTTPropGet_ReasonString (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, const char **pReasonString, size_t *pReasonStringLength)
	Get Reason String property from property builder.
MQTTStatus_t	MQTTPropGet_WildcardId (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint8_t *pWildcardAvailable)
	Get Wildcard Subscription Available property from property builder.
MQTTStatus_t	MQTTPropGet_SubsIdAvailable (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint8_t *pSubsIdAvailable)
	Get Subscription Identifier Available property from property builder.
MQTTStatus_t	MQTTPropGet_SharedSubAvailable (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint8_t *pSharedSubAvailable)
	Get Shared Subscription Available property from property builder.
MQTTStatus_t	MQTTPropGet_ServerKeepAlive (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint16_t *pServerKeepAlive)
	Get Server Keep Alive property from property builder.
MQTTStatus_t	MQTTPropGet_ResponseInfo (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, const char **pResponseInfo, size_t *pResponseInfoLength)
	Get Response Information property from property builder.
MQTTStatus_t	MQTTPropGet_ServerRef (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, const char **pServerRef, size_t *pServerRefLength)
	Get Server Reference property from property builder.
MQTTStatus_t	MQTTPropGet_AuthMethod (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, const char **pAuthMethod, size_t *pAuthMethodLen)
	Get Authentication Method property from property builder.
MQTTStatus_t	MQTTPropGet_AuthData (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, const char **pAuthData, size_t *pAuthDataLen)
	Get Authentication Data property from property builder.
MQTTStatus_t	MQTTPropGet_PayloadFormatIndicator (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint8_t *pPayloadFormat)
	Get Payload Format Indicator property from property builder.
MQTTStatus_t	MQTTPropGet_MessageExpiryInterval (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint32_t *pMessageExpiry)
	Get Message Expiry Interval property from property builder.
MQTTStatus_t	MQTTPropGet_TopicAlias (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint16_t *pTopicAlias)
	Get Topic Alias property from property builder.
MQTTStatus_t	MQTTPropGet_ResponseTopic (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, const char **pResponseTopic, size_t *pResponseTopicLength)
	Get Response Topic property from property builder.
MQTTStatus_t	MQTTPropGet_CorrelationData (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, const char **pCorrelationData, size_t *pCorrelationDataLength)
	Get Correlation Data property from property builder.
MQTTStatus_t	MQTTPropGet_SubscriptionId (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, uint32_t *pSubscriptionId)
	Get Subscription Identifier property from property builder.
MQTTStatus_t	MQTTPropGet_ContentType (const MQTTPropBuilder_t *pPropertyBuilder, size_t *currentIndex, const char **pContentType, size_t *pContentTypeLength)
	Get the Content Type property from the property builder.
MQTTStatus_t	MQTT_ValidatePublishProperties (uint16_t serverTopicAliasMax, const MQTTPropBuilder_t *propBuilder, uint16_t *topicAlias)
	Validates the properties of a PUBLISH packet.
MQTTStatus_t	MQTT_ValidatePublishParams (const MQTTPublishInfo_t *pPublishInfo, uint8_t retainAvailable, uint8_t maxQos, uint16_t topicAlias, uint32_t maxPacketSize)
	Validate the publish parameters present in the given publish structure pPublishInfo.
MQTTStatus_t	MQTT_ValidatePublishAckProperties (const MQTTPropBuilder_t *pPropertyBuilder)
	Validates the properties specified for an MQTT PUBLISH ACK packet.
MQTTStatus_t	MQTT_ValidateUnsubscribeProperties (const MQTTPropBuilder_t *pPropertyBuilder)
	Validates the properties specified for an MQTT UNSUBSCRIBE packet.
MQTTStatus_t	MQTT_GetAckPacketSize (uint32_t *pRemainingLength, uint32_t *pPacketSize, uint32_t maxPacketSize, size_t ackPropertyLength)
	Get the size of an outgoing PUBLISH ACK packet.
MQTTStatus_t	MQTT_ValidateDisconnectProperties (uint32_t connectSessionExpiry, const MQTTPropBuilder_t *pPropertyBuilder)
	Validates the properties specified for an MQTT DISCONNECT packet.
MQTTStatus_t	MQTT_DeserializeDisconnect (const MQTTPacketInfo_t *pPacket, uint32_t maxPacketSize, MQTTReasonCodeInfo_t *pDisconnectInfo, MQTTPropBuilder_t *pPropBuffer)
	Deserialize an MQTT Disconnect packet.

Detailed Description

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

Function Documentation

MQTT_GetConnectPacketSize()

MQTTStatus_t MQTT_GetConnectPacketSize	(	const MQTTConnectInfo_t *	pConnectInfo,
		const MQTTPublishInfo_t *	pWillInfo,
		const MQTTPropBuilder_t *	pConnectProperties,
		const MQTTPropBuilder_t *	pWillProperties,
		uint32_t *	pRemainingLength,
		uint32_t *	pPacketSize
	)

Get the size and Remaining Length of an MQTT Version 5 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, MQTTPublishInfo_t and optional MQTTPropBuilder_t. The size of the MQTTFixedBuffer_t supplied to MQTT_SerializeConnect must be at least pPacketSize. The provided pConnectInfo and pWillInfo are valid for serialization with MQTT_SerializeConnect only if this function returns MQTTSuccess. The remaining length returned in pRemainingLength and the packet size returned in pPacketSize are valid only if this function returns MQTTSuccess.

Parameters

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

Returns

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

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTConnectInfo_t connectInfo = { 0 };
MQTTPublishInfo_t willInfo = { 0 };
MQTTPropBuilder_t connectionProperties = { 0 };
MQTTPropBuilder_t willProperties = { 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 );
 
// Initialize connect properties and will properties, the details are out of scope for this example.
initializeConnectProperties( &connectionProperties );
initializeWillProperties( &willProperties );
 
// Get the size requirement for the connect packet.
status = MQTT_GetConnectPacketSize(
     &connectInfo,
     &willInfo,
     &connectionProperties,
     &willProperties,
     &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,
		const MQTTPropBuilder_t *	pConnectProperties,
		const MQTTPropBuilder_t *	pWillProperties,
		uint32_t	remainingLength,
		const MQTTFixedBuffer_t *	pFixedBuffer
	)

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

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

Parameters

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

Returns

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

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTConnectInfo_t connectInfo = { 0 };
MQTTPublishInfo_t willInfo = { 0 };
MQTTPropBuilder_t connectionProperties = { 0 };
MQTTPropBuilder_t willProperties = { 0 };
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ BUFFER_SIZE ];
size_t remainingLength = 0, packetSize = 0;
 
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = BUFFER_SIZE;
 
// Assume connectInfo, willInfo, and properties are initialized.
// Get the size requirement for the connect packet.
status = MQTT_GetConnectPacketSize(
     &connectInfo, &willInfo, &connectionProperties, &willProperties,
     &remainingLength, &packetSize
);
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
 
// Serialize the connect packet into the fixed buffer.
status = MQTT_SerializeConnect(
     &connectInfo,
     &willInfo,
     &connectionProperties,
     &willProperties,
     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,
		const MQTTPropBuilder_t *	pSubscribeProperties,
		uint32_t *	pRemainingLength,
		uint32_t *	pPacketSize,
		uint32_t	maxPacketSize
	)

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 and MQTTPropBuilder_t (optional subscribe properties). The size of the MQTTFixedBuffer_t supplied to MQTT_SerializeSubscribe must be at least pPacketSize. The provided pSubscriptionList is valid for serialization with MQTT_SerializeSubscribe only if this function returns MQTTSuccess. The remaining length returned in pRemainingLength and the packet size returned in pPacketSize are valid only if this function returns MQTTSuccess.

Parameters

[in]	pSubscriptionList	List of MQTT subscription info.
[in]	subscriptionCount	The number of elements in pSubscriptionList.
[in]	pSubscribeProperties	MQTT SUBSCRIBE properties builder. Pass NULL if not used.
[out]	pRemainingLength	The Remaining Length of the MQTT SUBSCRIBE packet.
[out]	pPacketSize	The total size of the MQTT SUBSCRIBE packet.
[in]	maxPacketSize	Maximum packet size.

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 };
MQTTPropBuilder_t subscribeProperties = { 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 ] );
     subscriptionList[ i ].noLocalOption = false;
     subscriptionList[ i ].retainAsPublishedOption = false;
     subscriptionList[ i ].retainHandlingOption = retainSendOnSub;
}
 
// Initialize subscribe properties (if needed)
initializeSubscribeProperties( &subscribeProperties );
 
// Get the size requirement for the subscribe packet.
status = MQTT_GetSubscribePacketSize(
     &subscriptionList[ 0 ],
     NUMBER_OF_SUBSCRIPTIONS,
     &subscribeProperties,
     &remainingLength,
     &packetSize,
     maxPacketSize
);
 
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,
		const MQTTPropBuilder_t *	pSubscribeProperties,
		uint16_t	packetId,
		uint32_t	remainingLength,
		const MQTTFixedBuffer_t *	pFixedBuffer
	)

Serialize an MQTT SUBSCRIBE packet in the given buffer.

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

Parameters

[in]	pSubscriptionList	List of MQTT subscription info.
[in]	subscriptionCount	The number of elements in pSubscriptionList.
[in]	pSubscribeProperties	MQTT v5.0 properties for the SUBSCRIBE packet. Can be NULL if no properties are needed.
[in]	packetId	packet ID generated by MQTT_GetPacketId.
[in]	remainingLength	Remaining Length provided by MQTT_GetSubscribePacketSize.
[out]	pFixedBuffer	Buffer for packet serialization.

Returns

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

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTSubscribeInfo_t subscriptionList[ NUMBER_OF_SUBSCRIPTIONS ] = { 0 };
MQTTPropBuilder_t subscribeProperties = { 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 and subscribeProperties have been initialized.
Get the subscribe packet size.
status = MQTT_GetSubscribePacketSize(
     &subscriptionList[ 0 ], NUMBER_OF_SUBSCRIPTIONS, &subscribeProperties,
     &remainingLength, &packetSize
);
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
 
// Serialize the subscribe packet into the fixed buffer.
status = MQTT_SerializeSubscribe(
     &subscriptionList[ 0 ],
     NUMBER_OF_SUBSCRIPTIONS,
     &subscribeProperties,
     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,
		const MQTTPropBuilder_t *	pUnsubscribeProperties,
		uint32_t *	pRemainingLength,
		uint32_t *	pPacketSize,
		uint32_t	maxPacketSize
	)

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 and MQTTPropBuilder_t (optional unsubscribe properties). The size of the MQTTFixedBuffer_t supplied to MQTT_SerializeUnsubscribe must be at least pPacketSize. The provided pSubscriptionList is valid for serialization with MQTT_SerializeUnsubscribe only if this function returns MQTTSuccess. The remaining length returned in pRemainingLength and the packet size returned in pPacketSize are valid only if this function returns MQTTSuccess.

Parameters

[in]	pSubscriptionList	List of MQTT subscription info.
[in]	subscriptionCount	The number of elements in pSubscriptionList.
[in]	pUnsubscribeProperties	MQTT UNSUBSCRIBE properties builder. Pass NULL if not used.
[out]	pRemainingLength	The Remaining Length of the MQTT UNSUBSCRIBE packet.
[out]	pPacketSize	The total size of the MQTT UNSUBSCRIBE packet.
[in]	maxPacketSize	Maximum packet size.

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;
MQTTPropBuilder_t unsubscribeProperties = { 0 };
size_t maxPacketSize = 0;
 
// Initialize maxPacketSize. The details are out of scope for this example.
initializeMaxPacketSize( &maxPacketSize );
 
// Initialize the subscribe info. The details are out of scope for this example.
initializeSubscribeInfo( &subscriptionList[ 0 ] );
 
//Initialize the property buffer. The details are out of scope for this example.
initializePropertyBuffer( &unsubscribeProperties );
 
// Get the size requirement for the unsubscribe packet.
status = MQTT_GetUnsubscribePacketSize(
     &subscriptionList[ 0 ],
     NUMBER_OF_SUBSCRIPTIONS,
     &unsubscribeProperties,
     &remainingLength,
     &packetSize,
     maxPacketSize);
 
if( status == MQTTSuccess )
{
     // The unsubscribe packet can now be sent to the broker.
}

MQTT_SerializeUnsubscribe()

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

Serialize an MQTT UNSUBSCRIBE packet with properties in the given buffer.

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

Parameters

[in]	pSubscriptionList	List of MQTT subscription info to unsubscribe from.
[in]	subscriptionCount	The number of elements in pSubscriptionList.
[in]	pUnsubscribeProperties	MQTT 5.0 properties for the UNSUBSCRIBE packet. Can be NULL if no properties are needed.
[in]	packetId	Packet identifier used for the UNSUBSCRIBE packet.
[in]	remainingLength	Remaining Length provided by MQTT_GetUnsubscribePacketSize.
[out]	pFixedBuffer	Buffer where the serialized UNSUBSCRIBE packet will be written.

Returns

MQTTNoMemory if pFixedBuffer is too small to hold the MQTT packet; MQTTBadParameter if any of the parameters are invalid (NULL pSubscriptionList or pFixedBuffer, zero subscriptionCount); MQTTSuccess if the packet was serialized successfully.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTSubscribeInfo_t subscriptionList[2];
MQTTPropBuilder_t unsubscribeProperties;
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[100];
size_t remainingLength = 0, packetSize = 0;
uint16_t packetId = 1;
 
// Initialize the fixed buffer.
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = sizeof( buffer );
 
// Initialize subscription list.
subscriptionList[0].pTopicFilter = "topic/1";
subscriptionList[0].topicFilterLength = strlen("topic/1");
subscriptionList[1].pTopicFilter = "topic/2";
subscriptionList[1].topicFilterLength = strlen("topic/2");
 
// Initialize properties (optional)
 
// Get size requirement for the unsubscribe packet.
status = MQTT_GetUnsubscribePacketSize(
     subscriptionList,
     2,
     &unsubscribeProperties,
     &remainingLength,
     &packetSize
);
 
if( status == MQTTSuccess )
{
     // Serialize unsubscribe packet.
     status = MQTT_SerializeUnsubscribe(
         subscriptionList,
         2,
         &unsubscribeProperties,
         packetId,
         remainingLength,
         &fixedBuffer
     );
}
 
if( status == MQTTSuccess )
{
     // The unsubscribe packet has been serialized successfully.
     // The serialized packet is now ready to be sent to the broker.
}

MQTT_GetPublishPacketSize()

MQTTStatus_t MQTT_GetPublishPacketSize	(	const MQTTPublishInfo_t *	pPublishInfo,
		const MQTTPropBuilder_t *	pPublishProperties,
		uint32_t *	pRemainingLength,
		uint32_t *	pPacketSize,
		uint32_t	maxPacketSize
	)

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

MQTT_ValidatePublishParams should be called with pPublishInfo before invoking this function to validate the publish parameters. This function must be called before sendPublishWithoutCopy in order to get the size of the MQTT PUBLISH packet that is generated from MQTTPublishInfo_t and optional publish properties. The remaining length returned in pRemainingLength and the packet size returned in pPacketSize are valid only if this function returns MQTTSuccess.

Parameters

[in]	pPublishInfo	MQTT PUBLISH packet parameters.
[in]	pPublishProperties	MQTT PUBLISH properties builder. Pass NULL if not used.
[out]	pRemainingLength	The Remaining Length of the MQTT PUBLISH packet.
[out]	pPacketSize	The total size of the MQTT PUBLISH packet.
[in]	maxPacketSize	Maximum packet size allowed by the server.

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 };
MQTTPropBuilder_t publishProperties = { 0 };
uint16_t topicAliasMax;
uint8_t retainAvailable;
uint8_t maxQos;
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!" );
 
// Initialize publish properties (if needed)
initializePublishProperties( &publishProperties );
 
// Validate publish parameters
status = MQTT_ValidatePublishParams(&publishInfo, topicAliasMax, retainAvailable, maxQos);
 
// Get the size requirement for the publish packet.
status = MQTT_GetPublishPacketSize(
     &publishInfo,
     &publishProperties,
     &remainingLength,
     &packetSize,
     maxPacketSize
);
 
if( status == MQTTSuccess )
{
     // The publish packet can now be sent to the broker.
}

MQTT_SerializePublish()

MQTTStatus_t MQTT_SerializePublish	(	const MQTTPublishInfo_t *	pPublishInfo,
		const MQTTPropBuilder_t *	pPublishProperties,
		uint16_t	packetId,
		uint32_t	remainingLength,
		const MQTTFixedBuffer_t *	pFixedBuffer
	)

Serialize an MQTT PUBLISH packet in the given buffer.

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

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

Parameters

[in]	pPublishInfo	MQTT PUBLISH packet parameters.
[in]	pPublishProperties	MQTT v5.0 properties for the PUBLISH packet. Can be NULL if no properties are needed.
[in]	packetId	packet ID generated by MQTT_GetPacketId.
[in]	remainingLength	Remaining Length provided by MQTT_GetPublishPacketSize.
[out]	pFixedBuffer	Buffer for packet serialization.

Returns

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

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPublishInfo_t publishInfo = { 0 };
MQTTPropBuilder_t publishProperties = { 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 and publishProperties have been initialized. Get publish packet size.
status = MQTT_GetPublishPacketSize(
     &publishInfo, &publishProperties, &remainingLength, &packetSize
);
assert( status == MQTTSuccess );
assert( packetSize <= BUFFER_SIZE );
 
// Serialize the publish packet into the fixed buffer.
status = MQTT_SerializePublish(
     &publishInfo,
     &publishProperties,
     packetId,
     remainingLength,
     &fixedBuffer
);
 
if( status == MQTTSuccess )
{
     // The publish packet can now be sent to the broker.
}

MQTT_SerializePublishHeaderWithoutTopic()

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

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

Parameters

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

Returns

MQTTSuccess if the serialization is successful. Otherwise, MQTTBadParameter.

MQTT_SerializePublishHeader()

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

Serialize an MQTT PUBLISH packet header in the given buffer.

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

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

Parameters

[in]	pPublishInfo	MQTT PUBLISH packet parameters.
[in]	pPublishProperties	MQTT v5.0 properties for the PUBLISH packet. Can be NULL if no properties are needed.
[in]	packetId	packet ID generated by MQTT_GetPacketId.
[in]	remainingLength	Remaining Length provided by MQTT_GetPublishPacketSize.
[out]	pFixedBuffer	Buffer for packet serialization.
[out]	pHeaderSize	Size of the serialized MQTT PUBLISH header.

Returns

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

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPublishInfo_t publishInfo = { 0 };
MQTTPropBuilder_t publishProperties ;
MQTTFixedBuffer_t fixedBuffer;
uint8_t buffer[ BUFFER_SIZE ];
size_t remainingLength = 0, packetSize = 0, headerSize = 0;
uint16_t packetId;
int32_t bytesSent;
uint32_t maxPacketSize = pContext->connectionProperties.serverMaxPacketSize;
 
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 and publishProperties have been initialized. Get the publish packet size.
status = MQTT_GetPublishPacketSize(
     &publishInfo, &publishProperties, &remainingLength, &packetSize, maxPacketSize );
assert( status == MQTTSuccess );
// The payload will not be serialized, so the the fixed buffer does not need to hold it.
assert( ( packetSize - publishInfo.payloadLength ) <= BUFFER_SIZE );
 
// Serialize the publish packet header into the fixed buffer.
status = MQTT_SerializePublishHeader(
     &publishInfo,
     &publishProperties,
     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,
		const MQTTPropBuilder_t *	pAckProperties,
		const MQTTSuccessFailReasonCode_t *	pReasonCode
	)

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

Parameters

[out]	pFixedBuffer	Buffer for packet serialization.
[in]	packetType	Byte of the corresponding packet fixed header per the MQTT spec.
[in]	packetId	Packet ID of the publish.
[in]	pAckProperties	Optional properties to be added to the ACK packet.
[in]	pReasonCode	Optional reason code to be added to the ACK packet.

Note

If any properties are provided to the function to be added to the ack packet, then a reason code must be provided as well.

Returns

MQTTBadParameter, MQTTNoMemory, or MQTTSuccess.

Example

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

MQTT_GetDisconnectPacketSize()

MQTTStatus_t MQTT_GetDisconnectPacketSize	(	const MQTTPropBuilder_t *	pDisconnectProperties,
		uint32_t *	pRemainingLength,
		uint32_t *	pPacketSize,
		uint32_t	maxPacketSize,
		const MQTTSuccessFailReasonCode_t *	pReasonCode
	)

Get the size of an MQTT DISCONNECT packet.

Parameters

[in]	pDisconnectProperties	MQTT DISCONNECT properties builder. Pass NULL if not used.
[out]	pRemainingLength	The Remaining Length of the MQTT DISCONNECT packet.
[out]	pPacketSize	The size of the MQTT DISCONNECT packet.
[in]	maxPacketSize	Maximum packet size allowed by the server.
[in]	pReasonCode	The reason code for the disconnect. Pass NULL if not used - only valid if the properties are NULL too.

Returns

MQTTSuccess, or MQTTBadParameter if parameters are invalid

Example

// Variables used in this example.
MQTTStatus_t status;
uint32_t remainingLength = 0;
uint32_t packetSize = 0;
uint32_t maxPacketSize;
MQTTPropBuilder_t disconnectProperties ;
MQTTSuccessFailReasonCode_t reasonCode = MQTT_REASON_DISCONNECT_NORMAL_DISCONNECTION;
 
//Set property builder. The details are out of scope for this example.
initializePropertyBuilder( &disconnectProperties );
 
//Set the parameters.
// Get the size requirement for the disconnect packet.
status = MQTT_GetDisconnectPacketSize( &disconnectProperties, &remainingLength, &packetSize, maxPacketSize, &reasonCode );
 
if( status == MQTTSuccess )
{
     // Send the disconnect packet.
}

MQTT_SerializeDisconnect()

MQTTStatus_t MQTT_SerializeDisconnect	(	const MQTTPropBuilder_t *	pDisconnectProperties,
		const MQTTSuccessFailReasonCode_t *	pReasonCode,
		uint32_t	remainingLength,
		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. This function should only be called after MQTT_GetDisconnectPacketSize to ensure proper buffer sizing.

Parameters

[in]	pDisconnectProperties	MQTT v5.0 properties for the DISCONNECT packet. Can be NULL if no properties are needed.
[in]	pReasonCode	The reason code for the disconnect. For MQTT v5.0, this indicates why the connection is being terminated. If this is NULL, then the pDisconnectProperties must be NULL as well.
[in]	remainingLength	Remaining Length provided by MQTT_GetDisconnectPacketSize.
[out]	pFixedBuffer	Buffer for packet serialization.

Returns

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

Example

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

MQTT_GetPingreqPacketSize()

MQTTStatus_t MQTT_GetPingreqPacketSize

(

uint32_t *

pPacketSize

)

Get the size of an MQTT PINGREQ packet.

Parameters

[out]

pPacketSize

The size of the MQTT PINGREQ packet.

Returns

MQTTSuccess or MQTTBadParameter if pPacketSize is NULL.

Example

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

MQTT_SerializePingreq()

MQTTStatus_t MQTT_SerializePingreq

(

const MQTTFixedBuffer_t *

pFixedBuffer

)

Serialize an MQTT PINGREQ packet into the given buffer.

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

Parameters

[out]

pFixedBuffer

Buffer for packet serialization.

Returns

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

Example

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

MQTT_DeserializePublish()

MQTTStatus_t MQTT_DeserializePublish	(	const MQTTPacketInfo_t *	pIncomingPacket,
		uint16_t *	pPacketId,
		MQTTPublishInfo_t *	pPublishInfo,
		MQTTPropBuilder_t *	propBuffer,
		uint32_t	maxPacketSize,
		uint16_t	topicAliasMax
	)

Deserialize an MQTT PUBLISH packet.

Parameters

[in]	pIncomingPacket	MQTTPacketInfo_t containing the buffer.
[out]	pPacketId	The packet ID obtained from the buffer.
[out]	pPublishInfo	Struct containing information about the publish.
[in]	propBuffer	Buffer to hold the properties.
[in]	maxPacketSize	Maximum packet size.
[in]	topicAliasMax	Maximum topic alias specified in the CONNECT packet.

Returns

• MQTTBadParameter if invalid parameters are passed
• MQTTBadResponse if invalid packet is read
• MQTTSuccess otherwise.

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 };
MQTTPropBuilder_t propBuffer ;
uint16_t packetId;
uint32_t maxPacketSize = pContext->connectionProperties.maxPacketSize;
uint16_t topicAliasMax = pContext->connectionProperties.topicAliasMax;
 
int32_t bytesRecvd;
// A buffer to hold remaining data of the incoming packet.
uint8_t buffer[ BUFFER_SIZE ];
 
// Populate all fields of the incoming packet.
status = MQTT_GetIncomingPacketTypeAndLength(
     socket_recv,
     &networkContext,
     &incomingPacket
);
assert( status == MQTTSuccess );
assert( incomingPacket.remainingLength <= BUFFER_SIZE );
bytesRecvd = socket_recv(
     &networkContext,
     ( void * ) buffer,
     incomingPacket.remainingLength
);
incomingPacket.pRemainingData = buffer;
 
// Deserialize the publish information if the incoming packet is a publish.
if( ( incomingPacket.type & 0xF0 ) == MQTT_PACKET_TYPE_PUBLISH )
{
     status = MQTT_DeserializePublish( &incomingPacket, &packetId, &publishInfo,
                                       &propBuffer, maxPacketSize, topicAliasMax );
     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,
		MQTTReasonCodeInfo_t *	pReasonCode,
		MQTTPropBuilder_t *	pPropBuffer,
		const MQTTConnectionProperties_t *	pConnectProperties
	)

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

Parameters

[in]	pIncomingPacket	MQTTPacketInfo_t containing the buffer.
[out]	pPacketId	The packet ID obtained from the buffer.
[out]	pReasonCode	Struct to store reason code(s) from the acknowledgment packet. Contains the success/failure status of the corresponding request.
[out]	pPropBuffer	Struct to store the deserialized acknowledgment properties. Will contain any MQTT v5.0 properties included in the ack packet.
[in,out]	pConnectProperties	Struct to store the deserialized connect/connack properties.

Returns

Returns one of the following:

• MQTTSuccess if the packet was successfully deserialized
• MQTTBadParameter if invalid parameters are passed
• MQTTServerRefused if the server explicitly rejected the request, either in the CONNACK or a SUBACK.
• MQTTBadResponse if the packet type is invalid or packet parsing fails

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPacketInfo_t incomingPacket;
uint16_t packetId;
MQTTReasonCodeInfo_t reasonCode ; // Can be set to NULL if the incoming packet is CONNACK or PINGRESP
MQTTPropBuilder_t propBuffer; // Can be set to NULL if the user does not want any incoming properties.
MQTTConnectionProperties_t connectionProperties = pContext->connectionProperties;  // Cannot be set to NULL.
 
// 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 a publish ack.
status = MQTT_DeserializeAck( &incomingPacket,
                              &packetId,
                              &reasonCode,
                              &propBuffer,
                              &connectionProperties );
if(status == MQTTSuccess)
{
    // Ack information is now available.
}

MQTT_DeserializeConnAck()

MQTTStatus_t MQTT_DeserializeConnAck	(	const MQTTPacketInfo_t *	pIncomingPacket,
		bool *	pSessionPresent,
		MQTTPropBuilder_t *	pPropBuffer,
		MQTTConnectionProperties_t *	pConnectProperties
	)

Deserialize an MQTT CONNACK.

Parameters

[in]	pIncomingPacket	MQTTPacketInfo_t containing the buffer.
[out]	pSessionPresent	Boolean flag from a CONNACK indicating present session.
[out]	pPropBuffer	Struct to store the deserialized acknowledgment properties. Will contain any MQTT v5.0 properties included in the ack packet.
[in,out]	pConnectProperties	Struct to store the deserialized connect/connack properties. This parameter cannot be NULL.

Returns

MQTTBadParameter, MQTTBadResponse, MQTTServerRefused, or MQTTSuccess.

MQTT_GetIncomingPacketTypeAndLength()

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

Extract the MQTT packet type and length from incoming packet.

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

Parameters

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

Returns

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

Example

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

MQTT_ProcessIncomingPacketTypeAndLength()

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

Extract the MQTT packet type and length from incoming packet.

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

Parameters

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

Returns

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

MQTT_UpdateDuplicatePublishFlag()

MQTTStatus_t MQTT_UpdateDuplicatePublishFlag	(	uint8_t *	pHeader,
		bool	set
	)

Update the duplicate publish flag within the given header of the publish packet.

Parameters

[in]	pHeader	The buffer holding the header content
[in]	set	If true then the flag will be set else cleared

Returns

MQTTSuccess on successful setting of the duplicate flag, MQTTBadParameter for invalid parameters

MQTT_InitConnect()

MQTTStatus_t MQTT_InitConnect

(

MQTTConnectionProperties_t *

pConnectProperties

)

Initialize an MQTTConnectionProperties_t.

Note

This function initializes the connect properties to default values. This function should only be used if using only serializer functions throughout the connection. It is also important to only call this function before sending the connect packet.

Parameters

[in]

pConnectProperties

The connect properties to initialize.

Returns

• MQTTBadParameter if pConnectProperties is NULL.
• MQTTSuccess otherwise.

MQTTPropertyBuilder_Init()

MQTTStatus_t MQTTPropertyBuilder_Init	(	MQTTPropBuilder_t *	pPropertyBuilder,
		uint8_t *	buffer,
		size_t	length
	)

Initialize the property builder.

Parameters

[out]	pPropertyBuilder	Property builder to initialize.
[in]	buffer	Buffer to store the properties.
[in]	length	Length of the buffer.

Returns

• MQTTBadParameter if invalid parameters are passed.
• MQTTSuccess otherwise.

MQTT_ValidateWillProperties()

MQTTStatus_t MQTT_ValidateWillProperties

(

const MQTTPropBuilder_t *

pPropertyBuilder

)

Validates the properties specified for WILL Properties in the MQTT CONNECT packet.

Parameters

[in]

pPropertyBuilder

Pointer to the property builder structure containing will properties.

Returns

Returns one of the following:

• MQTTSuccess , MQTTBadParameter or MQTTBadResponse.

MQTT_ValidateConnectProperties()

MQTTStatus_t MQTT_ValidateConnectProperties	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		bool *	isRequestProblemInfoSet,
		uint32_t *	pPacketMaxSizeValue
	)

Validate the properties in a CONNECT packet.

Parameters

[in]	pPropertyBuilder	Pointer to the property builder structure containing connect packet properties.
[out]	isRequestProblemInfoSet	Whether the request problem info field is set in the properties.
[out]	pPacketMaxSizeValue	Optional pointer to get the Maximum Packet Size from the properties. If not required, NULL can be passed.

Returns

Returns one of the following:

• MQTTSuccess , MQTTBadParameter or MQTTBadResponse.

MQTTPropAdd_SubscriptionId()

MQTTStatus_t MQTTPropAdd_SubscriptionId	(	MQTTPropBuilder_t *	pPropertyBuilder,
		uint32_t	subscriptionId,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds a Subscription Identifier property to the MQTT property builder.

This function adds a Subscription Identifier property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure where the Subscription Identifier will be added. Must not be NULL.
[in]	subscriptionId	The Subscription Identifier value to be added. Must be greater than 0.
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Subscription Identifier was successfully added
• MQTTBadParameter if pPropertyBuilder is NULL or subscriptionId is 0
• MQTTNoMemory if the property builder has insufficient space

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPropBuilder_t propertyBuilder ; // Assume this is initialized properly
uint32_t subscriptionId = 12345;
 
// Add Subscription Identifier to property builder
status = MQTTPropAdd_SubscriptionId(&propertyBuilder, subscriptionId, &(uint8_t){ MQTT_PACKET_TYPE_SUBSCRIBE });
 
if(status == MQTTSuccess)
{
    // Subscription Identifier successfully added
}

Note

This property is only valid for MQTT v5.0 and above.

The Subscription Identifier can be used in SUBSCRIBE packets and will be returned in matched PUBLISH packets.

MQTTPropAdd_UserProp()

MQTTStatus_t MQTTPropAdd_UserProp	(	MQTTPropBuilder_t *	pPropertyBuilder,
		const MQTTUserProperty_t *	userProperty,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds User Property to the MQTT property builder.

This function adds User Property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	userProperty	The User Property to be added.
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Subscription Identifier was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_SessionExpiry()

MQTTStatus_t MQTTPropAdd_SessionExpiry	(	MQTTPropBuilder_t *	pPropertyBuilder,
		uint32_t	sessionExpiry,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Session Expiry Interval property to the MQTT property builder.

This function adds Session Expiry Interval property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	sessionExpiry	The Session Expiry Interval in seconds.
[in]	pOptionalMqttPacketType	Optional MQTT packet type for validation. Can be NULL to skip packet type validation.

Returns

Returns one of the following:

• MQTTSuccess if the Session Expiry Interval was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_ReceiveMax()

MQTTStatus_t MQTTPropAdd_ReceiveMax	(	MQTTPropBuilder_t *	pPropertyBuilder,
		uint16_t	receiveMax,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Receive Maximum property to the MQTT property builder.

This function adds Receive Maximum property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	receiveMax	The maximum number of QoS 1 and QoS 2 messages allowed to be received simultaneously.
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Receive Maximum was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_MaxPacketSize()

MQTTStatus_t MQTTPropAdd_MaxPacketSize	(	MQTTPropBuilder_t *	pPropertyBuilder,
		uint32_t	maxPacketSize,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Maximum Packet Size property to the MQTT property builder.

This function adds Maximum Packet Size property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	maxPacketSize	The maximum packet size the client is willing to accept.
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Maximum Packet Size was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_TopicAliasMax()

MQTTStatus_t MQTTPropAdd_TopicAliasMax	(	MQTTPropBuilder_t *	pPropertyBuilder,
		uint16_t	topicAliasMax,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Topic Alias Maximum property to the MQTT property builder.

This function adds Topic Alias Maximum property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	topicAliasMax	The maximum value of topic alias accepted by the client.
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Topic Alias Maximum was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_RequestRespInfo()

MQTTStatus_t MQTTPropAdd_RequestRespInfo	(	MQTTPropBuilder_t *	pPropertyBuilder,
		bool	requestResponseInfo,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Request Response Information property to the MQTT property builder.

This function adds Request Response Information property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	requestResponseInfo	Boolean indicating whether response information is requested.
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Request Response Information was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_RequestProbInfo()

MQTTStatus_t MQTTPropAdd_RequestProbInfo	(	MQTTPropBuilder_t *	pPropertyBuilder,
		bool	requestProblemInfo,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Request Problem Information property to the MQTT property builder.

This function adds Request Problem Information property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	requestProblemInfo	Boolean indicating whether problem information is requested.
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Request Problem Information was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_AuthMethod()

MQTTStatus_t MQTTPropAdd_AuthMethod	(	MQTTPropBuilder_t *	pPropertyBuilder,
		const char *	authMethod,
		size_t	authMethodLength,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Authentication Method property to the MQTT property builder.

This function adds Authentication Method property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	authMethod	Pointer to the authentication method string.
[in]	authMethodLength	Length of the authentication method string (must be less than 65536).
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Authentication Method was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_AuthData()

MQTTStatus_t MQTTPropAdd_AuthData	(	MQTTPropBuilder_t *	pPropertyBuilder,
		const char *	authData,
		size_t	authDataLength,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Authentication Data property to the MQTT property builder.

This function adds Authentication Data property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	authData	Pointer to the authentication data.
[in]	authDataLength	Length of the authentication data (must be less than 65536).
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Authentication Data was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_PayloadFormat()

MQTTStatus_t MQTTPropAdd_PayloadFormat	(	MQTTPropBuilder_t *	pPropertyBuilder,
		bool	payloadFormat,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Payload Format Indicator property to the MQTT property builder.

This function adds Payload Format Indicator property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	payloadFormat	Boolean indicating the payload format (true for UTF-8, false for unspecified bytes).
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Payload Format Indicator was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_MessageExpiry()

MQTTStatus_t MQTTPropAdd_MessageExpiry	(	MQTTPropBuilder_t *	pPropertyBuilder,
		uint32_t	messageExpiry,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Message Expiry Interval property to the MQTT property builder.

This function adds Message Expiry Interval property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	messageExpiry	The message expiry interval in seconds.
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Message Expiry Interval was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_WillDelayInterval()

MQTTStatus_t MQTTPropAdd_WillDelayInterval	(	MQTTPropBuilder_t *	pPropertyBuilder,
		uint32_t	willDelayInterval,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Will Delay Interval property to the MQTT property builder.

This function adds Message Expiry Interval property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	willDelayInterval	Will Delay Interval in seconds.
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Message Expiry Interval was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_TopicAlias()

MQTTStatus_t MQTTPropAdd_TopicAlias	(	MQTTPropBuilder_t *	pPropertyBuilder,
		uint16_t	topicAlias,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Topic Alias property to the MQTT property builder.

This function adds Topic Alias property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	topicAlias	The topic alias value.
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Topic Alias was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_ResponseTopic()

MQTTStatus_t MQTTPropAdd_ResponseTopic	(	MQTTPropBuilder_t *	pPropertyBuilder,
		const char *	responseTopic,
		size_t	responseTopicLength,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Response Topic property to the MQTT property builder.

This function adds Response Topic property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	responseTopic	Pointer to the response topic string.
[in]	responseTopicLength	Length of the response topic string (must be less than 65536).
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Response Topic was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_CorrelationData()

MQTTStatus_t MQTTPropAdd_CorrelationData	(	MQTTPropBuilder_t *	pPropertyBuilder,
		const void *	pCorrelationData,
		size_t	correlationLength,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Correlation Data property to the MQTT property builder.

This function adds Correlation Data property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	pCorrelationData	Pointer to the correlation data.
[in]	correlationLength	Length of the correlation data (must be less than 65536).
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Correlation Data was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_ContentType()

MQTTStatus_t MQTTPropAdd_ContentType	(	MQTTPropBuilder_t *	pPropertyBuilder,
		const char *	contentType,
		size_t	contentTypeLength,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Content Type property to the MQTT property builder.

This function adds Content Type property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	contentType	Pointer to the content type string.
[in]	contentTypeLength	Length of the content type string (must be less than 65536).
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Content Type was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTTPropAdd_ReasonString()

MQTTStatus_t MQTTPropAdd_ReasonString	(	MQTTPropBuilder_t *	pPropertyBuilder,
		const char *	pReasonString,
		size_t	reasonStringLength,
		const uint8_t *	pOptionalMqttPacketType
	)

Adds Reason String property to the MQTT property builder.

This function adds Reason String property to the property builder.

Parameters

[out]	pPropertyBuilder	Pointer to the property builder structure.
[in]	pReasonString	Pointer to the reason string.
[in]	reasonStringLength	Length of the reason string (must be less than 65536).
[in]	pOptionalMqttPacketType	Optional MQTT packet type for which the property is being added. The function will check whether the given property can be added to the packet type if it is provided.

Returns

Returns one of the following:

• MQTTSuccess if the Reason String was successfully added
• MQTTBadParameter if an invalid parameter is passed
• MQTTNoMemory if the property builder has insufficient space

MQTT_ValidateSubscribeProperties()

MQTTStatus_t MQTT_ValidateSubscribeProperties	(	bool	isSubscriptionIdAvailable,
		const MQTTPropBuilder_t *	propBuilder
	)

Validates the properties of a SUBSCRIBE packet.

This function validates the properties in the property builder for a SUBSCRIBE packet.

Parameters

[in]	isSubscriptionIdAvailable	Boolean indicating if subscription identifiers are supported.
[in]	propBuilder	Pointer to the property builder structure.

Returns

Returns one of the following:

• MQTTSuccess if the properties are valid
• MQTTBadParameter if an invalid parameter is passed

updateContextWithConnectProps()

MQTTStatus_t updateContextWithConnectProps	(	const MQTTPropBuilder_t *	pPropBuilder,
		MQTTConnectionProperties_t *	pConnectProperties
	)

Updates the MQTT context with connect properties from the property builder.

This function processes the property builder and updates the connect properties in the MQTT context. It handles the conversion and validation of properties from the property builder to the connect properties structure.

Parameters

[in]	pPropBuilder	Pointer to the property builder containing MQTT properties. Must not be NULL.
[out]	pConnectProperties	Pointer to the connection properties structure to be updated. Must not be NULL.

Returns

Returns one of the following:

• MQTTSuccess if properties were successfully updated
• MQTTBadParameter, MQTTBadResponse if invalid parameters are passed

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPropBuilder_t propBuilder = { 0 };
MQTTConnectionProperties_t connectionProperties = { 0 };
 
// Initialize property builder with desired properties
// ...
 
// Update connect properties
status = updateContextWithConnectProps( &propBuilder, &connectionProperties );
 
if(status == MQTTSuccess)
{
    // Properties successfully updated in the context
}

This value shall get overwritten if the server sends a sessionExpiry in the CONNACK.

MQTT_GetNextPropertyType()

MQTTStatus_t MQTT_GetNextPropertyType	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		const size_t *	currentIndex,
		uint8_t *	property
	)

Get the property type at the current index in the property builder.

This function retrieves the property identifier byte at the specified index and validates that it is a recognized MQTT v5 property type. The index is not advanced by this function - use the appropriate MQTTPropGet_* function to retrieve the property value and advance the index.

Warning

When iterating through properties in a loop, every property returned by this function MUST be consumed by either calling the corresponding MQTTPropGet_* function or MQTT_SkipNextProperty. Failing to do so will leave the index unchanged, causing an infinite loop.

Parameters

[in]	pPropertyBuilder	Property builder containing the properties.
[in]	currentIndex	Current index in the property builder buffer.
[out]	property	Pointer to store the property type identifier.

Returns

MQTTSuccess if property type is retrieved and valid; MQTTBadParameter if invalid parameters are passed, index is out of bounds, or the property type is not recognized.

MQTT_SkipNextProperty()

MQTTStatus_t MQTT_SkipNextProperty	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex
	)

Skip the next property in the property builder without extracting its value.

This function advances the current index past the property at the current position in the property buffer. It validates the property ID and ensures the property data is within bounds, but does not extract or return the property value. This is useful for iterating through properties when only specific properties need to be extracted.

Warning

When iterating through properties with MQTT_GetNextPropertyType, you MUST call this function for any property you do not handle with a MQTTPropGet_* function. Without this, the index will not advance past the unhandled property, resulting in an infinite loop.

Parameters

[in]	pPropertyBuilder	Pointer to the property builder containing the properties.
[in,out]	currentIndex	Pointer to the current index in the property buffer. On success, updated to point to the next property.

Returns

MQTTSuccess if the property is successfully skipped; MQTTBadParameter if parameters are invalid, property ID is unknown, or the property data extends beyond the buffer bounds; MQTTEndOfProperties if currentIndex is already at or past the end of properties.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPropBuilder_t propertyBuilder = { 0 };
size_t currentIndex = 0;
uint8_t propertyType;
 
// Initialize property builder with received properties
// (initialization details out of scope for this example)
initializePropertyBuilder( &propertyBuilder );
 
// Iterate through all properties
while( currentIndex < propertyBuilder.currentIndex )
{
    // Get the property type at current position
    status = MQTT_GetNextPropertyType( &propertyBuilder, &currentIndex, &propertyType );
 
    if( status != MQTTSuccess )
    {
        break;
    }
 
    // Only extract user properties, skip all others
    if( propertyType == MQTT_USER_PROPERTY_ID )
    {
        MQTTUserProperty_t userProp;
        status = MQTTPropGet_UserProp( &propertyBuilder, &currentIndex, &userProp );
        // Process user property...
    }
    else
    {
        // Skip this property
        status = MQTT_SkipNextProperty( &propertyBuilder, &currentIndex );
    }
 
    if( status != MQTTSuccess )
    {
        break;
    }
}

MQTTPropGet_UserProp()

MQTTStatus_t MQTTPropGet_UserProp	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		MQTTUserProperty_t *	pUserProperty
	)

Get User Property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pUserProperty	Pointer to store the user property key-value pair.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_SessionExpiry()

MQTTStatus_t MQTTPropGet_SessionExpiry	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint32_t *	pSessionExpiry
	)

Get Session Expiry Interval property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pSessionExpiry	Pointer to store the session expiry interval in seconds.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_ReceiveMax()

MQTTStatus_t MQTTPropGet_ReceiveMax	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint16_t *	pReceiveMax
	)

Get Receive Maximum property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pReceiveMax	Pointer to store the receive maximum value.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_MaxQos()

MQTTStatus_t MQTTPropGet_MaxQos	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint8_t *	pMaxQos
	)

Get Maximum QoS property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pMaxQos	Pointer to store the maximum QoS level (0, 1, or 2).

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_RetainAvailable()

MQTTStatus_t MQTTPropGet_RetainAvailable	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint8_t *	pRetainAvailable
	)

Get Retain Available property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pRetainAvailable	Pointer to store the retain available flag (0 or 1).

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_MaxPacketSize()

MQTTStatus_t MQTTPropGet_MaxPacketSize	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint32_t *	pMaxPacketSize
	)

Get Maximum Packet Size property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pMaxPacketSize	Pointer to store the maximum packet size in bytes.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_AssignedClientId()

MQTTStatus_t MQTTPropGet_AssignedClientId	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		const char **	pClientId,
		size_t *	pClientIdLength
	)

Get Assigned Client Identifier property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pClientId	Pointer to store the assigned client identifier string.
[out]	pClientIdLength	Pointer to store the client identifier length.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_TopicAliasMax()

MQTTStatus_t MQTTPropGet_TopicAliasMax	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint16_t *	pTopicAliasMax
	)

Get Topic Alias Maximum property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pTopicAliasMax	Pointer to store the topic alias maximum value.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_ReasonString()

MQTTStatus_t MQTTPropGet_ReasonString	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		const char **	pReasonString,
		size_t *	pReasonStringLength
	)

Get Reason String property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pReasonString	Pointer to store the reason string.
[out]	pReasonStringLength	Pointer to store the reason string length.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_WildcardId()

MQTTStatus_t MQTTPropGet_WildcardId	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint8_t *	pWildcardAvailable
	)

Get Wildcard Subscription Available property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pWildcardAvailable	Pointer to store the wildcard subscription available flag (0 or 1).

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_SubsIdAvailable()

MQTTStatus_t MQTTPropGet_SubsIdAvailable	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint8_t *	pSubsIdAvailable
	)

Get Subscription Identifier Available property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pSubsIdAvailable	Pointer to store the subscription identifier available flag (0 or 1).

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_SharedSubAvailable()

MQTTStatus_t MQTTPropGet_SharedSubAvailable	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint8_t *	pSharedSubAvailable
	)

Get Shared Subscription Available property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pSharedSubAvailable	Pointer to store the shared subscription available flag (0 or 1).

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_ServerKeepAlive()

MQTTStatus_t MQTTPropGet_ServerKeepAlive	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint16_t *	pServerKeepAlive
	)

Get Server Keep Alive property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pServerKeepAlive	Pointer to store the server keep alive interval in seconds.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_ResponseInfo()

MQTTStatus_t MQTTPropGet_ResponseInfo	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		const char **	pResponseInfo,
		size_t *	pResponseInfoLength
	)

Get Response Information property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pResponseInfo	Pointer to store the response information string.
[out]	pResponseInfoLength	Pointer to store the response information length.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_ServerRef()

MQTTStatus_t MQTTPropGet_ServerRef	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		const char **	pServerRef,
		size_t *	pServerRefLength
	)

Get Server Reference property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pServerRef	Pointer to store the server reference string.
[out]	pServerRefLength	Pointer to store the server reference length.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_AuthMethod()

MQTTStatus_t MQTTPropGet_AuthMethod	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		const char **	pAuthMethod,
		size_t *	pAuthMethodLen
	)

Get Authentication Method property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pAuthMethod	Pointer to store the authentication method string.
[out]	pAuthMethodLen	Pointer to store the authentication method length.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_AuthData()

MQTTStatus_t MQTTPropGet_AuthData	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		const char **	pAuthData,
		size_t *	pAuthDataLen
	)

Get Authentication Data property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pAuthData	Pointer to store the authentication data.
[out]	pAuthDataLen	Pointer to store the authentication data length.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_PayloadFormatIndicator()

MQTTStatus_t MQTTPropGet_PayloadFormatIndicator	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint8_t *	pPayloadFormat
	)

Get Payload Format Indicator property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pPayloadFormat	Pointer to store the payload format indicator (0=unspecified, 1=UTF-8).

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_MessageExpiryInterval()

MQTTStatus_t MQTTPropGet_MessageExpiryInterval	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint32_t *	pMessageExpiry
	)

Get Message Expiry Interval property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pMessageExpiry	Pointer to store the message expiry interval in seconds.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_TopicAlias()

MQTTStatus_t MQTTPropGet_TopicAlias	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint16_t *	pTopicAlias
	)

Get Topic Alias property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pTopicAlias	Pointer to store the topic alias value.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_ResponseTopic()

MQTTStatus_t MQTTPropGet_ResponseTopic	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		const char **	pResponseTopic,
		size_t *	pResponseTopicLength
	)

Get Response Topic property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pResponseTopic	Pointer to store the response topic string.
[out]	pResponseTopicLength	Pointer to store the response topic length.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_CorrelationData()

MQTTStatus_t MQTTPropGet_CorrelationData	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		const char **	pCorrelationData,
		size_t *	pCorrelationDataLength
	)

Get Correlation Data property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pCorrelationData	Pointer to store the correlation data.
[out]	pCorrelationDataLength	Pointer to store the correlation data length.

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_SubscriptionId()

MQTTStatus_t MQTTPropGet_SubscriptionId	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		uint32_t *	pSubscriptionId
	)

Get Subscription Identifier property from property builder.

Parameters

[in]	pPropertyBuilder	Property builder to get property from.
[in,out]	currentIndex	Current index in the property builder buffer. Updated to next property on success.
[out]	pSubscriptionId	Pointer to store the subscription identifier (variable byte integer).

Returns

MQTTSuccess if property is retrieved successfully; MQTTBadParameter if invalid parameters are passed.

MQTTPropGet_ContentType()

MQTTStatus_t MQTTPropGet_ContentType	(	const MQTTPropBuilder_t *	pPropertyBuilder,
		size_t *	currentIndex,
		const char **	pContentType,
		size_t *	pContentTypeLength
	)

Get the Content Type property from the property builder.

This function extracts the Content Type property value from the property builder at the specified index. The Content Type property describes the content of the Application Message.

Parameters

[in]	pPropertyBuilder	Pointer to the property builder containing the properties.
[in,out]	currentIndex	Pointer to the current index in the property buffer. Updated to point past the property on success.
[out]	pContentType	Pointer to store the extracted Content Type string.
[out]	pContentTypeLength	Pointer to store the length of the Content Type string.

Returns

MQTTSuccess if the property is successfully extracted; MQTTBadParameter if parameters are invalid or property is not Content Type.

MQTT_ValidatePublishProperties()

MQTTStatus_t MQTT_ValidatePublishProperties	(	uint16_t	serverTopicAliasMax,
		const MQTTPropBuilder_t *	propBuilder,
		uint16_t *	topicAlias
	)

Validates the properties of a PUBLISH packet.

This function validates the properties in the property builder for a PUBLISH packet.

Parameters

[in]	serverTopicAliasMax	Maximum topic alias value allowed by the server.
[in]	propBuilder	Pointer to the property builder structure.
[out]	topicAlias	Pointer to store the topic alias value if present.

Returns

Returns one of the following:

• MQTTSuccess if the properties are valid
• MQTTBadParameter if invalid parameters are passed
• MQTTBadResponse if an invalid packet is read

MQTT_ValidatePublishParams()

MQTTStatus_t MQTT_ValidatePublishParams	(	const MQTTPublishInfo_t *	pPublishInfo,
		uint8_t	retainAvailable,
		uint8_t	maxQos,
		uint16_t	topicAlias,
		uint32_t	maxPacketSize
	)

Validate the publish parameters present in the given publish structure pPublishInfo.

This function must be called before MQTT_GetPublishPacketSize in order to validate the publish parameters.

Parameters

[in]	pPublishInfo	MQTT publish packet parameters.
[in]	retainAvailable	Whether server allows retain or not.
[in]	maxQos	Maximum QoS supported by the server.
[in]	topicAlias	Topic alias in the PUBLISH packet.
[in]	maxPacketSize	Maximum packet size allowed by the server.

Returns

MQTTBadParameter if invalid parameters are passed; MQTTSuccess otherwise.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPublishInfo_t publishInfo = {0};
uint16_t topicAlias;
uint8_t retainAvailable;
uint8_t maxQos;
// Set in the CONNACK packet.
uint32_t maxPacketSize ;
 
//Set the publish info parameters.
 
//Validate the publish packet
status = MQTT_ValidatePublishParams(&publishInfo, retainAvailable, maxQos, topicAlias, maxPacketSize);
 
if( status == MQTTSuccess )
{
     // Get the packet size and serialize the publish packet.
}

MQTT_ValidatePublishAckProperties()

MQTTStatus_t MQTT_ValidatePublishAckProperties

(

const MQTTPropBuilder_t *

pPropertyBuilder

)

Validates the properties specified for an MQTT PUBLISH ACK packet.

Parameters

[in]

pPropertyBuilder

Pointer to the property builder structure containing unsubscribe properties.

Returns

Returns one of the following:

• MQTTSuccess , MQTTBadParameter or MQTTBadResponse.

MQTT_ValidateUnsubscribeProperties()

MQTTStatus_t MQTT_ValidateUnsubscribeProperties

(

const MQTTPropBuilder_t *

pPropertyBuilder

)

Validates the properties specified for an MQTT UNSUBSCRIBE packet.

Parameters

[in]

pPropertyBuilder

Pointer to the property builder structure containing unsubscribe properties.

Returns

Returns one of the following:

• MQTTSuccess , MQTTBadParameter or MQTTBadResponse.

MQTT_GetAckPacketSize()

MQTTStatus_t MQTT_GetAckPacketSize	(	uint32_t *	pRemainingLength,
		uint32_t *	pPacketSize,
		uint32_t	maxPacketSize,
		size_t	ackPropertyLength
	)

Get the size of an outgoing PUBLISH ACK packet.

Note

If no reason code is sent and property length is zero then MQTT_SerializeAck can be used directly.

Parameters

[out]	pRemainingLength	The remaining length of the packet to be serialized.
[out]	pPacketSize	The size of the packet to be serialized.
[in]	maxPacketSize	Maximum packet size allowed by the server.
[in]	ackPropertyLength	The length of the properties.

Returns

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 ];
MQTTAckInfo_t  ackInfo;
uint16_t sessionExpiry;
 
fixedBuffer.pBuffer = buffer;
fixedBuffer.size = BUFFER_SIZE;
// Variables used in this example.
MQTTStatus_t status;
size_t remainingLength =0;
size_t packetSize = 0;
size_t ackPropertyLength = 0;
uint32_t maxPacketSize;
//set the parameters.
// Get the size requirement for the ack packet.
status = MQTT_GetAckPacketSize(&remainingLength,&packetSize,maxPacketSize, ackPropertyLength);
}

MQTT_ValidateDisconnectProperties()

MQTTStatus_t MQTT_ValidateDisconnectProperties	(	uint32_t	connectSessionExpiry,
		const MQTTPropBuilder_t *	pPropertyBuilder
	)

Validates the properties specified for an MQTT DISCONNECT packet.

Parameters

[in]	connectSessionExpiry	The session expiry interval that was specified in the CONNECT packet. Used to validate that the DISCONNECT session expiry is not non-zero while connectSessionExpiry is zero.
[in]	pPropertyBuilder	Pointer to the property builder structure containing subscribe properties.

Returns

Returns one of the following:

• MQTTSuccess , MQTTBadParameter or MQTTBadResponse.

MQTT_DeserializeDisconnect()

MQTTStatus_t MQTT_DeserializeDisconnect	(	const MQTTPacketInfo_t *	pPacket,
		uint32_t	maxPacketSize,
		MQTTReasonCodeInfo_t *	pDisconnectInfo,
		MQTTPropBuilder_t *	pPropBuffer
	)

Deserialize an MQTT Disconnect packet.

Parameters

[in]	pPacket	MQTTPacketInfo_t containing the buffer.
[in]	maxPacketSize	Maximum packet size allowed by the client.
[out]	pDisconnectInfo	Struct containing disconnect reason code
[out]	pPropBuffer	MQTTPropBuilder_t to store the deserialized properties.

Returns

MQTTBadParameter, MQTTBadResponse or MQTTSuccess.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTPacketInfo_t incomingPacket;
MQTTReasonCodeInfo_t disconnectInfo;
uint32_t maxPacketSize;
MQTTPropBuilder_t propBuffer; // Assume this is initialized properly
// Receive an incoming packet and populate all fields. The details are out of scope
// for this example.
receiveIncomingPacket( &incomingPacket );
 
// Deserialize disconnect information.
if( ( incomingPacket.type) == MQTT_PACKET_TYPE_DISCONNECT )
{
     status = MQTT_DeserializeDisconnect(&incomingPacket,
                                          maxPacketSize,
                                          &disconnectInfo,
                                          &propBuffer);
     if( status == MQTTSuccess )
     {
         // Disconnect information is available.
     }
}