aws_iot_jobs_subscription.c File Reference

Implements functions for interacting with the Jobs library's subscription list. More...

#include "iot_config.h"
#include <string.h>
#include "private/aws_iot_jobs_internal.h"
#include "iot_error.h"
#include "platform/iot_threads.h"
#include "iot_mqtt.h"

Functions
static bool	_jobsSubscription_match (const IotLink_t *pSubscriptionLink, void *pMatch)
	Match two _jobsSubscription_t by Thing Name. 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_RemovePersistentSubscriptions (const AwsIotJobsRequestInfo_t *pRequestInfo, uint32_t flags)
	Remove persistent Jobs operation topic subscriptions. More...

Variables
IotListDouble_t	_AwsIotJobsSubscriptions = { 0 }
	List of active Jobs subscriptions objects.
IotMutex_t	_AwsIotJobsSubscriptionsMutex
	Protects _AwsIotJobsSubscriptions from concurrent access.

Detailed Description

Implements functions for interacting with the Jobs library's subscription list.

Function Documentation

_jobsSubscription_match()

static bool _jobsSubscription_match ( const IotLink_t *  pSubscriptionLink, void *  pMatch  )

static

Match two _jobsSubscription_t by Thing Name.

Parameters

[in]	pSubscriptionLink	Pointer to the link member of a _jobsSubscription_t containing the Thing Name to check.
[in]	pMatch	Pointer to a AwsIotThingName_t.

Returns

true if the Thing Names match; false otherwise.

_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_RemovePersistentSubscriptions()

AwsIotJobsError_t AwsIotJobs_RemovePersistentSubscriptions	(	const AwsIotJobsRequestInfo_t *	pRequestInfo,
		uint32_t	flags
	)

Remove persistent Jobs operation topic subscriptions.

Passing the flag AWS_IOT_JOBS_FLAG_KEEP_SUBSCRIPTIONS to AwsIotJobs_GetPendingAsync, AwsIotJobs_StartNextAsync, AwsIotJobs_DescribeAsync, AwsIotJobs_UpdateAsync, or their blocking versions causes the Jobs operation topic subscriptions to be maintained for future calls to the same function. If a persistent subscription for a Jobs topic are no longer needed, this function may be used to remove it.

Parameters

[in]	pRequestInfo	Jobs request info. Only the pThingName, thingNameLength, and mqttConnection members need to be set for this function.
[in]	flags	Flags that determine which subscriptions to remove. Valid values are the bitwise OR of the following individual flags: AWS_IOT_JOBS_FLAG_REMOVE_GET_PENDING_SUBSCRIPTIONS AWS_IOT_JOBS_FLAG_REMOVE_START_NEXT_SUBSCRIPTIONS AWS_IOT_JOBS_FLAG_REMOVE_DESCRIBE_SUBSCRIPTIONS AWS_IOT_JOBS_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS

Returns

On success:

• AWS_IOT_JOBS_SUCCESS

If an MQTT UNSUBSCRIBE packet cannot be sent, one of the following:

• AWS_IOT_JOBS_NO_MEMORY
• AWS_IOT_JOBS_MQTT_ERROR

Note

AwsIotJobs_Cleanup removes persistent sessions as well.

Warning

This function is not safe to call with any in-progress operations! It also does not affect NOTIFY PENDING and NOTIFY NEXT callbacks registered with AwsIotJobs_SetNotifyPendingCallback and AwsIotJobs_SetNotifyNextCallback, respectively. (See documentation for those functions on how to remove their callbacks).