path: root/FreeRTOS-Labs/Source/FreeRTOS-IoT-Libraries/c_sdk/aws/shadow/include/aws_iot_shadow.h

/*
 * AWS IoT Shadow V2.1.0
 * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

/**
 * @file aws_iot_shadow.h
 * @brief User-facing functions of the Shadow library.
 */

#ifndef AWS_IOT_SHADOW_H_
#define AWS_IOT_SHADOW_H_

/* The config header is always included first. */
#include "iot_config.h"

/* Shadow types include. */
#include "types/aws_iot_shadow_types.h"

/*------------------------ Shadow library functions -------------------------*/

/**
 * @functionspage{shadow,Shadow library}
 * - @functionname{shadow_function_init}
 * - @functionname{shadow_function_cleanup}
 * - @functionname{shadow_function_deleteasync}
 * - @functionname{shadow_function_deletesync}
 * - @functionname{shadow_function_getasync}
 * - @functionname{shadow_function_getsync}
 * - @functionname{shadow_function_updateasync}
 * - @functionname{shadow_function_updatesync}
 * - @functionname{shadow_function_wait}
 * - @functionname{shadow_function_setdeltacallback}
 * - @functionname{shadow_function_setupdatedcallback}
 * - @functionname{shadow_function_removepersistentsubscriptions}
 * - @functionname{shadow_function_strerror}
 */

/**
 * @functionpage{AwsIotShadow_Init,shadow,init}
 * @functionpage{AwsIotShadow_Cleanup,shadow,cleanup}
 * @functionpage{AwsIotShadow_DeleteAsync,shadow,deleteasync}
 * @functionpage{AwsIotShadow_DeleteSync,shadow,deletesync}
 * @functionpage{AwsIotShadow_GetAsync,shadow,getasync}
 * @functionpage{AwsIotShadow_GetSync,shadow,getsync}
 * @functionpage{AwsIotShadow_UpdateAsync,shadow,updateasync}
 * @functionpage{AwsIotShadow_UpdateSync,shadow,updatesync}
 * @functionpage{AwsIotShadow_Wait,shadow,wait}
 * @functionpage{AwsIotShadow_SetDeltaCallback,shadow,setdeltacallback}
 * @functionpage{AwsIotShadow_SetUpdatedCallback,shadow,setupdatedcallback}
 * @functionpage{AwsIotShadow_RemovePersistentSubscriptions,shadow,removepersistentsubscriptions}
 * @functionpage{AwsIotShadow_strerror,shadow,strerror}
 */

/**
 * @brief One-time initialization function for the Shadow library.
 *
 * This function performs internal setup of the Shadow library. <b>It must be
 * called once (and only once) before calling any other Shadow function.</b>
 * Calling this function more than once without first calling @ref
 * shadow_function_cleanup may result in a crash.
 *
 * @param[in] mqttTimeout The amount of time (in milliseconds) that the Shadow
 * library will wait for MQTT operations. Optional; set this to `0` to use
 * @ref AWS_IOT_SHADOW_DEFAULT_MQTT_TIMEOUT_MS.
 *
 * @return One of the following:
 * - #AWS_IOT_SHADOW_SUCCESS
 * - #AWS_IOT_SHADOW_INIT_FAILED
 *
 * @warning No thread-safety guarantees are provided for this function.
 *
 * @see @ref shadow_function_cleanup
 */
/* @[declare_shadow_init] */
AwsIotShadowError_t AwsIotShadow_Init( uint32_t mqttTimeout );
/* @[declare_shadow_init] */

/**
 * @brief One-time deinitialization function for the Shadow library.
 *
 * This function frees resources taken in @ref shadow_function_init and deletes
 * any [persistent subscriptions.](@ref AWS_IOT_SHADOW_FLAG_KEEP_SUBSCRIPTIONS)
 * It should be called to clean up the Shadow library. After this function returns,
 * @ref shadow_function_init must be called again before calling any other Shadow
 * function.
 *
 * @warning No thread-safety guarantees are provided for this function.
 *
 * @see @ref shadow_function_init
 */
/* @[declare_shadow_cleanup] */
void AwsIotShadow_Cleanup( void );
/* @[declare_shadow_cleanup] */

/**
 * @brief 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](@ref #IOT_MQTT_QOS_0).
 *
 * @param[in] mqttConnection The MQTT connection to use for Shadow delete.
 * @param[in] pThingName The Thing Name associated with the Shadow to delete.
 * @param[in] thingNameLength The length of `pThingName`.
 * @param[in] flags Flags which modify the behavior of this function. See @ref shadow_constants_flags.
 * @param[in] pCallbackInfo Asynchronous notification of this function's completion.
 * @param[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.
 *
 * @return This function will return #AWS_IOT_SHADOW_STATUS_PENDING upon successfully
 * queuing a Shadow delete.
 * @return 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
 * @return Upon successful completion of the Shadow delete (either through an #AwsIotShadowCallbackInfo_t
 * or #AwsIotShadow_Wait), the status will be #AWS_IOT_SHADOW_SUCCESS.
 * @return 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 @ref shadow_function_deletesync for a blocking variant of this function.
 *
 * <b>Example</b>
 * @code{c}
 * #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.
 * }
 * @endcode
 */
/* @[declare_shadow_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 );
/* @[declare_shadow_deleteasync] */

/**
 * @brief 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 @ref shadow_function_deleteasync followed by @ref shadow_function_wait.
 * See @ref shadow_function_deleteasync for more information on the Shadow delete operation.
 *
 * @param[in] mqttConnection The MQTT connection to use for Shadow delete.
 * @param[in] pThingName The Thing Name associated with the Shadow to delete.
 * @param[in] thingNameLength The length of `pThingName`.
 * @param[in] flags Flags which modify the behavior of this function. See @ref shadow_constants_flags.
 * @param[in] timeoutMs If the Shadow service does not respond to the Shadow delete
 * within this timeout, this function returns #AWS_IOT_SHADOW_TIMEOUT.
 *
 * @return 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)
 */
/* @[declare_shadow_deletesync] */
AwsIotShadowError_t AwsIotShadow_DeleteSync( IotMqttConnection_t mqttConnection,
                                             const char * pThingName,
                                             size_t thingNameLength,
                                             uint32_t flags,
                                             uint32_t timeoutMs );
/* @[declare_shadow_deletesync] */

/**
 * @brief 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](@ref AwsIotShadowCallbackInfo_t) 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]
 * (@ref shadow_function_setdeltacallback) to retrieve Shadows from
 * the Shadow service.
 *
 * @param[in] mqttConnection The MQTT connection to use for Shadow get.
 * @param[in] pGetInfo Shadow document parameters.
 * @param[in] flags Flags which modify the behavior of this function. See @ref shadow_constants_flags.
 * @param[in] pCallbackInfo Asynchronous notification of this function's completion.
 * @param[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.
 *
 * @return This function will return #AWS_IOT_SHADOW_STATUS_PENDING upon successfully
 * queuing a Shadow get.
 * @return If this function fails before queuing a Shadow get, it will return one of:
 * - #AWS_IOT_SHADOW_NOT_INITIALIZED
 * - #AWS_IOT_SHADOW_BAD_PARAMETER
 * - #AWS_IOT_SHADOW_NO_MEMORY
 * @return Upon successful completion of the Shadow get (either through an #AwsIotShadowCallbackInfo_t
 * or #AwsIotShadow_Wait), the status will be #AWS_IOT_SHADOW_SUCCESS.
 * @return 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 @ref shadow_function_getsync for a blocking variant of this function.
 *
 * <b>Example</b>
 * @code{c}
 * // 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.
 * @endcode
 *
 * See @ref shadow_function_wait <b>Example 2</b> for an example of using this
 * function with #AWS_IOT_SHADOW_FLAG_WAITABLE and @ref shadow_function_wait.
 */
/* @[declare_shadow_getasync] */
AwsIotShadowError_t AwsIotShadow_GetAsync( IotMqttConnection_t mqttConnection,
                                           const AwsIotShadowDocumentInfo_t * pGetInfo,
                                           uint32_t flags,
                                           const AwsIotShadowCallbackInfo_t * pCallbackInfo,
                                           AwsIotShadowOperation_t * const pGetOperation );
/* @[declare_shadow_getasync] */

/**
 * @brief 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 @ref shadow_function_getasync followed by @ref shadow_function_wait.
 * See @ref shadow_function_getasync for more information on the Shadow get operation.
 *
 * @param[in] mqttConnection The MQTT connection to use for Shadow get.
 * @param[in] pGetInfo Shadow document parameters.
 * @param[in] flags Flags which modify the behavior of this function. See @ref shadow_constants_flags.
 * @param[in] timeoutMs If the Shadow service does not respond to the Shadow get
 * within this timeout, this function returns #AWS_IOT_SHADOW_TIMEOUT.
 * @param[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.
 * @param[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.
 *
 * @return 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)
 */
/* @[declare_shadow_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 );
/* @[declare_shadow_getsync] */

/**
 * @brief 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]
 * (@ref shadow_function_setupdatedcallback). If the resulting Shadow document contains
 * different `desired` and `reported` keys, then the [Shadow delta callback]
 * (@ref shadow_function_setdeltacallback) will be triggered as well.
 *
 * @attention All documents passed to this function must contain a `clientToken`.
 * The [client token]
 * (https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-document.html#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 <i>as long as no two Shadow updates are using the same
 * client token at the same time</i>.
 *
 * @param[in] mqttConnection The MQTT connection to use for Shadow update.
 * @param[in] pUpdateInfo Shadow document parameters.
 * @param[in] flags Flags which modify the behavior of this function. See @ref shadow_constants_flags.
 * @param[in] pCallbackInfo Asynchronous notification of this function's completion.
 * @param[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.
 *
 * @return This function will return #AWS_IOT_SHADOW_STATUS_PENDING upon successfully
 * queuing a Shadow update.
 * @return 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
 * @return Upon successful completion of the Shadow update (either through an #AwsIotShadowCallbackInfo_t
 * or #AwsIotShadow_Wait), the status will be #AWS_IOT_SHADOW_SUCCESS.
 * @return 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 @ref shadow_function_updatesync for a blocking variant of this function.
 *
 * <b>Example</b>
 * @code{c}
 * // 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.
 * @endcode
 *
 * See @ref shadow_function_wait <b>Example 1</b> for an example of using this
 * function with #AWS_IOT_SHADOW_FLAG_WAITABLE and @ref shadow_function_wait.
 */
/* @[declare_shadow_updateasync] */
AwsIotShadowError_t AwsIotShadow_UpdateAsync( IotMqttConnection_t mqttConnection,
                                              const AwsIotShadowDocumentInfo_t * pUpdateInfo,
                                              uint32_t flags,
                                              const AwsIotShadowCallbackInfo_t * pCallbackInfo,
                                              AwsIotShadowOperation_t * const pUpdateOperation );
/* @[declare_shadow_updateasync] */

/**
 * @brief 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 @ref shadow_function_updateasync followed by @ref shadow_function_wait.
 * See @ref shadow_function_updateasync for more information on the Shadow update operation.
 *
 * @param[in] mqttConnection The MQTT connection to use for Shadow update.
 * @param[in] pUpdateInfo Shadow document parameters.
 * @param[in] flags Flags which modify the behavior of this function. See @ref shadow_constants_flags.
 * @param[in] timeoutMs If the Shadow service does not respond to the Shadow update
 * within this timeout, this function returns #AWS_IOT_SHADOW_TIMEOUT.
 *
 * @return 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)
 */
/* @[declare_shadow_updatesync] */
AwsIotShadowError_t AwsIotShadow_UpdateSync( IotMqttConnection_t mqttConnection,
                                             const AwsIotShadowDocumentInfo_t * pUpdateInfo,
                                             uint32_t flags,
                                             uint32_t timeoutMs );
/* @[declare_shadow_updatesync] */

/**
 * @brief Wait for a Shadow operation to complete.
 *
 * This function blocks to wait for a [delete](@ref shadow_function_deleteasync),
 * [get](@ref shadow_function_getasync), or [update](@ref shadow_function_updateasync) 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.
 *
 * @param[in] operation Reference to the Shadow operation to wait for. The flag
 * #AWS_IOT_SHADOW_FLAG_WAITABLE must have been set for this operation.
 * @param[in] timeoutMs How long to wait before returning #AWS_IOT_SHADOW_TIMEOUT.
 * @param[out] pShadowDocument A pointer to a buffer containing the Shadow document
 * retrieved by a [Shadow get](@ref shadow_function_getasync) is placed here. The buffer
 * was allocated with the function #AwsIotShadowDocumentInfo_t.mallocDocument passed
 * to @ref shadow_function_getasync. This parameter is only valid for a [Shadow get]
 * (@ref shadow_function_getasync) and ignored for other Shadow operations. This output
 * parameter is only valid if this function returns #AWS_IOT_SHADOW_SUCCESS.
 * @param[out] pShadowDocumentLength The length of the Shadow document in
 * `pShadowDocument` is placed here. This parameter is only valid for a [Shadow get]
 * (@ref shadow_function_getasync) and ignored for other Shadow operations. This output
 * parameter is only valid if this function returns #AWS_IOT_SHADOW_SUCCESS.
 *
 * @return 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)
 *
 * <b>Example 1 (Shadow Update)</b>
 * @code{c}
 * 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 );
 * }
 * @endcode
 *
 * <b>Example 2 (Shadow Get)</b>
 * @code{c}
 * 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 );
 *     }
 * }
 * @endcode
 */
/* @[declare_shadow_wait] */
AwsIotShadowError_t AwsIotShadow_Wait( AwsIotShadowOperation_t operation,
                                       uint32_t timeoutMs,
                                       const char ** const pShadowDocument,
                                       size_t * const pShadowDocumentLength );
/* @[declare_shadow_wait] */

/**
 * @brief 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
 * <i>delta document</i> 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]
 * (https://docs.aws.amazon.com/iot/latest/developerguide/using-device-shadows.html#delta-state)
 * for more information about using delta documents.
 *
 * A <i>delta callback</i> 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 @ref shadow_function_init,
 * and defaults to @ref 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.
 *
 * @param[in] mqttConnection The MQTT connection to use for the subscription to
 * `update/delta`.
 * @param[in] pThingName The subscription to `update/delta` will be added for
 * this Thing Name.
 * @param[in] thingNameLength The length of `pThingName`.
 * @param[in] flags This parameter is for future-compatibility. Currently, flags
 * are not supported for this function and this parameter is ignored.
 * @param[in] pDeltaCallback Callback function to invoke for incoming delta
 * documents.
 *
 * @return 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
 *
 * @return This function always returns #AWS_IOT_SHADOW_SUCCESS when replacing or
 * removing existing delta callbacks.
 *
 * @see @ref shadow_function_setupdatedcallback for the function to register
 * callbacks for all Shadow updates.
 *
 * <b>Example</b>
 * @code{c}
 * #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 );
 * }
 * @endcode
 */
/* @[declare_shadow_setdeltacallback] */
AwsIotShadowError_t AwsIotShadow_SetDeltaCallback( IotMqttConnection_t mqttConnection,
                                                   const char * pThingName,
                                                   size_t thingNameLength,
                                                   uint32_t flags,
                                                   const AwsIotShadowCallbackInfo_t * pDeltaCallback );
/* @[declare_shadow_setdeltacallback] */

/**
 * @brief 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 <i>updated callback</i> 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.
 *
 * @param[in] mqttConnection The MQTT connection to use for the subscription to `update/documents`.
 * @param[in] pThingName The subscription to `update/documents` will be added for
 * this Thing Name.
 * @param[in] thingNameLength The length of `pThingName`.
 * @param[in] flags This parameter is for future-compatibility. Currently, flags are
 * not supported for this function and this parameter is ignored.
 * @param[in] pUpdatedCallback Callback function to invoke for incoming updated documents.
 *
 * @return 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
 *
 * @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 @ref shadow_function_setdeltacallback for the function to register callbacks
 * for delta documents.
 *
 * <b>Example</b>
 * @code{c}
 * #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 );
 * }
 * @endcode
 */
/* @[declare_shadow_setupdatedcallback] */
AwsIotShadowError_t AwsIotShadow_SetUpdatedCallback( IotMqttConnection_t mqttConnection,
                                                     const char * pThingName,
                                                     size_t thingNameLength,
                                                     uint32_t flags,
                                                     const AwsIotShadowCallbackInfo_t * pUpdatedCallback );
/* @[declare_shadow_setupdatedcallback] */

/**
 * @brief Remove persistent Thing Shadow operation topic subscriptions.
 *
 * Passing the flag @ref AWS_IOT_SHADOW_FLAG_KEEP_SUBSCRIPTIONS to @ref shadow_function_deleteasync,
 * @ref shadow_function_getasync, @ref shadow_function_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.
 *
 * @param[in] mqttConnection The MQTT connection associated with the persistent subscription.
 * @param[in] pThingName The Thing Name associated with the persistent subscription.
 * @param[in] thingNameLength The length of `pThingName`.
 * @param[in] flags Flags that determine which subscriptions to remove. Valid values are
 * the bitwise OR of the following individual flags:
 * - @ref AWS_IOT_SHADOW_FLAG_REMOVE_DELETE_SUBSCRIPTIONS
 * - @ref AWS_IOT_SHADOW_FLAG_REMOVE_GET_SUBSCRIPTIONS
 * - @ref AWS_IOT_SHADOW_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS
 *
 * @return On success:
 * - #AWS_IOT_SHADOW_SUCCESS
 * @return If an MQTT UNSUBSCRIBE packet cannot be sent, one of the following:
 * - #AWS_IOT_SHADOW_NO_MEMORY
 * - #AWS_IOT_SHADOW_MQTT_ERROR
 *
 * @note @ref shadow_function_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 @ref
 * shadow_function_setdeltacallback and @ref shadow_function_setupdatedcallback,
 * respectively. (See documentation for those functions on how to remove their
 * callbacks).
 */
/* @[declare_shadow_removepersistentsubscriptions] */
AwsIotShadowError_t AwsIotShadow_RemovePersistentSubscriptions( IotMqttConnection_t mqttConnection,
                                                                const char * pThingName,
                                                                size_t thingNameLength,
                                                                uint32_t flags );
/* @[declare_shadow_removepersistentsubscriptions] */

/*------------------------- Shadow helper functions -------------------------*/

/**
 * @brief 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 <b>MUST</b> 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.
 *
 * @param[in] status The status to describe.
 *
 * @return A read-only string that describes `status`.
 *
 * @warning The string returned by this function must never be modified.
 */
/* @[declare_shadow_strerror] */
const char * AwsIotShadow_strerror( AwsIotShadowError_t status );
/* @[declare_shadow_strerror] */

/**
 * @cond DOXYGEN_IGNORE
 * Doxygen should ignore this section.
 *
 * Backwards compatibility macros for previous function names.
 */
#define AwsIotShadow_Delete         AwsIotShadow_DeleteAsync
#define AwsIotShadow_TimedDelete    AwsIotShadow_DeleteSync
#define AwsIotShadow_Get            AwsIotShadow_GetAsync
#define AwsIotShadow_TimedGet       AwsIotShadow_GetSync
#define AwsIotShadow_Update         AwsIotShadow_UpdateAsync
#define AwsIotShadow_TimedUpdate    AwsIotShadow_UpdateSync
/** @endcond */

#endif /* ifndef AWS_IOT_SHADOW_H_ */