Internal header of MQTT library. This header should not be included in typical application code. More...

#include "iot_config.h"
#include "iot_linear_containers.h"
#include "iot_mqtt.h"
#include "iot_taskpool.h"
#include "iot_logging_setup.h"
#include "iot_static_memory.h"

Data Structures
struct	_mqttOperation_t
	Internal structure representing a single MQTT operation, such as CONNECT, SUBSCRIBE, PUBLISH, etc. More...

struct	_mqttConnection_t
	Represents an MQTT connection. More...

struct	_mqttSubscription_t
	Represents a subscription stored in an MQTT connection. More...

struct	_mqttPacket_t
	Represents an MQTT packet received from the network. More...

Macros
#define	IotMqtt_Assert(expression)
	Assertion macro for the MQTT library. More...

#define	IotMqtt_MallocMessage Iot_MallocMessageBuffer
	Allocate memory for an MQTT packet. This function should have the same signature as malloc.

#define	IotMqtt_FreeMessage Iot_FreeMessageBuffer
	Free an MQTT packet. This function should have the same signature as free.

#define	MQTT_SERVER_MAX_CLIENTID_LENGTH ( ( uint16_t ) 23 )
	Optional maximum length of client identifier specified by MQTT 3.1.1.

#define	MQTT_SERVER_MAX_PUBLISH_PAYLOAD_LENGTH ( ( size_t ) ( 268435456 ) )
	Maximum publish payload length supported by MQTT 3.1.1.

#define	MQTT_SERVER_MAX_LWT_PAYLOAD_LENGTH ( ( size_t ) UINT16_MAX )
	Maximum LWT payload length supported by MQTT 3.1.1.

#define	AWS_IOT_MQTT_SERVER_MAX_CLIENTID_LENGTH ( ( uint16_t ) 128 )
	Maximum length of client identifier accepted by AWS IoT.

#define	AWS_IOT_MQTT_SERVER_MAX_TOPIC_LENGTH ( ( uint16_t ) 256 )
	Maximum length of topic names or filters accepted by AWS IoT.

#define	AWS_IOT_MQTT_SERVER_MAX_TOPIC_FILTERS_PER_SUBSCRIBE ( ( size_t ) 8 )
	Maximum number of topic filters in a single SUBSCRIBE packet.

#define	AWS_IOT_MQTT_SERVER_MAX_PUBLISH_PAYLOAD_LENGTH ( ( size_t ) ( 131072 ) )
	Maximum publish payload length accepted by AWS IoT.

#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 (server-to-client).

#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_REMAINING_LENGTH_INVALID ( ( size_t ) 268435456 )
	A value that represents an invalid remaining length. More...

#define	MQTT_INTERNAL_FLAG_BLOCK_ON_SEND ( 0x80000000U )
	When this flag is passed, MQTT functions will execute jobs on the calling thread, bypassing the task pool. More...

#define	MQTT_REMOVE_ALL_SUBSCRIPTIONS ( -1 )
	When calling _IotMqtt_RemoveSubscriptionByPacket, use this value for `order` to delete all subscriptions for the packet. More...

#define	SERIALIZER_OVERRIDE_SELECTOR(funcType_t, funcName, defaultFunc, serializerMember)
	Utility macro for creating serializer override selector functions. More...

Functions
void *	IotMqtt_MallocConnection (size_t size)
	Allocate an _mqttConnection_t. This function should have the same signature as malloc.

void	IotMqtt_FreeConnection (void *ptr)
	Free an _mqttConnection_t. This function should have the same signature as free.

void *	IotMqtt_MallocOperation (size_t size)
	Allocate an _mqttOperation_t. This function should have the same signature as malloc.

void	IotMqtt_FreeOperation (void *ptr)
	Free an _mqttOperation_t. This function should have the same signature as free.

void *	IotMqtt_MallocSubscription (size_t size)
	Allocate an _mqttSubscription_t. This function should have the same signature as malloc.

void	IotMqtt_FreeSubscription (void *ptr)
	Free an _mqttSubscription_t. This function should have the same signature as free.

bool	_IotMqtt_ValidateConnect (const IotMqttConnectInfo_t *pConnectInfo)
	Check that an IotMqttConnectInfo_t is valid. More...

bool	_IotMqtt_ValidatePublish (bool awsIotMqttMode, const IotMqttPublishInfo_t pPublishInfo, uint32_t flags, const IotMqttCallbackInfo_t pCallbackInfo, const IotMqttOperation_t *const pPublishOperation)
	Check that parameters for an MQTT PUBLISH are valid. More...

bool	_IotMqtt_ValidateLwtPublish (bool awsIotMqttMode, const IotMqttPublishInfo_t *pLwtPublishInfo)
	Check that an IotMqttPublishInfo_t is valid for an LWT publish. More...

bool	_IotMqtt_ValidateOperation (IotMqttOperation_t operation)
	Check that an IotMqttOperation_t is valid and waitable. More...

bool	_IotMqtt_ValidateSubscriptionList (IotMqttOperationType_t operation, bool awsIotMqttMode, const IotMqttSubscription_t *pListStart, size_t listSize)
	Check that a list of IotMqttSubscription_t is valid. More...

uint8_t	_IotMqtt_GetPacketType (IotNetworkConnection_t pNetworkConnection, const IotNetworkInterface_t *pNetworkInterface)
	Get the MQTT packet type from a stream of bytes off the network. More...

size_t	_IotMqtt_GetRemainingLength (IotNetworkConnection_t pNetworkConnection, const IotNetworkInterface_t *pNetworkInterface)
	Get the remaining length from a stream of bytes off the network. More...

IotMqttError_t	_IotMqtt_SerializeConnect (const IotMqttConnectInfo_t pConnectInfo, uint8_t pConnectPacket, size_t pPacketSize)
	Generate a CONNECT packet from the given parameters. More...

IotMqttError_t	_IotMqtt_DeserializeConnack (_mqttPacket_t *pConnack)
	Deserialize a CONNACK packet. More...

IotMqttError_t	_IotMqtt_SerializePublish (const IotMqttPublishInfo_t pPublishInfo, uint8_t pPublishPacket, size_t pPacketSize, uint16_t pPacketIdentifier, uint8_t *pPacketIdentifierHigh)
	Generate a PUBLISH packet from the given parameters. More...

void	_IotMqtt_PublishSetDup (uint8_t pPublishPacket, uint8_t pPacketIdentifierHigh, uint16_t *pNewPacketIdentifier)
	Set the DUP bit in a QoS 1 PUBLISH packet. More...

IotMqttError_t	_IotMqtt_DeserializePublish (_mqttPacket_t *pPublish)
	Deserialize a PUBLISH packet received from the server. More...

IotMqttError_t	_IotMqtt_SerializePuback (uint16_t packetIdentifier, uint8_t *pPubackPacket, size_t pPacketSize)
	Generate a PUBACK packet for the given packet identifier. More...

IotMqttError_t	_IotMqtt_DeserializePuback (_mqttPacket_t *pPuback)
	Deserialize a PUBACK packet. More...

IotMqttError_t	_IotMqtt_SerializeSubscribe (const IotMqttSubscription_t pSubscriptionList, size_t subscriptionCount, uint8_t pSubscribePacket, size_t pPacketSize, uint16_t *pPacketIdentifier)
	Generate a SUBSCRIBE packet from the given parameters. More...

IotMqttError_t	_IotMqtt_DeserializeSuback (_mqttPacket_t *pSuback)
	Deserialize a SUBACK packet. More...

IotMqttError_t	_IotMqtt_SerializeUnsubscribe (const IotMqttSubscription_t pSubscriptionList, size_t subscriptionCount, uint8_t pUnsubscribePacket, size_t pPacketSize, uint16_t *pPacketIdentifier)
	Generate an UNSUBSCRIBE packet from the given parameters. More...

IotMqttError_t	_IotMqtt_DeserializeUnsuback (_mqttPacket_t *pUnsuback)
	Deserialize a UNSUBACK packet. More...

IotMqttError_t	_IotMqtt_SerializePingreq (uint8_t *pPingreqPacket, size_t pPacketSize)
	Generate a PINGREQ packet. More...

IotMqttError_t	_IotMqtt_DeserializePingresp (_mqttPacket_t *pPingresp)
	Deserialize a PINGRESP packet. More...

IotMqttError_t	_IotMqtt_SerializeDisconnect (uint8_t *pDisconnectPacket, size_t pPacketSize)
	Generate a DISCONNECT packet. More...

void	_IotMqtt_FreePacket (uint8_t *pPacket)
	Free a packet generated by the serializer. More...

IotMqttError_t	_IotMqtt_CreateOperation (_mqttConnection_t pMqttConnection, uint32_t flags, const IotMqttCallbackInfo_t pCallbackInfo, _mqttOperation_t **pNewOperation)
	Create a record for a new in-progress MQTT operation. More...

bool	_IotMqtt_DecrementOperationReferences (_mqttOperation_t *pOperation, bool cancelJob)
	Decrement the job reference count of an MQTT operation and optionally cancel its job. More...

void	_IotMqtt_DestroyOperation (_mqttOperation_t *pOperation)
	Free resources used to record an MQTT operation. This is called when the operation completes. More...

void	_IotMqtt_ProcessKeepAlive (IotTaskPool_t pTaskPool, IotTaskPoolJob_t pKeepAliveJob, void *pContext)
	Task pool routine for processing an MQTT connection's keep-alive. More...

void	_IotMqtt_ProcessIncomingPublish (IotTaskPool_t pTaskPool, IotTaskPoolJob_t pPublishJob, void *pContext)
	Task pool routine for processing an incoming PUBLISH message. More...

void	_IotMqtt_ProcessSend (IotTaskPool_t pTaskPool, IotTaskPoolJob_t pSendJob, void *pContext)
	Task pool routine for processing an MQTT operation to send. More...

void	_IotMqtt_ProcessCompletedOperation (IotTaskPool_t pTaskPool, IotTaskPoolJob_t pOperationJob, void *pContext)
	Task pool routine for processing a completed MQTT operation. More...

IotMqttError_t	_IotMqtt_ScheduleOperation (_mqttOperation_t *pOperation, IotTaskPoolRoutine_t jobRoutine, uint32_t delay)
	Schedule an operation for immediate processing. More...

_mqttOperation_t *	_IotMqtt_FindOperation (_mqttConnection_t pMqttConnection, IotMqttOperationType_t type, const uint16_t pPacketIdentifier)
	Search a list of MQTT operations pending responses using an operation name and packet identifier. Removes a matching operation from the list if found. More...

void	_IotMqtt_Notify (_mqttOperation_t *pOperation)
	Notify of a completed MQTT operation. More...

IotMqttError_t	_IotMqtt_AddSubscriptions (_mqttConnection_t pMqttConnection, uint16_t subscribePacketIdentifier, const IotMqttSubscription_t pSubscriptionList, size_t subscriptionCount)
	Add an array of subscriptions to the subscription manager. More...

void	_IotMqtt_InvokeSubscriptionCallback (_mqttConnection_t pMqttConnection, IotMqttCallbackParam_t pCallbackParam)
	Process a received PUBLISH from the server, invoking any subscription callbacks that have a matching topic filter. More...

void	_IotMqtt_RemoveSubscriptionByPacket (_mqttConnection_t *pMqttConnection, uint16_t packetIdentifier, int32_t order)
	Remove a single subscription from the subscription manager by packetIdentifier and order. More...

void	_IotMqtt_RemoveSubscriptionByTopicFilter (_mqttConnection_t pMqttConnection, const IotMqttSubscription_t pSubscriptionList, size_t subscriptionCount)
	Remove an array of subscriptions from the subscription manager by topic filter. More...

bool	_IotMqtt_IncrementConnectionReferences (_mqttConnection_t *pMqttConnection)
	Attempt to increment the reference count of an MQTT connection. More...

void	_IotMqtt_DecrementConnectionReferences (_mqttConnection_t *pMqttConnection)
	Decrement the reference count of an MQTT connection. More...

bool	_IotMqtt_GetNextByte (IotNetworkConnection_t pNetworkConnection, const IotNetworkInterface_t pNetworkInterface, uint8_t pIncomingByte)
	Read the next available byte on a network connection. More...

void	_IotMqtt_CloseNetworkConnection (IotMqttDisconnectReason_t disconnectReason, _mqttConnection_t *pMqttConnection)
	Closes the network connection associated with an MQTT connection. More...

Detailed Description

Internal header of MQTT library. This header should not be included in typical application code.

Macro Definition Documentation

◆ IotMqtt_Assert

#define IotMqtt_Assert ( expression )

Assertion macro for the MQTT library.

Set IOT_MQTT_ENABLE_ASSERTS to 1 to enable assertions in the MQTT library.

Parameters

[in] expression Expression to be evaluated.

◆ MQTT_REMAINING_LENGTH_INVALID

#define MQTT_REMAINING_LENGTH_INVALID ( ( size_t ) 268435456 )

A value that represents an invalid remaining length.

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

◆ MQTT_INTERNAL_FLAG_BLOCK_ON_SEND

#define MQTT_INTERNAL_FLAG_BLOCK_ON_SEND ( 0x80000000U )

When this flag is passed, MQTT functions will execute jobs on the calling thread, bypassing the task pool.

This flag is used along with MQTT Function Flags, but is intended for internal use only. Nevertheless, its value must be bitwise exclusive of all conflicting MQTT Function Flags.

◆ MQTT_REMOVE_ALL_SUBSCRIPTIONS

#define MQTT_REMOVE_ALL_SUBSCRIPTIONS ( -1 )

When calling _IotMqtt_RemoveSubscriptionByPacket, use this value for order to delete all subscriptions for the packet.

This flag is used along with MQTT Function Flags, but is intended for internal use only.

MQTT Function Flags.

◆ SERIALIZER_OVERRIDE_SELECTOR

#define SERIALIZER_OVERRIDE_SELECTOR	(	funcType_t,
		funcName,
		defaultFunc,
		serializerMember
	)

Value:

static funcType_t funcName( const IotMqttSerializer_t * pSerializer );                      \
    static funcType_t funcName( const IotMqttSerializer_t * pSerializer )                       \
    {                                                                                           \
        funcType_t returnValue = defaultFunc;                                                   \
        if( pSerializer != NULL )                                                               \
        {                                                                                       \
            if( pSerializer->serializerMember != NULL )                                         \
            {                                                                                   \
                returnValue = pSerializer->serializerMember;                                    \
            }                                                                                   \
        }                                                                                       \
                                                                                                \
        return returnValue;                                                                     \
    }

Utility macro for creating serializer override selector functions.

Function Documentation

◆ _IotMqtt_ValidateConnect()

bool _IotMqtt_ValidateConnect ( const IotMqttConnectInfo_t * pConnectInfo )

Check that an IotMqttConnectInfo_t is valid.

Parameters

[in] pConnectInfo The IotMqttConnectInfo_t to validate.

Returns: true if pConnectInfo is valid; false otherwise.

◆ _IotMqtt_ValidatePublish()

bool _IotMqtt_ValidatePublish	(	bool	awsIotMqttMode,
		const IotMqttPublishInfo_t *	pPublishInfo,
		uint32_t	flags,
		const IotMqttCallbackInfo_t *	pCallbackInfo,
		const IotMqttOperation_t *const	pPublishOperation
	)

Check that parameters for an MQTT PUBLISH are valid.

Parameters

[in]	awsIotMqttMode	Specifies if this PUBLISH packet is being sent to an AWS IoT MQTT server.
[in]	pPublishInfo	The IotMqttPublishInfo_t to validate.
[in]	flags	Behavior modification flags to validate. See MQTT Function Flags.
[in]	pCallbackInfo	IotMqttCallbackInfo_t to validate.
[in]	pPublishOperation	Handle to a PUBLISH operation.

Returns: true if all parameters are valid; false otherwise.

◆ _IotMqtt_ValidateLwtPublish()

bool _IotMqtt_ValidateLwtPublish	(	bool	awsIotMqttMode,
		const IotMqttPublishInfo_t *	pLwtPublishInfo
	)

Check that an IotMqttPublishInfo_t is valid for an LWT publish.

Parameters

[in]	awsIotMqttMode	Specifies if this PUBLISH packet is being sent to an AWS IoT MQTT server.
[in]	pLwtPublishInfo	The IotMqttPublishInfo_t to validate.

Returns: true if pLwtPublishInfo is valid; false otherwise.

◆ _IotMqtt_ValidateOperation()

bool _IotMqtt_ValidateOperation ( IotMqttOperation_t operation )

Check that an IotMqttOperation_t is valid and waitable.

Parameters

[in] operation The IotMqttOperation_t to validate.

Returns: true if operation is valid; false otherwise.

◆ _IotMqtt_ValidateSubscriptionList()

bool _IotMqtt_ValidateSubscriptionList	(	IotMqttOperationType_t	operation,
		bool	awsIotMqttMode,
		const IotMqttSubscription_t *	pListStart,
		size_t	listSize
	)

Check that a list of IotMqttSubscription_t is valid.

Parameters

[in]	operation	Either IOT_MQTT_SUBSCRIBE or IOT_MQTT_UNSUBSCRIBE. Some parameters are not validated for IOT_MQTT_UNSUBSCRIBE.
[in]	awsIotMqttMode	Specifies if this SUBSCRIBE packet is being sent to an AWS IoT MQTT server.
[in]	pListStart	First element of the list to validate.
[in]	listSize	Number of elements in the subscription list.

Returns: true if every element in the list is valid; false otherwise.

◆ _IotMqtt_GetPacketType()

uint8_t _IotMqtt_GetPacketType	(	IotNetworkConnection_t	pNetworkConnection,
		const IotNetworkInterface_t *	pNetworkInterface
	)

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

Parameters

[in]	pNetworkConnection	Reference to the network connection.
[in]	pNetworkInterface	Function pointers used to interact with the network.

Returns: One of the server-to-client MQTT packet types.

Note: This function is only used for incoming packets, and may not work correctly for outgoing packets.

◆ _IotMqtt_GetRemainingLength()

size_t _IotMqtt_GetRemainingLength	(	IotNetworkConnection_t	pNetworkConnection,
		const IotNetworkInterface_t *	pNetworkInterface
	)

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

Parameters

[in]	pNetworkConnection	Reference to the network connection.
[in]	pNetworkInterface	Function pointers used to interact with the network.

Returns: The remaining length; MQTT_REMAINING_LENGTH_INVALID on error.

◆ _IotMqtt_SerializeConnect()

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

Generate a CONNECT packet from the given parameters.

Parameters

[in]	pConnectInfo	User-provided CONNECT information.
[out]	pConnectPacket	Where the CONNECT packet is written.
[out]	pPacketSize	Size of the packet written to `pConnectPacket`.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_DeserializeConnack()

IotMqttError_t _IotMqtt_DeserializeConnack ( _mqttPacket_t * pConnack )

Deserialize a CONNACK packet.

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

Parameters

[in,out] pConnack Pointer to an MQTT packet struct representing a CONNACK.

Returns: IOT_MQTT_SUCCESS if CONNACK specifies that CONNECT was accepted; IOT_MQTT_SERVER_REFUSED if CONNACK specifies that CONNECT was rejected; IOT_MQTT_BAD_RESPONSE if the CONNACK packet doesn't follow MQTT spec.

◆ _IotMqtt_SerializePublish()

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

Generate a PUBLISH packet from the given parameters.

Parameters

[in]	pPublishInfo	User-provided PUBLISH information.
[out]	pPublishPacket	Where the PUBLISH packet is written.
[out]	pPacketSize	Size of the packet written to `pPublishPacket`.
[out]	pPacketIdentifier	The packet identifier generated for this PUBLISH.
[out]	pPacketIdentifierHigh	Where the high byte of the packet identifier is written.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_PublishSetDup()

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

Set the DUP bit in a QoS 1 PUBLISH packet.

Parameters

[in]	pPublishPacket	Pointer to the PUBLISH packet to modify.
[in]	pPacketIdentifierHigh	The high byte of any packet identifier to modify.
[out]	pNewPacketIdentifier	Since AWS IoT does not support the DUP flag, a new packet identifier is generated and should be written here. This parameter is only used when connected to an AWS IoT MQTT server.

Note: See IotMqttPublishInfo_t for caveats with retransmission to the AWS IoT MQTT server.

◆ _IotMqtt_DeserializePublish()

IotMqttError_t _IotMqtt_DeserializePublish ( _mqttPacket_t * pPublish )

Deserialize a PUBLISH packet received from the server.

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

Parameters

[in,out] pPublish Pointer to an MQTT packet struct representing a PUBLISH.

Returns: IOT_MQTT_SUCCESS if PUBLISH is valid; IOT_MQTT_BAD_RESPONSE if the PUBLISH packet doesn't follow MQTT spec.

◆ _IotMqtt_SerializePuback()

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

Generate a PUBACK packet for the given packet identifier.

Parameters

[in]	packetIdentifier	The packet identifier to place in PUBACK.
[out]	pPubackPacket	Where the PUBACK packet is written.
[out]	pPacketSize	Size of the packet written to `pPubackPacket`.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_DeserializePuback()

IotMqttError_t _IotMqtt_DeserializePuback ( _mqttPacket_t * pPuback )

Deserialize a PUBACK packet.

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

Parameters

[in,out] pPuback Pointer to an MQTT packet struct representing a PUBACK.

Returns: IOT_MQTT_SUCCESS if PUBACK is valid; IOT_MQTT_BAD_RESPONSE if the PUBACK packet doesn't follow MQTT spec.

◆ _IotMqtt_SerializeSubscribe()

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

Generate a SUBSCRIBE packet from the given parameters.

Parameters

[in]	pSubscriptionList	User-provided array of subscriptions.
[in]	subscriptionCount	Size of `pSubscriptionList`.
[out]	pSubscribePacket	Where the SUBSCRIBE packet is written.
[out]	pPacketSize	Size of the packet written to `pSubscribePacket`.
[out]	pPacketIdentifier	The packet identifier generated for this SUBSCRIBE.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_DeserializeSuback()

IotMqttError_t _IotMqtt_DeserializeSuback ( _mqttPacket_t * pSuback )

Deserialize a SUBACK packet.

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

Parameters

[in,out] pSuback Pointer to an MQTT packet struct representing a SUBACK.

Returns: IOT_MQTT_SUCCESS if SUBACK is valid; IOT_MQTT_BAD_RESPONSE if the SUBACK packet doesn't follow MQTT spec.

◆ _IotMqtt_SerializeUnsubscribe()

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

Generate an UNSUBSCRIBE packet from the given parameters.

Parameters

[in]	pSubscriptionList	User-provided array of subscriptions to remove.
[in]	subscriptionCount	Size of `pSubscriptionList`.
[out]	pUnsubscribePacket	Where the UNSUBSCRIBE packet is written.
[out]	pPacketSize	Size of the packet written to `pUnsubscribePacket`.
[out]	pPacketIdentifier	The packet identifier generated for this UNSUBSCRIBE.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_DeserializeUnsuback()

IotMqttError_t _IotMqtt_DeserializeUnsuback ( _mqttPacket_t * pUnsuback )

Deserialize a UNSUBACK packet.

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

Parameters

[in,out] pUnsuback Pointer to an MQTT packet struct representing an UNSUBACK.

Returns: IOT_MQTT_SUCCESS if UNSUBACK is valid; IOT_MQTT_BAD_RESPONSE if the UNSUBACK packet doesn't follow MQTT spec.

◆ _IotMqtt_SerializePingreq()

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

Generate a PINGREQ packet.

Parameters

[out]	pPingreqPacket	Where the PINGREQ packet is written.
[out]	pPacketSize	Size of the packet written to `pPingreqPacket`.

Returns: Always returns IOT_MQTT_SUCCESS.

◆ _IotMqtt_DeserializePingresp()

IotMqttError_t _IotMqtt_DeserializePingresp ( _mqttPacket_t * pPingresp )

Deserialize a PINGRESP packet.

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

Parameters

[in,out] pPingresp Pointer to an MQTT packet struct representing a PINGRESP.

Returns: IOT_MQTT_SUCCESS if PINGRESP is valid; IOT_MQTT_BAD_RESPONSE if the PINGRESP packet doesn't follow MQTT spec.

◆ _IotMqtt_SerializeDisconnect()

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

Generate a DISCONNECT packet.

Parameters

[out]	pDisconnectPacket	Where the DISCONNECT packet is written.
[out]	pPacketSize	Size of the packet written to `pDisconnectPacket`.

Returns: Always returns IOT_MQTT_SUCCESS.

◆ _IotMqtt_FreePacket()

void _IotMqtt_FreePacket ( uint8_t * pPacket )

Free a packet generated by the serializer.

Parameters

[in] pPacket The packet to free.

◆ _IotMqtt_CreateOperation()

IotMqttError_t _IotMqtt_CreateOperation	(	_mqttConnection_t *	pMqttConnection,
		uint32_t	flags,
		const IotMqttCallbackInfo_t *	pCallbackInfo,
		_mqttOperation_t **	pNewOperation
	)

Create a record for a new in-progress MQTT operation.

Parameters

[in]	pMqttConnection	The MQTT connection to associate with the operation.
[in]	flags	Flags variable passed to a user-facing MQTT function.
[in]	pCallbackInfo	User-provided callback function and parameter.
[out]	pNewOperation	Set to point to the new operation on success.

Returns: IOT_MQTT_SUCCESS, IOT_MQTT_BAD_PARAMETER, or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_DecrementOperationReferences()

bool _IotMqtt_DecrementOperationReferences	(	_mqttOperation_t *	pOperation,
		bool	cancelJob
	)

Decrement the job reference count of an MQTT operation and optionally cancel its job.

Checks if the operation may be destroyed afterwards.

Parameters

[in]	pOperation	The MQTT operation with the job to cancel.
[in]	cancelJob	Whether to attempt cancellation of the operation's job.

Returns: true if the the operation may be safely destroyed; false otherwise.

◆ _IotMqtt_DestroyOperation()

void _IotMqtt_DestroyOperation ( _mqttOperation_t * pOperation )

Free resources used to record an MQTT operation. This is called when the operation completes.

Parameters

[in] pOperation The operation which completed.

◆ _IotMqtt_ProcessKeepAlive()

void _IotMqtt_ProcessKeepAlive	(	IotTaskPool_t	pTaskPool,
		IotTaskPoolJob_t	pKeepAliveJob,
		void *	pContext
	)

Task pool routine for processing an MQTT connection's keep-alive.

Parameters

[in]	pTaskPool	Pointer to the system task pool.
[in]	pKeepAliveJob	Pointer the an MQTT connection's keep-alive job.
[in]	pContext	Pointer to an MQTT connection, passed as an opaque context.

◆ _IotMqtt_ProcessIncomingPublish()

void _IotMqtt_ProcessIncomingPublish	(	IotTaskPool_t	pTaskPool,
		IotTaskPoolJob_t	pPublishJob,
		void *	pContext
	)

Task pool routine for processing an incoming PUBLISH message.

Parameters

[in]	pTaskPool	Pointer to the system task pool.
[in]	pPublishJob	Pointer to the incoming PUBLISH operation's job.
[in]	pContext	Pointer to the incoming PUBLISH operation, passed as an opaque context.

◆ _IotMqtt_ProcessSend()

void _IotMqtt_ProcessSend	(	IotTaskPool_t	pTaskPool,
		IotTaskPoolJob_t	pSendJob,
		void *	pContext
	)

Task pool routine for processing an MQTT operation to send.

Parameters

[in]	pTaskPool	Pointer to the system task pool.
[in]	pSendJob	Pointer to an operation's job.
[in]	pContext	Pointer to the operation to send, passed as an opaque context.

◆ _IotMqtt_ProcessCompletedOperation()

void _IotMqtt_ProcessCompletedOperation	(	IotTaskPool_t	pTaskPool,
		IotTaskPoolJob_t	pOperationJob,
		void *	pContext
	)

Task pool routine for processing a completed MQTT operation.

Parameters

[in]	pTaskPool	Pointer to the system task pool.
[in]	pOperationJob	Pointer to the completed operation's job.
[in]	pContext	Pointer to the completed operation, passed as an opaque context.

◆ _IotMqtt_ScheduleOperation()

IotMqttError_t _IotMqtt_ScheduleOperation	(	_mqttOperation_t *	pOperation,
		IotTaskPoolRoutine_t	jobRoutine,
		uint32_t	delay
	)

Schedule an operation for immediate processing.

Parameters

[in]	pOperation	The operation to schedule.
[in]	jobRoutine	The routine to run for the job. Must be either _IotMqtt_ProcessSend, _IotMqtt_ProcessCompletedOperation, or _IotMqtt_ProcessIncomingPublish.
[in]	delay	A delay before the operation job should be executed. Pass `0` to execute ASAP.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_SCHEDULING_ERROR.

◆ _IotMqtt_FindOperation()

_mqttOperation_t* _IotMqtt_FindOperation	(	_mqttConnection_t *	pMqttConnection,
		IotMqttOperationType_t	type,
		const uint16_t *	pPacketIdentifier
	)

Search a list of MQTT operations pending responses using an operation name and packet identifier. Removes a matching operation from the list if found.

Parameters

[in]	pMqttConnection	The connection associated with the operation.
[in]	type	The operation type to look for.
[in]	pPacketIdentifier	A packet identifier to match. Pass `NULL` to ignore.

Returns: Pointer to any matching operation; NULL if no match was found.

◆ _IotMqtt_Notify()

void _IotMqtt_Notify ( _mqttOperation_t * pOperation )

Notify of a completed MQTT operation.

Parameters

[in] pOperation The MQTT operation which completed.

Depending on the parameters passed to a user-facing MQTT function, the notification will cause IotMqtt_Wait to return or invoke a user-provided callback.

◆ _IotMqtt_AddSubscriptions()

IotMqttError_t _IotMqtt_AddSubscriptions	(	_mqttConnection_t *	pMqttConnection,
		uint16_t	subscribePacketIdentifier,
		const IotMqttSubscription_t *	pSubscriptionList,
		size_t	subscriptionCount
	)

Add an array of subscriptions to the subscription manager.

Parameters

[in]	pMqttConnection	The MQTT connection associated with the subscriptions.
[in]	subscribePacketIdentifier	Packet identifier for the subscriptions' SUBSCRIBE packet.
[in]	pSubscriptionList	The first element in the array.
[in]	subscriptionCount	Number of elements in `pSubscriptionList`.

Returns: IOT_MQTT_SUCCESS or IOT_MQTT_NO_MEMORY.

◆ _IotMqtt_InvokeSubscriptionCallback()

void _IotMqtt_InvokeSubscriptionCallback	(	_mqttConnection_t *	pMqttConnection,
		IotMqttCallbackParam_t *	pCallbackParam
	)

Process a received PUBLISH from the server, invoking any subscription callbacks that have a matching topic filter.

Parameters

[in]	pMqttConnection	The MQTT connection associated with the received PUBLISH.
[in]	pCallbackParam	The parameter to pass to a PUBLISH callback.

◆ _IotMqtt_RemoveSubscriptionByPacket()

void _IotMqtt_RemoveSubscriptionByPacket	(	_mqttConnection_t *	pMqttConnection,
		uint16_t	packetIdentifier,
		int32_t	order
	)

Remove a single subscription from the subscription manager by packetIdentifier and order.

Parameters

[in]	pMqttConnection	The MQTT connection associated with the subscriptions.
[in]	packetIdentifier	The packet identifier associated with the subscription's SUBSCRIBE packet.
[in]	order	The order of the subscription in the SUBSCRIBE packet. Pass MQTT_REMOVE_ALL_SUBSCRIPTIONS to ignore order and remove all subscriptions for `packetIdentifier`.

◆ _IotMqtt_RemoveSubscriptionByTopicFilter()

void _IotMqtt_RemoveSubscriptionByTopicFilter	(	_mqttConnection_t *	pMqttConnection,
		const IotMqttSubscription_t *	pSubscriptionList,
		size_t	subscriptionCount
	)

Remove an array of subscriptions from the subscription manager by topic filter.

Parameters

[in]	pMqttConnection	The MQTT connection associated with the subscriptions.
[in]	pSubscriptionList	The first element in the array.
[in]	subscriptionCount	Number of elements in `pSubscriptionList`.

◆ _IotMqtt_IncrementConnectionReferences()

bool _IotMqtt_IncrementConnectionReferences ( _mqttConnection_t * pMqttConnection )

Attempt to increment the reference count of an MQTT connection.

Parameters

[in] pMqttConnection The referenced MQTT connection.

Returns: true if the reference count was incremented; false otherwise. The reference count will not be incremented for a disconnected connection.

◆ _IotMqtt_DecrementConnectionReferences()

void _IotMqtt_DecrementConnectionReferences ( _mqttConnection_t * pMqttConnection )

Decrement the reference count of an MQTT connection.

Also destroys an unreferenced MQTT connection.

Parameters

[in] pMqttConnection The referenced MQTT connection.

◆ _IotMqtt_GetNextByte()

bool _IotMqtt_GetNextByte	(	IotNetworkConnection_t	pNetworkConnection,
		const IotNetworkInterface_t *	pNetworkInterface,
		uint8_t *	pIncomingByte
	)

Read the next available byte on a network connection.

Parameters

[in]	pNetworkConnection	Reference to the network connection.
[in]	pNetworkInterface	Function pointers used to interact with the network.
[out]	pIncomingByte	The byte read from the network.

Returns: true if a byte was successfully received from the network; false otherwise.

◆ _IotMqtt_CloseNetworkConnection()

void _IotMqtt_CloseNetworkConnection	(	IotMqttDisconnectReason_t	disconnectReason,
		_mqttConnection_t *	pMqttConnection
	)

Closes the network connection associated with an MQTT connection.

A network disconnect function must be set in the network interface for the network connection to be closed.

Parameters

[in]	disconnectReason	A reason to pass to the connection's disconnect callback.
[in]	pMqttConnection	The MQTT connection with the network connection to close.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ IotMqtt_Assert

◆ MQTT_REMAINING_LENGTH_INVALID

◆ MQTT_INTERNAL_FLAG_BLOCK_ON_SEND

◆ MQTT_REMOVE_ALL_SUBSCRIPTIONS

◆ SERIALIZER_OVERRIDE_SELECTOR

Function Documentation

◆ _IotMqtt_ValidateConnect()

◆ _IotMqtt_ValidatePublish()

◆ _IotMqtt_ValidateLwtPublish()

◆ _IotMqtt_ValidateOperation()

◆ _IotMqtt_ValidateSubscriptionList()

◆ _IotMqtt_GetPacketType()

◆ _IotMqtt_GetRemainingLength()

◆ _IotMqtt_SerializeConnect()

◆ _IotMqtt_DeserializeConnack()

◆ _IotMqtt_SerializePublish()

◆ _IotMqtt_PublishSetDup()

◆ _IotMqtt_DeserializePublish()

◆ _IotMqtt_SerializePuback()

◆ _IotMqtt_DeserializePuback()

◆ _IotMqtt_SerializeSubscribe()

◆ _IotMqtt_DeserializeSuback()

◆ _IotMqtt_SerializeUnsubscribe()

◆ _IotMqtt_DeserializeUnsuback()

◆ _IotMqtt_SerializePingreq()

◆ _IotMqtt_DeserializePingresp()

◆ _IotMqtt_SerializeDisconnect()

◆ _IotMqtt_FreePacket()

◆ _IotMqtt_CreateOperation()

◆ _IotMqtt_DecrementOperationReferences()

◆ _IotMqtt_DestroyOperation()

◆ _IotMqtt_ProcessKeepAlive()

◆ _IotMqtt_ProcessIncomingPublish()

◆ _IotMqtt_ProcessSend()

◆ _IotMqtt_ProcessCompletedOperation()

◆ _IotMqtt_ScheduleOperation()

◆ _IotMqtt_FindOperation()

◆ _IotMqtt_Notify()

◆ _IotMqtt_AddSubscriptions()

◆ _IotMqtt_InvokeSubscriptionCallback()

◆ _IotMqtt_RemoveSubscriptionByPacket()

◆ _IotMqtt_RemoveSubscriptionByTopicFilter()

◆ _IotMqtt_IncrementConnectionReferences()

◆ _IotMqtt_DecrementConnectionReferences()

◆ _IotMqtt_GetNextByte()

◆ _IotMqtt_CloseNetworkConnection()