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