Implements functions that generate and parse Jobs JSON documents. More...

#include "iot_config.h"
#include <stdio.h>
#include <string.h>
#include "private/aws_iot_jobs_internal.h"
#include "aws_iot_doc_parser.h"

Macros
#define	MINIMUM_REQUEST_LENGTH ( AWS_IOT_CLIENT_TOKEN_KEY_LENGTH + 7 )
	Minimum length of a Jobs request. More...

#define	CLIENT_TOKEN_AUTOGENERATE_LENGTH ( 8 )
	The length of client tokens generated by this library.

#define	STATUS_KEY "status"
	JSON key representing Jobs status.

#define	STATUS_KEY_LENGTH ( sizeof( STATUS_KEY ) - 1 )
	Length of STATUS_KEY.

#define	STATUS_DETAILS_KEY "statusDetails"
	JSON key representing Jobs status details.

#define	STATUS_DETAILS_KEY_LENGTH ( sizeof( STATUS_DETAILS_KEY ) - 1 )
	Length of STATUS_DETAILS_KEY.

#define	EXPECTED_VERSION_KEY "expectedVersion"
	JSON key representing Jobs expected version.

#define	EXPECTED_VERSION_KEY_LENGTH ( sizeof( EXPECTED_VERSION_KEY ) - 1 )
	Length of EXPECTED_VERSION_KEY.

#define	EXPECTED_VERSION_STRING_LENGTH ( 11 )
	Maximum length of the expected version when represented as a string. More...

#define	STEP_TIMEOUT_KEY "stepTimeoutInMinutes"
	JSON key representing Jobs step timeout.

#define	STEP_TIMEOUT_KEY_LENGTH ( sizeof( STEP_TIMEOUT_KEY ) - 1 )
	Length of STEP_TIMEOUT_KEY.

#define	STEP_TIMEOUT_STRING_LENGTH ( 6 )
	Maximum length of the step timeout when represented as a string. More...

#define	INCLUDE_JOB_DOCUMENT_KEY "includeJobDocument"
	JSON key representing the "include Job document" flag.

#define	INCLUDE_JOB_EXECUTION_STATE_KEY "includeJobExecutionState"
	JSON key representing the "include Job Execution state" flag.

#define	INCLUDE_JOB_EXECUTION_STATE_KEY_LENGTH ( sizeof( INCLUDE_JOB_EXECUTION_STATE_KEY ) - 1 )
	Length of INCLUDE_JOB_EXECUTION_STATE_KEY.

#define	INCLUDE_JOB_DOCUMENT_KEY_LENGTH ( sizeof( INCLUDE_JOB_DOCUMENT_KEY ) - 1 )
	Length of INCLUDE_JOB_DOCUMENT_KEY.

#define	EXECUTION_NUMBER_KEY "executionNumber"
	JSON key representing the Jobs execution number.

#define	EXECUTION_NUMBER_KEY_LENGTH ( sizeof( EXECUTION_NUMBER_KEY ) - 1 )
	Length of EXECUTION_NUMBER_KEY.

#define	EXECUTION_NUMBER_STRING_LENGTH ( 12 )
	Maximum length of the execution number when represented as a string. More...

#define	CODE_KEY "code"
	JSON key representing Jobs error code in error responses.

#define	CODE_KEY_LENGTH ( sizeof( CODE_KEY ) - 1 )
	Length of CODE_KEY.

#define	APPEND_STRING(pBuffer, copyOffset, pString, stringLength)
	Append a string to a buffer. More...

Functions
static size_t	_appendFlag (char pBuffer, size_t copyOffset, const char pFlagName, size_t flagNameLength, bool value)
	Place a JSON boolean flag in the given buffer. More...

static size_t	_appendStatusDetails (char pBuffer, size_t copyOffset, const char pStatusDetails, size_t statusDetailsLength)
	Place Job status details in the given buffer. More...

static size_t	_appendExecutionNumber (char pBuffer, size_t copyOffset, const char pExecutionNumber, size_t executionNumberLength)
	Place Job execution number in the given buffer. More...

static size_t	_appendStepTimeout (char pBuffer, size_t copyOffset, const char pStepTimeout, size_t stepTimeoutLength)
	Place Job step timeout in the given buffer. More...

static size_t	_appendClientToken (char pBuffer, size_t copyOffset, const AwsIotJobsRequestInfo_t pRequestInfo, _jobsOperation_t *pOperation)
	Place a client token in the given buffer. More...

static AwsIotJobsError_t	_generateGetPendingRequest (const AwsIotJobsRequestInfo_t pRequestInfo, _jobsOperation_t pOperation)
	Generates a request JSON for a GET PENDING operation. More...

static AwsIotJobsError_t	_generateStartNextRequest (const AwsIotJobsRequestInfo_t pRequestInfo, const AwsIotJobsUpdateInfo_t pUpdateInfo, _jobsOperation_t *pOperation)
	Generates a request JSON for a START NEXT operation. More...

static AwsIotJobsError_t	_generateDescribeRequest (const AwsIotJobsRequestInfo_t pRequestInfo, int32_t executionNumber, bool includeJobDocument, _jobsOperation_t pOperation)
	Generates a request JSON for a DESCRIBE operation. More...

static AwsIotJobsError_t	_generateUpdateRequest (const AwsIotJobsRequestInfo_t pRequestInfo, const AwsIotJobsUpdateInfo_t pUpdateInfo, _jobsOperation_t *pOperation)
	Generates a request JSON for an UPDATE operation. More...

static AwsIotJobsError_t	_parseErrorDocument (const char *pErrorDocument, size_t errorDocumentLength)
	Parse an error from a Jobs error document. 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...

Detailed Description

Implements functions that generate and parse Jobs JSON documents.

Macro Definition Documentation

◆ MINIMUM_REQUEST_LENGTH

#define MINIMUM_REQUEST_LENGTH ( AWS_IOT_CLIENT_TOKEN_KEY_LENGTH + 7 )

Minimum length of a Jobs request.

At the very least, the request will contain: {"clientToken":""}

◆ EXPECTED_VERSION_STRING_LENGTH

#define EXPECTED_VERSION_STRING_LENGTH ( 11 )

Maximum length of the expected version when represented as a string.

The expected version is a 32-bit unsigned integer. This can be represented in 10 digits plus a NULL-terminator.

◆ STEP_TIMEOUT_STRING_LENGTH

#define STEP_TIMEOUT_STRING_LENGTH ( 6 )

Maximum length of the step timeout when represented as a string.

The step timeout is in the range of [-1,10080]. This can be represented as 5 digits plus a NULL-terminator.

◆ EXECUTION_NUMBER_STRING_LENGTH

#define EXECUTION_NUMBER_STRING_LENGTH ( 12 )

Maximum length of the execution number when represented as a string.

The execution number is a 32-bit integer. This can be represented in 10 digits, plus 1 for a possible negative sign, plus a NULL-terminator.

◆ APPEND_STRING

#define APPEND_STRING	(	pBuffer,
		copyOffset,
		pString,
		stringLength
	)

Value:

( void ) memcpy( pBuffer + copyOffset, pString, stringLength ); \

copyOffset += ( size_t ) stringLength;

Append a string to a buffer.

Also updates copyOffset with stringLength.

Parameters

[in]	pBuffer	Start of a buffer.
[in]	copyOffset	Offset in `pBuffer` where `pString` will be placed.
[in]	pString	The string to append.
[in]	stringLength	Length of `pString`.

Function Documentation

◆ _appendFlag()

static size_t _appendFlag	(	char *	pBuffer,
		size_t	copyOffset,
		const char *	pFlagName,
		size_t	flagNameLength,
		bool	value
	)

static

Place a JSON boolean flag in the given buffer.

Parameters

[in]	pBuffer	The buffer where the flag is placed.
[in]	copyOffset	Offset in `pBuffer` where the flag is placed.
[in]	pFlagName	Either INCLUDE_JOB_DOCUMENT_KEY or INCLUDE_JOB_EXECUTION_STATE_KEY.
[in]	flagNameLength	Either INCLUDE_JOB_EXECUTION_STATE_KEY_LENGTH or INCLUDE_JOB_EXECUTION_STATE_KEY_LENGTH
[in]	value	Either `true` or `false`.

Warning: This function does not check the length of pBuffer! Any provided buffer must be large enough to accommodate the flag and value.

Returns: A value of copyOffset after the flag.

◆ _appendStatusDetails()

static size_t _appendStatusDetails	(	char *	pBuffer,
		size_t	copyOffset,
		const char *	pStatusDetails,
		size_t	statusDetailsLength
	)

static

Place Job status details in the given buffer.

Parameters

[in]	pBuffer	The buffer where the status details are placed.
[in]	copyOffset	Offset in `pBuffer` where the status details are placed.
[in]	pStatusDetails	The status details to place in the buffer.
[in]	statusDetailsLength	Length of `pStatusDetails`.

Warning: This function does not check the length of pBuffer! Any provided buffer must be large enough to accommodate the status details.

Returns: A value of copyOffset after the status details.

◆ _appendExecutionNumber()

static size_t _appendExecutionNumber	(	char *	pBuffer,
		size_t	copyOffset,
		const char *	pExecutionNumber,
		size_t	executionNumberLength
	)

static

Place Job execution number in the given buffer.

Parameters

[in]	pBuffer	The buffer where the execution number is placed.
[in]	copyOffset	Offset in `pBuffer` where the execution number is placed.
[in]	pExecutionNumber	The execution number to place in the buffer.
[in]	executionNumberLength	Length of `pExecutionNumber`.

Warning: This function does not check the length of pBuffer! Any provided buffer must be large enough to accommodate the execution number.

Returns: A value of copyOffset after the execution number.

◆ _appendStepTimeout()

static size_t _appendStepTimeout	(	char *	pBuffer,
		size_t	copyOffset,
		const char *	pStepTimeout,
		size_t	stepTimeoutLength
	)

static

Place Job step timeout in the given buffer.

Parameters

[in]	pBuffer	The buffer where the step timeout is placed.
[in]	copyOffset	Offset in `pBuffer` where the step timeout is placed.
[in]	pStepTimeout	The step timeout to place in the buffer.
[in]	stepTimeoutLength	Length of `pStepTimeout`.

Warning: This function does not check the length of pBuffer! Any provided buffer must be large enough to accommodate the step timeout.

Returns: A value of copyOffset after the step timeout.

◆ _appendClientToken()

static size_t _appendClientToken	(	char *	pBuffer,
		size_t	copyOffset,
		const AwsIotJobsRequestInfo_t *	pRequestInfo,
		_jobsOperation_t *	pOperation
	)

static

Place a client token in the given buffer.

Parameters

[in]	pBuffer	The buffer where the client token is placed.
[in]	copyOffset	Offset in `pBuffer` where client token is placed.
[in]	pRequestInfo	Contains information on a client token to place.
[out]	pOperation	Location and length of client token are written here.

Warning: This function does not check the length of pBuffer! Any provided buffer must be large enough to accommodate CLIENT_TOKEN_AUTOGENERATE_LENGTH characters.

Returns: A value of copyOffset after the client token.

◆ _generateGetPendingRequest()

static AwsIotJobsError_t _generateGetPendingRequest	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		_jobsOperation_t *	pOperation
	)

static

Generates a request JSON for a GET PENDING operation.

Parameters

[in]	pRequestInfo	Common Jobs request parameters.
[in]	pOperation	Operation associated with the Jobs request.

Returns: AWS_IOT_JOBS_SUCCESS or AWS_IOT_JOBS_NO_MEMORY

◆ _generateStartNextRequest()

static AwsIotJobsError_t _generateStartNextRequest	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		const AwsIotJobsUpdateInfo_t *	pUpdateInfo,
		_jobsOperation_t *	pOperation
	)

static

Generates a request JSON for a START NEXT operation.

Parameters

[in]	pRequestInfo	Common Jobs request parameters.
[in]	pUpdateInfo	Jobs update parameters.
[in]	pOperation	Operation associated with the Jobs request.

Returns: AWS_IOT_JOBS_SUCCESS or AWS_IOT_JOBS_NO_MEMORY

◆ _generateDescribeRequest()

static AwsIotJobsError_t _generateDescribeRequest	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		int32_t	executionNumber,
		bool	includeJobDocument,
		_jobsOperation_t *	pOperation
	)

static

Generates a request JSON for a DESCRIBE operation.

Parameters

[in]	pRequestInfo	Common jobs request parameters.
[in]	executionNumber	Job execution number to include in request.
[in]	includeJobDocument	Whether the response should include the Job document.
[in]	pOperation	Operation associated with the Jobs request.

Returns: AWS_IOT_JOBS_SUCCESS or AWS_IOT_JOBS_NO_MEMORY.

◆ _generateUpdateRequest()

static AwsIotJobsError_t _generateUpdateRequest	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		const AwsIotJobsUpdateInfo_t *	pUpdateInfo,
		_jobsOperation_t *	pOperation
	)

static

Generates a request JSON for an UPDATE operation.

Parameters

[in]	pRequestInfo	Common Jobs request parameters.
[in]	pUpdateInfo	Jobs update parameters.
[in]	pOperation	Operation associated with the Jobs request.

◆ _parseErrorDocument()

static AwsIotJobsError_t _parseErrorDocument	(	const char *	pErrorDocument,
		size_t	errorDocumentLength
	)

static

Parse an error from a Jobs error document.

Parameters

[in]	pErrorDocument	Jobs error document.
[in]	errorDocumentLength	Length of `pErrorDocument`.

Returns: A Jobs error code between AWS_IOT_JOBS_INVALID_TOPIC and AWS_IOT_JOBS_TERMINAL_STATE.

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

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ MINIMUM_REQUEST_LENGTH

◆ EXPECTED_VERSION_STRING_LENGTH

◆ STEP_TIMEOUT_STRING_LENGTH

◆ EXECUTION_NUMBER_STRING_LENGTH

◆ APPEND_STRING

Function Documentation

◆ _appendFlag()

◆ _appendStatusDetails()

◆ _appendExecutionNumber()

◆ _appendStepTimeout()

◆ _appendClientToken()

◆ _generateGetPendingRequest()

◆ _generateStartNextRequest()

◆ _generateDescribeRequest()

◆ _generateUpdateRequest()

◆ _parseErrorDocument()

◆ _AwsIotJobs_GenerateJsonRequest()

◆ _AwsIotJobs_ParseResponse()