Demonstrates use of the AWS IoT Jobs library. More...

#include "iot_config.h"
#include <string.h>
#include "iot_demo_logging.h"
#include "platform/iot_clock.h"
#include "iot_mqtt.h"
#include "aws_iot_jobs.h"
#include "aws_iot_doc_parser.h"
#include "iot_atomic.h"

Macros
#define	TIMEOUT_MS ( ( uint32_t ) 5000u )
	The timeout for Jobs and MQTT operations in this demo.

#define	KEEP_ALIVE_SECONDS ( ( uint16_t ) 60u )
	The keep-alive interval used for this demo. More...

#define	JOB_ID_KEY "jobId"
	The JSON key of the Job ID. More...

#define	JOB_ID_KEY_LENGTH ( sizeof( JOB_ID_KEY ) - 1 )
	The length of JOB_ID_KEY.

#define	JOB_DOC_KEY "jobDocument"
	The JSON key of the Job document. More...

#define	JOB_DOC_KEY_LENGTH ( sizeof( JOB_DOC_KEY ) - 1 )
	The length of JOB_DOC_KEY.

#define	JOB_ACTION_KEY "action"
	The JSON key whose value represents the action this demo should take. More...

#define	JOB_ACTION_KEY_LENGTH ( sizeof( JOB_ACTION_KEY ) - 1 )
	The length of JOB_ACTION_KEY.

#define	JOB_MESSAGE_KEY "message"
	A message associated with the Job action. More...

#define	JOB_MESSAGE_KEY_LENGTH ( sizeof( JOB_MESSAGE_KEY ) - 1 )
	The length of JOB_MESSAGE_KEY.

#define	JOB_TOPIC_KEY "topic"
	An MQTT topic associated with the Job "publish" action. More...

#define	JOB_TOPIC_KEY_LENGTH ( sizeof( JOB_TOPIC_KEY ) - 1 )
	The length of JOB_TOPIC_KEY.

#define	JSON_STRING_MIN_LENGTH ( ( size_t ) 3 )
	The minimum length of a string in a JSON Job document. More...

#define	JOB_ID_MAX_LENGTH ( ( size_t ) 64 )
	The maximum length of a Job ID. More...

#define	JOBS_DEMO_SHOULD_EXIT ( ( void * ) ( ( intptr_t ) 1 ) )
	A value passed as context to _operationCompleteCallback to specify that it should set the JOBS_DEMO_FINISHED flag.

#define	JOBS_DEMO_RUNNING ( ( uint32_t ) 0 )
	Flag value for signaling that the demo is still running. More...

#define	JOBS_DEMO_FINISHED ( ( uint32_t ) 1 )
	Flag value for signaling that the demo is finished. More...

Enumerations
enum	_jobAction_t { JOB_ACTION_PRINT, JOB_ACTION_PUBLISH, JOB_ACTION_EXIT, JOB_ACTION_UNKNOWN }
	Currently supported actions that a Job document can specify. More...

Functions
static int	_initializeDemo (void)
	Initialize the libraries required for this demo. More...

static void	_cleanupDemo (void)
	Clean up the libraries initialized by _initializeDemo. More...

static int	_establishMqttConnection (const char pIdentifier, void pNetworkServerInfo, void pNetworkCredentialInfo, const IotNetworkInterface_t pNetworkInterface, IotMqttConnection_t *const pMqttConnection)
	Establish a new connection to the MQTT server for the Jobs demo. More...

static _jobAction_t	_getAction (const char *pAction, size_t actionLength)
	Converts a string in a Job document to a _jobAction_t. More...

static bool	_getJsonString (const char pJsonDoc, size_t jsonDocLength, const char pKey, size_t keyLength, const char *pValue, size_t valueLength)
	Extracts a JSON string from the Job document. More...

static void	_operationCompleteCallback (void pCallbackContext, AwsIotJobsCallbackParam_t pCallbackParam)
	Job operation completion callback. This function is invoked when an asynchronous Job operation finishes. More...

static AwsIotJobState_t	_processMessage (IotMqttConnection_t mqttConnection, _jobAction_t action, const char *pJobDoc, size_t jobDocLength)
	Process an action with a message, such as "print" or "publish". More...

static void	_processJob (const AwsIotJobsCallbackParam_t pJobInfo, const char pJobId, size_t jobIdLength, const char *pJobDoc, size_t jobDocLength)
	Process a Job received from the Notify Next callback. More...

static void	_jobsCallback (void pCallbackContext, AwsIotJobsCallbackParam_t pCallbackInfo)
	Jobs Notify Next callback. This function is invoked when a new Job is received from the Jobs service. More...

int	RunJobsDemo (bool awsIotMqttMode, const char pIdentifier, void pNetworkServerInfo, void pNetworkCredentialInfo, const IotNetworkInterface_t pNetworkInterface)
	The function that runs the Jobs demo, called by the demo runner. More...

Variables
static IotLogConfig_t	_logHideAll = { .hideLogLevel = true, .hideLibraryName = true, .hideTimestring = true }
	Used to print log messages that do not contain any metadata.

static uint32_t	_exitFlag = 0
	A flag that signals the end of the demo. More...

Detailed Description

Demonstrates use of the AWS IoT Jobs library.

This program sets a Jobs Notify-Next callback and waits for Job documents to arrive. It will then take action based on the Job document.

Macro Definition Documentation

◆ KEEP_ALIVE_SECONDS

#define KEEP_ALIVE_SECONDS ( ( uint16_t ) 60u )

The keep-alive interval used for this demo.

An MQTT ping request will be sent periodically at this interval.

◆ JOB_ID_KEY

#define JOB_ID_KEY "jobId"

The JSON key of the Job ID.

Job documents are JSON documents received from the AWS IoT Jobs service. All Job documents will contain this key, whose value represents the unique identifier of a Job.

◆ JOB_DOC_KEY

#define JOB_DOC_KEY "jobDocument"

The JSON key of the Job document.

Job documents are JSON documents received from the AWS IoT Jobs service. All Job documents will contain this key, whose value is an application-specific JSON document.

◆ JOB_ACTION_KEY

#define JOB_ACTION_KEY "action"

The JSON key whose value represents the action this demo should take.

This demo program expects this key to be in the Job document. It is a key specific to this demo.

◆ JOB_MESSAGE_KEY

#define JOB_MESSAGE_KEY "message"

A message associated with the Job action.

This demo program expects this key to be in the Job document if the "action" is either "publish" or "print". It represents the message that should be published or printed, respectively.

◆ JOB_TOPIC_KEY

#define JOB_TOPIC_KEY "topic"

An MQTT topic associated with the Job "publish" action.

This demo program expects this key to be in the Job document if the "action" is "publish". It represents the MQTT topic on which the message should be published.

◆ JSON_STRING_MIN_LENGTH

#define JSON_STRING_MIN_LENGTH ( ( size_t ) 3 )

The minimum length of a string in a JSON Job document.

At the very least the Job ID must have the quotes that identify it as a JSON string and 1 character for the string itself (the string must not be empty).

◆ JOB_ID_MAX_LENGTH

#define JOB_ID_MAX_LENGTH ( ( size_t ) 64 )

The maximum length of a Job ID.

This limit is defined by AWS service limits. See the following page for more information.

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

◆ JOBS_DEMO_RUNNING

#define JOBS_DEMO_RUNNING ( ( uint32_t ) 0 )

Flag value for signaling that the demo is still running.

The initial value of _exitFlag.

◆ JOBS_DEMO_FINISHED

#define JOBS_DEMO_FINISHED ( ( uint32_t ) 1 )

Flag value for signaling that the demo is finished.

_exitFlag will be set to this when a Job document with { "action": "exit" } is received.

Enumeration Type Documentation

◆ _jobAction_t

enum _jobAction_t

Currently supported actions that a Job document can specify.

Enumerator
JOB_ACTION_PRINT	Print a message.
JOB_ACTION_PUBLISH	Publish a message to an MQTT topic.
JOB_ACTION_EXIT	Exit the demo.
JOB_ACTION_UNKNOWN	Unknown action.

Function Documentation

◆ _initializeDemo()

static int _initializeDemo ( void )

static

Initialize the libraries required for this demo.

Initialize the MQTT and Jobs libraries. If the Jobs library fails to initialize, the MQTT library is cleaned up.

Returns: EXIT_SUCCESS if all initialization succeeds; EXIT_FAILURE otherwise.

◆ _cleanupDemo()

static void _cleanupDemo ( void )

static

Clean up the libraries initialized by _initializeDemo.

Note: Must not be called if _initializeDemo was not successfully called.

◆ _establishMqttConnection()

static int _establishMqttConnection	(	const char *	pIdentifier,
		void *	pNetworkServerInfo,
		void *	pNetworkCredentialInfo,
		const IotNetworkInterface_t *	pNetworkInterface,
		IotMqttConnection_t *const	pMqttConnection
	)

static

Establish a new connection to the MQTT server for the Jobs demo.

Parameters

[in]	pIdentifier	NULL-terminated MQTT client identifier. The Jobs demo will use the Thing Name as the client identifier.
[in]	pNetworkServerInfo	Passed to the MQTT connect function when establishing the MQTT connection.
[in]	pNetworkCredentialInfo	Passed to the MQTT connect function when establishing the MQTT connection.
[in]	pNetworkInterface	The network interface to use for this demo.
[out]	pMqttConnection	Set to the handle to the new MQTT connection.

Returns: EXIT_SUCCESS if the connection is successfully established; EXIT_FAILURE otherwise.

◆ _getAction()

static _jobAction_t _getAction	(	const char *	pAction,
		size_t	actionLength
	)

static

Converts a string in a Job document to a _jobAction_t.

Parameters

[in]	pAction	The Job action as a string.
[in]	actionLength	The length of `pAction`.

Returns: A _jobAction_t equivalent to the given string.

◆ _getJsonString()

static bool _getJsonString	(	const char *	pJsonDoc,
		size_t	jsonDocLength,
		const char *	pKey,
		size_t	keyLength,
		const char **	pValue,
		size_t *	valueLength
	)

static

Extracts a JSON string from the Job document.

Parameters

[in]	pJsonDoc	The JSON document to search.
[in]	jsonDocLength	Length of `pJsonDoc`.
[in]	pKey	The JSON key to search for.
[in]	keyLength	Length of `pKey`.
[out]	pValue	The extracted JSON value.
[out]	valueLength	Length of pValue.

Returns: true if the key was found and the value is valid; false otherwise.

◆ _operationCompleteCallback()

static void _operationCompleteCallback	(	void *	pCallbackContext,
		AwsIotJobsCallbackParam_t *	pCallbackParam
	)

static

Job operation completion callback. This function is invoked when an asynchronous Job operation finishes.

Parameters

[in]	pCallbackContext	Set to a non-NULL value to exit the demo.
[in]	pCallbackParam	Information on the Job operation that completed.

◆ _processMessage()

static AwsIotJobState_t _processMessage	(	IotMqttConnection_t	mqttConnection,
		_jobAction_t	action,
		const char *	pJobDoc,
		size_t	jobDocLength
	)

static

Process an action with a message, such as "print" or "publish".

Parameters

[in]	mqttConnection	The MQTT connection to use if the action is "publish".
[in]	action	Either JOB_ACTION_PRINT or JOB_ACTION_PUBLISH.
[in]	pJobDoc	A pointer to the Job document.
[in]	jobDocLength	The length of the Job document.

Returns: AWS_IOT_JOB_STATE_SUCCEEDED on success; AWS_IOT_JOB_STATE_FAILED otherwise.

◆ _processJob()

static void _processJob	(	const AwsIotJobsCallbackParam_t *	pJobInfo,
		const char *	pJobId,
		size_t	jobIdLength,
		const char *	pJobDoc,
		size_t	jobDocLength
	)

static

Process a Job received from the Notify Next callback.

Parameters

[in]	pJobInfo	The parameter to the Notify Next callback that contains information about the received Job.
[in]	pJobId	A pointer to the Job ID.
[in]	jobIdLength	The length of the Job ID.
[in]	pJobDoc	A pointer to the Job document.
[in]	jobDocLength	The length of the Job document.

◆ _jobsCallback()

static void _jobsCallback	(	void *	pCallbackContext,
		AwsIotJobsCallbackParam_t *	pCallbackInfo
	)

static

Jobs Notify Next callback. This function is invoked when a new Job is received from the Jobs service.

Parameters

[in]	pCallbackContext	Ignored.
[in]	pCallbackInfo	Contains the received Job.

◆ RunJobsDemo()

int RunJobsDemo	(	bool	awsIotMqttMode,
		const char *	pIdentifier,
		void *	pNetworkServerInfo,
		void *	pNetworkCredentialInfo,
		const IotNetworkInterface_t *	pNetworkInterface
	)

The function that runs the Jobs demo, called by the demo runner.

Parameters

[in]	awsIotMqttMode	Ignored for the Jobs demo.
[in]	pIdentifier	NULL-terminated Jobs Thing Name.
[in]	pNetworkServerInfo	Passed to the MQTT connect function when establishing the MQTT connection for Jobs.
[in]	pNetworkCredentialInfo	Passed to the MQTT connect function when establishing the MQTT connection for Jobs.
[in]	pNetworkInterface	The network interface to use for this demo.

Returns: EXIT_SUCCESS if the demo completes successfully; EXIT_FAILURE otherwise.

Variable Documentation

◆ _exitFlag

uint32_t _exitFlag = 0

static

A flag that signals the end of the demo.

When a Job document is received with { "action": "exit" }, the demo will set this flag and exit.

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ KEEP_ALIVE_SECONDS

◆ JOB_ID_KEY

◆ JOB_DOC_KEY

◆ JOB_ACTION_KEY

◆ JOB_MESSAGE_KEY

◆ JOB_TOPIC_KEY

◆ JSON_STRING_MIN_LENGTH

◆ JOB_ID_MAX_LENGTH

◆ JOBS_DEMO_RUNNING

◆ JOBS_DEMO_FINISHED

Enumeration Type Documentation

◆ _jobAction_t

Function Documentation

◆ _initializeDemo()

◆ _cleanupDemo()

◆ _establishMqttConnection()

◆ _getAction()

◆ _getJsonString()

◆ _operationCompleteCallback()

◆ _processMessage()

◆ _processJob()

◆ _jobsCallback()

◆ RunJobsDemo()

Variable Documentation

◆ _exitFlag