Implements functions that manage subscriptions for an MQTT connection. More...

#include "iot_config.h"
#include <stdbool.h>
#include <string.h>
#include "private/iot_mqtt_internal.h"
#include "platform/iot_threads.h"

Data Structures
struct	_topicMatchParams_t
	First parameter to _topicMatch. More...

struct	_packetMatchParams_t
	First parameter to _packetMatch. More...

Functions
static bool	_matchEndWildcards (const char pTopicFilter, uint16_t topicNameLength, uint16_t topicFilterLength, uint16_t nameIndex, uint16_t filterIndex, bool pMatch)
	Handle special corner cases regarding wildcards at the end of topic filters, as documented by the MQTT protocol spec. More...

static bool	_matchWildcards (const char pTopicFilter, const char pTopicName, uint16_t topicNameLength, uint16_t filterIndex, uint16_t pNameIndex, bool pMatch)
	Attempt to match characters in a topic filter by wildcards. More...

static bool	_topicFilterMatch (const char pTopicName, uint16_t topicNameLength, const char pTopicFilter, uint16_t topicFilterLength)
	Match a topic name and topic filter while allowing the use of wildcards. More...

static bool	_topicMatch (const IotLink_t const pSubscriptionLink, void pMatch)
	Matches a topic name (from a publish) with a topic filter (from a subscription). More...

static bool	_packetMatch (const IotLink_t const pSubscriptionLink, void pMatch)
	Matches a packet identifier and order. 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_IsSubscribed (IotMqttConnection_t mqttConnection, const char pTopicFilter, uint16_t topicFilterLength, IotMqttSubscription_t const pCurrentSubscription)
	Check if an MQTT connection has a subscription for a topic filter. More...

Detailed Description

Implements functions that manage subscriptions for an MQTT connection.

Function Documentation

◆ _matchEndWildcards()

static bool _matchEndWildcards	(	const char *	pTopicFilter,
		uint16_t	topicNameLength,
		uint16_t	topicFilterLength,
		uint16_t	nameIndex,
		uint16_t	filterIndex,
		bool *	pMatch
	)

static

Handle special corner cases regarding wildcards at the end of topic filters, as documented by the MQTT protocol spec.

Parameters

[in]	pTopicFilter	The topic filter containing the wildcard.
[in]	nameIndex	Index of the topic name being examined.
[in]	filterIndex	Index of the topic filter being examined.
[in]	topicNameLength	Length of the topic name being examined.
[in]	topicFilterLength	Length of the topic filter being examined.
[out]	pMatch	Whether the topic filter and topic name match.

Returns: true if the caller of this function should exit; false if the caller should continue parsing the topics.

◆ _matchWildcards()

static bool _matchWildcards	(	const char *	pTopicFilter,
		const char *	pTopicName,
		uint16_t	topicNameLength,
		uint16_t	filterIndex,
		uint16_t *	pNameIndex,
		bool *	pMatch
	)

static

Attempt to match characters in a topic filter by wildcards.

Parameters

[in]	pTopicFilter	The topic filter containing the wildcard.
[in]	pTopicName	The topic name to check.
[in]	topicNameLength	Length of the topic name.
[in]	filterIndex	Index of the wildcard in the topic filter.
[in,out]	pNameIndex	Index of character in topic name. This variable is advanced for `+` wildcards.
[out]	pMatch	Whether the topic filter and topic name match.

Returns: true if the caller of this function should exit; false if the caller should continue parsing the topics.

◆ _topicFilterMatch()

static bool _topicFilterMatch	(	const char *	pTopicName,
		uint16_t	topicNameLength,
		const char *	pTopicFilter,
		uint16_t	topicFilterLength
	)

static

Match a topic name and topic filter while allowing the use of wildcards.

Parameters

[in]	pTopicName	The topic name to check.
[in]	topicNameLength	Length of `pTopicName`.
[in]	pTopicFilter	The topic filter to check.
[in]	topicFilterLength	Length of `pTopicFilter`.

Returns: true if the topic name and topic filter match; false otherwise.

◆ _topicMatch()

static bool _topicMatch	(	const IotLink_t *const	pSubscriptionLink,
		void *	pMatch
	)

static

Matches a topic name (from a publish) with a topic filter (from a subscription).

Parameters

[in]	pSubscriptionLink	Pointer to the link member of an _mqttSubscription_t.
[in]	pMatch	Pointer to a _topicMatchParams_t.

Returns: true if the arguments match the subscription topic filter; false otherwise.

◆ _packetMatch()

static bool _packetMatch	(	const IotLink_t *const	pSubscriptionLink,
		void *	pMatch
	)

static

Matches a packet identifier and order.

Parameters

[in]	pSubscriptionLink	Pointer to the link member of an _mqttSubscription_t.
[in]	pMatch	Pointer to a _packetMatchParams_t.

Returns: true if the arguments match the subscription's packet info; false otherwise.

◆ _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_IsSubscribed()

bool IotMqtt_IsSubscribed	(	IotMqttConnection_t	mqttConnection,
		const char *	pTopicFilter,
		uint16_t	topicFilterLength,
		IotMqttSubscription_t *const	pCurrentSubscription
	)

Check if an MQTT connection has a subscription for a topic filter.

This function checks whether an MQTT connection mqttConnection has a subscription callback registered for a topic filter pTopicFilter. If a subscription callback is found, its details are copied into the output parameter pCurrentSubscription. This subscription callback will be invoked for incoming PUBLISH messages on pTopicFilter.

The check for a matching subscription is only performed client-side; therefore, this function should not be relied upon for perfect accuracy. For example, this function may return an incorrect result if the MQTT server crashes and drops subscriptions without informing the client.

Note that an MQTT connection's subscriptions might change between the time this function checks the subscription list and its caller tests the return value. This function certainly should not be used concurrently with any pending SUBSCRIBE or UNSUBSCRIBE operations.

One suitable use of this function is to check which subscriptions were rejected if IotMqtt_SubscribeAsync returns IOT_MQTT_SERVER_REFUSED; that return code only means that at least one subscription was rejected.

Parameters

[in]	mqttConnection	The MQTT connection to check.
[in]	pTopicFilter	The topic filter to check.
[in]	topicFilterLength	Length of `pTopicFilter`.
[out]	pCurrentSubscription	If a subscription is found, its details are copied here. This output parameter is only valid if this function returns `true` (`NULL` to disable).

Returns: true if a subscription was found; false otherwise.

Note: The subscription QoS is not stored by the MQTT library; therefore, pCurrentSubscription->qos will always be set to IOT_MQTT_QOS_0.

Data Structures

Functions

Detailed Description

Function Documentation

◆ _matchEndWildcards()

◆ _matchWildcards()

◆ _topicFilterMatch()

◆ _topicMatch()

◆ _packetMatch()

◆ _IotMqtt_AddSubscriptions()

◆ _IotMqtt_InvokeSubscriptionCallback()

◆ _IotMqtt_RemoveSubscriptionByPacket()

◆ _IotMqtt_RemoveSubscriptionByTopicFilter()

◆ IotMqtt_IsSubscribed()