AwsIotShadow_SetDeltaCallback

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

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

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:

• 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_TIMEOUT

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 );
}