User-facing functions of the Shadow library. More...

#include "iot_config.h"
#include "types/aws_iot_shadow_types.h"

Functions
AwsIotShadowError_t	AwsIotShadow_Init (uint32_t mqttTimeoutMs)
	One-time initialization function for the Shadow library. More...

void	AwsIotShadow_Cleanup (void)
	One-time deinitialization function for the Shadow library. More...

AwsIotShadowError_t	AwsIotShadow_DeleteAsync (IotMqttConnection_t mqttConnection, const char pThingName, size_t thingNameLength, uint32_t flags, const AwsIotShadowCallbackInfo_t pCallbackInfo, AwsIotShadowOperation_t *const pDeleteOperation)
	Delete a Thing Shadow and receive an asynchronous notification when the Delete completes. More...

AwsIotShadowError_t	AwsIotShadow_DeleteSync (IotMqttConnection_t mqttConnection, const char *pThingName, size_t thingNameLength, uint32_t flags, uint32_t timeoutMs)
	Delete a Thing Shadow with a timeout. More...

AwsIotShadowError_t	AwsIotShadow_GetAsync (IotMqttConnection_t mqttConnection, const AwsIotShadowDocumentInfo_t pGetInfo, uint32_t flags, const AwsIotShadowCallbackInfo_t pCallbackInfo, AwsIotShadowOperation_t *const pGetOperation)
	Retrieve a Thing Shadow and receive an asynchronous notification when the Shadow document is received. More...

AwsIotShadowError_t	AwsIotShadow_GetSync (IotMqttConnection_t mqttConnection, const AwsIotShadowDocumentInfo_t pGetInfo, uint32_t flags, uint32_t timeoutMs, const char const pShadowDocument, size_t const pShadowDocumentLength)
	Retrieve a Thing Shadow with a timeout. More...

AwsIotShadowError_t	AwsIotShadow_UpdateAsync (IotMqttConnection_t mqttConnection, const AwsIotShadowDocumentInfo_t pUpdateInfo, uint32_t flags, const AwsIotShadowCallbackInfo_t pCallbackInfo, AwsIotShadowOperation_t *const pUpdateOperation)
	Send a Thing Shadow update and receive an asynchronous notification when the Shadow Update completes. More...

AwsIotShadowError_t	AwsIotShadow_UpdateSync (IotMqttConnection_t mqttConnection, const AwsIotShadowDocumentInfo_t *pUpdateInfo, uint32_t flags, uint32_t timeoutMs)
	Send a Thing Shadow update with a timeout. More...

AwsIotShadowError_t	AwsIotShadow_Wait (AwsIotShadowOperation_t operation, uint32_t timeoutMs, const char *const pShadowDocument, size_t const pShadowDocumentLength)
	Wait for a Shadow operation to complete. More...

AwsIotShadowError_t	AwsIotShadow_SetDeltaCallback (IotMqttConnection_t mqttConnection, const char pThingName, size_t thingNameLength, uint32_t flags, const AwsIotShadowCallbackInfo_t pDeltaCallback)
	Set a callback to be invoked when the Thing Shadow `desired` and `reported` states differ. More...

AwsIotShadowError_t	AwsIotShadow_SetUpdatedCallback (IotMqttConnection_t mqttConnection, const char pThingName, size_t thingNameLength, uint32_t flags, const AwsIotShadowCallbackInfo_t pUpdatedCallback)
	Set a callback to be invoked when a Thing Shadow changes. 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...

const char *	AwsIotShadow_strerror (AwsIotShadowError_t status)
	Returns a string that describes an AwsIotShadowError_t. More...

Detailed Description

User-facing functions of the Shadow library.

Function Documentation

◆ AwsIotShadow_Init()

AwsIotShadowError_t AwsIotShadow_Init ( uint32_t mqttTimeoutMs )

One-time initialization function for the Shadow library.

This function performs internal setup of the Shadow library. It must be called once (and only once) before calling any other Shadow function. Calling this function more than once without first calling AwsIotShadow_Cleanup may result in a crash.

Parameters

[in] mqttTimeoutMs The amount of time (in milliseconds) that the Shadow library will wait for MQTT operations. Optional; set this to 0 to use AWS_IOT_SHADOW_DEFAULT_MQTT_TIMEOUT_MS.

Returns

One of the following:

Warning: No thread-safety guarantees are provided for this function.

See also: AwsIotShadow_Cleanup

◆ AwsIotShadow_Cleanup()

void AwsIotShadow_Cleanup ( void )

One-time deinitialization function for the Shadow library.

This function frees resources taken in AwsIotShadow_Init and deletes any persistent subscriptions. It should be called to clean up the Shadow library. After this function returns, AwsIotShadow_Init must be called again before calling any other Shadow function.

Warning: No thread-safety guarantees are provided for this function.

See also: AwsIotShadow_Init

◆ AwsIotShadow_DeleteAsync()

AwsIotShadowError_t AwsIotShadow_DeleteAsync	(	IotMqttConnection_t	mqttConnection,
		const char *	pThingName,
		size_t	thingNameLength,
		uint32_t	flags,
		const AwsIotShadowCallbackInfo_t *	pCallbackInfo,
		AwsIotShadowOperation_t *const	pDeleteOperation
	)

Delete a Thing Shadow and receive an asynchronous notification when the Delete completes.

This function deletes any existing Shadow document for the given Thing Name. If the given Thing has no Shadow and this function is called, the result will be AWS_IOT_SHADOW_NOT_FOUND.

Deleting a Shadow involves sending an MQTT message to AWS IoT and waiting on a response. This message will always be sent at MQTT QoS 0.

Parameters

[in]	mqttConnection	The MQTT connection to use for Shadow delete.
[in]	pThingName	The Thing Name associated with the Shadow to delete.
[in]	thingNameLength	The length of `pThingName`.
[in]	flags	Flags which modify the behavior of this function. See Shadow Function Flags.
[in]	pCallbackInfo	Asynchronous notification of this function's completion.
[out]	pDeleteOperation	Set to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the Shadow delete completes.

Returns

This function will return AWS_IOT_SHADOW_STATUS_PENDING upon successfully queuing a Shadow delete.

If this function fails before queuing a Shadow delete, it will return one of:

Upon successful completion of the Shadow delete (either through an AwsIotShadowCallbackInfo_t or AwsIotShadow_Wait), the status will be AWS_IOT_SHADOW_SUCCESS.

Should the Shadow delete fail, the status will be one of:

AWS_IOT_SHADOW_MQTT_ERROR
AWS_IOT_SHADOW_BAD_RESPONSE
A Shadow service rejection reason between 400 (AWS_IOT_SHADOW_BAD_REQUEST) and 500 (AWS_IOT_SHADOW_SERVER_ERROR)

See also: AwsIotShadow_DeleteSync for a blocking variant of this function.

Example

#define THING_NAME "Test_device"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )
// Shadow operation handle.
AwsIotShadowOperation_t deleteOperation = AWS_IOT_SHADOW_OPERATION_INITIALIZER;
// Queue a Shadow delete.
AwsIotShadowError_t deleteResult = AwsIotShadow_DeleteAsync( mqttConnection,
                                                             THING_NAME,
                                                             THING_NAME_LENGTH,
                                                             AWS_IOT_SHADOW_FLAG_WAITABLE,
                                                             NULL,
                                                             &deleteOperation );
// Shadow delete should return AWS_IOT_SHADOW_STATUS_PENDING upon success.
if( deleteResult == AWS_IOT_SHADOW_STATUS_PENDING )
{
    // Wait for the Shadow delete to complete.
    deleteResult = AwsIotShadow_Wait( deleteOperation, 5000 );
    // Delete result should be AWS_IOT_SHADOW_SUCCESS upon successfully
    // deleting an existing Shadow.
}

◆ AwsIotShadow_DeleteSync()

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

Delete a Thing Shadow with a timeout.

This function queues a Shadow delete, then waits for the result. Internally, this function is a call to AwsIotShadow_DeleteAsync followed by AwsIotShadow_Wait. See AwsIotShadow_DeleteAsync for more information on the Shadow delete operation.

Parameters

[in]	mqttConnection	The MQTT connection to use for Shadow delete.
[in]	pThingName	The Thing Name associated with the Shadow to delete.
[in]	thingNameLength	The length of `pThingName`.
[in]	flags	Flags which modify the behavior of this function. See Shadow Function Flags.
[in]	timeoutMs	If the Shadow service does not respond to the Shadow delete within this timeout, this function returns AWS_IOT_SHADOW_TIMEOUT.

Returns

One of the following:

AWS_IOT_SHADOW_SUCCESS
AWS_IOT_SHADOW_NOT_INITIALIZED
AWS_IOT_SHADOW_BAD_PARAMETER
AWS_IOT_SHADOW_NO_MEMORY
AWS_IOT_SHADOW_MQTT_ERROR
AWS_IOT_SHADOW_BAD_RESPONSE
AWS_IOT_SHADOW_TIMEOUT
A Shadow service rejection reason between 400 (AWS_IOT_SHADOW_BAD_REQUEST) and 500 (AWS_IOT_SHADOW_SERVER_ERROR)

◆ AwsIotShadow_GetAsync()

AwsIotShadowError_t AwsIotShadow_GetAsync	(	IotMqttConnection_t	mqttConnection,
		const AwsIotShadowDocumentInfo_t *	pGetInfo,
		uint32_t	flags,
		const AwsIotShadowCallbackInfo_t *	pCallbackInfo,
		AwsIotShadowOperation_t *const	pGetOperation
	)

Retrieve a Thing Shadow and receive an asynchronous notification when the Shadow document is received.

This function retrieves the Thing Shadow document currently stored by the Shadow service. If a given Thing has no Shadow and this function is called, the result will be AWS_IOT_SHADOW_NOT_FOUND.

Shadow documents may be large, and their size is not known beforehand. Therefore, this function works best when memory is dynamically allocated. Because the Shadow document is retrieved in an MQTT PUBLISH packet, the MQTT library will allocate a buffer for the Shadow document using IotMqtt_MallocMessage.

The MQTT library may free the buffer for a retrieved Shadow document as soon as the Shadow completion callback returns. Therefore, any data needed later must be copied from the Shadow document. Similarly, if the flag AWS_IOT_SHADOW_FLAG_WAITABLE is given to this function (which indicates that the Shadow document will be needed after the Shadow operation completes), AwsIotShadowDocumentInfo_t.mallocDocument must be provided to allocate a longer-lasting buffer.

Note: Because of the potentially large size of complete Shadow documents, it is more memory-efficient for most applications to use delta callbacks to retrieve Shadows from the Shadow service.

Parameters

[in]	mqttConnection	The MQTT connection to use for Shadow get.
[in]	pGetInfo	Shadow document parameters.
[in]	flags	Flags which modify the behavior of this function. See Shadow Function Flags.
[in]	pCallbackInfo	Asynchronous notification of this function's completion.
[out]	pGetOperation	Set to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the Shadow get completes.

Returns

This function will return AWS_IOT_SHADOW_STATUS_PENDING upon successfully queuing a Shadow get.

If this function fails before queuing a Shadow get, it will return one of:

Upon successful completion of the Shadow get (either through an AwsIotShadowCallbackInfo_t or AwsIotShadow_Wait), the status will be AWS_IOT_SHADOW_SUCCESS.

Should the Shadow get fail, the status will be one of:

AWS_IOT_SHADOW_NO_MEMORY (Memory could not be allocated for incoming document)
AWS_IOT_SHADOW_MQTT_ERROR
AWS_IOT_SHADOW_BAD_RESPONSE
A Shadow service rejection reason between 400 (AWS_IOT_SHADOW_BAD_REQUEST) and 500 (AWS_IOT_SHADOW_SERVER_ERROR)

See also: AwsIotShadow_GetSync for a blocking variant of this function.

Example

// Shadow get completion callback. The retrieved document will be in
// pCallbackParam. Any data in the retrieved document needed after this
// function returns must be copied.
void _processRetrievedDocument( void * pCallbackContext,
                                AwsIotShadowCallbackParam_t * pCallbackParam );
// Parameters and return value of Shadow get.
AwsIotShadowError_t result = AWS_IOT_SHADOW_STATUS_PENDING;
AwsIotShadowDocumentInfo_t getInfo = { ... };
uint32_t timeout = 5000; // 5 seconds
// Callback for get completion.
AwsIotShadowCallbackInfo_t getCallback = AWS_IOT_SHADOW_CALLBACK_INFO_INITIALIZER;
getCallback.function = _processRetrievedDocument;
// Shadow get operation.
result = AwsIotShadow_GetAsync( mqttConnection,
                                &getInfo,
                                0,
                                &getCallback,
                                NULL );
// Get should have returned AWS_IOT_SHADOW_STATUS_PENDING. The function
// _processRetrievedDocument will be invoked once the Shadow get completes.

See AwsIotShadow_Wait Example 2 for an example of using this function with AWS_IOT_SHADOW_FLAG_WAITABLE and AwsIotShadow_Wait.

◆ AwsIotShadow_GetSync()

AwsIotShadowError_t AwsIotShadow_GetSync	(	IotMqttConnection_t	mqttConnection,
		const AwsIotShadowDocumentInfo_t *	pGetInfo,
		uint32_t	flags,
		uint32_t	timeoutMs,
		const char **const	pShadowDocument,
		size_t *const	pShadowDocumentLength
	)

Retrieve a Thing Shadow with a timeout.

This function queues a Shadow get, then waits for the result. Internally, this function is a call to AwsIotShadow_GetAsync followed by AwsIotShadow_Wait. See AwsIotShadow_GetAsync for more information on the Shadow get operation.

Parameters

[in]	mqttConnection	The MQTT connection to use for Shadow get.
[in]	pGetInfo	Shadow document parameters.
[in]	flags	Flags which modify the behavior of this function. See Shadow Function Flags.
[in]	timeoutMs	If the Shadow service does not respond to the Shadow get within this timeout, this function returns AWS_IOT_SHADOW_TIMEOUT.
[out]	pShadowDocument	A pointer to a buffer containing the Shadow document retrieved by a Shadow get is placed here. The buffer was allocated with the function `pGetInfo->get.mallocDocument`. This output parameter is only valid if this function returns AWS_IOT_SHADOW_SUCCESS.
[out]	pShadowDocumentLength	The length of the Shadow document in `pShadowDocument` is placed here. This output parameter is only valid if this function returns AWS_IOT_SHADOW_SUCCESS.

Returns

One of the following:

AWS_IOT_SHADOW_SUCCESS
AWS_IOT_SHADOW_NOT_INITIALIZED
AWS_IOT_SHADOW_BAD_PARAMETER
AWS_IOT_SHADOW_NO_MEMORY
AWS_IOT_SHADOW_MQTT_ERROR
AWS_IOT_SHADOW_BAD_RESPONSE
AWS_IOT_SHADOW_TIMEOUT
A Shadow service rejection reason between 400 (AWS_IOT_SHADOW_BAD_REQUEST) and 500 (AWS_IOT_SHADOW_SERVER_ERROR)

◆ AwsIotShadow_UpdateAsync()

AwsIotShadowError_t AwsIotShadow_UpdateAsync	(	IotMqttConnection_t	mqttConnection,
		const AwsIotShadowDocumentInfo_t *	pUpdateInfo,
		uint32_t	flags,
		const AwsIotShadowCallbackInfo_t *	pCallbackInfo,
		AwsIotShadowOperation_t *const	pUpdateOperation
	)

Send a Thing Shadow update and receive an asynchronous notification when the Shadow Update completes.

This function modifies the Thing Shadow document stored by the Shadow service. If a given Thing has no Shadow and this function is called, then a new Shadow is created.

New JSON keys in the Shadow document will be appended. For example, if the Shadow service currently has a document containing key example1 and this function sends a document only containing key example2, then the resulting document in the Shadow service will contain both example1 and example2.

Existing JSON keys in the Shadow document will be replaced. For example, if the Shadow service currently has a document containing "example1": [0,1,2] and this function sends a document containing key "example1": [1,2,3], then the resulting document in the Shadow service will contain "example1": [1,2,3].

Successful Shadow updates will trigger the Shadow updated callback. If the resulting Shadow document contains different desired and reported keys, then the Shadow delta callback will be triggered as well.

Attention: All documents passed to this function must contain a clientToken. The client token is a string used to distinguish between Shadow updates. They are limited to 64 characters; attempting to use a client token longer than 64 characters will cause the Shadow update to fail. They must be unique at any given time, i.e. they may be reused as long as no two Shadow updates are using the same client token at the same time.

Parameters

[in]	mqttConnection	The MQTT connection to use for Shadow update.
[in]	pUpdateInfo	Shadow document parameters.
[in]	flags	Flags which modify the behavior of this function. See Shadow Function Flags.
[in]	pCallbackInfo	Asynchronous notification of this function's completion.
[out]	pUpdateOperation	Set to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the Shadow update completes.

Returns

This function will return AWS_IOT_SHADOW_STATUS_PENDING upon successfully queuing a Shadow update.

If this function fails before queuing a Shadow update, it will return one of:

Upon successful completion of the Shadow update (either through an AwsIotShadowCallbackInfo_t or AwsIotShadow_Wait), the status will be AWS_IOT_SHADOW_SUCCESS.

Should the Shadow update fail, the status will be one of:

AWS_IOT_SHADOW_MQTT_ERROR
AWS_IOT_SHADOW_BAD_RESPONSE
A Shadow service rejection reason between 400 (AWS_IOT_SHADOW_BAD_REQUEST) and 500 (AWS_IOT_SHADOW_SERVER_ERROR)

See also: AwsIotShadow_UpdateSync for a blocking variant of this function.

Example

// Shadow update completion callback.
void _updateComplete( void * pCallbackContext,
                      AwsIotShadowCallbackParam_t * pCallbackParam );
// Parameters and return value of Shadow update.
AwsIotShadowError_t result = AWS_IOT_SHADOW_STATUS_PENDING;
AwsIotShadowDocumentInfo_t updateInfo = { ... };
uint32_t timeout = 5000; // 5 seconds
// Set Shadow document to send.
updateInfo.update.pUpdateDocument = "{...}"; // Must contain clientToken
updateInfo.update.updateDocumentLength = strlen( updateInfo.update.pUpdateDocument );
// Callback for update completion.
AwsIotShadowCallbackInfo_t updateCallback = AWS_IOT_SHADOW_CALLBACK_INFO_INITIALIZER;
updateCallback.function = _updateComplete;
// Shadow update operation.
result = AwsIotShadow_UpdateAsync( mqttConnection,
                                   &updateInfo,
                                   0,
                                   &updateCallback,
                                   NULL );
// Update should have returned AWS_IOT_SHADOW_STATUS_PENDING. The function
// _updateComplete will be invoked once the Shadow update completes.

See AwsIotShadow_Wait Example 1 for an example of using this function with AWS_IOT_SHADOW_FLAG_WAITABLE and AwsIotShadow_Wait.

◆ AwsIotShadow_UpdateSync()

AwsIotShadowError_t AwsIotShadow_UpdateSync	(	IotMqttConnection_t	mqttConnection,
		const AwsIotShadowDocumentInfo_t *	pUpdateInfo,
		uint32_t	flags,
		uint32_t	timeoutMs
	)

Send a Thing Shadow update with a timeout.

This function queues a Shadow update, then waits for the result. Internally, this function is a call to AwsIotShadow_UpdateAsync followed by AwsIotShadow_Wait. See AwsIotShadow_UpdateAsync for more information on the Shadow update operation.

Parameters

[in]	mqttConnection	The MQTT connection to use for Shadow update.
[in]	pUpdateInfo	Shadow document parameters.
[in]	flags	Flags which modify the behavior of this function. See Shadow Function Flags.
[in]	timeoutMs	If the Shadow service does not respond to the Shadow update within this timeout, this function returns AWS_IOT_SHADOW_TIMEOUT.

Returns

One of the following:

AWS_IOT_SHADOW_SUCCESS
AWS_IOT_SHADOW_NOT_INITIALIZED
AWS_IOT_SHADOW_BAD_PARAMETER
AWS_IOT_SHADOW_NO_MEMORY
AWS_IOT_SHADOW_MQTT_ERROR
AWS_IOT_SHADOW_BAD_RESPONSE
AWS_IOT_SHADOW_TIMEOUT
A Shadow service rejection reason between 400 (AWS_IOT_SHADOW_BAD_REQUEST) and 500 (AWS_IOT_SHADOW_SERVER_ERROR)

◆ AwsIotShadow_Wait()

AwsIotShadowError_t AwsIotShadow_Wait	(	AwsIotShadowOperation_t	operation,
		uint32_t	timeoutMs,
		const char **const	pShadowDocument,
		size_t *const	pShadowDocumentLength
	)

Wait for a Shadow operation to complete.

This function blocks to wait for a delete, get, or update to complete. These operations are by default asynchronous; the function calls queue an operation for processing, and a callback is invoked once the operation is complete.

To use this function, the flag AWS_IOT_SHADOW_FLAG_WAITABLE must have been set in the operation's function call. Additionally, this function must always be called with any waitable operation to clean up resources.

Regardless of its return value, this function always clean up resources used by the waitable operation. This means operation is invalidated as soon as this function returns, even if it returns AWS_IOT_SHADOW_TIMEOUT or another error.

Parameters

[in]	operation	Reference to the Shadow operation to wait for. The flag AWS_IOT_SHADOW_FLAG_WAITABLE must have been set for this operation.
[in]	timeoutMs	How long to wait before returning AWS_IOT_SHADOW_TIMEOUT.
[out]	pShadowDocument	A pointer to a buffer containing the Shadow document retrieved by a Shadow get is placed here. The buffer was allocated with the function AwsIotShadowDocumentInfo_t.mallocDocument passed to AwsIotShadow_GetAsync. This parameter is only valid for a Shadow get and ignored for other Shadow operations. This output parameter is only valid if this function returns AWS_IOT_SHADOW_SUCCESS.
[out]	pShadowDocumentLength	The length of the Shadow document in `pShadowDocument` is placed here. This parameter is only valid for a Shadow get and ignored for other Shadow operations. This output parameter is only valid if this function returns AWS_IOT_SHADOW_SUCCESS.

Returns

One of the following:

AWS_IOT_SHADOW_SUCCESS
AWS_IOT_SHADOW_NOT_INITIALIZED
AWS_IOT_SHADOW_BAD_PARAMETER
AWS_IOT_SHADOW_BAD_RESPONSE
AWS_IOT_SHADOW_TIMEOUT
A Shadow service rejection reason between 400 (AWS_IOT_SHADOW_BAD_REQUEST) and 500 (AWS_IOT_SHADOW_SERVER_ERROR)

Example 1 (Shadow Update)

AwsIotShadowError_t result = AWS_IOT_SHADOW_STATUS_PENDING;
AwsIotShadowDocumentInfo_t updateInfo = { ... };
// Reference and timeout.
AwsIotShadowOperation_t updateOperation = AWS_IOT_SHADOW_OPERATION_INITIALIZER;
uint32_t timeout = 5000; // 5 seconds
// Shadow update operation.
result = AwsIotShadow_UpdateAsync( mqttConnection,
                                   &updateInfo,
                                   AWS_IOT_SHADOW_FLAG_WAITABLE,
                                   NULL,
                                   &updateOperation );
// Update should have returned AWS_IOT_SHADOW_STATUS_PENDING. The call to wait
// returns once the result of the update is available or the timeout expires.
if( result == AWS_IOT_SHADOW_STATUS_PENDING )
{
    // The last two parameters are ignored for a Shadow update.
    result = AwsIotShadow_Wait( updateOperation, timeout, NULL, NULL );
    // After the call to wait, the result of the update is known
    // (not AWS_IOT_SHADOW_STATUS_PENDING).
    assert( result != AWS_IOT_SHADOW_STATUS_PENDING );
}

Example 2 (Shadow Get)

AwsIotShadowError_t result = AWS_IOT_SHADOW_STATUS_PENDING;
AwsIotShadowDocumentInfo_t getInfo = { ... };
// Reference and timeout.
AwsIotShadowOperation_t getOperation = AWS_IOT_SHADOW_OPERATION_INITIALIZER;
uint32_t timeout = 5000; // 5 seconds
// Buffer pointer and size for retrieved Shadow document.
const char * pShadowDocument = NULL;
size_t documentLength = 0;
// Buffer allocation function must be set for a waitable Shadow get.
getInfo.get.mallocDocument = malloc;
// Shadow get operation.
result = AwsIotShadow_GetAsync( mqttConnection,
                                &getInfo,
                                AWS_IOT_SHADOW_FLAG_WAITABLE,
                                NULL,
                                &getOperation );
// Get should have returned AWS_IOT_SHADOW_STATUS_PENDING. The call to wait
// returns once the result of the get is available or the timeout expires.
if( result == AWS_IOT_SHADOW_STATUS_PENDING )
{
    // The last two parameters must be set for a Shadow get.
    result = AwsIotShadow_Wait( getOperation, timeout, &pShadowDocument, &documentLength );
    // After the call to wait, the result of the get is known
    // (not AWS_IOT_SHADOW_STATUS_PENDING).
    assert( result != AWS_IOT_SHADOW_STATUS_PENDING );
    // The retrieved Shadow document is only valid for a successful Shadow get.
    if( result == AWS_IOT_SHADOW_SUCCESS )
    {
        // Do something with the Shadow document...
        // Free the Shadow document when finished.
        free( pShadowDocument );
    }
}

◆ AwsIotShadow_SetDeltaCallback()

AwsIotShadowError_t AwsIotShadow_SetDeltaCallback	(	IotMqttConnection_t	mqttConnection,
		const char *	pThingName,
		size_t	thingNameLength,
		uint32_t	flags,
		const AwsIotShadowCallbackInfo_t *	pDeltaCallback
	)

Set a callback to be invoked when the Thing Shadow desired and reported states differ.

A Thing Shadow contains reported and desired states, meant to represent the current device status and some desired status, respectively. When the reported and desired states differ, the Thing Shadow service generates a delta document and publishes it to the topic update/delta. Devices with a subscription for this topic will receive the delta document and may act based on the different reported and desired states. See this page for more information about using delta documents.

A delta callback may be invoked whenever a delta document is generated. Each Thing may have a single delta callback set. This function modifies the delta callback for a specific Thing depending on the pDeltaCallback parameter and the presence of any existing delta callback:

When no existing delta callback exists for a specific Thing, a new delta callback is added.
If there is an existing delta callback and pDeltaCallback is not NULL, then the existing callback function and parameter are replaced with pDeltaCallback.
If there is an existing subscription and pDeltaCallback is NULL, then the delta callback is removed.

This function is always blocking; it may block for up to the default MQTT timeout. This timeout is set as a parameter to AwsIotShadow_Init, and defaults to AWS_IOT_SHADOW_DEFAULT_MQTT_TIMEOUT_MS if not set. If this function's underlying MQTT operations fail to complete within this timeout, then this function returns AWS_IOT_SHADOW_TIMEOUT.

Parameters

[in]	mqttConnection	The MQTT connection to use for the subscription to `update/delta`.
[in]	pThingName	The subscription to `update/delta` will be added for this Thing Name.
[in]	thingNameLength	The length of `pThingName`.
[in]	flags	This parameter is for future-compatibility. Currently, flags are not supported for this function and this parameter is ignored.
[in]	pDeltaCallback	Callback function to invoke for incoming delta documents.

Returns

One of the following:

This function always returns AWS_IOT_SHADOW_SUCCESS when replacing or removing existing delta callbacks.

See also: AwsIotShadow_SetUpdatedCallback for the function to register callbacks for all Shadow updates.

Example

#define THING_NAME "Test_device"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )
AwsIotShadowError_t result = AWS_IOT_SHADOW_STATUS_PENDING;
AwsIotShadowCallbackInfo_t deltaCallback = AWS_IOT_SHADOW_CALLBACK_INFO_INITIALIZER;
// _deltaCallbackFunction will be invoked when a delta document is received.
deltaCallback.function = _deltaCallbackFunction;
// Set the delta callback for the Thing "Test_device".
result = AwsIotShadow_SetDeltaCallback( mqttConnection,
                                        THING_NAME,
                                        THING_NAME_LENGTH,
                                        0,
                                        &deltaCallback );
// Check if callback was successfully set.
if( result == AWS_IOT_SHADOW_SUCCESS )
{
    AwsIotShadowDocumentInfo_t updateInfo = AWS_IOT_SHADOW_DOCUMENT_INFO_INITIALIZER;
    // Set the Thing Name for Shadow update.
    updateInfo.pThingName = THING_NAME;
    updateInfo.thingNameLength = THING_NAME_LENGTH;
    // Set the Shadow document to send. This document has different "reported"
    // and "desired" states. It represents a scenario where a device is currently
    // off, but is being ordered to turn on.
    updateInfo.update.pUpdateDocument =
    "{"
         "\"state\": {"
             "\"reported\": { \"deviceOn\": false },"
             "\"desired\": { \"deviceOn\": true }"
         "}"
    "}";
    updateInfo.update.updateDocumentLength = strlen( updateInfo.update.pUpdateDocument );
    // Send the Shadow document with different "reported" and desired states.
    result = AwsIotShadow_UpdateSync( mqttConnection,
                                      &updateInfo,
                                      0,
                                      0,
                                      5000 );
    // After the update is successfully sent, the function _deltaCallbackFunction
    // will be invoked once the Shadow service generates and sends a delta document.
    // The delta document will contain the different "deviceOn" states, as well as
    // metadata.
    // Once the delta callback is no longer needed, it may be removed by passing
    // NULL as pDeltaCallback.
    result = AwsIotShadow_SetDeltaCallback( mqttConnection,
                                            THING_NAME,
                                            THING_NAME_LENGTH,
                                            0,
                                            NULL );
    // The return value from removing a delta callback should always be success.
    assert( result == AWS_IOT_SHADOW_SUCCESS );
}

◆ AwsIotShadow_SetUpdatedCallback()

AwsIotShadowError_t AwsIotShadow_SetUpdatedCallback	(	IotMqttConnection_t	mqttConnection,
		const char *	pThingName,
		size_t	thingNameLength,
		uint32_t	flags,
		const AwsIotShadowCallbackInfo_t *	pUpdatedCallback
	)

Set a callback to be invoked when a Thing Shadow changes.

The Shadow service publishes a state document to the update/documents topic whenever a Thing Shadow is successfully updated. This document reports the complete previous and current Shadow documents in previous and current sections, respectively. Therefore, the update/documents topic is useful for monitoring Shadow updates.

An updated callback may be invoked whenever a document is published to update/documents. Each Thing may have a single updated callback set. This function modifies the updated callback for a specific Thing depending on the pUpdatedCallback parameter and the presence of any existing updated callback.

When no existing updated callback exists for a specific Thing, a new updated callback is added.
If there is an existing updated callback and pUpdatedCallback is not NULL, then the existing callback function and parameter are replaced with pUpdatedCallback.
If there is an existing updated callback and pUpdatedCallback is NULL, then the updated callback is removed.

Parameters

[in]	mqttConnection	The MQTT connection to use for the subscription to `update/documents`.
[in]	pThingName	The subscription to `update/documents` will be added for this Thing Name.
[in]	thingNameLength	The length of `pThingName`.
[in]	flags	This parameter is for future-compatibility. Currently, flags are not supported for this function and this parameter is ignored.
[in]	pUpdatedCallback	Callback function to invoke for incoming updated documents.

Returns

One of the following:

Note: Documents published to update/documents will be large, as they contain 2 complete Shadow state documents. If an updated callback is used, ensure that the device has sufficient memory for incoming documents.

See also: AwsIotShadow_SetDeltaCallback for the function to register callbacks for delta documents.

Example

#define THING_NAME "Test_device"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )
AwsIotShadowError_t result = AWS_IOT_SHADOW_STATUS_PENDING;
AwsIotShadowCallbackInfo_t updatedCallback = AWS_IOT_SHADOW_CALLBACK_INFO_INITIALIZER;
// _updatedCallbackFunction will be invoked when an updated document is received.
updatedCallback.function = _updatedCallbackFunction;
// Set the updated callback for the Thing "Test_device".
result = AwsIotShadow_SetUpdatedCallback( mqttConnection,
                                          THING_NAME,
                                          THING_NAME_LENGTH,
                                          0,
                                          &updatedCallback );
// Check if the callback was successfully set.
if( result == AWS_IOT_SHADOW_SUCCESS )
{
    AwsIotShadowDocumentInfo_t updateInfo = AWS_IOT_SHADOW_DOCUMENT_INFO_INITIALIZER;
    // Set the Thing Name for Shadow update.
    updateInfo.pThingName = THING_NAME;
    updateInfo.thingNameLength = THING_NAME_LENGTH;
    // Set the Shadow document to send. Any Shadow update will trigger the
    // updated callback.
    updateInfo.update.pUpdateDocument =
    "{"
         "\"state\": {"
             "\"reported\": { \"deviceOn\": false }"
         "}"
    "}";
    updateInfo.update.updateDocumentLength = strlen( updateInfo.update.pUpdateDocument );
    // Send the Shadow document. A successful update will trigger the updated callback.
    result = AwsIotShadow_UpdateSync( mqttConnection,
                                      &updateInfo,
                                      0,
                                      0,
                                      5000 );
    // After a successful Shadow update, the updated callback will be invoked.
    // Once the updated callback is no longer needed, it may be removed by
    // passing NULL as pUpdatedCallback.
    result = AwsIotShadow_SetUpdatedCallback( mqttConnection,
                                              THING_NAME,
                                              THING_NAME_LENGTH,
                                              NULL );
    // The return value from removing an updated callback should always be
    // success.
    assert( result == AWS_IOT_SHADOW_SUCCESS );
}

◆ 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:

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

◆ AwsIotShadow_strerror()

const char* AwsIotShadow_strerror ( AwsIotShadowError_t status )

Returns a string that describes an AwsIotShadowError_t.

Like POSIX's strerror, this function returns a string describing a return code. In this case, the return code is a Shadow library error code, status.

The string returned by this function MUST be treated as read-only: any attempt to modify its contents may result in a crash. Therefore, this function is limited to usage in logging.

Parameters

[in] status The status to describe.

Returns: A read-only string that describes status.

Warning: The string returned by this function must never be modified.

Functions

Detailed Description

Function Documentation

◆ AwsIotShadow_Init()

◆ AwsIotShadow_Cleanup()

◆ AwsIotShadow_DeleteAsync()

◆ AwsIotShadow_DeleteSync()

◆ AwsIotShadow_GetAsync()

◆ AwsIotShadow_GetSync()

◆ AwsIotShadow_UpdateAsync()

◆ AwsIotShadow_UpdateSync()

◆ AwsIotShadow_Wait()

◆ AwsIotShadow_SetDeltaCallback()

◆ AwsIotShadow_SetUpdatedCallback()

◆ AwsIotShadow_RemovePersistentSubscriptions()

◆ AwsIotShadow_strerror()