Correct an err in queue.c introduced when previously updating behaviour when queue...

[freertos] / FreeRTOS-Plus / Source / FreeRTOS-IoT-Libraries / c_sdk / standard / mqtt / include / types / iot_mqtt_types.h

/*\r
 * Amazon FreeRTOS MQTT V2.0.0\r
 * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
 *\r
 * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
 * this software and associated documentation files (the "Software"), to deal in\r
 * the Software without restriction, including without limitation the rights to\r
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
 * the Software, and to permit persons to whom the Software is furnished to do so,\r
 * subject to the following conditions:\r
 *\r
 * The above copyright notice and this permission notice shall be included in all\r
 * copies or substantial portions of the Software.\r
 *\r
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
 *\r
 * http://aws.amazon.com/freertos\r
 * http://www.FreeRTOS.org\r
 */\r
\r
/**\r
 * @file iot_mqtt_types.h\r
 * @brief Types of the MQTT library.\r
 */\r
\r
#ifndef IOT_MQTT_TYPES_H_\r
#define IOT_MQTT_TYPES_H_\r
\r
/* The config header is always included first. */\r
#include "iot_config.h"\r
\r
/* Standard includes. */\r
#include <stdbool.h>\r
#include <stdint.h>\r
#include <stddef.h>\r
\r
/* Type includes. */\r
#include "types/iot_platform_types.h"\r
#include "types/iot_taskpool_types.h"\r
\r
/* Platform network include. */\r
#include "platform/iot_network.h"\r
\r
/*---------------------------- MQTT handle types ----------------------------*/\r
\r
/**\r
 * @handles{mqtt,MQTT library}\r
 */\r
\r
/**\r
 * @ingroup mqtt_datatypes_handles\r
 * @brief Opaque handle of an MQTT connection.\r
 *\r
 * This type identifies an MQTT connection, which is valid after a successful call\r
 * to @ref mqtt_function_connect. A variable of this type is passed as the first\r
 * argument to [MQTT library functions](@ref mqtt_functions) to identify which\r
 * connection that function acts on.\r
 *\r
 * A call to @ref mqtt_function_disconnect makes a connection handle invalid. Once\r
 * @ref mqtt_function_disconnect returns, the connection handle should no longer\r
 * be used.\r
 *\r
 * @initializer{IotMqttConnection_t,IOT_MQTT_CONNECTION_INITIALIZER}\r
 */\r
typedef struct _mqttConnection   * IotMqttConnection_t;\r
\r
/**\r
 * @ingroup mqtt_datatypes_handles\r
 * @brief Opaque handle that references an in-progress MQTT operation.\r
 *\r
 * Set as an output parameter of @ref mqtt_function_publish, @ref mqtt_function_subscribe,\r
 * and @ref mqtt_function_unsubscribe. These functions queue an MQTT operation; the result\r
 * of the operation is unknown until a response from the MQTT server is received. Therefore,\r
 * this handle serves as a reference to MQTT operations awaiting MQTT server response.\r
 *\r
 * This reference will be valid from the successful return of @ref mqtt_function_publish,\r
 * @ref mqtt_function_subscribe, or @ref mqtt_function_unsubscribe. The reference becomes\r
 * invalid once the [completion callback](@ref IotMqttCallbackInfo_t) is invoked, or\r
 * @ref mqtt_function_wait returns.\r
 *\r
 * @initializer{IotMqttOperation_t,IOT_MQTT_OPERATION_INITIALIZER}\r
 *\r
 * @see @ref mqtt_function_wait and #IOT_MQTT_FLAG_WAITABLE for waiting on a reference.\r
 * #IotMqttCallbackInfo_t and #IotMqttCallbackParam_t for an asynchronous notification\r
 * of completion.\r
 */\r
typedef struct _mqttOperation    * IotMqttOperation_t;\r
\r
/*-------------------------- MQTT enumerated types --------------------------*/\r
\r
/**\r
 * @enums{mqtt,MQTT library}\r
 */\r
\r
/**\r
 * @ingroup mqtt_datatypes_enums\r
 * @brief Return codes of [MQTT functions](@ref mqtt_functions).\r
 *\r
 * The function @ref mqtt_function_strerror can be used to get a return code's\r
 * description.\r
 */\r
typedef enum IotMqttError\r
{\r
    /**\r
     * @brief MQTT operation completed successfully.\r
     *\r
     * Functions that may return this value:\r
     * - @ref mqtt_function_connect\r
     * - @ref mqtt_function_publish with QoS 0 parameter\r
     * - @ref mqtt_function_wait\r
     * - @ref mqtt_function_timedsubscribe\r
     * - @ref mqtt_function_timedunsubscribe\r
     * - @ref mqtt_function_timedpublish\r
     *\r
     * Will also be the value of an operation completion callback's\r
     * #IotMqttCallbackParam_t.result when successful.\r
     */\r
    IOT_MQTT_SUCCESS = 0,\r
\r
    /**\r
     * @brief MQTT operation queued, awaiting result.\r
     *\r
     * Functions that may return this value:\r
     * - @ref mqtt_function_subscribe\r
     * - @ref mqtt_function_unsubscribe\r
     * - @ref mqtt_function_publish with QoS 1 parameter\r
     */\r
    IOT_MQTT_STATUS_PENDING,\r
\r
    /**\r
     * @brief Initialization failed.\r
     *\r
     * Functions that may return this value:\r
     * - @ref mqtt_function_init\r
     */\r
    IOT_MQTT_INIT_FAILED,\r
\r
    /**\r
     * @brief At least one parameter is invalid.\r
     *\r
     * Functions that may return this value:\r
     * - @ref mqtt_function_connect\r
     * - @ref mqtt_function_subscribe and @ref mqtt_function_timedsubscribe\r
     * - @ref mqtt_function_unsubscribe and @ref mqtt_function_timedunsubscribe\r
     * - @ref mqtt_function_publish and @ref mqtt_function_timedpublish\r
     * - @ref mqtt_function_wait\r
     */\r
    IOT_MQTT_BAD_PARAMETER,\r
\r
    /**\r
     * @brief MQTT operation failed because of memory allocation failure.\r
     *\r
     * Functions that may return this value:\r
     * - @ref mqtt_function_connect\r
     * - @ref mqtt_function_subscribe and @ref mqtt_function_timedsubscribe\r
     * - @ref mqtt_function_unsubscribe and @ref mqtt_function_timedunsubscribe\r
     * - @ref mqtt_function_publish and @ref mqtt_function_timedpublish\r
     */\r
    IOT_MQTT_NO_MEMORY,\r
\r
    /**\r
     * @brief MQTT operation failed because the network was unusable.\r
     *\r
     * This return value may indicate that the network is disconnected.\r
     *\r
     * Functions that may return this value:\r
     * - @ref mqtt_function_connect\r
     * - @ref mqtt_function_wait\r
     * - @ref mqtt_function_timedsubscribe\r
     * - @ref mqtt_function_timedunsubscribe\r
     * - @ref mqtt_function_timedpublish\r
     *\r
     * May also be the value of an operation completion callback's\r
     * #IotMqttCallbackParam_t.result.\r
     */\r
    IOT_MQTT_NETWORK_ERROR,\r
\r
    /**\r
     * @brief MQTT operation could not be scheduled, i.e. enqueued for sending.\r
     *\r
     * Functions that may return this value:\r
     * - @ref mqtt_function_connect\r
     * - @ref mqtt_function_subscribe and @ref mqtt_function_timedsubscribe\r
     * - @ref mqtt_function_unsubscribe and @ref mqtt_function_timedunsubscribe\r
     * - @ref mqtt_function_publish and @ref mqtt_function_timedpublish\r
     */\r
    IOT_MQTT_SCHEDULING_ERROR,\r
\r
    /**\r
     * @brief MQTT response packet received from the network is malformed.\r
     *\r
     * Functions that may return this value:\r
     * - @ref mqtt_function_connect\r
     * - @ref mqtt_function_wait\r
     * - @ref mqtt_function_timedsubscribe\r
     * - @ref mqtt_function_timedunsubscribe\r
     * - @ref mqtt_function_timedpublish\r
     *\r
     * May also be the value of an operation completion callback's\r
     * #IotMqttCallbackParam_t.result.\r
     *\r
     * @note If this value is received, the network connection has been closed.\r
     */\r
    IOT_MQTT_BAD_RESPONSE,\r
\r
    /**\r
     * @brief A blocking MQTT operation timed out.\r
     *\r
     * Functions that may return this value:\r
     * - @ref mqtt_function_connect\r
     * - @ref mqtt_function_wait\r
     * - @ref mqtt_function_timedsubscribe\r
     * - @ref mqtt_function_timedunsubscribe\r
     * - @ref mqtt_function_timedpublish\r
     */\r
    IOT_MQTT_TIMEOUT,\r
\r
    /**\r
     * @brief A CONNECT or at least one subscription was refused by the server.\r
     *\r
     * Functions that may return this value:\r
     * - @ref mqtt_function_connect\r
     * - @ref mqtt_function_wait, but only when its #IotMqttOperation_t parameter\r
     * is associated with a SUBSCRIBE operation.\r
     * - @ref mqtt_function_timedsubscribe\r
     *\r
     * May also be the value of an operation completion callback's\r
     * #IotMqttCallbackParam_t.result for a SUBSCRIBE.\r
     *\r
     * @note If this value is returned and multiple subscriptions were passed to\r
     * @ref mqtt_function_subscribe (or @ref mqtt_function_timedsubscribe), it's\r
     * still possible that some of the subscriptions succeeded. This value only\r
     * signifies that AT LEAST ONE subscription was rejected. The function @ref\r
     * mqtt_function_issubscribed can be used to determine which subscriptions\r
     * were accepted or rejected.\r
     */\r
    IOT_MQTT_SERVER_REFUSED,\r
\r
    /**\r
     * @brief A QoS 1 PUBLISH received no response and [the retry limit]\r
     * (#IotMqttPublishInfo_t.retryLimit) was reached.\r
     *\r
     * Functions that may return this value:\r
     * - @ref mqtt_function_wait, but only when its #IotMqttOperation_t parameter\r
     * is associated with a QoS 1 PUBLISH operation\r
     * - @ref mqtt_function_timedpublish\r
     *\r
     * May also be the value of an operation completion callback's\r
     * #IotMqttCallbackParam_t.result for a QoS 1 PUBLISH.\r
     */\r
    IOT_MQTT_RETRY_NO_RESPONSE\r
} IotMqttError_t;\r
\r
/**\r
 * @ingroup mqtt_datatypes_enums\r
 * @brief Types of MQTT operations.\r
 *\r
 * The function @ref mqtt_function_operationtype can be used to get an operation\r
 * type's description.\r
 */\r
typedef enum IotMqttOperationType\r
{\r
    IOT_MQTT_CONNECT,           /**< Client-to-server CONNECT. */\r
    IOT_MQTT_PUBLISH_TO_SERVER, /**< Client-to-server PUBLISH. */\r
    IOT_MQTT_PUBACK,            /**< Client-to-server PUBACK. */\r
    IOT_MQTT_SUBSCRIBE,         /**< Client-to-server SUBSCRIBE. */\r
    IOT_MQTT_UNSUBSCRIBE,       /**< Client-to-server UNSUBSCRIBE. */\r
    IOT_MQTT_PINGREQ,           /**< Client-to-server PINGREQ. */\r
    IOT_MQTT_DISCONNECT         /**< Client-to-server DISCONNECT. */\r
} IotMqttOperationType_t;\r
\r
/**\r
 * @ingroup mqtt_datatypes_enums\r
 * @brief Quality of service levels for MQTT PUBLISH messages.\r
 *\r
 * All MQTT PUBLISH messages, including Last Will and Testament and messages\r
 * received on subscription filters, have an associated <i>Quality of Service</i>,\r
 * which defines any delivery guarantees for that message.\r
 * - QoS 0 messages will be delivered at most once. This is a "best effort"\r
 * transmission with no retransmissions.\r
 * - QoS 1 messages will be delivered at least once. See #IotMqttPublishInfo_t\r
 * for the retransmission strategy this library uses to redeliver messages\r
 * assumed to be lost.\r
 *\r
 * @attention QoS 2 is not supported by this library and should not be used.\r
 */\r
typedef enum IotMqttQos\r
{\r
    IOT_MQTT_QOS_0 = 0, /**< Delivery at most once. */\r
    IOT_MQTT_QOS_1 = 1, /**< Delivery at least once. See #IotMqttPublishInfo_t for client-side retry strategy. */\r
    IOT_MQTT_QOS_2 = 2  /**< Delivery exactly once. Unsupported, but enumerated for completeness. */\r
} IotMqttQos_t;\r
\r
/**\r
 * @ingroup mqtt_datatypes_enums\r
 * @brief The reason that an MQTT connection (and its associated network connection)\r
 * was disconnected.\r
 *\r
 * When an MQTT connection is closed, its associated [disconnect callback]\r
 * (@ref IotMqttNetworkInfo_t::disconnectCallback) will be invoked. This type\r
 * is passed inside of an #IotMqttCallbackParam_t to provide a reason for the\r
 * disconnect.\r
 */\r
typedef enum IotMqttDisconnectReason\r
{\r
    IOT_MQTT_DISCONNECT_CALLED,   /**< @ref mqtt_function_disconnect was invoked. */\r
    IOT_MQTT_BAD_PACKET_RECEIVED, /**< An invalid packet was received from the network. */\r
    IOT_MQTT_KEEP_ALIVE_TIMEOUT   /**< Keep-alive response was not received within @ref IOT_MQTT_RESPONSE_WAIT_MS. */\r
} IotMqttDisconnectReason_t;\r
\r
/*------------------------- MQTT parameter structs --------------------------*/\r
\r
/**\r
 * @paramstructs{mqtt,MQTT}\r
 */\r
\r
/**\r
 * @ingroup mqtt_datatypes_paramstructs\r
 * @brief Information on a PUBLISH message.\r
 *\r
 * @paramfor @ref mqtt_function_connect, @ref mqtt_function_publish\r
 *\r
 * Passed to @ref mqtt_function_publish as the message to publish and @ref\r
 * mqtt_function_connect as the Last Will and Testament (LWT) message.\r
 *\r
 * @initializer{IotMqttPublishInfo_t,IOT_MQTT_PUBLISH_INFO_INITIALIZER}\r
 *\r
 * #IotMqttPublishInfo_t.retryMs and #IotMqttPublishInfo_t.retryLimit are only\r
 * relevant to QoS 1 PUBLISH messages. They are ignored for QoS 0 PUBLISH\r
 * messages and LWT messages. These members control retransmissions of QoS 1\r
 * messages under the following rules:\r
 * - Retransmission is disabled when #IotMqttPublishInfo_t.retryLimit is 0.\r
 * After sending the PUBLISH, the library will wait indefinitely for a PUBACK.\r
 * - If #IotMqttPublishInfo_t.retryLimit is greater than 0, then QoS 1 publishes\r
 * that do not receive a PUBACK within #IotMqttPublishInfo_t.retryMs will be\r
 * retransmitted, up to #IotMqttPublishInfo_t.retryLimit times.\r
 *\r
 * Retransmission follows a truncated exponential backoff strategy. The constant\r
 * @ref IOT_MQTT_RETRY_MS_CEILING controls the maximum time between retransmissions.\r
 *\r
 * After #IotMqttPublishInfo_t.retryLimit retransmissions are sent, the MQTT\r
 * library will wait @ref IOT_MQTT_RESPONSE_WAIT_MS before a final check\r
 * for a PUBACK. If no PUBACK was received within this time, the QoS 1 PUBLISH\r
 * fails with the code #IOT_MQTT_RETRY_NO_RESPONSE.\r
 *\r
 * @note The lengths of the strings in this struct should not include the NULL\r
 * terminator. Strings in this struct do not need to be NULL-terminated.\r
 *\r
 * @note The AWS IoT MQTT server does not support the DUP bit. When\r
 * [using this library with the AWS IoT MQTT server](@ref IotMqttConnectInfo_t.awsIotMqttMode),\r
 * retransmissions will instead be sent with a new packet identifier in the PUBLISH\r
 * packet. This is a nonstandard workaround. Note that this workaround has some\r
 * flaws, including the following:\r
 * - The previous packet identifier is forgotten, so if a PUBACK arrives for that\r
 * packet identifier, it will be ignored. On an exceptionally busy network, this\r
 * may cause excessive retransmissions when too many PUBACKS arrive after the\r
 * PUBLISH packet identifier is changed. However, the exponential backoff\r
 * retransmission strategy should mitigate this problem.\r
 * - Log messages will be printed using the new packet identifier; the old packet\r
 * identifier is not saved.\r
 *\r
 * <b>Example</b>\r
 *\r
 * Consider a situation where\r
 * - @ref IOT_MQTT_RETRY_MS_CEILING is 60000\r
 * - #IotMqttPublishInfo_t.retryMs is 2000\r
 * - #IotMqttPublishInfo_t.retryLimit is 20\r
 *\r
 * A PUBLISH message will be retransmitted at the following times after the initial\r
 * transmission if no PUBACK is received:\r
 * - 2000 ms (2000 ms after previous transmission)\r
 * - 6000 ms (4000 ms after previous transmission)\r
 * - 14000 ms (8000 ms after previous transmission)\r
 * - 30000 ms (16000 ms after previous transmission)\r
 * - 62000 ms (32000 ms after previous transmission)\r
 * - 122000 ms, 182000 ms, 242000 ms... (every 60000 ms until 20 transmissions have been sent)\r
 *\r
 * After the 20th retransmission, the MQTT library will wait\r
 * @ref IOT_MQTT_RESPONSE_WAIT_MS before checking a final time for a PUBACK.\r
 */\r
typedef struct IotMqttPublishInfo\r
{\r
    IotMqttQos_t qos;         /**< @brief QoS of message. Must be 0 or 1. */\r
    bool retain;              /**< @brief MQTT message retain flag. */\r
\r
    const char * pTopicName;  /**< @brief Topic name of PUBLISH. */\r
    uint16_t topicNameLength; /**< @brief Length of #IotMqttPublishInfo_t.pTopicName. */\r
\r
    const void * pPayload;    /**< @brief Payload of PUBLISH. */\r
    size_t payloadLength;     /**< @brief Length of #IotMqttPublishInfo_t.pPayload. For LWT messages, this is limited to 65535. */\r
\r
    uint32_t retryMs;         /**< @brief If no response is received within this time, the message is retransmitted. */\r
    uint32_t retryLimit;      /**< @brief How many times to attempt retransmission. */\r
} IotMqttPublishInfo_t;\r
\r
/**\r
 * @ingroup mqtt_datatypes_paramstructs\r
 * @brief Parameter to an MQTT callback function.\r
 *\r
 * @paramfor MQTT callback functions\r
 *\r
 * The MQTT library passes this struct to registered callback whenever an\r
 * operation completes, a message is received on a topic filter, or an MQTT\r
 * connection is disconnected.\r
 *\r
 * The members of this struct are different based on the callback trigger. If the\r
 * callback function was triggered for completed operation, the `operation`\r
 * member is valid. Otherwise, if the callback was triggered because of a\r
 * server-to-client PUBLISH, the `message` member is valid. Finally, if the callback\r
 * was triggered because of a disconnect, the `disconnectReason` member is valid.\r
 *\r
 * For an incoming PUBLISH, the `message.pTopicFilter` parameter provides the\r
 * subscription topic filter that matched the topic name in the PUBLISH. Because\r
 * topic filters may use MQTT wildcards, the topic filter may be different from the\r
 * topic name. This pointer must be treated as read-only; the topic filter must not\r
 * be modified. Additionally, the topic filter may go out of scope as soon as the\r
 * callback function returns, so it must be copied if it is needed at a later time.\r
 *\r
 * @attention Any pointers in this callback parameter may be freed as soon as\r
 * the [callback function](@ref IotMqttCallbackInfo_t.function) returns.\r
 * Therefore, data must be copied if it is needed after the callback function\r
 * returns.\r
 * @attention The MQTT library may set strings that are not NULL-terminated.\r
 *\r
 * @see #IotMqttCallbackInfo_t for the signature of a callback function.\r
 */\r
typedef struct IotMqttCallbackParam\r
{\r
    /**\r
     * @brief The MQTT connection associated with this completed operation,\r
     * incoming PUBLISH, or disconnect.\r
     *\r
     * [MQTT API functions](@ref mqtt_functions) are safe to call from a callback\r
     * for completed operations or incoming PUBLISH messages. However, blocking\r
     * function calls (including @ref mqtt_function_wait) are not recommended\r
     * (though still safe). Do not call any API functions from a disconnect\r
     * callback.\r
     */\r
    IotMqttConnection_t mqttConnection;\r
\r
    union\r
    {\r
        /* Valid for completed operations. */\r
        struct\r
        {\r
            IotMqttOperationType_t type;  /**< @brief Type of operation that completed. */\r
            IotMqttOperation_t reference; /**< @brief Reference to the operation that completed. */\r
            IotMqttError_t result;        /**< @brief Result of operation, e.g. succeeded or failed. */\r
        } operation;\r
\r
        /* Valid for incoming PUBLISH messages. */\r
        struct\r
        {\r
            const char * pTopicFilter;  /**< @brief Topic filter that matched the message. */\r
            uint16_t topicFilterLength; /**< @brief Length of `pTopicFilter`. */\r
            IotMqttPublishInfo_t info;  /**< @brief PUBLISH message received from the server. */\r
        } message;\r
\r
        /* Valid when a connection is disconnected. */\r
        IotMqttDisconnectReason_t disconnectReason; /**< @brief Why the MQTT connection was disconnected. */\r
    } u; /**< @brief Valid member depends on callback type. */\r
} IotMqttCallbackParam_t;\r
\r
/**\r
 * @ingroup mqtt_datatypes_paramstructs\r
 * @brief Information on a user-provided MQTT callback function.\r
 *\r
 * @paramfor @ref mqtt_function_subscribe, @ref mqtt_function_unsubscribe,\r
 * and @ref mqtt_function_publish. Cannot be used with #IOT_MQTT_FLAG_WAITABLE.\r
 *\r
 * Provides a function to be invoked when an operation completes or when a\r
 * server-to-client PUBLISH is received.\r
 *\r
 * @initializer{IotMqttCallbackInfo_t,IOT_MQTT_CALLBACK_INFO_INITIALIZER}\r
 *\r
 * Below is an example for receiving an asynchronous notification on operation\r
 * completion. See @ref mqtt_function_subscribe for an example of using this struct\r
 * with for incoming PUBLISH messages.\r
 *\r
 * @code{c}\r
 * // Operation completion callback.\r
 * void operationComplete( void * pArgument, IotMqttCallbackParam_t * pOperation );\r
 *\r
 * // Callback information.\r
 * IotMqttCallbackInfo_t callbackInfo = IOT_MQTT_CALLBACK_INFO_INITIALIZER;\r
 * callbackInfo.function = operationComplete;\r
 *\r
 * // Operation to wait for.\r
 * IotMqttError_t result = IotMqtt_Publish( &mqttConnection,\r
 *                                          &publishInfo,\r
 *                                          0,\r
 *                                          &callbackInfo,\r
 *                                          &reference );\r
 *\r
 * // Publish should have returned IOT_MQTT_STATUS_PENDING. Once a response\r
 * // is received, operationComplete is executed with the actual status passed\r
 * // in pOperation.\r
 * @endcode\r
 */\r
typedef struct IotMqttCallbackInfo\r
{\r
    void * pCallbackContext; /**< @brief The first parameter to pass to the callback function to provide context. */\r
\r
    /**\r
     * @brief User-provided callback function signature.\r
     *\r
     * @param[in] void * #IotMqttCallbackInfo_t.pCallbackContext\r
     * @param[in] IotMqttCallbackParam_t * Details on the outcome of the MQTT operation\r
     * or an incoming MQTT PUBLISH.\r
     *\r
     * @see #IotMqttCallbackParam_t for more information on the second parameter.\r
     */\r
    void ( * function )( void *,\r
                         IotMqttCallbackParam_t * );\r
} IotMqttCallbackInfo_t;\r
\r
/**\r
 * @ingroup mqtt_datatypes_paramstructs\r
 * @brief Information on an MQTT subscription.\r
 *\r
 * @paramfor @ref mqtt_function_subscribe, @ref mqtt_function_unsubscribe\r
 *\r
 * An array of these is passed to @ref mqtt_function_subscribe and @ref\r
 * mqtt_function_unsubscribe. However, #IotMqttSubscription_t.callback and\r
 * and #IotMqttSubscription_t.qos are ignored by @ref mqtt_function_unsubscribe.\r
 *\r
 * @initializer{IotMqttSubscription_t,IOT_MQTT_SUBSCRIPTION_INITIALIZER}\r
 *\r
 * @note The lengths of the strings in this struct should not include the NULL\r
 * terminator. Strings in this struct do not need to be NULL-terminated.\r
 * @see #IotMqttCallbackInfo_t for details on setting a callback function.\r
 */\r
typedef struct IotMqttSubscription\r
{\r
    /**\r
     * @brief QoS of messages delivered on subscription.\r
     *\r
     * Must be `0` or `1`. Ignored by @ref mqtt_function_unsubscribe.\r
     */\r
    IotMqttQos_t qos;\r
\r
    const char * pTopicFilter;  /**< @brief Topic filter of subscription. */\r
    uint16_t topicFilterLength; /**< @brief Length of #IotMqttSubscription_t.pTopicFilter. */\r
\r
    /**\r
     * @brief Callback to invoke when a message is received.\r
     *\r
     * See #IotMqttCallbackInfo_t. Ignored by @ref mqtt_function_unsubscribe.\r
     */\r
    IotMqttCallbackInfo_t callback;\r
} IotMqttSubscription_t;\r
\r
/**\r
 * @ingroup mqtt_datatypes_paramstructs\r
 * @brief Information on a new MQTT connection.\r
 *\r
 * @paramfor @ref mqtt_function_connect\r
 *\r
 * Passed as an argument to @ref mqtt_function_connect. Most members of this struct\r
 * correspond to the content of an [MQTT CONNECT packet.]\r
 * (http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/csprd02/mqtt-v3.1.1-csprd02.html#_Toc385349764)\r
 *\r
 * @initializer{IotMqttConnectInfo_t,IOT_MQTT_CONNECT_INFO_INITIALIZER}\r
 *\r
 * @note The lengths of the strings in this struct should not include the NULL\r
 * terminator. Strings in this struct do not need to be NULL-terminated.\r
 */\r
typedef struct IotMqttConnectInfo\r
{\r
    /**\r
     * @brief Specifies if this MQTT connection is to an AWS IoT MQTT server.\r
     *\r
     * The AWS IoT MQTT broker [differs somewhat from the MQTT specification.]\r
     * (https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html)\r
     * When this member is `true`, the MQTT library will accommodate these\r
     * differences. This setting should be `false` when communicating with a\r
     * fully-compliant MQTT broker.\r
     *\r
     * @attention This setting <b>MUST</b> be `true` when using the AWS IoT MQTT\r
     * server; it <b>MUST</b> be `false` otherwise.\r
     * @note Currently, @ref IOT_MQTT_CONNECT_INFO_INITIALIZER sets this\r
     * this member to `true`.\r
     */\r
    bool awsIotMqttMode;\r
\r
    /**\r
     * @brief Whether this connection is a clean session.\r
     *\r
     * MQTT servers can maintain and topic filter subscriptions and unacknowledged\r
     * PUBLISH messages. These form part of an <i>MQTT session</i>, which is identified by\r
     * the [client identifier](@ref IotMqttConnectInfo_t.pClientIdentifier).\r
     *\r
     * Setting this value to `true` establishes a <i>clean session</i>, which causes\r
     * the MQTT server to discard any previous session data for a client identifier.\r
     * When the client disconnects, the server discards all session data. If this\r
     * value is `true`, #IotMqttConnectInfo_t.pPreviousSubscriptions and\r
     * #IotMqttConnectInfo_t.previousSubscriptionCount are ignored.\r
     *\r
     * Setting this value to `false` does one of the following:\r
     * - If no previous session exists, the MQTT server will create a new\r
     * <i>persistent session</i>. The server may maintain subscriptions and\r
     * unacknowledged PUBLISH messages after a client disconnects, to be restored\r
     * once the same client identifier reconnects.\r
     * - If a previous session exists, the MQTT server restores all of the session's\r
     * subscriptions for the client identifier and may immediately transmit any\r
     * unacknowledged PUBLISH packets to the client.\r
     *\r
     * When a client with a persistent session disconnects, the MQTT server\r
     * continues to maintain all subscriptions and unacknowledged PUBLISH messages.\r
     * The client must also remember the session subscriptions to restore them\r
     * upon reconnecting. #IotMqttConnectInfo_t.pPreviousSubscriptions and\r
     * #IotMqttConnectInfo_t.previousSubscriptionCount are used to restore a\r
     * previous session's subscriptions client-side.\r
     */\r
    bool cleanSession;\r
\r
    /**\r
     * @brief An array of MQTT subscriptions present in a previous session, if any.\r
     *\r
     * Pointer to the start of an array of subscriptions present a previous session,\r
     * if any. These subscriptions will be immediately restored upon reconnecting.\r
     *\r
     * This member is ignored if it is `NULL` or #IotMqttConnectInfo_t.cleanSession\r
     * is `true`. If this member is not `NULL`, #IotMqttConnectInfo_t.previousSubscriptionCount\r
     * must be nonzero.\r
     */\r
    const IotMqttSubscription_t * pPreviousSubscriptions;\r
\r
    /**\r
     * @brief The number of MQTT subscriptions present in a previous session, if any.\r
     *\r
     * Number of subscriptions contained in the array\r
     * #IotMqttConnectInfo_t.pPreviousSubscriptions.\r
     *\r
     * This value is ignored if #IotMqttConnectInfo_t.pPreviousSubscriptions\r
     * is `NULL` or #IotMqttConnectInfo_t.cleanSession is `true`. If\r
     * #IotMqttConnectInfo_t.pPreviousSubscriptions is not `NULL`, this value\r
     * must be nonzero.\r
     */\r
    size_t previousSubscriptionCount;\r
\r
    /**\r
     * @brief A message to publish if the new MQTT connection is unexpectedly closed.\r
     *\r
     * A Last Will and Testament (LWT) message may be published if this connection is\r
     * closed without sending an MQTT DISCONNECT packet. This pointer should be set to\r
     * an #IotMqttPublishInfo_t representing any LWT message to publish. If an LWT\r
     * is not needed, this member must be set to `NULL`.\r
     *\r
     * Unlike other PUBLISH messages, an LWT message is limited to 65535 bytes in\r
     * length. Additionally, [pWillInfo->retryMs](@ref IotMqttPublishInfo_t.retryMs)\r
     * and [pWillInfo->retryLimit](@ref IotMqttPublishInfo_t.retryLimit) will\r
     * be ignored.\r
     */\r
    const IotMqttPublishInfo_t * pWillInfo;\r
\r
    uint16_t keepAliveSeconds;       /**< @brief Period of keep-alive messages. Set to 0 to disable keep-alive. */\r
\r
    const char * pClientIdentifier;  /**< @brief MQTT client identifier. */\r
    uint16_t clientIdentifierLength; /**< @brief Length of #IotMqttConnectInfo_t.pClientIdentifier. */\r
\r
    /* These credentials are not used by AWS IoT and may be ignored if\r
     * awsIotMqttMode is true. */\r
    const char * pUserName;  /**< @brief Username for MQTT connection. */\r
    uint16_t userNameLength; /**< @brief Length of #IotMqttConnectInfo_t.pUserName. */\r
    const char * pPassword;  /**< @brief Password for MQTT connection. */\r
    uint16_t passwordLength; /**< @brief Length of #IotMqttConnectInfo_t.pPassword. */\r
} IotMqttConnectInfo_t;\r
\r
#if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1\r
\r
/**\r
 * @cond DOXYGEN_IGNORE\r
 * Doxygen should ignore this section.\r
 *\r
 * Forward declaration of the internal MQTT packet structure.\r
 */\r
    struct _mqttPacket;\r
/** @endcond */\r
\r
/**\r
 * @ingroup mqtt_datatypes_paramstructs\r
 * @brief Function pointers for MQTT packet serializer overrides.\r
 *\r
 * These function pointers allow the MQTT serialization and deserialization functions\r
 * to be overridden for an MQTT connection. The compile-time setting\r
 * @ref IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES must be `1` to enable this functionality.\r
 * See the #IotMqttSerializer_t::serialize and #IotMqttSerializer_t::deserialize\r
 * members for a list of functions that can be overridden. In addition, the functions\r
 * for freeing packets and determining the packet type can also be overridden. If\r
 * @ref IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES is `1`, the serializer initialization and\r
 * cleanup functions may be extended. See documentation of\r
 * @ref IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES for more information.\r
 *\r
 * If any function pointers that are `NULL`, then the default implementation of that\r
 * function will be used.\r
 */\r
    typedef struct IotMqttSerializer\r
    {\r
        /**\r
         * @brief Get the MQTT packet type from a stream of bytes off the network.\r
         *\r
         * @param[in] pNetworkConnection Reference to the network connection.\r
         * @param[in] pNetworkInterface Function pointers used to interact with the\r
         * network.\r
         *\r
         * <b>Default implementation:</b> #_IotMqtt_GetPacketType\r
         */\r
        uint8_t ( * getPacketType )( void * /* pNetworkConnection */,\r
                                     const IotNetworkInterface_t * /* pNetworkInterface */ );\r
\r
        /**\r
         * @brief Get the remaining length from a stream of bytes off the network.\r
         *\r
         * @param[in] pNetworkConnection Reference to the network connection.\r
         * @param[in] pNetworkInterface Function pointers used to interact with the\r
         * network.\r
         *\r
         * <b>Default implementation:</b> #_IotMqtt_GetRemainingLength\r
         */\r
        size_t ( * getRemainingLength )( void * pNetworkConnection,\r
                                         const IotNetworkInterface_t * pNetworkInterface );\r
\r
        /**\r
         * @brief Free a packet generated by the serializer.\r
         *\r
         * This function pointer must be set if any other serializer override is set.\r
         * @param[in] uint8_t* The packet to free.\r
         *\r
         * <b>Default implementation:</b> #_IotMqtt_FreePacket\r
         */\r
        void ( * freePacket )( uint8_t * /* pPacket */ );\r
\r
        struct\r
        {\r
            /**\r
             * @brief CONNECT packet serializer function.\r
             * @param[in] IotMqttConnectInfo_t* User-provided CONNECT information.\r
             * @param[out] uint8_t** Where the CONNECT packet is written.\r
             * @param[out] size_t* Size of the CONNECT packet.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_SerializeConnect\r
             */\r
            IotMqttError_t ( * connect )( const IotMqttConnectInfo_t * /* pConnectInfo */,\r
                                          uint8_t ** /* pConnectPacket */,\r
                                          size_t * /* pPacketSize */ );\r
\r
            /**\r
             * @brief PUBLISH packet serializer function.\r
             * @param[in] IotMqttPublishInfo_t* User-provided PUBLISH information.\r
             * @param[out] uint8_t** Where the PUBLISH packet is written.\r
             * @param[out] size_t* Size of the PUBLISH packet.\r
             * @param[out] uint16_t* The packet identifier generated for this PUBLISH.\r
             * @param[out] uint8_t** Where the high byte of the packet identifier\r
             * is written.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_SerializePublish\r
             */\r
            IotMqttError_t ( * publish )( const IotMqttPublishInfo_t * /* pPublishInfo */,\r
                                          uint8_t ** /* pPublishPacket */,\r
                                          size_t * /* pPacketSize */,\r
                                          uint16_t * /* pPacketIdentifier */,\r
                                          uint8_t ** /* pPacketIdentifierHigh */ );\r
\r
            /**\r
             * @brief Set the `DUP` bit in a QoS `1` PUBLISH packet.\r
             * @param[in] uint8_t* Pointer to the PUBLISH packet to modify.\r
             * @param[in] uint8_t* The high byte of any packet identifier to modify.\r
             * @param[out] uint16_t* New packet identifier (AWS IoT MQTT mode only).\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_PublishSetDup\r
             */\r
            void ( *publishSetDup )( uint8_t * /* pPublishPacket */,\r
                                     uint8_t * /* pPacketIdentifierHigh */,\r
                                     uint16_t * /* pNewPacketIdentifier */ );\r
\r
            /**\r
             * @brief PUBACK packet serializer function.\r
             * @param[in] uint16_t The packet identifier to place in PUBACK.\r
             * @param[out] uint8_t** Where the PUBACK packet is written.\r
             * @param[out] size_t* Size of the PUBACK packet.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_SerializePuback\r
             */\r
            IotMqttError_t ( * puback )( uint16_t /* packetIdentifier */,\r
                                         uint8_t ** /* pPubackPacket */,\r
                                         size_t * /* pPacketSize */ );\r
\r
            /**\r
             * @brief SUBSCRIBE packet serializer function.\r
             * @param[in] IotMqttSubscription_t* User-provided array of subscriptions.\r
             * @param[in] size_t Number of elements in the subscription array.\r
             * @param[out] uint8_t** Where the SUBSCRIBE packet is written.\r
             * @param[out] size_t* Size of the SUBSCRIBE packet.\r
             * @param[out] uint16_t* The packet identifier generated for this SUBSCRIBE.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_SerializeSubscribe\r
             */\r
            IotMqttError_t ( * subscribe )( const IotMqttSubscription_t * /* pSubscriptionList */,\r
                                            size_t /* subscriptionCount */,\r
                                            uint8_t ** /* pSubscribePacket */,\r
                                            size_t * /* pPacketSize */,\r
                                            uint16_t * /* pPacketIdentifier */ );\r
\r
            /**\r
             * @brief UNSUBSCRIBE packet serializer function.\r
             * @param[in] IotMqttSubscription_t* User-provided array of subscriptions to remove.\r
             * @param[in] size_t Number of elements in the subscription array.\r
             * @param[out] uint8_t** Where the UNSUBSCRIBE packet is written.\r
             * @param[out] size_t* Size of the UNSUBSCRIBE packet.\r
             * @param[out] uint16_t* The packet identifier generated for this UNSUBSCRIBE.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_SerializeUnsubscribe\r
             */\r
            IotMqttError_t ( * unsubscribe )( const IotMqttSubscription_t * /* pSubscriptionList */,\r
                                              size_t /* subscriptionCount */,\r
                                              uint8_t ** /* pUnsubscribePacket */,\r
                                              size_t * /* pPacketSize */,\r
                                              uint16_t * /* pPacketIdentifier */ );\r
\r
            /**\r
             * @brief PINGREQ packet serializer function.\r
             * @param[out] uint8_t** Where the PINGREQ packet is written.\r
             * @param[out] size_t* Size of the PINGREQ packet.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_SerializePingreq\r
             */\r
            IotMqttError_t ( * pingreq )( uint8_t ** /* pPingreqPacket */,\r
                                          size_t * /* pPacketSize */ );\r
\r
            /**\r
             * @brief DISCONNECT packet serializer function.\r
             * @param[out] uint8_t** Where the DISCONNECT packet is written.\r
             * @param[out] size_t* Size of the DISCONNECT packet.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_SerializeDisconnect\r
             */\r
            IotMqttError_t ( * disconnect )( uint8_t ** /* pDisconnectPacket */,\r
                                             size_t * /* pPacketSize */ );\r
        } serialize; /**< @brief Overrides the packet serialization functions for a single connection. */\r
\r
        struct\r
        {\r
            /**\r
             * @brief CONNACK packet deserializer function.\r
             * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing a CONNACK.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_DeserializeConnack\r
             */\r
            IotMqttError_t ( * connack )( struct _mqttPacket * /* pConnack */ );\r
\r
            /**\r
             * @brief PUBLISH packet deserializer function.\r
             * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing a PUBLISH.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_DeserializePublish\r
             */\r
            IotMqttError_t ( * publish )( struct _mqttPacket * /* pPublish */ );\r
\r
            /**\r
             * @brief PUBACK packet deserializer function.\r
             * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing a PUBACK.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_DeserializePuback\r
             */\r
            IotMqttError_t ( * puback )( struct _mqttPacket * pPuback );\r
\r
            /**\r
             * @brief SUBACK packet deserializer function.\r
             * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing a SUBACK.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_DeserializeSuback\r
             */\r
            IotMqttError_t ( * suback )( struct _mqttPacket * /* pSuback */ );\r
\r
            /**\r
             * @brief UNSUBACK packet deserializer function.\r
             * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing an UNSUBACK.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_DeserializeUnsuback\r
             */\r
            IotMqttError_t ( * unsuback )( struct _mqttPacket * /* pUnsuback */ );\r
\r
            /**\r
             * @brief PINGRESP packet deserializer function.\r
             * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing a PINGRESP.\r
             *\r
             * <b>Default implementation:</b> #_IotMqtt_DeserializePingresp\r
             */\r
            IotMqttError_t ( * pingresp )( struct _mqttPacket * /* pPingresp */ );\r
        } deserialize; /**< @brief Overrides the packet deserialization functions for a single connection. */\r
    } IotMqttSerializer_t;\r
#else /* if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1 */\r
\r
/* When MQTT packet serializer overrides are disabled, this struct is an\r
 * incomplete type. */\r
    typedef struct IotMqttSerializer IotMqttSerializer_t;\r
\r
#endif /* if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1 */\r
\r
/**\r
 * @ingroup mqtt_datatypes_paramstructs\r
 * @brief Infomation on the transport-layer network connection for the new MQTT\r
 * connection.\r
 *\r
 * @paramfor @ref mqtt_function_connect\r
 *\r
 * The MQTT library needs to be able to send and receive data over a network.\r
 * This struct provides an interface for interacting with the network.\r
 *\r
 * @initializer{IotMqttNetworkInfo_t,IOT_MQTT_NETWORK_INFO_INITIALIZER}\r
 */\r
typedef struct IotMqttNetworkInfo\r
{\r
    /**\r
     * @brief Whether a new network connection should be created.\r
     *\r
     * When this value is `true`, a new transport-layer network connection will\r
     * be created along with the MQTT connection. #IotMqttNetworkInfo_t::pNetworkServerInfo\r
     * and #IotMqttNetworkInfo_t::pNetworkCredentialInfo are valid when this value\r
     * is `true`.\r
     *\r
     * When this value is `false`, the MQTT connection will use a transport-layer\r
     * network connection that has already been established. The MQTT library will\r
     * still set the appropriate receive callback even if the network connection\r
     * has been established.\r
     * #IotMqttNetworkInfo_t::pNetworkConnection, which represents an established\r
     * network connection, is valid when this value is `false`.\r
     */\r
    bool createNetworkConnection;\r
\r
    union\r
    {\r
        struct\r
        {\r
            /**\r
             * @brief Information on the MQTT server, passed as `pConnectionInfo` to\r
             * #IotNetworkInterface_t::create.\r
             *\r
             * This member is opaque to the MQTT library. It is passed to the network\r
             * interface when creating a new network connection. It is only valid when\r
             * #IotMqttNetworkInfo_t::createNetworkConnection is `true`.\r
             */\r
            void * pNetworkServerInfo;\r
\r
            /**\r
             * @brief Credentials for the MQTT server, passed as `pCredentialInfo` to\r
             * #IotNetworkInterface_t::create.\r
             *\r
             * This member is opaque to the MQTT library. It is passed to the network\r
             * interface when creating a new network connection. It is only valid when\r
             * #IotMqttNetworkInfo_t::createNetworkConnection is `true`.\r
             */\r
            void * pNetworkCredentialInfo;\r
        } setup;\r
\r
        /**\r
         * @brief An established transport-layer network connection.\r
         *\r
         * This member is opaque to the MQTT library. It is passed to the network\r
         * interface to reference an established network connection. It is only\r
         * valid when #IotMqttNetworkInfo_t::createNetworkConnection is `false`.\r
         */\r
        void * pNetworkConnection;\r
    } u /**< @brief Valid member depends of IotMqttNetworkInfo_t.createNetworkConnection. */;\r
\r
    /**\r
     * @brief The network functions used by the new MQTT connection.\r
     *\r
     * @attention The function pointers of the network interface must remain valid\r
     * for the lifetime of the MQTT connection.\r
     */\r
    const IotNetworkInterface_t * pNetworkInterface;\r
\r
    /**\r
     * @brief A callback function to invoke when this MQTT connection is disconnected.\r
     */\r
    IotMqttCallbackInfo_t disconnectCallback;\r
\r
    #if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1\r
\r
        /**\r
         * @brief MQTT packet serializer overrides used by the new MQTT connection.\r
         *\r
         * @attention The function pointers of the MQTT serializer overrides must\r
         * remain valid for the lifetime of the MQTT connection.\r
         */\r
        const IotMqttSerializer_t * pMqttSerializer;\r
    #endif\r
} IotMqttNetworkInfo_t;\r
\r
/*------------------------- MQTT defined constants --------------------------*/\r
\r
/**\r
 * @constantspage{mqtt,MQTT library}\r
 *\r
 * @section mqtt_constants_initializers MQTT Initializers\r
 * @brief Provides default values for the data types of the MQTT library.\r
 *\r
 * @snippet this define_mqtt_initializers\r
 *\r
 * All user-facing data types of the MQTT library should be initialized using\r
 * one of the following.\r
 *\r
 * @warning Failing to initialize an MQTT data type with the appropriate initializer\r
 * may result in undefined behavior!\r
 * @note The initializers may change at any time in future versions, but their\r
 * names will remain the same.\r
 *\r
 * <b>Example</b>\r
 * @code{c}\r
 * IotMqttNetworkInfo_t networkInfo = IOT_MQTT_NETWORK_INFO_INITIALIZER;\r
 * IotMqttSerializer_t serializer = IOT_MQTT_SERIALIZER_INITIALIZER;\r
 * IotMqttConnectInfo_t connectInfo = IOT_MQTT_CONNECT_INFO_INITIALIZER;\r
 * IotMqttPublishInfo_t publishInfo = IOT_MQTT_PUBLISH_INFO_INITIALIZER;\r
 * IotMqttSubscription_t subscription = IOT_MQTT_SUBSCRIPTION_INITIALIZER;\r
 * IotMqttCallbackInfo_t callbackInfo = IOT_MQTT_CALLBACK_INFO_INITIALIZER;\r
 * IotMqttConnection_t connection = IOT_MQTT_CONNECTION_INITIALIZER;\r
 * IotMqttOperation_t operation = IOT_MQTT_OPERATION_INITIALIZER;\r
 * @endcode\r
 *\r
 * @section mqtt_constants_flags MQTT Function Flags\r
 * @brief Flags that modify the behavior of MQTT library functions.\r
 * - #IOT_MQTT_FLAG_WAITABLE <br>\r
 *   @copybrief IOT_MQTT_FLAG_WAITABLE\r
 * - #IOT_MQTT_FLAG_CLEANUP_ONLY <br>\r
 *   @copybrief IOT_MQTT_FLAG_CLEANUP_ONLY\r
 *\r
 * Flags should be bitwise-ORed with each other to change the behavior of\r
 * @ref mqtt_function_subscribe, @ref mqtt_function_unsubscribe,\r
 * @ref mqtt_function_publish, or @ref mqtt_function_disconnect.\r
 *\r
 * @note The values of the flags may change at any time in future versions, but\r
 * their names will remain the same. Additionally, flags that may be used together\r
 * will be bitwise-exclusive of each other.\r
 */\r
\r
/* @[define_mqtt_initializers] */\r
/** @brief Initializer for #IotMqttNetworkInfo_t. */\r
#define IOT_MQTT_NETWORK_INFO_INITIALIZER     { .createNetworkConnection = true }\r
/** @brief Initializer for #IotMqttSerializer_t. */\r
#define IOT_MQTT_SERIALIZER_INITIALIZER       { 0 }\r
/** @brief Initializer for #IotMqttConnectInfo_t. */\r
#define IOT_MQTT_CONNECT_INFO_INITIALIZER     { .cleanSession = true }\r
/** @brief Initializer for #IotMqttPublishInfo_t. */\r
#define IOT_MQTT_PUBLISH_INFO_INITIALIZER     { .qos = IOT_MQTT_QOS_0 }\r
/** @brief Initializer for #IotMqttSubscription_t. */\r
#define IOT_MQTT_SUBSCRIPTION_INITIALIZER     { .qos = IOT_MQTT_QOS_0 }\r
/** @brief Initializer for #IotMqttCallbackInfo_t. */\r
#define IOT_MQTT_CALLBACK_INFO_INITIALIZER    { 0 }\r
/** @brief Initializer for #IotMqttConnection_t. */\r
#define IOT_MQTT_CONNECTION_INITIALIZER       NULL\r
/** @brief Initializer for #IotMqttOperation_t. */\r
#define IOT_MQTT_OPERATION_INITIALIZER        NULL\r
/* @[define_mqtt_initializers] */\r
\r
/**\r
 * @brief Allows the use of @ref mqtt_function_wait for blocking until completion.\r
 *\r
 * This flag is always valid for @ref mqtt_function_subscribe and\r
 * @ref mqtt_function_unsubscribe. If passed to @ref mqtt_function_publish,\r
 * the parameter [pPublishInfo->qos](@ref IotMqttPublishInfo_t.qos) must not be `0`.\r
 *\r
 * An #IotMqttOperation_t <b>MUST</b> be provided if this flag is set. Additionally, an\r
 * #IotMqttCallbackInfo_t <b>MUST NOT</b> be provided.\r
 *\r
 * @note If this flag is set, @ref mqtt_function_wait <b>MUST</b> be called to clean up\r
 * resources.\r
 */\r
#define IOT_MQTT_FLAG_WAITABLE        ( 0x00000001 )\r
\r
/**\r
 * @brief Causes @ref mqtt_function_disconnect to only free memory and not send\r
 * an MQTT DISCONNECT packet.\r
 *\r
 * This flag is only valid for @ref mqtt_function_disconnect. It should be passed\r
 * to @ref mqtt_function_disconnect if the network goes offline or is otherwise\r
 * unusable.\r
 */\r
#define IOT_MQTT_FLAG_CLEANUP_ONLY    ( 0x00000001 )\r
\r
#endif /* ifndef IOT_MQTT_TYPES_H_ */\r