Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
mqtt.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2018 Nordic Semiconductor ASA
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
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>
30#include <zephyr/net/net_ip.h>
31#include <zephyr/sys/mutex.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
47
52
61
64
67
70
73
76
79
82};
83
88};
89
96
101
108
113
118
123
128
131
135
140
143
146
150
152struct mqtt_utf8 {
153 const uint8_t *utf8;
155};
156
166#define MQTT_UTF8_LITERAL(literal) \
167 ((struct mqtt_utf8) {literal, sizeof(literal) - 1})
168
173};
174
181
186};
187
192};
193
201
206};
207
212};
213
218};
219
224};
225
230};
231
240};
241
246};
247
254
257
262
267};
268
273
276
279};
280
288
296
299
302
305
308
311
314};
315
317struct mqtt_evt {
320
323
328};
329
330struct mqtt_client;
331
340typedef void (*mqtt_evt_cb_t)(struct mqtt_client *client,
341 const struct mqtt_evt *evt);
342
347
350
354 const int *cipher_list;
355
358
361
362#if defined(CONFIG_MQTT_LIB_TLS_USE_ALPN)
367 const char **alpn_protocol_name_list;
368
372 uint32_t alpn_protocol_name_count;
373#endif
374
377
381 const char *hostname;
382
385
388};
389
394
395#if defined(CONFIG_MQTT_LIB_TLS)
397 MQTT_TRANSPORT_SECURE,
398#endif /* CONFIG_MQTT_LIB_TLS */
399
400#if defined(CONFIG_MQTT_LIB_WEBSOCKET)
402 MQTT_TRANSPORT_NON_SECURE_WEBSOCKET,
403#if defined(CONFIG_MQTT_LIB_TLS)
405 MQTT_TRANSPORT_SECURE_WEBSOCKET,
406#endif
407#endif /* CONFIG_MQTT_LIB_WEBSOCKET */
408#if defined(CONFIG_MQTT_LIB_CUSTOM_TRANSPORT)
410 MQTT_TRANSPORT_CUSTOM,
411#endif /* CONFIG_MQTT_LIB_CUSTOM_TRANSPORT */
412
418
426
428 union {
430 struct {
432 int sock;
434
435#if defined(CONFIG_MQTT_LIB_TLS)
437 struct {
439 int sock;
440
444 struct mqtt_sec_config config;
445 } tls;
446#endif /* CONFIG_MQTT_LIB_TLS */
447 };
448
449#if defined(CONFIG_MQTT_LIB_WEBSOCKET)
451 struct {
453 struct websocket_request config;
454
456 int sock;
457
459 int32_t timeout;
460 } websocket;
461#endif
462
463#if defined(CONFIG_MQTT_LIB_CUSTOM_TRANSPORT)
465 void *custom_transport_data;
466#endif /* CONFIG_MQTT_LIB_CUSTOM_TRANSPORT */
467
468#if defined(CONFIG_SOCKS)
469 struct {
470 struct sockaddr addr;
471 socklen_t addrlen;
472 } proxy;
473#endif
474};
475
480
485
488
491
494};
495
503
506
509
513 const void *broker;
514
519
525
528
533
537
540
543
546
549
554
557
560
564
569
572};
573
583void mqtt_client_init(struct mqtt_client *client);
584
585#if defined(CONFIG_SOCKS)
586/*
587 * @brief Set proxy server details
588 *
589 * @param[in] client Client instance for which the procedure is requested,
590 * Shall not be NULL.
591 * @param[in] proxy_addr Proxy server address.
592 * @param[in] addrlen Proxy server address length.
593 *
594 * @return 0 or a negative error code (errno.h) indicating reason of failure.
595 *
596 * @note Must be called before calling mqtt_connect().
597 */
598int mqtt_client_set_proxy(struct mqtt_client *client,
599 struct sockaddr *proxy_addr,
600 socklen_t addrlen);
601#endif
602
621int mqtt_connect(struct mqtt_client *client);
622
633int mqtt_publish(struct mqtt_client *client,
634 const struct mqtt_publish_param *param);
635
648 const struct mqtt_puback_param *param);
649
662 const struct mqtt_pubrec_param *param);
663
675 const struct mqtt_pubrel_param *param);
676
689 const struct mqtt_pubcomp_param *param);
690
700int mqtt_subscribe(struct mqtt_client *client,
701 const struct mqtt_subscription_list *param);
702
715int mqtt_unsubscribe(struct mqtt_client *client,
716 const struct mqtt_subscription_list *param);
717
727int mqtt_ping(struct mqtt_client *client);
728
737int mqtt_disconnect(struct mqtt_client *client);
738
749int mqtt_abort(struct mqtt_client *client);
750
765int mqtt_live(struct mqtt_client *client);
766
777int mqtt_keepalive_time_left(const struct mqtt_client *client);
778
794int mqtt_input(struct mqtt_client *client);
795
811int mqtt_read_publish_payload(struct mqtt_client *client, void *buffer,
812 size_t length);
813
825int mqtt_read_publish_payload_blocking(struct mqtt_client *client, void *buffer,
826 size_t length);
827
841 size_t length);
842
843#ifdef __cplusplus
844}
845#endif
846
847#endif /* ZEPHYR_INCLUDE_NET_MQTT_H_ */
848
size_t socklen_t
Length of a socket address.
Definition: net_ip.h:168
mqtt_evt_type
MQTT Asynchronous Events notified to the application from the module through the callback registered ...
Definition: mqtt.h:42
int mqtt_read_publish_payload_blocking(struct mqtt_client *client, void *buffer, size_t length)
Blocking version of mqtt_read_publish_payload function.
int mqtt_publish_qos2_complete(struct mqtt_client *client, const struct mqtt_pubcomp_param *param)
API used by client to send acknowledgment on receiving QoS2 publish release message.
int mqtt_input(struct mqtt_client *client)
Receive an incoming MQTT packet.
int mqtt_readall_publish_payload(struct mqtt_client *client, uint8_t *buffer, size_t length)
Blocking version of mqtt_read_publish_payload function which runs until the required number of bytes ...
int mqtt_read_publish_payload(struct mqtt_client *client, void *buffer, size_t length)
Read the payload of the received PUBLISH message.
mqtt_qos
MQTT Quality of Service types.
Definition: mqtt.h:91
int mqtt_subscribe(struct mqtt_client *client, const struct mqtt_subscription_list *param)
API to request subscription of one or more topics on the connection.
int mqtt_unsubscribe(struct mqtt_client *client, const struct mqtt_subscription_list *param)
API to request unsubscription of one or more topics on the connection.
int mqtt_publish(struct mqtt_client *client, const struct mqtt_publish_param *param)
API to publish messages on topics.
int mqtt_publish_qos2_release(struct mqtt_client *client, const struct mqtt_pubrel_param *param)
API used by client to request release of QoS2 publish message.
int mqtt_live(struct mqtt_client *client)
This API should be called periodically for the client to be able to keep the connection alive by send...
mqtt_version
MQTT version protocol level.
Definition: mqtt.h:85
int mqtt_keepalive_time_left(const struct mqtt_client *client)
Helper function to determine when next keep alive message should be sent.
mqtt_conn_return_code
MQTT CONNACK return codes.
Definition: mqtt.h:110
void(* mqtt_evt_cb_t)(struct mqtt_client *client, const struct mqtt_evt *evt)
Asynchronous event notification callback registered by the application.
Definition: mqtt.h:340
mqtt_suback_return_code
MQTT SUBACK return codes.
Definition: mqtt.h:137
int mqtt_publish_qos2_receive(struct mqtt_client *client, const struct mqtt_pubrec_param *param)
API used by client to send acknowledgment on receiving QoS2 publish message.
void mqtt_client_init(struct mqtt_client *client)
Initializes the client instance.
int mqtt_ping(struct mqtt_client *client)
API to send MQTT ping.
int mqtt_disconnect(struct mqtt_client *client)
API to disconnect MQTT connection.
int mqtt_connect(struct mqtt_client *client)
API to request new MQTT client connection.
int mqtt_publish_qos1_ack(struct mqtt_client *client, const struct mqtt_puback_param *param)
API used by client to send acknowledgment on receiving QoS1 publish message.
int mqtt_abort(struct mqtt_client *client)
API to abort MQTT connection.
mqtt_transport_type
MQTT transport type.
Definition: mqtt.h:391
@ MQTT_EVT_PUBREC
Reception confirmation for published message with QoS 2.
Definition: mqtt.h:66
@ MQTT_EVT_PUBACK
Acknowledgment for published message with QoS 1.
Definition: mqtt.h:63
@ MQTT_EVT_PINGRESP
Ping Response from server.
Definition: mqtt.h:81
@ MQTT_EVT_SUBACK
Acknowledgment to a subscribe request.
Definition: mqtt.h:75
@ MQTT_EVT_DISCONNECT
Disconnection Event.
Definition: mqtt.h:51
@ MQTT_EVT_UNSUBACK
Acknowledgment to a unsubscribe request.
Definition: mqtt.h:78
@ MQTT_EVT_PUBLISH
Publish event received when message is published on a topic client is subscribed to.
Definition: mqtt.h:60
@ MQTT_EVT_PUBREL
Release of published message with QoS 2.
Definition: mqtt.h:69
@ MQTT_EVT_CONNACK
Acknowledgment of connection request.
Definition: mqtt.h:46
@ MQTT_EVT_PUBCOMP
Confirmation to a publish release message with QoS 2.
Definition: mqtt.h:72
@ MQTT_QOS_0_AT_MOST_ONCE
Lowest Quality of Service, no acknowledgment needed for published message.
Definition: mqtt.h:95
@ MQTT_QOS_1_AT_LEAST_ONCE
Medium Quality of Service, if acknowledgment expected for published message, duplicate messages permi...
Definition: mqtt.h:100
@ MQTT_QOS_2_EXACTLY_ONCE
Highest Quality of Service, acknowledgment expected and message shall be published only once.
Definition: mqtt.h:106
@ MQTT_VERSION_3_1_0
Protocol level for 3.1.0.
Definition: mqtt.h:86
@ MQTT_VERSION_3_1_1
Protocol level for 3.1.1.
Definition: mqtt.h:87
@ MQTT_CONNECTION_ACCEPTED
Connection accepted.
Definition: mqtt.h:112
@ MQTT_NOT_AUTHORIZED
The Client is not authorized to connect.
Definition: mqtt.h:133
@ MQTT_UNACCEPTABLE_PROTOCOL_VERSION
The Server does not support the level of the MQTT protocol requested by the Client.
Definition: mqtt.h:117
@ MQTT_BAD_USER_NAME_OR_PASSWORD
The data in the user name or password is malformed.
Definition: mqtt.h:130
@ MQTT_IDENTIFIER_REJECTED
The Client identifier is correct UTF-8 but not allowed by the Server.
Definition: mqtt.h:122
@ MQTT_SERVER_UNAVAILABLE
The Network Connection has been made but the MQTT service is unavailable.
Definition: mqtt.h:127
@ MQTT_SUBACK_FAILURE
Subscription for a topic failed.
Definition: mqtt.h:148
@ MQTT_SUBACK_SUCCESS_QoS_0
Subscription with QoS 0 succeeded.
Definition: mqtt.h:139
@ MQTT_SUBACK_SUCCESS_QoS_2
Subscription with QoS 2 succeeded.
Definition: mqtt.h:145
@ MQTT_SUBACK_SUCCESS_QoS_1
Subscription with QoS 1 succeeded.
Definition: mqtt.h:142
@ MQTT_TRANSPORT_NUM
Shall not be used as a transport type.
Definition: mqtt.h:416
@ MQTT_TRANSPORT_NON_SECURE
Use non secure TCP transport for MQTT connection.
Definition: mqtt.h:393
int sec_tag_t
Secure tag, a reference to TLS credential.
Definition: tls_credentials.h:72
Public kernel APIs.
IPv6 and IPv4 definitions.
__UINT32_TYPE__ uint32_t
Definition: stdint.h:90
__INT32_TYPE__ int32_t
Definition: stdint.h:74
__UINT8_TYPE__ uint8_t
Definition: stdint.h:88
__UINT16_TYPE__ uint16_t
Definition: stdint.h:89
__INT8_TYPE__ int8_t
Definition: stdint.h:72
Abstracts binary strings.
Definition: mqtt.h:170
uint8_t * data
Pointer to binary stream.
Definition: mqtt.h:171
uint32_t len
Length of binary stream.
Definition: mqtt.h:172
MQTT Client definition to maintain information relevant to the client.
Definition: mqtt.h:500
struct mqtt_internal internal
MQTT client internal state.
Definition: mqtt.h:502
mqtt_evt_cb_t evt_cb
Application callback registered with the module to get MQTT events.
Definition: mqtt.h:536
struct mqtt_topic * will_topic
Will topic and QoS.
Definition: mqtt.h:527
uint32_t tx_buf_size
Size of transmit buffer.
Definition: mqtt.h:548
uint8_t protocol_version
MQTT protocol version.
Definition: mqtt.h:556
uint32_t rx_buf_size
Size of receive buffer.
Definition: mqtt.h:542
int8_t unacked_ping
Unanswered PINGREQ count on this connection.
Definition: mqtt.h:559
const void * broker
Broker details, for example, address, port.
Definition: mqtt.h:513
struct mqtt_utf8 * will_message
Will message.
Definition: mqtt.h:532
uint8_t * rx_buf
Receive buffer used for MQTT packet reception in RX path.
Definition: mqtt.h:539
uint16_t keepalive
Keepalive interval for this client in seconds.
Definition: mqtt.h:553
struct mqtt_utf8 client_id
Unique client identification to be used for the connection.
Definition: mqtt.h:508
uint8_t clean_session
Clean session flag indicating a fresh (1) or a retained session (0).
Definition: mqtt.h:568
struct mqtt_utf8 * user_name
User name (if any) to be used for the connection.
Definition: mqtt.h:518
struct mqtt_transport transport
MQTT transport configuration and data.
Definition: mqtt.h:505
uint8_t will_retain
Will retain flag, 1 if will message shall be retained persistently.
Definition: mqtt.h:563
uint8_t * tx_buf
Transmit buffer used for creating MQTT packet in TX path.
Definition: mqtt.h:545
struct mqtt_utf8 * password
Password (if any) to be used for the connection.
Definition: mqtt.h:524
void * user_data
User specific opaque data.
Definition: mqtt.h:571
Parameters for a connection acknowledgment (CONNACK).
Definition: mqtt.h:195
enum mqtt_conn_return_code return_code
The appropriate non-zero Connect return code indicates if the Server is unable to process a connectio...
Definition: mqtt.h:205
uint8_t session_present_flag
The Session Present flag enables a Client to establish whether the Client and Server have a consisten...
Definition: mqtt.h:200
Defines MQTT asynchronous event notified to the application.
Definition: mqtt.h:317
enum mqtt_evt_type type
Identifies the event.
Definition: mqtt.h:319
int result
Event result.
Definition: mqtt.h:327
union mqtt_evt_param param
Contains parameters (if any) accompanying the event.
Definition: mqtt.h:322
MQTT internal state.
Definition: mqtt.h:477
uint32_t rx_buf_datalen
Internal.
Definition: mqtt.h:490
uint32_t last_activity
Internal.
Definition: mqtt.h:484
uint32_t remaining_payload
Internal.
Definition: mqtt.h:493
uint32_t state
Internal.
Definition: mqtt.h:487
struct sys_mutex mutex
Internal.
Definition: mqtt.h:479
Parameters for MQTT publish acknowledgment (PUBACK).
Definition: mqtt.h:209
uint16_t message_id
Message id of the PUBLISH message being acknowledged.
Definition: mqtt.h:211
Parameters for MQTT publish complete (PUBCOMP).
Definition: mqtt.h:227
uint16_t message_id
Message id of the PUBREL message being acknowledged.
Definition: mqtt.h:229
Parameters for a publish message.
Definition: mqtt.h:189
struct mqtt_binstr payload
Payload on the topic published.
Definition: mqtt.h:191
struct mqtt_topic topic
Topic on which data was published.
Definition: mqtt.h:190
Parameters for a publish message (PUBLISH).
Definition: mqtt.h:249
uint8_t dup_flag
Duplicate flag.
Definition: mqtt.h:261
struct mqtt_publish_message message
Messages including topic, QoS and its payload (if any) to be published.
Definition: mqtt.h:253
uint8_t retain_flag
Retain flag.
Definition: mqtt.h:266
uint16_t message_id
Message id used for the publish message.
Definition: mqtt.h:256
Parameters for MQTT publish receive (PUBREC).
Definition: mqtt.h:215
uint16_t message_id
Message id of the PUBLISH message being acknowledged.
Definition: mqtt.h:217
Parameters for MQTT publish release (PUBREL).
Definition: mqtt.h:221
uint16_t message_id
Message id of the PUBREC message being acknowledged.
Definition: mqtt.h:223
TLS configuration for secure MQTT transports.
Definition: mqtt.h:344
int peer_verify
Indicates the preference for peer verification.
Definition: mqtt.h:346
const int * cipher_list
Indicates the list of ciphers to be used for the session.
Definition: mqtt.h:354
uint32_t cipher_count
Indicates the number of entries in the cipher list.
Definition: mqtt.h:349
int cert_nocopy
Indicates the preference for copying certificates to the heap.
Definition: mqtt.h:384
uint32_t sec_tag_count
Indicates the number of entries in the sec tag list.
Definition: mqtt.h:357
bool set_native_tls
Set socket to native TLS.
Definition: mqtt.h:387
const sec_tag_t * sec_tag_list
Indicates the list of security tags to be used for the session.
Definition: mqtt.h:360
int session_cache
Indicates the preference for enabling TLS session caching.
Definition: mqtt.h:376
const char * hostname
Peer hostname for ceritificate verification.
Definition: mqtt.h:381
Parameters for MQTT subscription acknowledgment (SUBACK).
Definition: mqtt.h:233
struct mqtt_binstr return_codes
Return codes indicating maximum QoS level granted for each topic in the subscription list.
Definition: mqtt.h:239
uint16_t message_id
Message id of the SUBSCRIBE message being acknowledged.
Definition: mqtt.h:235
List of topics in a subscription request.
Definition: mqtt.h:270
uint16_t message_id
Message id used to identify subscription request.
Definition: mqtt.h:278
uint16_t list_count
Number of topics in the subscription list.
Definition: mqtt.h:275
struct mqtt_topic * list
Array containing topics along with QoS for each.
Definition: mqtt.h:272
Abstracts MQTT UTF-8 encoded topic that can be subscribed to or published.
Definition: mqtt.h:178
uint8_t qos
Quality of service requested for the subscription.
Definition: mqtt.h:185
struct mqtt_utf8 topic
Topic on to be published or subscribed to.
Definition: mqtt.h:180
MQTT transport specific data.
Definition: mqtt.h:420
int sock
Socket descriptor.
Definition: mqtt.h:432
enum mqtt_transport_type type
Transport type selection for client instance.
Definition: mqtt.h:425
struct mqtt_transport::@324::@326 tcp
TCP socket transport for MQTT.
Parameters for MQTT unsubscribe acknowledgment (UNSUBACK).
Definition: mqtt.h:243
uint16_t message_id
Message id of the UNSUBSCRIBE message being acknowledged.
Definition: mqtt.h:245
Abstracts UTF-8 encoded strings.
Definition: mqtt.h:152
uint32_t size
Size of UTF string, in bytes.
Definition: mqtt.h:154
const uint8_t * utf8
Pointer to UTF-8 string.
Definition: mqtt.h:153
Generic sockaddr struct.
Definition: net_ip.h:385
Definition: mutex.h:28
Websocket client connection request.
Definition: websocket.h:68
TLS credentials management.
Defines event parameters notified along with asynchronous events to the application.
Definition: mqtt.h:285
struct mqtt_pubrel_param pubrel
Parameters accompanying MQTT_EVT_PUBREL event.
Definition: mqtt.h:304
struct mqtt_puback_param puback
Parameters accompanying MQTT_EVT_PUBACK event.
Definition: mqtt.h:298
struct mqtt_pubrec_param pubrec
Parameters accompanying MQTT_EVT_PUBREC event.
Definition: mqtt.h:301
struct mqtt_publish_param publish
Parameters accompanying MQTT_EVT_PUBLISH event.
Definition: mqtt.h:295
struct mqtt_connack_param connack
Parameters accompanying MQTT_EVT_CONNACK event.
Definition: mqtt.h:287
struct mqtt_pubcomp_param pubcomp
Parameters accompanying MQTT_EVT_PUBCOMP event.
Definition: mqtt.h:307
struct mqtt_unsuback_param unsuback
Parameters accompanying MQTT_EVT_UNSUBACK event.
Definition: mqtt.h:313
struct mqtt_suback_param suback
Parameters accompanying MQTT_EVT_SUBACK event.
Definition: mqtt.h:310
Websocket API.