len0rd/FreeRTOS-Kernel
1
0
Fork 0
mirror of https://github.com/FreeRTOS/FreeRTOS-Kernel.git synced 2025-08-30 06:58:33 -04:00
Code Issues Projects Releases Packages Wiki Activity

Add the Labs projects provided in the V10.2.1_191129 zip file.

Browse source
This commit is contained in:
Richard Barry 2019-12-02 23:39:25 +00:00
parent 46e5937529
commit e5708b38e9
801 changed files with 356576 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

909
FreeRTOS-Labs/Source/FreeRTOS-IoT-Libraries/c_sdk/aws/shadow/include/aws_iot_shadow.h Normal file
View file

@ -0,0 +1,909 @@
/*
* 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_ */

641
FreeRTOS-Labs/Source/FreeRTOS-IoT-Libraries/c_sdk/aws/shadow/include/types/aws_iot_shadow_types.h Normal file
View file

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