AWS IoT Device Shadow  v1.1.0
AWS IoT Device Shadow client library
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_CLASSIC_ROOT   "/shadow"
 The root of all unnamed "Classic" Shadow MQTT topics from here https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html.
 
#define SHADOW_CLASSIC_ROOT_LENGTH   ( ( uint16_t ) ( sizeof( SHADOW_CLASSIC_ROOT ) - 1U ) )
 The length of SHADOW_CLASSIC_ROOT.
 
#define SHADOW_NAMED_ROOT   "/shadow/name/"
 The common root of all named Shadow MQTT topics from here https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html.
 
#define SHADOW_NAMED_ROOT_LENGTH   ( ( uint16_t ) ( sizeof( SHADOW_NAMED_ROOT ) - 1U ) )
 The length of SHADOW_NAMED_ROOT.
 
#define SHADOW_OP_DELETE   "/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   "/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   "/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_NAME_LENGTH_MAX   ( 64U )
 The maximum length of Shadow Name.
 
#define SHADOW_NAME_CLASSIC   ""
 The name string for the unnamed "Classic" shadow.
 
#define SHADOW_NAME_CLASSIC_LENGTH   ( ( uint16_t ) ( sizeof( SHADOW_NAME_CLASSIC ) - 1U ) )
 The length of SHADOW_NAME_CLASSIC.
 
#define SHADOW_TOPIC_LEN(operationLength, suffixLength, thingNameLength, shadowNameLength)
 Compute shadow topic length. More...
 
#define SHADOW_TOPIC_LEN_UPDATE(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of shadow topic "$aws/things/<thingName>/shadow/update" or "$aws/things/<thingName>/shadow/name/<shadowName>/update". More...
 
#define SHADOW_TOPIC_LEN_UPDATE_ACC(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of shadow topic "$aws/things/<thingName>/shadow/update/accepted" or "$aws/things/<thingName>/shadow/name/<shadowName>/update/accepted". More...
 
#define SHADOW_TOPIC_LEN_UPDATE_REJ(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of shadow topic "$aws/things/<thingName>/shadow/update/rejected" or "$aws/things/<thingName>/shadow/name/<shadowName>/update/rejected". More...
 
#define SHADOW_TOPIC_LEN_UPDATE_DOCS(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DOCUMENTS_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of shadow topic "$aws/things/<thingName>/shadow/update/documents" or "$aws/things/<thingName>/shadow/name/<shadowName>/update/documents". More...
 
#define SHADOW_TOPIC_LEN_UPDATE_DELTA(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DELTA_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of shadow topic "$aws/things/<thingName>/shadow/update/delta" or "$aws/things/<thingName>/shadow/name/<shadowName>/update/delta". More...
 
#define SHADOW_TOPIC_LEN_GET(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of shadow topic "$aws/things/<thingName>/shadow/get" or "$aws/things/<thingName>/shadow/name/<shadowName>/get". More...
 
#define SHADOW_TOPIC_LEN_GET_ACC(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of shadow topic "$aws/things/<thingName>/shadow/get/accepted" or "$aws/things/<thingName>/shadow/name/<shadowName>/get/accepted". More...
 
#define SHADOW_TOPIC_LEN_GET_REJ(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of shadow topic "$aws/things/<thingName>/shadow/get/rejected" or "$aws/things/<thingName>/shadow/name/<shadowName>/get/rejected". More...
 
#define SHADOW_TOPIC_LEN_DELETE(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of shadow topic "$aws/things/<thingName>/shadow/delete" or "$aws/things/<thingName>/shadow/name/<shadowName>/delete". More...
 
#define SHADOW_TOPIC_LEN_DELETE_ACC(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of shadow topic "$aws/things/<thingName>/shadow/delete/accepted" or "$aws/things/<thingName>/shadow/name/<shadowName>/delete/accepted". More...
 
#define SHADOW_TOPIC_LEN_DELETE_REJ(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of shadow topic "$aws/things/<thingName>/shadow/delete/rejected" or "$aws/things/<thingName>/shadow/name/<shadowName>/delete/rejected". More...
 
#define SHADOW_TOPIC_LEN_MAX(thingNameLength, shadowNameLength)    SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DOCUMENTS_LENGTH, thingNameLength, shadowNameLength )
 Compute the length of the longest shadow topic. More...
 
#define SHADOW_TOPIC_STR(thingName, shadowName, operation, suffix)
 Assemble constant shadow topic strings when Thing Name is known at compile time. More...
 
#define SHADOW_TOPIC_STR_UPDATE(thingName, shadowName)    SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_NULL )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/update" or "$aws/things/<thingName>/shadow/name/<shadowName>/update". More...
 
#define SHADOW_TOPIC_STR_UPDATE_ACC(thingName, shadowName)    SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_ACCEPTED )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/update/accepted" or "$aws/things/<thingName>/shadow/name/<shadowName>/update/accepted". More...
 
#define SHADOW_TOPIC_STR_UPDATE_REJ(thingName, shadowName)    SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_REJECTED )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/update/rejected" or "$aws/things/<thingName>/shadow/name/<shadowName>/update/rejected". More...
 
#define SHADOW_TOPIC_STR_UPDATE_DOCS(thingName, shadowName)    SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_DOCUMENTS )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/update/documents" or "$aws/things/<thingName>/shadow/name/<shadowName>/update/documents". More...
 
#define SHADOW_TOPIC_STR_UPDATE_DELTA(thingName, shadowName)    SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_DELTA )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/update/delta" or "$aws/things/<thingName>/shadow/name/<shadowName>/update/delta". More...
 
#define SHADOW_TOPIC_STR_GET(thingName, shadowName)    SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_GET, SHADOW_SUFFIX_NULL )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/get" or "$aws/things/<thingName>/shadow/name/<shadowName>/get". More...
 
#define SHADOW_TOPIC_STR_GET_ACC(thingName, shadowName)    SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_GET, SHADOW_SUFFIX_ACCEPTED )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/get/accepted" or "$aws/things/<thingName>/shadow/name/<shadowName>/get/accepted". More...
 
#define SHADOW_TOPIC_STR_GET_REJ(thingName, shadowName)    SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_GET, SHADOW_SUFFIX_REJECTED )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/get/rejected" or "$aws/things/<thingName>/shadow/name/<shadowName>/get/rejected". More...
 
#define SHADOW_TOPIC_STR_DELETE(thingName, shadowName)    SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_DELETE, SHADOW_SUFFIX_NULL )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/delete" or "$aws/things/<thingName>/shadow/name/<shadowName>/delete". More...
 
#define SHADOW_TOPIC_STR_DELETE_ACC(thingName, shadowName)    SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_DELETE, SHADOW_SUFFIX_ACCEPTED )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/delete/accepted" or "$aws/things/<thingName>/shadow/name/<shadowName>/delete/accepted". More...
 
#define SHADOW_TOPIC_STR_DELETE_REJ(thingName, shadowName)    SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_DELETE, SHADOW_SUFFIX_REJECTED )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/delete/rejected". or "$aws/things/<thingName>/shadow/name/<shadowName>/delete/rejected". More...
 
#define SHADOW_TOPIC_LENGTH(operationLength, suffixLength, thingNameLength)    SHADOW_TOPIC_LEN( operationLength, suffixLength, thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute unnamed "Classic" shadow topic length. More...
 
#define SHADOW_TOPIC_LENGTH_UPDATE(thingNameLength)    SHADOW_TOPIC_LEN_UPDATE( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/update". More...
 
#define SHADOW_TOPIC_LENGTH_UPDATE_ACCEPTED(thingNameLength)    SHADOW_TOPIC_LEN_UPDATE_ACC( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/update/accepted". More...
 
#define SHADOW_TOPIC_LENGTH_UPDATE_REJECTED(thingNameLength)    SHADOW_TOPIC_LEN_UPDATE_REJ( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/update/rejected". More...
 
#define SHADOW_TOPIC_LENGTH_UPDATE_DOCUMENTS(thingNameLength)    SHADOW_TOPIC_LEN_UPDATE_DOCS( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/update/documents". More...
 
#define SHADOW_TOPIC_LENGTH_UPDATE_DELTA(thingNameLength)    SHADOW_TOPIC_LEN_UPDATE_DELTA( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/update/delta". More...
 
#define SHADOW_TOPIC_LENGTH_GET(thingNameLength)    SHADOW_TOPIC_LEN_GET( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/get". More...
 
#define SHADOW_TOPIC_LENGTH_GET_ACCEPTED(thingNameLength)    SHADOW_TOPIC_LEN_GET_ACC( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/get/accepted". More...
 
#define SHADOW_TOPIC_LENGTH_GET_REJECTED(thingNameLength)    SHADOW_TOPIC_LEN_GET_REJ( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/get/rejected". More...
 
#define SHADOW_TOPIC_LENGTH_DELETE(thingNameLength)    SHADOW_TOPIC_LEN_DELETE( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/delete". More...
 
#define SHADOW_TOPIC_LENGTH_DELETE_ACCEPTED(thingNameLength)    SHADOW_TOPIC_LEN_DELETE_ACC( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/delete/accepted". More...
 
#define SHADOW_TOPIC_LENGTH_DELETE_REJECTED(thingNameLength)    SHADOW_TOPIC_LEN_DELETE_REJ( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/delete/rejected". More...
 
#define SHADOW_TOPIC_LENGTH_MAX(thingNameLength)    SHADOW_TOPIC_LEN_MAX( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
 Compute the length of the longest unnamed "Classic" shadow topic. More...
 
#define SHADOW_TOPIC_STRING(thingName, operation, suffix)    SHADOW_TOPIC_STR( thingName, SHADOW_NAME_CLASSIC, operation, suffix )
 Assemble constant unnamed "Classic" shadow topic strings when Thing Name is known at compile time. More...
 
#define SHADOW_TOPIC_STRING_UPDATE(thingName)    SHADOW_TOPIC_STR_UPDATE( thingName, SHADOW_NAME_CLASSIC )
 Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/update". More...
 
#define SHADOW_TOPIC_STRING_UPDATE_ACCEPTED(thingName)    SHADOW_TOPIC_STR_UPDATE_ACC( thingName, SHADOW_NAME_CLASSIC )
 Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/update/accepted". More...
 
#define SHADOW_TOPIC_STRING_UPDATE_REJECTED(thingName)    SHADOW_TOPIC_STR_UPDATE_REJ( thingName, SHADOW_NAME_CLASSIC )
 Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/update/rejected". More...
 
#define SHADOW_TOPIC_STRING_UPDATE_DOCUMENTS(thingName)    SHADOW_TOPIC_STR_UPDATE_DOCS( thingName, SHADOW_NAME_CLASSIC )
 Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/update/documents". More...
 
#define SHADOW_TOPIC_STRING_UPDATE_DELTA(thingName)    SHADOW_TOPIC_STR_UPDATE_DELTA( thingName, SHADOW_NAME_CLASSIC )
 Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/update/delta". More...
 
#define SHADOW_TOPIC_STRING_GET(thingName)    SHADOW_TOPIC_STR_GET( thingName, SHADOW_NAME_CLASSIC )
 Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/get". More...
 
#define SHADOW_TOPIC_STRING_GET_ACCEPTED(thingName)    SHADOW_TOPIC_STR_GET_ACC( thingName, SHADOW_NAME_CLASSIC )
 Assemble shadow topic string "$aws/things/<thingName>/shadow/get/accepted". More...
 
#define SHADOW_TOPIC_STRING_GET_REJECTED(thingName)    SHADOW_TOPIC_STR_GET_REJ( thingName, SHADOW_NAME_CLASSIC )
 Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/get/rejected". More...
 
#define SHADOW_TOPIC_STRING_DELETE(thingName)    SHADOW_TOPIC_STR_DELETE( thingName, SHADOW_NAME_CLASSIC )
 Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/delete". More...
 
#define SHADOW_TOPIC_STRING_DELETE_ACCEPTED(thingName)    SHADOW_TOPIC_STR_DELETE_ACC( thingName, SHADOW_NAME_CLASSIC )
 Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/delete/accepted". More...
 
#define SHADOW_TOPIC_STRING_DELETE_REJECTED(thingName)    SHADOW_TOPIC_STR_DELETE_REJ( thingName, SHADOW_NAME_CLASSIC )
 Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/delete/rejected". More...
 
#define Shadow_GetTopicString(topicType, pThingName, thingNameLength, pTopicBuffer, bufferSize, pOutLength)
 Assemble unnamed ("Classic") 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 macro instead. More...
 

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_MESSAGE_TYPE_PARSE_FAILED, SHADOW_ROOT_PARSE_FAILED, SHADOW_SHADOWNAME_PARSE_FAILED
}
 Return codes from Shadow functions. More...
 

Functions

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_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_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...
 

Detailed Description

User-facing Shadow functions, and parameter structs.

Macro Definition Documentation

◆ SHADOW_TOPIC_LENGTH

#define SHADOW_TOPIC_LENGTH (   operationLength,
  suffixLength,
  thingNameLength 
)     SHADOW_TOPIC_LEN( operationLength, suffixLength, thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute unnamed "Classic" shadow topic length.

Deprecated:
Please use SHADOW_TOPIC_LEN in new designs.

See SHADOW_TOPIC_LEN for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_UPDATE

#define SHADOW_TOPIC_LENGTH_UPDATE (   thingNameLength)     SHADOW_TOPIC_LEN_UPDATE( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/update".

Deprecated:
Please use SHADOW_TOPIC_LEN_UPDATE in new designs.

See SHADOW_TOPIC_LEN_UPDATE for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_UPDATE_ACCEPTED

#define SHADOW_TOPIC_LENGTH_UPDATE_ACCEPTED (   thingNameLength)     SHADOW_TOPIC_LEN_UPDATE_ACC( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/update/accepted".

Deprecated:
Please use SHADOW_TOPIC_LEN_UPDATE_ACC in new designs.

See SHADOW_TOPIC_LEN_UPDATE_ACC for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_UPDATE_REJECTED

#define SHADOW_TOPIC_LENGTH_UPDATE_REJECTED (   thingNameLength)     SHADOW_TOPIC_LEN_UPDATE_REJ( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/update/rejected".

Deprecated:
Please use SHADOW_TOPIC_LEN_UPDATE_REJ in new designs.

See SHADOW_TOPIC_LEN_UPDATE_REJ for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_UPDATE_DOCUMENTS

#define SHADOW_TOPIC_LENGTH_UPDATE_DOCUMENTS (   thingNameLength)     SHADOW_TOPIC_LEN_UPDATE_DOCS( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/update/documents".

Deprecated:
Please use SHADOW_TOPIC_LEN_UPDATE_DOCS in new designs.

See SHADOW_TOPIC_LEN_UPDATE_DOCS for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_UPDATE_DELTA

#define SHADOW_TOPIC_LENGTH_UPDATE_DELTA (   thingNameLength)     SHADOW_TOPIC_LEN_UPDATE_DELTA( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/update/delta".

Deprecated:
Please use SHADOW_TOPIC_LEN_UPDATE_DELTA in new designs.

See SHADOW_TOPIC_LEN_UPDATE_DELTA for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_GET

#define SHADOW_TOPIC_LENGTH_GET (   thingNameLength)     SHADOW_TOPIC_LEN_GET( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/get".

Deprecated:
Please use SHADOW_TOPIC_LEN_GET in new designs.

See SHADOW_TOPIC_LEN_GET for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_GET_ACCEPTED

#define SHADOW_TOPIC_LENGTH_GET_ACCEPTED (   thingNameLength)     SHADOW_TOPIC_LEN_GET_ACC( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/get/accepted".

Deprecated:
Please use SHADOW_TOPIC_LEN_GET_ACC in new designs.

See SHADOW_TOPIC_LEN_GET_ACC for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_GET_REJECTED

#define SHADOW_TOPIC_LENGTH_GET_REJECTED (   thingNameLength)     SHADOW_TOPIC_LEN_GET_REJ( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/get/rejected".

Deprecated:
Please use SHADOW_TOPIC_LEN_GET_REJ in new designs.

See SHADOW_TOPIC_LEN_GET_REJ for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_DELETE

#define SHADOW_TOPIC_LENGTH_DELETE (   thingNameLength)     SHADOW_TOPIC_LEN_DELETE( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/delete".

Deprecated:
Please use SHADOW_TOPIC_LEN_DELETE in new designs.

See SHADOW_TOPIC_LEN_DELETE for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_DELETE_ACCEPTED

#define SHADOW_TOPIC_LENGTH_DELETE_ACCEPTED (   thingNameLength)     SHADOW_TOPIC_LEN_DELETE_ACC( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/delete/accepted".

Deprecated:
Please use SHADOW_TOPIC_LEN_DELETE_ACC in new designs.

See SHADOW_TOPIC_LEN_DELETE_ACC for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_DELETE_REJECTED

#define SHADOW_TOPIC_LENGTH_DELETE_REJECTED (   thingNameLength)     SHADOW_TOPIC_LEN_DELETE_REJ( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of unnamed "Classic" shadow topic "$aws/things/<thingName>/shadow/delete/rejected".

Deprecated:
Please use SHADOW_TOPIC_LEN_DELETE_REJ in new designs.

See SHADOW_TOPIC_LEN_DELETE_REJ for documentation of common behavior.

◆ SHADOW_TOPIC_LENGTH_MAX

#define SHADOW_TOPIC_LENGTH_MAX (   thingNameLength)     SHADOW_TOPIC_LEN_MAX( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )

Compute the length of the longest unnamed "Classic" shadow topic.

Deprecated:
Please use SHADOW_TOPIC_LEN_MAX in new designs.

See SHADOW_TOPIC_LEN for documentation of common behavior.

◆ SHADOW_TOPIC_STRING

#define SHADOW_TOPIC_STRING (   thingName,
  operation,
  suffix 
)     SHADOW_TOPIC_STR( thingName, SHADOW_NAME_CLASSIC, operation, suffix )

Assemble constant unnamed "Classic" shadow topic strings when Thing Name is known at compile time.

Deprecated:
Please use SHADOW_TOPIC_STR in new designs.

See SHADOW_TOPIC_STR for documentation of common behavior.

◆ SHADOW_TOPIC_STRING_UPDATE

#define SHADOW_TOPIC_STRING_UPDATE (   thingName)     SHADOW_TOPIC_STR_UPDATE( thingName, SHADOW_NAME_CLASSIC )

Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/update".

Deprecated:
Please use SHADOW_TOPIC_STR_UPDATE in new designs.

See SHADOW_TOPIC_STR_UPDATE for documentation of common behavior.

◆ SHADOW_TOPIC_STRING_UPDATE_ACCEPTED

#define SHADOW_TOPIC_STRING_UPDATE_ACCEPTED (   thingName)     SHADOW_TOPIC_STR_UPDATE_ACC( thingName, SHADOW_NAME_CLASSIC )

Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/update/accepted".

Deprecated:
Please use SHADOW_TOPIC_STR_UPDATE_ACC in new designs.

See SHADOW_TOPIC_STR_UPDATE_ACC for documentation of common behavior.

◆ SHADOW_TOPIC_STRING_UPDATE_REJECTED

#define SHADOW_TOPIC_STRING_UPDATE_REJECTED (   thingName)     SHADOW_TOPIC_STR_UPDATE_REJ( thingName, SHADOW_NAME_CLASSIC )

Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/update/rejected".

Deprecated:
Please use SHADOW_TOPIC_STR_UPDATE_REJ in new designs.

See SHADOW_TOPIC_STR_UPDATE_REJ for documentation of common behavior.

◆ SHADOW_TOPIC_STRING_UPDATE_DOCUMENTS

#define SHADOW_TOPIC_STRING_UPDATE_DOCUMENTS (   thingName)     SHADOW_TOPIC_STR_UPDATE_DOCS( thingName, SHADOW_NAME_CLASSIC )

Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/update/documents".

Deprecated:
Please use SHADOW_TOPIC_STR_UPDATE_DOCS in new designs.

See SHADOW_TOPIC_STR_UPDATE_DOCS for documentation of common behavior.

◆ SHADOW_TOPIC_STRING_UPDATE_DELTA

#define SHADOW_TOPIC_STRING_UPDATE_DELTA (   thingName)     SHADOW_TOPIC_STR_UPDATE_DELTA( thingName, SHADOW_NAME_CLASSIC )

Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/update/delta".

Deprecated:
Please use SHADOW_TOPIC_STR_UPDATE_DELTA in new designs.

See SHADOW_TOPIC_STR_UPDATE_DELTA for documentation of common behavior.

◆ SHADOW_TOPIC_STRING_GET

#define SHADOW_TOPIC_STRING_GET (   thingName)     SHADOW_TOPIC_STR_GET( thingName, SHADOW_NAME_CLASSIC )

Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/get".

Deprecated:
Please use SHADOW_TOPIC_STR_GET in new designs.

See SHADOW_TOPIC_STR_GET for documentation of common behavior.

◆ SHADOW_TOPIC_STRING_GET_ACCEPTED

#define SHADOW_TOPIC_STRING_GET_ACCEPTED (   thingName)     SHADOW_TOPIC_STR_GET_ACC( thingName, SHADOW_NAME_CLASSIC )

Assemble shadow topic string "$aws/things/<thingName>/shadow/get/accepted".

Deprecated:
Please use SHADOW_TOPIC_STR_GET_ACC in new designs.

See SHADOW_TOPIC_STR_GET_ACC for documentation of common behavior.

◆ SHADOW_TOPIC_STRING_GET_REJECTED

#define SHADOW_TOPIC_STRING_GET_REJECTED (   thingName)     SHADOW_TOPIC_STR_GET_REJ( thingName, SHADOW_NAME_CLASSIC )

Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/get/rejected".

Deprecated:
Please use SHADOW_TOPIC_STR_GET_REJ in new designs.

See SHADOW_TOPIC_STR_GET_REJ for documentation of common behavior.

◆ SHADOW_TOPIC_STRING_DELETE

#define SHADOW_TOPIC_STRING_DELETE (   thingName)     SHADOW_TOPIC_STR_DELETE( thingName, SHADOW_NAME_CLASSIC )

Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/delete".

Deprecated:
Please use SHADOW_TOPIC_STR_DELETE in new designs.

See SHADOW_TOPIC_STR_DELETE for documentation of common behavior.

◆ SHADOW_TOPIC_STRING_DELETE_ACCEPTED

#define SHADOW_TOPIC_STRING_DELETE_ACCEPTED (   thingName)     SHADOW_TOPIC_STR_DELETE_ACC( thingName, SHADOW_NAME_CLASSIC )

Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/delete/accepted".

Deprecated:
Please use SHADOW_TOPIC_STR_DELETE_ACC in new designs.

See SHADOW_TOPIC_STR_DELETE_ACC for documentation of common behavior.

◆ SHADOW_TOPIC_STRING_DELETE_REJECTED

#define SHADOW_TOPIC_STRING_DELETE_REJECTED (   thingName)     SHADOW_TOPIC_STR_DELETE_REJ( thingName, SHADOW_NAME_CLASSIC )

Assemble unnamed "Classic" shadow topic string "$aws/things/<thingName>/shadow/delete/rejected".

Deprecated:
Please use SHADOW_TOPIC_STR_DELETE_REJ in new designs.

See SHADOW_TOPIC_STR_DELETE_REJ for documentation of common behavior.

◆ Shadow_GetTopicString

#define Shadow_GetTopicString (   topicType,
  pThingName,
  thingNameLength,
  pTopicBuffer,
  bufferSize,
  pOutLength 
)
Value:
Shadow_AssembleTopicString( topicType, pThingName, thingNameLength, SHADOW_NAME_CLASSIC, 0, \
pTopicBuffer, bufferSize, pOutLength )

Assemble unnamed ("Classic") 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 macro instead.

Deprecated:
Please use Shadow_AssembleTopicString in new designs.

See Shadow_AssembleTopicString for documentation of common behavior.

Function Documentation

◆ Shadow_AssembleTopicString()

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.

Parameters
[in]topicTypeIndicates 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]pThingNameThing Name string. No need to be null terminated. Must not be NULL.
[in]thingNameLengthLength of Thing Name string pointed to by pThingName. Must not be zero.
[in]pShadowNameShadow Name string. No need to be null terminated. Must not be NULL. Empty string for classic shadow.
[in]shadowNameLengthLength of Shadow Name string pointed to by pShadowName. Zero for classic shadow.
[out]pTopicBufferPointer 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]bufferSizeLength of pTopicBuffer. This function will return error if bufferSize is less than the length of the assembled topic string.
[out]pOutLengthPointer 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 )
char topicBuffer[ SHADOW_TOPIC_MAX_LENGTH ] = { 0 };
uint16_t bufferSize = SHADOW_TOPIC_MAX_LENGTH;
uint16_t outLength = 0;
const char thingName[] = "TestThingName";
uint16_t thingNameLength = ( sizeof( thingName ) - 1U );
const char shadowName[] = "TestShadowName";
uint16_t shadowNameLength = ( sizeof( shadowName ) - 1U );
shadowStatus = Shadow_AssembleTopicString( ShadowTopicStringTypeUpdateDelta,
thingName,
thingNameLength,
shadowName,
shadowNameLength,
& ( topicBuffer[ 0 ] ),
bufferSize,
& outLength );
if( shadowStatus == SHADOW_SUCCESS )
{
// The assembled topic string is put in pTopicBuffer with the length outLength.
}

◆ Shadow_MatchTopicString()

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.

Note
When this function returns, the pointer pThingName points at the first character of the <thingName> segment inside of the topic string. Likewise, the pointer pShadowName points at the first character of the <shadowName> segment inside of the topic string (if the topic is for a named shadow, not the "Classic" shadow.) Caller is responsible for keeping the memory holding the topic string around while accessing the Thing Name through pThingName and the Shadow Name through pShadowName.
Parameters
[in]pTopicPointer to the MQTT topic string. Does not have to be null-terminated.
[in]topicLengthLength of the MQTT topic string.
[out]pMessageTypePointer to caller-supplied memory for returning the type of the shadow message.
[out]pThingNamePoints 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]pThingNameLengthPointer 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]pShadowNamePoints 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]pShadowNameLengthPointer 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.
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_SUCCESS;
char * pTopicName; //usually supplied by MQTT stack
uint16_t topicNameLength; //usually supplied by MQTT stack
ShadowMessageType_t messageType;
shadowStatus = Shadow_MatchTopicString( pTopicName,
topicNameLength,
&messageType,
NULL,
NULL,
NULL,
NULL );
if( shadowStatus == SHADOW_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.
}

◆ 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 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.

Deprecated:
Please use Shadow_MatchTopicString in new designs.

See Shadow_MatchTopicString for documentation of common behavior.

Shadow_AssembleTopicString
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....
Definition: shadow.c:873
ShadowMessageType_t
ShadowMessageType_t
Each of these values describes the type of a shadow message. https://docs.aws.amazon....
Definition: shadow.h:54
ShadowStatus_t
ShadowStatus_t
Return codes from Shadow functions.
Definition: shadow.h:94
Shadow_MatchTopicString
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...
Definition: shadow.c:764
SHADOW_NAME_CLASSIC
#define SHADOW_NAME_CLASSIC
The name string for the unnamed "Classic" shadow.
Definition: shadow.h:258
SHADOW_SUCCESS
@ SHADOW_SUCCESS
Shadow function success.
Definition: shadow.h:95