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 :
84 : /** @brief MQTT version protocol level. */
85 1 : enum mqtt_version {
86 : MQTT_VERSION_3_1_0 = 3, /**< Protocol level for 3.1.0. */
87 : MQTT_VERSION_3_1_1 = 4 /**< Protocol level for 3.1.1. */
88 : };
89 :
90 : /** @brief MQTT Quality of Service types. */
91 1 : enum mqtt_qos {
92 : /** Lowest Quality of Service, no acknowledgment needed for published
93 : * message.
94 : */
95 : MQTT_QOS_0_AT_MOST_ONCE = 0x00,
96 :
97 : /** Medium Quality of Service, if acknowledgment expected for published
98 : * message, duplicate messages permitted.
99 : */
100 : MQTT_QOS_1_AT_LEAST_ONCE = 0x01,
101 :
102 : /** Highest Quality of Service, acknowledgment expected and message
103 : * shall be published only once. Message not published to interested
104 : * parties unless client issues a PUBREL.
105 : */
106 : MQTT_QOS_2_EXACTLY_ONCE = 0x02
107 : };
108 :
109 : /** @brief MQTT CONNACK return codes. */
110 1 : enum mqtt_conn_return_code {
111 : /** Connection accepted. */
112 : MQTT_CONNECTION_ACCEPTED = 0x00,
113 :
114 : /** The Server does not support the level of the MQTT protocol
115 : * requested by the Client.
116 : */
117 : MQTT_UNACCEPTABLE_PROTOCOL_VERSION = 0x01,
118 :
119 : /** The Client identifier is correct UTF-8 but not allowed by the
120 : * Server.
121 : */
122 : MQTT_IDENTIFIER_REJECTED = 0x02,
123 :
124 : /** The Network Connection has been made but the MQTT service is
125 : * unavailable.
126 : */
127 : MQTT_SERVER_UNAVAILABLE = 0x03,
128 :
129 : /** The data in the user name or password is malformed. */
130 : MQTT_BAD_USER_NAME_OR_PASSWORD = 0x04,
131 :
132 : /** The Client is not authorized to connect. */
133 : MQTT_NOT_AUTHORIZED = 0x05
134 : };
135 :
136 : /** @brief MQTT SUBACK return codes. */
137 1 : enum mqtt_suback_return_code {
138 : /** Subscription with QoS 0 succeeded. */
139 : MQTT_SUBACK_SUCCESS_QoS_0 = 0x00,
140 :
141 : /** Subscription with QoS 1 succeeded. */
142 : MQTT_SUBACK_SUCCESS_QoS_1 = 0x01,
143 :
144 : /** Subscription with QoS 2 succeeded. */
145 : MQTT_SUBACK_SUCCESS_QoS_2 = 0x02,
146 :
147 : /** Subscription for a topic failed. */
148 : MQTT_SUBACK_FAILURE = 0x80
149 : };
150 :
151 : /** @brief Abstracts UTF-8 encoded strings. */
152 1 : struct mqtt_utf8 {
153 1 : const uint8_t *utf8; /**< Pointer to UTF-8 string. */
154 1 : uint32_t size; /**< Size of UTF string, in bytes. */
155 : };
156 :
157 : /**
158 : * @brief Initialize UTF-8 encoded string from C literal string.
159 : *
160 : * Use it as follows:
161 : *
162 : * struct mqtt_utf8 password = MQTT_UTF8_LITERAL("my_pass");
163 : *
164 : * @param[in] literal Literal string from which to generate mqtt_utf8 object.
165 : */
166 1 : #define MQTT_UTF8_LITERAL(literal) \
167 : ((struct mqtt_utf8) {literal, sizeof(literal) - 1})
168 :
169 : /** @brief Abstracts binary strings. */
170 1 : struct mqtt_binstr {
171 1 : uint8_t *data; /**< Pointer to binary stream. */
172 1 : uint32_t len; /**< Length of binary stream. */
173 : };
174 :
175 : /** @brief Abstracts MQTT UTF-8 encoded topic that can be subscribed
176 : * to or published.
177 : */
178 1 : struct mqtt_topic {
179 : /** Topic on to be published or subscribed to. */
180 1 : struct mqtt_utf8 topic;
181 :
182 : /** Quality of service requested for the subscription.
183 : * @ref mqtt_qos for details.
184 : */
185 1 : uint8_t qos;
186 : };
187 :
188 : /** @brief Parameters for a publish message. */
189 1 : struct mqtt_publish_message {
190 1 : struct mqtt_topic topic; /**< Topic on which data was published. */
191 1 : struct mqtt_binstr payload; /**< Payload on the topic published. */
192 : };
193 :
194 : /** @brief Parameters for a connection acknowledgment (CONNACK). */
195 1 : struct mqtt_connack_param {
196 : /** The Session Present flag enables a Client to establish whether
197 : * the Client and Server have a consistent view about whether there
198 : * is already stored Session state.
199 : */
200 1 : uint8_t session_present_flag;
201 :
202 : /** The appropriate non-zero Connect return code indicates if the Server
203 : * is unable to process a connection request for some reason.
204 : */
205 1 : enum mqtt_conn_return_code return_code;
206 : };
207 :
208 : /** @brief Parameters for MQTT publish acknowledgment (PUBACK). */
209 1 : struct mqtt_puback_param {
210 : /** Message id of the PUBLISH message being acknowledged */
211 1 : uint16_t message_id;
212 : };
213 :
214 : /** @brief Parameters for MQTT publish receive (PUBREC). */
215 1 : struct mqtt_pubrec_param {
216 : /** Message id of the PUBLISH message being acknowledged */
217 1 : uint16_t message_id;
218 : };
219 :
220 : /** @brief Parameters for MQTT publish release (PUBREL). */
221 1 : struct mqtt_pubrel_param {
222 : /** Message id of the PUBREC message being acknowledged */
223 1 : uint16_t message_id;
224 : };
225 :
226 : /** @brief Parameters for MQTT publish complete (PUBCOMP). */
227 1 : struct mqtt_pubcomp_param {
228 : /** Message id of the PUBREL message being acknowledged */
229 1 : uint16_t message_id;
230 : };
231 :
232 : /** @brief Parameters for MQTT subscription acknowledgment (SUBACK). */
233 1 : struct mqtt_suback_param {
234 : /** Message id of the SUBSCRIBE message being acknowledged */
235 1 : uint16_t message_id;
236 : /** Return codes indicating maximum QoS level granted for each topic
237 : * in the subscription list.
238 : */
239 1 : struct mqtt_binstr return_codes;
240 : };
241 :
242 : /** @brief Parameters for MQTT unsubscribe acknowledgment (UNSUBACK). */
243 1 : struct mqtt_unsuback_param {
244 : /** Message id of the UNSUBSCRIBE message being acknowledged */
245 1 : uint16_t message_id;
246 : };
247 :
248 : /** @brief Parameters for a publish message (PUBLISH). */
249 1 : struct mqtt_publish_param {
250 : /** Messages including topic, QoS and its payload (if any)
251 : * to be published.
252 : */
253 1 : struct mqtt_publish_message message;
254 :
255 : /** Message id used for the publish message. Redundant for QoS 0. */
256 1 : uint16_t message_id;
257 :
258 : /** Duplicate flag. If 1, it indicates the message is being
259 : * retransmitted. Has no meaning with QoS 0.
260 : */
261 1 : uint8_t dup_flag : 1;
262 :
263 : /** Retain flag. If 1, the message shall be stored persistently
264 : * by the broker.
265 : */
266 1 : uint8_t retain_flag : 1;
267 : };
268 :
269 : /** @brief List of topics in a subscription request. */
270 1 : struct mqtt_subscription_list {
271 : /** Array containing topics along with QoS for each. */
272 1 : struct mqtt_topic *list;
273 :
274 : /** Number of topics in the subscription list */
275 1 : uint16_t list_count;
276 :
277 : /** Message id used to identify subscription request. */
278 1 : uint16_t message_id;
279 : };
280 :
281 : /**
282 : * @brief Defines event parameters notified along with asynchronous events
283 : * to the application.
284 : */
285 1 : union mqtt_evt_param {
286 : /** Parameters accompanying MQTT_EVT_CONNACK event. */
287 1 : struct mqtt_connack_param connack;
288 :
289 : /** Parameters accompanying MQTT_EVT_PUBLISH event.
290 : *
291 : * @note PUBLISH event structure only contains payload size, the payload
292 : * data parameter should be ignored. Payload content has to be
293 : * read manually with @ref mqtt_read_publish_payload function.
294 : */
295 1 : struct mqtt_publish_param publish;
296 :
297 : /** Parameters accompanying MQTT_EVT_PUBACK event. */
298 1 : struct mqtt_puback_param puback;
299 :
300 : /** Parameters accompanying MQTT_EVT_PUBREC event. */
301 1 : struct mqtt_pubrec_param pubrec;
302 :
303 : /** Parameters accompanying MQTT_EVT_PUBREL event. */
304 1 : struct mqtt_pubrel_param pubrel;
305 :
306 : /** Parameters accompanying MQTT_EVT_PUBCOMP event. */
307 1 : struct mqtt_pubcomp_param pubcomp;
308 :
309 : /** Parameters accompanying MQTT_EVT_SUBACK event. */
310 1 : struct mqtt_suback_param suback;
311 :
312 : /** Parameters accompanying MQTT_EVT_UNSUBACK event. */
313 1 : struct mqtt_unsuback_param unsuback;
314 : };
315 :
316 : /** @brief Defines MQTT asynchronous event notified to the application. */
317 1 : struct mqtt_evt {
318 : /** Identifies the event. */
319 1 : enum mqtt_evt_type type;
320 :
321 : /** Contains parameters (if any) accompanying the event. */
322 1 : union mqtt_evt_param param;
323 :
324 : /** Event result. 0 or a negative error code (errno.h) indicating
325 : * reason of failure.
326 : */
327 1 : int result;
328 : };
329 :
330 : struct mqtt_client;
331 :
332 : /**
333 : * @brief Asynchronous event notification callback registered by the
334 : * application.
335 : *
336 : * @param[in] client Identifies the client for which the event is notified.
337 : * @param[in] evt Event description along with result and associated
338 : * parameters (if any).
339 : */
340 1 : typedef void (*mqtt_evt_cb_t)(struct mqtt_client *client,
341 : const struct mqtt_evt *evt);
342 :
343 : /** @brief TLS configuration for secure MQTT transports. */
344 1 : struct mqtt_sec_config {
345 : /** Indicates the preference for peer verification. */
346 1 : int peer_verify;
347 :
348 : /** Indicates the number of entries in the cipher list. */
349 1 : uint32_t cipher_count;
350 :
351 : /** Indicates the list of ciphers to be used for the session.
352 : * May be NULL to use the default ciphers.
353 : */
354 1 : const int *cipher_list;
355 :
356 : /** Indicates the number of entries in the sec tag list. */
357 1 : uint32_t sec_tag_count;
358 :
359 : /** Indicates the list of security tags to be used for the session. */
360 1 : const sec_tag_t *sec_tag_list;
361 :
362 : #if defined(CONFIG_MQTT_LIB_TLS_USE_ALPN)
363 : /**
364 : * Pointer to array of string indicating the ALPN protocol name.
365 : * May be NULL to skip ALPN protocol negotiation.
366 : */
367 : const char **alpn_protocol_name_list;
368 :
369 : /**
370 : * Indicate number of ALPN protocol name in alpn protocol name list.
371 : */
372 : uint32_t alpn_protocol_name_count;
373 : #endif
374 :
375 : /** Peer hostname for ceritificate verification.
376 : * May be NULL to skip hostname verification.
377 : */
378 1 : const char *hostname;
379 :
380 : /** Indicates the preference for copying certificates to the heap. */
381 1 : int cert_nocopy;
382 : };
383 :
384 : /** @brief MQTT transport type. */
385 1 : enum mqtt_transport_type {
386 : /** Use non secure TCP transport for MQTT connection. */
387 : MQTT_TRANSPORT_NON_SECURE,
388 :
389 : #if defined(CONFIG_MQTT_LIB_TLS)
390 : /** Use secure TCP transport (TLS) for MQTT connection. */
391 : MQTT_TRANSPORT_SECURE,
392 : #endif /* CONFIG_MQTT_LIB_TLS */
393 :
394 : #if defined(CONFIG_MQTT_LIB_WEBSOCKET)
395 : /** Use non secure Websocket transport for MQTT connection. */
396 : MQTT_TRANSPORT_NON_SECURE_WEBSOCKET,
397 : #if defined(CONFIG_MQTT_LIB_TLS)
398 : /** Use secure Websocket transport (TLS) for MQTT connection. */
399 : MQTT_TRANSPORT_SECURE_WEBSOCKET,
400 : #endif
401 : #endif /* CONFIG_MQTT_LIB_WEBSOCKET */
402 : #if defined(CONFIG_MQTT_LIB_CUSTOM_TRANSPORT)
403 : /** Use custom transport for MQTT connection. */
404 : MQTT_TRANSPORT_CUSTOM,
405 : #endif /* CONFIG_MQTT_LIB_CUSTOM_TRANSPORT */
406 :
407 : /** Shall not be used as a transport type.
408 : * Indicator of maximum transport types possible.
409 : */
410 : MQTT_TRANSPORT_NUM
411 : };
412 :
413 : /** @brief MQTT transport specific data. */
414 1 : struct mqtt_transport {
415 : /** Transport type selection for client instance.
416 : * @ref mqtt_transport_type for possible values. MQTT_TRANSPORT_MAX
417 : * is not a valid type.
418 : */
419 1 : enum mqtt_transport_type type;
420 :
421 : /** Use either unsecured TCP or secured TLS transport */
422 : union {
423 : /** TCP socket transport for MQTT */
424 : struct {
425 : /** Socket descriptor. */
426 1 : int sock;
427 1 : } tcp;
428 :
429 : #if defined(CONFIG_MQTT_LIB_TLS)
430 : /** TLS socket transport for MQTT */
431 : struct {
432 : /** Socket descriptor. */
433 : int sock;
434 :
435 : /** TLS configuration. See @ref mqtt_sec_config for
436 : * details.
437 : */
438 : struct mqtt_sec_config config;
439 : } tls;
440 : #endif /* CONFIG_MQTT_LIB_TLS */
441 1 : };
442 :
443 : #if defined(CONFIG_MQTT_LIB_WEBSOCKET)
444 : /** Websocket transport for MQTT */
445 : struct {
446 : /** Websocket configuration. */
447 : struct websocket_request config;
448 :
449 : /** Socket descriptor */
450 : int sock;
451 :
452 : /** Websocket timeout, in milliseconds. */
453 : int32_t timeout;
454 : } websocket;
455 : #endif
456 :
457 : #if defined(CONFIG_MQTT_LIB_CUSTOM_TRANSPORT)
458 : /** User defined data for custom transport for MQTT. */
459 : void *custom_transport_data;
460 : #endif /* CONFIG_MQTT_LIB_CUSTOM_TRANSPORT */
461 :
462 : #if defined(CONFIG_SOCKS)
463 : struct {
464 : struct sockaddr addr;
465 : socklen_t addrlen;
466 : } proxy;
467 : #endif
468 : };
469 :
470 : /** @brief MQTT internal state. */
471 1 : struct mqtt_internal {
472 : /** Internal. Mutex to protect access to the client instance. */
473 1 : struct sys_mutex mutex;
474 :
475 : /** Internal. Wall clock value (in milliseconds) of the last activity
476 : * that occurred. Needed for periodic PING.
477 : */
478 1 : uint32_t last_activity;
479 :
480 : /** Internal. Client's state in the connection. */
481 1 : uint32_t state;
482 :
483 : /** Internal. Packet length read so far. */
484 1 : uint32_t rx_buf_datalen;
485 :
486 : /** Internal. Remaining payload length to read. */
487 1 : uint32_t remaining_payload;
488 : };
489 :
490 : /**
491 : * @brief MQTT Client definition to maintain information relevant to the
492 : * client.
493 : */
494 1 : struct mqtt_client {
495 : /** MQTT client internal state. */
496 1 : struct mqtt_internal internal;
497 :
498 : /** MQTT transport configuration and data. */
499 1 : struct mqtt_transport transport;
500 :
501 : /** Unique client identification to be used for the connection. */
502 1 : struct mqtt_utf8 client_id;
503 :
504 : /** Broker details, for example, address, port. Address type should
505 : * be compatible with transport used.
506 : */
507 1 : const void *broker;
508 :
509 : /** User name (if any) to be used for the connection. NULL indicates
510 : * no user name.
511 : */
512 1 : struct mqtt_utf8 *user_name;
513 :
514 : /** Password (if any) to be used for the connection. Note that if
515 : * password is provided, user name shall also be provided. NULL
516 : * indicates no password.
517 : */
518 1 : struct mqtt_utf8 *password;
519 :
520 : /** Will topic and QoS. Can be NULL. */
521 1 : struct mqtt_topic *will_topic;
522 :
523 : /** Will message. Can be NULL. Non NULL value valid only if will topic
524 : * is not NULL.
525 : */
526 1 : struct mqtt_utf8 *will_message;
527 :
528 : /** Application callback registered with the module to get MQTT events.
529 : */
530 1 : mqtt_evt_cb_t evt_cb;
531 :
532 : /** Receive buffer used for MQTT packet reception in RX path. */
533 1 : uint8_t *rx_buf;
534 :
535 : /** Size of receive buffer. */
536 1 : uint32_t rx_buf_size;
537 :
538 : /** Transmit buffer used for creating MQTT packet in TX path. */
539 1 : uint8_t *tx_buf;
540 :
541 : /** Size of transmit buffer. */
542 1 : uint32_t tx_buf_size;
543 :
544 : /** Keepalive interval for this client in seconds.
545 : * Default is CONFIG_MQTT_KEEPALIVE.
546 : */
547 1 : uint16_t keepalive;
548 :
549 : /** MQTT protocol version. */
550 1 : uint8_t protocol_version;
551 :
552 : /** Unanswered PINGREQ count on this connection. */
553 1 : int8_t unacked_ping;
554 :
555 : /** Will retain flag, 1 if will message shall be retained persistently.
556 : */
557 1 : uint8_t will_retain : 1;
558 :
559 : /** Clean session flag indicating a fresh (1) or a retained session (0).
560 : * Default is CONFIG_MQTT_CLEAN_SESSION.
561 : */
562 1 : uint8_t clean_session : 1;
563 :
564 : /** User specific opaque data */
565 1 : void *user_data;
566 : };
567 :
568 : /**
569 : * @brief Initializes the client instance.
570 : *
571 : * @param[in] client Client instance for which the procedure is requested.
572 : * Shall not be NULL.
573 : *
574 : * @note Shall be called to initialize client structure, before setting any
575 : * client parameters and before connecting to broker.
576 : */
577 1 : void mqtt_client_init(struct mqtt_client *client);
578 :
579 : #if defined(CONFIG_SOCKS)
580 : /*
581 : * @brief Set proxy server details
582 : *
583 : * @param[in] client Client instance for which the procedure is requested,
584 : * Shall not be NULL.
585 : * @param[in] proxy_addr Proxy server address.
586 : * @param[in] addrlen Proxy server address length.
587 : *
588 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
589 : *
590 : * @note Must be called before calling mqtt_connect().
591 : */
592 : int mqtt_client_set_proxy(struct mqtt_client *client,
593 : struct sockaddr *proxy_addr,
594 : socklen_t addrlen);
595 : #endif
596 :
597 : /**
598 : * @brief API to request new MQTT client connection.
599 : *
600 : * @param[in] client Client instance for which the procedure is requested.
601 : * Shall not be NULL.
602 : *
603 : * @note This memory is assumed to be resident until mqtt_disconnect is called.
604 : * @note Any subsequent changes to parameters like broker address, user name,
605 : * device id, etc. have no effect once MQTT connection is established.
606 : *
607 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
608 : *
609 : * @note Default protocol revision used for connection request is 3.1.1. Please
610 : * set client.protocol_version = MQTT_VERSION_3_1_0 to use protocol 3.1.0.
611 : * @note
612 : * Please modify @kconfig{CONFIG_MQTT_KEEPALIVE} time to override default
613 : * of 1 minute.
614 : */
615 1 : int mqtt_connect(struct mqtt_client *client);
616 :
617 : /**
618 : * @brief API to publish messages on topics.
619 : *
620 : * @param[in] client Client instance for which the procedure is requested.
621 : * Shall not be NULL.
622 : * @param[in] param Parameters to be used for the publish message.
623 : * Shall not be NULL.
624 : *
625 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
626 : */
627 1 : int mqtt_publish(struct mqtt_client *client,
628 : const struct mqtt_publish_param *param);
629 :
630 : /**
631 : * @brief API used by client to send acknowledgment on receiving QoS1 publish
632 : * message. Should be called on reception of @ref MQTT_EVT_PUBLISH with
633 : * QoS level @ref MQTT_QOS_1_AT_LEAST_ONCE.
634 : *
635 : * @param[in] client Client instance for which the procedure is requested.
636 : * Shall not be NULL.
637 : * @param[in] param Identifies message being acknowledged.
638 : *
639 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
640 : */
641 1 : int mqtt_publish_qos1_ack(struct mqtt_client *client,
642 : const struct mqtt_puback_param *param);
643 :
644 : /**
645 : * @brief API used by client to send acknowledgment on receiving QoS2 publish
646 : * message. Should be called on reception of @ref MQTT_EVT_PUBLISH with
647 : * QoS level @ref MQTT_QOS_2_EXACTLY_ONCE.
648 : *
649 : * @param[in] client Identifies client instance for which the procedure is
650 : * requested. Shall not be NULL.
651 : * @param[in] param Identifies message being acknowledged.
652 : *
653 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
654 : */
655 1 : int mqtt_publish_qos2_receive(struct mqtt_client *client,
656 : const struct mqtt_pubrec_param *param);
657 :
658 : /**
659 : * @brief API used by client to request release of QoS2 publish message.
660 : * Should be called on reception of @ref MQTT_EVT_PUBREC.
661 : *
662 : * @param[in] client Client instance for which the procedure is requested.
663 : * Shall not be NULL.
664 : * @param[in] param Identifies message being released.
665 : *
666 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
667 : */
668 1 : int mqtt_publish_qos2_release(struct mqtt_client *client,
669 : const struct mqtt_pubrel_param *param);
670 :
671 : /**
672 : * @brief API used by client to send acknowledgment on receiving QoS2 publish
673 : * release message. Should be called on reception of
674 : * @ref MQTT_EVT_PUBREL.
675 : *
676 : * @param[in] client Identifies client instance for which the procedure is
677 : * requested. Shall not be NULL.
678 : * @param[in] param Identifies message being completed.
679 : *
680 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
681 : */
682 1 : int mqtt_publish_qos2_complete(struct mqtt_client *client,
683 : const struct mqtt_pubcomp_param *param);
684 :
685 : /**
686 : * @brief API to request subscription of one or more topics on the connection.
687 : *
688 : * @param[in] client Identifies client instance for which the procedure
689 : * is requested. Shall not be NULL.
690 : * @param[in] param Subscription parameters. Shall not be NULL.
691 : *
692 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
693 : */
694 1 : int mqtt_subscribe(struct mqtt_client *client,
695 : const struct mqtt_subscription_list *param);
696 :
697 : /**
698 : * @brief API to request unsubscription of one or more topics on the connection.
699 : *
700 : * @param[in] client Identifies client instance for which the procedure is
701 : * requested. Shall not be NULL.
702 : * @param[in] param Parameters describing topics being unsubscribed from.
703 : * Shall not be NULL.
704 : *
705 : * @note QoS included in topic description is unused in this API.
706 : *
707 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
708 : */
709 1 : int mqtt_unsubscribe(struct mqtt_client *client,
710 : const struct mqtt_subscription_list *param);
711 :
712 : /**
713 : * @brief API to send MQTT ping. The use of this API is optional, as the library
714 : * handles the connection keep-alive on it's own, see @ref mqtt_live.
715 : *
716 : * @param[in] client Identifies client instance for which procedure is
717 : * requested.
718 : *
719 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
720 : */
721 1 : int mqtt_ping(struct mqtt_client *client);
722 :
723 : /**
724 : * @brief API to disconnect MQTT connection.
725 : *
726 : * @param[in] client Identifies client instance for which procedure is
727 : * requested.
728 : *
729 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
730 : */
731 1 : int mqtt_disconnect(struct mqtt_client *client);
732 :
733 : /**
734 : * @brief API to abort MQTT connection. This will close the corresponding
735 : * transport without closing the connection gracefully at the MQTT level
736 : * (with disconnect message).
737 : *
738 : * @param[in] client Identifies client instance for which procedure is
739 : * requested.
740 : *
741 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
742 : */
743 1 : int mqtt_abort(struct mqtt_client *client);
744 :
745 : /**
746 : * @brief This API should be called periodically for the client to be able
747 : * to keep the connection alive by sending Ping Requests if need be.
748 : *
749 : * @param[in] client Client instance for which the procedure is requested.
750 : * Shall not be NULL.
751 : *
752 : * @note Application shall ensure that the periodicity of calling this function
753 : * makes it possible to respect the Keep Alive time agreed with the
754 : * broker on connection. @ref mqtt_connect for details on Keep Alive
755 : * time.
756 : *
757 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
758 : */
759 1 : int mqtt_live(struct mqtt_client *client);
760 :
761 : /**
762 : * @brief Helper function to determine when next keep alive message should be
763 : * sent. Can be used for instance as a source for `poll` timeout.
764 : *
765 : * @param[in] client Client instance for which the procedure is requested.
766 : *
767 : * @return Time in milliseconds until next keep alive message is expected to
768 : * be sent. Function will return -1 if keep alive messages are
769 : * not enabled.
770 : */
771 1 : int mqtt_keepalive_time_left(const struct mqtt_client *client);
772 :
773 : /**
774 : * @brief Receive an incoming MQTT packet. The registered callback will be
775 : * called with the packet content.
776 : *
777 : * @note In case of PUBLISH message, the payload has to be read separately with
778 : * @ref mqtt_read_publish_payload function. The size of the payload to
779 : * read is provided in the publish event structure.
780 : *
781 : * @note This is a non-blocking call.
782 : *
783 : * @param[in] client Client instance for which the procedure is requested.
784 : * Shall not be NULL.
785 : *
786 : * @return 0 or a negative error code (errno.h) indicating reason of failure.
787 : */
788 1 : int mqtt_input(struct mqtt_client *client);
789 :
790 : /**
791 : * @brief Read the payload of the received PUBLISH message. This function should
792 : * be called within the MQTT event handler, when MQTT PUBLISH message is
793 : * notified.
794 : *
795 : * @note This is a non-blocking call.
796 : *
797 : * @param[in] client Client instance for which the procedure is requested.
798 : * Shall not be NULL.
799 : * @param[out] buffer Buffer where payload should be stored.
800 : * @param[in] length Length of the buffer, in bytes.
801 : *
802 : * @return Number of bytes read or a negative error code (errno.h) indicating
803 : * reason of failure.
804 : */
805 1 : int mqtt_read_publish_payload(struct mqtt_client *client, void *buffer,
806 : size_t length);
807 :
808 : /**
809 : * @brief Blocking version of @ref mqtt_read_publish_payload function.
810 : *
811 : * @param[in] client Client instance for which the procedure is requested.
812 : * Shall not be NULL.
813 : * @param[out] buffer Buffer where payload should be stored.
814 : * @param[in] length Length of the buffer, in bytes.
815 : *
816 : * @return Number of bytes read or a negative error code (errno.h) indicating
817 : * reason of failure.
818 : */
819 1 : int mqtt_read_publish_payload_blocking(struct mqtt_client *client, void *buffer,
820 : size_t length);
821 :
822 : /**
823 : * @brief Blocking version of @ref mqtt_read_publish_payload function which
824 : * runs until the required number of bytes are read.
825 : *
826 : * @param[in] client Client instance for which the procedure is requested.
827 : * Shall not be NULL.
828 : * @param[out] buffer Buffer where payload should be stored.
829 : * @param[in] length Number of bytes to read.
830 : *
831 : * @return 0 if success, otherwise a negative error code (errno.h) indicating
832 : * reason of failure.
833 : */
834 1 : int mqtt_readall_publish_payload(struct mqtt_client *client, uint8_t *buffer,
835 : size_t length);
836 :
837 : #ifdef __cplusplus
838 : }
839 : #endif
840 :
841 : #endif /* ZEPHYR_INCLUDE_NET_MQTT_H_ */
842 :
843 : /**@} */
|
