AWS IoT Jobs v1.5.1
Client library for AWS IoT Jobs
 
Loading...
Searching...
No Matches
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
clientTokenThe device's token
clientTokenLengthThe expected length of the clientToken
bufferThe buffer to be written to
bufferSizeThe 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,
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.
}
#define START_JOB_MSG_LENGTH
Size of Jobs Start Next Message Buffer.
Definition: jobs.h:55
size_t Jobs_StartNextMsg(const char *clientToken, size_t clientTokenLength, char *buffer, size_t bufferSize)
Populate a message string for a StartNextPendingJobExecution request.
Definition: jobs.c:718

◆ 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
statusCurrent status of the job
expectedVersionThe version that is expected
expectedVersionLengthThe length of the expectedVersion string
bufferThe buffer to be written to
bufferSizethe 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,
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.
}
#define UPDATE_JOB_MSG_LENGTH
Size of Jobs Update Message Buffer.
Definition: jobs.h:61
JobCurrentStatus_t
Status codes for jobs.
Definition: jobs.h:267
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.
Definition: jobs.c:816

◆ 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
topicThe topic to check against
topicLengthThe expected topic length
thingNameThe device's thingName as registered with AWS IoT.
thingNameLengthThe 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
topicThe topic to check against
topicLengthThe expected topic length
jobIdCorresponding Job ID which the update was accepted for
jobIdLengthThe Job ID length
thingNameThe device's thingName as registered with AWS IoT.
thingNameLengthThe length of the thingName.
expectedStatusThe 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.
}
size_t Jobs_GetJobId(const char *message, size_t messageLength, const char **jobId)
Retrieves the job ID from a given message (if applicable)
Definition: jobs.c:900

◆ 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.
}
size_t Jobs_GetJobDocument(const char *message, size_t messageLength, const char **jobDoc)
Retrieves the job document from a given message (if applicable)
Definition: jobs.c:923