AWS IoT Device Shadow v1.3.0
AWS IoT Device Shadow client library
shadow.h
Go to the documentation of this file.
1/*
2 * AWS IoT Device Shadow v1.3.0
3 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * SPDX-License-Identifier: MIT
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy of
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
10 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
21 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 */
24
30#ifndef SHADOW_H_
31#define SHADOW_H_
32
33/* Standard includes. */
34#include <stdint.h>
35
36/* *INDENT-OFF* */
37#ifdef __cplusplus
38 extern "C" {
39#endif
40/* *INDENT-ON* */
41
42/* SHADOW_DO_NOT_USE_CUSTOM_CONFIG allows building the Shadow library
43 * without a custom config. If a custom config is provided, the
44 * SHADOW_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */
45#ifndef SHADOW_DO_NOT_USE_CUSTOM_CONFIG
46 /* Include custom config file before other headers. */
47 #include "shadow_config.h"
48#endif
49
50/* Include config defaults header to get default values of configs not
51 * defined in shadow_config_defaults.h file. */
53
54/*--------------------------- Shadow types ---------------------------*/
55
61typedef enum ShadowMessageType
62{
63 ShadowMessageTypeGetAccepted = 0,
64 ShadowMessageTypeGetRejected,
65 ShadowMessageTypeDeleteAccepted,
66 ShadowMessageTypeDeleteRejected,
67 ShadowMessageTypeUpdateAccepted,
68 ShadowMessageTypeUpdateRejected,
69 ShadowMessageTypeUpdateDocuments,
70 ShadowMessageTypeUpdateDelta,
71 ShadowMessageTypeMaxNum
73
81typedef enum ShadowTopicStringType
82{
83 ShadowTopicStringTypeGet = 0,
84 ShadowTopicStringTypeGetAccepted,
85 ShadowTopicStringTypeGetRejected,
86 ShadowTopicStringTypeDelete,
87 ShadowTopicStringTypeDeleteAccepted,
88 ShadowTopicStringTypeDeleteRejected,
89 ShadowTopicStringTypeUpdate,
90 ShadowTopicStringTypeUpdateAccepted,
91 ShadowTopicStringTypeUpdateRejected,
92 ShadowTopicStringTypeUpdateDocuments,
93 ShadowTopicStringTypeUpdateDelta,
94 ShadowTopicStringTypeMaxNum
96
101typedef enum ShadowStatus
102{
112
113/*------------------------ Shadow library constants -------------------------*/
114
120#define SHADOW_PREFIX "$aws/things/"
121
126#define SHADOW_PREFIX_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_PREFIX ) - 1U ) )
127
133#define SHADOW_CLASSIC_ROOT "/shadow"
134
139#define SHADOW_CLASSIC_ROOT_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_CLASSIC_ROOT ) - 1U ) )
140
146#define SHADOW_NAMED_ROOT "/shadow/name/"
147
152#define SHADOW_NAMED_ROOT_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_NAMED_ROOT ) - 1U ) )
153
158#define SHADOW_OP_DELETE "/delete"
159
164#define SHADOW_OP_DELETE_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_OP_DELETE ) - 1U ) )
165
170#define SHADOW_OP_GET "/get"
171
176#define SHADOW_OP_GET_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_OP_GET ) - 1U ) )
177
182#define SHADOW_OP_UPDATE "/update"
183
188#define SHADOW_OP_UPDATE_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_OP_UPDATE ) - 1U ) )
189
194#define SHADOW_SUFFIX_ACCEPTED "/accepted"
195
200#define SHADOW_SUFFIX_ACCEPTED_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_ACCEPTED ) - 1U ) )
201
206#define SHADOW_SUFFIX_REJECTED "/rejected"
207
212#define SHADOW_SUFFIX_REJECTED_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_REJECTED ) - 1U ) )
213
218#define SHADOW_SUFFIX_DELTA "/delta"
219
224#define SHADOW_SUFFIX_DELTA_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_DELTA ) - 1U ) )
225
230#define SHADOW_SUFFIX_DOCUMENTS "/documents"
231
236#define SHADOW_SUFFIX_DOCUMENTS_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_DOCUMENTS ) - 1U ) )
237
242#define SHADOW_SUFFIX_NULL
243
248#define SHADOW_SUFFIX_NULL_LENGTH ( 0U )
249
254#define SHADOW_THINGNAME_LENGTH_MAX ( 128U )
255
260#define SHADOW_NAME_LENGTH_MAX ( 64U )
261
266#define SHADOW_NAME_CLASSIC ""
267
272#define SHADOW_NAME_CLASSIC_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_NAME_CLASSIC ) - 1U ) )
273
321#define SHADOW_TOPIC_LEN( operationLength, suffixLength, thingNameLength, shadowNameLength ) \
322 ( operationLength + suffixLength + thingNameLength + shadowNameLength + \
323 SHADOW_PREFIX_LENGTH + \
324 ( ( shadowNameLength > 0 ) ? SHADOW_NAMED_ROOT_LENGTH : SHADOW_CLASSIC_ROOT_LENGTH ) )
325
336#define SHADOW_TOPIC_LEN_UPDATE( thingNameLength, shadowNameLength ) \
337 SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength, shadowNameLength )
338
349#define SHADOW_TOPIC_LEN_UPDATE_ACC( thingNameLength, shadowNameLength ) \
350 SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength, shadowNameLength )
351
362#define SHADOW_TOPIC_LEN_UPDATE_REJ( thingNameLength, shadowNameLength ) \
363 SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength, shadowNameLength )
364
375#define SHADOW_TOPIC_LEN_UPDATE_DOCS( thingNameLength, shadowNameLength ) \
376 SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DOCUMENTS_LENGTH, thingNameLength, shadowNameLength )
377
388#define SHADOW_TOPIC_LEN_UPDATE_DELTA( thingNameLength, shadowNameLength ) \
389 SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DELTA_LENGTH, thingNameLength, shadowNameLength )
390
401#define SHADOW_TOPIC_LEN_GET( thingNameLength, shadowNameLength ) \
402 SHADOW_TOPIC_LEN( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength, shadowNameLength )
403
414#define SHADOW_TOPIC_LEN_GET_ACC( thingNameLength, shadowNameLength ) \
415 SHADOW_TOPIC_LEN( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength, shadowNameLength )
416
427#define SHADOW_TOPIC_LEN_GET_REJ( thingNameLength, shadowNameLength ) \
428 SHADOW_TOPIC_LEN( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength, shadowNameLength )
429
440#define SHADOW_TOPIC_LEN_DELETE( thingNameLength, shadowNameLength ) \
441 SHADOW_TOPIC_LEN( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength, shadowNameLength )
442
453#define SHADOW_TOPIC_LEN_DELETE_ACC( thingNameLength, shadowNameLength ) \
454 SHADOW_TOPIC_LEN( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength, shadowNameLength )
455
466#define SHADOW_TOPIC_LEN_DELETE_REJ( thingNameLength, shadowNameLength ) \
467 SHADOW_TOPIC_LEN( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength, shadowNameLength )
468
478#define SHADOW_TOPIC_LEN_MAX( thingNameLength, shadowNameLength ) \
479 SHADOW_TOPIC_LEN( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DOCUMENTS_LENGTH, thingNameLength, shadowNameLength )
480
508#define SHADOW_TOPIC_STR( thingName, shadowName, operation, suffix ) \
509 ( ( sizeof( shadowName ) > 1 ) ? \
510 ( SHADOW_PREFIX thingName SHADOW_NAMED_ROOT shadowName operation suffix ) : \
511 ( SHADOW_PREFIX thingName SHADOW_CLASSIC_ROOT operation suffix ) )
512
523#define SHADOW_TOPIC_STR_UPDATE( thingName, shadowName ) \
524 SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_NULL )
525
536#define SHADOW_TOPIC_STR_UPDATE_ACC( thingName, shadowName ) \
537 SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_ACCEPTED )
538
549#define SHADOW_TOPIC_STR_UPDATE_REJ( thingName, shadowName ) \
550 SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_REJECTED )
551
562#define SHADOW_TOPIC_STR_UPDATE_DOCS( thingName, shadowName ) \
563 SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_DOCUMENTS )
564
575#define SHADOW_TOPIC_STR_UPDATE_DELTA( thingName, shadowName ) \
576 SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_DELTA )
577
588#define SHADOW_TOPIC_STR_GET( thingName, shadowName ) \
589 SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_GET, SHADOW_SUFFIX_NULL )
590
601#define SHADOW_TOPIC_STR_GET_ACC( thingName, shadowName ) \
602 SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_GET, SHADOW_SUFFIX_ACCEPTED )
603
614#define SHADOW_TOPIC_STR_GET_REJ( thingName, shadowName ) \
615 SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_GET, SHADOW_SUFFIX_REJECTED )
616
627#define SHADOW_TOPIC_STR_DELETE( thingName, shadowName ) \
628 SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_DELETE, SHADOW_SUFFIX_NULL )
629
640#define SHADOW_TOPIC_STR_DELETE_ACC( thingName, shadowName ) \
641 SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_DELETE, SHADOW_SUFFIX_ACCEPTED )
642
653#define SHADOW_TOPIC_STR_DELETE_REJ( thingName, shadowName ) \
654 SHADOW_TOPIC_STR( thingName, shadowName, SHADOW_OP_DELETE, SHADOW_SUFFIX_REJECTED )
655
656/*------------------------ Shadow library functions -------------------------*/
657
723/* @[declare_shadow_assembletopicstring] */
725 const char * pThingName,
726 uint8_t thingNameLength,
727 const char * pShadowName,
728 uint8_t shadowNameLength,
729 char * pTopicBuffer,
730 uint16_t bufferSize,
731 uint16_t * pOutLength );
732/* @[declare_shadow_assembletopicstring] */
733
795/* @[declare_shadow_matchtopicstring] */
796ShadowStatus_t Shadow_MatchTopicString( const char * pTopic,
797 uint16_t topicLength,
798 ShadowMessageType_t * pMessageType,
799 const char ** pThingName,
800 uint8_t * pThingNameLength,
801 const char ** pShadowName,
802 uint8_t * pShadowNameLength );
803/* @[declare_shadow_matchtopicstring] */
804
805/*------------- Shadow library backwardly-compatible constants -------------*/
806
813#define SHADOW_TOPIC_LENGTH( operationLength, suffixLength, thingNameLength ) \
814 SHADOW_TOPIC_LEN( operationLength, suffixLength, thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
815
822#define SHADOW_TOPIC_LENGTH_UPDATE( thingNameLength ) \
823 SHADOW_TOPIC_LEN_UPDATE( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
824
831#define SHADOW_TOPIC_LENGTH_UPDATE_ACCEPTED( thingNameLength ) \
832 SHADOW_TOPIC_LEN_UPDATE_ACC( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
833
840#define SHADOW_TOPIC_LENGTH_UPDATE_REJECTED( thingNameLength ) \
841 SHADOW_TOPIC_LEN_UPDATE_REJ( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
842
849#define SHADOW_TOPIC_LENGTH_UPDATE_DOCUMENTS( thingNameLength ) \
850 SHADOW_TOPIC_LEN_UPDATE_DOCS( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
851
858#define SHADOW_TOPIC_LENGTH_UPDATE_DELTA( thingNameLength ) \
859 SHADOW_TOPIC_LEN_UPDATE_DELTA( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
860
867#define SHADOW_TOPIC_LENGTH_GET( thingNameLength ) \
868 SHADOW_TOPIC_LEN_GET( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
869
876#define SHADOW_TOPIC_LENGTH_GET_ACCEPTED( thingNameLength ) \
877 SHADOW_TOPIC_LEN_GET_ACC( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
878
885#define SHADOW_TOPIC_LENGTH_GET_REJECTED( thingNameLength ) \
886 SHADOW_TOPIC_LEN_GET_REJ( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
887
894#define SHADOW_TOPIC_LENGTH_DELETE( thingNameLength ) \
895 SHADOW_TOPIC_LEN_DELETE( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
896
903#define SHADOW_TOPIC_LENGTH_DELETE_ACCEPTED( thingNameLength ) \
904 SHADOW_TOPIC_LEN_DELETE_ACC( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
905
912#define SHADOW_TOPIC_LENGTH_DELETE_REJECTED( thingNameLength ) \
913 SHADOW_TOPIC_LEN_DELETE_REJ( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
914
921#define SHADOW_TOPIC_LENGTH_MAX( thingNameLength ) \
922 SHADOW_TOPIC_LEN_MAX( thingNameLength, SHADOW_NAME_CLASSIC_LENGTH )
923
930#define SHADOW_TOPIC_STRING( thingName, operation, suffix ) \
931 SHADOW_TOPIC_STR( thingName, SHADOW_NAME_CLASSIC, operation, suffix )
932
939#define SHADOW_TOPIC_STRING_UPDATE( thingName ) \
940 SHADOW_TOPIC_STR_UPDATE( thingName, SHADOW_NAME_CLASSIC )
941
948#define SHADOW_TOPIC_STRING_UPDATE_ACCEPTED( thingName ) \
949 SHADOW_TOPIC_STR_UPDATE_ACC( thingName, SHADOW_NAME_CLASSIC )
950
957#define SHADOW_TOPIC_STRING_UPDATE_REJECTED( thingName ) \
958 SHADOW_TOPIC_STR_UPDATE_REJ( thingName, SHADOW_NAME_CLASSIC )
959
966#define SHADOW_TOPIC_STRING_UPDATE_DOCUMENTS( thingName ) \
967 SHADOW_TOPIC_STR_UPDATE_DOCS( thingName, SHADOW_NAME_CLASSIC )
968
975#define SHADOW_TOPIC_STRING_UPDATE_DELTA( thingName ) \
976 SHADOW_TOPIC_STR_UPDATE_DELTA( thingName, SHADOW_NAME_CLASSIC )
977
984#define SHADOW_TOPIC_STRING_GET( thingName ) \
985 SHADOW_TOPIC_STR_GET( thingName, SHADOW_NAME_CLASSIC )
986
993#define SHADOW_TOPIC_STRING_GET_ACCEPTED( thingName ) \
994 SHADOW_TOPIC_STR_GET_ACC( thingName, SHADOW_NAME_CLASSIC )
995
1002#define SHADOW_TOPIC_STRING_GET_REJECTED( thingName ) \
1003 SHADOW_TOPIC_STR_GET_REJ( thingName, SHADOW_NAME_CLASSIC )
1004
1011#define SHADOW_TOPIC_STRING_DELETE( thingName ) \
1012 SHADOW_TOPIC_STR_DELETE( thingName, SHADOW_NAME_CLASSIC )
1013
1020#define SHADOW_TOPIC_STRING_DELETE_ACCEPTED( thingName ) \
1021 SHADOW_TOPIC_STR_DELETE_ACC( thingName, SHADOW_NAME_CLASSIC )
1022
1029#define SHADOW_TOPIC_STRING_DELETE_REJECTED( thingName ) \
1030 SHADOW_TOPIC_STR_DELETE_REJ( thingName, SHADOW_NAME_CLASSIC )
1031
1041/* @[declare_shadow_gettopicstring] */
1042#define Shadow_GetTopicString( topicType, pThingName, thingNameLength, pTopicBuffer, bufferSize, pOutLength ) \
1043 Shadow_AssembleTopicString( topicType, pThingName, thingNameLength, SHADOW_NAME_CLASSIC, 0, \
1044 pTopicBuffer, bufferSize, pOutLength )
1045/* @[declare_shadow_gettopicstring] */
1046
1058/* @[declare_shadow_matchtopic] */
1059ShadowStatus_t Shadow_MatchTopic( const char * pTopic,
1060 uint16_t topicLength,
1061 ShadowMessageType_t * pMessageType,
1062 const char ** pThingName,
1063 uint16_t * pThingNameLength );
1064/* @[declare_shadow_matchtopic] */
1065
1066/* *INDENT-OFF* */
1067#ifdef __cplusplus
1068 }
1069#endif
1070/* *INDENT-ON* */
1071
1072#endif /* ifndef SHADOW_H_ */
ShadowTopicStringType_t
Each of these values describes the type of a shadow topic string.
Definition: shadow.h:82
ShadowStatus_t
Return codes from Shadow functions.
Definition: shadow.h:102
ShadowMessageType_t
Each of these values describes the type of a shadow message. https://docs.aws.amazon....
Definition: shadow.h:62
@ SHADOW_BAD_PARAMETER
Input parameter is invalid.
Definition: shadow.h:105
@ SHADOW_ROOT_PARSE_FAILED
Could not parse the classic or named shadow root.
Definition: shadow.h:109
@ SHADOW_SUCCESS
Shadow function success.
Definition: shadow.h:103
@ SHADOW_MESSAGE_TYPE_PARSE_FAILED
Could not parse the shadow type.
Definition: shadow.h:108
@ SHADOW_SHADOWNAME_PARSE_FAILED
Could not parse the shadow name (in the case of a named shadow topic).
Definition: shadow.h:110
@ SHADOW_BUFFER_TOO_SMALL
The provided buffer is too small.
Definition: shadow.h:106
@ SHADOW_FAIL
Shadow function encountered error.
Definition: shadow.h:104
@ SHADOW_THINGNAME_PARSE_FAILED
Could not parse the thing name.
Definition: shadow.h:107
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:766
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 ("Classi...
Definition: shadow.c:930
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:875
This represents the default values for the configuration macros for the Shadow library.