AWS IoT Device Shadow  v1.0.1
AWS IoT Device Shadow client library
shadow.h
Go to the documentation of this file.
1 /*
2  * AWS IoT Device Shadow v1.0.1
3  * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a copy of
6  * this software and associated documentation files (the "Software"), to deal in
7  * the Software without restriction, including without limitation the rights to
8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9  * the Software, and to permit persons to whom the Software is furnished to do so,
10  * subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in all
13  * copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21  */
22 
28 #ifndef SHADOW_H_
29 #define SHADOW_H_
30 
31 /* Standard includes. */
32 #include <stdint.h>
33 
34 /* SHADOW_DO_NOT_USE_CUSTOM_CONFIG allows building the Shadow library
35  * without a custom config. If a custom config is provided, the
36  * SHADOW_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */
37 #ifndef SHADOW_DO_NOT_USE_CUSTOM_CONFIG
38  /* Include custom config file before other headers. */
39  #include "shadow_config.h"
40 #endif
41 
42 /* Include config defaults header to get default values of configs not
43  * defined in shadow_config_defaults.h file. */
44 #include "shadow_config_defaults.h"
45 
46 /*--------------------------- Shadow types ---------------------------*/
47 
53 typedef enum ShadowMessageType
54 {
55  ShadowMessageTypeGetAccepted = 0,
56  ShadowMessageTypeGetRejected,
57  ShadowMessageTypeDeleteAccepted,
58  ShadowMessageTypeDeleteRejected,
59  ShadowMessageTypeUpdateAccepted,
60  ShadowMessageTypeUpdateRejected,
61  ShadowMessageTypeUpdateDocuments,
62  ShadowMessageTypeUpdateDelta,
63  ShadowMessageTypeMaxNum
64 } ShadowMessageType_t;
65 
73 typedef enum ShadowTopicStringType
74 {
75  ShadowTopicStringTypeGet = 0,
76  ShadowTopicStringTypeGetAccepted,
77  ShadowTopicStringTypeGetRejected,
78  ShadowTopicStringTypeDelete,
79  ShadowTopicStringTypeDeleteAccepted,
80  ShadowTopicStringTypeDeleteRejected,
81  ShadowTopicStringTypeUpdate,
82  ShadowTopicStringTypeUpdateAccepted,
83  ShadowTopicStringTypeUpdateRejected,
84  ShadowTopicStringTypeUpdateDocuments,
85  ShadowTopicStringTypeUpdateDelta,
86  ShadowTopicStringTypeMaxNum
87 } ShadowTopicStringType_t;
88 
93 typedef enum ShadowStatus
94 {
95  SHADOW_SUCCESS = 0,
96  SHADOW_FAIL,
97  SHADOW_BAD_PARAMETER,
98  SHADOW_BUFFER_TOO_SMALL,
99  SHADOW_THINGNAME_PARSE_FAILED,
100  SHADOW_SHADOW_MESSAGE_TYPE_PARSE_FAILED
101 } ShadowStatus_t;
102 
103 /*------------------------ Shadow library functions -------------------------*/
104 
110 #define SHADOW_PREFIX "$aws/things/"
111 
116 #define SHADOW_PREFIX_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_PREFIX ) - 1U ) )
117 
122 #define SHADOW_OP_DELETE "/shadow/delete"
123 
128 #define SHADOW_OP_DELETE_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_OP_DELETE ) - 1U ) )
129 
134 #define SHADOW_OP_GET "/shadow/get"
135 
140 #define SHADOW_OP_GET_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_OP_GET ) - 1U ) )
141 
146 #define SHADOW_OP_UPDATE "/shadow/update"
147 
152 #define SHADOW_OP_UPDATE_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_OP_UPDATE ) - 1U ) )
153 
158 #define SHADOW_SUFFIX_ACCEPTED "/accepted"
159 
164 #define SHADOW_SUFFIX_ACCEPTED_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_ACCEPTED ) - 1U ) )
165 
170 #define SHADOW_SUFFIX_REJECTED "/rejected"
171 
176 #define SHADOW_SUFFIX_REJECTED_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_REJECTED ) - 1U ) )
177 
182 #define SHADOW_SUFFIX_DELTA "/delta"
183 
188 #define SHADOW_SUFFIX_DELTA_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_DELTA ) - 1U ) )
189 
194 #define SHADOW_SUFFIX_DOCUMENTS "/documents"
195 
200 #define SHADOW_SUFFIX_DOCUMENTS_LENGTH ( ( uint16_t ) ( sizeof( SHADOW_SUFFIX_DOCUMENTS ) - 1U ) )
201 
206 #define SHADOW_SUFFIX_NULL
207 
212 #define SHADOW_SUFFIX_NULL_LENGTH ( 0U )
213 
218 #define SHADOW_THINGNAME_LENGTH_MAX ( 128U )
219 
258 #define SHADOW_TOPIC_LENGTH( operationLength, suffixLength, thingNameLength ) \
259  ( operationLength + suffixLength + thingNameLength + SHADOW_PREFIX_LENGTH )
260 
264 #define SHADOW_TOPIC_LENGTH_UPDATE( thingNameLength ) \
265  SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength )
266 
270 #define SHADOW_TOPIC_LENGTH_UPDATE_ACCEPTED( thingNameLength ) \
271  SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength )
272 
276 #define SHADOW_TOPIC_LENGTH_UPDATE_REJECTED( thingNameLength ) \
277  SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength )
278 
282 #define SHADOW_TOPIC_LENGTH_UPDATE_DOCUMENTS( thingNameLength ) \
283  SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DOCUMENTS_LENGTH, thingNameLength )
284 
288 #define SHADOW_TOPIC_LENGTH_UPDATE_DELTA( thingNameLength ) \
289  SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DELTA_LENGTH, thingNameLength )
290 
294 #define SHADOW_TOPIC_LENGTH_GET( thingNameLength ) \
295  SHADOW_TOPIC_LENGTH( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength )
296 
300 #define SHADOW_TOPIC_LENGTH_GET_ACCEPTED( thingNameLength ) \
301  SHADOW_TOPIC_LENGTH( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength )
302 
306 #define SHADOW_TOPIC_LENGTH_GET_REJECTED( thingNameLength ) \
307  SHADOW_TOPIC_LENGTH( SHADOW_OP_GET_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength )
308 
312 #define SHADOW_TOPIC_LENGTH_DELETE( thingNameLength ) \
313  SHADOW_TOPIC_LENGTH( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_NULL_LENGTH, thingNameLength )
314 
318 #define SHADOW_TOPIC_LENGTH_DELETE_ACCEPTED( thingNameLength ) \
319  SHADOW_TOPIC_LENGTH( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_ACCEPTED_LENGTH, thingNameLength )
320 
324 #define SHADOW_TOPIC_LENGTH_DELETE_REJECTED( thingNameLength ) \
325  SHADOW_TOPIC_LENGTH( SHADOW_OP_DELETE_LENGTH, SHADOW_SUFFIX_REJECTED_LENGTH, thingNameLength )
326 
331 #define SHADOW_TOPIC_LENGTH_MAX( thingNameLength ) \
332  SHADOW_TOPIC_LENGTH( SHADOW_OP_UPDATE_LENGTH, SHADOW_SUFFIX_DOCUMENTS_LENGTH, thingNameLength )
333 
360 #define SHADOW_TOPIC_STRING( thingName, operation, suffix ) \
361  ( SHADOW_PREFIX thingName operation suffix )
362 
366 #define SHADOW_TOPIC_STRING_UPDATE( thingName ) \
367  SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_NULL )
368 
372 #define SHADOW_TOPIC_STRING_UPDATE_ACCEPTED( thingName ) \
373  SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_ACCEPTED )
374 
378 #define SHADOW_TOPIC_STRING_UPDATE_REJECTED( thingName ) \
379  SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_REJECTED )
380 
384 #define SHADOW_TOPIC_STRING_UPDATE_DOCUMENTS( thingName ) \
385  SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_DOCUMENTS )
386 
390 #define SHADOW_TOPIC_STRING_UPDATE_DELTA( thingName ) \
391  SHADOW_TOPIC_STRING( thingName, SHADOW_OP_UPDATE, SHADOW_SUFFIX_DELTA )
392 
396 #define SHADOW_TOPIC_STRING_GET( thingName ) \
397  SHADOW_TOPIC_STRING( thingName, SHADOW_OP_GET, SHADOW_SUFFIX_NULL )
398 
402 #define SHADOW_TOPIC_STRING_GET_ACCEPTED( thingName ) \
403  SHADOW_TOPIC_STRING( thingName, SHADOW_OP_GET, SHADOW_SUFFIX_ACCEPTED )
404 
408 #define SHADOW_TOPIC_STRING_GET_REJECTED( thingName ) \
409  SHADOW_TOPIC_STRING( thingName, SHADOW_OP_GET, SHADOW_SUFFIX_REJECTED )
410 
414 #define SHADOW_TOPIC_STRING_DELETE( thingName ) \
415  SHADOW_TOPIC_STRING( thingName, SHADOW_OP_DELETE, SHADOW_SUFFIX_NULL )
416 
420 #define SHADOW_TOPIC_STRING_DELETE_ACCEPTED( thingName ) \
421  SHADOW_TOPIC_STRING( thingName, SHADOW_OP_DELETE, SHADOW_SUFFIX_ACCEPTED )
422 
426 #define SHADOW_TOPIC_STRING_DELETE_REJECTED( thingName ) \
427  SHADOW_TOPIC_STRING( thingName, SHADOW_OP_DELETE, SHADOW_SUFFIX_REJECTED )
428 
488 /* @[declare_shadow_gettopicstring] */
489 ShadowStatus_t Shadow_GetTopicString( ShadowTopicStringType_t topicType,
490  const char * pThingName,
491  uint8_t thingNameLength,
492  char * pTopicBuffer,
493  uint16_t bufferSize,
494  uint16_t * pOutLength );
495 /* @[declare_shadow_gettopicstring] */
496 
548 /* @[declare_shadow_matchtopic] */
549 ShadowStatus_t Shadow_MatchTopic( const char * pTopic,
550  uint16_t topicLength,
551  ShadowMessageType_t * pMessageType,
552  const char ** pThingName,
553  uint16_t * pThingNameLength );
554 /* @[declare_shadow_matchtopic] */
555 
556 #endif /* ifndef SHADOW_H_ */
SHADOW_SHADOW_MESSAGE_TYPE_PARSE_FAILED
@ SHADOW_SHADOW_MESSAGE_TYPE_PARSE_FAILED
Could not parse the shadow type.
Definition: shadow.h:100
shadow_config_defaults.h
This represents the default values for the configuration macros for the Shadow library.
SHADOW_THINGNAME_PARSE_FAILED
@ SHADOW_THINGNAME_PARSE_FAILED
Could not parse the thing name.
Definition: shadow.h:99
ShadowMessageType_t
ShadowMessageType_t
Each of these values describes the type of a shadow message. https://docs.aws.amazon....
Definition: shadow.h:54
SHADOW_BUFFER_TOO_SMALL
@ SHADOW_BUFFER_TOO_SMALL
The provided buffer is too small.
Definition: shadow.h:98
ShadowTopicStringType_t
ShadowTopicStringType_t
Each of these values describes the type of a shadow topic string.
Definition: shadow.h:74
ShadowStatus_t
ShadowStatus_t
Return codes from Shadow functions.
Definition: shadow.h:94
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...
Definition: shadow.c:536
SHADOW_BAD_PARAMETER
@ SHADOW_BAD_PARAMETER
Input parameter is invalid.
Definition: shadow.h:97
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...
Definition: shadow.c:430
SHADOW_FAIL
@ SHADOW_FAIL
Shadow function encountered error.
Definition: shadow.h:96
SHADOW_SUCCESS
@ SHADOW_SUCCESS
Shadow function success.
Definition: shadow.h:95