aws_iot_shadow_types.h File Reference

Types of the Thing Shadow library. More...

#include "iot_config.h"
#include "types/iot_mqtt_types.h"

Go to the source code of this file.

Data Structures
struct	AwsIotShadowCallbackParam_t
	Parameter to a Shadow callback function. More...
struct	AwsIotShadowCallbackInfo_t
	Information on a user-provided Shadow callback function. More...
struct	AwsIotShadowDocumentInfo_t
	Information on a Shadow document for AwsIotShadow_GetAsync or AwsIotShadow_UpdateAsync. More...

Macros
#define	AWS_IOT_SHADOW_CALLBACK_INFO_INITIALIZER   { 0 }
	Initializer for AwsIotShadowCallbackInfo_t.
#define	AWS_IOT_SHADOW_DOCUMENT_INFO_INITIALIZER   { 0 }
	Initializer for AwsIotShadowDocumentInfo_t.
#define	AWS_IOT_SHADOW_OPERATION_INITIALIZER   NULL
	Initializer for AwsIotShadowOperation_t.
#define	AWS_IOT_SHADOW_FLAG_WAITABLE   ( 0x00000001U )
	Allows the use of AwsIotShadow_Wait for blocking until completion. More...
#define	AWS_IOT_SHADOW_FLAG_KEEP_SUBSCRIPTIONS   ( 0x00000002UL )
	Maintain the subscriptions for the Shadow operation topics, even after this function returns. More...
#define	AWS_IOT_SHADOW_FLAG_REMOVE_DELETE_SUBSCRIPTIONS   ( 0x00000001UL )
	Remove the persistent subscriptions from a Shadow delete operation. More...
#define	AWS_IOT_SHADOW_FLAG_REMOVE_GET_SUBSCRIPTIONS   ( 0x00000002UL )
	Remove the persistent subscriptions from a Shadow get operation. More...
#define	AWS_IOT_SHADOW_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS   ( 0x00000004UL )
	Remove the persistent subscriptions from a Shadow update operation. More...

Typedefs
typedef struct _shadowOperation *	AwsIotShadowOperation_t
	Opaque handle that references an in-progress Shadow operation. More...

Enumerations
enum	AwsIotShadowError_t {   AWS_IOT_SHADOW_SUCCESS = 0, AWS_IOT_SHADOW_STATUS_PENDING = 1, AWS_IOT_SHADOW_INIT_FAILED = 2, AWS_IOT_SHADOW_BAD_PARAMETER = 3,   AWS_IOT_SHADOW_NO_MEMORY = 4, AWS_IOT_SHADOW_MQTT_ERROR = 5, AWS_IOT_SHADOW_BAD_RESPONSE = 7, AWS_IOT_SHADOW_TIMEOUT = 8,   AWS_IOT_SHADOW_NOT_INITIALIZED = 11, AWS_IOT_SHADOW_BAD_REQUEST = 400, AWS_IOT_SHADOW_UNAUTHORIZED = 401, AWS_IOT_SHADOW_FORBIDDEN = 403,   AWS_IOT_SHADOW_NOT_FOUND = 404, AWS_IOT_SHADOW_CONFLICT = 409, AWS_IOT_SHADOW_TOO_LARGE = 413, AWS_IOT_SHADOW_UNSUPPORTED = 415,   AWS_IOT_SHADOW_TOO_MANY_REQUESTS = 429, AWS_IOT_SHADOW_SERVER_ERROR = 500 }
	Return codes of Shadow functions. More...
enum	AwsIotShadowCallbackType_t {   AWS_IOT_SHADOW_DELETE_COMPLETE, AWS_IOT_SHADOW_GET_COMPLETE, AWS_IOT_SHADOW_UPDATE_COMPLETE, AWS_IOT_SHADOW_DELTA_CALLBACK,   AWS_IOT_SHADOW_UPDATED_CALLBACK }
	Types of Shadow library callbacks. More...

Detailed Description

Types of the Thing Shadow library.

Macro Definition Documentation

AWS_IOT_SHADOW_FLAG_WAITABLE

#define AWS_IOT_SHADOW_FLAG_WAITABLE   ( 0x00000001U )

Allows the use of AwsIotShadow_Wait for blocking until completion.

This flag is only valid if passed to the functions AwsIotShadow_DeleteAsync, AwsIotShadow_GetAsync, or AwsIotShadow_UpdateAsync.

An AwsIotShadowOperation_t MUST be provided if this flag is set. Additionally, an AwsIotShadowCallbackInfo_t MUST NOT be provided.

Note

If this flag is set, AwsIotShadow_Wait MUST be called to clean up resources.

AWS_IOT_SHADOW_FLAG_KEEP_SUBSCRIPTIONS

#define AWS_IOT_SHADOW_FLAG_KEEP_SUBSCRIPTIONS   ( 0x00000002UL )

Maintain the subscriptions for the Shadow operation topics, even after this function returns.

This flag is only valid if passed to the functions AwsIotShadow_DeleteAsync, AwsIotShadow_GetAsync, AwsIotShadow_UpdateAsync, or their blocking versions.

The Shadow service reports results of Shadow operations by publishing messages to MQTT topics. By default, the functions AwsIotShadow_DeleteAsync, AwsIotShadow_GetAsync, and AwsIotShadow_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 AwsIotShadow_DeleteAsync, AwsIotShadow_GetAsync, or AwsIotShadow_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 AwsIotShadow_RemovePersistentSubscriptions may be used to remove subscriptions maintained by this flag.

AWS_IOT_SHADOW_FLAG_REMOVE_DELETE_SUBSCRIPTIONS

#define AWS_IOT_SHADOW_FLAG_REMOVE_DELETE_SUBSCRIPTIONS   ( 0x00000001UL )

Remove the persistent subscriptions from a Shadow delete operation.

This flag is only valid if passed to the function AwsIotShadow_RemovePersistentSubscriptions.

This flag may be passed to AwsIotShadow_RemovePersistentSubscriptions to remove any subscriptions for a specific Thing Name maintained by a previous call to AwsIotShadow_DeleteAsync or AwsIotShadow_DeleteSync.

Warning

Do not call AwsIotShadow_RemovePersistentSubscriptions with this flag for Thing Names with any in-progress Shadow delete operations.

AWS_IOT_SHADOW_FLAG_REMOVE_GET_SUBSCRIPTIONS

#define AWS_IOT_SHADOW_FLAG_REMOVE_GET_SUBSCRIPTIONS   ( 0x00000002UL )

Remove the persistent subscriptions from a Shadow get operation.

This flag is only valid if passed to the function AwsIotShadow_RemovePersistentSubscriptions.

This flag may be passed to AwsIotShadow_RemovePersistentSubscriptions to remove any subscriptions for a specific Thing Name maintained by a previous call to AwsIotShadow_GetAsync or AwsIotShadow_GetSync.

Warning

Do not call AwsIotShadow_RemovePersistentSubscriptions with this flag for Thing Names with any in-progress Shadow get operations.

AWS_IOT_SHADOW_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS

#define AWS_IOT_SHADOW_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS   ( 0x00000004UL )

Remove the persistent subscriptions from a Shadow update operation.

This flag is only valid if passed to the function AwsIotShadow_RemovePersistentSubscriptions.

This flag may be passed to AwsIotShadow_RemovePersistentSubscriptions to remove any subscriptions for a specific Thing Name maintained by a previous call to AwsIotShadow_UpdateAsync or AwsIotShadow_UpdateSync.

Warning

Do not call AwsIotShadow_RemovePersistentSubscriptions with this flag for Thing Names with any in-progress Shadow update operations.