Client library APIs for the AWS IoT Jobs service. More...

#include <stddef.h>
#include <stdint.h>

Macros
#define	JOBS_THINGNAME_MAX_LENGTH 128U /* per AWS IoT API Reference */
	Maximum length of a thing name for the AWS IoT Jobs Service.

#define	JOBS_JOBID_MAX_LENGTH 64U /* per AWS IoT API Reference */
	Maximum length of a job ID for the AWS IoT Jobs Service.

#define	THINGNAME_MAX_LENGTH JOBS_THINGNAME_MAX_LENGTH
	User defined maximum length of a thing name for the application. More...

#define	JOBID_MAX_LENGTH JOBS_JOBID_MAX_LENGTH
	User defined maximum length of a job ID for the application. More...

#define	JOBS_API_MAX_LENGTH(thingNameLength)
	The size needed to hold the longest topic for a given thing name length. More...

Enumerations
enum	JobsStatus_t { JobsError = 0, JobsSuccess, JobsNoMatch, JobsBadParameter, JobsBufferTooSmall }
	Return codes from jobs functions. More...

enum	JobsTopic_t { JobsInvalidTopic = -1, JobsJobsChanged, JobsNextJobChanged, JobsGetPendingSuccess, JobsGetPendingFailed, JobsStartNextSuccess, JobsStartNextFailed, JobsDescribeSuccess, JobsDescribeFailed, JobsUpdateSuccess, JobsUpdateFailed, JobsMaxTopic }
	Topic values for subscription requests. More...

Functions
JobsStatus_t	Jobs_GetTopic (char buffer, size_t length, const char thingName, uint16_t thingNameLength, JobsTopic_t api, size_t *outLength)
	Populate a topic string for a subscription request. More...

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. More...

JobsStatus_t	Jobs_GetPending (char buffer, size_t length, const char thingName, uint16_t thingNameLength, size_t *outLength)
	Populate a topic string for a GetPendingJobExecutions request. More...

JobsStatus_t	Jobs_StartNext (char buffer, size_t length, const char thingName, uint16_t thingNameLength, size_t *outLength)
	Populate a topic string for a StartNextPendingJobExecution request. More...

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. More...

JobsStatus_t	Jobs_Update (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 an UpdateJobExecution request. More...

Detailed Description

Client library APIs for the AWS IoT Jobs service.

https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#jobs-mqtt-api

Macro Definition Documentation

◆ THINGNAME_MAX_LENGTH

#define THINGNAME_MAX_LENGTH JOBS_THINGNAME_MAX_LENGTH

User defined maximum length of a thing name for the application.

Default value: JOBS_THINGNAME_MAX_LENGTH

◆ JOBID_MAX_LENGTH

#define JOBID_MAX_LENGTH JOBS_JOBID_MAX_LENGTH

User defined maximum length of a job ID for the application.

Default value: JOBS_JOBID_MAX_LENGTH

Function Documentation

◆ Jobs_GetTopic()

JobsStatus_t Jobs_GetTopic	(	char *	buffer,
		size_t	length,
		const char *	thingName,
		uint16_t	thingNameLength,
		JobsTopic_t	api,
		size_t *	outLength
	)

Populate a topic string for a subscription 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.
[in]	api	The desired Jobs API, e.g., JobsNextJobChanged.
[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: The thingName parameter does not need a NULL terminator.

See jobs.h for docs.

◆ 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 NULL 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.

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.

◆ Jobs_GetPending()

JobsStatus_t Jobs_GetPending	(	char *	buffer,
		size_t	length,
		const char *	thingName,
		uint16_t	thingNameLength,
		size_t *	outLength
	)

Populate a topic string for a GetPendingJobExecutions 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]	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: The thingName parameter does not need a NULL terminator.

See jobs.h for docs.

◆ Jobs_StartNext()

JobsStatus_t Jobs_StartNext	(	char *	buffer,
		size_t	length,
		const char *	thingName,
		uint16_t	thingNameLength,
		size_t *	outLength
	)

Populate a topic string for a StartNextPendingJobExecution 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]	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: The thingName parameter does not need a NULL terminator.

See jobs.h for docs.

◆ Jobs_Describe()

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: The thingName and jobId parameters do not need a NULL terminator.

See jobs.h for docs.

◆ Jobs_Update()

JobsStatus_t Jobs_Update	(	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 an UpdateJobExecution 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: The thingName and jobId parameters do not need a NULL terminator.

See jobs.h for docs.

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ THINGNAME_MAX_LENGTH

◆ JOBID_MAX_LENGTH

Function Documentation

◆ Jobs_GetTopic()

◆ Jobs_MatchTopic()

◆ Jobs_GetPending()

◆ Jobs_StartNext()

◆ Jobs_Describe()

◆ Jobs_Update()