+++ /dev/null
-/*\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
projects / freertos / blobdiff