AWS IoT Jobs  v1.1.0
Client library for AWS IoT Jobs
jobs.h
Go to the documentation of this file.
1 /*
2  * AWS IoT Jobs v1.1.0
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 
30 #ifndef JOBS_H_
31 #define JOBS_H_
32 
33 #include <stddef.h>
34 #include <stdint.h>
35 
40 #define JOBS_THINGNAME_MAX_LENGTH 128U /* per AWS IoT API Reference */
41 
46 #define JOBS_JOBID_MAX_LENGTH 64U /* per AWS IoT API Reference */
47 
48 #ifndef THINGNAME_MAX_LENGTH
49 
55  #define THINGNAME_MAX_LENGTH JOBS_THINGNAME_MAX_LENGTH
56 #endif
57 
58 #ifndef JOBID_MAX_LENGTH
59 
65  #define JOBID_MAX_LENGTH JOBS_JOBID_MAX_LENGTH
66 #endif
67 
68 #if ( THINGNAME_MAX_LENGTH > JOBS_THINGNAME_MAX_LENGTH )
69  #error "The value of THINGNAME_MAX_LENGTH exceeds the AWS IoT Jobs Service limit."
70 #endif
71 
72 #if ( JOBID_MAX_LENGTH > JOBS_JOBID_MAX_LENGTH )
73  #error "The value of JOBID_MAX_LENGTH exceeds the AWS IoT Jobs Service limit."
74 #endif
75 
81 #define JOBS_API_PREFIX "$aws/things/"
82 #define JOBS_API_PREFIX_LENGTH ( sizeof( JOBS_API_PREFIX ) - 1U )
83 
84 #define JOBS_API_BRIDGE "/jobs/"
85 #define JOBS_API_BRIDGE_LENGTH ( sizeof( JOBS_API_BRIDGE ) - 1U )
86 
87 #define JOBS_API_SUCCESS "/accepted"
88 #define JOBS_API_SUCCESS_LENGTH ( sizeof( JOBS_API_SUCCESS ) - 1U )
89 
90 #define JOBS_API_FAILURE "/rejected"
91 #define JOBS_API_FAILURE_LENGTH ( sizeof( JOBS_API_FAILURE ) - 1U )
92 
93 #define JOBS_API_JOBSCHANGED "notify"
94 #define JOBS_API_JOBSCHANGED_LENGTH ( sizeof( JOBS_API_JOBSCHANGED ) - 1U )
95 
96 #define JOBS_API_NEXTJOBCHANGED "notify-next"
97 #define JOBS_API_NEXTJOBCHANGED_LENGTH ( sizeof( JOBS_API_NEXTJOBCHANGED ) - 1U )
98 
99 #define JOBS_API_GETPENDING "get"
100 #define JOBS_API_GETPENDING_LENGTH ( sizeof( JOBS_API_GETPENDING ) - 1U )
101 
102 #define JOBS_API_STARTNEXT "start-next"
103 #define JOBS_API_STARTNEXT_LENGTH ( sizeof( JOBS_API_STARTNEXT ) - 1U )
104 
105 #define JOBS_API_DESCRIBE "get"
106 #define JOBS_API_DESCRIBE_LENGTH ( sizeof( JOBS_API_DESCRIBE ) - 1U )
107 
108 #define JOBS_API_UPDATE "update"
109 #define JOBS_API_UPDATE_LENGTH ( sizeof( JOBS_API_UPDATE ) - 1U )
110 
111 #define JOBS_API_JOBID_NEXT "$next"
112 #define JOBS_API_JOBID_NEXT_LENGTH ( sizeof( JOBS_API_JOBID_NEXT ) - 1U )
113 
114 #define JOBS_API_JOBID_NULL ""
115 #define JOBS_API_LEVEL_SEPARATOR "/"
116 
117 #define JOBS_API_COMMON_LENGTH( thingNameLength ) \
118  ( JOBS_API_PREFIX_LENGTH + ( thingNameLength ) + JOBS_API_BRIDGE_LENGTH )
119 
128 /* AWS IoT Jobs API topics. */
129 #define JOBS_TOPIC_COMMON( thingName, jobId, jobsApi ) \
130  ( JOBS_API_PREFIX \
131  thingName \
132  JOBS_API_BRIDGE \
133  jobId \
134  jobsApi )
135 
147 #define JOBS_API_SUBSCRIBE_NEXTJOBCHANGED( thingName ) \
148  JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_NEXTJOBCHANGED )
149 
160 #define JOBS_API_SUBSCRIBE_JOBSCHANGED( thingName ) \
161  JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_JOBSCHANGED )
162 
173 #define JOBS_API_PUBLISH_STARTNEXT( thingName ) \
174  JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_STARTNEXT )
175 
186 #define JOBS_API_PUBLISH_GETPENDING( thingName ) \
187  JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_GETPENDING )
188 
201 #define JOBS_API_PUBLISH_DESCRIBENEXTJOB( thingName ) \
202  JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NEXT JOBS_API_LEVEL_SEPARATOR, JOBS_API_DESCRIBE )
203 
209 #define JOBS_API_MAX_LENGTH( thingNameLength ) \
210  ( JOBS_API_COMMON_LENGTH( thingNameLength ) + \
211  JOBID_MAX_LENGTH + sizeof( '/' ) + JOBS_API_UPDATE_LENGTH + \
212  JOBS_API_SUCCESS_LENGTH + 1U )
213 
218 typedef enum
219 {
220  JobsError = 0,
226 
243 typedef enum
244 {
245  JobsInvalidTopic = -1,
246  JobsJobsChanged,
247  JobsNextJobChanged,
248  JobsGetPendingSuccess,
249  JobsGetPendingFailed,
250  JobsStartNextSuccess,
251  JobsStartNextFailed,
252  /* Topics below use a job ID. */
253  JobsDescribeSuccess,
254  JobsDescribeFailed,
255  JobsUpdateSuccess,
256  JobsUpdateFailed,
257  JobsMaxTopic
258 } JobsTopic_t;
259 
260 /*-----------------------------------------------------------*/
261 
320 /* @[declare_jobs_gettopic] */
321 JobsStatus_t Jobs_GetTopic( char * buffer,
322  size_t length,
323  const char * thingName,
324  uint16_t thingNameLength,
325  JobsTopic_t api,
326  size_t * outLength );
327 /* @[declare_jobs_gettopic] */
328 
438 /* @[declare_jobs_matchtopic] */
439 JobsStatus_t Jobs_MatchTopic( char * topic,
440  size_t length,
441  const char * thingName,
442  uint16_t thingNameLength,
443  JobsTopic_t * outApi,
444  char ** outJobId,
445  uint16_t * outJobIdLength );
446 /* @[declare_jobs_matchtopic] */
447 
506 /* @[declare_jobs_getpending] */
507 JobsStatus_t Jobs_GetPending( char * buffer,
508  size_t length,
509  const char * thingName,
510  uint16_t thingNameLength,
511  size_t * outLength );
512 /* @[declare_jobs_getpending] */
513 
572 /* @[declare_jobs_startnext] */
573 JobsStatus_t Jobs_StartNext( char * buffer,
574  size_t length,
575  const char * thingName,
576  uint16_t thingNameLength,
577  size_t * outLength );
578 /* @[declare_jobs_startnext] */
579 
650 /* @[declare_jobs_describe] */
651 JobsStatus_t Jobs_Describe( char * buffer,
652  size_t length,
653  const char * thingName,
654  uint16_t thingNameLength,
655  const char * jobId,
656  uint16_t jobIdLength,
657  size_t * outLength );
658 /* @[declare_jobs_describe] */
659 
727 /* @[declare_jobs_update] */
728 JobsStatus_t Jobs_Update( char * buffer,
729  size_t length,
730  const char * thingName,
731  uint16_t thingNameLength,
732  const char * jobId,
733  uint16_t jobIdLength,
734  size_t * outLength );
735 /* @[declare_jobs_update] */
736 
737 #endif /* ifndef JOBS_H_ */
JobsTopic_t
JobsTopic_t
Topic values for subscription requests.
Definition: jobs.h:244
JobsSuccess
@ JobsSuccess
The buffer was properly written or a match was found.
Definition: jobs.h:221
JobsBufferTooSmall
@ JobsBufferTooSmall
The buffer write was truncated.
Definition: jobs.h:224
JobsNoMatch
@ JobsNoMatch
The buffer does not contain a jobs topic.
Definition: jobs.h:222
Jobs_GetTopic
JobsStatus_t Jobs_GetTopic(char *buffer, size_t length, const char *thingName, uint16_t thingNameLength, JobsTopic_t api, size_t *outLength)
Populate a topic string for a subscription request.
Definition: jobs.c:264
Jobs_Update
JobsStatus_t Jobs_Update(char *buffer, size_t length, const char *thingName, uint16_t thingNameLength, const char *jobId, uint16_t jobIdLength, size_t *outLength)
Populate a topic string for an UpdateJobExecution request.
Definition: jobs.c:675
JobsStatus_t
JobsStatus_t
Return codes from jobs functions.
Definition: jobs.h:219
JobsBadParameter
@ JobsBadParameter
A function parameter was NULL or has an illegal value.
Definition: jobs.h:223
Jobs_Describe
JobsStatus_t Jobs_Describe(char *buffer, size_t length, const char *thingName, uint16_t thingNameLength, const char *jobId, uint16_t jobIdLength, size_t *outLength)
Populate a topic string for a DescribeJobExecution request.
Definition: jobs.c:634
Jobs_GetPending
JobsStatus_t Jobs_GetPending(char *buffer, size_t length, const char *thingName, uint16_t thingNameLength, size_t *outLength)
Populate a topic string for a GetPendingJobExecutions request.
Definition: jobs.c:567
Jobs_MatchTopic
JobsStatus_t Jobs_MatchTopic(char *topic, size_t length, const char *thingName, uint16_t thingNameLength, JobsTopic_t *outApi, char **outJobId, uint16_t *outJobIdLength)
Output a topic value if a Jobs API topic string is present. Optionally, output a pointer to a jobID w...
Definition: jobs.c:509
Jobs_StartNext
JobsStatus_t Jobs_StartNext(char *buffer, size_t length, const char *thingName, uint16_t thingNameLength, size_t *outLength)
Populate a topic string for a StartNextPendingJobExecution request.
Definition: jobs.c:600