Shadow API configuration, functions, and parameter structs. More...

#include "FreeRTOS.h"
#include "aws_mqtt_agent.h"

Data Structures
struct	ShadowCreateParams
	Parameters to pass into SHADOW_ClientCreate. More...

struct	ShadowOperationParams
	Parameters for a Shadow API operation. More...

struct	ShadowCallbackParams
	Parameters to SHADOW_RegisterCallbacks. More...

Macros
#define	eShadowJSMNPart ( -3 )
	Return values of Shadow API functions. More...

#define	eShadowJSMNInval ( -2 )

#define	eShadowJSMNNoMem ( -1 )

#define	eShadowSuccess ( 0 )

#define	eShadowTimeout ( 1 )

#define	eShadowFailure ( 2 )

#define	eShadowUnknown ( 3 )

Typedefs
typedef void *	ShadowClientHandle_t
	The handle of a Shadow Client.

typedef enum ShadowMQTTClientType	ShadowMQTTClientType_t
	Type of MQTT client in a new Shadow Client. More...

typedef struct ShadowCreateParams	ShadowCreateParams_t
	Parameters to pass into SHADOW_ClientCreate.

typedef struct ShadowOperationParams	ShadowOperationParams_t
	Parameters for a Shadow API operation. More...

typedef BaseType_t(*	ShadowUpdatedCallback_t) (void pvUserData, const char const pcThingName, const char *const pcUpdateDocument, uint32_t ulDocumentLength, MQTTBufferHandle_t xBuffer)
	Function signature of a callback function registered for /update/documents. More...

typedef void(*	ShadowDeletedCallback_t) (void pvUserData, const char const pcThingName)
	Function header of a callback function registered for /delete/accepted. More...

typedef BaseType_t(*	ShadowDeltaCallback_t) (void pvUserData, const char const pcThingName, const char *const pcDeltaDocument, uint32_t ulDocumentLength, MQTTBufferHandle_t xBuffer)
	Function header of a callback function registered for /update/delta. More...

typedef struct ShadowCallbackParams	ShadowCallbackParams_t
	Parameters to SHADOW_RegisterCallbacks.

Enumerations
enum	ShadowMQTTClientType { eSharedMQTTClient, eDedicatedMQTTClient }
	Type of MQTT client in a new Shadow Client. More...

Functions
ShadowReturnCode_t	SHADOW_ClientCreate (ShadowClientHandle_t pxShadowClientHandle, const ShadowCreateParams_t const pxShadowCreateParams)
	Create a new Shadow Client. More...

ShadowReturnCode_t	SHADOW_ClientConnect (ShadowClientHandle_t xShadowClientHandle, MQTTAgentConnectParams_t *const pxConnectParams, TickType_t xTimeoutTicks)
	Connect to the Shadow service. More...

ShadowReturnCode_t	SHADOW_ClientDisconnect (ShadowClientHandle_t xShadowClientHandle)
	Disconnect from the Shadow service. More...

ShadowReturnCode_t	SHADOW_ClientDelete (ShadowClientHandle_t xShadowClientHandle)
	Free resources used by a Shadow Client. More...

ShadowReturnCode_t	SHADOW_Update (ShadowClientHandle_t xShadowClientHandle, ShadowOperationParams_t *const pxUpdateParams, TickType_t xTimeoutTicks)
	Update a Thing Shadow. More...

ShadowReturnCode_t	SHADOW_Get (ShadowClientHandle_t xShadowClientHandle, ShadowOperationParams_t *const pxGetParams, TickType_t xTimeoutTicks)
	Get a Thing Shadow from the cloud. More...

ShadowReturnCode_t	SHADOW_Delete (ShadowClientHandle_t xShadowClientHandle, ShadowOperationParams_t *const pxDeleteParams, TickType_t xTimeoutTicks)
	Delete a Thing Shadow in the cloud. More...

ShadowReturnCode_t	SHADOW_RegisterCallbacks (ShadowClientHandle_t xShadowClientHandle, ShadowCallbackParams_t *const pxCallbackParams, TickType_t xTimeoutTicks)
	Register callback functions. More...

ShadowReturnCode_t	SHADOW_ReturnMQTTBuffer (ShadowClientHandle_t xShadowClientHandle, MQTTBufferHandle_t xBufferHandle)
	Return an MQTT Buffer to the MQTT client. More...

#define	eShadowRejectedBadRequest ( 400 )
	Shadow service rejection reasons.

#define	eShadowRejectedUnauthorized ( 401 )

#define	eShadowRejectedForbidden ( 403 )

#define	eShadowRejectedNotFound ( 404 )

#define	eShadowRejectedConflict ( 409 )

#define	eShadowRejectedPayloadTooLarge ( 413 )

#define	eShadowRejectedUnsupportedMediaType ( 415 )

#define	eShadowRejectedTooManyRequests ( 429 )

#define	eShadowRejectedInternalServerError ( 500 )

typedef int16_t	ShadowReturnCode_t

Detailed Description

Shadow API configuration, functions, and parameter structs.

Definition in file aws_shadow.h.

Macro Definition Documentation

◆ eShadowFailure

#define eShadowFailure ( 2 )

Failure code; signifies that at least one subroutine failed to complete and did not time out.

Definition at line 79 of file aws_shadow.h.

◆ eShadowJSMNPart

#define eShadowJSMNPart ( -3 )

Return values of Shadow API functions.

Negative values indicate jsmn (JSON parser) errors, and 0 indicates success. Positive values indicate other errors. Values in the range of 400 to 500 correspond to Shadow service rejection reasons.

Refer to jsmn.h for jsmn errors.

Refer to http://docs.aws.amazon.com/iot/latest/developerguide/thing-shadow-error-messages.html for Shadow service rejection reasons.

Definition at line 57 of file aws_shadow.h.

◆ eShadowSuccess

#define eShadowSuccess ( 0 )

An operation was accepted by the Shadow service, and all subroutines completed successfully.

Definition at line 63 of file aws_shadow.h.

◆ eShadowTimeout

#define eShadowTimeout ( 1 )

Timeout signifies that at least one of the API call's subroutines failed to complete within the given time. This error can usually be fixed by increasing the timeout parameter.

Note

Timeout doesn't always imply rejection. An operation may still be accepted after a timeout. However, the Shadow Client will not notify of acceptance or rejection after a timeout.
If an update fails because of incorrect JSON syntax in the update document, the update API call will return this code instead of eShadowRejectedBadRequest and print an error message if #shadowENABLE_DEBUG_LOGS is 1.

Definition at line 75 of file aws_shadow.h.

◆ eShadowUnknown

#define eShadowUnknown ( 3 )

Indicates neither failure nor success. This value should never be returned by a Shadow API function, but is used internally.

Definition at line 83 of file aws_shadow.h.

Typedef Documentation

◆ ShadowDeletedCallback_t

typedef void( * ShadowDeletedCallback_t) (void *pvUserData, const char *const pcThingName)

Function header of a callback function registered for /delete/accepted.

Parameters

in	Custom user data.
pcThingName	The Name of the Thing whose Shadow was deleted.

Note: Callback functions are called from the MQTT task.

Warning: Do not make any blocking calls (including SHADOW_Update, SHADOW_Get, or SHADOW_Delete) in a callback function!

Definition at line 237 of file aws_shadow.h.

◆ ShadowDeltaCallback_t

typedef BaseType_t( * ShadowDeltaCallback_t) (void *pvUserData, const char *const pcThingName, const char *const pcDeltaDocument, uint32_t ulDocumentLength, MQTTBufferHandle_t xBuffer)

Function header of a callback function registered for /update/delta.

Parameters

in	Custom user data.
pcThingName	The Thing Name of the delta document.
pcDeltaDocument	The delta document, a JSON string.
ulDocumentLength	The length of the delta document.
xBuffer	The MQTT buffer containing `pcDeltaDocument`. This buffer must eventually be returned by calling SHADOW_ReturnMQTTBuffer if taken.

Returns

pdTRUE to take ownership of the MQTT buffer containing pcDeltaDocument
pdFALSE to leave pcDeltaDocument with the MQTT client. The MQTT client may overwrite pcDeltaDocument.

Note: Callback functions are called from the MQTT task.

Warning

Do not make any blocking calls (including SHADOW_Update, SHADOW_Get, or SHADOW_Delete) in a callback function!
The MQTT client does not guarantee that messages on /update/delta will be received in the order they were published. If updates are being performed frequently, it is possible to receive newer delta documents before older ones.

Definition at line 264 of file aws_shadow.h.

◆ ShadowMQTTClientType_t

typedef enum ShadowMQTTClientType ShadowMQTTClientType_t

Type of MQTT client in a new Shadow Client.

The possible values of ShadowCreateParams_t.xMQTTClientType; determines whether to initialize a shared or dedicated MQTT client.

Note: Only eDedicatedMQTTClient is supported at this time.

◆ ShadowOperationParams_t

typedef struct ShadowOperationParams ShadowOperationParams_t

Parameters for a Shadow API operation.

Pass this struct as one of the arguments for SHADOW_Update, SHADOW_Get, or SHADOW_Delete.

◆ ShadowUpdatedCallback_t

typedef BaseType_t( * ShadowUpdatedCallback_t) (void *pvUserData, const char *const pcThingName, const char *const pcUpdateDocument, uint32_t ulDocumentLength, MQTTBufferHandle_t xBuffer)

Function signature of a callback function registered for /update/documents.

Parameters

in	Custom user data.
pcThingName	The Thing Name of the updated Shadow.
pcUpdateDocument	The update document, a JSON string.
ulDocumentLength	The length of the update document.
xBuffer	The MQTT buffer containing `pcUpdateDocument`. This buffer must eventually be returned by calling SHADOW_ReturnMQTTBuffer if taken.

Returns

pdTRUE to take ownership of the MQTT buffer containing pcUpdateDocument
pdFALSE to leave pcUpdateDocument with the MQTT client. The MQTT client may overwrite pcUpdateDocument.

Note: Callback functions are called from the MQTT task.

Warning

Do not make any blocking calls (including SHADOW_Update, SHADOW_Get, or SHADOW_Delete) in a callback function!
The MQTT client does not guarantee that messages on /update/documents will be received in the order they were published. If updates are being performed frequently, it is possible to receive newer update documents before older ones.

Definition at line 221 of file aws_shadow.h.

Enumeration Type Documentation

◆ ShadowMQTTClientType

enum ShadowMQTTClientType

Type of MQTT client in a new Shadow Client.

The possible values of ShadowCreateParams_t.xMQTTClientType; determines whether to initialize a shared or dedicated MQTT client.

Note: Only eDedicatedMQTTClient is supported at this time.

Enumerator
eSharedMQTTClient	A shared MQTT client that may be used for purposes other than Shadow Client. Currently unsupported.
eDedicatedMQTTClient	A dedicated MQTT client to be used only by Shadow Client.

Definition at line 107 of file aws_shadow.h.

Function Documentation

◆ SHADOW_ClientConnect()

ShadowReturnCode_t SHADOW_ClientConnect	(	ShadowClientHandle_t	xShadowClientHandle,
		MQTTAgentConnectParams_t *const	pxConnectParams,
		TickType_t	xTimeoutTicks
	)

Connect to the Shadow service.

For a Shadow Client with a dedicated MQTT Client (eDedicatedMQTTClient), calling this function is the only way to connect to the Shadow service. For a Shadow Client with a shared MQTT Client (eSharedMQTTClient), calling this function is equivalent to calling MQTT_AGENT_Connect with the corresponding shared MQTT Client handle.

Parameters

[in]	xShadowClientHandle	Handle of Shadow Client to connect.
[in]	pxConnectParams	Pointer to a `TradstoneMQTTConnectParams_t` struct. Note: ClientHandle should be at the top of user data passed in pxConnectParams
[in]	xTimeoutTicks	Number of ticks this function may block before timeout.

Returns: #ShadowReturnCode.

◆ SHADOW_ClientCreate()

ShadowReturnCode_t SHADOW_ClientCreate	(	ShadowClientHandle_t *	pxShadowClientHandle,
		const ShadowCreateParams_t *const	pxShadowCreateParams
	)

Create a new Shadow Client.

Parameters

[out]	pxShadowClientHandle	Output parameter for the handle of the newly-created Shadow Client. Only valid if the return code is eShadowSuccess.
[in]	pxShadowCreateParams	Pointer to a ShadowCreateParams struct.
[in]	xTimeoutTicks	Number of ticks this function may block before timeout.

Returns: #ShadowReturnCode. The value of output parameter pxShadowClientHandle is valid only if the return code is eShadowSuccess.

Note

If xTimeoutTicks is insufficient time for initialization, this function will timeout and stop Shadow Client initialization. However, this function may block for up to (xTimeoutTicks + #shadowCLEANUP_TIME_MS) time as it cleans up a partially-initialized Shadow Client.

◆ SHADOW_ClientDelete()

ShadowReturnCode_t SHADOW_ClientDelete ( ShadowClientHandle_t xShadowClientHandle )

Free resources used by a Shadow Client.

Parameters

[in] xShadowClientHandle Handle of Shadow Client to be deleted.

Returns: #ShadowReturnCode.

Warning: Do not call while another operation is in progress on the Shadow Client. A Shadow Client must be re-initialized after this function completes if it is to be used again.

◆ SHADOW_ClientDisconnect()

ShadowReturnCode_t SHADOW_ClientDisconnect ( ShadowClientHandle_t xShadowClientHandle )

Disconnect from the Shadow service.

For a Shadow Client with a dedicated MQTT Client (eDedicatedMQTTClient), calling this function is the only way to disconnect from the Shadow service. For a Shadow Client with a shared MQTT Client (eSharedMQTTClient), calling this function is equivalent to calling MQTT_AGENT_Disconnect with the corresponding shared MQTT Client handle.

Parameters

[in] xShadowClientHandle Handle of Shadow Client to disconnect.

Returns: Unless #shadowCLEANUP_TIME_MS is insufficient to disconnect a Shadow Client, this function always returns eShadowSuccess.

◆ SHADOW_Delete()

ShadowReturnCode_t SHADOW_Delete	(	ShadowClientHandle_t	xShadowClientHandle,
		ShadowOperationParams_t *const	pxDeleteParams,
		TickType_t	xTimeoutTicks
	)

Delete a Thing Shadow in the cloud.

Parameters

[in]	xShadowClientHandle	Handle of Shadow Client to use for delete.
[in]	pxDeleteParams	A pointer to a ShadowOperationParams struct.
[in]	xTimeoutTicks	Number of ticks this function may block before timeout.

Returns: #ShadowReturnCode.

Note

If xTimeoutTicks is insufficient time for the delete, this function will timeout and stop the delete. However, this function may block for up to (xTimeoutTicks + #shadowCLEANUP_TIME_MS) time as it cleans up subscriptions.
A timeout does not always mean that the delete failed. The Shadow Service may still accept the delete after this function times out. However, the user will not be notified if acceptance occurs after a timeout. The user may intentionally set a short timeout if the result of the delete isn't relevant, but the timeout must still be long enough for the delete to be published.

◆ SHADOW_Get()

ShadowReturnCode_t SHADOW_Get	(	ShadowClientHandle_t	xShadowClientHandle,
		ShadowOperationParams_t *const	pxGetParams,
		TickType_t	xTimeoutTicks
	)

Get a Thing Shadow from the cloud.

Parameters

[in]	xShadowClientHandle	Handle of Shadow Client to use for get.
	pxGetParams	A pointer to a ShadowOperationParams struct. This is used as both an input and output parameter.
[in]	xTimeoutTicks	Number of ticks this function may block before timeout.

Returns: #ShadowReturnCode.

Note

If xTimeoutTicks is insufficient time for the get, this function will timeout and stop the get. However, this function may block for up to (xTimeoutTicks + #shadowCLEANUP_TIME_MS) time as it cleans up subscriptions.
Documents received from the cloud after a timeout are ignored.
A call to SHADOW_ReturnMQTTBuffer should follow a call to SHADOW_Get to return the MQTT Buffer taken by SHADOW_Get. ShadowOperationParams_t.xBuffer should be passed as xBufferHandle.

◆ SHADOW_RegisterCallbacks()

ShadowReturnCode_t SHADOW_RegisterCallbacks	(	ShadowClientHandle_t	xShadowClientHandle,
		ShadowCallbackParams_t *const	pxCallbackParams,
		TickType_t	xTimeoutTicks
	)

Register callback functions.

Parameters

[in]	xShadowClientHandle	Handle of Shadow Client to use for registering callbacks.
[in]	pxCallbackParams	A pointer to a ShadowCallbackParams struct.
[in]	xTimeoutTicks	Number of ticks this function may block before timeout.

Returns

eShadowSuccess if all callbacks registered successfully.
eShadowFailure if the Shadow Client failed to subscribe to at least one callback topic and did not time out.
eShadowTimeout if the Shadow Client timed out when subscribing to at least one callback topic.

Note

This function will register as many callbacks as it can before xTimeoutTicks elapses.
Callbacks are registered in the order Updated, Deleted, Delta.
If a callback fails to register, this function will print a debug message if #shadowENABLE_DEBUG_LOGS is 1 and attempt to register the next callback.

◆ SHADOW_ReturnMQTTBuffer()

ShadowReturnCode_t SHADOW_ReturnMQTTBuffer	(	ShadowClientHandle_t	xShadowClientHandle,
		MQTTBufferHandle_t	xBufferHandle
	)

Return an MQTT Buffer to the MQTT client.

For a Shadow Client with a dedicated MQTT Client (eDedicatedMQTTClient), calling this function is the only way to return an MQTT Buffer. For a Shadow Client with a shared MQTT Client (eSharedMQTTClient), calling this function is equivalent to calling MQTT_AGENT_ReturnBuffer with the corresponding shared MQTT Client handle.

Parameters

[in]	xShadowClientHandle	Handle of Shadow Client for MQTT Buffer return.
[in]	xBufferHandle	Handle of MQTT Buffer to return.

Returns: #ShadowReturnCode.

Note

This function should be called after every SHADOW_Get call to return the MQTT buffer taken by SHADOW_Get. Otherwise, the MQTT client will run out of buffers after repeated calls to SHADOW_Get.
This function should also be called to return buffers taken in callback functions ShadowUpdatedCallback_t and ShadowDeltaCallback_t.

◆ SHADOW_Update()

ShadowReturnCode_t SHADOW_Update	(	ShadowClientHandle_t	xShadowClientHandle,
		ShadowOperationParams_t *const	pxUpdateParams,
		TickType_t	xTimeoutTicks
	)

Update a Thing Shadow.

Parameters

[in]	xShadowClientHandle	Handle of Shadow Client to use for update.
[in]	pxUpdateParams	A pointer to a ShadowOperationParams struct.
[in]	xTimeoutTicks	Number of ticks this function may block before timeout.

Returns: #ShadowReturnCode.

Note

If xTimeoutTicks is insufficient time for the update, this function will timeout and stop the update. However, this function may block for up to (xTimeoutTicks + #shadowCLEANUP_TIME_MS) time as it cleans up subscriptions.
A timeout does not always mean that the update failed. The Shadow Service may still accept an update after this function times out. However, the user will not be notified if acceptance occurs after a timeout. The user may intentionally set a short timeout if the result of the update isn't relevant, but the timeout must still be long enough for the update to be published.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ eShadowFailure

◆ eShadowJSMNPart

◆ eShadowSuccess

◆ eShadowTimeout

◆ eShadowUnknown

Typedef Documentation

◆ ShadowDeletedCallback_t

◆ ShadowDeltaCallback_t

◆ ShadowMQTTClientType_t

◆ ShadowOperationParams_t

◆ ShadowUpdatedCallback_t

Enumeration Type Documentation

◆ ShadowMQTTClientType

Function Documentation

◆ SHADOW_ClientConnect()

◆ SHADOW_ClientCreate()

◆ SHADOW_ClientDelete()

◆ SHADOW_ClientDisconnect()

◆ SHADOW_Delete()

◆ SHADOW_Get()

◆ SHADOW_RegisterCallbacks()

◆ SHADOW_ReturnMQTTBuffer()

◆ SHADOW_Update()