Implements the user-facing functions of the Shadow library. More...
Macros | |
#define | SHADOW_NAME_MAX_LENGTH ( 64U ) |
Maximum shadow name length. Refer to https://docs.aws.amazon.com/general/latest/gr/iot-core.html#device-shadow-limits for more details about the Device Shadow limits. | |
#define | SHADOW_THINGNAME_MAX_LENGTH ( 128U ) |
Maximum thing name length. Refer to https://docs.aws.amazon.com/general/latest/gr/iot-core.html#device-shadow-limits for more details about the Device Shadow limits. | |
#define | SHADOW_OP_UPDATE_ACCEPTED SHADOW_OP_UPDATE SHADOW_SUFFIX_ACCEPTED |
The string representing "/shadow/update/accepted". | |
#define | SHADOW_OP_UPDATE_REJECTED SHADOW_OP_UPDATE SHADOW_SUFFIX_REJECTED |
The string representing "/shadow/update/rejected". | |
#define | SHADOW_OP_UPDATE_DELTA SHADOW_OP_UPDATE SHADOW_SUFFIX_DELTA |
The string representing "/shadow/update/delta". | |
#define | SHADOW_OP_UPDATE_DOCUMENTS SHADOW_OP_UPDATE SHADOW_SUFFIX_DOCUMENTS |
The string representing "/shadow/update/document". | |
#define | SHADOW_OP_DELETE_ACCEPTED SHADOW_OP_DELETE SHADOW_SUFFIX_ACCEPTED |
The string representing "/shadow/delete/accepted". | |
#define | SHADOW_OP_DELETE_REJECTED SHADOW_OP_DELETE SHADOW_SUFFIX_REJECTED |
The string representing "/shadow/delete/accepted". | |
#define | SHADOW_OP_GET_ACCEPTED SHADOW_OP_GET SHADOW_SUFFIX_ACCEPTED |
The string representing "/shadow/get/accepted". | |
#define | SHADOW_OP_GET_REJECTED SHADOW_OP_GET SHADOW_SUFFIX_REJECTED |
The string representing "/shadow/get/accepted". | |
#define | SHADOW_OP_UPDATE_ACCEPTED_LENGTH ( SHADOW_OP_UPDATE_LENGTH + SHADOW_SUFFIX_ACCEPTED_LENGTH ) |
The length of "/shadow/update/accepted". | |
#define | SHADOW_OP_UPDATE_REJECTED_LENGTH ( SHADOW_OP_UPDATE_LENGTH + SHADOW_SUFFIX_REJECTED_LENGTH ) |
The length of "/shadow/update/rejected". | |
#define | SHADOW_OP_UPDATE_DOCUMENTS_LENGTH ( SHADOW_OP_UPDATE_LENGTH + SHADOW_SUFFIX_DOCUMENTS_LENGTH ) |
The length of "/shadow/update/document". | |
#define | SHADOW_OP_UPDATE_DELTA_LENGTH ( SHADOW_OP_UPDATE_LENGTH + SHADOW_SUFFIX_DELTA_LENGTH ) |
The length of "/shadow/update/rejected". | |
#define | SHADOW_OP_GET_ACCEPTED_LENGTH ( SHADOW_OP_GET_LENGTH + SHADOW_SUFFIX_ACCEPTED_LENGTH ) |
The length of "/shadow/get/accepted". | |
#define | SHADOW_OP_GET_REJECTED_LENGTH ( SHADOW_OP_GET_LENGTH + SHADOW_SUFFIX_REJECTED_LENGTH ) |
The length of "/shadow/get/rejected". | |
#define | SHADOW_OP_DELETE_ACCEPTED_LENGTH ( SHADOW_OP_DELETE_LENGTH + SHADOW_SUFFIX_ACCEPTED_LENGTH ) |
The length of "/shadow/get/accepted". | |
#define | SHADOW_OP_DELETE_REJECTED_LENGTH ( SHADOW_OP_DELETE_LENGTH + SHADOW_SUFFIX_REJECTED_LENGTH ) |
The length of "/shadow/delete/rejected". | |
Functions | |
static ShadowStatus_t | validateMatchTopicParameters (const char *pTopic, uint16_t topicLength, const ShadowMessageType_t *pMessageType) |
Check if Shadow_MatchTopicString has valid parameters. More... | |
static ShadowStatus_t | validateAssembleTopicParameters (ShadowTopicStringType_t topicType, const char *pThingName, uint8_t thingNameLength, const char *pShadowName, uint8_t shadowNameLength, const char *pTopicBuffer, const uint16_t *pOutLength) |
Check if Shadow_AssembleTopicString has valid parameters. More... | |
static ShadowStatus_t | containsSubString (const char *pString, uint16_t stringLength, const char *pSubString, uint16_t subStringLength) |
Determine if the string contains the substring. More... | |
static ShadowStatus_t | validateName (const char *pString, uint16_t stringLength, uint8_t maxAllowedLength, uint8_t *pNameLength) |
Check if the Thing or Shadow Name is valid. More... | |
static ShadowStatus_t | extractShadowMessageType (const char *pString, uint16_t stringLength, ShadowMessageType_t *pMessageType) |
Extract the Shadow message type from a string. More... | |
static ShadowStatus_t | extractThingName (const char *pTopic, uint16_t topicLength, uint16_t *pConsumedTopicLength, uint8_t *pThingNameLength) |
Extract the Thing name from a topic string. More... | |
static ShadowStatus_t | extractShadowRootAndName (const char *pTopic, uint16_t topicLength, uint16_t *pConsumedTopicLength, uint8_t *pShadowNameLength) |
Extract the classic shadow root OR the named shadow root and shadow name from a topic string. More... | |
static const char * | getShadowOperationString (ShadowTopicStringType_t topicType) |
Get the shadow operation string for a given shadow topic type. More... | |
static uint16_t | getShadowOperationLength (ShadowTopicStringType_t topicType) |
Get the shadow operation string length for a given shadow topic type. More... | |
static void | createShadowTopicString (ShadowTopicStringType_t topicType, const char *pThingName, uint8_t thingNameLength, const char *pShadowName, uint8_t shadowNameLength, char *pTopicBuffer) |
Creates a shadow topic string. More... | |
ShadowStatus_t | Shadow_MatchTopicString (const char *pTopic, uint16_t topicLength, ShadowMessageType_t *pMessageType, const char **pThingName, uint8_t *pThingNameLength, const char **pShadowName, uint8_t *pShadowNameLength) |
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 pointers to the Thing Name and Shadow Name inside of the topic string. See ShadowMessageType_t for the list of message types. Those types correspond to Device Shadow Topics. More... | |
ShadowStatus_t | Shadow_AssembleTopicString (ShadowTopicStringType_t topicType, const char *pThingName, uint8_t thingNameLength, const char *pShadowName, uint8_t shadowNameLength, char *pTopicBuffer, uint16_t bufferSize, uint16_t *pOutLength) |
Assemble shadow topic string when Thing Name or Shadow Name is only known at run time. If both the Thing Name and Shadow Name are known at compile time, use SHADOW_TOPIC_STR_* 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 an unnamed ("Classic") device shadow; if it is, return information about the type of device shadow message, and a pointers 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... | |
Implements the user-facing functions of the Shadow library.
|
static |
Check if Shadow_MatchTopicString has valid parameters.
[in] | pTopic | Pointer to the topic string. |
[in] | topicLength | Length of pTopic. |
[in] | pMessageType | Pointer to caller-supplied memory for returning the type of the shadow message. |
|
static |
Check if Shadow_AssembleTopicString has valid parameters.
[in] | topicType | Shadow topic type. |
[in] | pThingName | Thing Name string. |
[in] | thingNameLength | Length of Thing Name string pointed to by pThingName. |
[in] | pShadowName | Shadow Name string. |
[in] | shadowNameLength | Length of Shadow Name string pointed to by pShadowName. |
[in] | pTopicBuffer | Pointer to the topic buffer. |
[in] | pOutLength | Pointer to the length of the topic created. |
|
static |
Determine if the string contains the substring.
[in] | pString | Pointer to the string. |
[in] | stringLength | Length of pString. |
[in] | pSubString | Pointer to the substring. |
[in] | subStringLength | Length of pSubString. |
|
static |
Check if the Thing or Shadow Name is valid.
[in] | pString | Pointer to the starting of a name. |
[in] | stringLength | Length of pString. |
[in] | maxAllowedLength | Maximum allowed length of the Thing or Shadow name. |
[out] | pNameLength | Pointer to caller-supplied memory for returning the length of the Thing or Shadow Name. |
|
static |
Extract the Shadow message type from a string.
[in] | pString | Pointer to the string. |
[in] | stringLength | Length of pString. |
[out] | pMessageType | Pointer to caller-supplied memory for returning the type of the shadow message. |
|
static |
Extract the Thing name from a topic string.
[in] | pTopic | Pointer to the topic string. |
[in] | topicLength | Length of pTopic. |
[in,out] | pConsumedTopicLength | Pointer to caller-supplied memory for returning the consumed topic length. |
[out] | pThingNameLength | Pointer to caller-supplied memory for returning the Thing name length. |
|
static |
Extract the classic shadow root OR the named shadow root and shadow name from a topic string.
[in] | pTopic | Pointer to the topic string. |
[in] | topicLength | Length of pTopic. |
[in,out] | pConsumedTopicLength | Pointer to caller-supplied memory for returning the consumed topic length. |
[out] | pShadowNameLength | Pointer to caller-supplied memory for returning the shadow name length. |
|
static |
Get the shadow operation string for a given shadow topic type.
[in] | topicType | The given shadow topic type. |
|
static |
Get the shadow operation string length for a given shadow topic type.
[in] | topicType | The given shadow topic type. |
|
static |
Creates a shadow topic string.
[in] | topicType | The type of shadow topic to be constructed. |
[in] | pThingName | Pointer to the Thing name. |
[in] | thingNameLength | The length of the Thing name. |
[in] | pShadowName | Pointer to the Shadow name. |
[in] | shadowNameLength | The length of the Shadow name. |
[out] | pTopicBuffer | Pointer to caller-supplied memory for returning the constructed shadow topic string. |
ShadowStatus_t Shadow_MatchTopicString | ( | const char * | pTopic, |
uint16_t | topicLength, | ||
ShadowMessageType_t * | pMessageType, | ||
const char ** | pThingName, | ||
uint8_t * | pThingNameLength, | ||
const char ** | pShadowName, | ||
uint8_t * | pShadowNameLength | ||
) |
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 pointers to the Thing Name and Shadow Name inside of the topic string. See ShadowMessageType_t for the list of message types. Those types correspond to Device Shadow Topics.
[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. |
[out] | pShadowName | Points to the 1st character of Shadow Name inside of the topic string, and can be null if caller does not need to know the Shadow Name contained in the topic string. Null is returned if the shadow is Classic. |
[out] | pShadowNameLength | Pointer to caller-supplied memory for returning the length of the Shadow Name, and can be null if caller does not need to know the Shadow Name contained in the topic string. A value of 0 is returned if the shadow is Classic. |
Example
ShadowStatus_t Shadow_AssembleTopicString | ( | ShadowTopicStringType_t | topicType, |
const char * | pThingName, | ||
uint8_t | thingNameLength, | ||
const char * | pShadowName, | ||
uint8_t | shadowNameLength, | ||
char * | pTopicBuffer, | ||
uint16_t | bufferSize, | ||
uint16_t * | pOutLength | ||
) |
Assemble shadow topic string when Thing Name or Shadow Name is only known at run time. If both the Thing Name and Shadow Name are known at compile time, use SHADOW_TOPIC_STR_* macros instead.
[in] | topicType | Indicates what topic will be written into the buffer pointed to by pTopicBuffer. can be one of:
|
[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. |
[in] | pShadowName | Shadow Name string. No need to be null terminated. Must not be NULL. Empty string for classic shadow. |
[in] | shadowNameLength | Length of Shadow Name string pointed to by pShadowName. Zero for classic shadow. |
[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. |
Example
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 an unnamed ("Classic") device shadow; if it is, return information about the type of device shadow message, and a pointers 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.
See Shadow_MatchTopicString for documentation of common behavior.