git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/FreeRTOS-IoT-Libraries/c_sdk/aws/jobs/include/types/aws_iot_jobs_types.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_types.h\r
  25  * @brief Types of the Jobs library.\r
  26  */\r
  27 \r
  28 #ifndef AWS_IOT_JOBS_TYPES_H_\r
  29 #define AWS_IOT_JOBS_TYPES_H_\r
  30 \r
  31 /* The config header is always included first. */\r
  32 #include "iot_config.h"\r
  33 \r
  34 /* MQTT types include. */\r
  35 #include "types/iot_mqtt_types.h"\r
  36 \r
  37 /*---------------------------- Jobs handle types ----------------------------*/\r
  38 \r
  39 /**\r
  40  * @handles{jobs,Jobs library}\r
  41  */\r
  42 \r
  43 /**\r
  44  * @ingroup jobs_datatypes_handles\r
  45  * @brief Opaque handle that references an in-progress Jobs operation.\r
  46  *\r
  47  * Set as an output parameter of @ref jobs_function_getpendingasync, @ref jobs_function_startnextasync,\r
  48  * @ref jobs_function_describeasync, and @ref jobs_function_updateasync. These functions send a\r
  49  * message to the Jobs service requesting a Jobs operation; the result of this operation\r
  50  * is unknown until the Jobs service sends a response. Therefore, this handle serves as a\r
  51  * reference to Jobs operations awaiting a response from the Jobs service.\r
  52  *\r
  53  * This reference will be valid from the successful return of @ref jobs_function_getpendingasync,\r
  54  * @ref jobs_function_startnextasync, @ref jobs_function_describeasync, and @ref jobs_function_updateasync.\r
  55  * The reference becomes invalid once the [completion callback](@ref AwsIotJobsCallbackInfo_t)\r
  56  * is invoked, or @ref jobs_function_wait returns.\r
  57  *\r
  58  * @initializer{AwsIotJobsOperation_t,AWS_IOT_JOBS_OPERATION_INITIALIZER}\r
  59  *\r
  60  * @see @ref jobs_function_wait and #AWS_IOT_JOBS_FLAG_WAITABLE for waiting on\r
  61  * a reference; or #AwsIotJobsCallbackInfo_t and #AwsIotJobsCallbackParam_t for an\r
  62  * asynchronous notification of completion.\r
  63  */\r
  64 typedef struct _jobsOperation * AwsIotJobsOperation_t;\r
  65 \r
  66 /*-------------------------- Jobs enumerated types --------------------------*/\r
  67 \r
  68 /**\r
  69  * @enums{jobs,Jobs library}\r
  70  */\r
  71 \r
  72 /**\r
  73  * @ingroup jobs_datatypes_enums\r
  74  * @brief Return codes of [Jobs functions](@ref jobs_functions).\r
  75  *\r
  76  * The function @ref jobs_function_strerror can be used to get a return code's\r
  77  * description.\r
  78  *\r
  79  * The values between #AWS_IOT_JOBS_INVALID_TOPIC and #AWS_IOT_JOBS_TERMINAL_STATE\r
  80  * may be returned by the Jobs service upon failure of a Jobs operation. See [this page]\r
  81  * (https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#jobs-mqtt-error-response)\r
  82  * for more information.\r
  83  */\r
  84 typedef enum AwsIotJobsError\r
  85 {\r
  86     /**\r
  87      * @brief Jobs operation completed successfully.\r
  88      *\r
  89      * Functions that may return this value:\r
  90      * - @ref jobs_function_init\r
  91      * - @ref jobs_function_wait\r
  92      * - @ref jobs_function_getpendingsync\r
  93      * - @ref jobs_function_startnextsync\r
  94      * - @ref jobs_function_describesync\r
  95      * - @ref jobs_function_updatesync\r
  96      * - @ref jobs_function_setnotifypendingcallback\r
  97      * - @ref jobs_function_setnotifynextcallback\r
  98      * - @ref jobs_function_removepersistentsubscriptions\r
  99      *\r
 100      * Will also be the value of a Jobs operation completion callback's<br>\r
 101      * [AwsIotJobsCallbackParam_t.operation.result](@ref AwsIotJobsCallbackParam_t.result)\r
 102      * when successful.\r
 103      */\r
 104     AWS_IOT_JOBS_SUCCESS = 0,\r
 105 \r
 106     /**\r
 107      * @brief Jobs operation queued, awaiting result.\r
 108      *\r
 109      * Functions that may return this value:\r
 110      * - @ref jobs_function_getpendingasync\r
 111      * - @ref jobs_function_startnextasync\r
 112      * - @ref jobs_function_describeasync\r
 113      * - @ref jobs_function_updateasync\r
 114      */\r
 115     AWS_IOT_JOBS_STATUS_PENDING = 1,\r
 116 \r
 117     /**\r
 118      * @brief Initialization failed.\r
 119      *\r
 120      * Functions that may return this value:\r
 121      * - @ref jobs_function_init\r
 122      */\r
 123     AWS_IOT_JOBS_INIT_FAILED = 2,\r
 124 \r
 125     /**\r
 126      * @brief At least one parameter is invalid.\r
 127      *\r
 128      * Functions that may return this value:\r
 129      * - @ref jobs_function_getpendingasync and @ref jobs_function_getpendingsync\r
 130      * - @ref jobs_function_startnextasync and @ref jobs_function_startnextsync\r
 131      * - @ref jobs_function_describeasync and @ref jobs_function_describesync\r
 132      * - @ref jobs_function_updateasync and @ref jobs_function_updatesync\r
 133      * - @ref jobs_function_wait\r
 134      * - @ref jobs_function_setnotifypendingcallback\r
 135      * - @ref jobs_function_setnotifynextcallback\r
 136      * - @ref jobs_function_removepersistentsubscriptions\r
 137      */\r
 138     AWS_IOT_JOBS_BAD_PARAMETER = 3,\r
 139 \r
 140     /**\r
 141      * @brief Jobs operation failed because of memory allocation failure.\r
 142      *\r
 143      * Functions that may return this value:\r
 144      * - @ref jobs_function_getpendingasync and @ref jobs_function_getpendingsync\r
 145      * - @ref jobs_function_startnextasync and @ref jobs_function_startnextsync\r
 146      * - @ref jobs_function_describeasync and @ref jobs_function_describesync\r
 147      * - @ref jobs_function_updateasync and @ref jobs_function_updatesync\r
 148      * - @ref jobs_function_setnotifypendingcallback\r
 149      * - @ref jobs_function_setnotifynextcallback\r
 150      */\r
 151     AWS_IOT_JOBS_NO_MEMORY = 4,\r
 152 \r
 153     /**\r
 154      * @brief Jobs operation failed because of failure in MQTT library.\r
 155      *\r
 156      * Functions that may return this value:\r
 157      * - @ref jobs_function_getpendingasync and @ref jobs_function_getpendingsync\r
 158      * - @ref jobs_function_startnextasync and @ref jobs_function_startnextsync\r
 159      * - @ref jobs_function_describeasync and @ref jobs_function_describesync\r
 160      * - @ref jobs_function_updateasync and @ref jobs_function_updatesync\r
 161      * - @ref jobs_function_setnotifypendingcallback\r
 162      * - @ref jobs_function_setnotifynextcallback\r
 163      * - @ref jobs_function_removepersistentsubscriptions\r
 164      */\r
 165     AWS_IOT_JOBS_MQTT_ERROR = 5,\r
 166 \r
 167     /**\r
 168      * @brief Response received from Jobs service not understood.\r
 169      *\r
 170      * Functions that may return this value:\r
 171      * - @ref jobs_function_getpendingsync\r
 172      * - @ref jobs_function_startnextsync\r
 173      * - @ref jobs_function_describesync\r
 174      * - @ref jobs_function_updatesync\r
 175      * - @ref jobs_function_wait\r
 176      *\r
 177      * May also be the value of a Jobs operation completion callback's<br>\r
 178      * [AwsIotJobsCallbackParam_t.operation.result](@ref AwsIotJobsCallbackParam_t.result).\r
 179      */\r
 180     AWS_IOT_JOBS_BAD_RESPONSE = 7,\r
 181 \r
 182     /**\r
 183      * @brief A blocking Jobs operation timed out.\r
 184      *\r
 185      * Functions that may return this value:\r
 186      * - @ref jobs_function_getpendingsync\r
 187      * - @ref jobs_function_startnextsync\r
 188      * - @ref jobs_function_describesync\r
 189      * - @ref jobs_function_updatesync\r
 190      * - @ref jobs_function_wait\r
 191      * - @ref jobs_function_setnotifypendingcallback\r
 192      * - @ref jobs_function_setnotifynextcallback\r
 193      */\r
 194     AWS_IOT_JOBS_TIMEOUT = 8,\r
 195 \r
 196     /**\r
 197      * @brief An API function was called before @ref jobs_function_init.\r
 198      *\r
 199      * Functions that may return this value:\r
 200      * - @ref jobs_function_getpendingasync and @ref jobs_function_getpendingsync\r
 201      * - @ref jobs_function_startnextasync and @ref jobs_function_startnextsync\r
 202      * - @ref jobs_function_describeasync and @ref jobs_function_describesync\r
 203      * - @ref jobs_function_updateasync and @ref jobs_function_updatesync\r
 204      * - @ref jobs_function_wait\r
 205      * - @ref jobs_function_setnotifypendingcallback\r
 206      * - @ref jobs_function_setnotifynextcallback\r
 207      */\r
 208     AWS_IOT_JOBS_NOT_INITIALIZED = 11,\r
 209 \r
 210     /**\r
 211      * @brief Jobs operation failed: A request was sent to an unknown topic.\r
 212      *\r
 213      * Functions that may return this value:\r
 214      * - @ref jobs_function_getpendingsync\r
 215      * - @ref jobs_function_startnextsync\r
 216      * - @ref jobs_function_describesync\r
 217      * - @ref jobs_function_updatesync\r
 218      * - @ref jobs_function_wait\r
 219      *\r
 220      * May also be the value of a Jobs operation completion callback's<br>\r
 221      * [AwsIotJobsCallbackParam_t.operation.result](@ref AwsIotJobsCallbackParam_t.result).\r
 222      */\r
 223     AWS_IOT_JOBS_INVALID_TOPIC = 12,\r
 224 \r
 225     /**\r
 226      * @brief Jobs operation failed: The contents of the request were not understood.\r
 227      *\r
 228      * Jobs requests must be UTF-8 encoded JSON documents.\r
 229      *\r
 230      * Functions that may return this value:\r
 231      * - @ref jobs_function_getpendingsync\r
 232      * - @ref jobs_function_startnextsync\r
 233      * - @ref jobs_function_describesync\r
 234      * - @ref jobs_function_updatesync\r
 235      * - @ref jobs_function_wait\r
 236      *\r
 237      * May also be the value of a Jobs operation completion callback's<br>\r
 238      * [AwsIotJobsCallbackParam_t.operation.result](@ref AwsIotJobsCallbackParam_t.result).\r
 239      */\r
 240     AWS_IOT_JOBS_INVALID_JSON = 13,\r
 241 \r
 242     /**\r
 243      * @brief Jobs operation failed: The contents of the request were invalid.\r
 244      *\r
 245      * Functions that may return this value:\r
 246      * - @ref jobs_function_getpendingsync\r
 247      * - @ref jobs_function_startnextsync\r
 248      * - @ref jobs_function_describesync\r
 249      * - @ref jobs_function_updatesync\r
 250      * - @ref jobs_function_wait\r
 251      *\r
 252      * May also be the value of a Jobs operation completion callback's<br>\r
 253      * [AwsIotJobsCallbackParam_t.operation.result](@ref AwsIotJobsCallbackParam_t.result).\r
 254      */\r
 255     AWS_IOT_JOBS_INVALID_REQUEST = 14,\r
 256 \r
 257     /**\r
 258      * @brief Jobs operation failed: An update attempted to change the job execution\r
 259      * to an invalid state.\r
 260      *\r
 261      * Functions that may return this value:\r
 262      * - @ref jobs_function_startnextsync\r
 263      * - @ref jobs_function_updatesync\r
 264      * - @ref jobs_function_wait\r
 265      *\r
 266      * May also be the value of a Jobs operation completion callback's<br>\r
 267      * [AwsIotJobsCallbackParam_t.operation.result](@ref AwsIotJobsCallbackParam_t.result)\r
 268      * following a call to @ref jobs_function_startnextasync or @ref jobs_function_updateasync.\r
 269      */\r
 270     AWS_IOT_JOBS_INVALID_STATE = 15,\r
 271 \r
 272     /**\r
 273      * @brief Jobs operation failed: The specified job execution does not exist.\r
 274      *\r
 275      * * Functions that may return this value:\r
 276      * - @ref jobs_function_describesync\r
 277      * - @ref jobs_function_updatesync\r
 278      * - @ref jobs_function_wait\r
 279      *\r
 280      * May also be the value of a Jobs operation completion callback's<br>\r
 281      * [AwsIotJobsCallbackParam_t.operation.result](@ref AwsIotJobsCallbackParam_t.result)\r
 282      * following a call to @ref jobs_function_describeasync or @ref jobs_function_updateasync.\r
 283      */\r
 284     AWS_IOT_JOBS_NOT_FOUND = 16,\r
 285 \r
 286     /**\r
 287      * @brief Jobs operation failed: The Jobs service expected a version that did\r
 288      * not match what was in the request.\r
 289      *\r
 290      * * Functions that may return this value:\r
 291      * - @ref jobs_function_updatesync\r
 292      * - @ref jobs_function_wait\r
 293      *\r
 294      * May also be the value of a Jobs operation completion callback's<br>\r
 295      * [AwsIotJobsCallbackParam_t.operation.result](@ref AwsIotJobsCallbackParam_t.result)\r
 296      * following a call to @ref jobs_function_updateasync.\r
 297      */\r
 298     AWS_IOT_JOBS_VERSION_MISMATCH = 17,\r
 299 \r
 300     /**\r
 301      * @brief Jobs operation failed: The Jobs service encountered an internal error.\r
 302      *\r
 303      * Functions that may return this value:\r
 304      * - @ref jobs_function_getpendingsync\r
 305      * - @ref jobs_function_startnextsync\r
 306      * - @ref jobs_function_describesync\r
 307      * - @ref jobs_function_updatesync\r
 308      * - @ref jobs_function_wait\r
 309      *\r
 310      * May also be the value of a Jobs operation completion callback's<br>\r
 311      * [AwsIotJobsCallbackParam_t.operation.result](@ref AwsIotJobsCallbackParam_t.result).\r
 312      */\r
 313     AWS_IOT_JOBS_INTERNAL_ERROR = 18,\r
 314 \r
 315     /**\r
 316      * @brief Jobs operation failed: The request was throttled.\r
 317      *\r
 318      * Functions that may return this value:\r
 319      * - @ref jobs_function_getpendingsync\r
 320      * - @ref jobs_function_startnextsync\r
 321      * - @ref jobs_function_describesync\r
 322      * - @ref jobs_function_updatesync\r
 323      * - @ref jobs_function_wait\r
 324      *\r
 325      * May also be the value of a Jobs operation completion callback's<br>\r
 326      * [AwsIotJobsCallbackParam_t.operation.result](@ref AwsIotJobsCallbackParam_t.result).\r
 327      */\r
 328     AWS_IOT_JOBS_THROTTLED = 19,\r
 329 \r
 330     /**\r
 331      * @brief Jobs operation failed: Attempt to describe a Job in a terminal state.\r
 332      *\r
 333      * Functions that may return this value:\r
 334      * - @ref jobs_function_describesync\r
 335      * - @ref jobs_function_wait\r
 336      *\r
 337      * May also be the value of a Jobs operation completion callback's<br>\r
 338      * [AwsIotJobsCallbackParam_t.operation.result](@ref AwsIotJobsCallbackParam_t.result)\r
 339      * following a call to @ref jobs_function_describeasync.\r
 340      */\r
 341     AWS_IOT_JOBS_TERMINAL_STATE = 20\r
 342 } AwsIotJobsError_t;\r
 343 \r
 344 /**\r
 345  * @ingroup jobs_datatypes_enums\r
 346  * @brief Possible states of jobs.\r
 347  *\r
 348  * The function @ref jobs_function_statename can be used to get a state's\r
 349  * description.\r
 350  *\r
 351  * See [this page]\r
 352  * (https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html)\r
 353  * for more information on Job states.\r
 354  */\r
 355 typedef enum AwsIotJobState\r
 356 {\r
 357     /**\r
 358      * @brief A Job is queued and awaiting execution.\r
 359      */\r
 360     AWS_IOT_JOB_STATE_QUEUED,\r
 361 \r
 362     /**\r
 363      * @brief A Job is currently executing.\r
 364      */\r
 365     AWS_IOT_JOB_STATE_IN_PROGRESS,\r
 366 \r
 367     /**\r
 368      * @brief A Job has failed. This is a terminal state.\r
 369      */\r
 370     AWS_IOT_JOB_STATE_FAILED,\r
 371 \r
 372     /**\r
 373      * @brief A Job has succeeded. This is a terminal state.\r
 374      */\r
 375     AWS_IOT_JOB_STATE_SUCCEEDED,\r
 376 \r
 377     /**\r
 378      * @brief A Job was canceled. This is a terminal state.\r
 379      */\r
 380     AWS_IOT_JOB_STATE_CANCELED,\r
 381 \r
 382     /**\r
 383      * @brief A Job's timer has expired. This is a terminal state.\r
 384      *\r
 385      * Jobs are considered timed out if they remain [IN_PROGRESS]\r
 386      * (@ref AWS_IOT_JOB_STATE_IN_PROGRESS) for more than their\r
 387      * `inProgressTimeoutInMinutes` property or a [Job update](@ref jobs_function_updateasync)\r
 388      * was not sent within [stepTimeoutInMinutes](@ref AwsIotJobsUpdateInfo_t.stepTimeoutInMinutes).\r
 389      */\r
 390     AWS_IOT_JOB_STATE_TIMED_OUT,\r
 391 \r
 392     /**\r
 393      * @brief A Job was rejected by the device. This is a terminal state.\r
 394      */\r
 395     AWS_IOT_JOB_STATE_REJECTED,\r
 396 \r
 397     /**\r
 398      * @brief A Job was removed. This is a terminal state.\r
 399      */\r
 400     AWS_IOT_JOB_STATE_REMOVED\r
 401 } AwsIotJobState_t;\r
 402 \r
 403 /**\r
 404  * @ingroup jobs_datatypes_enums\r
 405  * @brief Types of Jobs library callbacks.\r
 406  *\r
 407  * One of these values will be placed in #AwsIotJobsCallbackParam_t.callbackType\r
 408  * to identify the reason for invoking a callback function.\r
 409  */\r
 410 typedef enum AwsIotJobsCallbackType\r
 411 {\r
 412     AWS_IOT_JOBS_GET_PENDING_COMPLETE = 0,    /**< Callback invoked because a [Jobs get pending](@ref jobs_function_getpendingasync) completed. */\r
 413     AWS_IOT_JOBS_START_NEXT_COMPLETE = 1,     /**< Callback invoked because a [Jobs start next](@ref jobs_function_startnextasync) completed. */\r
 414     AWS_IOT_JOBS_DESCRIBE_COMPLETE = 2,       /**< Callback invoked because a [Jobs describe](@ref jobs_function_describeasync) completed. */\r
 415     AWS_IOT_JOBS_UPDATE_COMPLETE = 3,         /**< Callback invoked because a [Jobs update](@ref jobs_function_updateasync) completed. */\r
 416     AWS_IOT_JOBS_NOTIFY_PENDING_CALLBACK = 4, /**< Callback invoked for an incoming message on a [Jobs notify-pending](@ref jobs_function_setnotifypendingcallback) topic. */\r
 417     AWS_IOT_JOBS_NOTIFY_NEXT_CALLBACK = 5     /**< Callback invoked for an incoming message on a [Jobs notify-next](@ref jobs_function_setnotifynextcallback) topic. */\r
 418 } AwsIotJobsCallbackType_t;\r
 419 \r
 420 /*-------------------------- Jobs parameter structs -------------------------*/\r
 421 \r
 422 /**\r
 423  * @paramstructs{jobs,Jobs library}\r
 424  */\r
 425 \r
 426 /**\r
 427  * @ingroup jobs_datatypes_paramstructs\r
 428  * @brief Parameter to a Jobs callback function.\r
 429  *\r
 430  * @paramfor Jobs callback functions\r
 431  *\r
 432  * The Jobs library passes this struct to a callback function whenever a\r
 433  * Jobs operation completes or a message is received on a Jobs notify-pending\r
 434  * or notify-next topic.\r
 435  *\r
 436  * The valid members of this struct are different based on\r
 437  * #AwsIotJobsCallbackParam_t.callbackType. If the callback type is\r
 438  * #AWS_IOT_JOBS_GET_PENDING_COMPLETE, #AWS_IOT_JOBS_START_NEXT_COMPLETE,\r
 439  * #AWS_IOT_JOBS_DESCRIBE_COMPLETE, or #AWS_IOT_JOBS_UPDATE_COMPLETE, then\r
 440  * #AwsIotJobsCallbackParam_t.operation is valid. Otherwise, if the callback type\r
 441  * is #AWS_IOT_JOBS_NOTIFY_PENDING_CALLBACK or #AWS_IOT_JOBS_NOTIFY_NEXT_CALLBACK,\r
 442  * then #AwsIotJobsCallbackParam_t.callback is valid.\r
 443  *\r
 444  * @attention Any pointers in this callback parameter may be freed as soon as the\r
 445  * [callback function](@ref AwsIotJobsCallbackInfo_t.function) returns. Therefore,\r
 446  * data must be copied if it is needed after the callback function returns.\r
 447  * @attention The Jobs library may set strings that are not NULL-terminated.\r
 448  *\r
 449  * @see #AwsIotJobsCallbackInfo_t for the signature of a callback function.\r
 450  */\r
 451 typedef struct AwsIotJobsCallbackParam\r
 452 {\r
 453     AwsIotJobsCallbackType_t callbackType; /**< @brief Reason for invoking the Jobs callback function to provide context. */\r
 454 \r
 455     const char * pThingName;               /**< @brief The Thing Name associated with this Jobs callback. */\r
 456     size_t thingNameLength;                /**< @brief Length of #AwsIotJobsCallbackParam_t.pThingName. */\r
 457 \r
 458     IotMqttConnection_t mqttConnection;    /**< @brief The MQTT connection associated with the Jobs callback. */\r
 459 \r
 460     union\r
 461     {\r
 462         /* Valid for completed Jobs operations. */\r
 463         struct\r
 464         {\r
 465             AwsIotJobsError_t result;        /**< @brief Result of Jobs operation, e.g. succeeded or failed. */\r
 466             AwsIotJobsOperation_t reference; /**< @brief Reference to the Jobs operation that completed. */\r
 467 \r
 468             const char * pResponse;          /**< @brief Response retrieved from the Jobs service. */\r
 469             size_t responseLength;           /**< @brief Length of retrieved response. */\r
 470         } operation;                         /**< @brief Information on a completed Jobs operation. */\r
 471 \r
 472         /* Valid for a message on a Jobs notify-pending or notify-next topic. */\r
 473         struct\r
 474         {\r
 475             const char * pDocument; /**< @brief Job execution document received on callback. */\r
 476             size_t documentLength;  /**< @brief Length of job execution document. */\r
 477         } callback;                 /**< @brief Jobs document from an incoming delta or updated topic. */\r
 478     } u;                            /**< @brief Valid member depends on callback type. */\r
 479 } AwsIotJobsCallbackParam_t;\r
 480 \r
 481 /**\r
 482  * @ingroup jobs_datatypes_paramstructs\r
 483  * @brief Information on a user-provided Jobs callback function.\r
 484  *\r
 485  * @paramfor @ref jobs_function_getpendingasync, @ref jobs_function_startnextasync,\r
 486  * @ref jobs_function_describeasync, @ref jobs_function_updateasync,\r
 487  * @ref jobs_function_setnotifypendingcallback, @ref jobs_function_setnotifynextcallback\r
 488  *\r
 489  * Provides a function to be invoked when a Jobs operation completes or when a\r
 490  * Jobs document is received on a callback topic (notify-pending or notify-next).\r
 491  *\r
 492  * @initializer{AwsIotJobsCallbackInfo_t,AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER}\r
 493  */\r
 494 typedef struct AwsIotJobsCallbackInfo\r
 495 {\r
 496     void * pCallbackContext; /**< @brief The first parameter to pass to the callback function. */\r
 497 \r
 498     /**\r
 499      * @brief User-provided callback function signature.\r
 500      *\r
 501      * @param[in] void* #AwsIotJobsCallbackInfo_t.pCallbackContext\r
 502      * @param[in] AwsIotJobsCallbackParam_t* Details on the outcome of the Jobs\r
 503      * operation or an incoming Job document.\r
 504      *\r
 505      * @see #AwsIotJobsCallbackParam_t for more information on the second parameter.\r
 506      */\r
 507     void ( * function )( void *,\r
 508                          AwsIotJobsCallbackParam_t * );\r
 509 \r
 510     /**\r
 511      * @brief Callback function to replace when passed to @ref jobs_function_setnotifynextcallback\r
 512      * or @ref jobs_function_setnotifypendingcallback.\r
 513      *\r
 514      * This member is ignored by Jobs operation functions.\r
 515      *\r
 516      * The number of callbacks of each type that may be registered for each Thing\r
 517      * is limited by @ref AWS_IOT_JOBS_NOTIFY_CALLBACKS. If @ref AWS_IOT_JOBS_NOTIFY_CALLBACKS\r
 518      * is `2`, that means that a maximum of `2` NOTIFY PENDING and `2` NOTIFY NEXT callbacks\r
 519      * (`4` total callbacks) may be set. This member is used to replace an existing callback\r
 520      * with a new one.\r
 521      *\r
 522      * To add a new callback:\r
 523      * @code{c}\r
 524      * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;\r
 525      *\r
 526      * callbackInfo.function = _newCallback;\r
 527      * callbackInfo.oldFunction = NULL;\r
 528      * @endcode\r
 529      *\r
 530      * For example, if the function `_oldCallback()` is currently registered:\r
 531      * - To replace `_oldCallback()` with a new callback function `_newCallback()`:\r
 532      * @code{c}\r
 533      * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;\r
 534      *\r
 535      * callbackInfo.function = _newCallback;\r
 536      * callbackInfo.oldFunction = _oldCallback;\r
 537      * @endcode\r
 538      * - To remove `_oldCallback()`:\r
 539      * @code{c}\r
 540      * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;\r
 541      *\r
 542      * callbackInfo.function = NULL;\r
 543      * callbackInfo.oldFunction = _oldCallback;\r
 544      * @endcode\r
 545      */\r
 546     void ( * oldFunction )( void *,\r
 547                             AwsIotJobsCallbackParam_t * );\r
 548 } AwsIotJobsCallbackInfo_t;\r
 549 \r
 550 /**\r
 551  * @ingroup jobs_datatypes_paramstructs\r
 552  * @brief Common information provided to Jobs requests.\r
 553  *\r
 554  * @paramfor @ref jobs_function_getpendingasync, @ref jobs_function_getpendingsync,\r
 555  * @ref jobs_function_startnextasync, @ref jobs_function_startnextsync\r
 556  * @ref jobs_function_describeasync, @ref jobs_function_describesync,\r
 557  * @ref jobs_function_updateasync, @ref jobs_function_updatesync\r
 558  *\r
 559  * @initializer{AwsIotJobsRequestInfo_t,AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER}\r
 560  */\r
 561 typedef struct AwsIotJobsRequestInfo\r
 562 {\r
 563     /**\r
 564      * @brief The MQTT connection to use for the Jobs request.\r
 565      */\r
 566     IotMqttConnection_t mqttConnection;\r
 567 \r
 568     /* These members allow Jobs commands to be retried. Be careful that duplicate\r
 569      * commands do no cause unexpected application behavior. Use of QoS 0 is recommended. */\r
 570     IotMqttQos_t qos;        /**< @brief QoS when sending the Jobs command. See #IotMqttPublishInfo_t.qos. */\r
 571     uint32_t retryLimit;     /**< @brief Maximum number of retries for the Jobs command. See #IotMqttPublishInfo_t.retryLimit. */\r
 572     uint32_t retryMs;        /**< @brief First retry time for the Jobs command. See IotMqttPublishInfo_t.retryMs. */\r
 573 \r
 574     /**\r
 575      * @brief Function to allocate memory for an incoming response.\r
 576      *\r
 577      * This only needs to be set if #AWS_IOT_JOBS_FLAG_WAITABLE is passed.\r
 578      */\r
 579     void * ( *mallocResponse )( size_t );\r
 580 \r
 581     /**\r
 582      * @brief The Thing Name associated with the Job.\r
 583      */\r
 584     const char * pThingName;\r
 585 \r
 586     /**\r
 587      * @brief Length of #AwsIotJobsRequestInfo_t.pThingName.\r
 588      */\r
 589     size_t thingNameLength;\r
 590 \r
 591     /**\r
 592      * @brief The Job ID to update.\r
 593      *\r
 594      * This may be set to #AWS_IOT_JOBS_NEXT_JOB to update the next pending Job.\r
 595      * When using #AWS_IOT_JOBS_NEXT_JOB, #AwsIotJobsRequestInfo_t.jobIdLength\r
 596      * should be set to #AWS_IOT_JOBS_NEXT_JOB_LENGTH.\r
 597      *\r
 598      * This parameter is ignored for calls to @ref jobs_function_getpendingasync,\r
 599      * @ref jobs_function_getpendingsync, @ref jobs_function_startnextasync,\r
 600      * and @ref jobs_function_startnextsync.\r
 601      */\r
 602     const char * pJobId;\r
 603 \r
 604     /**\r
 605      * @brief Length of #AwsIotJobsRequestInfo_t.pJobId.\r
 606      *\r
 607      * This parameter is ignored for calls to @ref jobs_function_getpendingasync,\r
 608      * @ref jobs_function_getpendingsync, @ref jobs_function_startnextasync,\r
 609      * and @ref jobs_function_startnextsync.\r
 610      */\r
 611     size_t jobIdLength;\r
 612 \r
 613     /**\r
 614      * @brief An arbitrary string that identifies this Job update to the Jobs\r
 615      * service.\r
 616      *\r
 617      * The recommended value is #AWS_IOT_JOBS_CLIENT_TOKEN_AUTOGENERATE.\r
 618      */\r
 619     const char * pClientToken;\r
 620 \r
 621     /**\r
 622      * @brief Length of #AwsIotJobsRequestInfo_t.pClientToken.\r
 623      */\r
 624     size_t clientTokenLength;\r
 625 } AwsIotJobsRequestInfo_t;\r
 626 \r
 627 /**\r
 628  * @ingroup jobs_datatypes_paramstructs\r
 629  * @brief Output parameter of blocking Jobs API functions.\r
 630  *\r
 631  * @paramfor @ref jobs_function_getpendingsync, @ref jobs_function_startnextsync,\r
 632  * @ref jobs_function_describesync, @ref jobs_function_updatesync,\r
 633  * @ref jobs_function_wait\r
 634  *\r
 635  * Provides the response received from the Jobs service. The buffer for the\r
 636  * response is allocated with #AwsIotJobsRequestInfo_t.mallocResponse.\r
 637  *\r
 638  * @initializer{AwsIotJobsResponse_t,AWS_IOT_JOBS_RESPONSE_INITIALIZER}\r
 639  */\r
 640 typedef struct AwsIotJobsResponse\r
 641 {\r
 642     const char * pJobsResponse; /**< @brief JSON response received from the Jobs service. */\r
 643     size_t jobsResponseLength;  /**< @brief Length of #AwsIotJobsResponse_t.pJobsResponse. */\r
 644 } AwsIotJobsResponse_t;\r
 645 \r
 646 /**\r
 647  * @ingroup jobs_datatypes_paramstructs\r
 648  * @brief Information on a Job update for @ref jobs_function_startnextasync and\r
 649  * @ref jobs_function_updateasync. These functions modify a Job's state.\r
 650  *\r
 651  * @paramfor @ref jobs_function_startnextasync, @ref jobs_function_startnextsync,\r
 652  * @ref jobs_function_updateasync, and @ref jobs_function_updatesync.\r
 653  *\r
 654  * @initializer{AwsIotJobsUpdateInfo_t,AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER}\r
 655  */\r
 656 typedef struct AwsIotJobsUpdateInfo\r
 657 {\r
 658     /**\r
 659      * @brief The new status to report as a Job execution update.\r
 660      *\r
 661      * Valid values are:\r
 662      * - #AWS_IOT_JOB_STATE_IN_PROGRESS\r
 663      * - #AWS_IOT_JOB_STATE_FAILED\r
 664      * - #AWS_IOT_JOB_STATE_SUCCEEDED\r
 665      * - #AWS_IOT_JOB_STATE_REJECTED\r
 666      *\r
 667      * This parameter is ignored for calls to @ref jobs_function_startnextasync and\r
 668      * @ref jobs_function_startnextsync. These functions always set the state\r
 669      * to #AWS_IOT_JOB_STATE_IN_PROGRESS.\r
 670      */\r
 671     AwsIotJobState_t newStatus;\r
 672 \r
 673     /**\r
 674      * @brief The expected current version of job execution.\r
 675      *\r
 676      * Each time a Job update is sent (for the same `JobId`), the version stored\r
 677      * on the AWS IoT Jobs service is updated. If this value does not match the\r
 678      * value stored by the Jobs service, the Job update is rejected with the code\r
 679      * #AWS_IOT_JOBS_VERSION_MISMATCH.\r
 680      *\r
 681      * This value is useful for ensuring the order of Job updates, i.e. that the\r
 682      * Jobs service does not overwrite a later update with a previous one. If not\r
 683      * needed, it can be set to #AWS_IOT_JOBS_NO_VERSION.\r
 684      *\r
 685      * This parameter is ignored for calls to @ref jobs_function_startnextasync and\r
 686      * @ref jobs_function_startnextsync.\r
 687      */\r
 688     uint32_t expectedVersion;\r
 689 \r
 690     /**\r
 691      * @brief An application-defined value that identifies a Job execution on a\r
 692      * specific device.\r
 693      *\r
 694      * The Jobs service provides commands for tracking the status of Job execution\r
 695      * on a specific target. Therefore, this value is used to provide a unique\r
 696      * identifier of a specific Job execution on a specific target.\r
 697      *\r
 698      * This value is optional. It may be set to #AWS_IOT_JOBS_NO_EXECUTION_NUMBER\r
 699      * if not needed.\r
 700      *\r
 701      * This parameter is ignored for calls to @ref jobs_function_startnextasync and\r
 702      * @ref jobs_function_startnextsync.\r
 703      */\r
 704     int32_t executionNumber;\r
 705 \r
 706     /**\r
 707      * @brief The amount of time (in minutes) before a new Job update must be reported.\r
 708      *\r
 709      * If this timeout expires without a new Job update being reported (for the same\r
 710      * `jobId`), the Job's status is set to #AWS_IOT_JOB_STATE_TIMED_OUT. Sending a\r
 711      * new Job update will reset this step timeout; a value of #AWS_IOT_JOBS_NO_TIMEOUT\r
 712      * will clear any previous step timeout.\r
 713      *\r
 714      * Valid values are between 1 and 10,080 (7 days). This value is optional. It may\r
 715      * be set to #AWS_IOT_JOBS_NO_TIMEOUT if not needed.\r
 716      */\r
 717     int32_t stepTimeoutInMinutes;\r
 718 \r
 719     /**\r
 720      * @brief Whether the Job response document should contain the `JobExecutionState`.\r
 721      *\r
 722      * The default value is `false`.\r
 723      *\r
 724      * This parameter is ignored for calls to @ref jobs_function_startnextasync and\r
 725      * @ref jobs_function_startnextsync.\r
 726      */\r
 727     bool includeJobExecutionState;\r
 728 \r
 729     /**\r
 730      * @brief Whether the Job response document should contain the `JobDocument`.\r
 731      *\r
 732      * The default value is `false`.\r
 733      *\r
 734      * This parameter is ignored for calls to @ref jobs_function_startnextasync and\r
 735      * @ref jobs_function_startnextsync.\r
 736      */\r
 737     bool includeJobDocument;\r
 738 \r
 739     /**\r
 740      * @brief An application-defined set of JSON name-value pairs that describe\r
 741      * the status of Job execution.\r
 742      *\r
 743      * This value is optional. It may be set to #AWS_IOT_JOBS_NO_STATUS_DETAILS\r
 744      * if not needed.\r
 745      */\r
 746     const char * pStatusDetails;\r
 747 \r
 748     /**\r
 749      * @brief Length of #AwsIotJobsUpdateInfo_t.pStatusDetails.\r
 750      */\r
 751     size_t statusDetailsLength;\r
 752 } AwsIotJobsUpdateInfo_t;\r
 753 \r
 754 /*------------------------- Jobs defined constants --------------------------*/\r
 755 \r
 756 /**\r
 757  * @brief Set #AwsIotJobsRequestInfo_t.pJobId to this value to use the next pending\r
 758  * Job as the Job ID.\r
 759  *\r
 760  * @note The value of this constant may change at any time in future versions, but\r
 761  * its name will remain the same.\r
 762  */\r
 763 #define AWS_IOT_JOBS_NEXT_JOB                     ( "$next" )\r
 764 \r
 765 /**\r
 766  * @brief Length of #AWS_IOT_JOBS_NEXT_JOB.\r
 767  *\r
 768  * Set #AwsIotJobsRequestInfo_t.jobIdLength to this value when using\r
 769  * #AWS_IOT_JOBS_NEXT_JOB.\r
 770  *\r
 771  * @note The value of this constant may change at any time in future versions, but\r
 772  * its name will remain the same.\r
 773  */\r
 774 #define AWS_IOT_JOBS_NEXT_JOB_LENGTH              ( sizeof( AWS_IOT_JOBS_NEXT_JOB ) - 1 )\r
 775 \r
 776 /**\r
 777  * @brief Set #AwsIotJobsRequestInfo_t.pClientToken to this value to automatically\r
 778  * generate a client token for the Jobs request.\r
 779  *\r
 780  * @note The value of this constant may change at any time in future versions, but\r
 781  * its name will remain the same.\r
 782  */\r
 783 #define AWS_IOT_JOBS_CLIENT_TOKEN_AUTOGENERATE    ( NULL )\r
 784 \r
 785 /**\r
 786  * @brief Set #AwsIotJobsUpdateInfo_t.expectedVersion to this value to omit the\r
 787  * version in the Jobs request.\r
 788  *\r
 789  * @note The value of this constant may change at any time in future versions, but\r
 790  * its name will remain the same.\r
 791  */\r
 792 #define AWS_IOT_JOBS_NO_VERSION                   ( 0 )\r
 793 \r
 794 /**\r
 795  * @brief Set #AwsIotJobsUpdateInfo_t.executionNumber to this value or pass it to\r
 796  * @ref jobs_function_describeasync to omit the execution number in the Jobs request.\r
 797  *\r
 798  * @note The value of this constant may change at any time in future versions, but\r
 799  * its name will remain the same.\r
 800  */\r
 801 #define AWS_IOT_JOBS_NO_EXECUTION_NUMBER          ( -1 )\r
 802 \r
 803 /**\r
 804  * @brief Set #AwsIotJobsUpdateInfo_t.stepTimeoutInMinutes to this value to omit the\r
 805  * step timeout in the Jobs request.\r
 806  *\r
 807  * @note The value of this constant may change at any time in future versions, but\r
 808  * its name will remain the same.\r
 809  */\r
 810 #define AWS_IOT_JOBS_NO_TIMEOUT                   ( 0 )\r
 811 \r
 812 /**\r
 813  * @brief Set #AwsIotJobsUpdateInfo_t.stepTimeoutInMinutes to this value to cancel\r
 814  * any previously set step timeout.\r
 815  *\r
 816  * The Jobs service will return an (InvalidRequest)[@ref AWS_IOT_JOBS_INVALID_REQUEST]\r
 817  * error if this value is used without an existing step timeout.\r
 818  *\r
 819  * @note The value of this constant may change at any time in future versions, but\r
 820  * its name will remain the same.\r
 821  */\r
 822 #define AWS_IOT_JOBS_CANCEL_TIMEOUT               ( -1 )\r
 823 \r
 824 /**\r
 825  * @brief Set #AwsIotJobsUpdateInfo_t.pStatusDetails to this value to omit the\r
 826  * status details in the Jobs request.\r
 827  *\r
 828  * @note The value of this constant may change at any time in future versions, but\r
 829  * its name will remain the same.\r
 830  */\r
 831 #define AWS_IOT_JOBS_NO_STATUS_DETAILS            ( NULL )\r
 832 \r
 833 /**\r
 834  * @constantspage{jobs,Jobs library}\r
 835  *\r
 836  * @section jobs_constants_initializers Jobs Initializers\r
 837  * @brief Provides default values for the data types of the Jobs library.\r
 838  *\r
 839  * @snippet this define_jobs_initializers\r
 840  *\r
 841  * All user-facing data types of the Jobs library should be initialized\r
 842  * using one of the following.\r
 843  *\r
 844  * @warning Failing to initialize a Jobs data type with the appropriate\r
 845  * initializer may result in undefined behavior!\r
 846  * @note The initializers may change at any time in future versions, but their\r
 847  * names will remain the same.\r
 848  *\r
 849  * <b>Example</b>\r
 850  * @code{c}\r
 851  * AwsIotJobsCallbackInfo_t callbackInfo = AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER;\r
 852  * AwsIotJobsRequestInfo_t requestInfo = AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER;\r
 853  * AwsIotJobsUpdateInfo_t updateInfo = AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER;\r
 854  * AwsIotJobsOperation_t operation = AWS_IOT_JOBS_OPERATION_INITIALIZER;\r
 855  * AwsIotJobsResponse_t response = AWS_IOT_JOBS_RESPONSE_INITIALIZER;\r
 856  * @endcode\r
 857  *\r
 858  * @section jobs_constants_flags Jobs Function Flags\r
 859  * @brief Flags that modify the behavior of Jobs library functions.\r
 860  *\r
 861  * Flags should be bitwise-ORed with each other to change the behavior of\r
 862  * Jobs library functions.\r
 863  *\r
 864  * The following flags are valid for the Jobs operation functions:\r
 865  * @ref jobs_function_getpendingasync, @ref jobs_function_startnextasync,\r
 866  * @ref jobs_function_describeasync, @ref jobs_function_updateasync,\r
 867  * and their blocking versions.\r
 868  * - #AWS_IOT_JOBS_FLAG_WAITABLE <br>\r
 869  *   @copybrief AWS_IOT_JOBS_FLAG_WAITABLE\r
 870  * - #AWS_IOT_JOBS_FLAG_KEEP_SUBSCRIPTIONS <br>\r
 871  *   @copybrief AWS_IOT_JOBS_FLAG_KEEP_SUBSCRIPTIONS\r
 872  *\r
 873  * The following flags are valid for @ref jobs_function_removepersistentsubscriptions.\r
 874  * These flags are not valid for the Jobs operation functions.\r
 875  * - #AWS_IOT_JOBS_FLAG_REMOVE_GET_PENDING_SUBSCRIPTIONS <br>\r
 876  *   @copybrief AWS_IOT_JOBS_FLAG_REMOVE_GET_PENDING_SUBSCRIPTIONS\r
 877  * - #AWS_IOT_JOBS_FLAG_REMOVE_START_NEXT_SUBSCRIPTIONS <br>\r
 878  *   @copybrief AWS_IOT_JOBS_FLAG_REMOVE_START_NEXT_SUBSCRIPTIONS\r
 879  * - #AWS_IOT_JOBS_FLAG_REMOVE_DESCRIBE_SUBSCRIPTIONS <br>\r
 880  *   @copybrief AWS_IOT_JOBS_FLAG_REMOVE_DESCRIBE_SUBSCRIPTIONS\r
 881  * - #AWS_IOT_JOBS_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS <br>\r
 882  *   @copybrief AWS_IOT_JOBS_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS\r
 883  *\r
 884  * @note The values of the flags may change at any time in future versions, but\r
 885  * their names will remain the same. Additionally, flags which may be used at\r
 886  * the same time will be bitwise-exclusive of each other.\r
 887  */\r
 888 \r
 889 /* @[define_jobs_initializers] */\r
 890 #define AWS_IOT_JOBS_CALLBACK_INFO_INITIALIZER    { 0 } /**< @brief Initializer for #AwsIotJobsCallbackInfo_t. */\r
 891 /** @brief Initializer for #AwsIotJobsRequestInfo_t. */\r
 892 #define AWS_IOT_JOBS_REQUEST_INFO_INITIALIZER \\r
 893     { .pClientToken = AWS_IOT_JOBS_CLIENT_TOKEN_AUTOGENERATE }\r
 894 /** @brief Initializer for #AwsIotJobsUpdateInfo_t. */\r
 895 #define AWS_IOT_JOBS_UPDATE_INFO_INITIALIZER               \\r
 896     { .newStatus = AWS_IOT_JOB_STATE_IN_PROGRESS,          \\r
 897       .expectedVersion = AWS_IOT_JOBS_NO_VERSION,          \\r
 898       .executionNumber = AWS_IOT_JOBS_NO_EXECUTION_NUMBER, \\r
 899       .stepTimeoutInMinutes = AWS_IOT_JOBS_NO_TIMEOUT,     \\r
 900       .includeJobExecutionState = false,                   \\r
 901       .includeJobDocument = false,                         \\r
 902       .pStatusDetails = AWS_IOT_JOBS_NO_STATUS_DETAILS }\r
 903 #define AWS_IOT_JOBS_OPERATION_INITIALIZER    NULL  /**< @brief Initializer for #AwsIotJobsOperation_t. */\r
 904 #define AWS_IOT_JOBS_RESPONSE_INITIALIZER     { 0 } /**< @brief Initializer for #AwsIotJobsResponse_t. */\r
 905 /* @[define_jobs_initializers] */\r
 906 \r
 907 /**\r
 908  * @brief Allows the use of @ref jobs_function_wait for blocking until completion.\r
 909  *\r
 910  * This flag is only valid if passed to the functions @ref jobs_function_getpendingasync,\r
 911  * @ref jobs_function_startnextasync, @ref jobs_function_describeasync, or @ref jobs_function_updateasync.\r
 912  *\r
 913  * An #AwsIotJobsOperation_t <b>MUST</b> be provided if this flag is set.\r
 914  * Additionally, an #AwsIotJobsCallbackInfo_t <b>MUST NOT</b> be provided.\r
 915  *\r
 916  * When this flag is set, #AwsIotJobsRequestInfo_t.mallocResponse must be set\r
 917  * to a function that can be used to allocate memory to hold an incoming response.\r
 918  *\r
 919  * @note If this flag is set, @ref jobs_function_wait <b>MUST</b> be called to\r
 920  * clean up resources.\r
 921  */\r
 922 #define AWS_IOT_JOBS_FLAG_WAITABLE                            ( 0x00000001 )\r
 923 \r
 924 /**\r
 925  * @brief Maintain the subscriptions for the Jobs operation topics, even after\r
 926  * this function returns.\r
 927  *\r
 928  * This flag is only valid if passed to the functions @ref jobs_function_getpendingasync,\r
 929  * @ref jobs_function_startnextasync, @ref jobs_function_describeasync, or @ref jobs_function_updateasync,\r
 930  * and their blocking versions.\r
 931  *\r
 932  * The Jobs service reports results of Jobs operations by publishing\r
 933  * messages to MQTT topics. By default, the Job operation functions subscribe to the\r
 934  * necessary topics, wait for the Jobs service to publish the result of the\r
 935  * Jobs operation, then unsubscribe from those topics. This workflow is suitable\r
 936  * for infrequent Jobs operations, but is inefficient for frequent, periodic\r
 937  * Jobs operations (where subscriptions for the Jobs operation topics would be\r
 938  * constantly added and removed).\r
 939  *\r
 940  * This flag causes the Jobs operation functions to maintain Jobs operation\r
 941  * topic subscriptions, even after the function returns. These subscriptions\r
 942  * may then be used by a future call to the same function.\r
 943  *\r
 944  * This flags only needs to be set once, after which subscriptions are maintained\r
 945  * and reused for a specific Thing Name and Jobs function. The function @ref\r
 946  * jobs_function_removepersistentsubscriptions may be used to remove\r
 947  * subscriptions maintained by this flag.\r
 948  */\r
 949 #define AWS_IOT_JOBS_FLAG_KEEP_SUBSCRIPTIONS                  ( 0x00000002 )\r
 950 \r
 951 /**\r
 952  * @brief Remove the persistent subscriptions from a Jobs get pending operation.\r
 953  *\r
 954  * This flag is only valid if passed to the function @ref\r
 955  * jobs_function_removepersistentsubscriptions.\r
 956  *\r
 957  * This flag may be passed to @ref jobs_function_removepersistentsubscriptions\r
 958  * to remove any subscriptions for a specific Thing Name maintained by a previous\r
 959  * call to @ref jobs_function_getpendingasync or @ref jobs_function_getpendingsync.\r
 960  *\r
 961  * @warning Do not call @ref jobs_function_removepersistentsubscriptions with\r
 962  * this flag for Thing Names with any in-progress Jobs get pending operations.\r
 963  */\r
 964 #define AWS_IOT_JOBS_FLAG_REMOVE_GET_PENDING_SUBSCRIPTIONS    ( 0x00000001 )\r
 965 \r
 966 /**\r
 967  * @brief Remove the persistent subscriptions from a Jobs start next operation.\r
 968  *\r
 969  * This flag is only valid if passed to the function @ref\r
 970  * jobs_function_removepersistentsubscriptions.\r
 971  *\r
 972  * This flag may be passed to @ref jobs_function_removepersistentsubscriptions\r
 973  * to remove any subscriptions for a specific Thing Name maintained by a previous\r
 974  * call to @ref jobs_function_startnextasync or @ref jobs_function_startnextsync.\r
 975  *\r
 976  * @warning Do not call @ref jobs_function_removepersistentsubscriptions with\r
 977  * this flag for Thing Names with any in-progress Jobs start next operations.\r
 978  */\r
 979 #define AWS_IOT_JOBS_FLAG_REMOVE_START_NEXT_SUBSCRIPTIONS     ( 0x00000002 )\r
 980 \r
 981 /**\r
 982  * @brief Remove the persistent subscriptions from a Jobs describe operation.\r
 983  *\r
 984  * This flag is only valid if passed to the function @ref\r
 985  * jobs_function_removepersistentsubscriptions.\r
 986  *\r
 987  * This flag may be passed to @ref jobs_function_removepersistentsubscriptions\r
 988  * to remove any subscriptions for a specific Thing Name maintained by a previous\r
 989  * call to @ref jobs_function_describeasync or @ref jobs_function_describesync.\r
 990  *\r
 991  * @warning Do not call @ref jobs_function_removepersistentsubscriptions with\r
 992  * this flag for Thing Names with any in-progress Jobs describe operations.\r
 993  */\r
 994 #define AWS_IOT_JOBS_FLAG_REMOVE_DESCRIBE_SUBSCRIPTIONS       ( 0x00000004 )\r
 995 \r
 996 /**\r
 997  * @brief Remove the persistent subscriptions from a Jobs update operation.\r
 998  *\r
 999  * This flag is only valid if passed to the function @ref\r
1000  * jobs_function_removepersistentsubscriptions.\r
1001  *\r
1002  * This flag may be passed to @ref jobs_function_removepersistentsubscriptions\r
1003  * to remove any subscriptions for a specific Thing Name maintained by a previous\r
1004  * call to @ref jobs_function_updateasync or @ref jobs_function_updatesync.\r
1005  *\r
1006  * @warning Do not call @ref jobs_function_removepersistentsubscriptions with\r
1007  * this flag for Thing Names with any in-progress Jobs update operations.\r
1008  */\r
1009 #define AWS_IOT_JOBS_FLAG_REMOVE_UPDATE_SUBSCRIPTIONS         ( 0x00000008 )\r
1010 \r
1011 #endif /* ifndef AWS_IOT_JOBS_TYPES_H_ */\r