Internal header of Shadow library. This header should not be included in typical application code. More...

#include "iot_config.h"
#include "iot_linear_containers.h"
#include "types/iot_platform_types.h"
#include "aws_iot_shadow.h"
#include "aws_iot.h"
#include "iot_logging_setup.h"
#include "iot_static_memory.h"

Data Structures
struct	_shadowSubscription_t
	Represents a Shadow subscriptions object. More...

struct	_shadowOperation_t
	Internal structure representing a single Shadow operation (DELETE, GET, or UPDATE). More...

Macros
#define	AwsIotShadow_Assert(expression)
	Assertion macro for the Shadow library. More...

#define	AwsIotShadow_MallocString Iot_MallocMessageBuffer
	Allocate a buffer for a short string, used for topic names or client tokens. This function should have the same signature as malloc.

#define	AwsIotShadow_FreeString Iot_FreeMessageBuffer
	Free a string. This function should have the same signature as free.

#define	SHADOW_OPERATION_COUNT ( 3U )
	The number of currently available Shadow operations. More...

#define	SHADOW_CALLBACK_COUNT ( 2 )
	The number of currently available Shadow callbacks. More...

#define	SHADOW_DELETE_OPERATION_STRING "/shadow/delete"
	The string representing a Shadow DELETE operation in a Shadow MQTT topic.

#define	SHADOW_DELETE_OPERATION_STRING_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_DELETE_OPERATION_STRING ) - 1U ) )
	The length of SHADOW_DELETE_OPERATION_STRING.

#define	SHADOW_GET_OPERATION_STRING "/shadow/get"
	The string representing a Shadow GET operation in a Shadow MQTT topic.

#define	SHADOW_GET_OPERATION_STRING_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_GET_OPERATION_STRING ) - 1U ) )
	The length of SHADOW_GET_OPERATION_STRING.

#define	SHADOW_UPDATE_OPERATION_STRING "/shadow/update"
	The string representing a Shadow UPDATE operation in a Shadow MQTT topic.

#define	SHADOW_UPDATE_OPERATION_STRING_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_UPDATE_OPERATION_STRING ) - 1U ) )
	The length of SHADOW_UPDATE_OPERATION_STRING.

#define	SHADOW_DELTA_SUFFIX "/delta"
	The suffix for a Shadow delta topic.

#define	SHADOW_DELTA_SUFFIX_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_DELTA_SUFFIX ) - 1U ) )
	The length of SHADOW_DELTA_SUFFIX.

#define	SHADOW_UPDATED_SUFFIX "/documents"
	The suffix for a Shadow updated topic.

#define	SHADOW_UPDATED_SUFFIX_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_UPDATED_SUFFIX ) - 1U ) )
	The length of SHADOW_UPDATED_SUFFIX.

#define	SHADOW_LONGEST_SUFFIX_LENGTH SHADOW_UPDATED_SUFFIX_LENGTH
	The length of the longest Shadow suffix.

#define	SHADOW_CONVERT_STATUS_CODE_MQTT_TO_SHADOW(X)
	The macro to convert MQTT error codes to Shadow error codes. Below are the conversions happening. IOT_MQTT_SUCCESS to AWS_IOT_SHADOW_SUCCESS IOT_MQTT_NO_MEMORY to AWS_IOT_SHADOW_NO_MEMORY all other error codes to AWS_IOT_SHADOW_MQTT_ERROR. More...

Enumerations
enum	_shadowOperationType_t { SHADOW_DELETE = 0, SHADOW_GET = 1, SHADOW_UPDATE = 2, SET_DELTA_CALLBACK = 3, SET_UPDATED_CALLBACK = 4 }
	Enumerations representing each of the Shadow library's API functions. More...

enum	_shadowCallbackType_t { DELTA_CALLBACK = 0, UPDATED_CALLBACK = 1 }
	Enumerations representing each of the Shadow callback functions. More...

Functions
void *	AwsIotShadow_MallocOperation (size_t size)
	Allocate a _shadowOperation_t. This function should have the same signature as malloc.

void	AwsIotShadow_FreeOperation (void *ptr)
	Free a _shadowOperation_t. This function should have the same signature as free.

void *	AwsIotShadow_MallocSubscription (size_t size)
	Allocate a _shadowSubscription_t. This function should have the same signature as malloc.

void	AwsIotShadow_FreeSubscription (void *ptr)
	Free a _shadowSubscription_t. This function should have the same signature as free.

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...

_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...

_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_ParseErrorDocument (const char *pErrorDocument, size_t errorDocumentLength)
	Parse a Shadow error document. More...

Variables
uint32_t	_AwsIotShadowMqttTimeoutMs
	Timeout used for MQTT operations.

IotListDouble_t	_AwsIotShadowPendingOperations
	List of active Shadow operations awaiting a response from the Shadow service.

IotListDouble_t	_AwsIotShadowSubscriptions
	List of active Shadow subscriptions objects.

IotMutex_t	_AwsIotShadowPendingOperationsMutex
	Protects _AwsIotShadowPendingOperations from concurrent access.

IotMutex_t	_AwsIotShadowSubscriptionsMutex
	Protects _AwsIotShadowSubscriptions from concurrent access.

Detailed Description

Internal header of Shadow library. This header should not be included in typical application code.

Macro Definition Documentation

◆ AwsIotShadow_Assert

#define AwsIotShadow_Assert ( expression )

Assertion macro for the Shadow library.

Set AWS_IOT_SHADOW_ENABLE_ASSERTS to 1 to enable assertions in the Shadow library.

Parameters

[in] expression Expression to be evaluated.

◆ SHADOW_OPERATION_COUNT

#define SHADOW_OPERATION_COUNT ( 3U )

The number of currently available Shadow operations.

The 3 Shadow operations are DELETE, GET, and UPDATE.

◆ SHADOW_CALLBACK_COUNT

#define SHADOW_CALLBACK_COUNT ( 2 )

The number of currently available Shadow callbacks.

The 2 Shadow callbacks are update/delta (AKA "Delta") and /update/documents (AKA "Updated").

◆ SHADOW_CONVERT_STATUS_CODE_MQTT_TO_SHADOW

#define SHADOW_CONVERT_STATUS_CODE_MQTT_TO_SHADOW ( X )

Value:

( ( X ) == IOT_MQTT_SUCCESS ) ? AWS_IOT_SHADOW_SUCCESS :     \
    ( ( X ) == IOT_MQTT_NO_MEMORY ) ? AWS_IOT_SHADOW_NO_MEMORY : \
    AWS_IOT_SHADOW_MQTT_ERROR

The macro to convert MQTT error codes to Shadow error codes. Below are the conversions happening. IOT_MQTT_SUCCESS to AWS_IOT_SHADOW_SUCCESS IOT_MQTT_NO_MEMORY to AWS_IOT_SHADOW_NO_MEMORY all other error codes to AWS_IOT_SHADOW_MQTT_ERROR.

Enumeration Type Documentation

◆ _shadowOperationType_t

enum _shadowOperationType_t

Enumerations representing each of the Shadow library's API functions.

Enumerator
SHADOW_DELETE	AwsIotShadow_DeleteAsync
SHADOW_GET	AwsIotShadow_GetAsync
SHADOW_UPDATE	AwsIotShadow_UpdateAsync
SET_DELTA_CALLBACK	AwsIotShadow_SetDeltaCallback
SET_UPDATED_CALLBACK	AwsIotShadow_SetUpdatedCallback

◆ _shadowCallbackType_t

enum _shadowCallbackType_t

Enumerations representing each of the Shadow callback functions.

Enumerator
DELTA_CALLBACK	Delta callback.
UPDATED_CALLBACK	Updated callback.

Function Documentation

◆ _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.

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

AwsIotShadowError_t _AwsIotShadow_ParseErrorDocument	(	const char *	pErrorDocument,
		size_t	errorDocumentLength
	)

Parse a Shadow error document.

Parameters

[in]	pErrorDocument	The error document to parse.
[in]	errorDocumentLength	The length of `pErrorDocument`.

Returns: One of the AwsIotShadowError_t ranging from 400 to 500 on success. AWS_IOT_SHADOW_BAD_RESPONSE on error.

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ AwsIotShadow_Assert

◆ SHADOW_OPERATION_COUNT

◆ SHADOW_CALLBACK_COUNT

◆ SHADOW_CONVERT_STATUS_CODE_MQTT_TO_SHADOW

Enumeration Type Documentation

◆ _shadowOperationType_t

◆ _shadowCallbackType_t

Function Documentation

◆ _AwsIotShadow_CreateOperation()

◆ _AwsIotShadow_DestroyOperation()

◆ _AwsIotShadow_GenerateShadowTopic()

◆ _AwsIotShadow_ProcessOperation()

◆ _AwsIotShadow_IntToShadowOperationType()

◆ _AwsIotShadow_IntToShadowCallbackType()

◆ _AwsIotShadow_FindSubscription()

◆ _AwsIotShadow_RemoveSubscription()

◆ _AwsIotShadow_DestroySubscription()

◆ _AwsIotShadow_IncrementReferences()

◆ _AwsIotShadow_DecrementReferences()

◆ _AwsIotShadow_ParseErrorDocument()