AwsIotJobs_SetNotifyPendingCallback

Set a callback to be invoked when the list of pending Jobs changes.

AwsIotJobsError_t AwsIotJobs_SetNotifyPendingCallback( IotMqttConnection_t mqttConnection,
                                                       const char * pThingName,
                                                       size_t thingNameLength,
                                                       uint32_t flags,
                                                       const AwsIotJobsCallbackInfo_t * pNotifyPendingCallback );

The Jobs service publishes a JobExecutionsChanged message to the jobs/notify topic whenever a Job execution is added to or removed from the list of pending Job executions for a Thing. The message sent is useful for monitoring the list of pending Job executions.

A NOTIFY PENDING callback may be invoked whenever a message is published to jobs/notify. Each Thing may have up to AWS_IOT_JOBS_NOTIFY_CALLBACKS NOTIFY PENDING callbacks set. This function modifies the NOTIFY PENDING callback for a specific Thing depending on the pNotifyPendingCallback parameter and the presence of any existing NOTIFY PENDING callback.

• When no existing NOTIFY PENDING callback exists for a specific Thing, a new callback is added.
• If there is an existing NOTIFY PENDING callback and pNotifyPendingCallback is not NULL, then the existing callback function and parameter are replaced with pNotifyPendingCallback.
• If there is an existing NOTIFY PENDING callback and pNotifyPendingCallback is NULL, then the callback is removed.

The member AwsIotJobsCallbackInfo_t::oldFunction must be used to select an already-registered callback function for replacement or removal when AWS_IOT_JOBS_NOTIFY_CALLBACKS is greater than 1. When multiple callbacks are set, all of them will be invoked when a message is received.

Parameters

[in]	mqttConnection	The MQTT connection to use for the subscription to jobs/notify.
[in]	pThingName	The subscription to jobs/notify will be added for this Thing Name.
[in]	thingNameLength	The length of pThingName.
[in]	flags	This parameter is for future-compatibility. Currently, flags are not supported for this function and this parameter is ignored.
[in]	pNotifyPendingCallback	Callback function to invoke for incoming messages.

Returns

One of the following:

• AWS_IOT_JOBS_SUCCESS
• AWS_IOT_JOBS_NOT_INITIALIZED
• AWS_IOT_JOBS_BAD_PARAMETER
• AWS_IOT_JOBS_NO_MEMORY
• AWS_IOT_JOBS_MQTT_ERROR
• AWS_IOT_JOBS_TIMEOUT

See also

AwsIotJobs_SetNotifyNextCallback for the function to register callbacks for next Job changes.

Example:

#define THING_NAME "Test_device"
#define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )

AwsIotJobsError_t result = AWS_IOT_JOBS_STATUS_PENDING;
AwsIotJobsCallbackInfo_t notifyPendingCallback = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;

// _jobsCallback will be invoked when any messages are received.
notifyPendingCallback.function = _jobsCallback;

// Set the NOTIFY PENDING callback for the Thing "Test_device".
result = AwsIotJobs_SetNotifyPendingCallback( mqttConnection,
                                              THING_NAME,
                                              THING_NAME_LENGTH,
                                              0,
                                              &notifyPendingCallback );

// Check if the callback was successfully set.
if( status == AWS_IOT_JOBS_SUCCESS )
{
    // The callback will now be invoked whenever the list of pending Job
    // executions changes.

    // Once the callback is no longer needed, it may be removed by passing
    // NULL as the callback function and specifying the function to remove.
    notifyPendingCallback.function = NULL;
    notifyPendingCallback.oldFunction = _jobsCallback;

    status = AwsIotJobs_SetNotifyPendingCallback( mqttConnection,
                                                  THING_NAME,
                                                  THING_NAME_LENGTH,
                                                  0,
                                                  &notifyPendingCallback );

    // The return value from removing a callback should always be success.
    assert( status == AWS_IOT_JOBS_SUCCESS );
}