--- /dev/null
+/*\r
+ * AWS IoT Shadow V2.1.0\r
+ * Copyright (C) 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.\r
+ *\r
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
+ * this software and associated documentation files (the "Software"), to deal in\r
+ * the Software without restriction, including without limitation the rights to\r
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
+ * the Software, and to permit persons to whom the Software is furnished to do so,\r
+ * subject to the following conditions:\r
+ *\r
+ * The above copyright notice and this permission notice shall be included in all\r
+ * copies or substantial portions of the Software.\r
+ *\r
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
+ */\r
+\r
+/**\r
+ * @file aws_iot_shadow_types.h\r
+ * @brief Types of the Thing Shadow library.\r
+ */\r
+\r
+#ifndef AWS_IOT_SHADOW_TYPES_H_\r
+#define AWS_IOT_SHADOW_TYPES_H_\r
+\r
+/* The config header is always included first. */\r
+#include "iot_config.h"\r
+\r
+/* MQTT types include. */\r
+#include "types/iot_mqtt_types.h"\r
+\r
+/*--------------------------- Shadow handle types ---------------------------*/\r
+\r
+/**\r
+ * @handles{shadow,Shadow library}\r
+ */\r
+\r
+/**\r
+ * @ingroup shadow_datatypes_handles\r
+ * @brief Opaque handle that references an in-progress Shadow operation.\r
+ *\r
+ * Set as an output parameter of @ref shadow_function_deleteasync, @ref shadow_function_getasync,\r
+ * and @ref shadow_function_updateasync. These functions send a message to the Shadow\r
+ * service requesting a Shadow operation; the result of this operation is unknown\r
+ * until the Shadow service sends a response. Therefore, this handle serves as a\r
+ * reference to Shadow operations awaiting a response from the Shadow service.\r
+ *\r
+ * This reference will be valid from the successful return of @ref shadow_function_deleteasync,\r
+ * @ref shadow_function_getasync, or @ref shadow_function_updateasync. The reference becomes\r
+ * invalid once the [completion callback](@ref AwsIotShadowCallbackInfo_t) is invoked,\r
+ * or @ref shadow_function_wait returns.\r
+ *\r
+ * @initializer{AwsIotShadowOperation_t,AWS_IOT_SHADOW_OPERATION_INITIALIZER}\r
+ *\r
+ * @see @ref shadow_function_wait and #AWS_IOT_SHADOW_FLAG_WAITABLE for waiting on\r
+ * a reference; or #AwsIotShadowCallbackInfo_t and #AwsIotShadowCallbackParam_t for an\r
+ * asynchronous notification of completion.\r
+ */\r
+typedef struct _shadowOperation * AwsIotShadowOperation_t;\r
+\r
+/*------------------------- Shadow enumerated types -------------------------*/\r
+\r
+/**\r
+ * @enums{shadow,Shadow library}\r
+ */\r
+\r
+/**\r
+ * @ingroup shadow_datatypes_enums\r
+ * @brief Return codes of [Shadow functions](@ref shadow_functions).\r
+ *\r
+ * The function @ref shadow_function_strerror can be used to get a return code's\r
+ * description.\r
+ *\r
+ * The values between 400 (#AWS_IOT_SHADOW_BAD_REQUEST) and 500\r
+ * (#AWS_IOT_SHADOW_SERVER_ERROR) may be returned by the Shadow service when it\r
+ * rejects a Shadow operation. See [this page]\r
+ * (https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-error-messages.html)\r
+ * for more information.\r
+ */\r
+typedef enum AwsIotShadowError\r
+{\r
+ /**\r
+ * @brief Shadow operation completed successfully.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_init\r
+ * - @ref shadow_function_wait\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_setdeltacallback\r
+ * - @ref shadow_function_setupdatedcallback\r
+ * - @ref shadow_function_removepersistentsubscriptions\r
+ *\r
+ * Will also be the value of a Shadow operation completion callback's<br>\r
+ * [AwsIotShadowCallbackParam_t.operation.result](@ref AwsIotShadowCallbackParam_t.result)\r
+ * when successful.\r
+ */\r
+ AWS_IOT_SHADOW_SUCCESS = 0,\r
+\r
+ /**\r
+ * @brief Shadow operation queued, awaiting result.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deleteasync\r
+ * - @ref shadow_function_getasync\r
+ * - @ref shadow_function_updateasync\r
+ */\r
+ AWS_IOT_SHADOW_STATUS_PENDING = 1,\r
+\r
+ /**\r
+ * @brief Initialization failed.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_init\r
+ */\r
+ AWS_IOT_SHADOW_INIT_FAILED = 2,\r
+\r
+ /**\r
+ * @brief At least one parameter is invalid.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deleteasync and @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getasync and @ref shadow_function_getsync\r
+ * - @ref shadow_function_updateasync and @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ * - @ref shadow_function_setdeltacallback\r
+ * - @ref shadow_function_setupdatedcallback\r
+ */\r
+ AWS_IOT_SHADOW_BAD_PARAMETER = 3,\r
+\r
+ /**\r
+ * @brief Shadow operation failed because of memory allocation failure.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deleteasync and @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getasync and @ref shadow_function_getsync\r
+ * - @ref shadow_function_updateasync and @ref shadow_function_updatesync\r
+ * - @ref shadow_function_setdeltacallback\r
+ * - @ref shadow_function_setupdatedcallback\r
+ */\r
+ AWS_IOT_SHADOW_NO_MEMORY = 4,\r
+\r
+ /**\r
+ * @brief Shadow operation failed because of failure in MQTT library.\r
+ *\r
+ * Check the Shadow library logs for the error code returned by the MQTT\r
+ * library.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deleteasync and @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getasync and @ref shadow_function_getsync\r
+ * - @ref shadow_function_updateasync and @ref shadow_function_updatesync\r
+ * - @ref shadow_function_setdeltacallback\r
+ * - @ref shadow_function_setupdatedcallback\r
+ * - @ref shadow_function_removepersistentsubscriptions\r
+ */\r
+ AWS_IOT_SHADOW_MQTT_ERROR = 5,\r
+\r
+ /**\r
+ * @brief Response received from Shadow service not understood.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ *\r
+ * May also be the value of a Shadow operation completion callback's<br>\r
+ * [AwsIotShadowCallbackParam_t.operation.result](@ref AwsIotShadowCallbackParam_t.result)\r
+ */\r
+ AWS_IOT_SHADOW_BAD_RESPONSE = 7,\r
+\r
+ /**\r
+ * @brief A blocking Shadow operation timed out.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ * - @ref shadow_function_setdeltacallback\r
+ * - @ref shadow_function_setupdatedcallback\r
+ */\r
+ AWS_IOT_SHADOW_TIMEOUT = 8,\r
+\r
+ /**\r
+ * @brief An API function was called before @ref shadow_function_init.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deleteasync and @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getasync and @ref shadow_function_getsync\r
+ * - @ref shadow_function_updateasync and @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ * - @ref shadow_function_setdeltacallback\r
+ * - @ref shadow_function_setupdatedcallback\r
+ */\r
+ AWS_IOT_SHADOW_NOT_INITIALIZED = 11,\r
+\r
+ /**\r
+ * @brief Shadow operation rejected: Bad request.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ *\r
+ * May also be the value of a Shadow operation completion callback's<br>\r
+ * [AwsIotShadowCallbackParam_t.operation.result](@ref AwsIotShadowCallbackParam_t.result)\r
+ */\r
+ AWS_IOT_SHADOW_BAD_REQUEST = 400,\r
+\r
+ /**\r
+ * @brief Shadow operation rejected: Unauthorized.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ *\r
+ * May also be the value of a Shadow operation completion callback's<br>\r
+ * [AwsIotShadowCallbackParam_t.operation.result](@ref AwsIotShadowCallbackParam_t.result)\r
+ */\r
+ AWS_IOT_SHADOW_UNAUTHORIZED = 401,\r
+\r
+ /**\r
+ * @brief Shadow operation rejected: Forbidden.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ *\r
+ * May also be the value of a Shadow operation completion callback's<br>\r
+ * [AwsIotShadowCallbackParam_t.operation.result](@ref AwsIotShadowCallbackParam_t.result)\r
+ */\r
+ AWS_IOT_SHADOW_FORBIDDEN = 403,\r
+\r
+ /**\r
+ * @brief Shadow operation rejected: Thing not found.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ *\r
+ * May also be the value of a Shadow operation completion callback's<br>\r
+ * [AwsIotShadowCallbackParam_t.operation.result](@ref AwsIotShadowCallbackParam_t.result)\r
+ */\r
+ AWS_IOT_SHADOW_NOT_FOUND = 404,\r
+\r
+ /**\r
+ * @brief Shadow operation rejected: Version conflict.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ *\r
+ * May also be the value of a Shadow operation completion callback's<br>\r
+ * [AwsIotShadowCallbackParam_t.operation.result](@ref AwsIotShadowCallbackParam_t.result)\r
+ */\r
+ AWS_IOT_SHADOW_CONFLICT = 409,\r
+\r
+ /**\r
+ * @brief Shadow operation rejected: The payload exceeds the maximum size\r
+ * allowed.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ *\r
+ * May also be the value of a Shadow operation completion callback's<br>\r
+ * [AwsIotShadowCallbackParam_t.operation.result](@ref AwsIotShadowCallbackParam_t.result)\r
+ */\r
+ AWS_IOT_SHADOW_TOO_LARGE = 413,\r
+\r
+ /**\r
+ * @brief Shadow operation rejected: Unsupported document encoding; supported\r
+ * encoding is UTF-8.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ *\r
+ * May also be the value of a Shadow operation completion callback's<br>\r
+ * [AwsIotShadowCallbackParam_t.operation.result](@ref AwsIotShadowCallbackParam_t.result)\r
+ */\r
+ AWS_IOT_SHADOW_UNSUPPORTED = 415,\r
+\r
+ /**\r
+ * @brief Shadow operation rejected: The Device Shadow service will generate\r
+ * this error message when there are more than 10 in-flight requests.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ *\r
+ * May also be the value of a Shadow operation completion callback's<br>\r
+ * [AwsIotShadowCallbackParam_t.operation.result](@ref AwsIotShadowCallbackParam_t.result)\r
+ */\r
+ AWS_IOT_SHADOW_TOO_MANY_REQUESTS = 429,\r
+\r
+ /**\r
+ * @brief Shadow operation rejected: Internal service failure.\r
+ *\r
+ * Functions that may return this value:\r
+ * - @ref shadow_function_deletesync\r
+ * - @ref shadow_function_getsync\r
+ * - @ref shadow_function_updatesync\r
+ * - @ref shadow_function_wait\r
+ *\r
+ * May also be the value of a Shadow operation completion callback's<br>\r
+ * [AwsIotShadowCallbackParam_t.operation.result](@ref AwsIotShadowCallbackParam_t.result)\r
+ */\r
+ AWS_IOT_SHADOW_SERVER_ERROR = 500,\r
+} AwsIotShadowError_t;\r
+\r
+/**\r
+ * @ingroup shadow_datatypes_enums\r
+ * @brief Types of Shadow library callbacks.\r
+ *\r
+ * One of these values will be placed in #AwsIotShadowCallbackParam_t.callbackType\r
+ * to identify the reason for invoking a callback function.\r
+ */\r
+typedef enum AwsIotShadowCallbackType\r
+{\r
+ AWS_IOT_SHADOW_DELETE_COMPLETE, /**< Callback invoked because a [Shadow delete](@ref shadow_function_deleteasync) completed. */\r
+ AWS_IOT_SHADOW_GET_COMPLETE, /**< Callback invoked because a [Shadow get](@ref shadow_function_getasync) completed. */\r
+ AWS_IOT_SHADOW_UPDATE_COMPLETE, /**< Callback invoked because a [Shadow update](@ref shadow_function_updateasync) completed. */\r
+ AWS_IOT_SHADOW_DELTA_CALLBACK, /**< Callback invoked for an incoming message on a [Shadow delta](@ref shadow_function_setdeltacallback) topic. */\r
+ AWS_IOT_SHADOW_UPDATED_CALLBACK /**< Callback invoked for an incoming message on a [Shadow updated](@ref shadow_function_setupdatedcallback) topic. */\r
+} AwsIotShadowCallbackType_t;\r
+\r
+/*------------------------- Shadow parameter structs ------------------------*/\r
+\r
+/**\r
+ * @paramstructs{shadow,Shadow}\r
+ */\r
+\r
+/**\r
+ * @ingroup shadow_datatypes_paramstructs\r
+ * @brief Parameter to a Shadow callback function.\r
+ *\r
+ * @paramfor Shadow callback functions\r
+ *\r
+ * The Shadow library passes this struct to a callback function whenever a\r
+ * Shadow operation completes or a message is received on a Shadow delta or\r
+ * updated topic.\r
+ *\r
+ * The valid members of this struct are different based on\r
+ * #AwsIotShadowCallbackParam_t.callbackType. If the callback type is\r
+ * #AWS_IOT_SHADOW_DELETE_COMPLETE, #AWS_IOT_SHADOW_GET_COMPLETE, or\r
+ * #AWS_IOT_SHADOW_UPDATE_COMPLETE, then #AwsIotShadowCallbackParam_t.operation\r
+ * is valid. Otherwise, if the callback type is #AWS_IOT_SHADOW_DELTA_CALLBACK\r
+ * or #AWS_IOT_SHADOW_UPDATED_CALLBACK, then #AwsIotShadowCallbackParam_t.callback\r
+ * is valid.\r
+ *\r
+ * @attention Any pointers in this callback parameter may be freed as soon as the\r
+ * [callback function](@ref AwsIotShadowCallbackInfo_t.function) returns. Therefore,\r
+ * data must be copied if it is needed after the callback function returns.\r
+ * @attention The Shadow library may set strings that are not NULL-terminated.\r
+ *\r
+ * @see #AwsIotShadowCallbackInfo_t for the signature of a callback function.\r
+ */\r
+typedef struct AwsIotShadowCallbackParam\r
+{\r
+ AwsIotShadowCallbackType_t callbackType; /**< @brief Reason for invoking the Shadow callback function to provide context. */\r
+\r
+ const char * pThingName; /**< @brief The Thing Name associated with this Shadow callback. */\r
+ size_t thingNameLength; /**< @brief Length of #AwsIotShadowCallbackParam_t.pThingName. */\r
+\r
+ IotMqttConnection_t mqttConnection; /**< @brief The MQTT connection associated with the Shadow callback. */\r
+\r
+ union\r
+ {\r
+ /* Valid for completed Shadow operations. */\r
+ struct\r
+ {\r
+ /* Valid for a completed Shadow GET operation. */\r
+ struct\r
+ {\r
+ const char * pDocument; /**< @brief Retrieved Shadow document. */\r
+ size_t documentLength; /**< @brief Length of retrieved Shadow document. */\r
+ } get; /**< @brief Retrieved Shadow document, valid only for a completed [Shadow Get](@ref shadow_function_getasync). */\r
+\r
+ AwsIotShadowError_t result; /**< @brief Result of Shadow operation, e.g. succeeded or failed. */\r
+ AwsIotShadowOperation_t reference; /**< @brief Reference to the Shadow operation that completed. */\r
+ } operation; /**< @brief Information on a completed Shadow operation. */\r
+\r
+ /* Valid for a message on a Shadow delta or updated topic. */\r
+ struct\r
+ {\r
+ const char * pDocument; /**< @brief Shadow delta or updated document. */\r
+ size_t documentLength; /**< @brief Length of Shadow delta or updated document. */\r
+ } callback; /**< @brief Shadow document from an incoming delta or updated topic. */\r
+ } u; /**< @brief Valid member depends on callback type. */\r
+} AwsIotShadowCallbackParam_t;\r
+\r
+/**\r
+ * @ingroup shadow_datatypes_paramstructs\r
+ * @brief Information on a user-provided Shadow callback function.\r
+ *\r
+ * @paramfor @ref shadow_function_deleteasync, @ref shadow_function_getasync, @ref\r
+ * shadow_function_updateasync, @ref shadow_function_setdeltacallback, @ref\r
+ * shadow_function_setupdatedcallback\r
+ *\r
+ * Provides a function to be invoked when a Shadow operation completes or when a\r
+ * Shadow document is received on a callback topic (delta or updated).\r
+ *\r
+ * @initializer{AwsIotShadowCallbackInfo_t,AWS_IOT_SHADOW_CALLBACK_INFO_INITIALIZER}\r
+ */\r
+typedef struct AwsIotShadowCallbackInfo\r
+{\r
+ void * pCallbackContext; /**< @brief The first parameter to pass to the callback function. */\r
+\r
+ /**\r
+ * @brief User-provided callback function signature.\r
+ *\r
+ * @param[in] pCallbackContext #AwsIotShadowCallbackInfo_t.pCallbackContext\r
+ * @param[in] pCallbackParam Details on the outcome of the Shadow\r
+ * operation or an incoming Shadow document.\r
+ *\r
+ * @see #AwsIotShadowCallbackParam_t for more information on the second parameter.\r
+ */\r
+ void ( * function )( void * pCallbackContext,\r
+ AwsIotShadowCallbackParam_t * pCallbackParam );\r
+} AwsIotShadowCallbackInfo_t;\r
+\r
+/**\r
+ * @ingroup shadow_datatypes_paramstructs\r
+ * @brief Information on a Shadow document for @ref shadow_function_getasync or @ref\r
+ * shadow_function_updateasync.\r
+ *\r
+ * @paramfor @ref shadow_function_getasync, @ref shadow_function_updateasync\r
+ *\r
+ * The valid members of this struct are different based on whether this struct\r
+ * is passed to @ref shadow_function_getasync or @ref shadow_function_updateasync. When\r
+ * passed to @ref shadow_function_getasync, the `get` member is valid. When passed to\r
+ * @ref shadow_function_updateasync, the `update` member is valid. All other members\r
+ * must always be set.\r
+ *\r
+ * @initializer{AwsIotShadowDocumentInfo_t,AWS_IOT_SHADOW_DOCUMENT_INFO_INITIALIZER}\r
+ */\r
+typedef struct AwsIotShadowDocumentInfo\r
+{\r
+ const char * pThingName; /**< @brief The Thing Name associated with this Shadow document. */\r
+ size_t thingNameLength; /**< @brief Length of #AwsIotShadowDocumentInfo_t.pThingName. */\r
+\r
+ IotMqttQos_t qos; /**< @brief QoS when sending a Shadow get or update message. See #IotMqttPublishInfo_t.qos. */\r
+ uint32_t retryLimit; /**< @brief Maximum number of retries for a Shadow get or update message. See #IotMqttPublishInfo_t.retryLimit. */\r
+ uint32_t retryMs; /**< @brief First retry time for a Shadow get or update message. See IotMqttPublishInfo_t.retryMs. */\r
+\r
+ union\r
+ {\r
+ /* Valid for Shadow get. */\r
+ struct\r
+ {\r
+ /**\r
+ * @brief Function to allocate memory for an incoming Shadow document.\r
+ *\r
+ * @param[in] documentLength Length of the document that needs to\r
+ * be allocated.\r
+ * This only needs to be set if #AWS_IOT_SHADOW_FLAG_WAITABLE is passed to\r
+ * @ref shadow_function_getasync.\r
+ */\r
+ void *( *mallocDocument )( size_t documentLength );\r
+ } get; /**< @brief Valid members for @ref shadow_function_getasync. */\r
+\r
+ /* Valid for Shadow update. */\r
+ struct\r
+ {\r
+ const char * pUpdateDocument; /**< @brief The Shadow document to send in the update. */\r
+ size_t updateDocumentLength; /**< @brief Length of Shadow update document. */\r
+ } update; /**< @brief Valid members for @ref shadow_function_updateasync. */\r
+ } u; /**< @brief Valid member depends on operation type. */\r
+} AwsIotShadowDocumentInfo_t;\r
+\r
+/*------------------------ Shadow defined constants -------------------------*/\r
+\r
+/**\r
+ * @constantspage{shadow,Shadow library}\r
+ *\r
+ * @section shadow_constants_initializers Shadow Initializers\r
+ * @brief Provides default values for the data types of the Shadow library.\r
+ *\r
+ * @snippet this define_shadow_initializers\r
+ *\r
+ * All user-facing data types of the Shadow library should be initialized\r
+ * using one of the following.\r
+ *\r
+ * @warning Failing to initialize a Shadow data type with the appropriate\r
+ * initializer may result in undefined behavior!\r
+ * @note The initializers may change at any time in future versions, but their\r
+ * names will remain the same.\r
+ *\r
+ * <b>Example</b>\r
+ * @code{c}\r
+ * AwsIotShadowCallbackInfo_t callbackInfo = AWS_IOT_SHADOW_CALLBACK_INFO_INITIALIZER;\r
+ * AwsIotShadowDocumentInfo_t documentInfo = AWS_IOT_SHADOW_DOCUMENT_INFO_INITIALIZER;\r
+ * AwsIotShadowOperation_t operation = AWS_IOT_SHADOW_OPERATION_INITIALIZER;\r
+ * @endcode\r
+ *\r
+ * @section shadow_constants_flags Shadow Function Flags\r
+ * @brief Flags that modify the behavior of Shadow library functions.\r
+ *\r
+ * Flags should be bitwise-ORed with each other to change the behavior of\r
+ * Shadow library functions.\r
+ *\r
+ * The following flags are valid for the Shadow operation functions:\r
+ * @ref shadow_function_deleteasync, @ref shadow_function_getasync, @ref shadow_function_updateasync,\r
+ * and their blocking versions.\r
+ * - #AWS_IOT_SHADOW_FLAG_WAITABLE <br>\r
+ * @copybrief AWS_IOT_SHADOW_FLAG_WAITABLE\r
+ * - #AWS_IOT_SHADOW_FLAG_KEEP_SUBSCRIPTIONS <br>\r
+ * @copybrief AWS_IOT_SHADOW_FLAG_KEEP_SUBSCRIPTIONS\r
+ *\r
+ * The following flags are valid for @ref shadow_function_removepersistentsubscriptions.\r
+ * These flags are not valid for the Shadow operation functions.\r
+ * - #AWS_IOT_SHADOW_FLAG_REMOVE_DELETE_SUBSCRIPTIONS <br>\r
+ * @copybrief AWS_IOT_SHADOW_FLAG_REMOVE_DELETE_SUBSCRIPTIONS\r
+ * - #AWS_IOT_SHADOW_FLAG_REMOVE_GET_SUBSCRIPTIONS <br>\r
+ * @copybrief AWS_IOT_SHADOW_FLAG_REMOVE_GET_SUBSCRIPTIONS\r
+ * - #AWS_IOT_SHADOW_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS <br>\r
+ * @copybrief AWS_IOT_SHADOW_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS\r
+ *\r
+ * @note The values of the flags may change at any time in future versions, but\r
+ * their names will remain the same. Additionally, flags which may be used at\r
+ * the same time will be bitwise-exclusive of each other.\r
+ */\r
+\r
+/* @[define_shadow_initializers] */\r
+#define AWS_IOT_SHADOW_CALLBACK_INFO_INITIALIZER { 0 } /**< @brief Initializer for #AwsIotShadowCallbackInfo_t. */\r
+#define AWS_IOT_SHADOW_DOCUMENT_INFO_INITIALIZER { 0 } /**< @brief Initializer for #AwsIotShadowDocumentInfo_t. */\r
+#define AWS_IOT_SHADOW_OPERATION_INITIALIZER NULL /**< @brief Initializer for #AwsIotShadowOperation_t. */\r
+/* @[define_shadow_initializers] */\r
+\r
+/**\r
+ * @brief Allows the use of @ref shadow_function_wait for blocking until completion.\r
+ *\r
+ * This flag is only valid if passed to the functions @ref shadow_function_deleteasync,\r
+ * @ref shadow_function_getasync, or @ref shadow_function_updateasync.\r
+ *\r
+ * An #AwsIotShadowOperation_t <b>MUST</b> be provided if this flag is set.\r
+ * Additionally, an #AwsIotShadowCallbackInfo_t <b>MUST NOT</b> be provided.\r
+ *\r
+ * @note If this flag is set, @ref shadow_function_wait <b>MUST</b> be called to\r
+ * clean up resources.\r
+ */\r
+#define AWS_IOT_SHADOW_FLAG_WAITABLE ( 0x00000001 )\r
+\r
+/**\r
+ * @brief Maintain the subscriptions for the Shadow operation topics, even after\r
+ * this function returns.\r
+ *\r
+ * This flag is only valid if passed to the functions @ref shadow_function_deleteasync,\r
+ * @ref shadow_function_getasync, @ref shadow_function_updateasync, or their blocking versions.\r
+ *\r
+ * The Shadow service reports results of Shadow operations by publishing\r
+ * messages to MQTT topics. By default, the functions @ref shadow_function_deleteasync,\r
+ * @ref shadow_function_getasync, and @ref shadow_function_updateasync subscribe to the\r
+ * necessary topics, wait for the Shadow service to publish the result of the\r
+ * Shadow operation, then unsubscribe from those topics. This workflow is suitable\r
+ * for infrequent Shadow operations, but is inefficient for frequent, periodic\r
+ * Shadow operations (where subscriptions for the Shadow operation topics would be\r
+ * constantly added and removed).\r
+ *\r
+ * This flag causes @ref shadow_function_deleteasync, @ref shadow_function_getasync, or\r
+ * @ref shadow_function_updateasync to maintain Shadow operation topic subscriptions,\r
+ * even after the function returns. These subscriptions may then be used by a\r
+ * future call to the same function.\r
+ *\r
+ * This flags only needs to be set once, after which subscriptions are maintained\r
+ * and reused for a specific Thing Name and Shadow function. The function @ref\r
+ * shadow_function_removepersistentsubscriptions may be used to remove\r
+ * subscriptions maintained by this flag.\r
+ */\r
+#define AWS_IOT_SHADOW_FLAG_KEEP_SUBSCRIPTIONS ( 0x00000002 )\r
+\r
+/**\r
+ * @brief Remove the persistent subscriptions from a Shadow delete operation.\r
+ *\r
+ * This flag is only valid if passed to the function @ref\r
+ * shadow_function_removepersistentsubscriptions.\r
+ *\r
+ * This flag may be passed to @ref shadow_function_removepersistentsubscriptions\r
+ * to remove any subscriptions for a specific Thing Name maintained by a previous\r
+ * call to @ref shadow_function_deleteasync or @ref shadow_function_deletesync.\r
+ *\r
+ * @warning Do not call @ref shadow_function_removepersistentsubscriptions with\r
+ * this flag for Thing Names with any in-progress Shadow delete operations.\r
+ */\r
+#define AWS_IOT_SHADOW_FLAG_REMOVE_DELETE_SUBSCRIPTIONS ( 0x00000001 )\r
+\r
+/**\r
+ * @brief Remove the persistent subscriptions from a Shadow get operation.\r
+ *\r
+ * This flag is only valid if passed to the function @ref\r
+ * shadow_function_removepersistentsubscriptions.\r
+ *\r
+ * This flag may be passed to @ref shadow_function_removepersistentsubscriptions\r
+ * to remove any subscriptions for a specific Thing Name maintained by a previous\r
+ * call to @ref shadow_function_getasync or @ref shadow_function_getsync.\r
+ *\r
+ * @warning Do not call @ref shadow_function_removepersistentsubscriptions with\r
+ * this flag for Thing Names with any in-progress Shadow get operations.\r
+ */\r
+#define AWS_IOT_SHADOW_FLAG_REMOVE_GET_SUBSCRIPTIONS ( 0x00000002 )\r
+\r
+/**\r
+ * @brief Remove the persistent subscriptions from a Shadow update operation.\r
+ *\r
+ * This flag is only valid if passed to the function @ref\r
+ * shadow_function_removepersistentsubscriptions.\r
+ *\r
+ * This flag may be passed to @ref shadow_function_removepersistentsubscriptions\r
+ * to remove any subscriptions for a specific Thing Name maintained by a previous\r
+ * call to @ref shadow_function_updateasync or @ref shadow_function_updatesync.\r
+ *\r
+ * @warning Do not call @ref shadow_function_removepersistentsubscriptions with\r
+ * this flag for Thing Names with any in-progress Shadow update operations.\r
+ */\r
+#define AWS_IOT_SHADOW_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS ( 0x00000004 )\r
+\r
+#endif /* ifndef AWS_IOT_SHADOW_TYPES_H_ */\r
projects / freertos / blobdiff