AwsIotJobs_SetNotifyNextCallback

Set a callback to be invoked when the next pending Job changes.

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

The Jobs service publishes a NextJobExecutionChanged message to the jobs/notify-next topic whenever the next Job execution in the list of pending Job executions changes for a Thing. The message sent is useful for being notified of changes to the next Job.

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

• When no existing NOTIFY NEXT callback exists for a specific Thing, a new callback is added.
• If there is an existing NOTIFY NEXT callback and pNotifyNextCallback is not NULL, then the existing callback function and parameter are replaced with pNotifyNextCallback.
• If there is an existing NOTIFY NEXT callback and pNotifyNextCallback 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-next.
[in]	pThingName	The subscription to jobs/notify-next 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]	pNotifyNextCallback	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_SetNotifyPendingCallback for the function to register callbacks for all pending 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 notifyNextCallback = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;

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

// Set the NOTIFY NEXT callback for the Thing "Test_device".
result = AwsIotJobs_SetNotifyNextCallback( mqttConnection,
                                           THING_NAME,
                                           THING_NAME_LENGTH,
                                           0,
                                           &notifyNextCallback );

// Check if the callback was successfully set.
if( status == AWS_IOT_JOBS_SUCCESS )
{
    // The callback will now be invoked whenever the next pending Job
    // execution 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.
    notifyNextCallback.function = NULL;
    notifyNextCallback.oldFunction = _jobsCallback;

    status = AwsIotJobs_SetNotifyNextCallback( mqttConnection,
                                               THING_NAME,
                                               THING_NAME_LENGTH,
                                               0,
                                               &notifyNextCallback );

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