AwsIotShadow_UpdateAsync

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

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

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:

• AWS_IOT_SHADOW_NOT_INITIALIZED
• AWS_IOT_SHADOW_BAD_PARAMETER
• AWS_IOT_SHADOW_NO_MEMORY

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.