Implements helper functions for the MQTT library. More...

#include "iot_config.h"
#include <string.h>
#include <limits.h>
#include <assert.h>
#include <stdlib.h>
#include "iot_atomic.h"
#include "private/iot_mqtt_helper.h"
#include "iot_logging_setup.h"

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

#define	AWS_IOT_METRICS_USERNAME "?SDK=C&Version=4.0.0"
	Specify C SDK and version.

#define	AWS_IOT_METRICS_USERNAME_LENGTH ( ( uint16_t ) sizeof( AWS_IOT_METRICS_USERNAME ) - 1U )
	The length of AWS_IOT_METRICS_USERNAME.

Functions
static uint8_t *	_encodeUserNameAndMetrics (uint8_t pDestination, const IotMqttConnectInfo_t pConnectInfo, bool *pEncodedUserName)
	Encode both connection and metrics username into a buffer, if they will fit. More...

static uint8_t *	_encodeUserName (uint8_t pDestination, const IotMqttConnectInfo_t pConnectInfo)
	Encode a username into a CONNECT packet, if necessary. More...

static uint8_t *	_encodeString (uint8_t pDestination, const char source, uint16_t sourceLength)
	Encode a C string as a UTF-8 string, per MQTT 3.1.1 spec. More...

static uint8_t *	_encodeRemainingLength (uint8_t *pDestination, size_t length)
	Encode the "Remaining length" field per MQTT spec. More...

size_t	_IotMqtt_RemainingLengthEncodedSize (size_t length)
	Calculate the number of bytes required to encode an MQTT "Remaining length" field. More...

uint16_t	_IotMqtt_NextPacketIdentifier (void)
	Generate and return a 2-byte packet identifier. More...

bool	_IotMqtt_ConnectPacketSize (const IotMqttConnectInfo_t pConnectInfo, size_t pRemainingLength, size_t *pPacketSize)
	Calculate the size and "Remaining length" of a CONNECT packet generated from the given parameters. More...

void	_IotMqtt_SerializeConnectCommon (const IotMqttConnectInfo_t pConnectInfo, size_t remainingLength, uint8_t pPacket, size_t connectPacketSize)
	Generate a CONNECT packet from the given parameters. More...

bool	_IotMqtt_IncomingPacketValid (uint8_t packetType)
	Check if an incoming packet type is valid. More...

void	_IotMqtt_SerializeSubscribeCommon (const IotMqttSubscription_t pSubscriptionList, size_t subscriptionCount, size_t remainingLength, uint16_t pPacketIdentifier, uint8_t *pPacket, size_t subscribePacketSize)
	Generate a SUBSCRIBE packet from the given parameters. More...

bool	_IotMqtt_SubscriptionPacketSize (IotMqttOperationType_t type, const IotMqttSubscription_t pSubscriptionList, size_t subscriptionCount, size_t pRemainingLength, size_t *pPacketSize)
	Calculate the size and "Remaining length" of a SUBSCRIBE or UNSUBSCRIBE packet generated from the given parameters. More...

bool	_IotMqtt_PublishPacketSize (const IotMqttPublishInfo_t pPublishInfo, size_t pRemainingLength, size_t *pPacketSize)
	Calculate the size and "Remaining length" of a PUBLISH packet generated from the given parameters. More...

void	_IotMqtt_SerializePublishCommon (const IotMqttPublishInfo_t pPublishInfo, size_t remainingLength, uint16_t pPacketIdentifier, uint8_t *pPacketIdentifierHigh, uint8_t pPacket, size_t publishPacketSize)
	Generate a PUBLISH packet from the given parameters. More...

void	_IotMqtt_SerializeUnsubscribeCommon (const IotMqttSubscription_t pSubscriptionList, size_t subscriptionCount, size_t remainingLength, uint16_t pPacketIdentifier, uint8_t *pPacket, size_t unsubscribePacketSize)
	Generate an UNSUBSCRIBE packet from the given parameters. More...

IotMqttError_t	_IotMqtt_ProcessPublishFlags (uint8_t publishFlags, IotMqttPublishInfo_t *pOutput)
	Process incoming publish flags. More...

Detailed Description

Implements helper functions for the MQTT library.

Implements internal helper functions for the MQTT library.

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.

Function Documentation

◆ _encodeUserNameAndMetrics()

static uint8_t * _encodeUserNameAndMetrics	(	uint8_t *	pDestination,
		const IotMqttConnectInfo_t *	pConnectInfo,
		bool *	pEncodedUserName
	)

static

Encode both connection and metrics username into a buffer, if they will fit.

Parameters

[in]	pDestination	Buffer to write username into.
[in]	pConnectInfo	User-provided CONNECT information.
[out]	pEncodedUserName	Whether the username was written into the buffer.

Returns: Pointer to the end of encoded string, which will be identical to pDestination if nothing was encoded.

Warning: This function does not check the size of pDestination! Ensure that pDestination is large enough to hold pConnectInfo->userNameLength + AWS_IOT_METRICS_USERNAME_LENGTH bytes to avoid a buffer overflow.

◆ _encodeUserName()

static uint8_t * _encodeUserName	(	uint8_t *	pDestination,
		const IotMqttConnectInfo_t *	pConnectInfo
	)

static

Encode a username into a CONNECT packet, if necessary.

Parameters

[out]	pDestination	Buffer for the CONNECT packet.
[in]	pConnectInfo	User-provided CONNECT information.

Returns: Pointer to the end of the encoded string, which will be identical to pDestination if nothing was encoded.

Warning: This function does not check the size of pDestination! To avoid a buffer overflow, ensure that pDestination is large enough to hold pConnectInfo->userNameLength bytes if a username is supplied, and/or AWS_IOT_METRICS_USERNAME_LENGTH bytes if metrics are enabled.

◆ _encodeString()

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

static

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

Parameters

[out]	pDestination	Where to write the encoded string.
[in]	source	The string to encode.
[in]	sourceLength	The length of source.

Returns: Pointer to the end of the encoded string, which is sourceLength+2 bytes greater than pDestination.

Warning: This function does not check the size of pDestination! Ensure that pDestination is large enough to hold sourceLength+2 bytes to avoid a buffer overflow.

◆ _encodeRemainingLength()

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

static

Encode the "Remaining length" field per MQTT spec.

Parameters

[out]	pDestination	Where to write the encoded "Remaining length".
[in]	length	The "Remaining length" to encode.

Returns: Pointer to the end of the encoded "Remaining length", which is 1-4 bytes greater than pDestination.

Warning: This function does not check the size of pDestination! Ensure that pDestination is large enough to hold the encoded "Remaining length" using the function _IotMqtt_RemainingLengthEncodedSize to avoid buffer overflows.

◆ _IotMqtt_RemainingLengthEncodedSize()

size_t _IotMqtt_RemainingLengthEncodedSize ( size_t length )

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

Parameters

[in] length The value of the "Remaining length" to encode.

Returns: The size of the encoding of length. This is always 1, 2, 3, or 4.

◆ _IotMqtt_NextPacketIdentifier()

uint16_t _IotMqtt_NextPacketIdentifier ( void )

Generate and return a 2-byte packet identifier.

This packet identifier will be nonzero.

Returns: The packet identifier.

◆ _IotMqtt_ConnectPacketSize()

bool _IotMqtt_ConnectPacketSize	(	const IotMqttConnectInfo_t *	pConnectInfo,
		size_t *	pRemainingLength,
		size_t *	pPacketSize
	)

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

Parameters

[in]	pConnectInfo	User-provided CONNECT information struct.
[out]	pRemainingLength	Output for calculated "Remaining length" field.
[out]	pPacketSize	Output for calculated total packet size.

Returns: true if the packet is within the length allowed by MQTT 3.1.1 spec; false otherwise. If this function returns false, the output parameters should be ignored.

◆ _IotMqtt_SerializeConnectCommon()

void _IotMqtt_SerializeConnectCommon	(	const IotMqttConnectInfo_t *	pConnectInfo,
		size_t	remainingLength,
		uint8_t *	pPacket,
		size_t	connectPacketSize
	)

Generate a CONNECT packet from the given parameters.

Parameters

[in]	pConnectInfo	User-provided CONNECT information.
[in]	remainingLength	User provided remaining length.
[in,out]	pPacket	User provided buffer where the CONNECT packet is written.
[in]	connectPacketSize	Size of the buffer pointed to by `pPacket`.

◆ _IotMqtt_IncomingPacketValid()

bool _IotMqtt_IncomingPacketValid ( uint8_t packetType )

Check if an incoming packet type is valid.

Parameters

[in] packetType The packet type to check.

Returns: true if the packet type is valid; false otherwise.

◆ _IotMqtt_SerializeSubscribeCommon()

void _IotMqtt_SerializeSubscribeCommon	(	const IotMqttSubscription_t *	pSubscriptionList,
		size_t	subscriptionCount,
		size_t	remainingLength,
		uint16_t *	pPacketIdentifier,
		uint8_t *	pPacket,
		size_t	subscribePacketSize
	)

Generate a SUBSCRIBE packet from the given parameters.

Parameters

[in]	pSubscriptionList	User-provided array of subscriptions.
[in]	subscriptionCount	Size of `pSubscriptionList`.
[in]	remainingLength	User provided remaining length.
[out]	pPacketIdentifier	The packet identifier generated for this SUBSCRIBE.
[in,out]	pPacket	User provided buffer where the SUBSCRIBE packet is written.
[in]	subscribePacketSize	Size of the buffer pointed to by `pPacket`.

◆ _IotMqtt_SubscriptionPacketSize()

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

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

Parameters

[in]	type	Either IOT_MQTT_SUBSCRIBE or IOT_MQTT_UNSUBSCRIBE.
[in]	pSubscriptionList	User-provided array of subscriptions.
[in]	subscriptionCount	Size of `pSubscriptionList`.
[out]	pRemainingLength	Output for calculated "Remaining length" field.
[out]	pPacketSize	Output for calculated total packet size.

Returns: true if the packet is within the length allowed by MQTT 3.1.1 spec; false otherwise. If this function returns false, the output parameters should be ignored.

◆ _IotMqtt_PublishPacketSize()

bool _IotMqtt_PublishPacketSize	(	const IotMqttPublishInfo_t *	pPublishInfo,
		size_t *	pRemainingLength,
		size_t *	pPacketSize
	)

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

Parameters

[in]	pPublishInfo	User-provided PUBLISH information struct.
[out]	pRemainingLength	Output for calculated "Remaining length" field.
[out]	pPacketSize	Output for calculated total packet size.

Returns: true if the packet is within the length allowed by MQTT 3.1.1 spec; false otherwise. If this function returns false, the output parameters should be ignored.

◆ _IotMqtt_SerializePublishCommon()

void _IotMqtt_SerializePublishCommon	(	const IotMqttPublishInfo_t *	pPublishInfo,
		size_t	remainingLength,
		uint16_t *	pPacketIdentifier,
		uint8_t **	pPacketIdentifierHigh,
		uint8_t *	pPacket,
		size_t	publishPacketSize
	)

Generate a PUBLISH packet from the given parameters.

Parameters

[in]	pPublishInfo	User-provided PUBLISH information.
[in]	remainingLength	User provided remaining length.
[out]	pPacketIdentifier	The packet identifier generated for this PUBLISH.
[out]	pPacketIdentifierHigh	Where the high byte of the packet identifier is written.
[in,out]	pPacket	User provided buffer where the PUBLISH packet is written.
[in]	publishPacketSize	Size of buffer pointed to by `pPacket`.

◆ _IotMqtt_SerializeUnsubscribeCommon()

void _IotMqtt_SerializeUnsubscribeCommon	(	const IotMqttSubscription_t *	pSubscriptionList,
		size_t	subscriptionCount,
		size_t	remainingLength,
		uint16_t *	pPacketIdentifier,
		uint8_t *	pPacket,
		size_t	unsubscribePacketSize
	)

Generate an UNSUBSCRIBE packet from the given parameters.

Parameters

[in]	pSubscriptionList	User-provided array of subscriptions to remove.
[in]	subscriptionCount	Size of `pSubscriptionList`.
[in]	remainingLength	User provided remaining length.
[out]	pPacketIdentifier	The packet identifier generated for this UNSUBSCRIBE.
[in,out]	pPacket	User provided buffer where the UNSUBSCRIBE packet is written.
[in]	unsubscribePacketSize	size of the buffer pointed to by `pPacket`.

◆ _IotMqtt_ProcessPublishFlags()

IotMqttError_t _IotMqtt_ProcessPublishFlags	(	uint8_t	publishFlags,
		IotMqttPublishInfo_t *	pOutput
	)

Process incoming publish flags.

Parameters

[in]	publishFlags	Incoming publish flags.
[in,out]	pOutput	Pointer to IotMqttPublishInfo_t struct. where output will be written.

Returns: IOT_MQTT_SUCCESS, IOT_MQTT_BAD_RESPONSE.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ IotMqtt_Assert

Function Documentation

◆ _encodeUserNameAndMetrics()

◆ _encodeUserName()

◆ _encodeString()

◆ _encodeRemainingLength()

◆ _IotMqtt_RemainingLengthEncodedSize()

◆ _IotMqtt_NextPacketIdentifier()

◆ _IotMqtt_ConnectPacketSize()

◆ _IotMqtt_SerializeConnectCommon()

◆ _IotMqtt_IncomingPacketValid()

◆ _IotMqtt_SerializeSubscribeCommon()

◆ _IotMqtt_SubscriptionPacketSize()

◆ _IotMqtt_PublishPacketSize()

◆ _IotMqtt_SerializePublishCommon()

◆ _IotMqtt_SerializeUnsubscribeCommon()

◆ _IotMqtt_ProcessPublishFlags()