shadow.h File Reference

User-facing Shadow functions, and parameter structs. More...

#include <stdint.h>
#include "shadow_config.h"
#include "shadow_config_defaults.h"

Go to the source code of this file.

Macros
#define	SHADOW_PREFIX   "$aws/things/"
	The common prefix of all Shadow MQTT topics from here https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html.
#define	SHADOW_PREFIX_LENGTH   ( ( uint16_t ) ( sizeof( SHADOW_PREFIX ) - 1U ) )
	The length of SHADOW_PREFIX.
#define	SHADOW_OP_DELETE   "/shadow/delete"
	The string representing a Shadow "DELETE" operation in a Shadow MQTT topic.
#define	SHADOW_OP_DELETE_LENGTH   ( ( uint16_t ) ( sizeof( SHADOW_OP_DELETE ) - 1U ) )
	The length of SHADOW_OP_DELETE.
#define	SHADOW_OP_GET   "/shadow/get"
	The string representing a Shadow "GET" operation in a Shadow MQTT topic.
#define	SHADOW_OP_GET_LENGTH   ( ( uint16_t ) ( sizeof( SHADOW_OP_GET ) - 1U ) )
	The length of SHADOW_OP_GET.
#define	SHADOW_OP_UPDATE   "/shadow/update"
	The string representing a Shadow "UPDATE" operation in a Shadow MQTT topic.
#define	SHADOW_OP_UPDATE_LENGTH   ( ( uint16_t ) ( sizeof( SHADOW_OP_UPDATE ) - 1U ) )
	The length of SHADOW_OP_UPDATE.
#define	SHADOW_SUFFIX_ACCEPTED   "/accepted"
	The suffix for a Shadow operation "accepted" topic.
#define	SHADOW_SUFFIX_ACCEPTED_LENGTH   ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_ACCEPTED ) - 1U ) )
	The length of SHADOW_SUFFIX_ACCEPTED.
#define	SHADOW_SUFFIX_REJECTED   "/rejected"
	The suffix for a Shadow operation "rejected" topic.
#define	SHADOW_SUFFIX_REJECTED_LENGTH   ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_REJECTED ) - 1U ) )
	The length of SHADOW_SUFFIX_REJECTED.
#define	SHADOW_SUFFIX_DELTA   "/delta"
	The suffix for a Shadow "delta" topic.
#define	SHADOW_SUFFIX_DELTA_LENGTH   ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_DELTA ) - 1U ) )
	The length of SHADOW_SUFFIX_DELTA.
#define	SHADOW_SUFFIX_DOCUMENTS   "/documents"
	The suffix for a Shadow "documents" topic.
#define	SHADOW_SUFFIX_DOCUMENTS_LENGTH   ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_DOCUMENTS ) - 1U ) )
	The length of SHADOW_SUFFIX_DOCUMENTS.
#define	SHADOW_SUFFIX_NULL
	The suffix for a "null" suffix.
#define	SHADOW_SUFFIX_NULL_LENGTH   ( 0U )
	The length of null suffix.
#define	SHADOW_THINGNAME_LENGTH_MAX   ( 128U )
	The maximum length of Thing Name.
#define	SHADOW_TOPIC_LENGTH(operationLength, suffixLength, thingNameLength)    ( operationLength + suffixLength + thingNameLength + SHADOW_PREFIX_LENGTH )
	Compute shadow topic length. More...
#define	SHADOW_TOPIC_LENGTH_UPDATE(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength )
	Compute the length of shadow topic "$aws/things/<thingName>/shadow/update".
#define	SHADOW_TOPIC_LENGTH_UPDATE_ACCEPTED(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength )
	Compute the length of shadow topic "$aws/things/<thingName>/shadow/update/accepted".
#define	SHADOW_TOPIC_LENGTH_UPDATE_REJECTED(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength )
	Compute the length of shadow topic "$aws/things/<thingName>/shadow/update/rejected".
#define	SHADOW_TOPIC_LENGTH_UPDATE_DOCUMENTS(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DOCUMENTS_LENGTH, thingNameLength )
	Compute the length of shadow topic "$aws/things/<thingName>/shadow/update/documents".
#define	SHADOW_TOPIC_LENGTH_UPDATE_DELTA(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DELTA_LENGTH, thingNameLength )
	Compute the length of shadow topic "$aws/things/<thingName>/shadow/update/delta".
#define	SHADOW_TOPIC_LENGTH_GET(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength )
	Compute the length of shadow topic "$aws/things/<thingName>/shadow/get".
#define	SHADOW_TOPIC_LENGTH_GET_ACCEPTED(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength )
	Compute the length of shadow topic "$aws/things/<thingName>/shadow/get/accepted".
#define	SHADOW_TOPIC_LENGTH_GET_REJECTED(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength )
	Compute the length of shadow topic "$aws/things/<thingName>/shadow/get/rejected".
#define	SHADOW_TOPIC_LENGTH_DELETE(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength )
	Compute the length of shadow topic "$aws/things/<thingName>/shadow/delete".
#define	SHADOW_TOPIC_LENGTH_DELETE_ACCEPTED(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength )
	Compute the length of shadow topic "$aws/things/<thingName>/shadow/delete/accepted".
#define	SHADOW_TOPIC_LENGTH_DELETE_REJECTED(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength )
	Compute the length of shadow topic "$aws/things/<thingName>/shadow/delete/rejected".
#define	SHADOW_TOPIC_LENGTH_MAX(thingNameLength)    SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DOCUMENTS_LENGTH, thingNameLength )
	Compute the length of the longest shadow topic.
#define	SHADOW_TOPIC_STRING(thingName, operation, suffix)    ( SHADOW_PREFIX thingName operation suffix )
	Assemble constant shadow topic strings when Thing Name is known at compile time. More...
#define	SHADOW_TOPIC_STRING_UPDATE(thingName)    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_NULL )
	Assemble shadow topic string "$aws/things/<thingName>/shadow/update".
#define	SHADOW_TOPIC_STRING_UPDATE_ACCEPTED(thingName)    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_ACCEPTED )
	Assemble shadow topic string "$aws/things/<thingName>/shadow/update/accepted".
#define	SHADOW_TOPIC_STRING_UPDATE_REJECTED(thingName)    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_REJECTED )
	Assemble shadow topic string "$aws/things/<thingName>/shadow/update/rejected".
#define	SHADOW_TOPIC_STRING_UPDATE_DOCUMENTS(thingName)    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_DOCUMENTS )
	Assemble shadow topic string "$aws/things/<thingName>/shadow/update/documents".
#define	SHADOW_TOPIC_STRING_UPDATE_DELTA(thingName)    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_DELTA )
	Assemble shadow topic string "$aws/things/<thingName>/shadow/update/delta".
#define	SHADOW_TOPIC_STRING_GET(thingName)    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_GET, SHADOW_SUFFIX_NULL )
	Assemble shadow topic string "$aws/things/<thingName>/shadow/get".
#define	SHADOW_TOPIC_STRING_GET_ACCEPTED(thingName)    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_GET, SHADOW_SUFFIX_ACCEPTED )
	Assemble shadow topic string "$aws/things/<thingName>/shadow/get/accepted".
#define	SHADOW_TOPIC_STRING_GET_REJECTED(thingName)    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_GET, SHADOW_SUFFIX_REJECTED )
	Assemble shadow topic string "$aws/things/<thingName>/shadow/get/rejected".
#define	SHADOW_TOPIC_STRING_DELETE(thingName)    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_DELETE, SHADOW_SUFFIX_NULL )
	Assemble shadow topic string "$aws/things/<thingName>/shadow/delete".
#define	SHADOW_TOPIC_STRING_DELETE_ACCEPTED(thingName)    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_DELETE, SHADOW_SUFFIX_ACCEPTED )
	Assemble shadow topic string "$aws/things/<thingName>/shadow/delete/accepted".
#define	SHADOW_TOPIC_STRING_DELETE_REJECTED(thingName)    SHADOW_TOPIC_STRING( thingName, SHADOW_OP_DELETE, SHADOW_SUFFIX_REJECTED )
	Assemble shadow topic string "$aws/things/<thingName>/shadow/delete/rejected".

Enumerations
enum	ShadowMessageType_t {   ShadowMessageTypeGetAccepted = 0, ShadowMessageTypeGetRejected, ShadowMessageTypeDeleteAccepted, ShadowMessageTypeDeleteRejected,   ShadowMessageTypeUpdateAccepted, ShadowMessageTypeUpdateRejected, ShadowMessageTypeUpdateDocuments, ShadowMessageTypeUpdateDelta,   ShadowMessageTypeMaxNum }
	Each of these values describes the type of a shadow message. https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html.
enum	ShadowTopicStringType_t {   ShadowTopicStringTypeGet = 0, ShadowTopicStringTypeGetAccepted, ShadowTopicStringTypeGetRejected, ShadowTopicStringTypeDelete,   ShadowTopicStringTypeDeleteAccepted, ShadowTopicStringTypeDeleteRejected, ShadowTopicStringTypeUpdate, ShadowTopicStringTypeUpdateAccepted,   ShadowTopicStringTypeUpdateRejected, ShadowTopicStringTypeUpdateDocuments, ShadowTopicStringTypeUpdateDelta, ShadowTopicStringTypeMaxNum }
	Each of these values describes the type of a shadow topic string. More...
enum	ShadowStatus_t {   SHADOW_SUCCESS = 0, SHADOW_FAIL, SHADOW_BAD_PARAMETER, SHADOW_BUFFER_TOO_SMALL,   SHADOW_THINGNAME_PARSE_FAILED, SHADOW_SHADOW_MESSAGE_TYPE_PARSE_FAILED }
	Return codes from Shadow functions. More...

Functions
ShadowStatus_t	Shadow_GetTopicString (ShadowTopicStringType_t topicType, const char *pThingName, uint8_t thingNameLength, char *pTopicBuffer, uint16_t bufferSize, uint16_t *pOutLength)
	Assemble shadow topic string when Thing Name is only known at run time. If the Thing Name is known at compile time, use SHADOW_TOPIC_STRING_* macros instead. More...
ShadowStatus_t	Shadow_MatchTopic (const char *pTopic, uint16_t topicLength, ShadowMessageType_t *pMessageType, const char **pThingName, uint16_t *pThingNameLength)
	Given the topic string of an incoming message, determine whether it is related to a device shadow; if it is, return information about the type of device shadow message, and a pointer to the Thing Name inside of the topic string. See ShadowMessageType_t for the list of message types. Those types correspond to Device Shadow Topics. More...

Detailed Description

User-facing Shadow functions, and parameter structs.

Function Documentation

Shadow_GetTopicString()

ShadowStatus_t Shadow_GetTopicString	(	ShadowTopicStringType_t	topicType,
		const char *	pThingName,
		uint8_t	thingNameLength,
		char *	pTopicBuffer,
		uint16_t	bufferSize,
		uint16_t *	pOutLength
	)

Assemble shadow topic string when Thing Name is only known at run time. If the Thing Name is known at compile time, use SHADOW_TOPIC_STRING_* macros instead.

Parameters

[in]	topicType	Indicates what topic will be written into the buffer pointed to by pTopicBuffer. can be one of: ShadowTopicStringTypeGet ShadowTopicStringTypeGetAccepted ShadowTopicStringTypeGetRejected ShadowTopicStringTypeDelete ShadowTopicStringTypeDeleteAccepted ShadowTopicStringTypeDeleteRejected ShadowTopicStringTypeUpdate ShadowTopicStringTypeUpdateAccepted ShadowTopicStringTypeUpdateRejected ShadowTopicStringTypeUpdateDocuments ShadowTopicStringTypeUpdateDelta
[in]	pThingName	Thing Name string. No need to be null terminated. Must not be NULL.
[in]	thingNameLength	Length of Thing Name string pointed to by pThingName. Must not be zero.
[out]	pTopicBuffer	Pointer to buffer for returning the topic string. Caller is responsible for supplying memory pointed to by pTopicBuffer. This function does not fill in the terminating null character. The app can supply a buffer that does not have space for holding the null character.
[in]	bufferSize	Length of pTopicBuffer. This function will return error if bufferSize is less than the length of the assembled topic string.
[out]	pOutLength	Pointer to caller-supplied memory for returning the length of the topic string.

Returns

One of the following:

• SHADOW_SUCCESS if successful.
• An error code if failed to assemble.

Example

// Variables used in this example.
 
#define SHADOW_TOPIC_MAX_LENGTH  ( 256U )
 
ShadowStatus_t shadowStatus = SHADOW_STATUS_SUCCESS;
char topicBuffer[ SHADOW_TOPIC_MAX_LENGTH ] = { 0 };
uint16_t bufferSize = SHADOW_TOPIC_MAX_LENGTH;
uint16_t outLength = 0;
const char * pThingName = "TestThingName";
uint16_t thingNameLength  = ( sizeof( thingName ) - 1U );
 
shadowStatus = Shadow_GetTopicString( SHADOW_TOPIC_STRING_TYPE_UPDATE_DELTA,
                                      pThingName,
                                      thingNameLength,
                                      & ( topicBuffer[ 0 ] ),
                                      bufferSize,
                                      & outLength );
 
if( shadowStatus == SHADOW_STATUS_SUCCESS )
{
     // The assembled topic string is put in pTopicBuffer with the length outLength.
}

Shadow_MatchTopic()

ShadowStatus_t Shadow_MatchTopic	(	const char *	pTopic,
		uint16_t	topicLength,
		ShadowMessageType_t *	pMessageType,
		const char **	pThingName,
		uint16_t *	pThingNameLength
	)

Given the topic string of an incoming message, determine whether it is related to a device shadow; if it is, return information about the type of device shadow message, and a pointer to the Thing Name inside of the topic string. See ShadowMessageType_t for the list of message types. Those types correspond to Device Shadow Topics.

Note

When this function returns, the pointer pThingName points at the first character of the <thingName> segment inside of the topic string. Caller is responsible for keeping the memory holding the topic string around while accessing the Thing Name through pThingName.

Parameters

[in]	pTopic	Pointer to the MQTT topic string. Does not have to be null-terminated.
[in]	topicLength	Length of the MQTT topic string.
[out]	pMessageType	Pointer to caller-supplied memory for returning the type of the shadow message.
[out]	pThingName	Points to the 1st character of Thing Name inside of the topic string, and can be null if caller does not need to know the Thing Name contained in the topic string.
[out]	pThingNameLength	Pointer to caller-supplied memory for returning the length of the Thing Name, and can be null if caller does not need to know the Thing Name contained in the topic string.

Returns

One of the following:

• SHADOW_SUCCESS if the message is related to a device shadow;
• An error code defined in ShadowStatus_t if the message is not related to a device shadow, if any input parameter is invalid, or if the function fails to parse the topic string.

Example

// Variables used in this example.
 
#define SHADOW_TOPIC_MAX_LENGTH  ( 256U )
 
ShadowStatus_te shadowStatus = SHADOW_STATUS_SUCCESS;
char * pTopicName; //usually supplied by MQTT stack
uint16_t topicNameLength; //usually supplied by MQTT stack
ShadowMessageType_t messageType;
 
shadowStatus = Shadow_MatchTopic( pTopicName,
                                  topicNameLength,
                                  & messageType,
                                  NULL,
                                  NULL );
 
if( shadowStatus == SHADOW_STATUS_SUCCESS )
{
     // It is a device shadow message. And the type of the message has been returned in messageType.
     // Now we can act on the message.
}