AwsIotJobs_UpdateAsync

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

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

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:

• AWS_IOT_JOBS_NOT_INITIALIZED
• AWS_IOT_JOBS_BAD_PARAMETER
• AWS_IOT_JOBS_NO_MEMORY

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.