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.

Parameters

[in]	buffer	The buffer to contain the topic string.
[in]	length	The size of the buffer.
[in]	thingName	The device's thingName as registered with AWS IoT.
[in]	thingNameLength	The length of the thingName.
[out]	jobId	The ID of the job to describe.
[out]	jobIdLength	The length of the job ID.
[out]	outLength	The length of the topic string written to the buffer.

Returns: JobsSuccess if the topic was written to the buffer; JobsBadParameter if invalid parameters are passed; JobsBufferTooSmall if the buffer cannot hold the full topic string.

When all parameters are valid, the topic string is written to the buffer up to one less than the buffer size. The topic is ended with a NUL character.

Note: A jobId consisting of the string, "$next", is supported to generate a topic string to request the next pending job.; The thingName and jobId parameters do not need a NUL terminator.; The AWS IoT Jobs service does not require clients to subscribe to the "/accepted" and "/rejected" response topics of the DescribeJobExecution API. The Jobs service will send responses to requests published to the API from clients irrespective of whether they have subscribed to response topics or not. For more information, refer to the AWS docs here: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-mqtt-api.html

Example

// The following example shows usage of the Jobs_Describe API to
// generate topic string for the DescribeJobExecution API
// of the AWS IoT Jobs service.
 
// Every device should have a unique thing name registered with AWS IoT Core.
// This example uses a dummy serial number for the thing name.
#define THING_NAME           "11223445566"
#define THING_NAME_LENGTH    ( sizeof( THING_NAME ) - 1U )
 
// The job ID is required to send a status update for a job to the AWS IoT
// Jobs service.
#define JOB_ID               "My_Job"
#define JOB_ID_LENGTH        ( sizeof( JOB_ID ) - 1U )
 
// This example allocates a buffer of maximum length for a Jobs topic
// possible for the thing name using the JOBS_API_MAX_LENGTH macro.
char topicBuffer[ JOBS_API_MAX_LENGTH( THING_NAME_LENGTH ) ] = { 0 };
uint16_t topicLength = 0U;
JobsStatus_t status = JobsSuccess;
status = Jobs_Describe( topicBuffer,
                        sizeof( topicBuffer ),
                        THING_NAME,
                        THING_NAME_LENGTH,
                        JOB_ID,
                        JOB_ID_LENGTH,
                        &( topicLength ) );
 
if( status == JobsSuccess )
{
    // The topic string of length, topicLength, has been generated in
    // the buffer, topicBuffer, for the DescribeJobExecution API.
    // Publish to this topic using an MQTT client of your choice.
}

See jobs.h for docs.