| /* | |
| * AWS IoT Jobs V1.0.0 | |
| * Copyright (C) 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. | |
| * | |
| * Permission is hereby granted, free of charge, to any person obtaining a copy of | |
| * this software and associated documentation files (the "Software"), to deal in | |
| * the Software without restriction, including without limitation the rights to | |
| * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of | |
| * the Software, and to permit persons to whom the Software is furnished to do so, | |
| * subject to the following conditions: | |
| * | |
| * The above copyright notice and this permission notice shall be included in all | |
| * copies or substantial portions of the Software. | |
| * | |
| * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
| * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS | |
| * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR | |
| * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER | |
| * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN | |
| * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
| */ | |
| /** | |
| * @file aws_iot_jobs.h | |
| * @brief User-facing functions of the Jobs library. | |
| */ | |
| #ifndef AWS_IOT_JOBS_H_ | |
| #define AWS_IOT_JOBS_H_ | |
| /* The config header is always included first. */ | |
| #include "iot_config.h" | |
| /* Jobs types include. */ | |
| #include "types/aws_iot_jobs_types.h" | |
| /*------------------------- Jobs library functions --------------------------*/ | |
| /** | |
| * @functionspage{jobs,Jobs library} | |
| * - @functionname{jobs_function_init} | |
| * - @functionname{jobs_function_cleanup} | |
| * - @functionname{jobs_function_getpendingasync} | |
| * - @functionname{jobs_function_getpendingsync} | |
| * - @functionname{jobs_function_startnextasync} | |
| * - @functionname{jobs_function_startnextsync} | |
| * - @functionname{jobs_function_describeasync} | |
| * - @functionname{jobs_function_describesync} | |
| * - @functionname{jobs_function_updateasync} | |
| * - @functionname{jobs_function_updatesync} | |
| * - @functionname{jobs_function_wait} | |
| * - @functionname{jobs_function_setnotifypendingcallback} | |
| * - @functionname{jobs_function_setnotifynextcallback} | |
| * - @functionname{jobs_function_removepersistentsubscriptions} | |
| * - @functionname{jobs_function_strerror} | |
| * - @functionname{jobs_function_statename} | |
| */ | |
| /** | |
| * @functionpage{AwsIotJobs_Init,jobs,init} | |
| * @functionpage{AwsIotJobs_Cleanup,jobs,cleanup} | |
| * @functionpage{AwsIotJobs_GetPendingAsync,jobs,getpendingasync} | |
| * @functionpage{AwsIotJobs_GetPendingSync,jobs,getpendingsync} | |
| * @functionpage{AwsIotJobs_StartNextAsync,jobs,startnextasync} | |
| * @functionpage{AwsIotJobs_StartNextSync,jobs,startnextsync} | |
| * @functionpage{AwsIotJobs_DescribeAsync,jobs,describeasync} | |
| * @functionpage{AwsIotJobs_DescribeSync,jobs,describesync} | |
| * @functionpage{AwsIotJobs_UpdateAsync,jobs,updateasync} | |
| * @functionpage{AwsIotJobs_UpdateSync,jobs,updatesync} | |
| * @functionpage{AwsIotJobs_Wait,jobs,wait} | |
| * @functionpage{AwsIotJobs_SetNotifyPendingCallback,jobs,setnotifypendingcallback} | |
| * @functionpage{AwsIotJobs_SetNotifyNextCallback,jobs,setnotifynextcallback} | |
| * @functionpage{AwsIotJobs_RemovePersistentSubscriptions,jobs,removepersistentsubscriptions} | |
| * @functionpage{AwsIotJobs_strerror,jobs,strerror} | |
| * @functionpage{AwsIotJobs_StateName,jobs,statename} | |
| */ | |
| /** | |
| * @brief One-time initialization function for the Jobs library. | |
| * | |
| * This function performs internal setup of the Jobs library. <b>It must be | |
| * called once (and only once) before calling any other Jobs function.</b> | |
| * Calling this function more than once without first calling @ref | |
| * jobs_function_cleanup may result in a crash. | |
| * | |
| * @param[in] mqttTimeoutMs The amount of time (in milliseconds) that the Jobs | |
| * library will wait for MQTT operations. Optional; set this to `0` to use | |
| * @ref AWS_IOT_JOBS_DEFAULT_MQTT_TIMEOUT_MS. | |
| * | |
| * @return One of the following: | |
| * - #AWS_IOT_JOBS_SUCCESS | |
| * - #AWS_IOT_JOBS_INIT_FAILED | |
| * | |
| * @warning No thread-safety guarantees are provided for this function. | |
| * | |
| * @see @ref jobs_function_cleanup | |
| */ | |
| /* @[declare_jobs_init] */ | |
| AwsIotJobsError_t AwsIotJobs_Init( uint32_t mqttTimeoutMs ); | |
| /* @[declare_jobs_init] */ | |
| /** | |
| * @brief One-time deinitialization function for the Jobs library. | |
| * | |
| * This function frees resources taken in @ref jobs_function_init and deletes | |
| * any [persistent subscriptions.](@ref AWS_IOT_JOBS_FLAG_KEEP_SUBSCRIPTIONS) | |
| * It should be called to clean up the Jobs library. After this function returns, | |
| * @ref jobs_function_init must be called again before calling any other Jobs | |
| * function. | |
| * | |
| * @warning No thread-safety guarantees are provided for this function. | |
| * | |
| * @see @ref jobs_function_init | |
| */ | |
| /* @[declare_jobs_cleanup] */ | |
| void AwsIotJobs_Cleanup( void ); | |
| /* @[declare_jobs_cleanup] */ | |
| /** | |
| * @brief Get the list of all pending jobs for a Thing and receive an asynchronous | |
| * notification when the response arrives. | |
| * | |
| * This function implements the [GetPendingJobExecutions] | |
| * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-getpendingjobexecutions) | |
| * command of the Jobs API, which gets the list of all Jobs for a Thing that are | |
| * not in a terminal state. The list of retrieved Jobs is returned as the `pResponse` | |
| * member in #AwsIotJobsCallbackParam_t, or through the #AwsIotJobsResponse_t | |
| * parameter of @ref jobs_function_wait. | |
| * | |
| * @param[in] pRequestInfo Jobs request parameters. | |
| * @param[in] flags Flags which modify the behavior of the Jobs request. See | |
| * @ref jobs_constants_flags. | |
| * @param[in] pCallbackInfo Asynchronous notification of this function's completion. | |
| * @param[out] pGetPendingOperation Set to a handle by which this operation may be referenced | |
| * after this function returns. This reference is invalidated once the Jobs operation | |
| * completes. | |
| * | |
| * @return This function will return #AWS_IOT_JOBS_STATUS_PENDING upon successfully | |
| * queuing the Jobs operation. | |
| * @return If this function fails before queuing the Jobs operation, it will return one of: | |
| * - #AWS_IOT_JOBS_NOT_INITIALIZED | |
| * - #AWS_IOT_JOBS_BAD_PARAMETER | |
| * - #AWS_IOT_JOBS_NO_MEMORY | |
| * @return Upon successful completion of the Jobs operation (either through an #AwsIotJobsCallbackInfo_t | |
| * or @ref jobs_function_wait), the status will be #AWS_IOT_JOBS_SUCCESS. | |
| * @return Should the Jobs operation fail, the status will be one of: | |
| * - #AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document) | |
| * - #AWS_IOT_JOBS_MQTT_ERROR | |
| * - #AWS_IOT_JOBS_BAD_RESPONSE | |
| * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE. | |
| * | |
| * @see @ref jobs_function_getpendingsync for a blocking variant of this function. | |
| * | |
| * <b>Example</b> | |
| * @code{c} | |
| * #define THING_NAME "Test_device" | |
| * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 ) | |
| * | |
| * // Signature of Jobs callback function. | |
| * void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam ); | |
| * | |
| * AwsIotJobsOperation_t getPendingOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER; | |
| * AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER; | |
| * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER; | |
| * | |
| * // Set the request info. | |
| * requestInfo.mqttConnection = _mqttConnection; | |
| * requestInfo.pThingName = THING_NAME; | |
| * requestInfo.thingNameLength = THING_NAME_LENGTH; | |
| * | |
| * // Set the callback function to invoke. | |
| * callbackInfo.function = _jobsCallback; | |
| * | |
| * // Queue Jobs GET PENDING. | |
| * AwsIotJobsError_t getPendingResult = AwsIotJobs_GetPendingAsync( &requestInfo, | |
| * 0, | |
| * &callbackInfo, | |
| * &getPendingOperation ); | |
| * | |
| * // GET PENDING should have returned AWS_IOT_JOBS_STATUS_PENDING. The function | |
| * // _jobsCallback will be invoked once the Jobs response is received. | |
| * @endcode | |
| */ | |
| /* @[declare_jobs_getpendingasync] */ | |
| AwsIotJobsError_t AwsIotJobs_GetPendingAsync( const AwsIotJobsRequestInfo_t * pRequestInfo, | |
| uint32_t flags, | |
| const AwsIotJobsCallbackInfo_t * pCallbackInfo, | |
| AwsIotJobsOperation_t * const pGetPendingOperation ); | |
| /* @[declare_jobs_getpendingasync] */ | |
| /** | |
| * @brief Get the list of all pending jobs for a Thing with a timeout for receiving | |
| * the response. | |
| * | |
| * This function queues a Jobs GET PENDING, then waits for the result. Internally, | |
| * this function is a call to @ref jobs_function_getpendingasync followed by | |
| * @ref jobs_function_wait. See @ref jobs_function_getpendingasync for more information | |
| * on the Jobs GET PENDING command. | |
| * | |
| * @param[in] pRequestInfo Jobs request parameters. | |
| * @param[in] flags Flags which modify the behavior of the Jobs request. See | |
| * @ref jobs_constants_flags. | |
| * @param[in] timeoutMs If a response is not received within this timeout, this | |
| * function returns #AWS_IOT_JOBS_TIMEOUT. | |
| * @param[out] pJobsResponse The response received from the Jobs service. | |
| * | |
| * @return 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_BAD_RESPONSE | |
| * - #AWS_IOT_JOBS_TIMEOUT | |
| * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE. | |
| */ | |
| /* @[declare_jobs_getpendingsync] */ | |
| AwsIotJobsError_t AwsIotJobs_GetPendingSync( const AwsIotJobsRequestInfo_t * pRequestInfo, | |
| uint32_t flags, | |
| uint32_t timeoutMs, | |
| AwsIotJobsResponse_t * const pJobsResponse ); | |
| /* @[declare_jobs_getpendingsync] */ | |
| /** | |
| * @brief Start the next pending job execution for a Thing and receive an asynchronous | |
| * notification when the response arrives. | |
| * | |
| * This function implements the [StartNextPendingJobExecution] | |
| * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-startnextpendingjobexecution) | |
| * command of the Jobs API, which gets and starts the next pending job execution | |
| * for a Thing. | |
| * | |
| * @param[in] pRequestInfo Jobs request parameters. | |
| * @param[in] pUpdateInfo Jobs update parameters. | |
| * @param[in] flags Flags which modify the behavior of the Jobs request. See | |
| * @ref jobs_constants_flags. | |
| * @param[in] pCallbackInfo Asynchronous notification of this function's completion. | |
| * @param[out] pStartNextOperation Set to a handle by which this operation may be referenced | |
| * after this function returns. This reference is invalidated once the Jobs operation | |
| * completes. | |
| * | |
| * @return This function will return #AWS_IOT_JOBS_STATUS_PENDING upon successfully | |
| * queuing the Jobs operation. | |
| * @return If this function fails before queuing the Jobs operation, it will return one of: | |
| * - #AWS_IOT_JOBS_NOT_INITIALIZED | |
| * - #AWS_IOT_JOBS_BAD_PARAMETER | |
| * - #AWS_IOT_JOBS_NO_MEMORY | |
| * @return Upon successful completion of the Jobs operation (either through an #AwsIotJobsCallbackInfo_t | |
| * or @ref jobs_function_wait), the status will be #AWS_IOT_JOBS_SUCCESS. | |
| * @return Should the Jobs operation fail, the status will be one of: | |
| * - #AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document) | |
| * - #AWS_IOT_JOBS_MQTT_ERROR | |
| * - #AWS_IOT_JOBS_BAD_RESPONSE | |
| * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE. | |
| * | |
| * @see @ref jobs_function_startnextsync for a blocking variant of this function. | |
| * | |
| * <b>Example</b> | |
| * @code{c} | |
| * #define THING_NAME "Test_device" | |
| * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 ) | |
| * | |
| * // Signature of Jobs callback function. | |
| * void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam ); | |
| * | |
| * AwsIotJobsOperation_t startNextOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER; | |
| * AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER; | |
| * AwsIotJobsUpdateInfo_t updateInfo = AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER; | |
| * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER; | |
| * | |
| * // Set the request info. The update info generally does not need to be | |
| * // changed, as its defaults are suitable. | |
| * requestInfo.mqttConnection = _mqttConnection; | |
| * requestInfo.pThingName = THING_NAME; | |
| * requestInfo.thingNameLength = THING_NAME_LENGTH; | |
| * | |
| * // Set the callback function to invoke. | |
| * callbackInfo.function = _jobsCallback; | |
| * | |
| * // Queue Jobs START NEXT. | |
| * AwsIotJobsError_t startNextResult = AwsIotJobs_StartNextAsync( &requestInfo, | |
| * &updateInfo, | |
| * 0, | |
| * &callbackInfo, | |
| * &startNextOperation ); | |
| * | |
| * // START NEXT should have returned AWS_IOT_JOBS_STATUS_PENDING. The function | |
| * // _jobsCallback will be invoked once the Jobs response is received. | |
| * @endcode | |
| */ | |
| /* @[declare_jobs_startnextasync] */ | |
| AwsIotJobsError_t AwsIotJobs_StartNextAsync( const AwsIotJobsRequestInfo_t * pRequestInfo, | |
| const AwsIotJobsUpdateInfo_t * pUpdateInfo, | |
| uint32_t flags, | |
| const AwsIotJobsCallbackInfo_t * pCallbackInfo, | |
| AwsIotJobsOperation_t * const pStartNextOperation ); | |
| /* @[declare_jobs_startnextasync] */ | |
| /** | |
| * @brief Start the next pending job execution for a Thing with a timeout for | |
| * receiving the response. | |
| * | |
| * This function queues a Jobs START NEXT, then waits for the result. Internally, | |
| * this function is a call to @ref jobs_function_startnextasync followed by | |
| * @ref jobs_function_wait. See @ref jobs_function_startnextasync for more information | |
| * on the Jobs START NEXT command. | |
| * | |
| * @param[in] pRequestInfo Jobs request parameters. | |
| * @param[in] pUpdateInfo Jobs update parameters. | |
| * @param[in] flags Flags which modify the behavior of the Jobs request. See | |
| * @ref jobs_constants_flags. | |
| * @param[in] timeoutMs If a response is not received within this timeout, this | |
| * function returns #AWS_IOT_JOBS_TIMEOUT. | |
| * @param[out] pJobsResponse The response received from the Jobs service. | |
| * | |
| * @return 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_BAD_RESPONSE | |
| * - #AWS_IOT_JOBS_TIMEOUT | |
| * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE. | |
| */ | |
| /* @[declare_jobs_startnextsync] */ | |
| AwsIotJobsError_t AwsIotJobs_StartNextSync( const AwsIotJobsRequestInfo_t * pRequestInfo, | |
| const AwsIotJobsUpdateInfo_t * pUpdateInfo, | |
| uint32_t flags, | |
| uint32_t timeoutMs, | |
| AwsIotJobsResponse_t * const pJobsResponse ); | |
| /* @[declare_jobs_startnextsync] */ | |
| /** | |
| * @brief Get detailed information about a job execution and receive an asynchronous | |
| * notification when the response arrives. | |
| * | |
| * This function implements the [DescribeJobExecution] | |
| * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-describejobexecution) | |
| * command of the Jobs API, which gets detailed information about a job execution. | |
| * The description is returned as the `pResponse` member in #AwsIotJobsCallbackParam_t, | |
| * or through the #AwsIotJobsResponse_t parameter of @ref jobs_function_wait. | |
| * | |
| * @param[in] pRequestInfo Jobs request parameters. | |
| * @param[in] executionNumber The execution number to describe. Optional; pass | |
| * #AWS_IOT_JOBS_NO_EXECUTION_NUMBER to ignore. | |
| * @param[in] includeJobDocument Whether the response should include the full | |
| * Job document. | |
| * @param[in] flags Flags which modify the behavior of the Jobs request. See | |
| * @ref jobs_constants_flags. | |
| * @param[in] pCallbackInfo Asynchronous notification of this function's completion. | |
| * @param[out] pDescribeOperation Set to a handle by which this operation may be referenced | |
| * after this function returns. This reference is invalidated once the Jobs operation | |
| * completes. | |
| * | |
| * @return This function will return #AWS_IOT_JOBS_STATUS_PENDING upon successfully | |
| * queuing the Jobs operation. | |
| * @return If this function fails before queuing the Jobs operation, it will return one of: | |
| * - #AWS_IOT_JOBS_NOT_INITIALIZED | |
| * - #AWS_IOT_JOBS_BAD_PARAMETER | |
| * - #AWS_IOT_JOBS_NO_MEMORY | |
| * @return Upon successful completion of the Jobs operation (either through an #AwsIotJobsCallbackInfo_t | |
| * or @ref jobs_function_wait), the status will be #AWS_IOT_JOBS_SUCCESS. | |
| * @return Should the Jobs operation fail, the status will be one of: | |
| * - #AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document) | |
| * - #AWS_IOT_JOBS_MQTT_ERROR | |
| * - #AWS_IOT_JOBS_BAD_RESPONSE | |
| * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE. | |
| * | |
| * @see @ref jobs_function_describesync for a blocking variant of this function. | |
| * | |
| * <b>Example</b> | |
| * @code{c} | |
| * #define THING_NAME "Test_device" | |
| * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 ) | |
| * | |
| * // Signature of Jobs callback function. | |
| * void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam ); | |
| * | |
| * AwsIotJobsOperation_t describeOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER; | |
| * AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER; | |
| * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER; | |
| * | |
| * // Set the request info. | |
| * requestInfo.mqttConnection = _mqttConnection; | |
| * requestInfo.pThingName = THING_NAME; | |
| * requestInfo.thingNameLength = THING_NAME_LENGTH; | |
| * | |
| * // Describe the next Job. Or, this may be set to a specific Job ID. | |
| * requestInfo.pJobId = AWS_IOT_JOBS_NEXT_JOB; | |
| * requestInfo.jobIdLength = AWS_IOT_JOBS_NEXT_JOB_LENGTH; | |
| * | |
| * // Set the callback function to invoke. | |
| * callbackInfo.function = _jobsCallback; | |
| * | |
| * // Queue Jobs DESCRIBE. | |
| * AwsIotJobsError_t describeResult = AwsIotJobs_DescribeAsync( &requestInfo, | |
| * AWS_IOT_JOBS_NO_EXECUTION_NUMBER, | |
| * false, | |
| * 0, | |
| * &callbackInfo, | |
| * &describeOperation ); | |
| * | |
| * // DESCRIBE should have returned AWS_IOT_JOBS_STATUS_PENDING. The function | |
| * // _jobsCallback will be invoked once the Jobs response is received. | |
| * @endcode | |
| */ | |
| /* @[declare_jobs_describeasync] */ | |
| AwsIotJobsError_t AwsIotJobs_DescribeAsync( const AwsIotJobsRequestInfo_t * pRequestInfo, | |
| int32_t executionNumber, | |
| bool includeJobDocument, | |
| uint32_t flags, | |
| const AwsIotJobsCallbackInfo_t * pCallbackInfo, | |
| AwsIotJobsOperation_t * const pDescribeOperation ); | |
| /* @[declare_jobs_describeasync] */ | |
| /** | |
| * @brief Get detailed information about a job execution with a timeout for receiving | |
| * the response. | |
| * | |
| * This function queues a Jobs DESCRIBE, then waits for the result. Internally, | |
| * this function is a call to @ref jobs_function_describeasync followed by | |
| * @ref jobs_function_wait. See @ref jobs_function_describeasync for more information | |
| * on the Jobs DESCRIBE command. | |
| * | |
| * @param[in] pRequestInfo Jobs request parameters. | |
| * @param[in] executionNumber The execution number to describe. Optional; pass | |
| * #AWS_IOT_JOBS_NO_EXECUTION_NUMBER to ignore. | |
| * @param[in] includeJobDocument Whether the response should include the full | |
| * Job document. | |
| * @param[in] flags Flags which modify the behavior of the Jobs request. See | |
| * @ref jobs_constants_flags. | |
| * @param[in] timeoutMs If a response is not received within this timeout, this | |
| * function returns #AWS_IOT_JOBS_TIMEOUT. | |
| * @param[out] pJobsResponse The response received from the Jobs service. | |
| * | |
| * @return 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_BAD_RESPONSE | |
| * - #AWS_IOT_JOBS_TIMEOUT | |
| * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE. | |
| */ | |
| /* @[declare_jobs_describesync] */ | |
| AwsIotJobsError_t AwsIotJobs_DescribeSync( const AwsIotJobsRequestInfo_t * pRequestInfo, | |
| int32_t executionNumber, | |
| bool includeJobDocument, | |
| uint32_t flags, | |
| uint32_t timeoutMs, | |
| AwsIotJobsResponse_t * const pJobsResponse ); | |
| /* @[declare_jobs_describesync] */ | |
| /** | |
| * @brief Update the status of a job execution and receive an asynchronous | |
| * notification when the Job update completes. | |
| * | |
| * This function implements the [UpdateJobExecution] | |
| * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-updatejobexecution) | |
| * command of the Jobs API, which updates the status of a Job execution. | |
| * | |
| * @param[in] pRequestInfo Jobs request parameters. | |
| * @param[in] pUpdateInfo Jobs update parameters. | |
| * @param[in] flags Flags which modify the behavior of the Jobs request. See | |
| * @ref jobs_constants_flags. | |
| * @param[in] pCallbackInfo Asynchronous notification of this function's completion. | |
| * @param[out] pUpdateOperation Set to a handle by which this operation may be referenced | |
| * after this function returns. This reference is invalidated once the Jobs operation | |
| * completes. | |
| * | |
| * @return This function will return #AWS_IOT_JOBS_STATUS_PENDING upon successfully | |
| * queuing the Jobs operation. | |
| * @return If this function fails before queuing the Jobs operation, it will return one of: | |
| * - #AWS_IOT_JOBS_NOT_INITIALIZED | |
| * - #AWS_IOT_JOBS_BAD_PARAMETER | |
| * - #AWS_IOT_JOBS_NO_MEMORY | |
| * @return Upon successful completion of the Jobs operation (either through an #AwsIotJobsCallbackInfo_t | |
| * or @ref jobs_function_wait), the status will be #AWS_IOT_JOBS_SUCCESS. | |
| * @return Should the Jobs operation fail, the status will be one of: | |
| * - #AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document) | |
| * - #AWS_IOT_JOBS_MQTT_ERROR | |
| * - #AWS_IOT_JOBS_BAD_RESPONSE | |
| * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE. | |
| * | |
| * @see @ref jobs_function_updatesync for a blocking variant of this function. | |
| * | |
| * <b>Example</b> | |
| * @code{c} | |
| * #define THING_NAME "Test_device" | |
| * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 ) | |
| * | |
| * // Signature of Jobs callback function. | |
| * void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam ); | |
| * | |
| * AwsIotJobsOperation_t updateOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER; | |
| * AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER; | |
| * AwsIotJobsUpdateInfo_t updateInfo = AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER; | |
| * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER; | |
| * | |
| * // Set the request info. | |
| * requestInfo.mqttConnection = _mqttConnection; | |
| * requestInfo.pThingName = THING_NAME; | |
| * requestInfo.thingNameLength = THING_NAME_LENGTH; | |
| * | |
| * // A Job ID must be set. AWS_IOT_JOBS_NEXT_JOB is not valid for UPDATE. | |
| * requestInfo.pJobId = "job-id"; | |
| * requestInfo.jobIdLength = 6; | |
| * | |
| * // Set the update info. | |
| * updateInfo.newStatus = AWS_IOT_JOB_STATE_SUCCEEDED; | |
| * | |
| * // Set the callback function to invoke. | |
| * callbackInfo.function = _jobsCallback; | |
| * | |
| * // Queue Jobs UPDATE. | |
| * AwsIotJobsError_t updateResult = AwsIotJobs_UpdateAsync( &requestInfo, | |
| * &updateInfo, | |
| * 0, | |
| * &callbackInfo, | |
| * &updateOperation ); | |
| * | |
| * // UPDATE should have returned AWS_IOT_JOBS_STATUS_PENDING. The function | |
| * // _jobsCallback will be invoked once the Jobs response is received. | |
| * @endcode | |
| */ | |
| /* @[declare_jobs_updateasync] */ | |
| AwsIotJobsError_t AwsIotJobs_UpdateAsync( const AwsIotJobsRequestInfo_t * pRequestInfo, | |
| const AwsIotJobsUpdateInfo_t * pUpdateInfo, | |
| uint32_t flags, | |
| const AwsIotJobsCallbackInfo_t * pCallbackInfo, | |
| AwsIotJobsOperation_t * const pUpdateOperation ); | |
| /* @[declare_jobs_updateasync] */ | |
| /** | |
| * @brief Update the status of a job execution with a timeout for receiving the | |
| * response. | |
| * | |
| * This function queues a Jobs UPDATE, then waits for the result. Internally, | |
| * this function is a call to @ref jobs_function_updateasync followed by | |
| * @ref jobs_function_wait. See @ref jobs_function_updateasync for more information | |
| * on the Jobs UPDATE command. | |
| * | |
| * @param[in] pRequestInfo Jobs request parameters. | |
| * @param[in] pUpdateInfo Jobs update parameters. | |
| * @param[in] flags Flags which modify the behavior of the Jobs request. See | |
| * @ref jobs_constants_flags. | |
| * @param[in] timeoutMs If a response is not received within this timeout, this | |
| * function returns #AWS_IOT_JOBS_TIMEOUT. | |
| * @param[out] pJobsResponse The response received from the Jobs service. | |
| * | |
| * @return 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_BAD_RESPONSE | |
| * - #AWS_IOT_JOBS_TIMEOUT | |
| * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE. | |
| */ | |
| /* @[declare_jobs_updatesync] */ | |
| AwsIotJobsError_t AwsIotJobs_UpdateSync( const AwsIotJobsRequestInfo_t * pRequestInfo, | |
| const AwsIotJobsUpdateInfo_t * pUpdateInfo, | |
| uint32_t flags, | |
| uint32_t timeoutMs, | |
| AwsIotJobsResponse_t * const pJobsResponse ); | |
| /* @[declare_jobs_updatesync] */ | |
| /** | |
| * @brief Wait for a Jobs operation to complete. | |
| * | |
| * This function blocks to wait for a [GET PENDING](@ref jobs_function_getpendingasync), | |
| * [START NEXT](@ref jobs_function_startnextasync), [DESCRIBE](@ref jobs_function_describeasync), | |
| * or [UPDATE](@ref jobs_function_updateasync) operation to complete. These operations are | |
| * by default asynchronous; the function calls queue an operation for processing, | |
| * and a callback is invoked once the operation is complete. | |
| * | |
| * To use this function, the flag #AWS_IOT_JOBS_FLAG_WAITABLE must have been | |
| * set in the operation's function call. Additionally, this function must always | |
| * be called with any waitable operation to clean up resources. | |
| * | |
| * Regardless of its return value, this function always clean up resources used | |
| * by the waitable operation. This means `operation` is invalidated as soon as | |
| * this function returns, even if it returns #AWS_IOT_JOBS_TIMEOUT or another | |
| * error. | |
| * | |
| * @param[in] operation Reference to the Jobs operation to wait for. The flag | |
| * #AWS_IOT_JOBS_FLAG_WAITABLE must have been set for this operation. | |
| * @param[in] timeoutMs How long to wait before returning #AWS_IOT_JOBS_TIMEOUT. | |
| * @param[out] pJobsResponse The response received from the Jobs service. | |
| * | |
| * @return One of the following: | |
| * - #AWS_IOT_JOBS_SUCCESS | |
| * - #AWS_IOT_JOBS_NOT_INITIALIZED | |
| * - #AWS_IOT_JOBS_BAD_PARAMETER | |
| * - #AWS_IOT_JOBS_BAD_RESPONSE | |
| * - #AWS_IOT_JOBS_TIMEOUT | |
| * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE. | |
| * | |
| * <b>Example</b>: | |
| * @code{c} | |
| * #define THING_NAME "Test_device" | |
| * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 ) | |
| * | |
| * AwsIotJobsOperation_t updateOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER; | |
| * AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER; | |
| * AwsIotJobsUpdateInfo_t updateInfo = AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER; | |
| * AwsIotJobsResponse_t jobsResponse = AWS_IOT_JOBS_RESPONSE_INITIALIZER; | |
| * | |
| * // Set the request info. | |
| * requestInfo.mqttConnection = _mqttConnection; | |
| * requestInfo.pThingName = THING_NAME; | |
| * requestInfo.thingNameLength = THING_NAME_LENGTH; | |
| * | |
| * // Set the function used to allocate memory for an incoming response. | |
| * requestInfo.mallocResponse = malloc; | |
| * | |
| * // A Job ID must be set. AWS_IOT_JOBS_NEXT_JOB is not valid for UPDATE. | |
| * requestInfo.pJobId = "job-id"; | |
| * requestInfo.jobIdLength = 6; | |
| * | |
| * // Set the update info. | |
| * updateInfo.newStatus = AWS_IOT_JOB_STATE_SUCCEEDED; | |
| * | |
| * // Queue Jobs UPDATE. | |
| * AwsIotJobsError_t updateResult = AwsIotJobs_UpdateAsync( &requestInfo, | |
| * &updateInfo, | |
| * AWS_IOT_JOBS_FLAG_WAITABLE, | |
| * NULL, | |
| * &updateOperation ); | |
| * | |
| * // UPDATE should have returned AWS_IOT_JOBS_STATUS_PENDING. The call to wait | |
| * // returns once the result of the UPDATE is available or the timeout expires. | |
| * if( updateResult == AWS_IOT_JOBS_STATUS_PENDING ) | |
| * { | |
| * updateResult = AwsIotJobs_Wait( updateOperation, 5000, &jobsResponse ); | |
| * | |
| * if( updateResult == AWS_IOT_JOBS_SUCCESS ) | |
| * { | |
| * // Jobs operation succeeded. Do something with the Jobs response. | |
| * | |
| * // Once the Jobs response is no longer needed, free it. | |
| * free( jobsResponse.pJobsResponse ); | |
| * } | |
| * else | |
| * { | |
| * // Jobs operation failed. | |
| * } | |
| * } | |
| * @endcode | |
| */ | |
| /* @[declare_jobs_wait] */ | |
| AwsIotJobsError_t AwsIotJobs_Wait( AwsIotJobsOperation_t operation, | |
| uint32_t timeoutMs, | |
| AwsIotJobsResponse_t * const pJobsResponse ); | |
| /* @[declare_jobs_wait] */ | |
| /** | |
| * @brief Set a callback to be invoked when the list of pending Jobs changes. | |
| * | |
| * The Jobs service publishes a [JobExecutionsChanged] | |
| * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-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 <i>NOTIFY PENDING</i> callback may be invoked whenever a message is published | |
| * to `jobs/notify`. Each Thing may have up to @ref 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 @ref AwsIotJobsCallbackInfo_t.oldFunction must be used to select an | |
| * already-registered callback function for replacement or removal when @ref | |
| * 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. | |
| * | |
| * @param[in] mqttConnection The MQTT connection to use for the subscription to `jobs/notify`. | |
| * @param[in] pThingName The subscription to `jobs/notify` will be added for | |
| * this Thing Name. | |
| * @param[in] thingNameLength The length of `pThingName`. | |
| * @param[in] flags This parameter is for future-compatibility. Currently, flags are | |
| * not supported for this function and this parameter is ignored. | |
| * @param[in] pNotifyPendingCallback Callback function to invoke for incoming messages. | |
| * | |
| * @return 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 @ref jobs_function_setnotifynextcallback for the function to register callbacks | |
| * for next Job changes. | |
| * | |
| * <b>Example</b>: | |
| * @code{c} | |
| * #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, | |
| * ¬ifyPendingCallback ); | |
| * | |
| * // 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, | |
| * ¬ifyPendingCallback ); | |
| * | |
| * // The return value from removing a callback should always be success. | |
| * assert( status == AWS_IOT_JOBS_SUCCESS ); | |
| * } | |
| * @endcode | |
| */ | |
| /* @[declare_jobs_setnotifypendingcallback] */ | |
| AwsIotJobsError_t AwsIotJobs_SetNotifyPendingCallback( IotMqttConnection_t mqttConnection, | |
| const char * pThingName, | |
| size_t thingNameLength, | |
| uint32_t flags, | |
| const AwsIotJobsCallbackInfo_t * pNotifyPendingCallback ); | |
| /* @[declare_jobs_setnotifypendingcallback] */ | |
| /** | |
| * @brief Set a callback to be invoked when the next pending Job changes. | |
| * | |
| * The Jobs service publishes a [NextJobExecutionChanged] | |
| * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-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 <i>NOTIFY NEXT</i> callback may be invoked whenever a message is published | |
| * to `jobs/notify-next`. Each Thing may have up to @ref 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 @ref AwsIotJobsCallbackInfo_t.oldFunction must be used to select an | |
| * already-registered callback function for replacement or removal when @ref | |
| * 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. | |
| * | |
| * @param[in] mqttConnection The MQTT connection to use for the subscription to `jobs/notify-next`. | |
| * @param[in] pThingName The subscription to `jobs/notify-next` will be added for | |
| * this Thing Name. | |
| * @param[in] thingNameLength The length of `pThingName`. | |
| * @param[in] flags This parameter is for future-compatibility. Currently, flags are | |
| * not supported for this function and this parameter is ignored. | |
| * @param[in] pNotifyNextCallback Callback function to invoke for incoming messages. | |
| * | |
| * @return 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 @ref jobs_function_setnotifypendingcallback for the function to register callbacks | |
| * for all pending Job changes. | |
| * | |
| * <b>Example</b>: | |
| * @code{c} | |
| * #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, | |
| * ¬ifyNextCallback ); | |
| * | |
| * // 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, | |
| * ¬ifyNextCallback ); | |
| * | |
| * // The return value from removing a callback should always be success. | |
| * assert( status == AWS_IOT_JOBS_SUCCESS ); | |
| * } | |
| * @endcode | |
| */ | |
| /* @[declare_jobs_setnotifynextcallback] */ | |
| AwsIotJobsError_t AwsIotJobs_SetNotifyNextCallback( IotMqttConnection_t mqttConnection, | |
| const char * pThingName, | |
| size_t thingNameLength, | |
| uint32_t flags, | |
| const AwsIotJobsCallbackInfo_t * pNotifyNextCallback ); | |
| /* @[declare_jobs_setnotifynextcallback] */ | |
| /** | |
| * @brief Remove persistent Jobs operation topic subscriptions. | |
| * | |
| * Passing the flag @ref AWS_IOT_JOBS_FLAG_KEEP_SUBSCRIPTIONS to @ref jobs_function_getpendingasync, | |
| * @ref jobs_function_startnextasync, @ref jobs_function_describeasync, @ref jobs_function_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. | |
| * | |
| * @param[in] pRequestInfo Jobs request info. Only the [pThingName] | |
| * (@ref #AwsIotJobsRequestInfo_t.pThingName), [thingNameLength] | |
| * (@ref #AwsIotJobsRequestInfo_t.thingNameLength), and [mqttConnection] | |
| * (@ref #AwsIotJobsRequestInfo_t.mqttConnection) members need to be set for this | |
| * function. | |
| * @param[in] flags Flags that determine which subscriptions to remove. Valid values are | |
| * the bitwise OR of the following individual flags: | |
| * - @ref AWS_IOT_JOBS_FLAG_REMOVE_GET_PENDING_SUBSCRIPTIONS | |
| * - @ref AWS_IOT_JOBS_FLAG_REMOVE_START_NEXT_SUBSCRIPTIONS | |
| * - @ref AWS_IOT_JOBS_FLAG_REMOVE_DESCRIBE_SUBSCRIPTIONS | |
| * - @ref AWS_IOT_JOBS_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS | |
| * | |
| * @return On success: | |
| * - #AWS_IOT_JOBS_SUCCESS | |
| * @return If an MQTT UNSUBSCRIBE packet cannot be sent, one of the following: | |
| * - #AWS_IOT_JOBS_NO_MEMORY | |
| * - #AWS_IOT_JOBS_MQTT_ERROR | |
| * | |
| * @note @ref jobs_function_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 @ref jobs_function_setnotifypendingcallback and | |
| * @ref jobs_function_setnotifynextcallback, respectively. (See documentation for | |
| * those functions on how to remove their callbacks). | |
| */ | |
| /* @[declare_jobs_removepersistentsubscriptions] */ | |
| AwsIotJobsError_t AwsIotJobs_RemovePersistentSubscriptions( const AwsIotJobsRequestInfo_t * pRequestInfo, | |
| uint32_t flags ); | |
| /* @[declare_jobs_removepersistentsubscriptions] */ | |
| /*-------------------------- Jobs helper functions --------------------------*/ | |
| /** | |
| * @brief Returns a string that describes an #AwsIotJobsError_t. | |
| * | |
| * Like POSIX's `strerror`, this function returns a string describing a return | |
| * code. In this case, the return code is a Jobs library error code, `status`. | |
| * | |
| * The string returned by this function <b>MUST</b> be treated as read-only: any | |
| * attempt to modify its contents may result in a crash. Therefore, this function | |
| * is limited to usage in logging. | |
| * | |
| * @param[in] status The status to describe. | |
| * | |
| * @return A read-only string that describes `status`. | |
| * | |
| * @warning The string returned by this function must never be modified. | |
| */ | |
| /* @[declare_jobs_strerror] */ | |
| const char * AwsIotJobs_strerror( AwsIotJobsError_t status ); | |
| /* @[declare_jobs_strerror] */ | |
| /** | |
| * @brief Returns a string that describes an #AwsIotJobState_t. | |
| * | |
| * This function returns a string describing a Job state, `state`. | |
| * | |
| * The string returned by this function <b>MUST</b> be treated as read-only: any | |
| * attempt to modify its contents may result in a crash. Therefore, this function | |
| * is limited to usage in logging. | |
| * | |
| * @param[in] state The job state to describe. | |
| * | |
| * @return A read-only string that describes `state`. | |
| * | |
| * @warning The string returned by this function must never be modified. | |
| */ | |
| /* @[declare_jobs_statename] */ | |
| const char * AwsIotJobs_StateName( AwsIotJobState_t state ); | |
| /* @[declare_jobs_statename] */ | |
| #endif /* ifndef AWS_IOT_JOBS_H_ */ |