AWS IoT Jobs  v1.1.0
Client library for AWS IoT Jobs
jobs.h File Reference

Client library APIs for the AWS IoT Jobs service. More...

#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Macros

#define JOBS_THINGNAME_MAX_LENGTH   128U /* per AWS IoT API Reference */
 Maximum length of a thing name for the AWS IoT Jobs Service.
 
#define JOBS_JOBID_MAX_LENGTH   64U /* per AWS IoT API Reference */
 Maximum length of a job ID for the AWS IoT Jobs Service.
 
#define THINGNAME_MAX_LENGTH   JOBS_THINGNAME_MAX_LENGTH
 User defined maximum length of a thing name for the application. More...
 
#define JOBID_MAX_LENGTH   JOBS_JOBID_MAX_LENGTH
 User defined maximum length of a job ID for the application. More...
 
#define JOBS_API_SUBSCRIBE_NEXTJOBCHANGED(thingName)    JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_NEXTJOBCHANGED )
 Topic string for subscribing to the NextJobExecutionChanged API. More...
 
#define JOBS_API_SUBSCRIBE_JOBSCHANGED(thingName)    JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_JOBSCHANGED )
 Topic string for subscribing to the JobExecutionsChanged API. More...
 
#define JOBS_API_PUBLISH_STARTNEXT(thingName)    JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_STARTNEXT )
 Topic string for publishing to the StartNextPendingJobExecution API. More...
 
#define JOBS_API_PUBLISH_GETPENDING(thingName)    JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NULL, JOBS_API_GETPENDING )
 Topic string for publishing to the GetPendingJobExecutions API. More...
 
#define JOBS_API_PUBLISH_DESCRIBENEXTJOB(thingName)    JOBS_TOPIC_COMMON( thingName, JOBS_API_JOBID_NEXT JOBS_API_LEVEL_SEPARATOR, JOBS_API_DESCRIBE )
 Topic string for querying the next pending job from the DescribeJobExecution API. More...
 
#define JOBS_API_MAX_LENGTH(thingNameLength)
 The size needed to hold the longest topic for a given thing name length. More...
 

Enumerations

enum  JobsStatus_t {
  JobsError = 0, JobsSuccess, JobsNoMatch, JobsBadParameter,
  JobsBufferTooSmall
}
 Return codes from jobs functions. More...
 
enum  JobsTopic_t {
  JobsInvalidTopic = -1, JobsJobsChanged, JobsNextJobChanged, JobsGetPendingSuccess,
  JobsGetPendingFailed, JobsStartNextSuccess, JobsStartNextFailed, JobsDescribeSuccess,
  JobsDescribeFailed, JobsUpdateSuccess, JobsUpdateFailed, JobsMaxTopic
}
 Topic values for subscription requests. More...
 

Functions

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. More...
 
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 within the topic and its length. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

Detailed Description

Macro Definition Documentation

◆ THINGNAME_MAX_LENGTH

#define THINGNAME_MAX_LENGTH   JOBS_THINGNAME_MAX_LENGTH

User defined maximum length of a thing name for the application.


Default value: JOBS_THINGNAME_MAX_LENGTH

◆ JOBID_MAX_LENGTH

#define JOBID_MAX_LENGTH   JOBS_JOBID_MAX_LENGTH

User defined maximum length of a job ID for the application.


Default value: JOBS_JOBID_MAX_LENGTH

Function Documentation

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

Parameters
[in]bufferThe buffer to contain the topic string.
[in]lengthThe size of the buffer.
[in]thingNameThe device's thingName as registered with AWS IoT.
[in]thingNameLengthThe length of the thingName.
[in]apiThe desired Jobs API, e.g., JobsNextJobChanged.
[out]outLengthThe length of the topic string written to the buffer.
Returns
JobsSuccess if the topic was written to the buffer; JobsBadParameter if invalid parameters are passed; JobsBufferTooSmall if the buffer cannot hold the full topic string.

When all parameters are valid, the topic string is written to the buffer up to one less than the buffer size. The topic is ended with a NUL character.

Note
The thingName parameter does not need a NUL terminator.
The AWS IoT Jobs service does not require clients to subscribe to the "/accepted" and "/rejected" response topics for the APIs that accept requests on PUBLISH topics. The Jobs service will send responses to requests from clients irrespective of whether they have subscribed to response topics or not. For more information, refer to the AWS docs here: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html

Example

// The following example shows usage of the Jobs_GetTopic API to
// generate topic string for the NextJobExecutionChanged API
// of AWS IoT Jobs service.
// Every device should have a unique thing name registered with AWS IoT Core.
// This example uses a dummy serial number for the thing name.
#define THING_NAME "11223445566"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1U )
// This example allocates a buffer of maximum length for a Jobs topic
// possible for the thing name using the JOBS_API_MAX_LENGTH macro.
char topicBuffer[ JOBS_API_MAX_LENGTH( THING_NAME_LENGTH ) ] = { 0 };
uint16_t topicLength = 0U;
status = Jobs_GetTopic( topicBuffer,
sizeof( topicBuffer ),
THING_NAME,
THING_NAME_LENGTH,
&( topicLength ) );
if( status == JobsSuccess )
{
// The topic string of length, topicLength, has been
// generated in the buffer, topicBuffer, for the NextJobExecutionChanged API.
// Subscribe to this topic using an MQTT client of your choice.
}

See jobs.h for docs.

◆ 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 within the topic and its length.

Parameters
[in]topicThe topic string to check.
[in]lengthThe length of the topic string.
[in]thingNameThe device's thingName as registered with AWS IoT.
[in]thingNameLengthThe length of the thingName.
[out]outApiThe jobs topic API value if present, e.g., JobsUpdateSuccess.
[out]outJobIdThe beginning of the jobID in the topic string.
[out]outJobIdLengthThe length of the jobID in the topic string.
Returns
JobsSuccess if a matching topic was found; JobsNoMatch if a matching topic was NOT found (parameter outApi gets JobsInvalidTopic ); JobsBadParameter if invalid parameters are passed.
Note
The topic and thingName parameters do not need a NUL terminator.
Not all Jobs APIs have jobIDs within the topic string. NULL and 0 are output when no jobID is present. The parameters jobId and jobIdLength may be NULL.

Example

// The following example shows how to use the Jobs_MatchTopic API to
// check if an incoming MQTT publish message is from the AWS IoT Jobs
// service.
// Assuming that these variables contain incoming topic data received
// from the MQTT client used.
char * pIncomingTopic;
size_t topicLength;
// Every device should have a unique thing name registered with AWS IoT Core.
// This example uses a dummy serial number for the thing name.
// The Jobs_MatchTopic API will check that the incoming message topic contains
// this thing name.
#define THING_NAME "11223445566"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1U )
char * pJobId = NULL;
uint16_t jobIdLength;
status = Jobs_MatchTopic( pIncomingTopic,
topicLength,
THING_NAME,
THING_NAME_LENGTH,
&api,
&pJobId,
&jobIdLength );
if( status == JobsSuccess )
{
// The Jobs_MatchTopic API has determined that the incoming topic is from
// AWS IoT Jobs service for the expected thing name.
// If the topic contains a jobID, then the pJobId and jobIdLength parameters
// populated by the API.
if( api == JobsJobsChanged )
{ // Message from JobExecutionsChanged API.
}
else if( api == JobsNextJobChanged )
{ // Message from NextJobExecutionChanged API.
}
else if( api == JobsGetPendingSuccess )
{ // Received accepted response for request to GetPendingJobExecutions API.
}
else if( api == JobsGetPendingFailed )
{ // Received rejected response for request to GetPendingJobExecutions API.
}
else if( api == JobsStartNextSuccess )
{ // Received accepted response for request to StartNextPendingJobExecution API.
}
else if( api == JobsStartNextFailed )
{ // Received rejected response for request to StartNextPendingJobExecution API.
}
else if( api == JobsDescribeSuccess )
{ // Received accepted response for request to DescribeJobExecution API.
}
else if( api == JobsDescribeFailed )
{ // Received rejected response for request to DescribeJobExecution API.
}
else if( api == JobsUpdateSuccess )
{ // Received accepted response for request to UpdateJobExecution API.
}
else if( api == JobsUpdateFailed )
{ // Received rejected response for request to UpdateJobExecution API.
}
else
{
// Unexpected response.
}
}

Output a topic value if a Jobs API topic string is present. Optionally, output a pointer to a jobID within the topic and its length.

See jobs.h for docs.

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

Parameters
[in]bufferThe buffer to contain the topic string.
[in]lengthThe size of the buffer.
[in]thingNameThe device's thingName as registered with AWS IoT.
[in]thingNameLengthThe length of the thingName.
[out]outLengthThe length of the topic string written to the buffer.
Returns
JobsSuccess if the topic was written to the buffer; JobsBadParameter if invalid parameters are passed; JobsBufferTooSmall if the buffer cannot hold the full topic string.

When all parameters are valid, the topic string is written to the buffer up to one less than the buffer size. The topic is ended with a NUL character.

Note
The thingName parameter does not need a NUL terminator.
The AWS IoT Jobs service does not require clients to subscribe to the "/accepted" and "/rejected" response topics of the GetPendingJobExecutions API. The Jobs service will send responses to requests published to the API from clients irrespective of whether they have subscribed to response topics or not. For more information, refer to the AWS docs here: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html

Example

// The following example shows usage of the Jobs_GetPending API to
// generate topic string for the GetPendingJobExecutions API
// of the AWS IoT Jobs service.
// Every device should have a unique thing name registered with AWS IoT Core.
// This example uses a dummy serial number for the thing name.
#define THING_NAME "11223445566"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1U )
// This example allocates a buffer of maximum length for a Jobs topic
// possible for the thing name using the JOBS_API_MAX_LENGTH macro.
char topicBuffer[ JOBS_API_MAX_LENGTH( THING_NAME_LENGTH ) ] = { 0 };
uint16_t topicLength = 0U;
status = Jobs_GetPending( topicBuffer,
sizeof( topicBuffer ),
THING_NAME,
THING_NAME_LENGTH,
&( topicLength ) );
if( status == JobsSuccess )
{
// The topic string of length, topicLength, has been
// generated in the buffer, topicBuffer, for the GetPendingJobExecutions API.
// Publish to this topic using an MQTT client of your choice.
}

See jobs.h for docs.

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

Parameters
[in]bufferThe buffer to contain the topic string.
[in]lengthThe size of the buffer.
[in]thingNameThe device's thingName as registered with AWS IoT.
[in]thingNameLengthThe length of the thingName.
[out]outLengthThe length of the topic string written to the buffer.
Returns
JobsSuccess if the topic was written to the buffer; JobsBadParameter if invalid parameters are passed; JobsBufferTooSmall if the buffer cannot hold the full topic string.

When all parameters are valid, the topic string is written to the buffer up to one less than the buffer size. The topic is ended with a NUL character.

Note
The thingName parameter does not need a NUL terminator.
The AWS IoT Jobs service does not require clients to subscribe to the "/accepted" and "/rejected" response topics of the StartNextPendingJobExecution API. The Jobs service will send responses to requests published to the API from clients irrespective of whether they have subscribed to response topics or not. For more information, refer to the AWS docs here: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html

Example

// The following example shows usage of the Jobs_StartNext API to
// generate topic string for the StartNextPendingJobExecution API
// of the AWS IoT Jobs service.
// Every device should have a unique thing name registered with AWS IoT Core.
// This example uses a dummy serial number for the thing name.
#define THING_NAME "11223445566"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1U )
// This example allocates a buffer of maximum length for a Jobs topic
// possible for the thing name using the JOBS_API_MAX_LENGTH macro.
char topicBuffer[ JOBS_API_MAX_LENGTH( THING_NAME_LENGTH ) ] = { 0 };
uint16_t topicLength = 0U;
status = Jobs_StartNext( topicBuffer,
sizeof( topicBuffer ),
THING_NAME,
THING_NAME_LENGTH,
&( topicLength ) );
if( status == JobsSuccess )
{
// The topic string of length, topicLength, has been generated in
// the buffer, topicBuffer, for the StartNextPendingJobExecution API.
// Publish to this topic using an MQTT client of your choice.
}

See jobs.h for docs.

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

Parameters
[in]bufferThe buffer to contain the topic string.
[in]lengthThe size of the buffer.
[in]thingNameThe device's thingName as registered with AWS IoT.
[in]thingNameLengthThe length of the thingName.
[out]jobIdThe ID of the job to describe.
[out]jobIdLengthThe length of the job ID.
[out]outLengthThe length of the topic string written to the buffer.
Returns
JobsSuccess if the topic was written to the buffer; JobsBadParameter if invalid parameters are passed; JobsBufferTooSmall if the buffer cannot hold the full topic string.

When all parameters are valid, the topic string is written to the buffer up to one less than the buffer size. The topic is ended with a NUL character.

Note
A jobId consisting of the string, "$next", is supported to generate a topic string to request the next pending job.
The thingName and jobId parameters do not need a NUL terminator.
The AWS IoT Jobs service does not require clients to subscribe to the "/accepted" and "/rejected" response topics of the DescribeJobExecution API. The Jobs service will send responses to requests published to the API from clients irrespective of whether they have subscribed to response topics or not. For more information, refer to the AWS docs here: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html

Example

// The following example shows usage of the Jobs_Describe API to
// generate topic string for the DescribeJobExecution API
// of the AWS IoT Jobs service.
// Every device should have a unique thing name registered with AWS IoT Core.
// This example uses a dummy serial number for the thing name.
#define THING_NAME "11223445566"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1U )
// The job ID is required to send a status update for a job to the AWS IoT
// Jobs service.
#define JOB_ID "My_Job"
#define JOB_ID_LENGTH ( sizeof( JOB_ID ) - 1U )
// This example allocates a buffer of maximum length for a Jobs topic
// possible for the thing name using the JOBS_API_MAX_LENGTH macro.
char topicBuffer[ JOBS_API_MAX_LENGTH( THING_NAME_LENGTH ) ] = { 0 };
uint16_t topicLength = 0U;
status = Jobs_Describe( topicBuffer,
sizeof( topicBuffer ),
THING_NAME,
THING_NAME_LENGTH,
JOB_ID,
JOB_ID_LENGTH,
&( topicLength ) );
if( status == JobsSuccess )
{
// The topic string of length, topicLength, has been generated in
// the buffer, topicBuffer, for the DescribeJobExecution API.
// Publish to this topic using an MQTT client of your choice.
}

See jobs.h for docs.

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

Parameters
[in]bufferThe buffer to contain the topic string.
[in]lengthThe size of the buffer.
[in]thingNameThe device's thingName as registered with AWS IoT.
[in]thingNameLengthThe length of the thingName.
[out]jobIdThe ID of the job to describe.
[out]jobIdLengthThe length of the job ID.
[out]outLengthThe length of the topic string written to the buffer.
Returns
JobsSuccess if the topic was written to the buffer; JobsBadParameter if invalid parameters are passed; JobsBufferTooSmall if the buffer cannot hold the full topic string.

When all parameters are valid, the topic string is written to the buffer up to one less than the buffer size. The topic is ended with a NUL character.

Note
The thingName and jobId parameters do not need a NUL terminator.
The AWS IoT Jobs service does not require clients to subscribe to the "/accepted" and "/rejected" response topics of the UpdateJobExecution API. The Jobs service will send responses to requests published to the API from clients irrespective of whether they have subscribed to response topics or not. For more information, refer to the AWS docs here: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html

Example

// The following example shows usage of the Jobs_Update API to
// generate topic string for the UpdateJobExecution API
// of the AWS IoT Jobs service.
// Every device should have a unique thing name registered with AWS IoT Core.
// This example uses a dummy serial number for the thing name.
#define THING_NAME "11223445566"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1U )
// The job ID is required to send a status update for a job to the AWS IoT
// Jobs service.
#define JOB_ID "My_Job"
#define JOB_ID_LENGTH ( sizeof( JOB_ID ) - 1U )
// This example allocates a buffer of maximum length for a Jobs topic
// possible for the thing name using the JOBS_API_MAX_LENGTH macro.
char topicBuffer[ JOBS_API_MAX_LENGTH( THING_NAME_LENGTH ) ] = { 0 };
uint16_t topicLength = 0U;
status = Jobs_Update( topicBuffer,
sizeof( topicBuffer ),
THING_NAME,
THING_NAME_LENGTH,
JOB_ID,
JOB_ID_LENGTH,
&( topicLength ) );
if( status == JobsSuccess )
{
// The topic string of length, topicLength, has been
// generated in the buffer, topicBuffer, for the UpdateJobExecution API.
// Publish to this topic using an MQTT client of your choice.
}

See jobs.h for docs.

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
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
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_API_MAX_LENGTH
#define JOBS_API_MAX_LENGTH(thingNameLength)
The size needed to hold the longest topic for a given thing name length.
Definition: jobs.h:209
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