AwsIotShadow_DeleteAsync

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

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

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:

• AWS_IOT_SHADOW_NOT_INITIALIZED
• AWS_IOT_SHADOW_BAD_PARAMETER
• AWS_IOT_SHADOW_NO_MEMORY

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