Jobs_MatchTopic

JobsStatus_t Jobs_MatchTopic( char * topic,
                              size_t length,
                              const char * thingName,
                              uint16_t thingNameLength,
                              JobsTopic_t * outApi,
                              char ** outJobId,
                              uint16_t * outJobIdLength );

Output a topic value if a Jobs API topic string is present. Optionally, output a pointer to a jobID within the topic and its length.

Parameters

[in]	topic	The topic string to check.
[in]	length	The length of the topic string.
[in]	thingName	The device's thingName as registered with AWS IoT.
[in]	thingNameLength	The length of the thingName.
[out]	outApi	The jobs topic API value if present, e.g., JobsUpdateSuccess.
[out]	outJobId	The beginning of the jobID in the topic string.
[out]	outJobIdLength	The length of the jobID in the topic string.

Returns

JobsSuccess if a matching topic was found; JobsNoMatch if a matching topic was NOT found (parameter outApi gets JobsInvalidTopic ); JobsBadParameter if invalid parameters are passed.

Note

The topic and thingName parameters do not need a NUL terminator.

Not all Jobs APIs have jobIDs within the topic string. NULL and 0 are output when no jobID is present. The parameters jobId and jobIdLength may be NULL.

Example

// The following example shows how to use the Jobs_MatchTopic API to
// check if an incoming MQTT publish message is from the AWS IoT Jobs
// service.
 
// Assuming that these variables contain incoming topic data received
// from the MQTT client used.
char * pIncomingTopic;
size_t topicLength;
 
// Every device should have a unique thing name registered with AWS IoT Core.
// This example uses a dummy serial number for the thing name.
// The Jobs_MatchTopic API will check that the incoming message topic contains
// this thing name.
#define THING_NAME           "11223445566"
#define THING_NAME_LENGTH    ( sizeof( THING_NAME ) - 1U )
 
JobsTopic_t api;
char * pJobId = NULL;
uint16_t jobIdLength;
JobsStatus_t status = JobsSuccess;
 
status = Jobs_MatchTopic( pIncomingTopic,
                          topicLength,
                          THING_NAME,
                          THING_NAME_LENGTH,
                          &api,
                          &pJobId,
                          &jobIdLength );
 
if( status == JobsSuccess )
{
    // The Jobs_MatchTopic API has determined that the incoming topic is from
    // AWS IoT Jobs service for the expected thing name.
    // If the topic contains a jobID, then the pJobId and jobIdLength parameters
    // populated by the API.
 
    if( api == JobsJobsChanged )
    { // Message from JobExecutionsChanged API.
    }
 
    else if( api == JobsNextJobChanged )
    { // Message from NextJobExecutionChanged API.
    }
 
    else if( api == JobsGetPendingSuccess )
    { // Received accepted response for request to GetPendingJobExecutions API.
    }
 
    else if( api == JobsGetPendingFailed )
    { // Received rejected response for request to GetPendingJobExecutions API.
    }
 
    else if( api == JobsStartNextSuccess )
    { // Received accepted response for request to StartNextPendingJobExecution API.
    }
 
    else if( api == JobsStartNextFailed )
    { // Received rejected response for request to StartNextPendingJobExecution API.
    }
 
    else if( api == JobsDescribeSuccess )
    { // Received accepted response for request to DescribeJobExecution API.
    }
 
    else if( api == JobsDescribeFailed )
    { // Received rejected response for request to DescribeJobExecution API.
    }
 
    else if( api == JobsUpdateSuccess )
    { // Received accepted response for request to UpdateJobExecution API.
    }
 
    else if( api == JobsUpdateFailed )
    { // Received rejected response for request to UpdateJobExecution API.
    }
    else
    {
        // Unexpected response.
    }
}

Output a topic value if a Jobs API topic string is present. Optionally, output a pointer to a jobID within the topic and its length.

See jobs.h for docs.