jobs.c File Reference

Implementation of the APIs from jobs.h. More...

#include <assert.h>
#include <string.h>
#include <stdbool.h>
#include "jobs.h"
#include "core_json.h"

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.
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 (JobCurrentStatus_t status, const char *expectedVersion, size_t expectedVersionLength, char *buffer, size_t bufferSize)
	Populate a message string for an UpdateJobExecution request.
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.
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)

Detailed Description

Implementation of the APIs from jobs.h.

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.

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.

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.

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.

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.

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.

See jobs.h for docs.

Jobs_UpdateMsg()

size_t Jobs_UpdateMsg	(	JobCurrentStatus_t	status,
		const char *	expectedVersion,
		size_t	expectedVersionLength,
		char *	buffer,
		size_t	bufferSize
	)

Populate a message string for an UpdateJobExecution request.

Parameters

status	Current status of the job
expectedVersion	The version that is expected, NULL if no version is expected
expectedVersionLength	The length of the expectedVersion string, 0U if no version is expected
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";
size_t expectedVersionLength = ( sizeof(expectedVersion ) - 1U );
JobCurrentStatus_t status = Succeeded;
char messageBuffer[ UPDATE_JOB_MSG_LENGTH ]  = {0};
size_t messageLength = 0U;
 
messageLength = Jobs_UpdateMsg( status,
                                expectedVersion,
                                expectedVersionLength,
                                messageBuffer,
                                UPDATE_JOB_MSG_LENGTH );
 
if (messageBufferLength > 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_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

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