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

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

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.