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

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

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.