git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/FreeRTOS-IoT-Libraries/c_sdk/aws/jobs/include/aws_iot_jobs.h

   1 /*\r
   2  * AWS IoT Jobs V1.0.0\r
   3  * Copyright (C) 2019 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  */\r
  22 \r
  23 /**\r
  24  * @file aws_iot_jobs.h\r
  25  * @brief User-facing functions of the Jobs library.\r
  26  */\r
  27 \r
  28 #ifndef AWS_IOT_JOBS_H_\r
  29 #define AWS_IOT_JOBS_H_\r
  30 \r
  31 /* The config header is always included first. */\r
  32 #include "iot_config.h"\r
  33 \r
  34 /* Jobs types include. */\r
  35 #include "types/aws_iot_jobs_types.h"\r
  36 \r
  37 /*------------------------- Jobs library functions --------------------------*/\r
  38 \r
  39 /**\r
  40  * @functionspage{jobs,Jobs library}\r
  41  * - @functionname{jobs_function_init}\r
  42  * - @functionname{jobs_function_cleanup}\r
  43  * - @functionname{jobs_function_getpendingasync}\r
  44  * - @functionname{jobs_function_getpendingsync}\r
  45  * - @functionname{jobs_function_startnextasync}\r
  46  * - @functionname{jobs_function_startnextsync}\r
  47  * - @functionname{jobs_function_describeasync}\r
  48  * - @functionname{jobs_function_describesync}\r
  49  * - @functionname{jobs_function_updateasync}\r
  50  * - @functionname{jobs_function_updatesync}\r
  51  * - @functionname{jobs_function_wait}\r
  52  * - @functionname{jobs_function_setnotifypendingcallback}\r
  53  * - @functionname{jobs_function_setnotifynextcallback}\r
  54  * - @functionname{jobs_function_removepersistentsubscriptions}\r
  55  * - @functionname{jobs_function_strerror}\r
  56  * - @functionname{jobs_function_statename}\r
  57  */\r
  58 \r
  59 /**\r
  60  * @functionpage{AwsIotJobs_Init,jobs,init}\r
  61  * @functionpage{AwsIotJobs_Cleanup,jobs,cleanup}\r
  62  * @functionpage{AwsIotJobs_GetPendingAsync,jobs,getpendingasync}\r
  63  * @functionpage{AwsIotJobs_GetPendingSync,jobs,getpendingsync}\r
  64  * @functionpage{AwsIotJobs_StartNextAsync,jobs,startnextasync}\r
  65  * @functionpage{AwsIotJobs_StartNextSync,jobs,startnextsync}\r
  66  * @functionpage{AwsIotJobs_DescribeAsync,jobs,describeasync}\r
  67  * @functionpage{AwsIotJobs_DescribeSync,jobs,describesync}\r
  68  * @functionpage{AwsIotJobs_UpdateAsync,jobs,updateasync}\r
  69  * @functionpage{AwsIotJobs_UpdateSync,jobs,updatesync}\r
  70  * @functionpage{AwsIotJobs_Wait,jobs,wait}\r
  71  * @functionpage{AwsIotJobs_SetNotifyPendingCallback,jobs,setnotifypendingcallback}\r
  72  * @functionpage{AwsIotJobs_SetNotifyNextCallback,jobs,setnotifynextcallback}\r
  73  * @functionpage{AwsIotJobs_RemovePersistentSubscriptions,jobs,removepersistentsubscriptions}\r
  74  * @functionpage{AwsIotJobs_strerror,jobs,strerror}\r
  75  * @functionpage{AwsIotJobs_StateName,jobs,statename}\r
  76  */\r
  77 \r
  78 /**\r
  79  * @brief One-time initialization function for the Jobs library.\r
  80  *\r
  81  * This function performs internal setup of the Jobs library. <b>It must be\r
  82  * called once (and only once) before calling any other Jobs function.</b>\r
  83  * Calling this function more than once without first calling @ref\r
  84  * jobs_function_cleanup may result in a crash.\r
  85  *\r
  86  * @param[in] mqttTimeoutMs The amount of time (in milliseconds) that the Jobs\r
  87  * library will wait for MQTT operations. Optional; set this to `0` to use\r
  88  * @ref AWS_IOT_JOBS_DEFAULT_MQTT_TIMEOUT_MS.\r
  89  *\r
  90  * @return One of the following:\r
  91  * - #AWS_IOT_JOBS_SUCCESS\r
  92  * - #AWS_IOT_JOBS_INIT_FAILED\r
  93  *\r
  94  * @warning No thread-safety guarantees are provided for this function.\r
  95  *\r
  96  * @see @ref jobs_function_cleanup\r
  97  */\r
  98 /* @[declare_jobs_init] */\r
  99 AwsIotJobsError_t AwsIotJobs_Init( uint32_t mqttTimeoutMs );\r
 100 /* @[declare_jobs_init] */\r
 101 \r
 102 /**\r
 103  * @brief One-time deinitialization function for the Jobs library.\r
 104  *\r
 105  * This function frees resources taken in @ref jobs_function_init and deletes\r
 106  * any [persistent subscriptions.](@ref AWS_IOT_JOBS_FLAG_KEEP_SUBSCRIPTIONS)\r
 107  * It should be called to clean up the Jobs library. After this function returns,\r
 108  * @ref jobs_function_init must be called again before calling any other Jobs\r
 109  * function.\r
 110  *\r
 111  * @warning No thread-safety guarantees are provided for this function.\r
 112  *\r
 113  * @see @ref jobs_function_init\r
 114  */\r
 115 /* @[declare_jobs_cleanup] */\r
 116 void AwsIotJobs_Cleanup( void );\r
 117 /* @[declare_jobs_cleanup] */\r
 118 \r
 119 /**\r
 120  * @brief Get the list of all pending jobs for a Thing and receive an asynchronous\r
 121  * notification when the response arrives.\r
 122  *\r
 123  * This function implements the [GetPendingJobExecutions]\r
 124  * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-getpendingjobexecutions)\r
 125  * command of the Jobs API, which gets the list of all Jobs for a Thing that are\r
 126  * not in a terminal state. The list of retrieved Jobs is returned as the `pResponse`\r
 127  * member in #AwsIotJobsCallbackParam_t, or through the #AwsIotJobsResponse_t\r
 128  * parameter of @ref jobs_function_wait.\r
 129  *\r
 130  * @param[in] pRequestInfo Jobs request parameters.\r
 131  * @param[in] flags Flags which modify the behavior of the Jobs request. See\r
 132  * @ref jobs_constants_flags.\r
 133  * @param[in] pCallbackInfo Asynchronous notification of this function's completion.\r
 134  * @param[out] pGetPendingOperation Set to a handle by which this operation may be referenced\r
 135  * after this function returns. This reference is invalidated once the Jobs operation\r
 136  * completes.\r
 137  *\r
 138  * @return This function will return #AWS_IOT_JOBS_STATUS_PENDING upon successfully\r
 139  * queuing the Jobs operation.\r
 140  * @return If this function fails before queuing the Jobs operation, it will return one of:\r
 141  * - #AWS_IOT_JOBS_NOT_INITIALIZED\r
 142  * - #AWS_IOT_JOBS_BAD_PARAMETER\r
 143  * - #AWS_IOT_JOBS_NO_MEMORY\r
 144  * @return Upon successful completion of the Jobs operation (either through an #AwsIotJobsCallbackInfo_t\r
 145  * or @ref jobs_function_wait), the status will be #AWS_IOT_JOBS_SUCCESS.\r
 146  * @return Should the Jobs operation fail, the status will be one of:\r
 147  * - #AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document)\r
 148  * - #AWS_IOT_JOBS_MQTT_ERROR\r
 149  * - #AWS_IOT_JOBS_BAD_RESPONSE\r
 150  * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE.\r
 151  *\r
 152  * @see @ref jobs_function_getpendingsync for a blocking variant of this function.\r
 153  *\r
 154  * <b>Example</b>\r
 155  * @code{c}\r
 156  * #define THING_NAME "Test_device"\r
 157  * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )\r
 158  *\r
 159  * // Signature of Jobs callback function.\r
 160  * void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam );\r
 161  *\r
 162  * AwsIotJobsOperation_t getPendingOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER;\r
 163  * AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER;\r
 164  * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;\r
 165  *\r
 166  * // Set the request info.\r
 167  * requestInfo.mqttConnection = _mqttConnection;\r
 168  * requestInfo.pThingName = THING_NAME;\r
 169  * requestInfo.thingNameLength = THING_NAME_LENGTH;\r
 170  *\r
 171  * // Set the callback function to invoke.\r
 172  * callbackInfo.function = _jobsCallback;\r
 173  *\r
 174  * // Queue Jobs GET PENDING.\r
 175  * AwsIotJobsError_t getPendingResult = AwsIotJobs_GetPendingAsync( &requestInfo,\r
 176  *                                                                  0,\r
 177  *                                                                  &callbackInfo,\r
 178  *                                                                  &getPendingOperation );\r
 179  *\r
 180  * // GET PENDING should have returned AWS_IOT_JOBS_STATUS_PENDING. The function\r
 181  * // _jobsCallback will be invoked once the Jobs response is received.\r
 182  * @endcode\r
 183  */\r
 184 /* @[declare_jobs_getpendingasync] */\r
 185 AwsIotJobsError_t AwsIotJobs_GetPendingAsync( const AwsIotJobsRequestInfo_t * pRequestInfo,\r
 186                                               uint32_t flags,\r
 187                                               const AwsIotJobsCallbackInfo_t * pCallbackInfo,\r
 188                                               AwsIotJobsOperation_t * const pGetPendingOperation );\r
 189 /* @[declare_jobs_getpendingasync] */\r
 190 \r
 191 /**\r
 192  * @brief Get the list of all pending jobs for a Thing with a timeout for receiving\r
 193  * the response.\r
 194  *\r
 195  * This function queues a Jobs GET PENDING, then waits for the result. Internally,\r
 196  * this function is a call to @ref jobs_function_getpendingasync followed by\r
 197  * @ref jobs_function_wait. See @ref jobs_function_getpendingasync for more information\r
 198  * on the Jobs GET PENDING command.\r
 199  *\r
 200  * @param[in] pRequestInfo Jobs request parameters.\r
 201  * @param[in] flags Flags which modify the behavior of the Jobs request. See\r
 202  * @ref jobs_constants_flags.\r
 203  * @param[in] timeoutMs If a response is not received within this timeout, this\r
 204  * function returns #AWS_IOT_JOBS_TIMEOUT.\r
 205  * @param[out] pJobsResponse The response received from the Jobs service.\r
 206  *\r
 207  * @return One of the following:\r
 208  * - #AWS_IOT_JOBS_SUCCESS\r
 209  * - #AWS_IOT_JOBS_NOT_INITIALIZED\r
 210  * - #AWS_IOT_JOBS_BAD_PARAMETER\r
 211  * - #AWS_IOT_JOBS_NO_MEMORY\r
 212  * - #AWS_IOT_JOBS_MQTT_ERROR\r
 213  * - #AWS_IOT_JOBS_BAD_RESPONSE\r
 214  * - #AWS_IOT_JOBS_TIMEOUT\r
 215  * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE.\r
 216  */\r
 217 /* @[declare_jobs_getpendingsync] */\r
 218 AwsIotJobsError_t AwsIotJobs_GetPendingSync( const AwsIotJobsRequestInfo_t * pRequestInfo,\r
 219                                              uint32_t flags,\r
 220                                              uint32_t timeoutMs,\r
 221                                              AwsIotJobsResponse_t * const pJobsResponse );\r
 222 /* @[declare_jobs_getpendingsync] */\r
 223 \r
 224 /**\r
 225  * @brief Start the next pending job execution for a Thing and receive an asynchronous\r
 226  * notification when the response arrives.\r
 227  *\r
 228  * This function implements the [StartNextPendingJobExecution]\r
 229  * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-startnextpendingjobexecution)\r
 230  * command of the Jobs API, which gets and starts the next pending job execution\r
 231  * for a Thing.\r
 232  *\r
 233  * @param[in] pRequestInfo Jobs request parameters.\r
 234  * @param[in] pUpdateInfo Jobs update parameters.\r
 235  * @param[in] flags Flags which modify the behavior of the Jobs request. See\r
 236  * @ref jobs_constants_flags.\r
 237  * @param[in] pCallbackInfo Asynchronous notification of this function's completion.\r
 238  * @param[out] pStartNextOperation Set to a handle by which this operation may be referenced\r
 239  * after this function returns. This reference is invalidated once the Jobs operation\r
 240  * completes.\r
 241  *\r
 242  * @return This function will return #AWS_IOT_JOBS_STATUS_PENDING upon successfully\r
 243  * queuing the Jobs operation.\r
 244  * @return If this function fails before queuing the Jobs operation, it will return one of:\r
 245  * - #AWS_IOT_JOBS_NOT_INITIALIZED\r
 246  * - #AWS_IOT_JOBS_BAD_PARAMETER\r
 247  * - #AWS_IOT_JOBS_NO_MEMORY\r
 248  * @return Upon successful completion of the Jobs operation (either through an #AwsIotJobsCallbackInfo_t\r
 249  * or @ref jobs_function_wait), the status will be #AWS_IOT_JOBS_SUCCESS.\r
 250  * @return Should the Jobs operation fail, the status will be one of:\r
 251  * - #AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document)\r
 252  * - #AWS_IOT_JOBS_MQTT_ERROR\r
 253  * - #AWS_IOT_JOBS_BAD_RESPONSE\r
 254  * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE.\r
 255  *\r
 256  * @see @ref jobs_function_startnextsync for a blocking variant of this function.\r
 257  *\r
 258  * <b>Example</b>\r
 259  * @code{c}\r
 260  * #define THING_NAME "Test_device"\r
 261  * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )\r
 262  *\r
 263  * // Signature of Jobs callback function.\r
 264  * void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam );\r
 265  *\r
 266  * AwsIotJobsOperation_t startNextOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER;\r
 267  * AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER;\r
 268  * AwsIotJobsUpdateInfo_t updateInfo = AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER;\r
 269  * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;\r
 270  *\r
 271  * // Set the request info. The update info generally does not need to be\r
 272  * // changed, as its defaults are suitable.\r
 273  * requestInfo.mqttConnection = _mqttConnection;\r
 274  * requestInfo.pThingName = THING_NAME;\r
 275  * requestInfo.thingNameLength = THING_NAME_LENGTH;\r
 276  *\r
 277  * // Set the callback function to invoke.\r
 278  * callbackInfo.function = _jobsCallback;\r
 279  *\r
 280  * // Queue Jobs START NEXT.\r
 281  * AwsIotJobsError_t startNextResult = AwsIotJobs_StartNextAsync( &requestInfo,\r
 282  *                                                                &updateInfo,\r
 283  *                                                                0,\r
 284  *                                                                &callbackInfo,\r
 285  *                                                                &startNextOperation );\r
 286  *\r
 287  * // START NEXT should have returned AWS_IOT_JOBS_STATUS_PENDING. The function\r
 288  * // _jobsCallback will be invoked once the Jobs response is received.\r
 289  * @endcode\r
 290  */\r
 291 /* @[declare_jobs_startnextasync] */\r
 292 AwsIotJobsError_t AwsIotJobs_StartNextAsync( const AwsIotJobsRequestInfo_t * pRequestInfo,\r
 293                                              const AwsIotJobsUpdateInfo_t * pUpdateInfo,\r
 294                                              uint32_t flags,\r
 295                                              const AwsIotJobsCallbackInfo_t * pCallbackInfo,\r
 296                                              AwsIotJobsOperation_t * const pStartNextOperation );\r
 297 /* @[declare_jobs_startnextasync] */\r
 298 \r
 299 /**\r
 300  * @brief Start the next pending job execution for a Thing with a timeout for\r
 301  * receiving the response.\r
 302  *\r
 303  * This function queues a Jobs START NEXT, then waits for the result. Internally,\r
 304  * this function is a call to @ref jobs_function_startnextasync followed by\r
 305  * @ref jobs_function_wait. See @ref jobs_function_startnextasync for more information\r
 306  * on the Jobs START NEXT command.\r
 307  *\r
 308  * @param[in] pRequestInfo Jobs request parameters.\r
 309  * @param[in] pUpdateInfo Jobs update parameters.\r
 310  * @param[in] flags Flags which modify the behavior of the Jobs request. See\r
 311  * @ref jobs_constants_flags.\r
 312  * @param[in] timeoutMs If a response is not received within this timeout, this\r
 313  * function returns #AWS_IOT_JOBS_TIMEOUT.\r
 314  * @param[out] pJobsResponse The response received from the Jobs service.\r
 315  *\r
 316  * @return One of the following:\r
 317  * - #AWS_IOT_JOBS_SUCCESS\r
 318  * - #AWS_IOT_JOBS_NOT_INITIALIZED\r
 319  * - #AWS_IOT_JOBS_BAD_PARAMETER\r
 320  * - #AWS_IOT_JOBS_NO_MEMORY\r
 321  * - #AWS_IOT_JOBS_MQTT_ERROR\r
 322  * - #AWS_IOT_JOBS_BAD_RESPONSE\r
 323  * - #AWS_IOT_JOBS_TIMEOUT\r
 324  * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE.\r
 325  */\r
 326 /* @[declare_jobs_startnextsync] */\r
 327 AwsIotJobsError_t AwsIotJobs_StartNextSync( const AwsIotJobsRequestInfo_t * pRequestInfo,\r
 328                                             const AwsIotJobsUpdateInfo_t * pUpdateInfo,\r
 329                                             uint32_t flags,\r
 330                                             uint32_t timeoutMs,\r
 331                                             AwsIotJobsResponse_t * const pJobsResponse );\r
 332 /* @[declare_jobs_startnextsync] */\r
 333 \r
 334 /**\r
 335  * @brief Get detailed information about a job execution and receive an asynchronous\r
 336  * notification when the response arrives.\r
 337  *\r
 338  * This function implements the [DescribeJobExecution]\r
 339  * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-describejobexecution)\r
 340  * command of the Jobs API, which gets detailed information about a job execution.\r
 341  * The description is returned as the `pResponse` member in #AwsIotJobsCallbackParam_t,\r
 342  * or through the #AwsIotJobsResponse_t parameter of @ref jobs_function_wait.\r
 343  *\r
 344  * @param[in] pRequestInfo Jobs request parameters.\r
 345  * @param[in] executionNumber The execution number to describe. Optional; pass\r
 346  * #AWS_IOT_JOBS_NO_EXECUTION_NUMBER to ignore.\r
 347  * @param[in] includeJobDocument Whether the response should include the full\r
 348  * Job document.\r
 349  * @param[in] flags Flags which modify the behavior of the Jobs request. See\r
 350  * @ref jobs_constants_flags.\r
 351  * @param[in] pCallbackInfo Asynchronous notification of this function's completion.\r
 352  * @param[out] pDescribeOperation Set to a handle by which this operation may be referenced\r
 353  * after this function returns. This reference is invalidated once the Jobs operation\r
 354  * completes.\r
 355  *\r
 356  * @return This function will return #AWS_IOT_JOBS_STATUS_PENDING upon successfully\r
 357  * queuing the Jobs operation.\r
 358  * @return If this function fails before queuing the Jobs operation, it will return one of:\r
 359  * - #AWS_IOT_JOBS_NOT_INITIALIZED\r
 360  * - #AWS_IOT_JOBS_BAD_PARAMETER\r
 361  * - #AWS_IOT_JOBS_NO_MEMORY\r
 362  * @return Upon successful completion of the Jobs operation (either through an #AwsIotJobsCallbackInfo_t\r
 363  * or @ref jobs_function_wait), the status will be #AWS_IOT_JOBS_SUCCESS.\r
 364  * @return Should the Jobs operation fail, the status will be one of:\r
 365  * - #AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document)\r
 366  * - #AWS_IOT_JOBS_MQTT_ERROR\r
 367  * - #AWS_IOT_JOBS_BAD_RESPONSE\r
 368  * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE.\r
 369  *\r
 370  * @see @ref jobs_function_describesync for a blocking variant of this function.\r
 371  *\r
 372  * <b>Example</b>\r
 373  * @code{c}\r
 374  * #define THING_NAME "Test_device"\r
 375  * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )\r
 376  *\r
 377  * // Signature of Jobs callback function.\r
 378  * void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam );\r
 379  *\r
 380  * AwsIotJobsOperation_t describeOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER;\r
 381  * AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER;\r
 382  * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;\r
 383  *\r
 384  * // Set the request info.\r
 385  * requestInfo.mqttConnection = _mqttConnection;\r
 386  * requestInfo.pThingName = THING_NAME;\r
 387  * requestInfo.thingNameLength = THING_NAME_LENGTH;\r
 388  *\r
 389  * // Describe the next Job. Or, this may be set to a specific Job ID.\r
 390  * requestInfo.pJobId = AWS_IOT_JOBS_NEXT_JOB;\r
 391  * requestInfo.jobIdLength = AWS_IOT_JOBS_NEXT_JOB_LENGTH;\r
 392  *\r
 393  * // Set the callback function to invoke.\r
 394  * callbackInfo.function = _jobsCallback;\r
 395  *\r
 396  * // Queue Jobs DESCRIBE.\r
 397  * AwsIotJobsError_t describeResult = AwsIotJobs_DescribeAsync( &requestInfo,\r
 398  *                                                              AWS_IOT_JOBS_NO_EXECUTION_NUMBER,\r
 399  *                                                              false,\r
 400  *                                                              0,\r
 401  *                                                              &callbackInfo,\r
 402  *                                                              &describeOperation );\r
 403  *\r
 404  * // DESCRIBE should have returned AWS_IOT_JOBS_STATUS_PENDING. The function\r
 405  * // _jobsCallback will be invoked once the Jobs response is received.\r
 406  * @endcode\r
 407  */\r
 408 /* @[declare_jobs_describeasync] */\r
 409 AwsIotJobsError_t AwsIotJobs_DescribeAsync( const AwsIotJobsRequestInfo_t * pRequestInfo,\r
 410                                             int32_t executionNumber,\r
 411                                             bool includeJobDocument,\r
 412                                             uint32_t flags,\r
 413                                             const AwsIotJobsCallbackInfo_t * pCallbackInfo,\r
 414                                             AwsIotJobsOperation_t * const pDescribeOperation );\r
 415 /* @[declare_jobs_describeasync] */\r
 416 \r
 417 /**\r
 418  * @brief Get detailed information about a job execution with a timeout for receiving\r
 419  * the response.\r
 420  *\r
 421  * This function queues a Jobs DESCRIBE, then waits for the result. Internally,\r
 422  * this function is a call to @ref jobs_function_describeasync followed by\r
 423  * @ref jobs_function_wait. See @ref jobs_function_describeasync for more information\r
 424  * on the Jobs DESCRIBE command.\r
 425  *\r
 426  * @param[in] pRequestInfo Jobs request parameters.\r
 427  * @param[in] executionNumber The execution number to describe. Optional; pass\r
 428  * #AWS_IOT_JOBS_NO_EXECUTION_NUMBER to ignore.\r
 429  * @param[in] includeJobDocument Whether the response should include the full\r
 430  * Job document.\r
 431  * @param[in] flags Flags which modify the behavior of the Jobs request. See\r
 432  * @ref jobs_constants_flags.\r
 433  * @param[in] timeoutMs If a response is not received within this timeout, this\r
 434  * function returns #AWS_IOT_JOBS_TIMEOUT.\r
 435  * @param[out] pJobsResponse The response received from the Jobs service.\r
 436  *\r
 437  * @return One of the following:\r
 438  * - #AWS_IOT_JOBS_SUCCESS\r
 439  * - #AWS_IOT_JOBS_NOT_INITIALIZED\r
 440  * - #AWS_IOT_JOBS_BAD_PARAMETER\r
 441  * - #AWS_IOT_JOBS_NO_MEMORY\r
 442  * - #AWS_IOT_JOBS_MQTT_ERROR\r
 443  * - #AWS_IOT_JOBS_BAD_RESPONSE\r
 444  * - #AWS_IOT_JOBS_TIMEOUT\r
 445  * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE.\r
 446  */\r
 447 /* @[declare_jobs_describesync] */\r
 448 AwsIotJobsError_t AwsIotJobs_DescribeSync( const AwsIotJobsRequestInfo_t * pRequestInfo,\r
 449                                            int32_t executionNumber,\r
 450                                            bool includeJobDocument,\r
 451                                            uint32_t flags,\r
 452                                            uint32_t timeoutMs,\r
 453                                            AwsIotJobsResponse_t * const pJobsResponse );\r
 454 /* @[declare_jobs_describesync] */\r
 455 \r
 456 /**\r
 457  * @brief Update the status of a job execution and receive an asynchronous\r
 458  * notification when the Job update completes.\r
 459  *\r
 460  * This function implements the [UpdateJobExecution]\r
 461  * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-updatejobexecution)\r
 462  * command of the Jobs API, which updates the status of a Job execution.\r
 463  *\r
 464  * @param[in] pRequestInfo Jobs request parameters.\r
 465  * @param[in] pUpdateInfo Jobs update parameters.\r
 466  * @param[in] flags Flags which modify the behavior of the Jobs request. See\r
 467  * @ref jobs_constants_flags.\r
 468  * @param[in] pCallbackInfo Asynchronous notification of this function's completion.\r
 469  * @param[out] pUpdateOperation Set to a handle by which this operation may be referenced\r
 470  * after this function returns. This reference is invalidated once the Jobs operation\r
 471  * completes.\r
 472  *\r
 473  * @return This function will return #AWS_IOT_JOBS_STATUS_PENDING upon successfully\r
 474  * queuing the Jobs operation.\r
 475  * @return If this function fails before queuing the Jobs operation, it will return one of:\r
 476  * - #AWS_IOT_JOBS_NOT_INITIALIZED\r
 477  * - #AWS_IOT_JOBS_BAD_PARAMETER\r
 478  * - #AWS_IOT_JOBS_NO_MEMORY\r
 479  * @return Upon successful completion of the Jobs operation (either through an #AwsIotJobsCallbackInfo_t\r
 480  * or @ref jobs_function_wait), the status will be #AWS_IOT_JOBS_SUCCESS.\r
 481  * @return Should the Jobs operation fail, the status will be one of:\r
 482  * - #AWS_IOT_JOBS_NO_MEMORY (Memory could not be allocated for incoming document)\r
 483  * - #AWS_IOT_JOBS_MQTT_ERROR\r
 484  * - #AWS_IOT_JOBS_BAD_RESPONSE\r
 485  * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE.\r
 486  *\r
 487  * @see @ref jobs_function_updatesync for a blocking variant of this function.\r
 488  *\r
 489  * <b>Example</b>\r
 490  * @code{c}\r
 491  * #define THING_NAME "Test_device"\r
 492  * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )\r
 493  *\r
 494  * // Signature of Jobs callback function.\r
 495  * void _jobsCallback( void * pCallbackContext, AwsIotJobsCallbackParam_t * pCallbackParam );\r
 496  *\r
 497  * AwsIotJobsOperation_t updateOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER;\r
 498  * AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER;\r
 499  * AwsIotJobsUpdateInfo_t updateInfo = AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER;\r
 500  * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;\r
 501  *\r
 502  * // Set the request info.\r
 503  * requestInfo.mqttConnection = _mqttConnection;\r
 504  * requestInfo.pThingName = THING_NAME;\r
 505  * requestInfo.thingNameLength = THING_NAME_LENGTH;\r
 506  *\r
 507  * // A Job ID must be set. AWS_IOT_JOBS_NEXT_JOB is not valid for UPDATE.\r
 508  * requestInfo.pJobId = "job-id";\r
 509  * requestInfo.jobIdLength = 6;\r
 510  *\r
 511  * // Set the update info.\r
 512  * updateInfo.newStatus = AWS_IOT_JOB_STATE_SUCCEEDED;\r
 513  *\r
 514  * // Set the callback function to invoke.\r
 515  * callbackInfo.function = _jobsCallback;\r
 516  *\r
 517  * // Queue Jobs UPDATE.\r
 518  * AwsIotJobsError_t updateResult = AwsIotJobs_UpdateAsync( &requestInfo,\r
 519  *                                                          &updateInfo,\r
 520  *                                                          0,\r
 521  *                                                          &callbackInfo,\r
 522  *                                                          &updateOperation );\r
 523  *\r
 524  * // UPDATE should have returned AWS_IOT_JOBS_STATUS_PENDING. The function\r
 525  * // _jobsCallback will be invoked once the Jobs response is received.\r
 526  * @endcode\r
 527  */\r
 528 /* @[declare_jobs_updateasync] */\r
 529 AwsIotJobsError_t AwsIotJobs_UpdateAsync( const AwsIotJobsRequestInfo_t * pRequestInfo,\r
 530                                           const AwsIotJobsUpdateInfo_t * pUpdateInfo,\r
 531                                           uint32_t flags,\r
 532                                           const AwsIotJobsCallbackInfo_t * pCallbackInfo,\r
 533                                           AwsIotJobsOperation_t * const pUpdateOperation );\r
 534 /* @[declare_jobs_updateasync] */\r
 535 \r
 536 /**\r
 537  * @brief Update the status of a job execution with a timeout for receiving the\r
 538  * response.\r
 539  *\r
 540  * This function queues a Jobs UPDATE, then waits for the result. Internally,\r
 541  * this function is a call to @ref jobs_function_updateasync followed by\r
 542  * @ref jobs_function_wait. See @ref jobs_function_updateasync for more information\r
 543  * on the Jobs UPDATE command.\r
 544  *\r
 545  * @param[in] pRequestInfo Jobs request parameters.\r
 546  * @param[in] pUpdateInfo Jobs update parameters.\r
 547  * @param[in] flags Flags which modify the behavior of the Jobs request. See\r
 548  * @ref jobs_constants_flags.\r
 549  * @param[in] timeoutMs If a response is not received within this timeout, this\r
 550  * function returns #AWS_IOT_JOBS_TIMEOUT.\r
 551  * @param[out] pJobsResponse The response received from the Jobs service.\r
 552  *\r
 553  * @return One of the following:\r
 554  * - #AWS_IOT_JOBS_SUCCESS\r
 555  * - #AWS_IOT_JOBS_NOT_INITIALIZED\r
 556  * - #AWS_IOT_JOBS_BAD_PARAMETER\r
 557  * - #AWS_IOT_JOBS_NO_MEMORY\r
 558  * - #AWS_IOT_JOBS_MQTT_ERROR\r
 559  * - #AWS_IOT_JOBS_BAD_RESPONSE\r
 560  * - #AWS_IOT_JOBS_TIMEOUT\r
 561  * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE.\r
 562  */\r
 563 /* @[declare_jobs_updatesync] */\r
 564 AwsIotJobsError_t AwsIotJobs_UpdateSync( const AwsIotJobsRequestInfo_t * pRequestInfo,\r
 565                                          const AwsIotJobsUpdateInfo_t * pUpdateInfo,\r
 566                                          uint32_t flags,\r
 567                                          uint32_t timeoutMs,\r
 568                                          AwsIotJobsResponse_t * const pJobsResponse );\r
 569 /* @[declare_jobs_updatesync] */\r
 570 \r
 571 /**\r
 572  * @brief Wait for a Jobs operation to complete.\r
 573  *\r
 574  * This function blocks to wait for a [GET PENDING](@ref jobs_function_getpendingasync),\r
 575  * [START NEXT](@ref jobs_function_startnextasync), [DESCRIBE](@ref jobs_function_describeasync),\r
 576  * or [UPDATE](@ref jobs_function_updateasync) operation to complete. These operations are\r
 577  * by default asynchronous; the function calls queue an operation for processing,\r
 578  * and a callback is invoked once the operation is complete.\r
 579  *\r
 580  * To use this function, the flag #AWS_IOT_JOBS_FLAG_WAITABLE must have been\r
 581  * set in the operation's function call. Additionally, this function must always\r
 582  * be called with any waitable operation to clean up resources.\r
 583  *\r
 584  * Regardless of its return value, this function always clean up resources used\r
 585  * by the waitable operation. This means `operation` is invalidated as soon as\r
 586  * this function returns, even if it returns #AWS_IOT_JOBS_TIMEOUT or another\r
 587  * error.\r
 588  *\r
 589  * @param[in] operation Reference to the Jobs operation to wait for. The flag\r
 590  * #AWS_IOT_JOBS_FLAG_WAITABLE must have been set for this operation.\r
 591  * @param[in] timeoutMs How long to wait before returning #AWS_IOT_JOBS_TIMEOUT.\r
 592  * @param[out] pJobsResponse The response received from the Jobs service.\r
 593  *\r
 594  * @return One of the following:\r
 595  * - #AWS_IOT_JOBS_SUCCESS\r
 596  * - #AWS_IOT_JOBS_NOT_INITIALIZED\r
 597  * - #AWS_IOT_JOBS_BAD_PARAMETER\r
 598  * - #AWS_IOT_JOBS_BAD_RESPONSE\r
 599  * - #AWS_IOT_JOBS_TIMEOUT\r
 600  * - A Jobs failure reason between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE.\r
 601  *\r
 602  * <b>Example</b>:\r
 603  * @code{c}\r
 604  * #define THING_NAME "Test_device"\r
 605  * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )\r
 606  *\r
 607  * AwsIotJobsOperation_t updateOperation = AWS_IOT_JOBS_OPERATION_INITIALIZER;\r
 608  * AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER;\r
 609  * AwsIotJobsUpdateInfo_t updateInfo = AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER;\r
 610  * AwsIotJobsResponse_t jobsResponse = AWS_IOT_JOBS_RESPONSE_INITIALIZER;\r
 611  *\r
 612  * // Set the request info.\r
 613  * requestInfo.mqttConnection = _mqttConnection;\r
 614  * requestInfo.pThingName = THING_NAME;\r
 615  * requestInfo.thingNameLength = THING_NAME_LENGTH;\r
 616  *\r
 617  * // Set the function used to allocate memory for an incoming response.\r
 618  * requestInfo.mallocResponse = malloc;\r
 619  *\r
 620  * // A Job ID must be set. AWS_IOT_JOBS_NEXT_JOB is not valid for UPDATE.\r
 621  * requestInfo.pJobId = "job-id";\r
 622  * requestInfo.jobIdLength = 6;\r
 623  *\r
 624  * // Set the update info.\r
 625  * updateInfo.newStatus = AWS_IOT_JOB_STATE_SUCCEEDED;\r
 626  *\r
 627  * // Queue Jobs UPDATE.\r
 628  * AwsIotJobsError_t updateResult = AwsIotJobs_UpdateAsync( &requestInfo,\r
 629  *                                                          &updateInfo,\r
 630  *                                                          AWS_IOT_JOBS_FLAG_WAITABLE,\r
 631  *                                                          NULL,\r
 632  *                                                          &updateOperation );\r
 633  *\r
 634  * // UPDATE should have returned AWS_IOT_JOBS_STATUS_PENDING. The call to wait\r
 635  * // returns once the result of the UPDATE is available or the timeout expires.\r
 636  * if( updateResult == AWS_IOT_JOBS_STATUS_PENDING )\r
 637  * {\r
 638  *     updateResult = AwsIotJobs_Wait( updateOperation, 5000, &jobsResponse );\r
 639  *\r
 640  *     if( updateResult == AWS_IOT_JOBS_SUCCESS )\r
 641  *     {\r
 642  *         // Jobs operation succeeded. Do something with the Jobs response.\r
 643  *\r
 644  *         // Once the Jobs response is no longer needed, free it.\r
 645  *         free( jobsResponse.pJobsResponse );\r
 646  *     }\r
 647  *     else\r
 648  *     {\r
 649  *         // Jobs operation failed.\r
 650  *     }\r
 651  * }\r
 652  * @endcode\r
 653  */\r
 654 /* @[declare_jobs_wait] */\r
 655 AwsIotJobsError_t AwsIotJobs_Wait( AwsIotJobsOperation_t operation,\r
 656                                    uint32_t timeoutMs,\r
 657                                    AwsIotJobsResponse_t * const pJobsResponse );\r
 658 /* @[declare_jobs_wait] */\r
 659 \r
 660 /**\r
 661  * @brief Set a callback to be invoked when the list of pending Jobs changes.\r
 662  *\r
 663  * The Jobs service publishes a [JobExecutionsChanged]\r
 664  * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-jobexecutionschanged)\r
 665  * message to the `jobs/notify` topic whenever a Job execution is added to or\r
 666  * removed from the list of pending Job executions for a Thing. The message sent is\r
 667  * useful for monitoring the list of pending Job executions.\r
 668  *\r
 669  * A <i>NOTIFY PENDING</i> callback may be invoked whenever a message is published\r
 670  * to `jobs/notify`. Each Thing may have up to @ref AWS_IOT_JOBS_NOTIFY_CALLBACKS\r
 671  * NOTIFY PENDING callbacks set. This function modifies the NOTIFY PENDING callback\r
 672  * for a specific Thing depending on the `pNotifyPendingCallback` parameter and the\r
 673  * presence of any existing NOTIFY PENDING callback.\r
 674  * - When no existing NOTIFY PENDING callback exists for a specific Thing, a new\r
 675  * callback is added.\r
 676  * - If there is an existing NOTIFY PENDING callback and `pNotifyPendingCallback` is not `NULL`,\r
 677  * then the existing callback function and parameter are replaced with `pNotifyPendingCallback`.\r
 678  * - If there is an existing NOTIFY PENDING callback and `pNotifyPendingCallback` is `NULL`,\r
 679  * then the callback is removed.\r
 680  *\r
 681  * The member @ref AwsIotJobsCallbackInfo_t.oldFunction must be used to select an\r
 682  * already-registered callback function for replacement or removal when @ref\r
 683  * AWS_IOT_JOBS_NOTIFY_CALLBACKS is greater than `1`. When multiple callbacks are\r
 684  * set, all of them will be invoked when a message is received.\r
 685  *\r
 686  * @param[in] mqttConnection The MQTT connection to use for the subscription to `jobs/notify`.\r
 687  * @param[in] pThingName The subscription to `jobs/notify` will be added for\r
 688  * this Thing Name.\r
 689  * @param[in] thingNameLength The length of `pThingName`.\r
 690  * @param[in] flags This parameter is for future-compatibility. Currently, flags are\r
 691  * not supported for this function and this parameter is ignored.\r
 692  * @param[in] pNotifyPendingCallback Callback function to invoke for incoming messages.\r
 693  *\r
 694  * @return One of the following:\r
 695  * - #AWS_IOT_JOBS_SUCCESS\r
 696  * - #AWS_IOT_JOBS_NOT_INITIALIZED\r
 697  * - #AWS_IOT_JOBS_BAD_PARAMETER\r
 698  * - #AWS_IOT_JOBS_NO_MEMORY\r
 699  * - #AWS_IOT_JOBS_MQTT_ERROR\r
 700  * - #AWS_IOT_JOBS_TIMEOUT\r
 701  *\r
 702  * @see @ref jobs_function_setnotifynextcallback for the function to register callbacks\r
 703  * for next Job changes.\r
 704  *\r
 705  * <b>Example</b>:\r
 706  * @code{c}\r
 707  * #define THING_NAME "Test_device"\r
 708  * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )\r
 709  *\r
 710  * AwsIotJobsError_t result = AWS_IOT_JOBS_STATUS_PENDING;\r
 711  * AwsIotJobsCallbackInfo_t notifyPendingCallback = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;\r
 712  *\r
 713  * // _jobsCallback will be invoked when any messages are received.\r
 714  * notifyPendingCallback.function = _jobsCallback;\r
 715  *\r
 716  * // Set the NOTIFY PENDING callback for the Thing "Test_device".\r
 717  * result = AwsIotJobs_SetNotifyPendingCallback( mqttConnection,\r
 718  *                                               THING_NAME,\r
 719  *                                               THING_NAME_LENGTH,\r
 720  *                                               0,\r
 721  *                                               &notifyPendingCallback );\r
 722  *\r
 723  * // Check if the callback was successfully set.\r
 724  * if( status == AWS_IOT_JOBS_SUCCESS )\r
 725  * {\r
 726  *     // The callback will now be invoked whenever the list of pending Job\r
 727  *     // executions changes.\r
 728  *\r
 729  *     // Once the callback is no longer needed, it may be removed by passing\r
 730  *     // NULL as the callback function and specifying the function to remove.\r
 731  *     notifyPendingCallback.function = NULL;\r
 732  *     notifyPendingCallback.oldFunction = _jobsCallback;\r
 733  *\r
 734  *     status = AwsIotJobs_SetNotifyPendingCallback( mqttConnection,\r
 735  *                                                   THING_NAME,\r
 736  *                                                   THING_NAME_LENGTH,\r
 737  *                                                   0,\r
 738  *                                                   &notifyPendingCallback );\r
 739  *\r
 740  *     // The return value from removing a callback should always be success.\r
 741  *     assert( status == AWS_IOT_JOBS_SUCCESS );\r
 742  * }\r
 743  * @endcode\r
 744  */\r
 745 /* @[declare_jobs_setnotifypendingcallback] */\r
 746 AwsIotJobsError_t AwsIotJobs_SetNotifyPendingCallback( IotMqttConnection_t mqttConnection,\r
 747                                                        const char * pThingName,\r
 748                                                        size_t thingNameLength,\r
 749                                                        uint32_t flags,\r
 750                                                        const AwsIotJobsCallbackInfo_t * pNotifyPendingCallback );\r
 751 /* @[declare_jobs_setnotifypendingcallback] */\r
 752 \r
 753 /**\r
 754  * @brief Set a callback to be invoked when the next pending Job changes.\r
 755  *\r
 756  * The Jobs service publishes a [NextJobExecutionChanged]\r
 757  * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-nextjobexecutionchanged)\r
 758  * message to the `jobs/notify-next` topic whenever the next Job execution in\r
 759  * the list of pending Job executions changes for a Thing. The message sent is\r
 760  * useful for being notified of changes to the next Job.\r
 761  *\r
 762  * A <i>NOTIFY NEXT</i> callback may be invoked whenever a message is published\r
 763  * to `jobs/notify-next`. Each Thing may have up to @ref AWS_IOT_JOBS_NOTIFY_CALLBACKS\r
 764  * NOTIFY NEXT callbacks set.  This function modifies the NOTIFY NEXT callback for\r
 765  * a specific Thing depending on the `pNotifyNextCallback` parameter and the presence\r
 766  * of any existing NOTIFY NEXT callback.\r
 767  * - When no existing NOTIFY NEXT callback exists for a specific Thing, a new\r
 768  * callback is added.\r
 769  * - If there is an existing NOTIFY NEXT callback and `pNotifyNextCallback` is not `NULL`,\r
 770  * then the existing callback function and parameter are replaced with `pNotifyNextCallback`.\r
 771  * - If there is an existing NOTIFY NEXT callback and `pNotifyNextCallback` is `NULL`,\r
 772  * then the callback is removed.\r
 773  *\r
 774  * The member @ref AwsIotJobsCallbackInfo_t.oldFunction must be used to select an\r
 775  * already-registered callback function for replacement or removal when @ref\r
 776  * AWS_IOT_JOBS_NOTIFY_CALLBACKS is greater than `1`. When multiple callbacks are\r
 777  * set, all of them will be invoked when a message is received.\r
 778  *\r
 779  * @param[in] mqttConnection The MQTT connection to use for the subscription to `jobs/notify-next`.\r
 780  * @param[in] pThingName The subscription to `jobs/notify-next` will be added for\r
 781  * this Thing Name.\r
 782  * @param[in] thingNameLength The length of `pThingName`.\r
 783  * @param[in] flags This parameter is for future-compatibility. Currently, flags are\r
 784  * not supported for this function and this parameter is ignored.\r
 785  * @param[in] pNotifyNextCallback Callback function to invoke for incoming messages.\r
 786  *\r
 787  * @return One of the following:\r
 788  * - #AWS_IOT_JOBS_SUCCESS\r
 789  * - #AWS_IOT_JOBS_NOT_INITIALIZED\r
 790  * - #AWS_IOT_JOBS_BAD_PARAMETER\r
 791  * - #AWS_IOT_JOBS_NO_MEMORY\r
 792  * - #AWS_IOT_JOBS_MQTT_ERROR\r
 793  * - #AWS_IOT_JOBS_TIMEOUT\r
 794  *\r
 795  * @see @ref jobs_function_setnotifypendingcallback for the function to register callbacks\r
 796  * for all pending Job changes.\r
 797  *\r
 798  * <b>Example</b>:\r
 799  * @code{c}\r
 800  * #define THING_NAME "Test_device"\r
 801  * #define THING_NAME_LENGTH ( sizeof( THING_NAME ) - 1 )\r
 802  *\r
 803  * AwsIotJobsError_t result = AWS_IOT_JOBS_STATUS_PENDING;\r
 804  * AwsIotJobsCallbackInfo_t notifyNextCallback = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;\r
 805  *\r
 806  * // _jobsCallback will be invoked when any messages are received.\r
 807  * notifyNextCallback.function = _jobsCallback;\r
 808  *\r
 809  * // Set the NOTIFY NEXT callback for the Thing "Test_device".\r
 810  * result = AwsIotJobs_SetNotifyNextCallback( mqttConnection,\r
 811  *                                            THING_NAME,\r
 812  *                                            THING_NAME_LENGTH,\r
 813  *                                            0,\r
 814  *                                            &notifyNextCallback );\r
 815  *\r
 816  * // Check if the callback was successfully set.\r
 817  * if( status == AWS_IOT_JOBS_SUCCESS )\r
 818  * {\r
 819  *     // The callback will now be invoked whenever the next pending Job\r
 820  *     // execution changes.\r
 821  *\r
 822  *     // Once the callback is no longer needed, it may be removed by passing\r
 823  *     // NULL as the callback function and specifying the function to remove.\r
 824  *     notifyNextCallback.function = NULL;\r
 825  *     notifyNextCallback.oldFunction = _jobsCallback;\r
 826  *\r
 827  *     status = AwsIotJobs_SetNotifyNextCallback( mqttConnection,\r
 828  *                                                THING_NAME,\r
 829  *                                                THING_NAME_LENGTH,\r
 830  *                                                0,\r
 831  *                                                &notifyNextCallback );\r
 832  *\r
 833  *     // The return value from removing a callback should always be success.\r
 834  *     assert( status == AWS_IOT_JOBS_SUCCESS );\r
 835  * }\r
 836  * @endcode\r
 837  */\r
 838 /* @[declare_jobs_setnotifynextcallback] */\r
 839 AwsIotJobsError_t AwsIotJobs_SetNotifyNextCallback( IotMqttConnection_t mqttConnection,\r
 840                                                     const char * pThingName,\r
 841                                                     size_t thingNameLength,\r
 842                                                     uint32_t flags,\r
 843                                                     const AwsIotJobsCallbackInfo_t * pNotifyNextCallback );\r
 844 /* @[declare_jobs_setnotifynextcallback] */\r
 845 \r
 846 /**\r
 847  * @brief Remove persistent Jobs operation topic subscriptions.\r
 848  *\r
 849  * Passing the flag @ref AWS_IOT_JOBS_FLAG_KEEP_SUBSCRIPTIONS to @ref jobs_function_getpendingasync,\r
 850  * @ref jobs_function_startnextasync, @ref jobs_function_describeasync, @ref jobs_function_updateasync,\r
 851  * or their blocking versions causes the Jobs operation topic subscriptions to be\r
 852  * maintained for future calls to the same function. If a persistent subscription for a\r
 853  * Jobs topic are no longer needed, this function may be used to remove it.\r
 854  *\r
 855  * @param[in] pRequestInfo Jobs request info. Only the [pThingName]\r
 856  * (@ref #AwsIotJobsRequestInfo_t.pThingName), [thingNameLength]\r
 857  * (@ref #AwsIotJobsRequestInfo_t.thingNameLength), and [mqttConnection]\r
 858  * (@ref #AwsIotJobsRequestInfo_t.mqttConnection) members need to be set for this\r
 859  * function.\r
 860  * @param[in] flags Flags that determine which subscriptions to remove. Valid values are\r
 861  * the bitwise OR of the following individual flags:\r
 862  * - @ref AWS_IOT_JOBS_FLAG_REMOVE_GET_PENDING_SUBSCRIPTIONS\r
 863  * - @ref AWS_IOT_JOBS_FLAG_REMOVE_START_NEXT_SUBSCRIPTIONS\r
 864  * - @ref AWS_IOT_JOBS_FLAG_REMOVE_DESCRIBE_SUBSCRIPTIONS\r
 865  * - @ref AWS_IOT_JOBS_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS\r
 866  *\r
 867  * @return On success:\r
 868  * - #AWS_IOT_JOBS_SUCCESS\r
 869  * @return If an MQTT UNSUBSCRIBE packet cannot be sent, one of the following:\r
 870  * - #AWS_IOT_JOBS_NO_MEMORY\r
 871  * - #AWS_IOT_JOBS_MQTT_ERROR\r
 872  *\r
 873  * @note @ref jobs_function_cleanup removes persistent sessions as well.\r
 874  *\r
 875  * @warning This function is not safe to call with any in-progress operations!\r
 876  * It also does not affect NOTIFY PENDING and NOTIFY NEXT callbacks registered\r
 877  * with @ref jobs_function_setnotifypendingcallback and\r
 878  * @ref jobs_function_setnotifynextcallback, respectively. (See documentation for\r
 879  * those functions on how to remove their callbacks).\r
 880  */\r
 881 /* @[declare_jobs_removepersistentsubscriptions] */\r
 882 AwsIotJobsError_t AwsIotJobs_RemovePersistentSubscriptions( const AwsIotJobsRequestInfo_t * pRequestInfo,\r
 883                                                             uint32_t flags );\r
 884 /* @[declare_jobs_removepersistentsubscriptions] */\r
 885 \r
 886 /*-------------------------- Jobs helper functions --------------------------*/\r
 887 \r
 888 /**\r
 889  * @brief Returns a string that describes an #AwsIotJobsError_t.\r
 890  *\r
 891  * Like POSIX's `strerror`, this function returns a string describing a return\r
 892  * code. In this case, the return code is a Jobs library error code, `status`.\r
 893  *\r
 894  * The string returned by this function <b>MUST</b> be treated as read-only: any\r
 895  * attempt to modify its contents may result in a crash. Therefore, this function\r
 896  * is limited to usage in logging.\r
 897  *\r
 898  * @param[in] status The status to describe.\r
 899  *\r
 900  * @return A read-only string that describes `status`.\r
 901  *\r
 902  * @warning The string returned by this function must never be modified.\r
 903  */\r
 904 /* @[declare_jobs_strerror] */\r
 905 const char * AwsIotJobs_strerror( AwsIotJobsError_t status );\r
 906 /* @[declare_jobs_strerror] */\r
 907 \r
 908 /**\r
 909  * @brief Returns a string that describes an #AwsIotJobState_t.\r
 910  *\r
 911  * This function returns a string describing a Job state, `state`.\r
 912  *\r
 913  * The string returned by this function <b>MUST</b> be treated as read-only: any\r
 914  * attempt to modify its contents may result in a crash. Therefore, this function\r
 915  * is limited to usage in logging.\r
 916  *\r
 917  * @param[in] state The job state to describe.\r
 918  *\r
 919  * @return A read-only string that describes `state`.\r
 920  *\r
 921  * @warning The string returned by this function must never be modified.\r
 922  */\r
 923 /* @[declare_jobs_statename] */\r
 924 const char * AwsIotJobs_StateName( AwsIotJobState_t state );\r
 925 /* @[declare_jobs_statename] */\r
 926 \r
 927 #endif /* ifndef AWS_IOT_JOBS_H_ */\r