Internal header of Jobs library. This header should not be included in typical application code. More...

#include "iot_config.h"
#include "iot_linear_containers.h"
#include "aws_iot_jobs.h"
#include "aws_iot.h"
#include "iot_logging_setup.h"
#include "iot_static_memory.h"

Go to the source code of this file.

Data Structures
union	_jsonRequestContents_t
	Parameter to _AwsIotJobs_GenerateJsonRequest. More...

struct	_jobsSubscription_t
	Represents a Jobs subscriptions object. More...

struct	_jobsOperation_t
	Internal structure representing a single Jobs operation. More...

Macros
#define	AwsIotJobs_Assert(expression)
	Assertion macro for the Jobs library. More...

#define	AwsIotJobs_MallocString Iot_MallocMessageBuffer
	Allocate a buffer for a short string, used for topic names or client tokens. This function should have the same signature as malloc.

#define	AwsIotJobs_FreeString Iot_FreeMessageBuffer
	Free a string. This function should have the same signature as free.

#define	JOBS_OPERATION_COUNT ( 4 )
	The number of currently available Jobs operations. More...

#define	JOBS_CALLBACK_COUNT ( 2 )
	The number of currently available Jobs callbacks. More...

#define	JOBS_GET_PENDING_OPERATION_STRING "/jobs/get"
	The string representing a Jobs GET PENDING operation in a Jobs MQTT topic.

#define	JOBS_GET_PENDING_OPERATION_STRING_LENGTH ( ( uint16_t ) ( sizeof( JOBS_GET_PENDING_OPERATION_STRING ) - 1 ) )
	The length of JOBS_GET_PENDING_OPERATION_STRING.

#define	JOBS_START_NEXT_OPERATION_STRING "/jobs/start-next"
	The string representing a Jobs START NEXT operation in a Jobs MQTT topic.

#define	JOBS_START_NEXT_OPERATION_STRING_LENGTH ( ( uint16_t ) ( sizeof( JOBS_START_NEXT_OPERATION_STRING ) - 1 ) )
	The length of JOBS_START_NEXT_OPERATION_STRING.

#define	JOBS_DESCRIBE_OPERATION_STRING "/get"
	The string representing a Jobs DESCRIBE operation in a Jobs MQTT topic. More...

#define	JOBS_DESCRIBE_OPERATION_STRING_LENGTH ( ( uint16_t ) ( sizeof( JOBS_DESCRIBE_OPERATION_STRING ) - 1 ) )
	The length of JOBS_DESCRIBE_OPERATION_STRING.

#define	JOBS_UPDATE_OPERATION_STRING "/update"
	The string representing a Jobs UPDATE operation in a Jobs MQTT topic. More...

#define	JOBS_UPDATE_OPERATION_STRING_LENGTH ( ( uint16_t ) ( sizeof( JOBS_UPDATE_OPERATION_STRING ) - 1 ) )
	The length of JOBS_UPDATE_OPERATION_STRING. More...

#define	JOBS_NOTIFY_PENDING_CALLBACK_STRING "/jobs/notify"
	The string representing the Jobs MQTT topic for receiving notifications of pending Jobs.

#define	JOBS_NOTIFY_PENDING_CALLBACK_STRING_LENGTH ( ( uint16_t ) ( sizeof( JOBS_NOTIFY_PENDING_CALLBACK_STRING ) - 1 ) )
	The length of JOBS_NOTIFY_PENDING_CALLBACK_STRING.

#define	JOBS_NOTIFY_NEXT_CALLBACK_STRING "/jobs/notify-next"
	The string representing the Jobs MQTT topic for receiving notifications of the next pending Job.

#define	JOBS_NOTIFY_NEXT_CALLBACK_STRING_LENGTH ( ( uint16_t ) ( sizeof( JOBS_NOTIFY_NEXT_CALLBACK_STRING ) - 1 ) )
	The length of JOBS_NOTIFY_NEXT_CALLBACK_STRING.

#define	JOBS_MAX_ID_LENGTH ( 64 )
	The maximum length of a Job ID, per AWS IoT Service Limits. More...

#define	JOBS_MAX_TIMEOUT ( 10080 )
	The maximum value of the Jobs step timeout, per AWS IoT Service Limits. More...

#define	JOBS_MAX_STATUS_DETAILS_LENGTH ( 32768 )
	A limit on the maximum length of a Jobs status details, per AWS IoT Service Limits. More...

#define	JOBS_LONGEST_SUFFIX_LENGTH ( JOBS_MAX_ID_LENGTH + JOBS_UPDATE_OPERATION_STRING_LENGTH + 6 )
	The length of the longest Jobs topic suffix. More...

Enumerations
enum	_jobsOperationType_t { JOBS_GET_PENDING = 0, JOBS_START_NEXT = 1, JOBS_DESCRIBE = 2, JOBS_UPDATE = 3, SET_NOTIFY_PENDING_CALLBACK = 4, SET_NOTIFY_NEXT_CALLBACK = 5 }
	Enumerations representing each of the Jobs library's API functions. More...

enum	_jobsCallbackType_t { NOTIFY_PENDING_CALLBACK = 0, NOTIFY_NEXT_CALLBACK = 1 }
	Enumerations representing each of the Jobs callback functions. More...

Functions
void *	AwsIotJobs_MallocOperation (size_t size)
	Allocate a _jobsOperation_t. This function should have the same signature as malloc.

void	AwsIotJobs_FreeOperation (void *ptr)
	Free a _jobsOperation_t. This function should have the same signature as free.

void *	AwsIotJobs_MallocSubscription (size_t size)
	Allocate a _jobsSubscription_t. This function should have the same signature as malloc.

void	AwsIotJobs_FreeSubscription (void *ptr)
	Free a _jobsSubscription_t. This function should have the same signature as free.

AwsIotJobsError_t	_AwsIotJobs_CreateOperation (_jobsOperationType_t type, const AwsIotJobsRequestInfo_t pRequestInfo, const _jsonRequestContents_t pRequestContents, uint32_t flags, const AwsIotJobsCallbackInfo_t pCallbackInfo, _jobsOperation_t *pNewOperation)
	Create a record for a new in-progress Jobs operation. More...

void	_AwsIotJobs_DestroyOperation (void *pData)
	Free resources used to record a Jobs operation. This is called when the operation completes. More...

AwsIotJobsError_t	_AwsIotJobs_GenerateJobsTopic (_jobsOperationType_t type, const AwsIotJobsRequestInfo_t pRequestInfo, char pTopicBuffer, uint16_t pOperationTopicLength)
	Fill a buffer with a Jobs topic. More...

AwsIotJobsError_t	_AwsIotJobs_ProcessOperation (const AwsIotJobsRequestInfo_t pRequestInfo, _jobsOperation_t pOperation)
	Process a Jobs operation by sending the necessary MQTT packets. More...

_jobsSubscription_t *	_AwsIotJobs_FindSubscription (const char *pThingName, size_t thingNameLength, bool createIfNotFound)
	Find a Jobs subscription object. May create a new subscription object and adds it to the subscription list if not found. More...

void	_AwsIotJobs_RemoveSubscription (_jobsSubscription_t pSubscription, _jobsSubscription_t *pRemovedSubscription)
	Remove a Jobs subscription object from the subscription list if unreferenced. More...

void	_AwsIotJobs_DestroySubscription (void *pData)
	Free resources used for a Jobs subscription object. More...

AwsIotJobsError_t	_AwsIotJobs_IncrementReferences (_jobsOperation_t pOperation, char pTopicBuffer, uint16_t operationTopicLength, AwsIotMqttCallbackFunction_t callback)
	Increment the reference count of a Jobs subscriptions object. More...

void	_AwsIotJobs_DecrementReferences (_jobsOperation_t pOperation, char pTopicBuffer, _jobsSubscription_t **pRemovedSubscription)
	Decrement the reference count of a Jobs subscriptions object. More...

AwsIotJobsError_t	_AwsIotJobs_GenerateJsonRequest (_jobsOperationType_t type, const AwsIotJobsRequestInfo_t pRequestInfo, const _jsonRequestContents_t pRequestContents, _jobsOperation_t *pOperation)
	Generates a Jobs JSON request document from an AwsIotJobsRequestInfo_t and an AwsIotJobsUpdateInfo_t. More...

void	_AwsIotJobs_ParseResponse (AwsIotStatus_t status, const char pResponse, size_t responseLength, _jobsOperation_t pOperation)
	Parse a response received from the Jobs service. More...

Variables
uint32_t	_AwsIotJobsMqttTimeoutMs
	Timeout used for MQTT operations.

IotListDouble_t	_AwsIotJobsPendingOperations
	List of active Jobs operations awaiting a response from the Jobs service.

IotListDouble_t	_AwsIotJobsSubscriptions
	List of active Jobs subscriptions objects.

IotMutex_t	_AwsIotJobsPendingOperationsMutex
	Protects _AwsIotJobsPendingOperations from concurrent access.

IotMutex_t	_AwsIotJobsSubscriptionsMutex
	Protects _AwsIotJobsSubscriptions from concurrent access.

Detailed Description

Internal header of Jobs library. This header should not be included in typical application code.

Macro Definition Documentation

◆ AwsIotJobs_Assert

#define AwsIotJobs_Assert ( expression )

Assertion macro for the Jobs library.

Set AWS_IOT_JOBS_ENABLE_ASSERTS to 1 to enable assertions in the Jobs library.

Parameters

[in] expression Expression to be evaluated.

◆ JOBS_OPERATION_COUNT

#define JOBS_OPERATION_COUNT ( 4 )

The number of currently available Jobs operations.

The 4 Jobs operations are GET PENDING, START NEXT, DESCRIBE, and UPDATE.

◆ JOBS_CALLBACK_COUNT

#define JOBS_CALLBACK_COUNT ( 2 )

The number of currently available Jobs callbacks.

The 2 Jobs callbacks are jobs/notify (AKA "Notify Pending") and /jobs/notify-next (AKA "Notify Next").

◆ JOBS_DESCRIBE_OPERATION_STRING

#define JOBS_DESCRIBE_OPERATION_STRING "/get"

The string representing a Jobs DESCRIBE operation in a Jobs MQTT topic.

This string should be placed after a Job ID.

◆ JOBS_UPDATE_OPERATION_STRING

#define JOBS_UPDATE_OPERATION_STRING "/update"

The string representing a Jobs UPDATE operation in a Jobs MQTT topic.

This string should be placed after a Job ID.

◆ JOBS_UPDATE_OPERATION_STRING_LENGTH

#define JOBS_UPDATE_OPERATION_STRING_LENGTH ( ( uint16_t ) ( sizeof( JOBS_UPDATE_OPERATION_STRING ) - 1 ) )

The length of JOBS_UPDATE_OPERATION_STRING.

This length excludes the length of the placeholder s.

◆ JOBS_MAX_ID_LENGTH

#define JOBS_MAX_ID_LENGTH ( 64 )

The maximum length of a Job ID, per AWS IoT Service Limits.

See https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#job-limits

◆ JOBS_MAX_TIMEOUT

#define JOBS_MAX_TIMEOUT ( 10080 )

The maximum value of the Jobs step timeout, per AWS IoT Service Limits.

See https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#job-limits

◆ JOBS_MAX_STATUS_DETAILS_LENGTH

#define JOBS_MAX_STATUS_DETAILS_LENGTH ( 32768 )

A limit on the maximum length of a Jobs status details, per AWS IoT Service Limits.

See https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#job-limits

This is actually the limit on the length of an entire Jobs document; but the status details must also not exceed this length,

◆ JOBS_LONGEST_SUFFIX_LENGTH

#define JOBS_LONGEST_SUFFIX_LENGTH ( JOBS_MAX_ID_LENGTH + JOBS_UPDATE_OPERATION_STRING_LENGTH + 6 )

The length of the longest Jobs topic suffix.

This is the length of the longest Job ID, plus the length of the "UPDATE" operation suffix, plus the length of "/jobs/".

Enumeration Type Documentation

◆ _jobsOperationType_t

enum _jobsOperationType_t

Enumerations representing each of the Jobs library's API functions.

Enumerator
JOBS_GET_PENDING	AwsIotJobs_GetPendingAsync
JOBS_START_NEXT	AwsIotJobs_StartNextAsync
JOBS_DESCRIBE	AwsIotJobs_DescribeAsync
JOBS_UPDATE	AwsIotJobs_UpdateAsync
SET_NOTIFY_PENDING_CALLBACK	AwsIotJobs_SetNotifyPendingCallback
SET_NOTIFY_NEXT_CALLBACK	AwsIotJobs_SetNotifyNextCallback

◆ _jobsCallbackType_t

enum _jobsCallbackType_t

Enumerations representing each of the Jobs callback functions.

Enumerator
NOTIFY_PENDING_CALLBACK	Pending Job notification callback.
NOTIFY_NEXT_CALLBACK	Next Job notification callback.

Function Documentation

◆ _AwsIotJobs_CreateOperation()

AwsIotJobsError_t _AwsIotJobs_CreateOperation	(	_jobsOperationType_t	type,
		const AwsIotJobsRequestInfo_t *	pRequestInfo,
		const _jsonRequestContents_t *	pRequestContents,
		uint32_t	flags,
		const AwsIotJobsCallbackInfo_t *	pCallbackInfo,
		_jobsOperation_t **	pNewOperation
	)

Create a record for a new in-progress Jobs operation.

Parameters

[in]	type	The type of Jobs operation for the request.
[in]	pRequestInfo	Common Jobs request parameters.
[in]	pRequestContents	Additional values to place in the JSON document, depending on `type`.
[in]	flags	Flags variables passed to a user-facing Jobs function.
[in]	pCallbackInfo	User-provided callback function and parameter.
[out]	pNewOperation	Set to point to the new operation on success.

Returns: AWS_IOT_JOBS_SUCCESS or AWS_IOT_JOBS_NO_MEMORY

◆ _AwsIotJobs_DestroyOperation()

void _AwsIotJobs_DestroyOperation ( void * pData )

Free resources used to record a Jobs operation. This is called when the operation completes.

Parameters

[in] pData The operation which completed. This parameter is of type void* to match the signature of free.

◆ _AwsIotJobs_GenerateJobsTopic()

AwsIotJobsError_t _AwsIotJobs_GenerateJobsTopic	(	_jobsOperationType_t	type,
		const AwsIotJobsRequestInfo_t *	pRequestInfo,
		char **	pTopicBuffer,
		uint16_t *	pOperationTopicLength
	)

Fill a buffer with a Jobs topic.

Parameters

[in]	type	One of: GET PENDING, START NEXT, DESCRIBE, or UPDATE.
[in]	pRequestInfo	Common Jobs request parameters.
[out]	pTopicBuffer	Address of the buffer for the Jobs topic. If the pointer at this address is `NULL`, this function will allocate a new buffer; otherwise, it will use the provided buffer.
[out]	pOperationTopicLength	Length of the Jobs operation topic (excluding any suffix) placed in `pTopicBuffer`.

Warning: This function does not check the length of pTopicBuffer! Any provided buffer must be large enough to accommodate the full Jobs topic, plus JOBS_LONGEST_SUFFIX_LENGTH.

Returns: AWS_IOT_JOBS_SUCCESS or AWS_IOT_JOBS_NO_MEMORY. This function will not return AWS_IOT_JOBS_NO_MEMORY when a buffer is provided.

◆ _AwsIotJobs_ProcessOperation()

AwsIotJobsError_t _AwsIotJobs_ProcessOperation	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		_jobsOperation_t *	pOperation
	)

Process a Jobs operation by sending the necessary MQTT packets.

Parameters

[in]	pRequestInfo	Common Jobs request parameters.
[in]	pOperation	Operation data to process.

Returns: AWS_IOT_JOBS_STATUS_PENDING on success. On error, one of AWS_IOT_JOBS_NO_MEMORY or AWS_IOT_JOBS_MQTT_ERROR.

◆ _AwsIotJobs_FindSubscription()

_jobsSubscription_t* _AwsIotJobs_FindSubscription	(	const char *	pThingName,
		size_t	thingNameLength,
		bool	createIfNotFound
	)

Find a Jobs subscription object. May create a new subscription object and adds it to the subscription list if not found.

Parameters

[in]	pThingName	Thing Name in the subscription object.
[in]	thingNameLength	Length of `pThingName`.
[in]	createIfNotFound	If `true`, attempt to create a new subscription object if no match is found.

Returns: Pointer to a Jobs subscription object, either found or newly allocated. Returns NULL if no subscription object is found and a new subscription object could not be allocated.

Note: This function should be called with the subscription list mutex locked.

◆ _AwsIotJobs_RemoveSubscription()

void _AwsIotJobs_RemoveSubscription	(	_jobsSubscription_t *	pSubscription,
		_jobsSubscription_t **	pRemovedSubscription
	)

Remove a Jobs subscription object from the subscription list if unreferenced.

Parameters

[in]	pSubscription	Subscription object to check. If this object has no active references, it is removed from the subscription list.
[out]	pRemovedSubscription	Removed subscription object, if any. Optional; pass `NULL` to ignore. If not `NULL`, this parameter will be set to the removed subscription and that subscription will not be destroyed.

Note: This function should be called with the subscription list mutex locked.

◆ _AwsIotJobs_DestroySubscription()

void _AwsIotJobs_DestroySubscription ( void * pData )

Free resources used for a Jobs subscription object.

Parameters

[in] pData The subscription object to destroy. This parameter is of type void* to match the signature of free.

◆ _AwsIotJobs_IncrementReferences()

AwsIotJobsError_t _AwsIotJobs_IncrementReferences	(	_jobsOperation_t *	pOperation,
		char *	pTopicBuffer,
		uint16_t	operationTopicLength,
		AwsIotMqttCallbackFunction_t	callback
	)

Increment the reference count of a Jobs subscriptions object.

Also adds MQTT subscriptions if necessary.

Parameters

[in]	pOperation	The operation for which the reference count should be incremented.
[in]	pTopicBuffer	Topic buffer containing the operation topic, used if subscriptions need to be added.
[in]	operationTopicLength	The length of the operation topic in `pTopicBuffer`.
[in]	callback	MQTT callback function for when this operation completes.

Warning: This function does not check the length of pTopicBuffer! Any provided buffer must already contain the Jobs operation topic, plus enough space for the status suffix.

Returns: AWS_IOT_JOBS_SUCCESS on success. On error, one of AWS_IOT_JOBS_NO_MEMORY or AWS_IOT_JOBS_MQTT_ERROR.

Note: This function should be called with the subscription list mutex locked.

◆ _AwsIotJobs_DecrementReferences()

void _AwsIotJobs_DecrementReferences	(	_jobsOperation_t *	pOperation,
		char *	pTopicBuffer,
		_jobsSubscription_t **	pRemovedSubscription
	)

Decrement the reference count of a Jobs subscriptions object.

Also removed MQTT subscriptions and deletes the subscription object if necessary.

Parameters

[in]	pOperation	The operation for which the reference count should be decremented.
[in]	pTopicBuffer	Topic buffer containing the operation topic, used if subscriptions need to be removed.
[out]	pRemovedSubscription	Set to point to a removed subscription. Optional; pass `NULL` to ignore. If not `NULL`, this function will not destroy a removed subscription.

Warning: This function does not check the length of pTopicBuffer! Any provided buffer must be large enough to accommodate the full Jobs topic, plus JOBS_LONGEST_SUFFIX_LENGTH.

Note: This function should be called with the subscription list mutex locked.

◆ _AwsIotJobs_GenerateJsonRequest()

AwsIotJobsError_t _AwsIotJobs_GenerateJsonRequest	(	_jobsOperationType_t	type,
		const AwsIotJobsRequestInfo_t *	pRequestInfo,
		const _jsonRequestContents_t *	pRequestContents,
		_jobsOperation_t *	pOperation
	)

Generates a Jobs JSON request document from an AwsIotJobsRequestInfo_t and an AwsIotJobsUpdateInfo_t.

Parameters

[in]	type	The type of Jobs operation for the request.
[in]	pRequestInfo	Common Jobs request parameters.
[in]	pRequestContents	Additional values to place in the JSON document, depending on `type`.
[in]	pOperation	Operation associated with the Jobs request.

Returns: AWS_IOT_JOBS_SUCCESS on success; otherwise, AWS_IOT_JOBS_NO_MEMORY.

◆ _AwsIotJobs_ParseResponse()

void _AwsIotJobs_ParseResponse	(	AwsIotStatus_t	status,
		const char *	pResponse,
		size_t	responseLength,
		_jobsOperation_t *	pOperation
	)

Parse a response received from the Jobs service.

Parameters

[in]	status	Either ACCEPTED or REJECTED.
[in]	pResponse	The response received from the Jobs service.
[in]	responseLength	Length of `pResponse`.
[out]	pOperation	Associated Jobs operation, where parse results are written.

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ AwsIotJobs_Assert

◆ JOBS_OPERATION_COUNT

◆ JOBS_CALLBACK_COUNT

◆ JOBS_DESCRIBE_OPERATION_STRING

◆ JOBS_UPDATE_OPERATION_STRING

◆ JOBS_UPDATE_OPERATION_STRING_LENGTH

◆ JOBS_MAX_ID_LENGTH

◆ JOBS_MAX_TIMEOUT

◆ JOBS_MAX_STATUS_DETAILS_LENGTH

◆ JOBS_LONGEST_SUFFIX_LENGTH

Enumeration Type Documentation

◆ _jobsOperationType_t

◆ _jobsCallbackType_t

Function Documentation

◆ _AwsIotJobs_CreateOperation()

◆ _AwsIotJobs_DestroyOperation()

◆ _AwsIotJobs_GenerateJobsTopic()

◆ _AwsIotJobs_ProcessOperation()

◆ _AwsIotJobs_FindSubscription()

◆ _AwsIotJobs_RemoveSubscription()

◆ _AwsIotJobs_DestroySubscription()

◆ _AwsIotJobs_IncrementReferences()

◆ _AwsIotJobs_DecrementReferences()

◆ _AwsIotJobs_GenerateJsonRequest()

◆ _AwsIotJobs_ParseResponse()