2 * Amazon FreeRTOS MQTT V2.0.0
\r
3 * Copyright (C) 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
\r
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
\r
6 * this software and associated documentation files (the "Software"), to deal in
\r
7 * the Software without restriction, including without limitation the rights to
\r
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
\r
9 * the Software, and to permit persons to whom the Software is furnished to do so,
\r
10 * subject to the following conditions:
\r
12 * The above copyright notice and this permission notice shall be included in all
\r
13 * copies or substantial portions of the Software.
\r
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
\r
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
\r
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
\r
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
\r
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
\r
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\r
22 * http://aws.amazon.com/freertos
\r
23 * http://www.FreeRTOS.org
\r
27 * @file iot_mqtt_types.h
\r
28 * @brief Types of the MQTT library.
\r
31 #ifndef IOT_MQTT_TYPES_H_
\r
32 #define IOT_MQTT_TYPES_H_
\r
34 /* The config header is always included first. */
\r
35 #include "iot_config.h"
\r
37 /* Standard includes. */
\r
38 #include <stdbool.h>
\r
42 /* Type includes. */
\r
43 #include "types/iot_platform_types.h"
\r
44 #include "types/iot_taskpool_types.h"
\r
46 /* Platform network include. */
\r
47 #include "platform/iot_network.h"
\r
49 /*---------------------------- MQTT handle types ----------------------------*/
\r
52 * @handles{mqtt,MQTT library}
\r
56 * @ingroup mqtt_datatypes_handles
\r
57 * @brief Opaque handle of an MQTT connection.
\r
59 * This type identifies an MQTT connection, which is valid after a successful call
\r
60 * to @ref mqtt_function_connect. A variable of this type is passed as the first
\r
61 * argument to [MQTT library functions](@ref mqtt_functions) to identify which
\r
62 * connection that function acts on.
\r
64 * A call to @ref mqtt_function_disconnect makes a connection handle invalid. Once
\r
65 * @ref mqtt_function_disconnect returns, the connection handle should no longer
\r
68 * @initializer{IotMqttConnection_t,IOT_MQTT_CONNECTION_INITIALIZER}
\r
70 typedef struct _mqttConnection * IotMqttConnection_t;
\r
73 * @ingroup mqtt_datatypes_handles
\r
74 * @brief Opaque handle that references an in-progress MQTT operation.
\r
76 * Set as an output parameter of @ref mqtt_function_publish, @ref mqtt_function_subscribe,
\r
77 * and @ref mqtt_function_unsubscribe. These functions queue an MQTT operation; the result
\r
78 * of the operation is unknown until a response from the MQTT server is received. Therefore,
\r
79 * this handle serves as a reference to MQTT operations awaiting MQTT server response.
\r
81 * This reference will be valid from the successful return of @ref mqtt_function_publish,
\r
82 * @ref mqtt_function_subscribe, or @ref mqtt_function_unsubscribe. The reference becomes
\r
83 * invalid once the [completion callback](@ref IotMqttCallbackInfo_t) is invoked, or
\r
84 * @ref mqtt_function_wait returns.
\r
86 * @initializer{IotMqttOperation_t,IOT_MQTT_OPERATION_INITIALIZER}
\r
88 * @see @ref mqtt_function_wait and #IOT_MQTT_FLAG_WAITABLE for waiting on a reference.
\r
89 * #IotMqttCallbackInfo_t and #IotMqttCallbackParam_t for an asynchronous notification
\r
92 typedef struct _mqttOperation * IotMqttOperation_t;
\r
94 /*-------------------------- MQTT enumerated types --------------------------*/
\r
97 * @enums{mqtt,MQTT library}
\r
101 * @ingroup mqtt_datatypes_enums
\r
102 * @brief Return codes of [MQTT functions](@ref mqtt_functions).
\r
104 * The function @ref mqtt_function_strerror can be used to get a return code's
\r
107 typedef enum IotMqttError
\r
110 * @brief MQTT operation completed successfully.
\r
112 * Functions that may return this value:
\r
113 * - @ref mqtt_function_connect
\r
114 * - @ref mqtt_function_publish with QoS 0 parameter
\r
115 * - @ref mqtt_function_wait
\r
116 * - @ref mqtt_function_timedsubscribe
\r
117 * - @ref mqtt_function_timedunsubscribe
\r
118 * - @ref mqtt_function_timedpublish
\r
120 * Will also be the value of an operation completion callback's
\r
121 * #IotMqttCallbackParam_t.result when successful.
\r
123 IOT_MQTT_SUCCESS = 0,
\r
126 * @brief MQTT operation queued, awaiting result.
\r
128 * Functions that may return this value:
\r
129 * - @ref mqtt_function_subscribe
\r
130 * - @ref mqtt_function_unsubscribe
\r
131 * - @ref mqtt_function_publish with QoS 1 parameter
\r
133 IOT_MQTT_STATUS_PENDING,
\r
136 * @brief Initialization failed.
\r
138 * Functions that may return this value:
\r
139 * - @ref mqtt_function_init
\r
141 IOT_MQTT_INIT_FAILED,
\r
144 * @brief At least one parameter is invalid.
\r
146 * Functions that may return this value:
\r
147 * - @ref mqtt_function_connect
\r
148 * - @ref mqtt_function_subscribe and @ref mqtt_function_timedsubscribe
\r
149 * - @ref mqtt_function_unsubscribe and @ref mqtt_function_timedunsubscribe
\r
150 * - @ref mqtt_function_publish and @ref mqtt_function_timedpublish
\r
151 * - @ref mqtt_function_wait
\r
153 IOT_MQTT_BAD_PARAMETER,
\r
156 * @brief MQTT operation failed because of memory allocation failure.
\r
158 * Functions that may return this value:
\r
159 * - @ref mqtt_function_connect
\r
160 * - @ref mqtt_function_subscribe and @ref mqtt_function_timedsubscribe
\r
161 * - @ref mqtt_function_unsubscribe and @ref mqtt_function_timedunsubscribe
\r
162 * - @ref mqtt_function_publish and @ref mqtt_function_timedpublish
\r
164 IOT_MQTT_NO_MEMORY,
\r
167 * @brief MQTT operation failed because the network was unusable.
\r
169 * This return value may indicate that the network is disconnected.
\r
171 * Functions that may return this value:
\r
172 * - @ref mqtt_function_connect
\r
173 * - @ref mqtt_function_wait
\r
174 * - @ref mqtt_function_timedsubscribe
\r
175 * - @ref mqtt_function_timedunsubscribe
\r
176 * - @ref mqtt_function_timedpublish
\r
178 * May also be the value of an operation completion callback's
\r
179 * #IotMqttCallbackParam_t.result.
\r
181 IOT_MQTT_NETWORK_ERROR,
\r
184 * @brief MQTT operation could not be scheduled, i.e. enqueued for sending.
\r
186 * Functions that may return this value:
\r
187 * - @ref mqtt_function_connect
\r
188 * - @ref mqtt_function_subscribe and @ref mqtt_function_timedsubscribe
\r
189 * - @ref mqtt_function_unsubscribe and @ref mqtt_function_timedunsubscribe
\r
190 * - @ref mqtt_function_publish and @ref mqtt_function_timedpublish
\r
192 IOT_MQTT_SCHEDULING_ERROR,
\r
195 * @brief MQTT response packet received from the network is malformed.
\r
197 * Functions that may return this value:
\r
198 * - @ref mqtt_function_connect
\r
199 * - @ref mqtt_function_wait
\r
200 * - @ref mqtt_function_timedsubscribe
\r
201 * - @ref mqtt_function_timedunsubscribe
\r
202 * - @ref mqtt_function_timedpublish
\r
204 * May also be the value of an operation completion callback's
\r
205 * #IotMqttCallbackParam_t.result.
\r
207 * @note If this value is received, the network connection has been closed.
\r
209 IOT_MQTT_BAD_RESPONSE,
\r
212 * @brief A blocking MQTT operation timed out.
\r
214 * Functions that may return this value:
\r
215 * - @ref mqtt_function_connect
\r
216 * - @ref mqtt_function_wait
\r
217 * - @ref mqtt_function_timedsubscribe
\r
218 * - @ref mqtt_function_timedunsubscribe
\r
219 * - @ref mqtt_function_timedpublish
\r
224 * @brief A CONNECT or at least one subscription was refused by the server.
\r
226 * Functions that may return this value:
\r
227 * - @ref mqtt_function_connect
\r
228 * - @ref mqtt_function_wait, but only when its #IotMqttOperation_t parameter
\r
229 * is associated with a SUBSCRIBE operation.
\r
230 * - @ref mqtt_function_timedsubscribe
\r
232 * May also be the value of an operation completion callback's
\r
233 * #IotMqttCallbackParam_t.result for a SUBSCRIBE.
\r
235 * @note If this value is returned and multiple subscriptions were passed to
\r
236 * @ref mqtt_function_subscribe (or @ref mqtt_function_timedsubscribe), it's
\r
237 * still possible that some of the subscriptions succeeded. This value only
\r
238 * signifies that AT LEAST ONE subscription was rejected. The function @ref
\r
239 * mqtt_function_issubscribed can be used to determine which subscriptions
\r
240 * were accepted or rejected.
\r
242 IOT_MQTT_SERVER_REFUSED,
\r
245 * @brief A QoS 1 PUBLISH received no response and [the retry limit]
\r
246 * (#IotMqttPublishInfo_t.retryLimit) was reached.
\r
248 * Functions that may return this value:
\r
249 * - @ref mqtt_function_wait, but only when its #IotMqttOperation_t parameter
\r
250 * is associated with a QoS 1 PUBLISH operation
\r
251 * - @ref mqtt_function_timedpublish
\r
253 * May also be the value of an operation completion callback's
\r
254 * #IotMqttCallbackParam_t.result for a QoS 1 PUBLISH.
\r
256 IOT_MQTT_RETRY_NO_RESPONSE
\r
260 * @ingroup mqtt_datatypes_enums
\r
261 * @brief Types of MQTT operations.
\r
263 * The function @ref mqtt_function_operationtype can be used to get an operation
\r
264 * type's description.
\r
266 typedef enum IotMqttOperationType
\r
268 IOT_MQTT_CONNECT, /**< Client-to-server CONNECT. */
\r
269 IOT_MQTT_PUBLISH_TO_SERVER, /**< Client-to-server PUBLISH. */
\r
270 IOT_MQTT_PUBACK, /**< Client-to-server PUBACK. */
\r
271 IOT_MQTT_SUBSCRIBE, /**< Client-to-server SUBSCRIBE. */
\r
272 IOT_MQTT_UNSUBSCRIBE, /**< Client-to-server UNSUBSCRIBE. */
\r
273 IOT_MQTT_PINGREQ, /**< Client-to-server PINGREQ. */
\r
274 IOT_MQTT_DISCONNECT /**< Client-to-server DISCONNECT. */
\r
275 } IotMqttOperationType_t;
\r
278 * @ingroup mqtt_datatypes_enums
\r
279 * @brief Quality of service levels for MQTT PUBLISH messages.
\r
281 * All MQTT PUBLISH messages, including Last Will and Testament and messages
\r
282 * received on subscription filters, have an associated <i>Quality of Service</i>,
\r
283 * which defines any delivery guarantees for that message.
\r
284 * - QoS 0 messages will be delivered at most once. This is a "best effort"
\r
285 * transmission with no retransmissions.
\r
286 * - QoS 1 messages will be delivered at least once. See #IotMqttPublishInfo_t
\r
287 * for the retransmission strategy this library uses to redeliver messages
\r
288 * assumed to be lost.
\r
290 * @attention QoS 2 is not supported by this library and should not be used.
\r
292 typedef enum IotMqttQos
\r
294 IOT_MQTT_QOS_0 = 0, /**< Delivery at most once. */
\r
295 IOT_MQTT_QOS_1 = 1, /**< Delivery at least once. See #IotMqttPublishInfo_t for client-side retry strategy. */
\r
296 IOT_MQTT_QOS_2 = 2 /**< Delivery exactly once. Unsupported, but enumerated for completeness. */
\r
300 * @ingroup mqtt_datatypes_enums
\r
301 * @brief The reason that an MQTT connection (and its associated network connection)
\r
302 * was disconnected.
\r
304 * When an MQTT connection is closed, its associated [disconnect callback]
\r
305 * (@ref IotMqttNetworkInfo_t::disconnectCallback) will be invoked. This type
\r
306 * is passed inside of an #IotMqttCallbackParam_t to provide a reason for the
\r
309 typedef enum IotMqttDisconnectReason
\r
311 IOT_MQTT_DISCONNECT_CALLED, /**< @ref mqtt_function_disconnect was invoked. */
\r
312 IOT_MQTT_BAD_PACKET_RECEIVED, /**< An invalid packet was received from the network. */
\r
313 IOT_MQTT_KEEP_ALIVE_TIMEOUT /**< Keep-alive response was not received within @ref IOT_MQTT_RESPONSE_WAIT_MS. */
\r
314 } IotMqttDisconnectReason_t;
\r
316 /*------------------------- MQTT parameter structs --------------------------*/
\r
319 * @paramstructs{mqtt,MQTT}
\r
323 * @ingroup mqtt_datatypes_paramstructs
\r
324 * @brief Information on a PUBLISH message.
\r
326 * @paramfor @ref mqtt_function_connect, @ref mqtt_function_publish
\r
328 * Passed to @ref mqtt_function_publish as the message to publish and @ref
\r
329 * mqtt_function_connect as the Last Will and Testament (LWT) message.
\r
331 * @initializer{IotMqttPublishInfo_t,IOT_MQTT_PUBLISH_INFO_INITIALIZER}
\r
333 * #IotMqttPublishInfo_t.retryMs and #IotMqttPublishInfo_t.retryLimit are only
\r
334 * relevant to QoS 1 PUBLISH messages. They are ignored for QoS 0 PUBLISH
\r
335 * messages and LWT messages. These members control retransmissions of QoS 1
\r
336 * messages under the following rules:
\r
337 * - Retransmission is disabled when #IotMqttPublishInfo_t.retryLimit is 0.
\r
338 * After sending the PUBLISH, the library will wait indefinitely for a PUBACK.
\r
339 * - If #IotMqttPublishInfo_t.retryLimit is greater than 0, then QoS 1 publishes
\r
340 * that do not receive a PUBACK within #IotMqttPublishInfo_t.retryMs will be
\r
341 * retransmitted, up to #IotMqttPublishInfo_t.retryLimit times.
\r
343 * Retransmission follows a truncated exponential backoff strategy. The constant
\r
344 * @ref IOT_MQTT_RETRY_MS_CEILING controls the maximum time between retransmissions.
\r
346 * After #IotMqttPublishInfo_t.retryLimit retransmissions are sent, the MQTT
\r
347 * library will wait @ref IOT_MQTT_RESPONSE_WAIT_MS before a final check
\r
348 * for a PUBACK. If no PUBACK was received within this time, the QoS 1 PUBLISH
\r
349 * fails with the code #IOT_MQTT_RETRY_NO_RESPONSE.
\r
351 * @note The lengths of the strings in this struct should not include the NULL
\r
352 * terminator. Strings in this struct do not need to be NULL-terminated.
\r
354 * @note The AWS IoT MQTT server does not support the DUP bit. When
\r
355 * [using this library with the AWS IoT MQTT server](@ref IotMqttConnectInfo_t.awsIotMqttMode),
\r
356 * retransmissions will instead be sent with a new packet identifier in the PUBLISH
\r
357 * packet. This is a nonstandard workaround. Note that this workaround has some
\r
358 * flaws, including the following:
\r
359 * - The previous packet identifier is forgotten, so if a PUBACK arrives for that
\r
360 * packet identifier, it will be ignored. On an exceptionally busy network, this
\r
361 * may cause excessive retransmissions when too many PUBACKS arrive after the
\r
362 * PUBLISH packet identifier is changed. However, the exponential backoff
\r
363 * retransmission strategy should mitigate this problem.
\r
364 * - Log messages will be printed using the new packet identifier; the old packet
\r
365 * identifier is not saved.
\r
369 * Consider a situation where
\r
370 * - @ref IOT_MQTT_RETRY_MS_CEILING is 60000
\r
371 * - #IotMqttPublishInfo_t.retryMs is 2000
\r
372 * - #IotMqttPublishInfo_t.retryLimit is 20
\r
374 * A PUBLISH message will be retransmitted at the following times after the initial
\r
375 * transmission if no PUBACK is received:
\r
376 * - 2000 ms (2000 ms after previous transmission)
\r
377 * - 6000 ms (4000 ms after previous transmission)
\r
378 * - 14000 ms (8000 ms after previous transmission)
\r
379 * - 30000 ms (16000 ms after previous transmission)
\r
380 * - 62000 ms (32000 ms after previous transmission)
\r
381 * - 122000 ms, 182000 ms, 242000 ms... (every 60000 ms until 20 transmissions have been sent)
\r
383 * After the 20th retransmission, the MQTT library will wait
\r
384 * @ref IOT_MQTT_RESPONSE_WAIT_MS before checking a final time for a PUBACK.
\r
386 typedef struct IotMqttPublishInfo
\r
388 IotMqttQos_t qos; /**< @brief QoS of message. Must be 0 or 1. */
\r
389 bool retain; /**< @brief MQTT message retain flag. */
\r
391 const char * pTopicName; /**< @brief Topic name of PUBLISH. */
\r
392 uint16_t topicNameLength; /**< @brief Length of #IotMqttPublishInfo_t.pTopicName. */
\r
394 const void * pPayload; /**< @brief Payload of PUBLISH. */
\r
395 size_t payloadLength; /**< @brief Length of #IotMqttPublishInfo_t.pPayload. For LWT messages, this is limited to 65535. */
\r
397 uint32_t retryMs; /**< @brief If no response is received within this time, the message is retransmitted. */
\r
398 uint32_t retryLimit; /**< @brief How many times to attempt retransmission. */
\r
399 } IotMqttPublishInfo_t;
\r
402 * @ingroup mqtt_datatypes_paramstructs
\r
403 * @brief Parameter to an MQTT callback function.
\r
405 * @paramfor MQTT callback functions
\r
407 * The MQTT library passes this struct to registered callback whenever an
\r
408 * operation completes, a message is received on a topic filter, or an MQTT
\r
409 * connection is disconnected.
\r
411 * The members of this struct are different based on the callback trigger. If the
\r
412 * callback function was triggered for completed operation, the `operation`
\r
413 * member is valid. Otherwise, if the callback was triggered because of a
\r
414 * server-to-client PUBLISH, the `message` member is valid. Finally, if the callback
\r
415 * was triggered because of a disconnect, the `disconnectReason` member is valid.
\r
417 * For an incoming PUBLISH, the `message.pTopicFilter` parameter provides the
\r
418 * subscription topic filter that matched the topic name in the PUBLISH. Because
\r
419 * topic filters may use MQTT wildcards, the topic filter may be different from the
\r
420 * topic name. This pointer must be treated as read-only; the topic filter must not
\r
421 * be modified. Additionally, the topic filter may go out of scope as soon as the
\r
422 * callback function returns, so it must be copied if it is needed at a later time.
\r
424 * @attention Any pointers in this callback parameter may be freed as soon as
\r
425 * the [callback function](@ref IotMqttCallbackInfo_t.function) returns.
\r
426 * Therefore, data must be copied if it is needed after the callback function
\r
428 * @attention The MQTT library may set strings that are not NULL-terminated.
\r
430 * @see #IotMqttCallbackInfo_t for the signature of a callback function.
\r
432 typedef struct IotMqttCallbackParam
\r
435 * @brief The MQTT connection associated with this completed operation,
\r
436 * incoming PUBLISH, or disconnect.
\r
438 * [MQTT API functions](@ref mqtt_functions) are safe to call from a callback
\r
439 * for completed operations or incoming PUBLISH messages. However, blocking
\r
440 * function calls (including @ref mqtt_function_wait) are not recommended
\r
441 * (though still safe). Do not call any API functions from a disconnect
\r
444 IotMqttConnection_t mqttConnection;
\r
448 /* Valid for completed operations. */
\r
451 IotMqttOperationType_t type; /**< @brief Type of operation that completed. */
\r
452 IotMqttOperation_t reference; /**< @brief Reference to the operation that completed. */
\r
453 IotMqttError_t result; /**< @brief Result of operation, e.g. succeeded or failed. */
\r
456 /* Valid for incoming PUBLISH messages. */
\r
459 const char * pTopicFilter; /**< @brief Topic filter that matched the message. */
\r
460 uint16_t topicFilterLength; /**< @brief Length of `pTopicFilter`. */
\r
461 IotMqttPublishInfo_t info; /**< @brief PUBLISH message received from the server. */
\r
464 /* Valid when a connection is disconnected. */
\r
465 IotMqttDisconnectReason_t disconnectReason; /**< @brief Why the MQTT connection was disconnected. */
\r
466 } u; /**< @brief Valid member depends on callback type. */
\r
467 } IotMqttCallbackParam_t;
\r
470 * @ingroup mqtt_datatypes_paramstructs
\r
471 * @brief Information on a user-provided MQTT callback function.
\r
473 * @paramfor @ref mqtt_function_subscribe, @ref mqtt_function_unsubscribe,
\r
474 * and @ref mqtt_function_publish. Cannot be used with #IOT_MQTT_FLAG_WAITABLE.
\r
476 * Provides a function to be invoked when an operation completes or when a
\r
477 * server-to-client PUBLISH is received.
\r
479 * @initializer{IotMqttCallbackInfo_t,IOT_MQTT_CALLBACK_INFO_INITIALIZER}
\r
481 * Below is an example for receiving an asynchronous notification on operation
\r
482 * completion. See @ref mqtt_function_subscribe for an example of using this struct
\r
483 * with for incoming PUBLISH messages.
\r
486 * // Operation completion callback.
\r
487 * void operationComplete( void * pArgument, IotMqttCallbackParam_t * pOperation );
\r
489 * // Callback information.
\r
490 * IotMqttCallbackInfo_t callbackInfo = IOT_MQTT_CALLBACK_INFO_INITIALIZER;
\r
491 * callbackInfo.function = operationComplete;
\r
493 * // Operation to wait for.
\r
494 * IotMqttError_t result = IotMqtt_Publish( &mqttConnection,
\r
500 * // Publish should have returned IOT_MQTT_STATUS_PENDING. Once a response
\r
501 * // is received, operationComplete is executed with the actual status passed
\r
502 * // in pOperation.
\r
505 typedef struct IotMqttCallbackInfo
\r
507 void * pCallbackContext; /**< @brief The first parameter to pass to the callback function to provide context. */
\r
510 * @brief User-provided callback function signature.
\r
512 * @param[in] void * #IotMqttCallbackInfo_t.pCallbackContext
\r
513 * @param[in] IotMqttCallbackParam_t * Details on the outcome of the MQTT operation
\r
514 * or an incoming MQTT PUBLISH.
\r
516 * @see #IotMqttCallbackParam_t for more information on the second parameter.
\r
518 void ( * function )( void *,
\r
519 IotMqttCallbackParam_t * );
\r
520 } IotMqttCallbackInfo_t;
\r
523 * @ingroup mqtt_datatypes_paramstructs
\r
524 * @brief Information on an MQTT subscription.
\r
526 * @paramfor @ref mqtt_function_subscribe, @ref mqtt_function_unsubscribe
\r
528 * An array of these is passed to @ref mqtt_function_subscribe and @ref
\r
529 * mqtt_function_unsubscribe. However, #IotMqttSubscription_t.callback and
\r
530 * and #IotMqttSubscription_t.qos are ignored by @ref mqtt_function_unsubscribe.
\r
532 * @initializer{IotMqttSubscription_t,IOT_MQTT_SUBSCRIPTION_INITIALIZER}
\r
534 * @note The lengths of the strings in this struct should not include the NULL
\r
535 * terminator. Strings in this struct do not need to be NULL-terminated.
\r
536 * @see #IotMqttCallbackInfo_t for details on setting a callback function.
\r
538 typedef struct IotMqttSubscription
\r
541 * @brief QoS of messages delivered on subscription.
\r
543 * Must be `0` or `1`. Ignored by @ref mqtt_function_unsubscribe.
\r
547 const char * pTopicFilter; /**< @brief Topic filter of subscription. */
\r
548 uint16_t topicFilterLength; /**< @brief Length of #IotMqttSubscription_t.pTopicFilter. */
\r
551 * @brief Callback to invoke when a message is received.
\r
553 * See #IotMqttCallbackInfo_t. Ignored by @ref mqtt_function_unsubscribe.
\r
555 IotMqttCallbackInfo_t callback;
\r
556 } IotMqttSubscription_t;
\r
559 * @ingroup mqtt_datatypes_paramstructs
\r
560 * @brief Information on a new MQTT connection.
\r
562 * @paramfor @ref mqtt_function_connect
\r
564 * Passed as an argument to @ref mqtt_function_connect. Most members of this struct
\r
565 * correspond to the content of an [MQTT CONNECT packet.]
\r
566 * (http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/csprd02/mqtt-v3.1.1-csprd02.html#_Toc385349764)
\r
568 * @initializer{IotMqttConnectInfo_t,IOT_MQTT_CONNECT_INFO_INITIALIZER}
\r
570 * @note The lengths of the strings in this struct should not include the NULL
\r
571 * terminator. Strings in this struct do not need to be NULL-terminated.
\r
573 typedef struct IotMqttConnectInfo
\r
576 * @brief Specifies if this MQTT connection is to an AWS IoT MQTT server.
\r
578 * The AWS IoT MQTT broker [differs somewhat from the MQTT specification.]
\r
579 * (https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html)
\r
580 * When this member is `true`, the MQTT library will accommodate these
\r
581 * differences. This setting should be `false` when communicating with a
\r
582 * fully-compliant MQTT broker.
\r
584 * @attention This setting <b>MUST</b> be `true` when using the AWS IoT MQTT
\r
585 * server; it <b>MUST</b> be `false` otherwise.
\r
586 * @note Currently, @ref IOT_MQTT_CONNECT_INFO_INITIALIZER sets this
\r
587 * this member to `true`.
\r
589 bool awsIotMqttMode;
\r
592 * @brief Whether this connection is a clean session.
\r
594 * MQTT servers can maintain and topic filter subscriptions and unacknowledged
\r
595 * PUBLISH messages. These form part of an <i>MQTT session</i>, which is identified by
\r
596 * the [client identifier](@ref IotMqttConnectInfo_t.pClientIdentifier).
\r
598 * Setting this value to `true` establishes a <i>clean session</i>, which causes
\r
599 * the MQTT server to discard any previous session data for a client identifier.
\r
600 * When the client disconnects, the server discards all session data. If this
\r
601 * value is `true`, #IotMqttConnectInfo_t.pPreviousSubscriptions and
\r
602 * #IotMqttConnectInfo_t.previousSubscriptionCount are ignored.
\r
604 * Setting this value to `false` does one of the following:
\r
605 * - If no previous session exists, the MQTT server will create a new
\r
606 * <i>persistent session</i>. The server may maintain subscriptions and
\r
607 * unacknowledged PUBLISH messages after a client disconnects, to be restored
\r
608 * once the same client identifier reconnects.
\r
609 * - If a previous session exists, the MQTT server restores all of the session's
\r
610 * subscriptions for the client identifier and may immediately transmit any
\r
611 * unacknowledged PUBLISH packets to the client.
\r
613 * When a client with a persistent session disconnects, the MQTT server
\r
614 * continues to maintain all subscriptions and unacknowledged PUBLISH messages.
\r
615 * The client must also remember the session subscriptions to restore them
\r
616 * upon reconnecting. #IotMqttConnectInfo_t.pPreviousSubscriptions and
\r
617 * #IotMqttConnectInfo_t.previousSubscriptionCount are used to restore a
\r
618 * previous session's subscriptions client-side.
\r
623 * @brief An array of MQTT subscriptions present in a previous session, if any.
\r
625 * Pointer to the start of an array of subscriptions present a previous session,
\r
626 * if any. These subscriptions will be immediately restored upon reconnecting.
\r
628 * This member is ignored if it is `NULL` or #IotMqttConnectInfo_t.cleanSession
\r
629 * is `true`. If this member is not `NULL`, #IotMqttConnectInfo_t.previousSubscriptionCount
\r
632 const IotMqttSubscription_t * pPreviousSubscriptions;
\r
635 * @brief The number of MQTT subscriptions present in a previous session, if any.
\r
637 * Number of subscriptions contained in the array
\r
638 * #IotMqttConnectInfo_t.pPreviousSubscriptions.
\r
640 * This value is ignored if #IotMqttConnectInfo_t.pPreviousSubscriptions
\r
641 * is `NULL` or #IotMqttConnectInfo_t.cleanSession is `true`. If
\r
642 * #IotMqttConnectInfo_t.pPreviousSubscriptions is not `NULL`, this value
\r
645 size_t previousSubscriptionCount;
\r
648 * @brief A message to publish if the new MQTT connection is unexpectedly closed.
\r
650 * A Last Will and Testament (LWT) message may be published if this connection is
\r
651 * closed without sending an MQTT DISCONNECT packet. This pointer should be set to
\r
652 * an #IotMqttPublishInfo_t representing any LWT message to publish. If an LWT
\r
653 * is not needed, this member must be set to `NULL`.
\r
655 * Unlike other PUBLISH messages, an LWT message is limited to 65535 bytes in
\r
656 * length. Additionally, [pWillInfo->retryMs](@ref IotMqttPublishInfo_t.retryMs)
\r
657 * and [pWillInfo->retryLimit](@ref IotMqttPublishInfo_t.retryLimit) will
\r
660 const IotMqttPublishInfo_t * pWillInfo;
\r
662 uint16_t keepAliveSeconds; /**< @brief Period of keep-alive messages. Set to 0 to disable keep-alive. */
\r
664 const char * pClientIdentifier; /**< @brief MQTT client identifier. */
\r
665 uint16_t clientIdentifierLength; /**< @brief Length of #IotMqttConnectInfo_t.pClientIdentifier. */
\r
667 /* These credentials are not used by AWS IoT and may be ignored if
\r
668 * awsIotMqttMode is true. */
\r
669 const char * pUserName; /**< @brief Username for MQTT connection. */
\r
670 uint16_t userNameLength; /**< @brief Length of #IotMqttConnectInfo_t.pUserName. */
\r
671 const char * pPassword; /**< @brief Password for MQTT connection. */
\r
672 uint16_t passwordLength; /**< @brief Length of #IotMqttConnectInfo_t.pPassword. */
\r
673 } IotMqttConnectInfo_t;
\r
675 #if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1
\r
678 * @cond DOXYGEN_IGNORE
\r
679 * Doxygen should ignore this section.
\r
681 * Forward declaration of the internal MQTT packet structure.
\r
683 struct _mqttPacket;
\r
687 * @ingroup mqtt_datatypes_paramstructs
\r
688 * @brief Function pointers for MQTT packet serializer overrides.
\r
690 * These function pointers allow the MQTT serialization and deserialization functions
\r
691 * to be overridden for an MQTT connection. The compile-time setting
\r
692 * @ref IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES must be `1` to enable this functionality.
\r
693 * See the #IotMqttSerializer_t::serialize and #IotMqttSerializer_t::deserialize
\r
694 * members for a list of functions that can be overridden. In addition, the functions
\r
695 * for freeing packets and determining the packet type can also be overridden. If
\r
696 * @ref IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES is `1`, the serializer initialization and
\r
697 * cleanup functions may be extended. See documentation of
\r
698 * @ref IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES for more information.
\r
700 * If any function pointers that are `NULL`, then the default implementation of that
\r
701 * function will be used.
\r
703 typedef struct IotMqttSerializer
\r
706 * @brief Get the MQTT packet type from a stream of bytes off the network.
\r
708 * @param[in] pNetworkConnection Reference to the network connection.
\r
709 * @param[in] pNetworkInterface Function pointers used to interact with the
\r
712 * <b>Default implementation:</b> #_IotMqtt_GetPacketType
\r
714 uint8_t ( * getPacketType )( void * /* pNetworkConnection */,
\r
715 const IotNetworkInterface_t * /* pNetworkInterface */ );
\r
718 * @brief Get the remaining length from a stream of bytes off the network.
\r
720 * @param[in] pNetworkConnection Reference to the network connection.
\r
721 * @param[in] pNetworkInterface Function pointers used to interact with the
\r
724 * <b>Default implementation:</b> #_IotMqtt_GetRemainingLength
\r
726 size_t ( * getRemainingLength )( void * pNetworkConnection,
\r
727 const IotNetworkInterface_t * pNetworkInterface );
\r
730 * @brief Free a packet generated by the serializer.
\r
732 * This function pointer must be set if any other serializer override is set.
\r
733 * @param[in] uint8_t* The packet to free.
\r
735 * <b>Default implementation:</b> #_IotMqtt_FreePacket
\r
737 void ( * freePacket )( uint8_t * /* pPacket */ );
\r
742 * @brief CONNECT packet serializer function.
\r
743 * @param[in] IotMqttConnectInfo_t* User-provided CONNECT information.
\r
744 * @param[out] uint8_t** Where the CONNECT packet is written.
\r
745 * @param[out] size_t* Size of the CONNECT packet.
\r
747 * <b>Default implementation:</b> #_IotMqtt_SerializeConnect
\r
749 IotMqttError_t ( * connect )( const IotMqttConnectInfo_t * /* pConnectInfo */,
\r
750 uint8_t ** /* pConnectPacket */,
\r
751 size_t * /* pPacketSize */ );
\r
754 * @brief PUBLISH packet serializer function.
\r
755 * @param[in] IotMqttPublishInfo_t* User-provided PUBLISH information.
\r
756 * @param[out] uint8_t** Where the PUBLISH packet is written.
\r
757 * @param[out] size_t* Size of the PUBLISH packet.
\r
758 * @param[out] uint16_t* The packet identifier generated for this PUBLISH.
\r
759 * @param[out] uint8_t** Where the high byte of the packet identifier
\r
762 * <b>Default implementation:</b> #_IotMqtt_SerializePublish
\r
764 IotMqttError_t ( * publish )( const IotMqttPublishInfo_t * /* pPublishInfo */,
\r
765 uint8_t ** /* pPublishPacket */,
\r
766 size_t * /* pPacketSize */,
\r
767 uint16_t * /* pPacketIdentifier */,
\r
768 uint8_t ** /* pPacketIdentifierHigh */ );
\r
771 * @brief Set the `DUP` bit in a QoS `1` PUBLISH packet.
\r
772 * @param[in] uint8_t* Pointer to the PUBLISH packet to modify.
\r
773 * @param[in] uint8_t* The high byte of any packet identifier to modify.
\r
774 * @param[out] uint16_t* New packet identifier (AWS IoT MQTT mode only).
\r
776 * <b>Default implementation:</b> #_IotMqtt_PublishSetDup
\r
778 void ( *publishSetDup )( uint8_t * /* pPublishPacket */,
\r
779 uint8_t * /* pPacketIdentifierHigh */,
\r
780 uint16_t * /* pNewPacketIdentifier */ );
\r
783 * @brief PUBACK packet serializer function.
\r
784 * @param[in] uint16_t The packet identifier to place in PUBACK.
\r
785 * @param[out] uint8_t** Where the PUBACK packet is written.
\r
786 * @param[out] size_t* Size of the PUBACK packet.
\r
788 * <b>Default implementation:</b> #_IotMqtt_SerializePuback
\r
790 IotMqttError_t ( * puback )( uint16_t /* packetIdentifier */,
\r
791 uint8_t ** /* pPubackPacket */,
\r
792 size_t * /* pPacketSize */ );
\r
795 * @brief SUBSCRIBE packet serializer function.
\r
796 * @param[in] IotMqttSubscription_t* User-provided array of subscriptions.
\r
797 * @param[in] size_t Number of elements in the subscription array.
\r
798 * @param[out] uint8_t** Where the SUBSCRIBE packet is written.
\r
799 * @param[out] size_t* Size of the SUBSCRIBE packet.
\r
800 * @param[out] uint16_t* The packet identifier generated for this SUBSCRIBE.
\r
802 * <b>Default implementation:</b> #_IotMqtt_SerializeSubscribe
\r
804 IotMqttError_t ( * subscribe )( const IotMqttSubscription_t * /* pSubscriptionList */,
\r
805 size_t /* subscriptionCount */,
\r
806 uint8_t ** /* pSubscribePacket */,
\r
807 size_t * /* pPacketSize */,
\r
808 uint16_t * /* pPacketIdentifier */ );
\r
811 * @brief UNSUBSCRIBE packet serializer function.
\r
812 * @param[in] IotMqttSubscription_t* User-provided array of subscriptions to remove.
\r
813 * @param[in] size_t Number of elements in the subscription array.
\r
814 * @param[out] uint8_t** Where the UNSUBSCRIBE packet is written.
\r
815 * @param[out] size_t* Size of the UNSUBSCRIBE packet.
\r
816 * @param[out] uint16_t* The packet identifier generated for this UNSUBSCRIBE.
\r
818 * <b>Default implementation:</b> #_IotMqtt_SerializeUnsubscribe
\r
820 IotMqttError_t ( * unsubscribe )( const IotMqttSubscription_t * /* pSubscriptionList */,
\r
821 size_t /* subscriptionCount */,
\r
822 uint8_t ** /* pUnsubscribePacket */,
\r
823 size_t * /* pPacketSize */,
\r
824 uint16_t * /* pPacketIdentifier */ );
\r
827 * @brief PINGREQ packet serializer function.
\r
828 * @param[out] uint8_t** Where the PINGREQ packet is written.
\r
829 * @param[out] size_t* Size of the PINGREQ packet.
\r
831 * <b>Default implementation:</b> #_IotMqtt_SerializePingreq
\r
833 IotMqttError_t ( * pingreq )( uint8_t ** /* pPingreqPacket */,
\r
834 size_t * /* pPacketSize */ );
\r
837 * @brief DISCONNECT packet serializer function.
\r
838 * @param[out] uint8_t** Where the DISCONNECT packet is written.
\r
839 * @param[out] size_t* Size of the DISCONNECT packet.
\r
841 * <b>Default implementation:</b> #_IotMqtt_SerializeDisconnect
\r
843 IotMqttError_t ( * disconnect )( uint8_t ** /* pDisconnectPacket */,
\r
844 size_t * /* pPacketSize */ );
\r
845 } serialize; /**< @brief Overrides the packet serialization functions for a single connection. */
\r
850 * @brief CONNACK packet deserializer function.
\r
851 * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing a CONNACK.
\r
853 * <b>Default implementation:</b> #_IotMqtt_DeserializeConnack
\r
855 IotMqttError_t ( * connack )( struct _mqttPacket * /* pConnack */ );
\r
858 * @brief PUBLISH packet deserializer function.
\r
859 * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing a PUBLISH.
\r
861 * <b>Default implementation:</b> #_IotMqtt_DeserializePublish
\r
863 IotMqttError_t ( * publish )( struct _mqttPacket * /* pPublish */ );
\r
866 * @brief PUBACK packet deserializer function.
\r
867 * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing a PUBACK.
\r
869 * <b>Default implementation:</b> #_IotMqtt_DeserializePuback
\r
871 IotMqttError_t ( * puback )( struct _mqttPacket * pPuback );
\r
874 * @brief SUBACK packet deserializer function.
\r
875 * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing a SUBACK.
\r
877 * <b>Default implementation:</b> #_IotMqtt_DeserializeSuback
\r
879 IotMqttError_t ( * suback )( struct _mqttPacket * /* pSuback */ );
\r
882 * @brief UNSUBACK packet deserializer function.
\r
883 * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing an UNSUBACK.
\r
885 * <b>Default implementation:</b> #_IotMqtt_DeserializeUnsuback
\r
887 IotMqttError_t ( * unsuback )( struct _mqttPacket * /* pUnsuback */ );
\r
890 * @brief PINGRESP packet deserializer function.
\r
891 * @param[in,out] _mqttPacket* Pointer to an MQTT packet struct representing a PINGRESP.
\r
893 * <b>Default implementation:</b> #_IotMqtt_DeserializePingresp
\r
895 IotMqttError_t ( * pingresp )( struct _mqttPacket * /* pPingresp */ );
\r
896 } deserialize; /**< @brief Overrides the packet deserialization functions for a single connection. */
\r
897 } IotMqttSerializer_t;
\r
898 #else /* if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1 */
\r
900 /* When MQTT packet serializer overrides are disabled, this struct is an
\r
901 * incomplete type. */
\r
902 typedef struct IotMqttSerializer IotMqttSerializer_t;
\r
904 #endif /* if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1 */
\r
907 * @ingroup mqtt_datatypes_paramstructs
\r
908 * @brief Infomation on the transport-layer network connection for the new MQTT
\r
911 * @paramfor @ref mqtt_function_connect
\r
913 * The MQTT library needs to be able to send and receive data over a network.
\r
914 * This struct provides an interface for interacting with the network.
\r
916 * @initializer{IotMqttNetworkInfo_t,IOT_MQTT_NETWORK_INFO_INITIALIZER}
\r
918 typedef struct IotMqttNetworkInfo
\r
921 * @brief Whether a new network connection should be created.
\r
923 * When this value is `true`, a new transport-layer network connection will
\r
924 * be created along with the MQTT connection. #IotMqttNetworkInfo_t::pNetworkServerInfo
\r
925 * and #IotMqttNetworkInfo_t::pNetworkCredentialInfo are valid when this value
\r
928 * When this value is `false`, the MQTT connection will use a transport-layer
\r
929 * network connection that has already been established. The MQTT library will
\r
930 * still set the appropriate receive callback even if the network connection
\r
931 * has been established.
\r
932 * #IotMqttNetworkInfo_t::pNetworkConnection, which represents an established
\r
933 * network connection, is valid when this value is `false`.
\r
935 bool createNetworkConnection;
\r
942 * @brief Information on the MQTT server, passed as `pConnectionInfo` to
\r
943 * #IotNetworkInterface_t::create.
\r
945 * This member is opaque to the MQTT library. It is passed to the network
\r
946 * interface when creating a new network connection. It is only valid when
\r
947 * #IotMqttNetworkInfo_t::createNetworkConnection is `true`.
\r
949 void * pNetworkServerInfo;
\r
952 * @brief Credentials for the MQTT server, passed as `pCredentialInfo` to
\r
953 * #IotNetworkInterface_t::create.
\r
955 * This member is opaque to the MQTT library. It is passed to the network
\r
956 * interface when creating a new network connection. It is only valid when
\r
957 * #IotMqttNetworkInfo_t::createNetworkConnection is `true`.
\r
959 void * pNetworkCredentialInfo;
\r
963 * @brief An established transport-layer network connection.
\r
965 * This member is opaque to the MQTT library. It is passed to the network
\r
966 * interface to reference an established network connection. It is only
\r
967 * valid when #IotMqttNetworkInfo_t::createNetworkConnection is `false`.
\r
969 void * pNetworkConnection;
\r
970 } u /**< @brief Valid member depends of IotMqttNetworkInfo_t.createNetworkConnection. */;
\r
973 * @brief The network functions used by the new MQTT connection.
\r
975 * @attention The function pointers of the network interface must remain valid
\r
976 * for the lifetime of the MQTT connection.
\r
978 const IotNetworkInterface_t * pNetworkInterface;
\r
981 * @brief A callback function to invoke when this MQTT connection is disconnected.
\r
983 IotMqttCallbackInfo_t disconnectCallback;
\r
985 #if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1
\r
988 * @brief MQTT packet serializer overrides used by the new MQTT connection.
\r
990 * @attention The function pointers of the MQTT serializer overrides must
\r
991 * remain valid for the lifetime of the MQTT connection.
\r
993 const IotMqttSerializer_t * pMqttSerializer;
\r
995 } IotMqttNetworkInfo_t;
\r
997 /*------------------------- MQTT defined constants --------------------------*/
\r
1000 * @constantspage{mqtt,MQTT library}
\r
1002 * @section mqtt_constants_initializers MQTT Initializers
\r
1003 * @brief Provides default values for the data types of the MQTT library.
\r
1005 * @snippet this define_mqtt_initializers
\r
1007 * All user-facing data types of the MQTT library should be initialized using
\r
1008 * one of the following.
\r
1010 * @warning Failing to initialize an MQTT data type with the appropriate initializer
\r
1011 * may result in undefined behavior!
\r
1012 * @note The initializers may change at any time in future versions, but their
\r
1013 * names will remain the same.
\r
1017 * IotMqttNetworkInfo_t networkInfo = IOT_MQTT_NETWORK_INFO_INITIALIZER;
\r
1018 * IotMqttSerializer_t serializer = IOT_MQTT_SERIALIZER_INITIALIZER;
\r
1019 * IotMqttConnectInfo_t connectInfo = IOT_MQTT_CONNECT_INFO_INITIALIZER;
\r
1020 * IotMqttPublishInfo_t publishInfo = IOT_MQTT_PUBLISH_INFO_INITIALIZER;
\r
1021 * IotMqttSubscription_t subscription = IOT_MQTT_SUBSCRIPTION_INITIALIZER;
\r
1022 * IotMqttCallbackInfo_t callbackInfo = IOT_MQTT_CALLBACK_INFO_INITIALIZER;
\r
1023 * IotMqttConnection_t connection = IOT_MQTT_CONNECTION_INITIALIZER;
\r
1024 * IotMqttOperation_t operation = IOT_MQTT_OPERATION_INITIALIZER;
\r
1027 * @section mqtt_constants_flags MQTT Function Flags
\r
1028 * @brief Flags that modify the behavior of MQTT library functions.
\r
1029 * - #IOT_MQTT_FLAG_WAITABLE <br>
\r
1030 * @copybrief IOT_MQTT_FLAG_WAITABLE
\r
1031 * - #IOT_MQTT_FLAG_CLEANUP_ONLY <br>
\r
1032 * @copybrief IOT_MQTT_FLAG_CLEANUP_ONLY
\r
1034 * Flags should be bitwise-ORed with each other to change the behavior of
\r
1035 * @ref mqtt_function_subscribe, @ref mqtt_function_unsubscribe,
\r
1036 * @ref mqtt_function_publish, or @ref mqtt_function_disconnect.
\r
1038 * @note The values of the flags may change at any time in future versions, but
\r
1039 * their names will remain the same. Additionally, flags that may be used together
\r
1040 * will be bitwise-exclusive of each other.
\r
1043 /* @[define_mqtt_initializers] */
\r
1044 /** @brief Initializer for #IotMqttNetworkInfo_t. */
\r
1045 #define IOT_MQTT_NETWORK_INFO_INITIALIZER { .createNetworkConnection = true }
\r
1046 /** @brief Initializer for #IotMqttSerializer_t. */
\r
1047 #define IOT_MQTT_SERIALIZER_INITIALIZER { 0 }
\r
1048 /** @brief Initializer for #IotMqttConnectInfo_t. */
\r
1049 #define IOT_MQTT_CONNECT_INFO_INITIALIZER { .cleanSession = true }
\r
1050 /** @brief Initializer for #IotMqttPublishInfo_t. */
\r
1051 #define IOT_MQTT_PUBLISH_INFO_INITIALIZER { .qos = IOT_MQTT_QOS_0 }
\r
1052 /** @brief Initializer for #IotMqttSubscription_t. */
\r
1053 #define IOT_MQTT_SUBSCRIPTION_INITIALIZER { .qos = IOT_MQTT_QOS_0 }
\r
1054 /** @brief Initializer for #IotMqttCallbackInfo_t. */
\r
1055 #define IOT_MQTT_CALLBACK_INFO_INITIALIZER { 0 }
\r
1056 /** @brief Initializer for #IotMqttConnection_t. */
\r
1057 #define IOT_MQTT_CONNECTION_INITIALIZER NULL
\r
1058 /** @brief Initializer for #IotMqttOperation_t. */
\r
1059 #define IOT_MQTT_OPERATION_INITIALIZER NULL
\r
1060 /* @[define_mqtt_initializers] */
\r
1063 * @brief Allows the use of @ref mqtt_function_wait for blocking until completion.
\r
1065 * This flag is always valid for @ref mqtt_function_subscribe and
\r
1066 * @ref mqtt_function_unsubscribe. If passed to @ref mqtt_function_publish,
\r
1067 * the parameter [pPublishInfo->qos](@ref IotMqttPublishInfo_t.qos) must not be `0`.
\r
1069 * An #IotMqttOperation_t <b>MUST</b> be provided if this flag is set. Additionally, an
\r
1070 * #IotMqttCallbackInfo_t <b>MUST NOT</b> be provided.
\r
1072 * @note If this flag is set, @ref mqtt_function_wait <b>MUST</b> be called to clean up
\r
1075 #define IOT_MQTT_FLAG_WAITABLE ( 0x00000001 )
\r
1078 * @brief Causes @ref mqtt_function_disconnect to only free memory and not send
\r
1079 * an MQTT DISCONNECT packet.
\r
1081 * This flag is only valid for @ref mqtt_function_disconnect. It should be passed
\r
1082 * to @ref mqtt_function_disconnect if the network goes offline or is otherwise
\r
1085 #define IOT_MQTT_FLAG_CLEANUP_ONLY ( 0x00000001 )
\r
1087 #endif /* ifndef IOT_MQTT_TYPES_H_ */
\r