User-facing functions of the Jobs library. More...

#include "iot_config.h"
#include "types/aws_iot_jobs_types.h"

Functions
AwsIotJobsError_t	AwsIotJobs_Init (uint32_t mqttTimeoutMs)
	One-time initialization function for the Jobs library. More...

void	AwsIotJobs_Cleanup (void)
	One-time deinitialization function for the Jobs library. More...

AwsIotJobsError_t	AwsIotJobs_GetPendingAsync (const AwsIotJobsRequestInfo_t pRequestInfo, uint32_t flags, const AwsIotJobsCallbackInfo_t pCallbackInfo, AwsIotJobsOperation_t *const pGetPendingOperation)
	Get the list of all pending jobs for a Thing and receive an asynchronous notification when the response arrives. More...

AwsIotJobsError_t	AwsIotJobs_GetPendingSync (const AwsIotJobsRequestInfo_t pRequestInfo, uint32_t flags, uint32_t timeoutMs, AwsIotJobsResponse_t const pJobsResponse)
	Get the list of all pending jobs for a Thing with a timeout for receiving the response. More...

AwsIotJobsError_t	AwsIotJobs_StartNextAsync (const AwsIotJobsRequestInfo_t pRequestInfo, const AwsIotJobsUpdateInfo_t pUpdateInfo, uint32_t flags, const AwsIotJobsCallbackInfo_t pCallbackInfo, AwsIotJobsOperation_t const pStartNextOperation)
	Start the next pending job execution for a Thing and receive an asynchronous notification when the response arrives. More...

AwsIotJobsError_t	AwsIotJobs_StartNextSync (const AwsIotJobsRequestInfo_t pRequestInfo, const AwsIotJobsUpdateInfo_t pUpdateInfo, uint32_t flags, uint32_t timeoutMs, AwsIotJobsResponse_t *const pJobsResponse)
	Start the next pending job execution for a Thing with a timeout for receiving the response. More...

AwsIotJobsError_t	AwsIotJobs_DescribeAsync (const AwsIotJobsRequestInfo_t pRequestInfo, int32_t executionNumber, bool includeJobDocument, uint32_t flags, const AwsIotJobsCallbackInfo_t pCallbackInfo, AwsIotJobsOperation_t *const pDescribeOperation)
	Get detailed information about a job execution and receive an asynchronous notification when the response arrives. More...

AwsIotJobsError_t	AwsIotJobs_DescribeSync (const AwsIotJobsRequestInfo_t pRequestInfo, int32_t executionNumber, bool includeJobDocument, uint32_t flags, uint32_t timeoutMs, AwsIotJobsResponse_t const pJobsResponse)
	Get detailed information about a job execution with a timeout for receiving the response. More...

AwsIotJobsError_t	AwsIotJobs_UpdateAsync (const AwsIotJobsRequestInfo_t pRequestInfo, const AwsIotJobsUpdateInfo_t pUpdateInfo, uint32_t flags, const AwsIotJobsCallbackInfo_t pCallbackInfo, AwsIotJobsOperation_t const pUpdateOperation)
	Update the status of a job execution and receive an asynchronous notification when the Job update completes. More...

AwsIotJobsError_t	AwsIotJobs_UpdateSync (const AwsIotJobsRequestInfo_t pRequestInfo, const AwsIotJobsUpdateInfo_t pUpdateInfo, uint32_t flags, uint32_t timeoutMs, AwsIotJobsResponse_t *const pJobsResponse)
	Update the status of a job execution with a timeout for receiving the response. More...

AwsIotJobsError_t	AwsIotJobs_Wait (AwsIotJobsOperation_t operation, uint32_t timeoutMs, AwsIotJobsResponse_t *const pJobsResponse)
	Wait for a Jobs operation to complete. More...

AwsIotJobsError_t	AwsIotJobs_SetNotifyPendingCallback (IotMqttConnection_t mqttConnection, const char pThingName, size_t thingNameLength, uint32_t flags, const AwsIotJobsCallbackInfo_t pNotifyPendingCallback)
	Set a callback to be invoked when the list of pending Jobs changes. More...

AwsIotJobsError_t	AwsIotJobs_SetNotifyNextCallback (IotMqttConnection_t mqttConnection, const char pThingName, size_t thingNameLength, uint32_t flags, const AwsIotJobsCallbackInfo_t pNotifyNextCallback)
	Set a callback to be invoked when the next pending Job changes. More...

AwsIotJobsError_t	AwsIotJobs_RemovePersistentSubscriptions (const AwsIotJobsRequestInfo_t *pRequestInfo, uint32_t flags)
	Remove persistent Jobs operation topic subscriptions. More...

const char *	AwsIotJobs_strerror (AwsIotJobsError_t status)
	Returns a string that describes an AwsIotJobsError_t. More...

const char *	AwsIotJobs_StateName (AwsIotJobState_t state)
	Returns a string that describes an AwsIotJobState_t. More...

Detailed Description

User-facing functions of the Jobs library.

Function Documentation

◆ AwsIotJobs_Init()

AwsIotJobsError_t AwsIotJobs_Init ( uint32_t mqttTimeoutMs )

One-time initialization function for the Jobs library.

This function performs internal setup of the Jobs library. It must be called once (and only once) before calling any other Jobs function. Calling this function more than once without first calling AwsIotJobs_Cleanup may result in a crash.

Parameters

[in] mqttTimeoutMs The amount of time (in milliseconds) that the Jobs library will wait for MQTT operations. Optional; set this to 0 to use AWS_IOT_JOBS_DEFAULT_MQTT_TIMEOUT_MS.

Returns

One of the following:

Warning: No thread-safety guarantees are provided for this function.

See also: AwsIotJobs_Cleanup

◆ AwsIotJobs_Cleanup()

void AwsIotJobs_Cleanup ( void )

One-time deinitialization function for the Jobs library.

This function frees resources taken in AwsIotJobs_Init and deletes any persistent subscriptions. It should be called to clean up the Jobs library. After this function returns, AwsIotJobs_Init must be called again before calling any other Jobs function.

Warning: No thread-safety guarantees are provided for this function.

See also: AwsIotJobs_Init

◆ AwsIotJobs_GetPendingAsync()

AwsIotJobsError_t AwsIotJobs_GetPendingAsync	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		uint32_t	flags,
		const AwsIotJobsCallbackInfo_t *	pCallbackInfo,
		AwsIotJobsOperation_t *const	pGetPendingOperation
	)

Get the list of all pending jobs for a Thing and receive an asynchronous notification when the response arrives.

This function implements the GetPendingJobExecutions command of the Jobs API, which gets the list of all Jobs for a Thing that are not in a terminal state. The list of retrieved Jobs is returned as the pResponse member in AwsIotJobsCallbackParam_t, or through the AwsIotJobsResponse_t parameter of AwsIotJobs_Wait.

Parameters

[in]	pRequestInfo	Jobs request parameters.
[in]	flags	Flags which modify the behavior of the Jobs request. See Jobs Function Flags.
[in]	pCallbackInfo	Asynchronous notification of this function's completion.
[out]	pGetPendingOperation	Set to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the Jobs operation completes.

Returns

This function will return AWS_IOT_JOBS_STATUS_PENDING upon successfully queuing the Jobs operation.

If this function fails before queuing the Jobs operation, it will return one of:

Upon successful completion of the Jobs operation (either through an AwsIotJobsCallbackInfo_t or AwsIotJobs_Wait), the status will be AWS_IOT_JOBS_SUCCESS.

Should the Jobs operation fail, the status will be one of:

AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document)
AWS_IOT_JOBS_MQTT_ERROR
AWS_IOT_JOBS_BAD_RESPONSE
A Jobs failure reason between AWS_IOT_JOBS_INVALID_TOPIC and AWS_IOT_JOBS_TERMINAL_STATE.

See also: AwsIotJobs_GetPendingSync for a blocking variant of this function.

Example

#define THING_NAME "Test_device"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )
// Signature of Jobs callback function.
void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam );
AwsIotJobsOperation_t getPendingOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER;
AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER;
AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;
// Set the request info.
requestInfo.mqttConnection = _mqttConnection;
requestInfo.pThingName = THING_NAME;
requestInfo.thingNameLength = THING_NAME_LENGTH;
// Set the callback function to invoke.
callbackInfo.function = _jobsCallback;
// Queue Jobs GET PENDING.
AwsIotJobsError_t getPendingResult = AwsIotJobs_GetPendingAsync( &requestInfo,
                                                                 0,
                                                                 &callbackInfo,
                                                                 &getPendingOperation );
// GET PENDING should have returned AWS_IOT_JOBS_STATUS_PENDING. The function
// _jobsCallback will be invoked once the Jobs response is received.

◆ AwsIotJobs_GetPendingSync()

AwsIotJobsError_t AwsIotJobs_GetPendingSync	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		uint32_t	flags,
		uint32_t	timeoutMs,
		AwsIotJobsResponse_t *const	pJobsResponse
	)

Get the list of all pending jobs for a Thing with a timeout for receiving the response.

This function queues a Jobs GET PENDING, then waits for the result. Internally, this function is a call to AwsIotJobs_GetPendingAsync followed by AwsIotJobs_Wait. See AwsIotJobs_GetPendingAsync for more information on the Jobs GET PENDING command.

Parameters

[in]	pRequestInfo	Jobs request parameters.
[in]	flags	Flags which modify the behavior of the Jobs request. See Jobs Function Flags.
[in]	timeoutMs	If a response is not received within this timeout, this function returns AWS_IOT_JOBS_TIMEOUT.
[out]	pJobsResponse	The response received from the Jobs service.

Returns

One of the following:

AWS_IOT_JOBS_SUCCESS
AWS_IOT_JOBS_NOT_INITIALIZED
AWS_IOT_JOBS_BAD_PARAMETER
AWS_IOT_JOBS_NO_MEMORY
AWS_IOT_JOBS_MQTT_ERROR
AWS_IOT_JOBS_BAD_RESPONSE
AWS_IOT_JOBS_TIMEOUT
A Jobs failure reason between AWS_IOT_JOBS_INVALID_TOPIC and AWS_IOT_JOBS_TERMINAL_STATE.

◆ AwsIotJobs_StartNextAsync()

AwsIotJobsError_t AwsIotJobs_StartNextAsync	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		const AwsIotJobsUpdateInfo_t *	pUpdateInfo,
		uint32_t	flags,
		const AwsIotJobsCallbackInfo_t *	pCallbackInfo,
		AwsIotJobsOperation_t *const	pStartNextOperation
	)

Start the next pending job execution for a Thing and receive an asynchronous notification when the response arrives.

This function implements the StartNextPendingJobExecution command of the Jobs API, which gets and starts the next pending job execution for a Thing.

Parameters

[in]	pRequestInfo	Jobs request parameters.
[in]	pUpdateInfo	Jobs update parameters.
[in]	flags	Flags which modify the behavior of the Jobs request. See Jobs Function Flags.
[in]	pCallbackInfo	Asynchronous notification of this function's completion.
[out]	pStartNextOperation	Set to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the Jobs operation completes.

Returns

This function will return AWS_IOT_JOBS_STATUS_PENDING upon successfully queuing the Jobs operation.

If this function fails before queuing the Jobs operation, it will return one of:

Upon successful completion of the Jobs operation (either through an AwsIotJobsCallbackInfo_t or AwsIotJobs_Wait), the status will be AWS_IOT_JOBS_SUCCESS.

Should the Jobs operation fail, the status will be one of:

AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document)
AWS_IOT_JOBS_MQTT_ERROR
AWS_IOT_JOBS_BAD_RESPONSE
A Jobs failure reason between AWS_IOT_JOBS_INVALID_TOPIC and AWS_IOT_JOBS_TERMINAL_STATE.

See also: AwsIotJobs_StartNextSync for a blocking variant of this function.

Example

#define THING_NAME "Test_device"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )
// Signature of Jobs callback function.
void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam );
AwsIotJobsOperation_t startNextOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER;
AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER;
AwsIotJobsUpdateInfo_t updateInfo = AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER;
AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;
// Set the request info. The update info generally does not need to be
// changed, as its defaults are suitable.
requestInfo.mqttConnection = _mqttConnection;
requestInfo.pThingName = THING_NAME;
requestInfo.thingNameLength = THING_NAME_LENGTH;
// Set the callback function to invoke.
callbackInfo.function = _jobsCallback;
// Queue Jobs START NEXT.
AwsIotJobsError_t startNextResult = AwsIotJobs_StartNextAsync( &requestInfo,
                                                               &updateInfo,
                                                               0,
                                                               &callbackInfo,
                                                               &startNextOperation );
// START NEXT should have returned AWS_IOT_JOBS_STATUS_PENDING. The function
// _jobsCallback will be invoked once the Jobs response is received.

◆ AwsIotJobs_StartNextSync()

AwsIotJobsError_t AwsIotJobs_StartNextSync	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		const AwsIotJobsUpdateInfo_t *	pUpdateInfo,
		uint32_t	flags,
		uint32_t	timeoutMs,
		AwsIotJobsResponse_t *const	pJobsResponse
	)

Start the next pending job execution for a Thing with a timeout for receiving the response.

This function queues a Jobs START NEXT, then waits for the result. Internally, this function is a call to AwsIotJobs_StartNextAsync followed by AwsIotJobs_Wait. See AwsIotJobs_StartNextAsync for more information on the Jobs START NEXT command.

Parameters

[in]	pRequestInfo	Jobs request parameters.
[in]	pUpdateInfo	Jobs update parameters.
[in]	flags	Flags which modify the behavior of the Jobs request. See Jobs Function Flags.
[in]	timeoutMs	If a response is not received within this timeout, this function returns AWS_IOT_JOBS_TIMEOUT.
[out]	pJobsResponse	The response received from the Jobs service.

Returns

One of the following:

AWS_IOT_JOBS_SUCCESS
AWS_IOT_JOBS_NOT_INITIALIZED
AWS_IOT_JOBS_BAD_PARAMETER
AWS_IOT_JOBS_NO_MEMORY
AWS_IOT_JOBS_MQTT_ERROR
AWS_IOT_JOBS_BAD_RESPONSE
AWS_IOT_JOBS_TIMEOUT
A Jobs failure reason between AWS_IOT_JOBS_INVALID_TOPIC and AWS_IOT_JOBS_TERMINAL_STATE.

◆ AwsIotJobs_DescribeAsync()

AwsIotJobsError_t AwsIotJobs_DescribeAsync	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		int32_t	executionNumber,
		bool	includeJobDocument,
		uint32_t	flags,
		const AwsIotJobsCallbackInfo_t *	pCallbackInfo,
		AwsIotJobsOperation_t *const	pDescribeOperation
	)

Get detailed information about a job execution and receive an asynchronous notification when the response arrives.

This function implements the DescribeJobExecution command of the Jobs API, which gets detailed information about a job execution. The description is returned as the pResponse member in AwsIotJobsCallbackParam_t, or through the AwsIotJobsResponse_t parameter of AwsIotJobs_Wait.

Parameters

[in]	pRequestInfo	Jobs request parameters.
[in]	executionNumber	The execution number to describe. Optional; pass AWS_IOT_JOBS_NO_EXECUTION_NUMBER to ignore.
[in]	includeJobDocument	Whether the response should include the full Job document.
[in]	flags	Flags which modify the behavior of the Jobs request. See Jobs Function Flags.
[in]	pCallbackInfo	Asynchronous notification of this function's completion.
[out]	pDescribeOperation	Set to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the Jobs operation completes.

Returns

This function will return AWS_IOT_JOBS_STATUS_PENDING upon successfully queuing the Jobs operation.

If this function fails before queuing the Jobs operation, it will return one of:

Upon successful completion of the Jobs operation (either through an AwsIotJobsCallbackInfo_t or AwsIotJobs_Wait), the status will be AWS_IOT_JOBS_SUCCESS.

Should the Jobs operation fail, the status will be one of:

AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document)
AWS_IOT_JOBS_MQTT_ERROR
AWS_IOT_JOBS_BAD_RESPONSE
A Jobs failure reason between AWS_IOT_JOBS_INVALID_TOPIC and AWS_IOT_JOBS_TERMINAL_STATE.

See also: AwsIotJobs_DescribeSync for a blocking variant of this function.

Example

#define THING_NAME "Test_device"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )
// Signature of Jobs callback function.
void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam );
AwsIotJobsOperation_t describeOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER;
AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER;
AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;
// Set the request info.
requestInfo.mqttConnection = _mqttConnection;
requestInfo.pThingName = THING_NAME;
requestInfo.thingNameLength = THING_NAME_LENGTH;
// Describe the next Job. Or, this may be set to a specific Job ID.
requestInfo.pJobId = AWS_IOT_JOBS_NEXT_JOB;
requestInfo.jobIdLength = AWS_IOT_JOBS_NEXT_JOB_LENGTH;
// Set the callback function to invoke.
callbackInfo.function = _jobsCallback;
// Queue Jobs DESCRIBE.
AwsIotJobsError_t describeResult = AwsIotJobs_DescribeAsync( &requestInfo,
                                                             AWS_IOT_JOBS_NO_EXECUTION_NUMBER,
                                                             false,
                                                             0,
                                                             &callbackInfo,
                                                             &describeOperation );
// DESCRIBE should have returned AWS_IOT_JOBS_STATUS_PENDING. The function
// _jobsCallback will be invoked once the Jobs response is received.

◆ AwsIotJobs_DescribeSync()

AwsIotJobsError_t AwsIotJobs_DescribeSync	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		int32_t	executionNumber,
		bool	includeJobDocument,
		uint32_t	flags,
		uint32_t	timeoutMs,
		AwsIotJobsResponse_t *const	pJobsResponse
	)

Get detailed information about a job execution with a timeout for receiving the response.

This function queues a Jobs DESCRIBE, then waits for the result. Internally, this function is a call to AwsIotJobs_DescribeAsync followed by AwsIotJobs_Wait. See AwsIotJobs_DescribeAsync for more information on the Jobs DESCRIBE command.

Parameters

[in]	pRequestInfo	Jobs request parameters.
[in]	executionNumber	The execution number to describe. Optional; pass AWS_IOT_JOBS_NO_EXECUTION_NUMBER to ignore.
[in]	includeJobDocument	Whether the response should include the full Job document.
[in]	flags	Flags which modify the behavior of the Jobs request. See Jobs Function Flags.
[in]	timeoutMs	If a response is not received within this timeout, this function returns AWS_IOT_JOBS_TIMEOUT.
[out]	pJobsResponse	The response received from the Jobs service.

Returns

One of the following:

AWS_IOT_JOBS_SUCCESS
AWS_IOT_JOBS_NOT_INITIALIZED
AWS_IOT_JOBS_BAD_PARAMETER
AWS_IOT_JOBS_NO_MEMORY
AWS_IOT_JOBS_MQTT_ERROR
AWS_IOT_JOBS_BAD_RESPONSE
AWS_IOT_JOBS_TIMEOUT
A Jobs failure reason between AWS_IOT_JOBS_INVALID_TOPIC and AWS_IOT_JOBS_TERMINAL_STATE.

◆ AwsIotJobs_UpdateAsync()

AwsIotJobsError_t AwsIotJobs_UpdateAsync	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		const AwsIotJobsUpdateInfo_t *	pUpdateInfo,
		uint32_t	flags,
		const AwsIotJobsCallbackInfo_t *	pCallbackInfo,
		AwsIotJobsOperation_t *const	pUpdateOperation
	)

Update the status of a job execution and receive an asynchronous notification when the Job update completes.

This function implements the UpdateJobExecution command of the Jobs API, which updates the status of a Job execution.

Parameters

[in]	pRequestInfo	Jobs request parameters.
[in]	pUpdateInfo	Jobs update parameters.
[in]	flags	Flags which modify the behavior of the Jobs request. See Jobs Function Flags.
[in]	pCallbackInfo	Asynchronous notification of this function's completion.
[out]	pUpdateOperation	Set to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the Jobs operation completes.

Returns

This function will return AWS_IOT_JOBS_STATUS_PENDING upon successfully queuing the Jobs operation.

If this function fails before queuing the Jobs operation, it will return one of:

Upon successful completion of the Jobs operation (either through an AwsIotJobsCallbackInfo_t or AwsIotJobs_Wait), the status will be AWS_IOT_JOBS_SUCCESS.

Should the Jobs operation fail, the status will be one of:

AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document)
AWS_IOT_JOBS_MQTT_ERROR
AWS_IOT_JOBS_BAD_RESPONSE
A Jobs failure reason between AWS_IOT_JOBS_INVALID_TOPIC and AWS_IOT_JOBS_TERMINAL_STATE.

See also: AwsIotJobs_UpdateSync for a blocking variant of this function.

Example

#define THING_NAME "Test_device"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )
// Signature of Jobs callback function.
void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam );
AwsIotJobsOperation_t updateOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER;
AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER;
AwsIotJobsUpdateInfo_t updateInfo = AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER;
AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;
// Set the request info.
requestInfo.mqttConnection = _mqttConnection;
requestInfo.pThingName = THING_NAME;
requestInfo.thingNameLength = THING_NAME_LENGTH;
// A Job ID must be set. AWS_IOT_JOBS_NEXT_JOB is not valid for UPDATE.
requestInfo.pJobId = "job-id";
requestInfo.jobIdLength = 6;
// Set the update info.
updateInfo.newStatus = AWS_IOT_JOB_STATE_SUCCEEDED;
// Set the callback function to invoke.
callbackInfo.function = _jobsCallback;
// Queue Jobs UPDATE.
AwsIotJobsError_t updateResult = AwsIotJobs_UpdateAsync( &requestInfo,
                                                         &updateInfo,
                                                         0,
                                                         &callbackInfo,
                                                         &updateOperation );
// UPDATE should have returned AWS_IOT_JOBS_STATUS_PENDING. The function
// _jobsCallback will be invoked once the Jobs response is received.

◆ AwsIotJobs_UpdateSync()

AwsIotJobsError_t AwsIotJobs_UpdateSync	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		const AwsIotJobsUpdateInfo_t *	pUpdateInfo,
		uint32_t	flags,
		uint32_t	timeoutMs,
		AwsIotJobsResponse_t *const	pJobsResponse
	)

Update the status of a job execution with a timeout for receiving the response.

This function queues a Jobs UPDATE, then waits for the result. Internally, this function is a call to AwsIotJobs_UpdateAsync followed by AwsIotJobs_Wait. See AwsIotJobs_UpdateAsync for more information on the Jobs UPDATE command.

Parameters

[in]	pRequestInfo	Jobs request parameters.
[in]	pUpdateInfo	Jobs update parameters.
[in]	flags	Flags which modify the behavior of the Jobs request. See Jobs Function Flags.
[in]	timeoutMs	If a response is not received within this timeout, this function returns AWS_IOT_JOBS_TIMEOUT.
[out]	pJobsResponse	The response received from the Jobs service.

Returns

One of the following:

AWS_IOT_JOBS_SUCCESS
AWS_IOT_JOBS_NOT_INITIALIZED
AWS_IOT_JOBS_BAD_PARAMETER
AWS_IOT_JOBS_NO_MEMORY
AWS_IOT_JOBS_MQTT_ERROR
AWS_IOT_JOBS_BAD_RESPONSE
AWS_IOT_JOBS_TIMEOUT
A Jobs failure reason between AWS_IOT_JOBS_INVALID_TOPIC and AWS_IOT_JOBS_TERMINAL_STATE.

◆ AwsIotJobs_Wait()

AwsIotJobsError_t AwsIotJobs_Wait	(	AwsIotJobsOperation_t	operation,
		uint32_t	timeoutMs,
		AwsIotJobsResponse_t *const	pJobsResponse
	)

Wait for a Jobs operation to complete.

This function blocks to wait for a GET PENDING, START NEXT, DESCRIBE, or UPDATE operation to complete. These operations are by default asynchronous; the function calls queue an operation for processing, and a callback is invoked once the operation is complete.

To use this function, the flag AWS_IOT_JOBS_FLAG_WAITABLE must have been set in the operation's function call. Additionally, this function must always be called with any waitable operation to clean up resources.

Regardless of its return value, this function always clean up resources used by the waitable operation. This means operation is invalidated as soon as this function returns, even if it returns AWS_IOT_JOBS_TIMEOUT or another error.

Parameters

[in]	operation	Reference to the Jobs operation to wait for. The flag AWS_IOT_JOBS_FLAG_WAITABLE must have been set for this operation.
[in]	timeoutMs	How long to wait before returning AWS_IOT_JOBS_TIMEOUT.
[out]	pJobsResponse	The response received from the Jobs service.

Returns

One of the following:

AWS_IOT_JOBS_SUCCESS
AWS_IOT_JOBS_NOT_INITIALIZED
AWS_IOT_JOBS_BAD_PARAMETER
AWS_IOT_JOBS_BAD_RESPONSE
AWS_IOT_JOBS_TIMEOUT
A Jobs failure reason between AWS_IOT_JOBS_INVALID_TOPIC and AWS_IOT_JOBS_TERMINAL_STATE.

Example:

#define THING_NAME "Test_device"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )
AwsIotJobsOperation_t updateOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER;
AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER;
AwsIotJobsUpdateInfo_t updateInfo = AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER;
AwsIotJobsResponse_t jobsResponse = AWS_IOT_JOBS_RESPONSE_INITIALIZER;
// Set the request info.
requestInfo.mqttConnection = _mqttConnection;
requestInfo.pThingName = THING_NAME;
requestInfo.thingNameLength = THING_NAME_LENGTH;
// Set the function used to allocate memory for an incoming response.
requestInfo.mallocResponse = malloc;
// A Job ID must be set. AWS_IOT_JOBS_NEXT_JOB is not valid for UPDATE.
requestInfo.pJobId = "job-id";
requestInfo.jobIdLength = 6;
// Set the update info.
updateInfo.newStatus = AWS_IOT_JOB_STATE_SUCCEEDED;
// Queue Jobs UPDATE.
AwsIotJobsError_t updateResult = AwsIotJobs_UpdateAsync( &requestInfo,
                                                         &updateInfo,
                                                         AWS_IOT_JOBS_FLAG_WAITABLE,
                                                         NULL,
                                                         &updateOperation );
// UPDATE should have returned AWS_IOT_JOBS_STATUS_PENDING. The call to wait
// returns once the result of the UPDATE is available or the timeout expires.
if( updateResult == AWS_IOT_JOBS_STATUS_PENDING )
{
    updateResult = AwsIotJobs_Wait( updateOperation, 5000, &jobsResponse );
    if( updateResult == AWS_IOT_JOBS_SUCCESS )
    {
        // Jobs operation succeeded. Do something with the Jobs response.
        // Once the Jobs response is no longer needed, free it.
        free( jobsResponse.pJobsResponse );
    }
    else
    {
        // Jobs operation failed.
    }
}

◆ AwsIotJobs_SetNotifyPendingCallback()

AwsIotJobsError_t AwsIotJobs_SetNotifyPendingCallback	(	IotMqttConnection_t	mqttConnection,
		const char *	pThingName,
		size_t	thingNameLength,
		uint32_t	flags,
		const AwsIotJobsCallbackInfo_t *	pNotifyPendingCallback
	)

Set a callback to be invoked when the list of pending Jobs changes.

The Jobs service publishes a JobExecutionsChanged message to the jobs/notify topic whenever a Job execution is added to or removed from the list of pending Job executions for a Thing. The message sent is useful for monitoring the list of pending Job executions.

A NOTIFY PENDING callback may be invoked whenever a message is published to jobs/notify. Each Thing may have up to AWS_IOT_JOBS_NOTIFY_CALLBACKS NOTIFY PENDING callbacks set. This function modifies the NOTIFY PENDING callback for a specific Thing depending on the pNotifyPendingCallback parameter and the presence of any existing NOTIFY PENDING callback.

When no existing NOTIFY PENDING callback exists for a specific Thing, a new callback is added.
If there is an existing NOTIFY PENDING callback and pNotifyPendingCallback is not NULL, then the existing callback function and parameter are replaced with pNotifyPendingCallback.
If there is an existing NOTIFY PENDING callback and pNotifyPendingCallback is NULL, then the callback is removed.

The member AwsIotJobsCallbackInfo_t::oldFunction must be used to select an already-registered callback function for replacement or removal when AWS_IOT_JOBS_NOTIFY_CALLBACKS is greater than 1. When multiple callbacks are set, all of them will be invoked when a message is received.

Parameters

[in]	mqttConnection	The MQTT connection to use for the subscription to `jobs/notify`.
[in]	pThingName	The subscription to `jobs/notify` will be added for this Thing Name.
[in]	thingNameLength	The length of `pThingName`.
[in]	flags	This parameter is for future-compatibility. Currently, flags are not supported for this function and this parameter is ignored.
[in]	pNotifyPendingCallback	Callback function to invoke for incoming messages.

Returns

One of the following:

See also: AwsIotJobs_SetNotifyNextCallback for the function to register callbacks for next Job changes.

Example:

#define THING_NAME "Test_device"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )
AwsIotJobsError_t result = AWS_IOT_JOBS_STATUS_PENDING;
AwsIotJobsCallbackInfo_t notifyPendingCallback = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;
// _jobsCallback will be invoked when any messages are received.
notifyPendingCallback.function = _jobsCallback;
// Set the NOTIFY PENDING callback for the Thing "Test_device".
result = AwsIotJobs_SetNotifyPendingCallback( mqttConnection,
                                              THING_NAME,
                                              THING_NAME_LENGTH,
                                              0,
                                              &notifyPendingCallback );
// Check if the callback was successfully set.
if( status == AWS_IOT_JOBS_SUCCESS )
{
    // The callback will now be invoked whenever the list of pending Job
    // executions changes.
    // Once the callback is no longer needed, it may be removed by passing
    // NULL as the callback function and specifying the function to remove.
    notifyPendingCallback.function = NULL;
    notifyPendingCallback.oldFunction = _jobsCallback;
    status = AwsIotJobs_SetNotifyPendingCallback( mqttConnection,
                                                  THING_NAME,
                                                  THING_NAME_LENGTH,
                                                  0,
                                                  &notifyPendingCallback );
    // The return value from removing a callback should always be success.
    assert( status == AWS_IOT_JOBS_SUCCESS );
}

◆ AwsIotJobs_SetNotifyNextCallback()

AwsIotJobsError_t AwsIotJobs_SetNotifyNextCallback	(	IotMqttConnection_t	mqttConnection,
		const char *	pThingName,
		size_t	thingNameLength,
		uint32_t	flags,
		const AwsIotJobsCallbackInfo_t *	pNotifyNextCallback
	)

Set a callback to be invoked when the next pending Job changes.

The Jobs service publishes a NextJobExecutionChanged message to the jobs/notify-next topic whenever the next Job execution in the list of pending Job executions changes for a Thing. The message sent is useful for being notified of changes to the next Job.

A NOTIFY NEXT callback may be invoked whenever a message is published to jobs/notify-next. Each Thing may have up to AWS_IOT_JOBS_NOTIFY_CALLBACKS NOTIFY NEXT callbacks set. This function modifies the NOTIFY NEXT callback for a specific Thing depending on the pNotifyNextCallback parameter and the presence of any existing NOTIFY NEXT callback.

When no existing NOTIFY NEXT callback exists for a specific Thing, a new callback is added.
If there is an existing NOTIFY NEXT callback and pNotifyNextCallback is not NULL, then the existing callback function and parameter are replaced with pNotifyNextCallback.
If there is an existing NOTIFY NEXT callback and pNotifyNextCallback is NULL, then the callback is removed.

The member AwsIotJobsCallbackInfo_t::oldFunction must be used to select an already-registered callback function for replacement or removal when AWS_IOT_JOBS_NOTIFY_CALLBACKS is greater than 1. When multiple callbacks are set, all of them will be invoked when a message is received.

Parameters

[in]	mqttConnection	The MQTT connection to use for the subscription to `jobs/notify-next`.
[in]	pThingName	The subscription to `jobs/notify-next` will be added for this Thing Name.
[in]	thingNameLength	The length of `pThingName`.
[in]	flags	This parameter is for future-compatibility. Currently, flags are not supported for this function and this parameter is ignored.
[in]	pNotifyNextCallback	Callback function to invoke for incoming messages.

Returns

One of the following:

See also: AwsIotJobs_SetNotifyPendingCallback for the function to register callbacks for all pending Job changes.

Example:

#define THING_NAME "Test_device"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )
AwsIotJobsError_t result = AWS_IOT_JOBS_STATUS_PENDING;
AwsIotJobsCallbackInfo_t notifyNextCallback = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;
// _jobsCallback will be invoked when any messages are received.
notifyNextCallback.function = _jobsCallback;
// Set the NOTIFY NEXT callback for the Thing "Test_device".
result = AwsIotJobs_SetNotifyNextCallback( mqttConnection,
                                           THING_NAME,
                                           THING_NAME_LENGTH,
                                           0,
                                           &notifyNextCallback );
// Check if the callback was successfully set.
if( status == AWS_IOT_JOBS_SUCCESS )
{
    // The callback will now be invoked whenever the next pending Job
    // execution changes.
    // Once the callback is no longer needed, it may be removed by passing
    // NULL as the callback function and specifying the function to remove.
    notifyNextCallback.function = NULL;
    notifyNextCallback.oldFunction = _jobsCallback;
    status = AwsIotJobs_SetNotifyNextCallback( mqttConnection,
                                               THING_NAME,
                                               THING_NAME_LENGTH,
                                               0,
                                               &notifyNextCallback );
    // The return value from removing a callback should always be success.
    assert( status == AWS_IOT_JOBS_SUCCESS );
}

◆ AwsIotJobs_RemovePersistentSubscriptions()

AwsIotJobsError_t AwsIotJobs_RemovePersistentSubscriptions	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		uint32_t	flags
	)

Remove persistent Jobs operation topic subscriptions.

Passing the flag AWS_IOT_JOBS_FLAG_KEEP_SUBSCRIPTIONS to AwsIotJobs_GetPendingAsync, AwsIotJobs_StartNextAsync, AwsIotJobs_DescribeAsync, AwsIotJobs_UpdateAsync, or their blocking versions causes the Jobs operation topic subscriptions to be maintained for future calls to the same function. If a persistent subscription for a Jobs topic are no longer needed, this function may be used to remove it.

Parameters

[in]	pRequestInfo	Jobs request info. Only the pThingName, thingNameLength, and mqttConnection members need to be set for this function.
[in]	flags	Flags that determine which subscriptions to remove. Valid values are the bitwise OR of the following individual flags: AWS_IOT_JOBS_FLAG_REMOVE_GET_PENDING_SUBSCRIPTIONS AWS_IOT_JOBS_FLAG_REMOVE_START_NEXT_SUBSCRIPTIONS AWS_IOT_JOBS_FLAG_REMOVE_DESCRIBE_SUBSCRIPTIONS AWS_IOT_JOBS_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS

Returns

On success:

AWS_IOT_JOBS_SUCCESS

If an MQTT UNSUBSCRIBE packet cannot be sent, one of the following:

Note: AwsIotJobs_Cleanup removes persistent sessions as well.

Warning: This function is not safe to call with any in-progress operations! It also does not affect NOTIFY PENDING and NOTIFY NEXT callbacks registered with AwsIotJobs_SetNotifyPendingCallback and AwsIotJobs_SetNotifyNextCallback, respectively. (See documentation for those functions on how to remove their callbacks).

◆ AwsIotJobs_strerror()

const char* AwsIotJobs_strerror ( AwsIotJobsError_t status )

Returns a string that describes an AwsIotJobsError_t.

Like POSIX's strerror, this function returns a string describing a return code. In this case, the return code is a Jobs library error code, status.

The string returned by this function MUST be treated as read-only: any attempt to modify its contents may result in a crash. Therefore, this function is limited to usage in logging.

Parameters

[in] status The status to describe.

Returns: A read-only string that describes status.

Warning: The string returned by this function must never be modified.

◆ AwsIotJobs_StateName()

const char* AwsIotJobs_StateName ( AwsIotJobState_t state )

Returns a string that describes an AwsIotJobState_t.

This function returns a string describing a Job state, state.

The string returned by this function MUST be treated as read-only: any attempt to modify its contents may result in a crash. Therefore, this function is limited to usage in logging.

Parameters

[in] state The job state to describe.

Returns: A read-only string that describes state.

Warning: The string returned by this function must never be modified.

Functions

Detailed Description

Function Documentation

◆ AwsIotJobs_Init()

◆ AwsIotJobs_Cleanup()

◆ AwsIotJobs_GetPendingAsync()

◆ AwsIotJobs_GetPendingSync()

◆ AwsIotJobs_StartNextAsync()

◆ AwsIotJobs_StartNextSync()

◆ AwsIotJobs_DescribeAsync()

◆ AwsIotJobs_DescribeSync()

◆ AwsIotJobs_UpdateAsync()

◆ AwsIotJobs_UpdateSync()

◆ AwsIotJobs_Wait()

◆ AwsIotJobs_SetNotifyPendingCallback()

◆ AwsIotJobs_SetNotifyNextCallback()

◆ AwsIotJobs_RemovePersistentSubscriptions()

◆ AwsIotJobs_strerror()

◆ AwsIotJobs_StateName()