Implements functions that process Shadow operations. More...

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

Data Structures
struct	_operationMatchParams_t
	First parameter to _shadowOperationMatch. More...

Functions
static bool	_shadowOperationMatch (const IotLink_t pOperationLink, void pMatch)
	Match a received Shadow response with a Shadow operation awaiting a response. More...

static void	_commonOperationCallback (_shadowOperationType_t type, IotMqttCallbackParam_t *pMessage)
	Common function for processing received Shadow responses. More...

static void	_deleteCallback (void pArgument, IotMqttCallbackParam_t pMessage)
	Invoked when a Shadow response is received for Shadow DELETE. More...

static void	_getCallback (void pArgument, IotMqttCallbackParam_t pMessage)
	Invoked when a Shadow response is received for a Shadow GET. More...

static AwsIotShadowError_t	_processAcceptedGet (_shadowOperation_t pOperation, const IotMqttPublishInfo_t pPublishInfo)
	Process an incoming Shadow document received when a Shadow GET is accepted. More...

static void	_updateCallback (void pArgument, IotMqttCallbackParam_t pMessage)
	Invoked when a Shadow response is received for a Shadow UPDATE. More...

static void	_notifyCompletion (_shadowOperation_t *pOperation)
	Notify of a completed Shadow operation. More...

static AwsIotShadowError_t	_findSubscription (const char pThingName, size_t thingNameLength, char pTopicBuffer, uint16_t operationTopicLength, _shadowOperation_t pOperation, bool pFreeTopicBuffer)
	Get a Shadow subscription to use with a Shadow operation. More...

_shadowOperationType_t	_AwsIotShadow_IntToShadowOperationType (uint32_t n)
	Convert an integer to the shadow operation type. More...

AwsIotShadowCallbackType_t	_AwsIotShadow_IntToShadowCallbackType (uint32_t n)
	Convert an integer to the shadow callback type. More...

AwsIotShadowError_t	_AwsIotShadow_CreateOperation (_shadowOperation_t *pNewOperation, _shadowOperationType_t type, uint32_t flags, const AwsIotShadowCallbackInfo_t pCallbackInfo)
	Create a record for a new in-progress Shadow operation. More...

void	_AwsIotShadow_DestroyOperation (void *pData)
	Free resources used to record a Shadow operation. This is called when the operation completes. More...

AwsIotShadowError_t	_AwsIotShadow_GenerateShadowTopic (_shadowOperationType_t type, const char pThingName, size_t thingNameLength, char pTopicBuffer, uint16_t pOperationTopicLength)
	Fill a buffer with a Shadow topic. More...

AwsIotShadowError_t	_AwsIotShadow_ProcessOperation (IotMqttConnection_t mqttConnection, const char pThingName, size_t thingNameLength, _shadowOperation_t pOperation, const AwsIotShadowDocumentInfo_t *pDocumentInfo)
	Process a Shadow operation by sending the necessary MQTT packets. More...

Variables
IotListDouble_t	_AwsIotShadowPendingOperations = { 0 }
	List of active Shadow operations awaiting a response from the Shadow service.

IotMutex_t	_AwsIotShadowPendingOperationsMutex
	Protects _AwsIotShadowPendingOperations from concurrent access.

Detailed Description

Implements functions that process Shadow operations.

Function Documentation

◆ _shadowOperationMatch()

static bool _shadowOperationMatch	(	const IotLink_t *	pOperationLink,
		void *	pMatch
	)

static

Match a received Shadow response with a Shadow operation awaiting a response.

Parameters

[in]	pOperationLink	Pointer to the link member of the _shadowOperation_t to check.
[in]	pMatch	Pointer to an _operationMatchParams_t.

Returns: true if pMatch matches the received response; false otherwise.

◆ _commonOperationCallback()

static void _commonOperationCallback	(	_shadowOperationType_t	type,
		IotMqttCallbackParam_t *	pMessage
	)

static

Common function for processing received Shadow responses.

Parameters

[in]	type	DELETE, GET, or UPDATE.
[in]	pMessage	Received Shadow response (as an MQTT PUBLISH message).

◆ _deleteCallback()

static void _deleteCallback	(	void *	pArgument,
		IotMqttCallbackParam_t *	pMessage
	)

static

Invoked when a Shadow response is received for Shadow DELETE.

Parameters

[in]	pArgument	Ignored.
[in]	pMessage	Received Shadow response (as an MQTT PUBLISH message).

◆ _getCallback()

static void _getCallback	(	void *	pArgument,
		IotMqttCallbackParam_t *	pMessage
	)

static

Invoked when a Shadow response is received for a Shadow GET.

Parameters

[in]	pArgument	Ignored.
[in]	pMessage	Received Shadow response (as an MQTT PUBLISH message).

◆ _processAcceptedGet()

static AwsIotShadowError_t _processAcceptedGet	(	_shadowOperation_t *	pOperation,
		const IotMqttPublishInfo_t *	pPublishInfo
	)

static

Process an incoming Shadow document received when a Shadow GET is accepted.

Parameters

[in]	pOperation	The GET operation associated with the incoming Shadow document.
[in]	pPublishInfo	The received Shadow document (as an MQTT PUBLISH message).

Returns: AWS_IOT_SHADOW_SUCCESS or AWS_IOT_SHADOW_NO_MEMORY. Memory allocation only happens for a waitable pOperation.

◆ _updateCallback()

static void _updateCallback	(	void *	pArgument,
		IotMqttCallbackParam_t *	pMessage
	)

static

Invoked when a Shadow response is received for a Shadow UPDATE.

Parameters

[in]	pArgument	Ignored.
[in]	pMessage	Received Shadow response (as an MQTT PUBLISH message).

◆ _notifyCompletion()

static void _notifyCompletion ( _shadowOperation_t * pOperation )

static

Notify of a completed Shadow operation.

Parameters

[in] pOperation The operation which completed.

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

◆ _findSubscription()

static AwsIotShadowError_t _findSubscription	(	const char *	pThingName,
		size_t	thingNameLength,
		char *	pTopicBuffer,
		uint16_t	operationTopicLength,
		_shadowOperation_t *	pOperation,
		bool *	pFreeTopicBuffer
	)

static

Get a Shadow subscription to use with a Shadow operation.

This function may use an existing Shadow subscription, or it may allocate a new one.

Parameters

[in]	pThingName	Thing Name associated with operation.
[in]	thingNameLength	Length of `pThingName`.
[in]	pTopicBuffer	Contains the topic to use for subscribing.
[in]	operationTopicLength	The length of the base topic in `pTopicBuffer`.
[in]	pOperation	Shadow operation that needs a subscription.
[out]	pFreeTopicBuffer	Whether the caller may free `pTopicBuffer` (which may be assigned to a subscription).

Returns: AWS_IOT_SHADOW_SUCCESS or AWS_IOT_SHADOW_NO_MEMORY

◆ _AwsIotShadow_IntToShadowOperationType()

_shadowOperationType_t _AwsIotShadow_IntToShadowOperationType ( uint32_t n )

Convert an integer to the shadow operation type.

Parameters

[in] n The integer to convert.

Returns: The enum value associated with the input.

◆ _AwsIotShadow_IntToShadowCallbackType()

AwsIotShadowCallbackType_t _AwsIotShadow_IntToShadowCallbackType ( uint32_t n )

Convert an integer to the shadow callback type.

Parameters

[in] n The integer to convert.

Returns: The enum value associated with the input.

◆ _AwsIotShadow_CreateOperation()

AwsIotShadowError_t _AwsIotShadow_CreateOperation	(	_shadowOperation_t **	pNewOperation,
		_shadowOperationType_t	type,
		uint32_t	flags,
		const AwsIotShadowCallbackInfo_t *	pCallbackInfo
	)

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

Parameters

[out]	pNewOperation	Set to point to the new operation on success.
[in]	type	The type of Shadow operation.
[in]	flags	Flags variables passed to a user-facing Shadow function.
[in]	pCallbackInfo	User-provided callback function and parameter.

Returns: AWS_IOT_SHADOW_SUCCESS or AWS_IOT_SHADOW_NO_MEMORY

◆ _AwsIotShadow_DestroyOperation()

void _AwsIotShadow_DestroyOperation ( void * pData )

Free resources used to record a Shadow operation. This is called when the operation completes.

Parameters

[in] pData The operation which completed. This parameter is of type void* to match the signature of free.

◆ _AwsIotShadow_GenerateShadowTopic()

AwsIotShadowError_t _AwsIotShadow_GenerateShadowTopic	(	_shadowOperationType_t	type,
		const char *	pThingName,
		size_t	thingNameLength,
		char **	pTopicBuffer,
		uint16_t *	pOperationTopicLength
	)

Fill a buffer with a Shadow topic.

Parameters

[in]	type	One of: DELETE, GET, UPDATE.
[in]	pThingName	Thing Name to place in the topic.
[in]	thingNameLength	Length of `pThingName`.
[out]	pTopicBuffer	Address of the buffer for the Shadow topic. If the pointer at this address is `NULL`, this function will allocate a new buffer; otherwise, it will use the provided buffer.
[out]	pOperationTopicLength	Length of the Shadow operation topic (excluding any suffix) placed in `pTopicBuffer`.

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.

Returns: AWS_IOT_SHADOW_SUCCESS or AWS_IOT_SHADOW_NO_MEMORY. This function will not return AWS_IOT_SHADOW_NO_MEMORY when a buffer is provided.

◆ _AwsIotShadow_ProcessOperation()

AwsIotShadowError_t _AwsIotShadow_ProcessOperation	(	IotMqttConnection_t	mqttConnection,
		const char *	pThingName,
		size_t	thingNameLength,
		_shadowOperation_t *	pOperation,
		const AwsIotShadowDocumentInfo_t *	pDocumentInfo
	)

Process a Shadow operation by sending the necessary MQTT packets.

Parameters

[in]	mqttConnection	The MQTT connection to use.
[in]	pThingName	Thing Name for the Shadow operation.
[in]	thingNameLength	Length of `pThingName`.
[in]	pOperation	Operation data to process.
[in]	pDocumentInfo	Information on the Shadow document for GET or UPDATE operations.

Returns: AWS_IOT_SHADOW_STATUS_PENDING on success. On error, one of AWS_IOT_SHADOW_NO_MEMORY or AWS_IOT_SHADOW_MQTT_ERROR.

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ _shadowOperationMatch()

◆ _commonOperationCallback()

◆ _deleteCallback()

◆ _getCallback()

◆ _processAcceptedGet()

◆ _updateCallback()

◆ _notifyCompletion()

◆ _findSubscription()

◆ _AwsIotShadow_IntToShadowOperationType()

◆ _AwsIotShadow_IntToShadowCallbackType()

◆ _AwsIotShadow_CreateOperation()

◆ _AwsIotShadow_DestroyOperation()

◆ _AwsIotShadow_GenerateShadowTopic()

◆ _AwsIotShadow_ProcessOperation()