aws_iot_shadow_subscription.c File Reference

Implements functions for interacting with the Shadow library's subscription list. More...

#include "iot_config.h"
#include <string.h>
#include "private/aws_iot_shadow_internal.h"
#include "platform/iot_threads.h"
#include "iot_mqtt.h"

Functions
static bool	_shadowSubscription_match (const IotLink_t *pSubscriptionLink, void *pMatch)
	Match two _shadowSubscription_t by Thing Name. More...
_shadowSubscription_t *	_AwsIotShadow_FindSubscription (const char *pThingName, size_t thingNameLength, bool createIfNotFound)
	Find a Shadow subscription object. May create a new subscription object and adds it to the subscription list if not found. More...
void	_AwsIotShadow_RemoveSubscription (_shadowSubscription_t *pSubscription, _shadowSubscription_t **pRemovedSubscription)
	Remove a Shadow subscription object from the subscription list if unreferenced. More...
void	_AwsIotShadow_DestroySubscription (void *pData)
	Free resources used for a Shadow subscription object. More...
AwsIotShadowError_t	_AwsIotShadow_IncrementReferences (_shadowOperation_t *pOperation, char *pTopicBuffer, uint16_t operationTopicLength, AwsIotMqttCallbackFunction_t callback)
	Increment the reference count of a Shadow subscriptions object. More...
void	_AwsIotShadow_DecrementReferences (_shadowOperation_t *pOperation, char *pTopicBuffer, _shadowSubscription_t **pRemovedSubscription)
	Decrement the reference count of a Shadow subscriptions object. More...
AwsIotShadowError_t	AwsIotShadow_RemovePersistentSubscriptions (IotMqttConnection_t mqttConnection, const char *pThingName, size_t thingNameLength, uint32_t flags)
	Remove persistent Thing Shadow operation topic subscriptions. More...

Variables
IotListDouble_t	_AwsIotShadowSubscriptions = { 0 }
	List of active Shadow subscriptions objects.
IotMutex_t	_AwsIotShadowSubscriptionsMutex
	Protects _AwsIotShadowSubscriptions from concurrent access.

Detailed Description

Implements functions for interacting with the Shadow library's subscription list.

Function Documentation

_shadowSubscription_match()

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

static

Match two _shadowSubscription_t by Thing Name.

Parameters

[in]	pSubscriptionLink	Pointer to the link member of a _shadowSubscription_t containing the Thing Name to check.
[in]	pMatch	Pointer to an AwsIotThingName_t.

Returns

true if the Thing Names match; false otherwise.

_AwsIotShadow_FindSubscription()

_shadowSubscription_t* _AwsIotShadow_FindSubscription	(	const char *	pThingName,
		size_t	thingNameLength,
		bool	createIfNotFound
	)

Find a Shadow subscription object. May create a new subscription object and adds it to the subscription list if not found.

Parameters

[in]	pThingName	Thing Name in the subscription object.
[in]	thingNameLength	Length of pThingName.
[in]	createIfNotFound	If true, attempt to create a new subscription object if no match is found.

Returns

Pointer to a Shadow subscription object, either found or newly allocated. Returns NULL if no subscription object is found and a new subscription object could not be allocated.

Note

This function should be called with the subscription list mutex locked.

_AwsIotShadow_RemoveSubscription()

void _AwsIotShadow_RemoveSubscription	(	_shadowSubscription_t *	pSubscription,
		_shadowSubscription_t **	pRemovedSubscription
	)

Remove a Shadow subscription object from the subscription list if unreferenced.

Parameters

[in]	pSubscription	Subscription object to check. If this object has no active references, it is removed from the subscription list.
[out]	pRemovedSubscription	Removed subscription object, if any. Optional; pass NULL to ignore. If not NULL, this parameter will be set to the removed subscription and that subscription will not be destroyed.

Note

This function should be called with the subscription list mutex locked.

_AwsIotShadow_DestroySubscription()

void _AwsIotShadow_DestroySubscription

(

void *

pData

)

Free resources used for a Shadow subscription object.

Parameters

[in]

pData

The subscription object to destroy. This parameter is of type void* to match the signature of free.

_AwsIotShadow_IncrementReferences()

AwsIotShadowError_t _AwsIotShadow_IncrementReferences	(	_shadowOperation_t *	pOperation,
		char *	pTopicBuffer,
		uint16_t	operationTopicLength,
		AwsIotMqttCallbackFunction_t	callback
	)

Increment the reference count of a Shadow subscriptions object.

Also adds MQTT subscriptions if necessary.

Parameters

[in]	pOperation	The operation for which the reference count should be incremented.
[in]	pTopicBuffer	Topic buffer containing the operation topic, used if subscriptions need to be added.
[in]	operationTopicLength	The length of the operation topic in pTopicBuffer.
[in]	callback	MQTT callback function for when this operation completes.

Warning

This function does not check the length of pTopicBuffer! Any provided buffer must already contain the Shadow operation topic, plus enough space for the status suffix.

Returns

AWS_IOT_SHADOW_SUCCESS on success. On error, one of AWS_IOT_SHADOW_NO_MEMORY or AWS_IOT_SHADOW_MQTT_ERROR.

Note

This function should be called with the subscription list mutex locked.

_AwsIotShadow_DecrementReferences()

void _AwsIotShadow_DecrementReferences	(	_shadowOperation_t *	pOperation,
		char *	pTopicBuffer,
		_shadowSubscription_t **	pRemovedSubscription
	)

Decrement the reference count of a Shadow subscriptions object.

Also removed MQTT subscriptions and deletes the subscription object if necessary.

Parameters

[in]	pOperation	The operation for which the reference count should be decremented.
[in]	pTopicBuffer	Topic buffer containing the operation topic, used if subscriptions need to be removed.
[out]	pRemovedSubscription	Set to point to a removed subscription. Optional; pass NULL to ignore. If not NULL, this function will not destroy a removed subscription.

Warning

This function does not check the length of pTopicBuffer! Any provided buffer must be large enough to accommodate the full Shadow topic, plus SHADOW_LONGEST_SUFFIX_LENGTH.

Note

This function should be called with the subscription list mutex locked.

AwsIotShadow_RemovePersistentSubscriptions()

AwsIotShadowError_t AwsIotShadow_RemovePersistentSubscriptions	(	IotMqttConnection_t	mqttConnection,
		const char *	pThingName,
		size_t	thingNameLength,
		uint32_t	flags
	)

Remove persistent Thing Shadow operation topic subscriptions.

Passing the flag AWS_IOT_SHADOW_FLAG_KEEP_SUBSCRIPTIONS to AwsIotShadow_DeleteAsync, AwsIotShadow_GetAsync, AwsIotShadow_UpdateAsync, or their blocking versions. causes the Shadow operation topic subscriptions to be maintained for future calls to the same function. If a persistent subscription for a Shadow topic are no longer needed, this function may be used to remove it.

Parameters

[in]	mqttConnection	The MQTT connection associated with the persistent subscription.
[in]	pThingName	The Thing Name associated with the persistent subscription.
[in]	thingNameLength	The length of pThingName.
[in]	flags	Flags that determine which subscriptions to remove. Valid values are the bitwise OR of the following individual flags: AWS_IOT_SHADOW_FLAG_REMOVE_DELETE_SUBSCRIPTIONS AWS_IOT_SHADOW_FLAG_REMOVE_GET_SUBSCRIPTIONS AWS_IOT_SHADOW_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS

Returns

On success:

• AWS_IOT_SHADOW_SUCCESS

If an MQTT UNSUBSCRIBE packet cannot be sent, one of the following:

• AWS_IOT_SHADOW_NO_MEMORY
• AWS_IOT_SHADOW_MQTT_ERROR

Note

AwsIotShadow_Cleanup removes all persistent subscriptions as well.

Warning

This function is not safe to call with any in-progress operations! It also does not affect delta and updated callbacks registered with AwsIotShadow_SetDeltaCallback and AwsIotShadow_SetUpdatedCallback, respectively. (See documentation for those functions on how to remove their callbacks).