Line data Source code
1 1 : /*
2 : * Copyright (c) 2018 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /** @file mqtt.h
8 : *
9 : * @brief MQTT Client Implementation
10 : *
11 : * @note The implementation assumes TCP module is enabled.
12 : *
13 : * @note By default the implementation uses MQTT version 3.1.1.
14 : *
15 : * @defgroup mqtt_socket MQTT Client library
16 : * @since 1.14
17 : * @version 0.8.0
18 : * @ingroup networking
19 : * @{
20 : */
21 :
22 : #ifndef ZEPHYR_INCLUDE_NET_MQTT_H_
23 : #define ZEPHYR_INCLUDE_NET_MQTT_H_
24 :
25 : #include <stddef.h>
26 :
27 : #include <zephyr/kernel.h>
28 : #include <zephyr/types.h>
29 : #include <zephyr/net/tls_credentials.h>
30 : #include <zephyr/net/net_ip.h>
31 : #include <zephyr/sys/mutex.h>
32 : #include <zephyr/net/websocket.h>
33 :
34 : #ifdef __cplusplus
35 : extern "C" {
36 : #endif
37 :
38 : /**
39 : * @brief MQTT Asynchronous Events notified to the application from the module
40 : * through the callback registered by the application.
41 : */
42 1 : enum mqtt_evt_type {
43 : /** Acknowledgment of connection request. Event result accompanying
44 : * the event indicates whether the connection failed or succeeded.
45 : */
46 : MQTT_EVT_CONNACK,
47 :
48 : /** Disconnection Event. MQTT Client Reference is no longer valid once
49 : * this event is received for the client.
50 : */
51 : MQTT_EVT_DISCONNECT,
52 :
53 : /** Publish event received when message is published on a topic client
54 : * is subscribed to.
55 : *
56 : * @note PUBLISH event structure only contains payload size, the payload
57 : * data parameter should be ignored. Payload content has to be
58 : * read manually with @ref mqtt_read_publish_payload function.
59 : */
60 : MQTT_EVT_PUBLISH,
61 :
62 : /** Acknowledgment for published message with QoS 1. */
63 : MQTT_EVT_PUBACK,
64 :
65 : /** Reception confirmation for published message with QoS 2. */
66 : MQTT_EVT_PUBREC,
67 :
68 : /** Release of published message with QoS 2. */
69 : MQTT_EVT_PUBREL,
70 :
71 : /** Confirmation to a publish release message with QoS 2. */
72 : MQTT_EVT_PUBCOMP,
73 :
74 : /** Acknowledgment to a subscribe request. */
75 : MQTT_EVT_SUBACK,
76 :
77 : /** Acknowledgment to a unsubscribe request. */
78 : MQTT_EVT_UNSUBACK,
79 :
80 : /** Ping Response from server. */
81 : MQTT_EVT_PINGRESP,
82 :
83 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
84 : /** Authentication packet received from server. MQTT 5.0 only. */
85 : MQTT_EVT_AUTH,
86 : #endif /* CONFIG_MQTT_VERSION_5_0 */
87 : };
88 :
89 : /** @brief MQTT version protocol level. */
90 1 : enum mqtt_version {
91 : MQTT_VERSION_3_1_0 = 3, /**< Protocol level for 3.1.0. */
92 : MQTT_VERSION_3_1_1 = 4, /**< Protocol level for 3.1.1. */
93 : MQTT_VERSION_5_0 = 5, /**< Protocol level for 5.0. */
94 : };
95 :
96 : /** @brief MQTT Quality of Service types. */
97 1 : enum mqtt_qos {
98 : /** Lowest Quality of Service, no acknowledgment needed for published
99 : * message.
100 : */
101 : MQTT_QOS_0_AT_MOST_ONCE = 0x00,
102 :
103 : /** Medium Quality of Service, if acknowledgment expected for published
104 : * message, duplicate messages permitted.
105 : */
106 : MQTT_QOS_1_AT_LEAST_ONCE = 0x01,
107 :
108 : /** Highest Quality of Service, acknowledgment expected and message
109 : * shall be published only once. Message not published to interested
110 : * parties unless client issues a PUBREL.
111 : */
112 : MQTT_QOS_2_EXACTLY_ONCE = 0x02
113 : };
114 :
115 : /** @brief MQTT 3.1 CONNACK return codes. */
116 1 : enum mqtt_conn_return_code {
117 : /** Connection accepted. */
118 : MQTT_CONNECTION_ACCEPTED = 0x00,
119 :
120 : /** The Server does not support the level of the MQTT protocol
121 : * requested by the Client.
122 : */
123 : MQTT_UNACCEPTABLE_PROTOCOL_VERSION = 0x01,
124 :
125 : /** The Client identifier is correct UTF-8 but not allowed by the
126 : * Server.
127 : */
128 : MQTT_IDENTIFIER_REJECTED = 0x02,
129 :
130 : /** The Network Connection has been made but the MQTT service is
131 : * unavailable.
132 : */
133 : MQTT_SERVER_UNAVAILABLE = 0x03,
134 :
135 : /** The data in the user name or password is malformed. */
136 : MQTT_BAD_USER_NAME_OR_PASSWORD = 0x04,
137 :
138 : /** The Client is not authorized to connect. */
139 : MQTT_NOT_AUTHORIZED = 0x05
140 : };
141 :
142 : /** @brief MQTT 5.0 CONNACK reason codes (MQTT 5.0, chapter 3.2.2.2). */
143 0 : enum mqtt_connack_reason_code {
144 : MQTT_CONNACK_SUCCESS = 0,
145 : MQTT_CONNACK_UNSPECIFIED_ERROR = 128,
146 : MQTT_CONNACK_MALFORMED_PACKET = 129,
147 : MQTT_CONNACK_PROTOCOL_ERROR = 130,
148 : MQTT_CONNACK_IMPL_SPECIFIC_ERROR = 131,
149 : MQTT_CONNACK_UNSUPPORTED_PROTO_ERROR = 132,
150 : MQTT_CONNACK_CLIENT_ID_NOT_VALID = 133,
151 : MQTT_CONNACK_BAD_USERNAME_OR_PASS = 134,
152 : MQTT_CONNACK_NOT_AUTHORIZED = 135,
153 : MQTT_CONNACK_SERVER_UNAVAILABLE = 136,
154 : MQTT_CONNACK_SERVER_BUSY = 137,
155 : MQTT_CONNACK_BANNED = 138,
156 : MQTT_CONNACK_BAD_AUTH_METHOD = 140,
157 : MQTT_CONNACK_TOPIC_NAME_INVALID = 144,
158 : MQTT_CONNACK_PACKET_TOO_LARGE = 149,
159 : MQTT_CONNACK_QUOTA_EXCEEDED = 151,
160 : MQTT_CONNACK_PAYLOAD_FORMAT_INVALID = 153,
161 : MQTT_CONNACK_RETAIN_NOT_SUPPORTED = 154,
162 : MQTT_CONNACK_QOS_NOT_SUPPORTED = 155,
163 : MQTT_CONNACK_USE_ANOTHER_SERVER = 156,
164 : MQTT_CONNACK_SERVER_MOVED = 157,
165 : MQTT_CONNACK_CONNECTION_RATE_EXCEEDED = 159,
166 : };
167 :
168 : /** @brief MQTT SUBACK return codes. */
169 1 : enum mqtt_suback_return_code {
170 : /** Subscription with QoS 0 succeeded. */
171 : MQTT_SUBACK_SUCCESS_QoS_0 = 0x00,
172 :
173 : /** Subscription with QoS 1 succeeded. */
174 : MQTT_SUBACK_SUCCESS_QoS_1 = 0x01,
175 :
176 : /** Subscription with QoS 2 succeeded. */
177 : MQTT_SUBACK_SUCCESS_QoS_2 = 0x02,
178 :
179 : /** Subscription for a topic failed. */
180 : MQTT_SUBACK_FAILURE = 0x80
181 : };
182 :
183 : /** @brief MQTT Disconnect reason codes (MQTT 5.0, chapter 3.14.2.1). */
184 0 : enum mqtt_disconnect_reason_code {
185 : MQTT_DISCONNECT_NORMAL = 0,
186 : MQTT_DISCONNECT_WITH_WILL_MSG = 4,
187 : MQTT_DISCONNECT_UNSPECIFIED_ERROR = 128,
188 : MQTT_DISCONNECT_MALFORMED_PACKET = 129,
189 : MQTT_DISCONNECT_PROTOCOL_ERROR = 130,
190 : MQTT_DISCONNECT_IMPL_SPECIFIC_ERROR = 131,
191 : MQTT_DISCONNECT_NOT_AUTHORIZED = 135,
192 : MQTT_DISCONNECT_SERVER_BUSY = 137,
193 : MQTT_DISCONNECT_SERVER_SHUTTING_DOWN = 139,
194 : MQTT_DISCONNECT_KEEP_ALIVE_TIMEOUT = 141,
195 : MQTT_DISCONNECT_SESSION_TAKE_OVER = 142,
196 : MQTT_DISCONNECT_TOPIC_FILTER_INVALID = 143,
197 : MQTT_DISCONNECT_TOPIC_NAME_INVALID = 144,
198 : MQTT_DISCONNECT_RECV_MAX_EXCEEDED = 147,
199 : MQTT_DISCONNECT_TOPIC_ALIAS_INVALID = 148,
200 : MQTT_DISCONNECT_PACKET_TOO_LARGE = 149,
201 : MQTT_DISCONNECT_MESSAGE_RATE_TOO_HIGH = 150,
202 : MQTT_DISCONNECT_QUOTA_EXCEEDED = 151,
203 : MQTT_DISCONNECT_ADMIN_ACTION = 152,
204 : MQTT_DISCONNECT_PAYLOAD_FORMAT_INVALID = 153,
205 : MQTT_DISCONNECT_RETAIN_NOT_SUPPORTED = 154,
206 : MQTT_DISCONNECT_QOS_NOT_SUPPORTED = 155,
207 : MQTT_DISCONNECT_USE_ANOTHER_SERVER = 156,
208 : MQTT_DISCONNECT_SERVER_MOVED = 157,
209 : MQTT_DISCONNECT_SHARED_SUB_NOT_SUPPORTED = 158,
210 : MQTT_DISCONNECT_CONNECTION_RATE_EXCEEDED = 159,
211 : MQTT_DISCONNECT_MAX_CONNECT_TIME = 160,
212 : MQTT_DISCONNECT_SUB_ID_NOT_SUPPORTED = 161,
213 : MQTT_DISCONNECT_WILDCARD_SUB_NOT_SUPPORTED = 162,
214 : };
215 :
216 : /** @brief MQTT Authenticate reason codes (MQTT 5.0, chapter 3.15.2.1). */
217 0 : enum mqtt_auth_reason_code {
218 : MQTT_AUTH_SUCCESS = 0,
219 : MQTT_AUTH_CONTINUE_AUTHENTICATION = 24,
220 : MQTT_AUTH_RE_AUTHENTICATE = 25,
221 : };
222 :
223 : /** @brief Abstracts UTF-8 encoded strings. */
224 1 : struct mqtt_utf8 {
225 1 : const uint8_t *utf8; /**< Pointer to UTF-8 string. */
226 1 : uint32_t size; /**< Size of UTF string, in bytes. */
227 : };
228 :
229 : /**
230 : * @brief Initialize UTF-8 encoded string from C literal string.
231 : *
232 : * Use it as follows:
233 : *
234 : * struct mqtt_utf8 password = MQTT_UTF8_LITERAL("my_pass");
235 : *
236 : * @param[in] literal Literal string from which to generate mqtt_utf8 object.
237 : */
238 1 : #define MQTT_UTF8_LITERAL(literal) \
239 : ((struct mqtt_utf8) {literal, sizeof(literal) - 1})
240 :
241 : /** @brief Abstracts binary strings. */
242 1 : struct mqtt_binstr {
243 1 : uint8_t *data; /**< Pointer to binary stream. */
244 1 : uint32_t len; /**< Length of binary stream. */
245 : };
246 :
247 : /** @brief Abstracts aliased topic. */
248 1 : struct mqtt_topic_alias {
249 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
250 : /** UTF-8 encoded topic name. */
251 1 : uint8_t topic_buf[CONFIG_MQTT_TOPIC_ALIAS_STRING_MAX];
252 :
253 : /** Topic name size. */
254 1 : uint16_t topic_size;
255 : #endif /* CONFIG_MQTT_VERSION_5_0 */
256 : };
257 :
258 : /** @brief Abstracts MQTT UTF-8 encoded topic that can be subscribed
259 : * to or published.
260 : */
261 1 : struct mqtt_topic {
262 : /** Topic on to be published or subscribed to. */
263 1 : struct mqtt_utf8 topic;
264 :
265 : /** Quality of service requested for the subscription.
266 : * @ref mqtt_qos for details.
267 : */
268 1 : uint8_t qos;
269 : };
270 :
271 : /** @brief Abstracts MQTT UTF-8 encoded string pair.
272 : */
273 1 : struct mqtt_utf8_pair {
274 0 : struct mqtt_utf8 name;
275 0 : struct mqtt_utf8 value;
276 : };
277 :
278 : /** @brief Parameters for a publish message. */
279 1 : struct mqtt_publish_message {
280 1 : struct mqtt_topic topic; /**< Topic on which data was published. */
281 1 : struct mqtt_binstr payload; /**< Payload on the topic published. */
282 : };
283 :
284 : /** @brief Parameters for a connection acknowledgment (CONNACK). */
285 1 : struct mqtt_connack_param {
286 : /** The Session Present flag enables a Client to establish whether
287 : * the Client and Server have a consistent view about whether there
288 : * is already stored Session state.
289 : */
290 1 : uint8_t session_present_flag;
291 :
292 : /** The appropriate non-zero Connect return code indicates if the Server
293 : * is unable to process a connection request for some reason.
294 : * MQTT 3.1 - Return codes specified in @ref mqtt_conn_return_code
295 : * MQTT 5.0 - Reason codes specified in @ref mqtt_connack_reason_code
296 : */
297 1 : uint8_t return_code;
298 :
299 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
300 : struct {
301 : /** MQTT 5.0, chapter 3.2.2.3.10 User Property. */
302 1 : struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];
303 :
304 : /** MQTT 5.0, chapter 3.2.2.3.7 Assigned Client Identifier. */
305 1 : struct mqtt_utf8 assigned_client_id;
306 :
307 : /** MQTT 5.0, chapter 3.2.2.3.9 Reason String. */
308 1 : struct mqtt_utf8 reason_string;
309 :
310 : /** MQTT 5.0, chapter 3.2.2.3.15 Response Information. */
311 1 : struct mqtt_utf8 response_information;
312 :
313 : /** MQTT 5.0, chapter 3.2.2.3.16 Server Reference. */
314 1 : struct mqtt_utf8 server_reference;
315 :
316 : /** MQTT 5.0, chapter 3.2.2.3.17 Authentication Method. */
317 1 : struct mqtt_utf8 auth_method;
318 :
319 : /** MQTT 5.0, chapter 3.2.2.3.18 Authentication Data. */
320 1 : struct mqtt_binstr auth_data;
321 :
322 : /** MQTT 5.0, chapter 3.2.2.3.2 Session Expiry Interval. */
323 1 : uint32_t session_expiry_interval;
324 :
325 : /** MQTT 5.0, chapter 3.2.2.3.6 Maximum Packet Size. */
326 1 : uint32_t maximum_packet_size;
327 :
328 : /** MQTT 5.0, chapter 3.3.2.3.3 Receive Maximum. */
329 1 : uint16_t receive_maximum;
330 :
331 : /** MQTT 5.0, chapter 3.2.2.3.8 Topic Alias Maximum. */
332 1 : uint16_t topic_alias_maximum;
333 :
334 : /** MQTT 5.0, chapter 3.2.2.3.14 Server Keep Alive. */
335 1 : uint16_t server_keep_alive;
336 :
337 : /** MQTT 5.0, chapter 3.2.2.3.4 Maximum QoS. */
338 1 : uint8_t maximum_qos;
339 :
340 : /** MQTT 5.0, chapter 3.2.2.3.5 Retain Available. */
341 1 : uint8_t retain_available;
342 :
343 : /** MQTT 5.0, chapter 3.2.2.3.11 Wildcard Subscription Available. */
344 1 : uint8_t wildcard_sub_available;
345 :
346 : /** MQTT 5.0, chapter 3.2.2.3.12 Subscription Identifiers Available. */
347 1 : uint8_t subscription_ids_available;
348 :
349 : /** MQTT 5.0, chapter 3.2.2.3.13 Shared Subscription Available. */
350 1 : uint8_t shared_sub_available;
351 :
352 : /** Flags indicating whether given property was present in received packet. */
353 : struct {
354 : /** Session Expiry Interval property was present. */
355 1 : bool has_session_expiry_interval;
356 : /** Receive Maximum property was present. */
357 1 : bool has_receive_maximum;
358 : /** Maximum QoS property was present. */
359 1 : bool has_maximum_qos;
360 : /** Retain Available property was present. */
361 1 : bool has_retain_available;
362 : /** Maximum Packet Size property was present. */
363 1 : bool has_maximum_packet_size;
364 : /** Assigned Client Identifier property was present. */
365 1 : bool has_assigned_client_id;
366 : /** Topic Alias Maximum property was present. */
367 1 : bool has_topic_alias_maximum;
368 : /** Reason String property was present. */
369 1 : bool has_reason_string;
370 : /** User Property property was present. */
371 1 : bool has_user_prop;
372 : /** Wildcard Subscription Available property was present. */
373 1 : bool has_wildcard_sub_available;
374 : /** Subscription Identifiers Available property was present. */
375 1 : bool has_subscription_ids_available;
376 : /** Shared Subscription Available property was present. */
377 1 : bool has_shared_sub_available;
378 : /** Server Keep Alive property was present. */
379 1 : bool has_server_keep_alive;
380 : /** Response Information property was present. */
381 1 : bool has_response_information;
382 : /** Server Reference property was present. */
383 1 : bool has_server_reference;
384 : /** Authentication Method property was present. */
385 1 : bool has_auth_method;
386 : /** Authentication Data property was present. */
387 1 : bool has_auth_data;
388 1 : } rx;
389 0 : } prop;
390 : #endif /* CONFIG_MQTT_VERSION_5_0 */
391 : };
392 :
393 : /** @brief Common MQTT 5.0 properties shared across all ack-type messages. */
394 1 : struct mqtt_common_ack_properties {
395 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
396 : /** MQTT 5.0, chapter 3.4.2.2.3 User Property. */
397 1 : struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];
398 :
399 : /** MQTT 5.0, chapter 3.4.2.2.2 Reason String. */
400 1 : struct mqtt_utf8 reason_string;
401 :
402 : /** Flags indicating whether given property was present in received packet. */
403 : struct {
404 : /** Reason String property was present. */
405 1 : bool has_reason_string;
406 : /** User Property property was present. */
407 1 : bool has_user_prop;
408 1 : } rx;
409 : #endif /* CONFIG_MQTT_VERSION_5_0 */
410 : };
411 :
412 : /** @brief Parameters for MQTT publish acknowledgment (PUBACK). */
413 1 : struct mqtt_puback_param {
414 : /** Message id of the PUBLISH message being acknowledged */
415 1 : uint16_t message_id;
416 :
417 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
418 : /** MQTT 5.0 reason code. */
419 1 : uint8_t reason_code;
420 :
421 : /** MQTT 5.0 properties. */
422 1 : struct mqtt_common_ack_properties prop;
423 : #endif /* CONFIG_MQTT_VERSION_5_0 */
424 : };
425 :
426 : /** @brief Parameters for MQTT publish receive (PUBREC). */
427 1 : struct mqtt_pubrec_param {
428 : /** Message id of the PUBLISH message being acknowledged */
429 1 : uint16_t message_id;
430 :
431 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
432 : /** MQTT 5.0 reason code. */
433 1 : uint8_t reason_code;
434 :
435 : /** MQTT 5.0 properties. */
436 1 : struct mqtt_common_ack_properties prop;
437 : #endif /* CONFIG_MQTT_VERSION_5_0 */
438 : };
439 :
440 : /** @brief Parameters for MQTT publish release (PUBREL). */
441 1 : struct mqtt_pubrel_param {
442 : /** Message id of the PUBREC message being acknowledged */
443 1 : uint16_t message_id;
444 :
445 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
446 : /** MQTT 5.0 reason code. */
447 1 : uint8_t reason_code;
448 :
449 : /** MQTT 5.0 properties. */
450 1 : struct mqtt_common_ack_properties prop;
451 : #endif /* CONFIG_MQTT_VERSION_5_0 */
452 : };
453 :
454 : /** @brief Parameters for MQTT publish complete (PUBCOMP). */
455 1 : struct mqtt_pubcomp_param {
456 : /** Message id of the PUBREL message being acknowledged */
457 1 : uint16_t message_id;
458 :
459 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
460 : /** MQTT 5.0 reason code. */
461 1 : uint8_t reason_code;
462 :
463 : /** MQTT 5.0 properties. */
464 1 : struct mqtt_common_ack_properties prop;
465 : #endif /* CONFIG_MQTT_VERSION_5_0 */
466 : };
467 :
468 : /** @brief Parameters for MQTT subscription acknowledgment (SUBACK). */
469 1 : struct mqtt_suback_param {
470 : /** Message id of the SUBSCRIBE message being acknowledged */
471 1 : uint16_t message_id;
472 :
473 : /** MQTT 3.1 - Return codes indicating maximum QoS level granted for
474 : * each topic in the subscription list.
475 : * MQTT 5.0 - Reason codes corresponding to each topic in the
476 : * subscription list.
477 : */
478 1 : struct mqtt_binstr return_codes;
479 :
480 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
481 : /** MQTT 5.0 properties. */
482 1 : struct mqtt_common_ack_properties prop;
483 : #endif /* CONFIG_MQTT_VERSION_5_0 */
484 : };
485 :
486 : /** @brief Parameters for MQTT unsubscribe acknowledgment (UNSUBACK). */
487 1 : struct mqtt_unsuback_param {
488 : /** Message id of the UNSUBSCRIBE message being acknowledged */
489 1 : uint16_t message_id;
490 :
491 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
492 : /** Reason codes corresponding to each topic in the unsubscription list. */
493 1 : struct mqtt_binstr reason_codes;
494 :
495 : /** MQTT 5.0 properties. */
496 1 : struct mqtt_common_ack_properties prop;
497 : #endif /* CONFIG_MQTT_VERSION_5_0 */
498 : };
499 :
500 : /** @brief Parameters for a publish message (PUBLISH). */
501 1 : struct mqtt_publish_param {
502 : /** Messages including topic, QoS and its payload (if any)
503 : * to be published.
504 : */
505 1 : struct mqtt_publish_message message;
506 :
507 : /** Message id used for the publish message. Redundant for QoS 0. */
508 1 : uint16_t message_id;
509 :
510 : /** Duplicate flag. If 1, it indicates the message is being
511 : * retransmitted. Has no meaning with QoS 0.
512 : */
513 1 : uint8_t dup_flag : 1;
514 :
515 : /** Retain flag. If 1, the message shall be stored persistently
516 : * by the broker.
517 : */
518 1 : uint8_t retain_flag : 1;
519 :
520 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
521 : /** MQTT 5.0 properties. */
522 : struct {
523 : /** MQTT 5.0, chapter 3.3.2.3.7 User Property. */
524 1 : struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];
525 :
526 : /** MQTT 5.0, chapter 3.3.2.3.5 Response Topic. */
527 1 : struct mqtt_utf8 response_topic;
528 :
529 : /** MQTT 5.0, chapter 3.3.2.3.6 Correlation Data. */
530 1 : struct mqtt_binstr correlation_data;
531 :
532 : /** MQTT 5.0, chapter 3.3.2.3.9 Content Type. */
533 1 : struct mqtt_utf8 content_type;
534 :
535 : /** MQTT 5.0, chapter 3.3.2.3.8 Subscription Identifier. */
536 1 : uint32_t subscription_identifier[CONFIG_MQTT_SUBSCRIPTION_ID_PROPERTIES_MAX];
537 :
538 : /** MQTT 5.0, chapter 3.3.2.3.3 Message Expiry Interval. */
539 1 : uint32_t message_expiry_interval;
540 :
541 : /** MQTT 5.0, chapter 3.3.2.3.4 Topic Alias. */
542 1 : uint16_t topic_alias;
543 :
544 : /** MQTT 5.0, chapter 3.3.2.3.2 Payload Format Indicator. */
545 1 : uint8_t payload_format_indicator;
546 :
547 : /** Flags indicating whether given property was present in received packet. */
548 : struct {
549 : /** Payload Format Indicator property was present. */
550 1 : bool has_payload_format_indicator;
551 : /** Message Expiry Interval property was present. */
552 1 : bool has_message_expiry_interval;
553 : /** Topic Alias property was present. */
554 1 : bool has_topic_alias;
555 : /** Response Topic property was present. */
556 1 : bool has_response_topic;
557 : /** Correlation Data property was present. */
558 1 : bool has_correlation_data;
559 : /** User Property property was present. */
560 1 : bool has_user_prop;
561 : /** Subscription Identifier property was present. */
562 1 : bool has_subscription_identifier;
563 : /** Content Type property was present. */
564 1 : bool has_content_type;
565 1 : } rx;
566 1 : } prop;
567 : #endif /* CONFIG_MQTT_VERSION_5_0 */
568 : };
569 :
570 : /** @brief Parameters for subscribe/unsubscribe message. */
571 1 : struct mqtt_subscription_list {
572 : /** Array containing topics along with QoS for each. */
573 1 : struct mqtt_topic *list;
574 :
575 : /** Number of topics in the subscription list */
576 1 : uint16_t list_count;
577 :
578 : /** Message id used to identify subscription request. */
579 1 : uint16_t message_id;
580 :
581 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
582 : /** MQTT 5.0 properties. */
583 : struct {
584 : /** MQTT 5.0, chapter 3.8.2.1.3 / 3.10.2.1.2 User Property. */
585 1 : struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];
586 :
587 : /** MQTT 5.0, chapter 3.8.2.1.2 Subscription Identifier.
588 : * Ignored for UNSUBSCRIBE requests.
589 : */
590 1 : uint32_t subscription_identifier;
591 1 : } prop;
592 : #endif /* CONFIG_MQTT_VERSION_5_0 */
593 : };
594 :
595 : /** @brief Parameters for disconnect message. */
596 1 : struct mqtt_disconnect_param {
597 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
598 : /* MQTT 5.0 Disconnect reason code. */
599 0 : enum mqtt_disconnect_reason_code reason_code;
600 :
601 : /** MQTT 5.0 properties. */
602 : struct {
603 : /** MQTT 5.0, chapter 3.14.2.2.4 User Property. */
604 1 : struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];
605 :
606 : /** MQTT 5.0, chapter 3.14.2.2.3 Reason String. */
607 1 : struct mqtt_utf8 reason_string;
608 :
609 : /** MQTT 5.0, chapter 3.14.2.2.5 Server Reference. */
610 1 : struct mqtt_utf8 server_reference;
611 :
612 : /** MQTT 5.0, chapter 3.14.2.2.2 Session Expiry Interval. */
613 1 : uint32_t session_expiry_interval;
614 :
615 : /** Flags indicating whether given property was present in received packet. */
616 : struct {
617 : /** Session Expiry Interval property was present. */
618 1 : bool has_session_expiry_interval;
619 : /** Reason String property was present. */
620 1 : bool has_reason_string;
621 : /** User Property property was present. */
622 1 : bool has_user_prop;
623 : /** Server Reference property was present. */
624 1 : bool has_server_reference;
625 1 : } rx;
626 1 : } prop;
627 : #endif /* CONFIG_MQTT_VERSION_5_0 */
628 : };
629 :
630 : /** @brief Parameters for auth message. */
631 1 : struct mqtt_auth_param {
632 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
633 : /* MQTT 5.0, chapter 3.15.2.1 Authenticate Reason Code */
634 0 : enum mqtt_auth_reason_code reason_code;
635 :
636 : struct {
637 : /** MQTT 5.0, chapter 3.15.2.2.5 User Property. */
638 1 : struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];
639 :
640 : /** MQTT 5.0, chapter 3.15.2.2.2 Authentication Method. */
641 1 : struct mqtt_utf8 auth_method;
642 :
643 : /** MQTT 5.0, chapter 3.15.2.2.3 Authentication Data. */
644 1 : struct mqtt_binstr auth_data;
645 :
646 : /** MQTT 5.0, chapter 3.15.2.2.4 Reason String. */
647 1 : struct mqtt_utf8 reason_string;
648 :
649 : /** Flags indicating whether given property was present in received packet. */
650 : struct {
651 : /** Authentication Method property was present. */
652 1 : bool has_auth_method;
653 : /** Authentication Data property was present. */
654 1 : bool has_auth_data;
655 : /** Reason String property was present. */
656 1 : bool has_reason_string;
657 : /** User Property property was present. */
658 1 : bool has_user_prop;
659 1 : } rx;
660 0 : } prop;
661 : #endif /* CONFIG_MQTT_VERSION_5_0 */
662 : };
663 :
664 : /**
665 : * @brief Defines event parameters notified along with asynchronous events
666 : * to the application.
667 : */
668 1 : union mqtt_evt_param {
669 : /** Parameters accompanying MQTT_EVT_CONNACK event. */
670 1 : struct mqtt_connack_param connack;
671 :
672 : /** Parameters accompanying MQTT_EVT_PUBLISH event.
673 : *
674 : * @note PUBLISH event structure only contains payload size, the payload
675 : * data parameter should be ignored. Payload content has to be
676 : * read manually with @ref mqtt_read_publish_payload function.
677 : */
678 1 : struct mqtt_publish_param publish;
679 :
680 : /** Parameters accompanying MQTT_EVT_PUBACK event. */
681 1 : struct mqtt_puback_param puback;
682 :
683 : /** Parameters accompanying MQTT_EVT_PUBREC event. */
684 1 : struct mqtt_pubrec_param pubrec;
685 :
686 : /** Parameters accompanying MQTT_EVT_PUBREL event. */
687 1 : struct mqtt_pubrel_param pubrel;
688 :
689 : /** Parameters accompanying MQTT_EVT_PUBCOMP event. */
690 1 : struct mqtt_pubcomp_param pubcomp;
691 :
692 : /** Parameters accompanying MQTT_EVT_SUBACK event. */
693 1 : struct mqtt_suback_param suback;
694 :
695 : /** Parameters accompanying MQTT_EVT_UNSUBACK event. */
696 1 : struct mqtt_unsuback_param unsuback;
697 :
698 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
699 : /** Parameters accompanying MQTT_EVT_DISCONNECT event. */
700 1 : struct mqtt_disconnect_param disconnect;
701 :
702 : /** Parameters accompanying MQTT_EVT_AUTH event. */
703 1 : struct mqtt_auth_param auth;
704 : #endif /* CONFIG_MQTT_VERSION_5_0 */
705 : };
706 :
707 : /** @brief Defines MQTT asynchronous event notified to the application. */
708 1 : struct mqtt_evt {
709 : /** Identifies the event. */
710 1 : enum mqtt_evt_type type;
711 :
712 : /** Contains parameters (if any) accompanying the event. */
713 1 : union mqtt_evt_param param;
714 :
715 : /** Event result. 0 or a negative error code (errno.h) indicating
716 : * reason of failure.
717 : */
718 1 : int result;
719 : };
720 :
721 : struct mqtt_client;
722 :
723 : /**
724 : * @brief Asynchronous event notification callback registered by the
725 : * application.
726 : *
727 : * @param[in] client Identifies the client for which the event is notified.
728 : * @param[in] evt Event description along with result and associated
729 : * parameters (if any).
730 : */
731 1 : typedef void (*mqtt_evt_cb_t)(struct mqtt_client *client,
732 : const struct mqtt_evt *evt);
733 :
734 : /** @brief TLS configuration for secure MQTT transports. */
735 1 : struct mqtt_sec_config {
736 : /** Indicates the preference for peer verification. */
737 1 : int peer_verify;
738 :
739 : /** Indicates the number of entries in the cipher list. */
740 1 : uint32_t cipher_count;
741 :
742 : /** Indicates the list of ciphers to be used for the session.
743 : * May be NULL to use the default ciphers.
744 : */
745 1 : const int *cipher_list;
746 :
747 : /** Indicates the number of entries in the sec tag list. */
748 1 : uint32_t sec_tag_count;
749 :
750 : /** Indicates the list of security tags to be used for the session. */
751 1 : const sec_tag_t *sec_tag_list;
752 :
753 : #if defined(CONFIG_MQTT_LIB_TLS_USE_ALPN)
754 : /**
755 : * Pointer to array of string indicating the ALPN protocol name.
756 : * May be NULL to skip ALPN protocol negotiation.
757 : */
758 : const char **alpn_protocol_name_list;
759 :
760 : /**
761 : * Indicate number of ALPN protocol name in alpn protocol name list.
762 : */
763 : uint32_t alpn_protocol_name_count;
764 : #endif
765 :
766 : /** Peer hostname for ceritificate verification.
767 : * May be NULL to skip hostname verification.
768 : */
769 1 : const char *hostname;
770 :
771 : /** Indicates the preference for copying certificates to the heap. */
772 1 : int cert_nocopy;
773 : };
774 :
775 : /** @brief MQTT transport type. */
776 1 : enum mqtt_transport_type {
777 : /** Use non secure TCP transport for MQTT connection. */
778 : MQTT_TRANSPORT_NON_SECURE,
779 :
780 : #if defined(CONFIG_MQTT_LIB_TLS)
781 : /** Use secure TCP transport (TLS) for MQTT connection. */
782 : MQTT_TRANSPORT_SECURE,
783 : #endif /* CONFIG_MQTT_LIB_TLS */
784 :
785 : #if defined(CONFIG_MQTT_LIB_WEBSOCKET)
786 : /** Use non secure Websocket transport for MQTT connection. */
787 : MQTT_TRANSPORT_NON_SECURE_WEBSOCKET,
788 : #if defined(CONFIG_MQTT_LIB_TLS)
789 : /** Use secure Websocket transport (TLS) for MQTT connection. */
790 : MQTT_TRANSPORT_SECURE_WEBSOCKET,
791 : #endif
792 : #endif /* CONFIG_MQTT_LIB_WEBSOCKET */
793 : #if defined(CONFIG_MQTT_LIB_CUSTOM_TRANSPORT)
794 : /** Use custom transport for MQTT connection. */
795 : MQTT_TRANSPORT_CUSTOM,
796 : #endif /* CONFIG_MQTT_LIB_CUSTOM_TRANSPORT */
797 :
798 : /** Shall not be used as a transport type.
799 : * Indicator of maximum transport types possible.
800 : */
801 : MQTT_TRANSPORT_NUM
802 : };
803 :
804 : /** @brief MQTT transport specific data. */
805 1 : struct mqtt_transport {
806 : /** Transport type selection for client instance.
807 : * @ref mqtt_transport_type for possible values. MQTT_TRANSPORT_MAX
808 : * is not a valid type.
809 : */
810 1 : enum mqtt_transport_type type;
811 :
812 : /** Name of the interface that the MQTT client instance should be bound to.
813 : * Leave as NULL if not specified.
814 : */
815 1 : const char *if_name;
816 :
817 : /** Use either unsecured TCP or secured TLS transport */
818 : union {
819 : /** TCP socket transport for MQTT */
820 : struct {
821 : /** Socket descriptor. */
822 1 : int sock;
823 1 : } tcp;
824 :
825 : #if defined(CONFIG_MQTT_LIB_TLS)
826 : /** TLS socket transport for MQTT */
827 : struct {
828 : /** Socket descriptor. */
829 : int sock;
830 :
831 : /** TLS configuration. See @ref mqtt_sec_config for
832 : * details.
833 : */
834 : struct mqtt_sec_config config;
835 : } tls;
836 : #endif /* CONFIG_MQTT_LIB_TLS */
837 1 : };
838 :
839 : #if defined(CONFIG_MQTT_LIB_WEBSOCKET)
840 : /** Websocket transport for MQTT */
841 : struct {
842 : /** Websocket configuration. */
843 : struct websocket_request config;
844 :
845 : /** Socket descriptor */
846 : int sock;
847 :
848 : /** Websocket timeout, in milliseconds. */
849 : int32_t timeout;
850 : } websocket;
851 : #endif
852 :
853 : #if defined(CONFIG_MQTT_LIB_CUSTOM_TRANSPORT)
854 : /** User defined data for custom transport for MQTT. */
855 : void *custom_transport_data;
856 : #endif /* CONFIG_MQTT_LIB_CUSTOM_TRANSPORT */
857 :
858 : #if defined(CONFIG_SOCKS)
859 : struct {
860 : struct sockaddr addr;
861 : socklen_t addrlen;
862 : } proxy;
863 : #endif
864 : };
865 :
866 : /** @brief MQTT internal state. */
867 1 : struct mqtt_internal {
868 : /** Internal. Mutex to protect access to the client instance. */
869 1 : struct sys_mutex mutex;
870 :
871 : /** Internal. Wall clock value (in milliseconds) of the last activity
872 : * that occurred. Needed for periodic PING.
873 : */
874 1 : uint32_t last_activity;
875 :
876 : /** Internal. Client's state in the connection. */
877 1 : uint32_t state;
878 :
879 : /** Internal. Packet length read so far. */
880 1 : uint32_t rx_buf_datalen;
881 :
882 : /** Internal. Remaining payload length to read. */
883 1 : uint32_t remaining_payload;
884 :
885 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
886 : /** Internal. MQTT 5.0 topic alias mapping. */
887 1 : struct mqtt_topic_alias topic_aliases[CONFIG_MQTT_TOPIC_ALIAS_MAX];
888 :
889 : /** Internal. MQTT 5.0 disconnect reason set in case of processing errors. */
890 1 : enum mqtt_disconnect_reason_code disconnect_reason;
891 : #endif /* CONFIG_MQTT_VERSION_5_0 */
892 : };
893 :
894 : /**
895 : * @brief MQTT Client definition to maintain information relevant to the
896 : * client.
897 : */
898 1 : struct mqtt_client {
899 : /** MQTT client internal state. */
900 1 : struct mqtt_internal internal;
901 :
902 : /** MQTT transport configuration and data. */
903 1 : struct mqtt_transport transport;
904 :
905 : /** Unique client identification to be used for the connection. */
906 1 : struct mqtt_utf8 client_id;
907 :
908 : /** Broker details, for example, address, port. Address type should
909 : * be compatible with transport used.
910 : */
911 1 : const void *broker;
912 :
913 : /** User name (if any) to be used for the connection. NULL indicates
914 : * no user name.
915 : */
916 1 : struct mqtt_utf8 *user_name;
917 :
918 : /** Password (if any) to be used for the connection. Note that if
919 : * password is provided, user name shall also be provided. NULL
920 : * indicates no password.
921 : */
922 1 : struct mqtt_utf8 *password;
923 :
924 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
925 : /** MQTT 5.0 Will properties. */
926 : struct {
927 : /** MQTT 5.0, chapter 3.1.3.2.8 User Property. */
928 1 : struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];
929 :
930 : /** MQTT 5.0, chapter 3.1.3.2.5 Content Type. */
931 1 : struct mqtt_utf8 content_type;
932 :
933 : /** MQTT 5.0, chapter 3.1.3.2.6 Response Topic. */
934 1 : struct mqtt_utf8 response_topic;
935 :
936 : /** MQTT 5.0, chapter 3.1.3.2.7 Correlation Data. */
937 1 : struct mqtt_binstr correlation_data;
938 :
939 : /** MQTT 5.0, chapter 3.1.3.2.2 Will Delay Interval. */
940 1 : uint32_t will_delay_interval;
941 :
942 : /** MQTT 5.0, chapter 3.1.3.2.4 Message Expiry Interval. */
943 1 : uint32_t message_expiry_interval;
944 :
945 : /** MQTT 5.0, chapter 3.1.3.2.3 Payload Format Indicator. */
946 1 : uint8_t payload_format_indicator;
947 1 : } will_prop;
948 : #endif /* CONFIG_MQTT_VERSION_5_0 */
949 :
950 : /** Will topic and QoS. Can be NULL. */
951 1 : struct mqtt_topic *will_topic;
952 :
953 : /** Will message. Can be NULL. Non NULL value valid only if will topic
954 : * is not NULL.
955 : */
956 1 : struct mqtt_utf8 *will_message;
957 :
958 : /** Application callback registered with the module to get MQTT events.
959 : */
960 1 : mqtt_evt_cb_t evt_cb;
961 :
962 : /** Receive buffer used for MQTT packet reception in RX path. */
963 1 : uint8_t *rx_buf;
964 :
965 : /** Size of receive buffer. */
966 1 : uint32_t rx_buf_size;
967 :
968 : /** Transmit buffer used for creating MQTT packet in TX path. */
969 1 : uint8_t *tx_buf;
970 :
971 : /** Size of transmit buffer. */
972 1 : uint32_t tx_buf_size;
973 :
974 : /** Keepalive interval for this client in seconds.
975 : * Default is CONFIG_MQTT_KEEPALIVE.
976 : */
977 1 : uint16_t keepalive;
978 :
979 : /** MQTT protocol version. */
980 1 : uint8_t protocol_version;
981 :
982 : /** Unanswered PINGREQ count on this connection. */
983 1 : int8_t unacked_ping;
984 :
985 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
986 : /** MQTT 5.0 properties. */
987 : struct {
988 : /** MQTT 5.0, chapter 3.1.2.11.8 User Property. */
989 : struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];
990 :
991 : /** MQTT 5.0, chapter 3.1.2.11.9 Authentication Method. */
992 1 : struct mqtt_utf8 auth_method;
993 :
994 : /** MQTT 5.0, chapter 3.1.2.11.10 Authentication Data. */
995 1 : struct mqtt_binstr auth_data;
996 :
997 : /** MQTT 5.0, chapter 3.1.2.11.2 Session Expiry Interval. */
998 1 : uint32_t session_expiry_interval;
999 :
1000 : /** MQTT 5.0, chapter 3.1.2.11.4 Maximum Packet Size. */
1001 1 : uint32_t maximum_packet_size;
1002 :
1003 : /** MQTT 5.0, chapter 3.1.2.11.3 Receive Maximum. */
1004 1 : uint16_t receive_maximum;
1005 :
1006 : /** MQTT 5.0, chapter 3.1.2.11.6 Request Response Information. */
1007 1 : bool request_response_info;
1008 :
1009 : /** MQTT 5.0, chapter 3.1.2.11.7 Request Response Information. */
1010 1 : bool request_problem_info;
1011 1 : } prop;
1012 : #endif /* CONFIG_MQTT_VERSION_5_0 */
1013 :
1014 : /** Will retain flag, 1 if will message shall be retained persistently.
1015 : */
1016 1 : uint8_t will_retain : 1;
1017 :
1018 : /** Clean session flag indicating a fresh (1) or a retained session (0).
1019 : * Default is CONFIG_MQTT_CLEAN_SESSION.
1020 : */
1021 1 : uint8_t clean_session : 1;
1022 :
1023 : /** User specific opaque data */
1024 1 : void *user_data;
1025 : };
1026 :
1027 : /**
1028 : * @brief Initializes the client instance.
1029 : *
1030 : * @param[in] client Client instance for which the procedure is requested.
1031 : * Shall not be NULL.
1032 : *
1033 : * @note Shall be called to initialize client structure, before setting any
1034 : * client parameters and before connecting to broker.
1035 : */
1036 1 : void mqtt_client_init(struct mqtt_client *client);
1037 :
1038 : #if defined(CONFIG_SOCKS)
1039 : /*
1040 : * @brief Set proxy server details
1041 : *
1042 : * @param[in] client Client instance for which the procedure is requested,
1043 : * Shall not be NULL.
1044 : * @param[in] proxy_addr Proxy server address.
1045 : * @param[in] addrlen Proxy server address length.
1046 : *
1047 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1048 : *
1049 : * @note Must be called before calling mqtt_connect().
1050 : */
1051 : int mqtt_client_set_proxy(struct mqtt_client *client,
1052 : struct sockaddr *proxy_addr,
1053 : socklen_t addrlen);
1054 : #endif
1055 :
1056 : /**
1057 : * @brief API to request new MQTT client connection.
1058 : *
1059 : * @param[in] client Client instance for which the procedure is requested.
1060 : * Shall not be NULL.
1061 : *
1062 : * @note This memory is assumed to be resident until mqtt_disconnect is called.
1063 : * @note Any subsequent changes to parameters like broker address, user name,
1064 : * device id, etc. have no effect once MQTT connection is established.
1065 : *
1066 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1067 : *
1068 : * @note Default protocol revision used for connection request is 3.1.1. Please
1069 : * set client.protocol_version = MQTT_VERSION_3_1_0 to use protocol 3.1.0.
1070 : * @note
1071 : * Please modify @kconfig{CONFIG_MQTT_KEEPALIVE} time to override default
1072 : * of 1 minute.
1073 : */
1074 1 : int mqtt_connect(struct mqtt_client *client);
1075 :
1076 : /**
1077 : * @brief API to publish messages on topics.
1078 : *
1079 : * @param[in] client Client instance for which the procedure is requested.
1080 : * Shall not be NULL.
1081 : * @param[in] param Parameters to be used for the publish message.
1082 : * Shall not be NULL.
1083 : *
1084 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1085 : */
1086 1 : int mqtt_publish(struct mqtt_client *client,
1087 : const struct mqtt_publish_param *param);
1088 :
1089 : /**
1090 : * @brief API used by client to send acknowledgment on receiving QoS1 publish
1091 : * message. Should be called on reception of @ref MQTT_EVT_PUBLISH with
1092 : * QoS level @ref MQTT_QOS_1_AT_LEAST_ONCE.
1093 : *
1094 : * @param[in] client Client instance for which the procedure is requested.
1095 : * Shall not be NULL.
1096 : * @param[in] param Identifies message being acknowledged.
1097 : *
1098 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1099 : */
1100 1 : int mqtt_publish_qos1_ack(struct mqtt_client *client,
1101 : const struct mqtt_puback_param *param);
1102 :
1103 : /**
1104 : * @brief API used by client to send acknowledgment on receiving QoS2 publish
1105 : * message. Should be called on reception of @ref MQTT_EVT_PUBLISH with
1106 : * QoS level @ref MQTT_QOS_2_EXACTLY_ONCE.
1107 : *
1108 : * @param[in] client Identifies client instance for which the procedure is
1109 : * requested. Shall not be NULL.
1110 : * @param[in] param Identifies message being acknowledged.
1111 : *
1112 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1113 : */
1114 1 : int mqtt_publish_qos2_receive(struct mqtt_client *client,
1115 : const struct mqtt_pubrec_param *param);
1116 :
1117 : /**
1118 : * @brief API used by client to request release of QoS2 publish message.
1119 : * Should be called on reception of @ref MQTT_EVT_PUBREC.
1120 : *
1121 : * @param[in] client Client instance for which the procedure is requested.
1122 : * Shall not be NULL.
1123 : * @param[in] param Identifies message being released.
1124 : *
1125 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1126 : */
1127 1 : int mqtt_publish_qos2_release(struct mqtt_client *client,
1128 : const struct mqtt_pubrel_param *param);
1129 :
1130 : /**
1131 : * @brief API used by client to send acknowledgment on receiving QoS2 publish
1132 : * release message. Should be called on reception of
1133 : * @ref MQTT_EVT_PUBREL.
1134 : *
1135 : * @param[in] client Identifies client instance for which the procedure is
1136 : * requested. Shall not be NULL.
1137 : * @param[in] param Identifies message being completed.
1138 : *
1139 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1140 : */
1141 1 : int mqtt_publish_qos2_complete(struct mqtt_client *client,
1142 : const struct mqtt_pubcomp_param *param);
1143 :
1144 : /**
1145 : * @brief API to request subscription of one or more topics on the connection.
1146 : *
1147 : * @param[in] client Identifies client instance for which the procedure
1148 : * is requested. Shall not be NULL.
1149 : * @param[in] param Subscription parameters. Shall not be NULL.
1150 : *
1151 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1152 : */
1153 1 : int mqtt_subscribe(struct mqtt_client *client,
1154 : const struct mqtt_subscription_list *param);
1155 :
1156 : /**
1157 : * @brief API to request unsubscription of one or more topics on the connection.
1158 : *
1159 : * @param[in] client Identifies client instance for which the procedure is
1160 : * requested. Shall not be NULL.
1161 : * @param[in] param Parameters describing topics being unsubscribed from.
1162 : * Shall not be NULL.
1163 : *
1164 : * @note QoS included in topic description is unused in this API.
1165 : *
1166 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1167 : */
1168 1 : int mqtt_unsubscribe(struct mqtt_client *client,
1169 : const struct mqtt_subscription_list *param);
1170 :
1171 : /**
1172 : * @brief API to send MQTT ping. The use of this API is optional, as the library
1173 : * handles the connection keep-alive on it's own, see @ref mqtt_live.
1174 : *
1175 : * @param[in] client Identifies client instance for which procedure is
1176 : * requested.
1177 : *
1178 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1179 : */
1180 1 : int mqtt_ping(struct mqtt_client *client);
1181 :
1182 : /**
1183 : * @brief API to disconnect MQTT connection.
1184 : *
1185 : * @param[in] client Identifies client instance for which procedure is
1186 : * requested.
1187 : * @param[in] param Optional Disconnect parameters. May be NULL.
1188 : * Ignored if MQTT 3.1.1 is used.
1189 : *
1190 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1191 : */
1192 1 : int mqtt_disconnect(struct mqtt_client *client,
1193 : const struct mqtt_disconnect_param *param);
1194 :
1195 : #if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
1196 : /**
1197 : * @brief API to send an authentication packet to the server.
1198 : *
1199 : * @param[in] client Client instance for which the procedure is requested.
1200 : * Shall not be NULL.
1201 : * @param[in] param Parameters to be used for the auth message.
1202 : * Shall not be NULL.
1203 : *
1204 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1205 : */
1206 1 : int mqtt_auth(struct mqtt_client *client, const struct mqtt_auth_param *param);
1207 : #endif /* CONFIG_MQTT_VERSION_5_0 */
1208 :
1209 : /**
1210 : * @brief API to abort MQTT connection. This will close the corresponding
1211 : * transport without closing the connection gracefully at the MQTT level
1212 : * (with disconnect message).
1213 : *
1214 : * @param[in] client Identifies client instance for which procedure is
1215 : * requested.
1216 : *
1217 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1218 : */
1219 1 : int mqtt_abort(struct mqtt_client *client);
1220 :
1221 : /**
1222 : * @brief This API should be called periodically for the client to be able
1223 : * to keep the connection alive by sending Ping Requests if need be.
1224 : *
1225 : * @param[in] client Client instance for which the procedure is requested.
1226 : * Shall not be NULL.
1227 : *
1228 : * @note Application shall ensure that the periodicity of calling this function
1229 : * makes it possible to respect the Keep Alive time agreed with the
1230 : * broker on connection. @ref mqtt_connect for details on Keep Alive
1231 : * time.
1232 : *
1233 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1234 : */
1235 1 : int mqtt_live(struct mqtt_client *client);
1236 :
1237 : /**
1238 : * @brief Helper function to determine when next keep alive message should be
1239 : * sent. Can be used for instance as a source for `poll` timeout.
1240 : *
1241 : * @param[in] client Client instance for which the procedure is requested.
1242 : *
1243 : * @return Time in milliseconds until next keep alive message is expected to
1244 : * be sent. Function will return -1 if keep alive messages are
1245 : * not enabled.
1246 : */
1247 1 : int mqtt_keepalive_time_left(const struct mqtt_client *client);
1248 :
1249 : /**
1250 : * @brief Receive an incoming MQTT packet. The registered callback will be
1251 : * called with the packet content.
1252 : *
1253 : * @note In case of PUBLISH message, the payload has to be read separately with
1254 : * @ref mqtt_read_publish_payload function. The size of the payload to
1255 : * read is provided in the publish event structure.
1256 : *
1257 : * @note This is a non-blocking call.
1258 : *
1259 : * @param[in] client Client instance for which the procedure is requested.
1260 : * Shall not be NULL.
1261 : *
1262 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
1263 : */
1264 1 : int mqtt_input(struct mqtt_client *client);
1265 :
1266 : /**
1267 : * @brief Read the payload of the received PUBLISH message. This function should
1268 : * be called within the MQTT event handler, when MQTT PUBLISH message is
1269 : * notified.
1270 : *
1271 : * @note This is a non-blocking call.
1272 : *
1273 : * @param[in] client Client instance for which the procedure is requested.
1274 : * Shall not be NULL.
1275 : * @param[out] buffer Buffer where payload should be stored.
1276 : * @param[in] length Length of the buffer, in bytes.
1277 : *
1278 : * @return Number of bytes read or a negative error code (errno.h) indicating
1279 : * reason of failure.
1280 : */
1281 1 : int mqtt_read_publish_payload(struct mqtt_client *client, void *buffer,
1282 : size_t length);
1283 :
1284 : /**
1285 : * @brief Blocking version of @ref mqtt_read_publish_payload function.
1286 : *
1287 : * @param[in] client Client instance for which the procedure is requested.
1288 : * Shall not be NULL.
1289 : * @param[out] buffer Buffer where payload should be stored.
1290 : * @param[in] length Length of the buffer, in bytes.
1291 : *
1292 : * @return Number of bytes read or a negative error code (errno.h) indicating
1293 : * reason of failure.
1294 : */
1295 1 : int mqtt_read_publish_payload_blocking(struct mqtt_client *client, void *buffer,
1296 : size_t length);
1297 :
1298 : /**
1299 : * @brief Blocking version of @ref mqtt_read_publish_payload function which
1300 : * runs until the required number of bytes are read.
1301 : *
1302 : * @param[in] client Client instance for which the procedure is requested.
1303 : * Shall not be NULL.
1304 : * @param[out] buffer Buffer where payload should be stored.
1305 : * @param[in] length Number of bytes to read.
1306 : *
1307 : * @return 0 if success, otherwise a negative error code (errno.h) indicating
1308 : * reason of failure.
1309 : */
1310 1 : int mqtt_readall_publish_payload(struct mqtt_client *client, uint8_t *buffer,
1311 : size_t length);
1312 :
1313 : #ifdef __cplusplus
1314 : }
1315 : #endif
1316 :
1317 : #endif /* ZEPHYR_INCLUDE_NET_MQTT_H_ */
1318 :
1319 : /**@} */
|
