AwsIotJobs_StartNextAsync

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

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

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:

• 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_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.