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