jobs.h File Reference

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

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

Go to the source code of this file.

Data Structures
struct	JobsUpdateRequest_t
	Structure for Jobs_UpdateMsg request parameters. More...

Macros
#define	TOPIC_BUFFER_SIZE   256U
	Size of Topic Buffer.
#define	START_JOB_MSG_LENGTH   147U
	Size of Jobs Start Next Message Buffer.
#define	UPDATE_JOB_MSG_LENGTH   48U
	Size of Jobs Update Message Buffer.
#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.
#define	JOBID_MAX_LENGTH   JOBS_JOBID_MAX_LENGTH
	User defined maximum length of a job ID for the application.
#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.
#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.
#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.
#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.
#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.
#define	JOBS_API_MAX_LENGTH(thingNameLength)
	The size needed to hold the longest topic for a given thing name length.

Enumerations
enum	JobsStatus_t {   JobsError = 0 , JobsSuccess , JobsNoMatch , JobsBadParameter ,   JobsBufferTooSmall }
	Return codes from jobs functions. More...
enum	JobCurrentStatus_t {   Queued , InProgress , Failed , Succeeded ,   Rejected }
	Status codes for jobs.
enum	JobUpdateStatus_t { JobUpdateStatus_Accepted , JobUpdateStatus_Rejected }
	Status codes for job update status.
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.
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.
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.
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.
size_t	Jobs_StartNextMsg (const char *clientToken, size_t clientTokenLength, char *buffer, size_t bufferSize)
	Populate a message string for a StartNextPendingJobExecution request.
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.
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.
size_t	Jobs_UpdateMsg (JobsUpdateRequest_t request, char *buffer, size_t bufferSize)
	Populate a message string for an UpdateJobExecution request.
size_t	Jobs_GetJobId (const char *message, size_t messageLength, const char **jobId)
	Retrieves the job ID from a given message (if applicable)
size_t	Jobs_GetJobDocument (const char *message, size_t messageLength, const char **jobDoc)
	Retrieves the job document from a given message (if applicable)
bool	Jobs_IsStartNextAccepted (const char *topic, const size_t topicLength, const char *thingName, const size_t thingNameLength)
	Checks if a message comes from the start-next/accepted reserved topic.
bool	Jobs_IsJobUpdateStatus (const char *topic, const size_t topicLength, const char *jobId, const size_t jobIdLength, const char *thingName, const size_t thingNameLength, JobUpdateStatus_t expectedStatus)
	Checks if a message comes from the update/accepted reserved topic.

Detailed Description

Client library APIs for the AWS IoT Jobs service.

https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#jobs-mqtt-api

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]	buffer	The buffer to contain the topic string.
[in]	length	The size of the buffer.
[in]	thingName	The device's thingName as registered with AWS IoT.
[in]	thingNameLength	The length of the thingName.
[in]	api	The desired Jobs API, e.g., JobsNextJobChanged.
[out]	outLength	The 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;
JobsStatus_t status = JobsSuccess;
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]	topic	The topic string to check.
[in]	length	The length of the topic string.
[in]	thingName	The device's thingName as registered with AWS IoT.
[in]	thingNameLength	The length of the thingName.
[out]	outApi	The jobs topic API value if present, e.g., JobsUpdateSuccess.
[out]	outJobId	The beginning of the jobID in the topic string.
[out]	outJobIdLength	The 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 )
 
JobsTopic_t api;
char * pJobId = NULL;
uint16_t jobIdLength;
JobsStatus_t status = JobsSuccess;
 
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]	buffer	The buffer to contain the topic string.
[in]	length	The size of the buffer.
[in]	thingName	The device's thingName as registered with AWS IoT.
[in]	thingNameLength	The length of the thingName.
[out]	outLength	The 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;
JobsStatus_t status = JobsSuccess;
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]	buffer	The buffer to contain the topic string.
[in]	length	The size of the buffer.
[in]	thingName	The device's thingName as registered with AWS IoT.
[in]	thingNameLength	The length of the thingName.
[out]	outLength	The 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;
JobsStatus_t status = JobsSuccess;
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_StartNextMsg()

size_t Jobs_StartNextMsg	(	const char *	clientToken,
		size_t	clientTokenLength,
		char *	buffer,
		size_t	bufferSize
	)

Populate a message string for a StartNextPendingJobExecution request.

Parameters

clientToken	The device's token
clientTokenLength	The expected length of the clientToken
buffer	The buffer to be written to
bufferSize	The size of the buffer

Returns

0 if write to buffer fails

The message length if the write is successful

Example

// The Following Example shows usage of the Jobs_StartNextMsg API
// to generate a message string for a StartNextPendingJobExecution request.
 
const char clientToken[] = "test";
size_t clientTokenLength = ( sizeof( clientToken ) - 1U );
char messageBuffer[ START_JOB_MSG_LENGTH ] = {0};
size_t messageLength = 0U;
 
messageLength = Jobs_StartNextMsg( clientToken,
                                   clientTokenLength,
                                   messageBuffer,
                                   START_JOB_MSG_LENGTH );
 
if ( messageLength > 0 )
{
    // The message string of the clientToken has been generated in
    // the buffer, messageBuffer, for the StartNextPendingJobExecution request
    // Publish to the topic string generated by Jobs_StartNext() using an
    // MQTT client of your choice.
}

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]	buffer	The buffer to contain the topic string.
[in]	length	The size of the buffer.
[in]	thingName	The device's thingName as registered with AWS IoT.
[in]	thingNameLength	The length of the thingName.
[out]	jobId	The ID of the job to describe.
[out]	jobIdLength	The length of the job ID.
[out]	outLength	The 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;
JobsStatus_t status = JobsSuccess;
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]	buffer	The buffer to contain the topic string.
[in]	length	The size of the buffer.
[in]	thingName	The device's thingName as registered with AWS IoT.
[in]	thingNameLength	The length of the thingName.
[out]	jobId	The ID of the job to describe.
[out]	jobIdLength	The length of the job ID.
[out]	outLength	The 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;
JobsStatus_t status = JobsSuccess;
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.

Jobs_UpdateMsg()

size_t Jobs_UpdateMsg	(	JobsUpdateRequest_t	request,
		char *	buffer,
		size_t	bufferSize
	)

Populate a message string for an UpdateJobExecution request.

Parameters

request	A jobs update request structure.
buffer	The buffer to be written to.
bufferSize	the size of the buffer.

Returns

0 if write to buffer fails.

messageLength if the write is successful.

Example

// The Following Example shows usage of the Jobs_UpdateMsg API to
// generate a message string for the UpdateJobExecution API
// of the AWS IoT Jobs Service.
 
const char expectedVersion[] = "2";
const char statusDetails[] = "{\"key\":\"value\"}";
char messageBuffer[ UPDATE_JOB_MSG_LENGTH ]  = {0};
size_t messageLength = 0U;
 
JobsUpdateRequest_t request;
request.status = Succeeded;
request.expectedVersion = expectedVersion;
request.expectedVersionLength = ( sizeof( expectedVersion ) - 1U );
request.statusDetails = statusDetails;
request.statusDetailsLength = ( sizeof( statusDetails ) - 1U );
 
messageLength = Jobs_UpdateMsg( request
                                messageBuffer,
                                UPDATE_JOB_MSG_LENGTH );
 
if (messageLength > 0 )
{
    // The message string of length, messageLength, has been
    // generated in the buffer, messageBuffer, for the UpdateJobExecution API
    // Publish this message to the topic generated by Jobs_Update using an
    // MQTT client of your choice.
}

Jobs_GetJobId()

size_t Jobs_GetJobId	(	const char *	message,
		size_t	messageLength,
		const char **	jobId
	)

Retrieves the job ID from a given message (if applicable)

Parameters

message	[In] A JSON formatted message
messageLength	[In] The length of the message
jobId	[Out] The job ID

Returns

size_t The job ID length

Example

// The following example shows the usage of the Jobs_GetJobId API to
// extract the jobId and its length from a message, if present.
 
const char * message;    // A JSON formatted message from the IoT core
size_t messageLength;    // Length of the JSON formatted message
const char * jobId;      // variable to hold jobId
size_t jobIdLength = 0U; // Holds length of the jobId
 
jobIdLength = Jobs_GetJobId( message,
                             messageLength,
                             &jobId);
 
if ( jobIdLength > 0 )
{
    // Job ID was successfully extracted from the message
    // Store the Job ID so that it can be used as needed by other functions.
    // For example, as an input to Jobs_Update.
}

Jobs_GetJobDocument()

size_t Jobs_GetJobDocument	(	const char *	message,
		size_t	messageLength,
		const char **	jobDoc
	)

Retrieves the job document from a given message (if applicable)

Parameters

message	[In] A JSON formatted message which
messageLength	[In] The length of the message
jobDoc	[Out] The job document

Returns

size_t The length of the job document

Example

// The following example shows the usage of the Jobs_GetJobId API to
// extract the jobId and its length from a message, if present.
 
const char * message;     // A JSON formatted message from the IoT core
size_t messageLength;     // Length of the JSON formatted message
const char * jobDoc;      // variable to hold the job doc
size_t jobDocLength = 0U; // Holds length of the job doc
 
jobDocLength = Jobs_GetJobDocument( message,
                                    messageLength,
                                    &jobDoc);
 
if ( jobDocLength > 0 )
{
    // JobDoc was successfully extracted from the message.
    // Pass JobDoc as input to otaParser_parseJobDocFile to
    // extract the fields from the job document and store them
    // in a AfrOtaJobDocumentFields_t stuct.
}

Jobs_IsStartNextAccepted()

bool Jobs_IsStartNextAccepted	(	const char *	topic,
		const size_t	topicLength,
		const char *	thingName,
		const size_t	thingNameLength
	)

Checks if a message comes from the start-next/accepted reserved topic.

Parameters

topic	The topic to check against
topicLength	The expected topic length
thingName	The device's thingName as registered with AWS IoT.
thingNameLength	The length of the thingName.

Returns

true If the topic is the start-next/accepted topic

false If the topic is not the start-next/accepted topic

Jobs_IsJobUpdateStatus()

bool Jobs_IsJobUpdateStatus	(	const char *	topic,
		const size_t	topicLength,
		const char *	jobId,
		const size_t	jobIdLength,
		const char *	thingName,
		const size_t	thingNameLength,
		JobUpdateStatus_t	expectedStatus
	)

Checks if a message comes from the update/accepted reserved topic.

Parameters

topic	The topic to check against
topicLength	The expected topic length
jobId	Corresponding Job ID which the update was accepted for
jobIdLength	The Job ID length
thingName	The device's thingName as registered with AWS IoT.
thingNameLength	The length of the thingName.
expectedStatus	The job update status reported by AWS IoT Jobs

Returns

true If the topic is the update/<expectedStatus> topic

false If the topic is not the update/<expectedStatus> topic