AWS IoT Device SDK C: MQTT
MQTT 3.1.1 client library
Return to main page ↑
iot_mqtt_internal.h File Reference

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"

Go to the source code of this file.

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]expressionExpression 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; \
}
Function pointers for MQTT packet serializer overrides.
Definition: iot_mqtt_types.h:867

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]pConnectInfoThe 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]awsIotMqttModeSpecifies if this PUBLISH packet is being sent to an AWS IoT MQTT server.
[in]pPublishInfoThe IotMqttPublishInfo_t to validate.
[in]flagsBehavior modification flags to validate. See MQTT Function Flags.
[in]pCallbackInfoIotMqttCallbackInfo_t to validate.
[in]pPublishOperationHandle 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]awsIotMqttModeSpecifies if this PUBLISH packet is being sent to an AWS IoT MQTT server.
[in]pLwtPublishInfoThe 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]operationThe 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]operationEither IOT_MQTT_SUBSCRIBE or IOT_MQTT_UNSUBSCRIBE. Some parameters are not validated for IOT_MQTT_UNSUBSCRIBE.
[in]awsIotMqttModeSpecifies if this SUBSCRIBE packet is being sent to an AWS IoT MQTT server.
[in]pListStartFirst element of the list to validate.
[in]listSizeNumber 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]pNetworkConnectionReference to the network connection.
[in]pNetworkInterfaceFunction pointers used to interact with the network.
Returns
One of the server-to-client MQTT packet types.
Note
This function is only used for incoming packets, and may not work correctly for outgoing packets.

◆ _IotMqtt_GetRemainingLength()

size_t _IotMqtt_GetRemainingLength ( IotNetworkConnection_t  pNetworkConnection,
const IotNetworkInterface_t pNetworkInterface 
)

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

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

◆ _IotMqtt_SerializeConnect()

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

Generate a CONNECT packet from the given parameters.

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

◆ _IotMqtt_DeserializeConnack()

IotMqttError_t _IotMqtt_DeserializeConnack ( _mqttPacket_t pConnack)

Deserialize a CONNACK packet.

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

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

◆ _IotMqtt_SerializePublish()

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

Generate a PUBLISH packet from the given parameters.

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

◆ _IotMqtt_PublishSetDup()

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

Set the DUP bit in a QoS 1 PUBLISH packet.

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

◆ _IotMqtt_DeserializePublish()

IotMqttError_t _IotMqtt_DeserializePublish ( _mqttPacket_t pPublish)

Deserialize a PUBLISH packet received from the server.

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

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

◆ _IotMqtt_SerializePuback()

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

Generate a PUBACK packet for the given packet identifier.

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

◆ _IotMqtt_DeserializePuback()

IotMqttError_t _IotMqtt_DeserializePuback ( _mqttPacket_t pPuback)

Deserialize a PUBACK packet.

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

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

◆ _IotMqtt_SerializeSubscribe()

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

Generate a SUBSCRIBE packet from the given parameters.

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

◆ _IotMqtt_DeserializeSuback()

IotMqttError_t _IotMqtt_DeserializeSuback ( _mqttPacket_t pSuback)

Deserialize a SUBACK packet.

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

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

◆ _IotMqtt_SerializeUnsubscribe()

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

Generate an UNSUBSCRIBE packet from the given parameters.

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

◆ _IotMqtt_DeserializeUnsuback()

IotMqttError_t _IotMqtt_DeserializeUnsuback ( _mqttPacket_t pUnsuback)

Deserialize a UNSUBACK packet.

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

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

◆ _IotMqtt_SerializePingreq()

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

Generate a PINGREQ packet.

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

◆ _IotMqtt_DeserializePingresp()

IotMqttError_t _IotMqtt_DeserializePingresp ( _mqttPacket_t pPingresp)

Deserialize a PINGRESP packet.

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

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

◆ _IotMqtt_SerializeDisconnect()

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

Generate a DISCONNECT packet.

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

◆ _IotMqtt_FreePacket()

void _IotMqtt_FreePacket ( uint8_t *  pPacket)

Free a packet generated by the serializer.

Parameters
[in]pPacketThe packet to free.

◆ _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]pMqttConnectionThe MQTT connection to associate with the operation.
[in]flagsFlags variable passed to a user-facing MQTT function.
[in]pCallbackInfoUser-provided callback function and parameter.
[out]pNewOperationSet 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]pOperationThe MQTT operation with the job to cancel.
[in]cancelJobWhether 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]pOperationThe 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]pTaskPoolPointer to the system task pool.
[in]pKeepAliveJobPointer the an MQTT connection's keep-alive job.
[in]pContextPointer 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]pTaskPoolPointer to the system task pool.
[in]pPublishJobPointer to the incoming PUBLISH operation's job.
[in]pContextPointer 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]pTaskPoolPointer to the system task pool.
[in]pSendJobPointer to an operation's job.
[in]pContextPointer 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]pTaskPoolPointer to the system task pool.
[in]pOperationJobPointer to the completed operation's job.
[in]pContextPointer 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]pOperationThe operation to schedule.
[in]jobRoutineThe routine to run for the job. Must be either _IotMqtt_ProcessSend, _IotMqtt_ProcessCompletedOperation, or _IotMqtt_ProcessIncomingPublish.
[in]delayA 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]pMqttConnectionThe connection associated with the operation.
[in]typeThe operation type to look for.
[in]pPacketIdentifierA 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]pOperationThe 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]pMqttConnectionThe MQTT connection associated with the subscriptions.
[in]subscribePacketIdentifierPacket identifier for the subscriptions' SUBSCRIBE packet.
[in]pSubscriptionListThe first element in the array.
[in]subscriptionCountNumber 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]pMqttConnectionThe MQTT connection associated with the received PUBLISH.
[in]pCallbackParamThe 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]pMqttConnectionThe MQTT connection associated with the subscriptions.
[in]packetIdentifierThe packet identifier associated with the subscription's SUBSCRIBE packet.
[in]orderThe 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]pMqttConnectionThe MQTT connection associated with the subscriptions.
[in]pSubscriptionListThe first element in the array.
[in]subscriptionCountNumber of elements in pSubscriptionList.

◆ _IotMqtt_IncrementConnectionReferences()

bool _IotMqtt_IncrementConnectionReferences ( _mqttConnection_t pMqttConnection)

Attempt to increment the reference count of an MQTT connection.

Parameters
[in]pMqttConnectionThe 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]pMqttConnectionThe 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]pNetworkConnectionReference to the network connection.
[in]pNetworkInterfaceFunction pointers used to interact with the network.
[out]pIncomingByteThe 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]disconnectReasonA reason to pass to the connection's disconnect callback.
[in]pMqttConnectionThe MQTT connection with the network connection to close.