git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/FreeRTOS-IoT-Libraries/c_sdk/standard/mqtt/include/types/iot_mqtt_types.h

   1 /*\r
   2  * IoT MQTT V2.1.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 iot_mqtt_types.h\r
  25  * @brief MQTT library types.\r
  26  */\r
  27 \r
  28 #ifndef IOT_MQTT_TYPES_H_\r
  29 #define IOT_MQTT_TYPES_H_\r
  30 \r
  31 /* The config header is always included first. */\r
  32 #include "iot_config.h"\r
  33 \r
  34 /* Standard includes. */\r
  35 #include <stdbool.h>\r
  36 #include <stdint.h>\r
  37 #include <stddef.h>\r
  38 \r
  39 /* Type includes. */\r
  40 #include "types/iot_platform_types.h"\r
  41 #include "types/iot_taskpool_types_freertos.h"\r
  42 \r
  43 /* Platform network include. */\r
  44 #include "platform/iot_network.h"\r
  45 \r
  46 /*---------------------------- MQTT handle types ----------------------------*/\r
  47 \r
  48 /**\r
  49  * @handles{mqtt,MQTT library}\r
  50  */\r
  51 \r
  52 /**\r
  53  * @ingroup mqtt_datatypes_handles\r
  54  * @brief Opaque handle of an MQTT connection.\r
  55  *\r
  56  * MQTT connection handle type.  MQTT connection handles are created by\r
  57  * successful calls to @ref mqtt_function_connect and are used to refer to\r
  58  * the connection when calling MQTT library functions.\r
  59  *\r
  60  * A call to @ref mqtt_function_disconnect makes a connection handle invalid. Once\r
  61  * @ref mqtt_function_disconnect returns, the connection handle should no longer\r
  62  * be used.\r
  63  *\r
  64  * @initializer{IotMqttConnection_t,IOT_MQTT_CONNECTION_INITIALIZER}\r
  65  */\r
  66 typedef struct _mqttConnection   * IotMqttConnection_t;\r
  67 \r
  68 /**\r
  69  * @ingroup mqtt_datatypes_handles\r
  70  * @brief Opaque handle that references an in-progress MQTT operation.\r
  71  *\r
  72  * Set as an output parameter of @ref mqtt_function_publishasync, @ref mqtt_function_subscribeasync,\r
  73  * and @ref mqtt_function_unsubscribeasync. These functions queue an MQTT operation; the result\r
  74  * of the operation is unknown until a response from the MQTT server is received. Therefore,\r
  75  * this handle serves as a reference to MQTT operations awaiting MQTT server response.\r
  76  *\r
  77  * This reference will be valid from the successful return of @ref mqtt_function_publishasync,\r
  78  * @ref mqtt_function_subscribeasync, or @ref mqtt_function_unsubscribeasync. The reference becomes\r
  79  * invalid once the [completion callback](@ref IotMqttCallbackInfo_t) is invoked, or\r
  80  * @ref mqtt_function_wait returns.\r
  81  *\r
  82  * @initializer{IotMqttOperation_t,IOT_MQTT_OPERATION_INITIALIZER}\r
  83  *\r
  84  * @see @ref mqtt_function_wait and #IOT_MQTT_FLAG_WAITABLE for waiting on a reference.\r
  85  * #IotMqttCallbackInfo_t and #IotMqttCallbackParam_t for an asynchronous notification\r
  86  * of completion.\r
  87  */\r
  88 typedef struct _mqttOperation    * IotMqttOperation_t;\r
  89 \r
  90 /*-------------------------- MQTT enumerated types --------------------------*/\r
  91 \r
  92 /**\r
  93  * @enums{mqtt,MQTT library}\r
  94  */\r
  95 \r
  96 /**\r
  97  * @ingroup mqtt_datatypes_enums\r
  98  * @brief Return codes of [MQTT functions](@ref mqtt_functions).\r
  99  *\r
 100  * The function @ref mqtt_function_strerror can be used to get a return code's\r
 101  * description.\r
 102  */\r
 103 typedef enum IotMqttError\r
 104 {\r
 105     /**\r
 106      * @brief MQTT operation completed successfully.\r
 107      *\r
 108      * Functions that may return this value:\r
 109      * - @ref mqtt_function_connect\r
 110      * - @ref mqtt_function_publishasync with QoS 0 parameter\r
 111      * - @ref mqtt_function_wait\r
 112      * - @ref mqtt_function_subscribesync\r
 113      * - @ref mqtt_function_unsubscribesync\r
 114      * - @ref mqtt_function_publishsync\r
 115      *\r
 116      * Will also be the value of an operation completion callback's\r
 117      * #IotMqttCallbackParam_t.result when successful.\r
 118      */\r
 119     IOT_MQTT_SUCCESS = 0,\r
 120 \r
 121     /**\r
 122      * @brief MQTT operation queued, awaiting result.\r
 123      *\r
 124      * Functions that may return this value:\r
 125      * - @ref mqtt_function_subscribeasync\r
 126      * - @ref mqtt_function_unsubscribeasync\r
 127      * - @ref mqtt_function_publishasync with QoS 1 parameter\r
 128      */\r
 129     IOT_MQTT_STATUS_PENDING = 1,\r
 130 \r
 131     /**\r
 132      * @brief Initialization failed.\r
 133      *\r
 134      * Functions that may return this value:\r
 135      * - @ref mqtt_function_init\r
 136      */\r
 137     IOT_MQTT_INIT_FAILED = 2,\r
 138 \r
 139     /**\r
 140      * @brief At least one parameter is invalid.\r
 141      *\r
 142      * Functions that may return this value:\r
 143      * - @ref mqtt_function_connect\r
 144      * - @ref mqtt_function_subscribeasync and @ref mqtt_function_subscribesync\r
 145      * - @ref mqtt_function_unsubscribeasync and @ref mqtt_function_unsubscribesync\r
 146      * - @ref mqtt_function_publishasync and @ref mqtt_function_publishsync\r
 147      * - @ref mqtt_function_wait\r
 148      */\r
 149     IOT_MQTT_BAD_PARAMETER = 3,\r
 150 \r
 151     /**\r
 152      * @brief MQTT operation failed because of memory allocation failure.\r
 153      *\r
 154      * Functions that may return this value:\r
 155      * - @ref mqtt_function_connect\r
 156      * - @ref mqtt_function_subscribeasync and @ref mqtt_function_subscribesync\r
 157      * - @ref mqtt_function_unsubscribeasync and @ref mqtt_function_unsubscribesync\r
 158      * - @ref mqtt_function_publishasync and @ref mqtt_function_publishsync\r
 159      */\r
 160     IOT_MQTT_NO_MEMORY = 4,\r
 161 \r
 162     /**\r
 163      * @brief MQTT operation failed because the network was unusable.\r
 164      *\r
 165      * This return value may indicate that the network is disconnected.\r
 166      *\r
 167      * Functions that may return this value:\r
 168      * - @ref mqtt_function_connect\r
 169      * - @ref mqtt_function_wait\r
 170      * - @ref mqtt_function_subscribesync\r
 171      * - @ref mqtt_function_unsubscribesync\r
 172      * - @ref mqtt_function_publishsync\r
 173      *\r
 174      * May also be the value of an operation completion callback's\r
 175      * #IotMqttCallbackParam_t.result.\r
 176      */\r
 177     IOT_MQTT_NETWORK_ERROR = 5,\r
 178 \r
 179     /**\r
 180      * @brief MQTT operation could not be scheduled, i.e. enqueued for sending.\r
 181      *\r
 182      * Functions that may return this value:\r
 183      * - @ref mqtt_function_connect\r
 184      * - @ref mqtt_function_subscribeasync and @ref mqtt_function_subscribesync\r
 185      * - @ref mqtt_function_unsubscribeasync and @ref mqtt_function_unsubscribesync\r
 186      * - @ref mqtt_function_publishasync and @ref mqtt_function_publishsync\r
 187      */\r
 188     IOT_MQTT_SCHEDULING_ERROR = 6,\r
 189 \r
 190     /**\r
 191      * @brief MQTT response packet received from the network is malformed.\r
 192      *\r
 193      * Functions that may return this value:\r
 194      * - @ref mqtt_function_connect\r
 195      * - @ref mqtt_function_wait\r
 196      * - @ref mqtt_function_subscribesync\r
 197      * - @ref mqtt_function_unsubscribesync\r
 198      * - @ref mqtt_function_publishsync\r
 199      *\r
 200      * May also be the value of an operation completion callback's\r
 201      * #IotMqttCallbackParam_t.result.\r
 202      *\r
 203      * @note If this value is received, the network connection has been closed.\r
 204      */\r
 205     IOT_MQTT_BAD_RESPONSE = 7,\r
 206 \r
 207     /**\r
 208      * @brief A blocking MQTT operation timed out.\r
 209      *\r
 210      * Functions that may return this value:\r
 211      * - @ref mqtt_function_connect\r
 212      * - @ref mqtt_function_wait\r
 213      * - @ref mqtt_function_subscribesync\r
 214      * - @ref mqtt_function_unsubscribesync\r
 215      * - @ref mqtt_function_publishsync\r
 216      */\r
 217     IOT_MQTT_TIMEOUT = 8,\r
 218 \r
 219     /**\r
 220      * @brief A CONNECT or at least one subscription was refused by the server.\r
 221      *\r
 222      * Functions that may return this value:\r
 223      * - @ref mqtt_function_connect\r
 224      * - @ref mqtt_function_wait, but only when its #IotMqttOperation_t parameter\r
 225      * is associated with a SUBSCRIBE operation.\r
 226      * - @ref mqtt_function_subscribesync\r
 227      *\r
 228      * May also be the value of an operation completion callback's\r
 229      * #IotMqttCallbackParam_t.result for a SUBSCRIBE.\r
 230      *\r
 231      * @note If this value is returned and multiple subscriptions were passed to\r
 232      * @ref mqtt_function_subscribeasync (or @ref mqtt_function_subscribesync), it's\r
 233      * still possible that some of the subscriptions succeeded. This value only\r
 234      * signifies that AT LEAST ONE subscription was rejected. The function @ref\r
 235      * mqtt_function_issubscribed can be used to determine which subscriptions\r
 236      * were accepted or rejected.\r
 237      */\r
 238     IOT_MQTT_SERVER_REFUSED = 9,\r
 239 \r
 240     /**\r
 241      * @brief A QoS 1 PUBLISH received no response and [the retry limit]\r
 242      * (#IotMqttPublishInfo_t.retryLimit) was reached.\r
 243      *\r
 244      * Functions that may return this value:\r
 245      * - @ref mqtt_function_wait, but only when its #IotMqttOperation_t parameter\r
 246      * is associated with a QoS 1 PUBLISH operation\r
 247      * - @ref mqtt_function_publishsync\r
 248      *\r
 249      * May also be the value of an operation completion callback's\r
 250      * #IotMqttCallbackParam_t.result for a QoS 1 PUBLISH.\r
 251      */\r
 252     IOT_MQTT_RETRY_NO_RESPONSE = 10,\r
 253 \r
 254     /**\r
 255      * @brief An API function was called before @ref mqtt_function_init.\r
 256      *\r
 257      * Functions that may return this value:\r
 258      * - @ref mqtt_function_connect\r
 259      * - @ref mqtt_function_subscribeasync\r
 260      * - @ref mqtt_function_subscribesync\r
 261      * - @ref mqtt_function_unsubscribeasync\r
 262      * - @ref mqtt_function_unsubscribesync\r
 263      * - @ref mqtt_function_publishasync\r
 264      * - @ref mqtt_function_publishsync\r
 265      * - @ref mqtt_function_wait\r
 266      */\r
 267     IOT_MQTT_NOT_INITIALIZED = 11\r
 268 } IotMqttError_t;\r
 269 \r
 270 /**\r
 271  * @ingroup mqtt_datatypes_enums\r
 272  * @brief Types of MQTT operations.\r
 273  *\r
 274  * The function @ref mqtt_function_operationtype can be used to get an operation\r
 275  * type's description.\r
 276  */\r
 277 typedef enum IotMqttOperationType\r
 278 {\r
 279     IOT_MQTT_CONNECT,           /**< Client-to-server CONNECT. */\r
 280     IOT_MQTT_PUBLISH_TO_SERVER, /**< Client-to-server PUBLISH. */\r
 281     IOT_MQTT_PUBACK,            /**< Client-to-server PUBACK. */\r
 282     IOT_MQTT_SUBSCRIBE,         /**< Client-to-server SUBSCRIBE. */\r
 283     IOT_MQTT_UNSUBSCRIBE,       /**< Client-to-server UNSUBSCRIBE. */\r
 284     IOT_MQTT_PINGREQ,           /**< Client-to-server PINGREQ. */\r
 285     IOT_MQTT_DISCONNECT         /**< Client-to-server DISCONNECT. */\r
 286 } IotMqttOperationType_t;\r
 287 \r
 288 /**\r
 289  * @ingroup mqtt_datatypes_enums\r
 290  * @brief Quality of service levels for MQTT PUBLISH messages.\r
 291  *\r
 292  * All MQTT PUBLISH messages, including Last Will and Testament and messages\r
 293  * received on subscription filters, have an associated <i>Quality of Service</i>,\r
 294  * which defines any delivery guarantees for that message.\r
 295  * - QoS 0 messages will be delivered at most once. This is a "best effort"\r
 296  * transmission with no retransmissions.\r
 297  * - QoS 1 messages will be delivered at least once. See #IotMqttPublishInfo_t\r
 298  * for the retransmission strategy this library uses to redeliver messages\r
 299  * assumed to be lost.\r
 300  *\r
 301  * @attention QoS 2 is not supported by this library and should not be used.\r
 302  */\r
 303 typedef enum IotMqttQos\r
 304 {\r
 305     IOT_MQTT_QOS_0 = 0, /**< Delivery at most once. */\r
 306     IOT_MQTT_QOS_1 = 1, /**< Delivery at least once. See #IotMqttPublishInfo_t for client-side retry strategy. */\r
 307     IOT_MQTT_QOS_2 = 2  /**< Delivery exactly once. Unsupported, but enumerated for completeness. */\r
 308 } IotMqttQos_t;\r
 309 \r
 310 /**\r
 311  * @ingroup mqtt_datatypes_enums\r
 312  * @brief The reason that an MQTT connection (and its associated network connection)\r
 313  * was disconnected.\r
 314  *\r
 315  * When an MQTT connection is closed, its associated [disconnect callback]\r
 316  * (@ref IotMqttNetworkInfo_t::disconnectCallback) will be invoked. This type\r
 317  * is passed inside of an #IotMqttCallbackParam_t to provide a reason for the\r
 318  * disconnect.\r
 319  */\r
 320 typedef enum IotMqttDisconnectReason\r
 321 {\r
 322     IOT_MQTT_DISCONNECT_CALLED,   /**< @ref mqtt_function_disconnect was invoked. */\r
 323     IOT_MQTT_BAD_PACKET_RECEIVED, /**< An invalid packet was received from the network. */\r
 324     IOT_MQTT_KEEP_ALIVE_TIMEOUT   /**< Keep-alive response was not received within @ref IOT_MQTT_RESPONSE_WAIT_MS. */\r
 325 } IotMqttDisconnectReason_t;\r
 326 \r
 327 /*------------------------- MQTT parameter structs --------------------------*/\r
 328 \r
 329 /**\r
 330  * @paramstructs{mqtt,MQTT}\r
 331  */\r
 332 \r
 333 /**\r
 334  * @ingroup mqtt_datatypes_paramstructs\r
 335  * @brief Information on a PUBLISH message.\r
 336  *\r
 337  * @paramfor @ref mqtt_function_connect, @ref mqtt_function_publishasync\r
 338  *\r
 339  * Passed to @ref mqtt_function_publishasync as the message to publish and @ref\r
 340  * mqtt_function_connect as the Last Will and Testament (LWT) message.\r
 341  *\r
 342  * @initializer{IotMqttPublishInfo_t,IOT_MQTT_PUBLISH_INFO_INITIALIZER}\r
 343  *\r
 344  * #IotMqttPublishInfo_t.retryMs and #IotMqttPublishInfo_t.retryLimit are only\r
 345  * relevant to QoS 1 PUBLISH messages. They are ignored for QoS 0 PUBLISH\r
 346  * messages and LWT messages. These members control retransmissions of QoS 1\r
 347  * messages under the following rules:\r
 348  * - Retransmission is disabled when #IotMqttPublishInfo_t.retryLimit is 0.\r
 349  * After sending the PUBLISH, the library will wait indefinitely for a PUBACK.\r
 350  * - If #IotMqttPublishInfo_t.retryLimit is greater than 0, then QoS 1 publishes\r
 351  * that do not receive a PUBACK within #IotMqttPublishInfo_t.retryMs will be\r
 352  * retransmitted, up to #IotMqttPublishInfo_t.retryLimit times.\r
 353  *\r
 354  * Retransmission follows a truncated exponential backoff strategy. The constant\r
 355  * @ref IOT_MQTT_RETRY_MS_CEILING controls the maximum time between retransmissions.\r
 356  *\r
 357  * After #IotMqttPublishInfo_t.retryLimit retransmissions are sent, the MQTT\r
 358  * library will wait @ref IOT_MQTT_RESPONSE_WAIT_MS before a final check\r
 359  * for a PUBACK. If no PUBACK was received within this time, the QoS 1 PUBLISH\r
 360  * fails with the code #IOT_MQTT_RETRY_NO_RESPONSE.\r
 361  *\r
 362  * @note The lengths of the strings in this struct should not include the NULL\r
 363  * terminator. Strings in this struct do not need to be NULL-terminated.\r
 364  *\r
 365  * @note The AWS IoT MQTT broker does not support the DUP bit.  More\r
 366  * information about connecting to AWS IoT via MQTT is available\r
 367  * [here](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html).\r
 368  *\r
 369  * <b>Example</b>\r
 370  *\r
 371  * Consider a situation where\r
 372  * - @ref IOT_MQTT_RETRY_MS_CEILING is 60000\r
 373  * - #IotMqttPublishInfo_t.retryMs is 2000\r
 374  * - #IotMqttPublishInfo_t.retryLimit is 20\r
 375  *\r
 376  * A PUBLISH message will be retransmitted at the following times after the initial\r
 377  * transmission if no PUBACK is received:\r
 378  * - 2000 ms (2000 ms after previous transmission)\r
 379  * - 6000 ms (4000 ms after previous transmission)\r
 380  * - 14000 ms (8000 ms after previous transmission)\r
 381  * - 30000 ms (16000 ms after previous transmission)\r
 382  * - 62000 ms (32000 ms after previous transmission)\r
 383  * - 122000 ms, 182000 ms, 242000 ms... (every 60000 ms until 20 transmissions have been sent)\r
 384  *\r
 385  * After the 20th retransmission, the MQTT library will wait\r
 386  * @ref IOT_MQTT_RESPONSE_WAIT_MS before checking a final time for a PUBACK.\r
 387  */\r
 388 typedef struct IotMqttPublishInfo\r
 389 {\r
 390     IotMqttQos_t qos;         /**< @brief QoS of message. Must be 0 or 1. */\r
 391     bool retain;              /**< @brief MQTT message retain flag. */\r
 392 \r
 393     const char * pTopicName;  /**< @brief Topic name of PUBLISH. */\r
 394     uint16_t topicNameLength; /**< @brief Length of #IotMqttPublishInfo_t.pTopicName. */\r
 395 \r
 396     const void * pPayload;    /**< @brief Payload of PUBLISH. */\r
 397     size_t payloadLength;     /**< @brief Length of #IotMqttPublishInfo_t.pPayload. For LWT messages, this is limited to 65535. */\r
 398 \r
 399     uint32_t retryMs;         /**< @brief If no response is received within this time, the message is retransmitted. */\r
 400     uint32_t retryLimit;      /**< @brief How many times to attempt retransmission. */\r
 401 } IotMqttPublishInfo_t;\r
 402 \r
 403 /**\r
 404  * @ingroup mqtt_datatypes_paramstructs\r
 405  * @brief Parameter to an MQTT callback function.\r
 406  *\r
 407  * @paramfor MQTT callback functions\r
 408  *\r
 409  * The MQTT library passes this struct to a registered callback whenever an\r
 410  * operation completes, a message is received on a topic filter, or an MQTT\r
 411  * connection is disconnected.\r
 412  *\r
 413  * The members of this struct are different based on the callback trigger. If the\r
 414  * callback function was triggered for completed operation, the `operation`\r
 415  * member is valid. Otherwise, if the callback was triggered because of a\r
 416  * server-to-client PUBLISH, the `message` member is valid. Finally, if the callback\r
 417  * was triggered because of a disconnect, the `disconnectReason` member is valid.\r
 418  *\r
 419  * For an incoming PUBLISH, the `message.pTopicFilter` parameter provides the\r
 420  * subscription topic filter that matched the topic name in the PUBLISH. Because\r
 421  * topic filters may use MQTT wildcards, the topic filter may be different from the\r
 422  * topic name. This pointer must be treated as read-only; the topic filter must not\r
 423  * be modified. Additionally, the topic filter may go out of scope as soon as the\r
 424  * callback function returns, so it must be copied if it is needed at a later time.\r
 425  *\r
 426  * @attention Any pointers in this callback parameter may be freed as soon as\r
 427  * the [callback function](@ref IotMqttCallbackInfo_t.function) returns.\r
 428  * Therefore, data must be copied if it is needed after the callback function\r
 429  * returns.\r
 430  * @attention The MQTT library may set strings that are not NULL-terminated.\r
 431  *\r
 432  * @see #IotMqttCallbackInfo_t for the signature of a callback function.\r
 433  */\r
 434 typedef struct IotMqttCallbackParam\r
 435 {\r
 436     /**\r
 437      * @brief The MQTT connection associated with this completed operation,\r
 438      * incoming PUBLISH, or disconnect.\r
 439      *\r
 440      * [MQTT API functions](@ref mqtt_functions) are safe to call from a callback\r
 441      * for completed operations or incoming PUBLISH messages. However, blocking\r
 442      * function calls (including @ref mqtt_function_wait) are not recommended\r
 443      * (though still safe). Do not call any API functions from a disconnect\r
 444      * callback.\r
 445      */\r
 446     IotMqttConnection_t mqttConnection;\r
 447 \r
 448     union\r
 449     {\r
 450         /* Valid for completed operations. */\r
 451         struct\r
 452         {\r
 453             IotMqttOperationType_t type;  /**< @brief Type of operation that completed. */\r
 454             IotMqttOperation_t reference; /**< @brief Reference to the operation that completed. */\r
 455             IotMqttError_t result;        /**< @brief Result of operation, e.g. succeeded or failed. */\r
 456         } operation;\r
 457 \r
 458         /* Valid for incoming PUBLISH messages. */\r
 459         struct\r
 460         {\r
 461             const char * pTopicFilter;  /**< @brief Topic filter that matched the message. */\r
 462             uint16_t topicFilterLength; /**< @brief Length of `pTopicFilter`. */\r
 463             IotMqttPublishInfo_t info;  /**< @brief PUBLISH message received from the server. */\r
 464         } message;\r
 465 \r
 466         /* Valid when a connection is disconnected. */\r
 467         IotMqttDisconnectReason_t disconnectReason; /**< @brief Why the MQTT connection was disconnected. */\r
 468     } u;                                            /**< @brief Valid member depends on callback type. */\r
 469 } IotMqttCallbackParam_t;\r
 470 \r
 471 /**\r
 472  * @ingroup mqtt_datatypes_paramstructs\r
 473  * @brief MQTT callback function and context.\r
 474  *\r
 475  * @paramfor @ref mqtt_function_subscribeasync, @ref mqtt_function_unsubscribeasync,\r
 476  * and @ref mqtt_function_publishasync. Cannot be used with #IOT_MQTT_FLAG_WAITABLE.\r
 477  *\r
 478  * Specifies a function to be invoked with optional context when an operation\r
 479  * completes or when a server-to-client PUBLISH is received.\r
 480  *\r
 481  * @initializer{IotMqttCallbackInfo_t,IOT_MQTT_CALLBACK_INFO_INITIALIZER}\r
 482  *\r
 483  * Below is an example for receiving an asynchronous notification on operation\r
 484  * completion. See @ref mqtt_function_subscribeasync for an example of using this struct\r
 485  * with for incoming PUBLISH messages.\r
 486  *\r
 487  * @code{c}\r
 488  * // Operation completion callback.\r
 489  * void operationComplete( void * pArgument, IotMqttCallbackParam_t * pOperation );\r
 490  *\r
 491  * // Callback information.\r
 492  * IotMqttCallbackInfo_t callbackInfo = IOT_MQTT_CALLBACK_INFO_INITIALIZER;\r
 493  * callbackInfo.function = operationComplete;\r
 494  *\r
 495  * // Operation to wait for.\r
 496  * IotMqttError_t result = IotMqtt_PublishAsync( &mqttConnection,\r
 497  *                                               &publishInfo,\r
 498  *                                               0,\r
 499  *                                               &callbackInfo,\r
 500  *                                               &reference );\r
 501  *\r
 502  * // Publish should have returned IOT_MQTT_STATUS_PENDING. Once a response\r
 503  * // is received, operationComplete is executed with the actual status passed\r
 504  * // in pOperation.\r
 505  * @endcode\r
 506  */\r
 507 typedef struct IotMqttCallbackInfo\r
 508 {\r
 509     void * pCallbackContext; /**< @brief The first parameter to pass to the callback function to provide context. */\r
 510 \r
 511     /**\r
 512      * @brief User-provided callback function signature.\r
 513      *\r
 514      * @param[in] void * #IotMqttCallbackInfo_t.pCallbackContext\r
 515      * @param[in] IotMqttCallbackParam_t * Details on the outcome of the MQTT operation\r
 516      * or an incoming MQTT PUBLISH.\r
 517      *\r
 518      * @see #IotMqttCallbackParam_t for more information on the second parameter.\r
 519      */\r
 520     void ( * function )( void *,\r
 521                          IotMqttCallbackParam_t * );\r
 522 } IotMqttCallbackInfo_t;\r
 523 \r
 524 /**\r
 525  * @ingroup mqtt_datatypes_paramstructs\r
 526  * @brief MQTT subscription.\r
 527  *\r
 528  * @paramfor @ref mqtt_function_subscribeasync, @ref mqtt_function_unsubscribeasync,\r
 529  * @ref mqtt_function_subscribesync, @ref mqtt_function_unsubscribesync\r
 530  *\r
 531  * An array of these is passed to @ref mqtt_function_subscribeasync and @ref\r
 532  * mqtt_function_unsubscribeasync. However, #IotMqttSubscription_t.callback and\r
 533  * and #IotMqttSubscription_t.qos are ignored by @ref mqtt_function_unsubscribeasync.\r
 534  *\r
 535  * @initializer{IotMqttSubscription_t,IOT_MQTT_SUBSCRIPTION_INITIALIZER}\r
 536  *\r
 537  * @note The lengths of the strings in this struct should not include the NULL\r
 538  * terminator. Strings in this struct do not need to be NULL-terminated.\r
 539  * @see #IotMqttCallbackInfo_t for details on setting a callback function.\r
 540  */\r
 541 typedef struct IotMqttSubscription\r
 542 {\r
 543     /**\r
 544      * @brief QoS of messages delivered on subscription.\r
 545      *\r
 546      * Must be `0` or `1`. Ignored by @ref mqtt_function_unsubscribeasync.\r
 547      */\r
 548     IotMqttQos_t qos;\r
 549 \r
 550     const char * pTopicFilter;  /**< @brief Topic filter of subscription. */\r
 551     uint16_t topicFilterLength; /**< @brief Length of #IotMqttSubscription_t.pTopicFilter. */\r
 552 \r
 553     /**\r
 554      * @brief Callback to invoke when a message is received.\r
 555      *\r
 556      * See #IotMqttCallbackInfo_t. Ignored by @ref mqtt_function_unsubscribeasync.\r
 557      */\r
 558     IotMqttCallbackInfo_t callback;\r
 559 } IotMqttSubscription_t;\r
 560 \r
 561 /**\r
 562  * @ingroup mqtt_datatypes_paramstructs\r
 563  * @brief MQTT connection details.\r
 564  *\r
 565  * @paramfor @ref mqtt_function_connect\r
 566  *\r
 567  * Passed as an argument to @ref mqtt_function_connect. Most members of this struct\r
 568  * correspond to the content of an [MQTT CONNECT packet.]\r
 569  * (http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/csprd02/mqtt-v3.1.1-csprd02.html#_Toc385349764)\r
 570  *\r
 571  * @initializer{IotMqttConnectInfo_t,IOT_MQTT_CONNECT_INFO_INITIALIZER}\r
 572  *\r
 573  * @note The lengths of the strings in this struct should not include the NULL\r
 574  * terminator. Strings in this struct do not need to be NULL-terminated.\r
 575  */\r
 576 typedef struct IotMqttConnectInfo\r
 577 {\r
 578     /**\r
 579      * @brief Specifies if this MQTT connection is to an AWS IoT MQTT server.\r
 580      *\r
 581      * Set this member to `true` when connecting to the AWS IoT MQTT broker or\r
 582      * `false` otherwise.  Additional details about connecting to AWS IoT\r
 583      * via MQTT are available [here]\r
 584      * (https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html)\r
 585      *\r
 586      * @attention This setting <b>MUST</b> be `true` when using the AWS IoT MQTT\r
 587      * server; it <b>MUST</b> be `false` otherwise.\r
 588      * @note Currently, @ref IOT_MQTT_CONNECT_INFO_INITIALIZER sets this\r
 589      * this member to `true`.\r
 590      */\r
 591     bool awsIotMqttMode;\r
 592 \r
 593     /**\r
 594      * @brief Whether this connection is a clean session.\r
 595      *\r
 596      * MQTT servers can maintain and topic filter subscriptions and unacknowledged\r
 597      * PUBLISH messages. These form part of an <i>MQTT session</i>, which is identified by\r
 598      * the [client identifier](@ref IotMqttConnectInfo_t.pClientIdentifier).\r
 599      *\r
 600      * Setting this value to `true` establishes a <i>clean session</i>, which causes\r
 601      * the MQTT server to discard any previous session data for a client identifier.\r
 602      * When the client disconnects, the server discards all session data. If this\r
 603      * value is `true`, #IotMqttConnectInfo_t.pPreviousSubscriptions and\r
 604      * #IotMqttConnectInfo_t.previousSubscriptionCount are ignored.\r
 605      *\r
 606      * Setting this value to `false` does one of the following:\r
 607      * - If no previous session exists, the MQTT server will create a new\r
 608      * <i>persistent session</i>. The server may maintain subscriptions and\r
 609      * unacknowledged PUBLISH messages after a client disconnects, to be restored\r
 610      * once the same client identifier reconnects.\r
 611      * - If a previous session exists, the MQTT server restores all of the session's\r
 612      * subscriptions for the client identifier and may immediately transmit any\r
 613      * unacknowledged PUBLISH packets to the client.\r
 614      *\r
 615      * When a client with a persistent session disconnects, the MQTT server\r
 616      * continues to maintain all subscriptions and unacknowledged PUBLISH messages.\r
 617      * The client must also remember the session subscriptions to restore them\r
 618      * upon reconnecting. #IotMqttConnectInfo_t.pPreviousSubscriptions and\r
 619      * #IotMqttConnectInfo_t.previousSubscriptionCount are used to restore a\r
 620      * previous session's subscriptions client-side.\r
 621      */\r
 622     bool cleanSession;\r
 623 \r
 624     /**\r
 625      * @brief An array of MQTT subscriptions present in a previous session, if any.\r
 626      *\r
 627      * Pointer to the start of an array of subscriptions present a previous session,\r
 628      * if any. These subscriptions will be immediately restored upon reconnecting.\r
 629      *\r
 630      * [Optional] The field can also be used to pass a list of subscriptions to be\r
 631      * stored locally without a SUBSCRIBE packet being sent to the broker. These subscriptions\r
 632      * are useful to invoke application level callbacks for messages received on unsolicited\r
 633      * topics from the broker.\r
 634      *\r
 635      * This member is ignored if it is `NULL`. If this member is not `NULL`,\r
 636      * #IotMqttConnectInfo_t.previousSubscriptionCount must be nonzero.\r
 637      */\r
 638     const IotMqttSubscription_t * pPreviousSubscriptions;\r
 639 \r
 640     /**\r
 641      * @brief The number of MQTT subscriptions present in a previous session, if any.\r
 642      *\r
 643      * Number of subscriptions contained in the array\r
 644      * #IotMqttConnectInfo_t.pPreviousSubscriptions.\r
 645      *\r
 646      * This value is ignored if #IotMqttConnectInfo_t.pPreviousSubscriptions\r
 647      * is `NULL`. If #IotMqttConnectInfo_t.pPreviousSubscriptions is not `NULL`,\r
 648      * this value must be nonzero.\r
 649      */\r
 650     size_t previousSubscriptionCount;\r
 651 \r
 652     /**\r
 653      * @brief A message to publish if the new MQTT connection is unexpectedly closed.\r
 654      *\r
 655      * A Last Will and Testament (LWT) message may be published if this connection is\r
 656      * closed without sending an MQTT DISCONNECT packet. This pointer should be set to\r
 657      * an #IotMqttPublishInfo_t representing any LWT message to publish. If an LWT\r
 658      * is not needed, this member must be set to `NULL`.\r
 659      *\r
 660      * Unlike other PUBLISH messages, an LWT message is limited to 65535 bytes in\r
 661      * length. Additionally, [pWillInfo->retryMs](@ref IotMqttPublishInfo_t.retryMs)\r
 662      * and [pWillInfo->retryLimit](@ref IotMqttPublishInfo_t.retryLimit) will\r
 663      * be ignored.\r
 664      */\r
 665     const IotMqttPublishInfo_t * pWillInfo;\r
 666 \r
 667     uint16_t keepAliveSeconds;       /**< @brief Period of keep-alive messages. Set to 0 to disable keep-alive. */\r
 668 \r
 669     const char * pClientIdentifier;  /**< @brief MQTT client identifier. */\r
 670     uint16_t clientIdentifierLength; /**< @brief Length of #IotMqttConnectInfo_t.pClientIdentifier. */\r
 671 \r
 672     /* These credentials are not used by AWS IoT and may be ignored if\r
 673      * awsIotMqttMode is true. */\r
 674     const char * pUserName;  /**< @brief Username for MQTT connection. */\r
 675     uint16_t userNameLength; /**< @brief Length of #IotMqttConnectInfo_t.pUserName. */\r
 676     const char * pPassword;  /**< @brief Password for MQTT connection. */\r
 677     uint16_t passwordLength; /**< @brief Length of #IotMqttConnectInfo_t.pPassword. */\r
 678 } IotMqttConnectInfo_t;\r
 679 \r
 680 /**\r
 681  * @ingroup mqtt_datatypes_paramstructs\r
 682  * @brief MQTT packet details.\r
 683  *\r
 684  * @paramfor @ref mqtt_function_deserializeresponse @ref mqtt_function_deserializepublish\r
 685  *\r
 686  * Passed as an argument to public low level mqtt deserialize functions.\r
 687  *\r
 688  * @initializer{IotMqttPacketInfo_t,IOT_MQTT_PACKET_INFO_INITIALIZER}\r
 689  *\r
 690  * @note This structure should be only used while accessing low level MQTT deserialization API.\r
 691  * The low level serialization/ deserialization API should be only used for implementing\r
 692  * light weight single threaded mqtt client.\r
 693  */\r
 694 typedef struct IotMqttPacketInfo\r
 695 {\r
 696     uint8_t * pRemainingData;     /**< @brief (Input) The remaining data in MQTT packet. */\r
 697     size_t remainingLength;       /**< @brief (Input) Length of the remaining data in the MQTT packet. */\r
 698     uint16_t packetIdentifier;    /**< @brief (Output) MQTT packet identifier. */\r
 699     uint8_t type;                 /**< @brief (Input) A value identifying the packet type. */\r
 700     IotMqttPublishInfo_t pubInfo; /**< @brief (Output) Publish info in case of deserializing PUBLISH. */\r
 701 } IotMqttPacketInfo_t;\r
 702 \r
 703 /**\r
 704  * @cond DOXYGEN_IGNORE\r
 705  * Doxygen should ignore this section.\r
 706  *\r
 707  * Forward declaration of the internal MQTT packet structure.\r
 708  */\r
 709 struct _mqttPacket;\r
 710 /** @endcond */\r
 711 \r
 712 /**\r
 713  * @brief Get the MQTT packet type from a stream of bytes off the network.\r
 714  *\r
 715  * @param[in] pNetworkConnection Reference to the network connection.\r
 716  * @param[in] pNetworkInterface Function pointers used to interact with the\r
 717  * network.\r
 718  */\r
 719 typedef uint8_t ( * IotMqttGetPacketType_t )( void * pNetworkConnection,\r
 720                                               const IotNetworkInterface_t * pNetworkInterface );\r
 721 \r
 722 /**\r
 723  * @brief Get the remaining length from a stream of bytes off the network.\r
 724  *\r
 725  * @param[in] pNetworkConnection Reference to the network connection.\r
 726  * @param[in] pNetworkInterface Function pointers used to interact with the\r
 727  * network.\r
 728  */\r
 729 typedef size_t ( * IotMqttGetRemainingLength_t )( void * pNetworkConnection,\r
 730                                                   const IotNetworkInterface_t * pNetworkInterface );\r
 731 \r
 732 /**\r
 733  * @brief Free a packet generated by the serializer.\r
 734  *\r
 735  * This function pointer must be set if any other serializer override is set.\r
 736  * @param[in] uint8_t* The packet to free.\r
 737  */\r
 738 typedef void ( * IotMqttFreePacket_t )( uint8_t * pPacket );\r
 739 \r
 740 /**\r
 741  * @brief CONNECT packet serializer function.\r
 742  * @param[in] IotMqttConnectInfo_t* User-provided CONNECT information.\r
 743  * @param[out] uint8_t** Where the CONNECT packet is written.\r
 744  * @param[out] size_t* Size of the CONNECT packet.\r
 745  */\r
 746 typedef IotMqttError_t ( * IotMqttSerializeConnect_t )( const IotMqttConnectInfo_t * pConnectInfo,\r
 747                                                         uint8_t ** pConnectPacket,\r
 748                                                         size_t * pPacketSize );\r
 749 \r
 750 /**\r
 751  * @brief PINGREQ packet serializer function.\r
 752  * @param[out] uint8_t** Where the PINGREQ packet is written.\r
 753  * @param[out] size_t* Size of the PINGREQ packet.\r
 754  */\r
 755 typedef IotMqttError_t ( * IotMqttSerializePingreq_t )( uint8_t ** pDisconnectPacket,\r
 756                                                         size_t * pPacketSize );\r
 757 \r
 758 /**\r
 759  * @brief PUBLISH packet serializer function.\r
 760  * @param[in] IotMqttPublishInfo_t* User-provided PUBLISH information.\r
 761  * @param[out] uint8_t** Where the PUBLISH packet is written.\r
 762  * @param[out] size_t* Size of the PUBLISH packet.\r
 763  * @param[out] uint16_t* The packet identifier generated for this PUBLISH.\r
 764  * @param[out] uint8_t** Where the high byte of the packet identifier\r
 765  * is written.\r
 766  */\r
 767 typedef IotMqttError_t ( * IotMqtt_SerializePublish_t )( const IotMqttPublishInfo_t * pPublishInfo,\r
 768                                                          uint8_t ** pPublishPacket,\r
 769                                                          size_t * pPacketSize,\r
 770                                                          uint16_t * pPacketIdentifier,\r
 771                                                          uint8_t ** pPacketIdentifierHigh );\r
 772 \r
 773 /**\r
 774  * @brief SUBSCRIBE/UNSUBSCRIBE packet serializer function.\r
 775  * @param[in] IotMqttSubscription_t* User-provided array of subscriptions.\r
 776  * @param[in] size_t Number of elements in the subscription array.\r
 777  * @param[out] uint8_t** Where the SUBSCRIBE packet is written.\r
 778  * @param[out] size_t* Size of the SUBSCRIBE packet.\r
 779  * @param[out] uint16_t* The packet identifier generated for this SUBSCRIBE.\r
 780  */\r
 781 typedef IotMqttError_t ( * IotMqttSerializeSubscribe_t )( const IotMqttSubscription_t * pSubscriptionList,\r
 782                                                           size_t subscriptionCount,\r
 783                                                           uint8_t ** pSubscribePacket,\r
 784                                                           size_t * pPacketSize,\r
 785                                                           uint16_t * pPacketIdentifier );\r
 786 \r
 787 /**\r
 788  * @brief DISCONNECT packet serializer function.\r
 789  * @param[out] uint8_t** Where the DISCONNECT packet is written.\r
 790  * @param[out] size_t* Size of the DISCONNECT packet.\r
 791  */\r
 792 typedef IotMqttError_t ( * IotMqttSerializeDisconnect_t )( uint8_t ** ppDisconnectPacket,\r
 793                                                            size_t * pPacketSize );\r
 794 \r
 795 /**\r
 796  * @brief MQTT packet deserializer function.\r
 797  * @param[in,out] _mqttPacket* Pointer to an MQTT packet structure\r
 798  */\r
 799 typedef IotMqttError_t ( * IotMqttDeserialize_t )( struct _mqttPacket * pMqttPacket );\r
 800 \r
 801 /**\r
 802  * @brief PUBACK packet serializer function.\r
 803  * @param[in] uint16_t The packet identifier to place in PUBACK.\r
 804  * @param[out] uint8_t** Where the PUBACK packet is written.\r
 805  * @param[out] size_t* Size of the PUBACK packet.\r
 806  */\r
 807 typedef IotMqttError_t ( * IotMqttSerializePuback_t )( uint16_t packetIdentifier,\r
 808                                                        uint8_t ** pPubackPacket,\r
 809                                                        size_t * pPacketSize );\r
 810 \r
 811 /**\r
 812  * @brief Set the `DUP` bit in a QoS `1` PUBLISH packet.\r
 813  * @param[in] uint8_t* Pointer to the PUBLISH packet to modify.\r
 814  * @param[in] uint8_t* The high byte of any packet identifier to modify.\r
 815  * @param[out] uint16_t* New packet identifier (AWS IoT MQTT mode only).\r
 816  */\r
 817 typedef void ( * IotMqttPublishSetDup_t )( uint8_t * pPublishPacket,\r
 818                                            uint8_t * pPacketIdentifierHigh,\r
 819                                            uint16_t * pNewPacketIdentifier );\r
 820 \r
 821 /**\r
 822  * @brief Function pointer to read the next available byte on a network connection.\r
 823  * @param[in] pNetworkContext reference to network connection like socket.\r
 824  * @param[out] pNextByte Pointer to the byte read from the network.\r
 825  */\r
 826 typedef IotMqttError_t (* IotMqttGetNextByte_t)( void * pNetworkContext,\r
 827                                                  uint8_t * pNextByte );\r
 828 \r
 829 #if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1\r
 830 \r
 831 /**\r
 832  * @ingroup mqtt_datatypes_paramstructs\r
 833  * @brief Function pointers for MQTT packet serializer overrides.\r
 834  *\r
 835  * These function pointers allow the MQTT serialization and deserialization functions\r
 836  * to be overridden for an MQTT connection. The compile-time setting\r
 837  * @ref IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES must be `1` to enable this functionality.\r
 838  * See the #IotMqttSerializer_t::serialize and #IotMqttSerializer_t::deserialize\r
 839  * members for a list of functions that can be overridden. In addition, the functions\r
 840  * for freeing packets and determining the packet type can also be overridden. If\r
 841  * @ref IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES is `1`, the serializer initialization and\r
 842  * cleanup functions may be extended. See documentation of\r
 843  * @ref IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES for more information.\r
 844  *\r
 845  * If any function pointers that are `NULL`, then the default implementation of that\r
 846  * function will be used.\r
 847  */\r
 848     typedef struct IotMqttSerializer\r
 849     {\r
 850         /**\r
 851          * @brief Get the MQTT packet type from a stream of bytes off the network.\r
 852          * <b>Default implementation:</b> #_IotMqtt_GetPacketType\r
 853          */\r
 854         IotMqttGetPacketType_t getPacketType;\r
 855 \r
 856         /**\r
 857          * @brief Get the remaining length from a stream of bytes off the network.\r
 858          * <b>Default implementation:</b> #_IotMqtt_GetRemainingLength\r
 859          */\r
 860         IotMqttGetRemainingLength_t getRemainingLength;\r
 861 \r
 862         /**\r
 863          * @brief Free a packet generated by the serializer.\r
 864          *\r
 865          * <b>Default implementation:</b> #_IotMqtt_FreePacket\r
 866          */\r
 867         IotMqttFreePacket_t freePacket;\r
 868 \r
 869         struct\r
 870         {\r
 871             /**\r
 872              * @brief CONNECT packet serializer function.\r
 873              *\r
 874              * <b>Default implementation:</b> #_IotMqtt_SerializeConnect\r
 875              */\r
 876             IotMqttSerializeConnect_t connect;\r
 877 \r
 878             /**\r
 879              * @brief PUBLISH packet serializer function.\r
 880              *\r
 881              * <b>Default implementation:</b> #_IotMqtt_SerializePublish\r
 882              */\r
 883             IotMqtt_SerializePublish_t publish;\r
 884 \r
 885             /**\r
 886              * @brief Set the `DUP` bit in a QoS `1` PUBLISH packet.\r
 887              *\r
 888              * <b>Default implementation:</b> #_IotMqtt_PublishSetDup\r
 889              */\r
 890             IotMqttPublishSetDup_t publishSetDup;\r
 891 \r
 892             /**\r
 893              * @brief PUBACK packet serializer function.\r
 894              *\r
 895              * <b>Default implementation:</b> #_IotMqtt_SerializePuback\r
 896              */\r
 897             IotMqttSerializePuback_t puback;\r
 898 \r
 899             /**\r
 900              * @brief SUBSCRIBE packet serializer function.\r
 901              *\r
 902              * <b>Default implementation:</b> #_IotMqtt_SerializeSubscribe\r
 903              */\r
 904             IotMqttSerializeSubscribe_t subscribe;\r
 905 \r
 906             /**\r
 907              * @brief UNSUBSCRIBE packet serializer function.\r
 908              *\r
 909              * <b>Default implementation:</b> #_IotMqtt_SerializeUnsubscribe\r
 910              */\r
 911             IotMqttSerializeSubscribe_t unsubscribe;\r
 912 \r
 913             /**\r
 914              * @brief PINGREQ packet serializer function.\r
 915              *\r
 916              * <b>Default implementation:</b> #_IotMqtt_SerializePingreq\r
 917              */\r
 918             IotMqttSerializePingreq_t pingreq;\r
 919 \r
 920             /**\r
 921              * @brief DISCONNECT packet serializer function.\r
 922              *\r
 923              * <b>Default implementation:</b> #_IotMqtt_SerializeDisconnect\r
 924              */\r
 925             IotMqttSerializeDisconnect_t disconnect;\r
 926         } serialize; /**< @brief Overrides the packet serialization functions for a single connection. */\r
 927 \r
 928         struct\r
 929         {\r
 930             /**\r
 931              * @brief CONNACK packet deserializer function.\r
 932              *\r
 933              * <b>Default implementation:</b> #_IotMqtt_DeserializeConnack\r
 934              */\r
 935             IotMqttDeserialize_t connack;\r
 936 \r
 937             /**\r
 938              * @brief PUBLISH packet deserializer function.\r
 939              *\r
 940              * <b>Default implementation:</b> #_IotMqtt_DeserializePublish\r
 941              */\r
 942             IotMqttDeserialize_t publish;\r
 943 \r
 944             /**\r
 945              * @brief PUBACK packet deserializer function.\r
 946              *\r
 947              * <b>Default implementation:</b> #_IotMqtt_DeserializePuback\r
 948              */\r
 949             IotMqttDeserialize_t puback;\r
 950 \r
 951             /**\r
 952              * @brief SUBACK packet deserializer function.\r
 953              *\r
 954              * <b>Default implementation:</b> #_IotMqtt_DeserializeSuback\r
 955              */\r
 956             IotMqttDeserialize_t suback;\r
 957 \r
 958             /**\r
 959              * @brief UNSUBACK packet deserializer function.\r
 960              *\r
 961              * <b>Default implementation:</b> #_IotMqtt_DeserializeUnsuback\r
 962              */\r
 963             IotMqttDeserialize_t unsuback;\r
 964 \r
 965             /**\r
 966              * @brief PINGRESP packet deserializer function.\r
 967              *\r
 968              * <b>Default implementation:</b> #_IotMqtt_DeserializePingresp\r
 969              */\r
 970             IotMqttDeserialize_t pingresp;\r
 971         } deserialize; /**< @brief Overrides the packet deserialization functions for a single connection. */\r
 972     } IotMqttSerializer_t;\r
 973 \r
 974 #else /* if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1 */\r
 975 \r
 976 /* When MQTT packet serializer overrides are disabled, this struct is an\r
 977  * incomplete type. */\r
 978     typedef struct IotMqttSerializer IotMqttSerializer_t;\r
 979 \r
 980 #endif /* if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1 */\r
 981 \r
 982 /**\r
 983  * @ingroup mqtt_datatypes_paramstructs\r
 984  * @brief MQTT network connection details.\r
 985  *\r
 986  * @paramfor @ref mqtt_function_connect\r
 987  *\r
 988  * The MQTT library needs to be able to send and receive data over a network.\r
 989  * This struct provides an interface for interacting with the network.\r
 990  *\r
 991  * @initializer{IotMqttNetworkInfo_t,IOT_MQTT_NETWORK_INFO_INITIALIZER}\r
 992  */\r
 993 typedef struct IotMqttNetworkInfo\r
 994 {\r
 995     /**\r
 996      * @brief Whether a new network connection should be created.\r
 997      *\r
 998      * When this value is `true`, a new transport-layer network connection will\r
 999      * be created along with the MQTT connection. #IotMqttNetworkInfo_t::pNetworkServerInfo\r
1000      * and #IotMqttNetworkInfo_t::pNetworkCredentialInfo are valid when this value\r
1001      * is `true`.\r
1002      *\r
1003      * When this value is `false`, the MQTT connection will use a transport-layer\r
1004      * network connection that has already been established. The MQTT library will\r
1005      * still set the appropriate receive callback even if the network connection\r
1006      * has been established.\r
1007      * #IotMqttNetworkInfo_t::pNetworkConnection, which represents an established\r
1008      * network connection, is valid when this value is `false`.\r
1009      */\r
1010     bool createNetworkConnection;\r
1011 \r
1012     union\r
1013     {\r
1014         struct\r
1015         {\r
1016             /**\r
1017              * @brief Information on the MQTT server, passed as `pServerInfo` to\r
1018              * #IotNetworkInterface_t::create.\r
1019              *\r
1020              * This member is opaque to the MQTT library. It is passed to the network\r
1021              * interface when creating a new network connection. It is only valid when\r
1022              * #IotMqttNetworkInfo_t::createNetworkConnection is `true`.\r
1023              */\r
1024             IotNetworkServerInfo_t pNetworkServerInfo;\r
1025 \r
1026             /**\r
1027              * @brief Credentials for the MQTT server, passed as `pCredentialInfo` to\r
1028              * #IotNetworkInterface_t::create.\r
1029              *\r
1030              * This member is opaque to the MQTT library. It is passed to the network\r
1031              * interface when creating a new network connection. It is only valid when\r
1032              * #IotMqttNetworkInfo_t::createNetworkConnection is `true`.\r
1033              */\r
1034             IotNetworkCredentials_t pNetworkCredentialInfo;\r
1035         } setup;\r
1036 \r
1037         /**\r
1038          * @brief An established transport-layer network connection.\r
1039          *\r
1040          * This member is opaque to the MQTT library. It is passed to the network\r
1041          * interface to reference an established network connection. It is only\r
1042          * valid when #IotMqttNetworkInfo_t::createNetworkConnection is `false`.\r
1043          */\r
1044         IotNetworkConnection_t pNetworkConnection;\r
1045     } u /**< @brief Valid member depends of IotMqttNetworkInfo_t.createNetworkConnection. */;\r
1046 \r
1047     /**\r
1048      * @brief The network functions used by the new MQTT connection.\r
1049      *\r
1050      * @attention The function pointers of the network interface must remain valid\r
1051      * for the lifetime of the MQTT connection.\r
1052      */\r
1053     const IotNetworkInterface_t * pNetworkInterface;\r
1054 \r
1055     /**\r
1056      * @brief A callback function to invoke when this MQTT connection is disconnected.\r
1057      */\r
1058     IotMqttCallbackInfo_t disconnectCallback;\r
1059 \r
1060     #if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1\r
1061 \r
1062         /**\r
1063          * @brief MQTT packet serializer overrides used by the new MQTT connection.\r
1064          *\r
1065          * @attention The function pointers of the MQTT serializer overrides must\r
1066          * remain valid for the lifetime of the MQTT connection.\r
1067          */\r
1068         const IotMqttSerializer_t * pMqttSerializer;\r
1069     #endif\r
1070 } IotMqttNetworkInfo_t;\r
1071 \r
1072 /*------------------------- MQTT defined constants --------------------------*/\r
1073 \r
1074 /**\r
1075  * @constantspage{mqtt,MQTT library}\r
1076  *\r
1077  * @section mqtt_constants_initializers MQTT Initializers\r
1078  * @brief Provides default values for the data types of the MQTT library.\r
1079  *\r
1080  * @snippet this define_mqtt_initializers\r
1081  *\r
1082  * All user-facing data types of the MQTT library should be initialized using\r
1083  * one of the following.\r
1084  *\r
1085  * @warning Failing to initialize an MQTT data type with the appropriate initializer\r
1086  * may result in undefined behavior!\r
1087  * @note The initializers may change at any time in future versions, but their\r
1088  * names will remain the same.\r
1089  *\r
1090  * <b>Example</b>\r
1091  * @code{c}\r
1092  * IotMqttNetworkInfo_t networkInfo = IOT_MQTT_NETWORK_INFO_INITIALIZER;\r
1093  * IotMqttSerializer_t serializer = IOT_MQTT_SERIALIZER_INITIALIZER;\r
1094  * IotMqttConnectInfo_t connectInfo = IOT_MQTT_CONNECT_INFO_INITIALIZER;\r
1095  * IotMqttPublishInfo_t publishInfo = IOT_MQTT_PUBLISH_INFO_INITIALIZER;\r
1096  * IotMqttSubscription_t subscription = IOT_MQTT_SUBSCRIPTION_INITIALIZER;\r
1097  * IotMqttCallbackInfo_t callbackInfo = IOT_MQTT_CALLBACK_INFO_INITIALIZER;\r
1098  * IotMqttConnection_t connection = IOT_MQTT_CONNECTION_INITIALIZER;\r
1099  * IotMqttOperation_t operation = IOT_MQTT_OPERATION_INITIALIZER;\r
1100  * @endcode\r
1101  *\r
1102  * @section mqtt_constants_flags MQTT Function Flags\r
1103  * @brief Flags that modify the behavior of MQTT library functions.\r
1104  * - #IOT_MQTT_FLAG_WAITABLE <br>\r
1105  *   @copybrief IOT_MQTT_FLAG_WAITABLE\r
1106  * - #IOT_MQTT_FLAG_CLEANUP_ONLY <br>\r
1107  *   @copybrief IOT_MQTT_FLAG_CLEANUP_ONLY\r
1108  *\r
1109  * Flags should be bitwise-ORed with each other to change the behavior of\r
1110  * @ref mqtt_function_subscribeasync, @ref mqtt_function_unsubscribeasync,\r
1111  * @ref mqtt_function_publishasync, their blocking versions; or @ref mqtt_function_disconnect.\r
1112  *\r
1113  * @note The values of the flags may change at any time in future versions, but\r
1114  * their names will remain the same. Additionally, flags that may be used together\r
1115  * will be bitwise-exclusive of each other.\r
1116  */\r
1117 \r
1118 /* @[define_mqtt_initializers] */\r
1119 /** @brief Initializer for #IotMqttNetworkInfo_t. */\r
1120 #define IOT_MQTT_NETWORK_INFO_INITIALIZER     { .createNetworkConnection = true }\r
1121 /** @brief Initializer for #IotMqttSerializer_t. */\r
1122 #define IOT_MQTT_SERIALIZER_INITIALIZER       { 0 }\r
1123 /** @brief Initializer for #IotMqttConnectInfo_t. */\r
1124 #define IOT_MQTT_CONNECT_INFO_INITIALIZER     { .cleanSession = true }\r
1125 /** @brief Initializer for #IotMqttPublishInfo_t. */\r
1126 #define IOT_MQTT_PUBLISH_INFO_INITIALIZER     { .qos = IOT_MQTT_QOS_0 }\r
1127 /** @brief Initializer for #IotMqttSubscription_t. */\r
1128 #define IOT_MQTT_SUBSCRIPTION_INITIALIZER     { .qos = IOT_MQTT_QOS_0 }\r
1129 /** @brief Initializer for #IotMqttCallbackInfo_t. */\r
1130 #define IOT_MQTT_CALLBACK_INFO_INITIALIZER    { 0 }\r
1131 /** @brief Initializer for #IotMqttConnection_t. */\r
1132 #define IOT_MQTT_CONNECTION_INITIALIZER       NULL\r
1133 /** @brief Initializer for #IotMqttOperation_t. */\r
1134 #define IOT_MQTT_OPERATION_INITIALIZER        NULL\r
1135 /** @brief Initializer for #IotMqttPacketInfo_t. */\r
1136 #define IOT_MQTT_PACKET_INFO_INITIALIZER      { .pRemainingData = NULL, remainingLength = 0, packetIdentifier = 0, .type = 0 }\r
1137 /* @[define_mqtt_initializers] */\r
1138 \r
1139 /**\r
1140  * @brief Allows the use of @ref mqtt_function_wait for blocking until completion.\r
1141  *\r
1142  * This flag is always valid for @ref mqtt_function_subscribeasync and\r
1143  * @ref mqtt_function_unsubscribeasync. If passed to @ref mqtt_function_publishasync,\r
1144  * the parameter [pPublishInfo->qos](@ref IotMqttPublishInfo_t.qos) must not be `0`.\r
1145  *\r
1146  * An #IotMqttOperation_t <b>MUST</b> be provided if this flag is set. Additionally, an\r
1147  * #IotMqttCallbackInfo_t <b>MUST NOT</b> be provided.\r
1148  *\r
1149  * @note If this flag is set, @ref mqtt_function_wait <b>MUST</b> be called to clean up\r
1150  * resources.\r
1151  */\r
1152 #define IOT_MQTT_FLAG_WAITABLE        ( 0x00000001 )\r
1153 \r
1154 /**\r
1155  * @brief Causes @ref mqtt_function_disconnect to only free memory and not send\r
1156  * an MQTT DISCONNECT packet.\r
1157  *\r
1158  * This flag is only valid for @ref mqtt_function_disconnect. It should be passed\r
1159  * to @ref mqtt_function_disconnect if the network goes offline or is otherwise\r
1160  * unusable.\r
1161  */\r
1162 #define IOT_MQTT_FLAG_CLEANUP_ONLY    ( 0x00000001 )\r
1163 \r
1164 #endif /* ifndef IOT_MQTT_TYPES_H_ */\r