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
378 const char *hostname;
379
382};
383
388
389#if defined(CONFIG_MQTT_LIB_TLS)
391 MQTT_TRANSPORT_SECURE,
392#endif /* CONFIG_MQTT_LIB_TLS */
393
394#if defined(CONFIG_MQTT_LIB_WEBSOCKET)
396 MQTT_TRANSPORT_NON_SECURE_WEBSOCKET,
397#if defined(CONFIG_MQTT_LIB_TLS)
399 MQTT_TRANSPORT_SECURE_WEBSOCKET,
400#endif
401#endif /* CONFIG_MQTT_LIB_WEBSOCKET */
402#if defined(CONFIG_MQTT_LIB_CUSTOM_TRANSPORT)
404 MQTT_TRANSPORT_CUSTOM,
405#endif /* CONFIG_MQTT_LIB_CUSTOM_TRANSPORT */
406
412
420
422 union {
424 struct {
426 int sock;
428
429#if defined(CONFIG_MQTT_LIB_TLS)
431 struct {
433 int sock;
434
438 struct mqtt_sec_config config;
439 } tls;
440#endif /* CONFIG_MQTT_LIB_TLS */
441 };
442
443#if defined(CONFIG_MQTT_LIB_WEBSOCKET)
445 struct {
447 struct websocket_request config;
448
450 int sock;
451
453 int32_t timeout;
454 } websocket;
455#endif
456
457#if defined(CONFIG_MQTT_LIB_CUSTOM_TRANSPORT)
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
474
479
482
485
488};
489
497
500
503
507 const void *broker;
508
513
519
522
527
531
534
537
540
543
548
551
554
558
563
566};
567
577void 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 */
592int mqtt_client_set_proxy(struct mqtt_client *client,
593 struct sockaddr *proxy_addr,
594 socklen_t addrlen);
595#endif
596
615int mqtt_connect(struct mqtt_client *client);
616
627int mqtt_publish(struct mqtt_client *client,
628 const struct mqtt_publish_param *param);
629
642 const struct mqtt_puback_param *param);
643
656 const struct mqtt_pubrec_param *param);
657
669 const struct mqtt_pubrel_param *param);
670
683 const struct mqtt_pubcomp_param *param);
684
694int mqtt_subscribe(struct mqtt_client *client,
695 const struct mqtt_subscription_list *param);
696
709int mqtt_unsubscribe(struct mqtt_client *client,
710 const struct mqtt_subscription_list *param);
711
721int mqtt_ping(struct mqtt_client *client);
722
731int mqtt_disconnect(struct mqtt_client *client);
732
743int mqtt_abort(struct mqtt_client *client);
744
759int mqtt_live(struct mqtt_client *client);
760
771int mqtt_keepalive_time_left(const struct mqtt_client *client);
772
788int mqtt_input(struct mqtt_client *client);
789
805int mqtt_read_publish_payload(struct mqtt_client *client, void *buffer,
806 size_t length);
807
819int mqtt_read_publish_payload_blocking(struct mqtt_client *client, void *buffer,
820 size_t length);
821
835 size_t length);
836
837#ifdef __cplusplus
838}
839#endif
840
841#endif /* ZEPHYR_INCLUDE_NET_MQTT_H_ */
842
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:385
@ 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:410
@ MQTT_TRANSPORT_NON_SECURE
Use non secure TCP transport for MQTT connection.
Definition: mqtt.h:387
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:494
struct mqtt_internal internal
MQTT client internal state.
Definition: mqtt.h:496
mqtt_evt_cb_t evt_cb
Application callback registered with the module to get MQTT events.
Definition: mqtt.h:530
struct mqtt_topic * will_topic
Will topic and QoS.
Definition: mqtt.h:521
uint32_t tx_buf_size
Size of transmit buffer.
Definition: mqtt.h:542
uint8_t protocol_version
MQTT protocol version.
Definition: mqtt.h:550
uint32_t rx_buf_size
Size of receive buffer.
Definition: mqtt.h:536
int8_t unacked_ping
Unanswered PINGREQ count on this connection.
Definition: mqtt.h:553
const void * broker
Broker details, for example, address, port.
Definition: mqtt.h:507
struct mqtt_utf8 * will_message
Will message.
Definition: mqtt.h:526
uint8_t * rx_buf
Receive buffer used for MQTT packet reception in RX path.
Definition: mqtt.h:533
uint16_t keepalive
Keepalive interval for this client in seconds.
Definition: mqtt.h:547
struct mqtt_utf8 client_id
Unique client identification to be used for the connection.
Definition: mqtt.h:502
uint8_t clean_session
Clean session flag indicating a fresh (1) or a retained session (0).
Definition: mqtt.h:562
struct mqtt_utf8 * user_name
User name (if any) to be used for the connection.
Definition: mqtt.h:512
struct mqtt_transport transport
MQTT transport configuration and data.
Definition: mqtt.h:499
uint8_t will_retain
Will retain flag, 1 if will message shall be retained persistently.
Definition: mqtt.h:557
uint8_t * tx_buf
Transmit buffer used for creating MQTT packet in TX path.
Definition: mqtt.h:539
struct mqtt_utf8 * password
Password (if any) to be used for the connection.
Definition: mqtt.h:518
void * user_data
User specific opaque data.
Definition: mqtt.h:565
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:471
uint32_t rx_buf_datalen
Internal.
Definition: mqtt.h:484
uint32_t last_activity
Internal.
Definition: mqtt.h:478
uint32_t remaining_payload
Internal.
Definition: mqtt.h:487
uint32_t state
Internal.
Definition: mqtt.h:481
struct sys_mutex mutex
Internal.
Definition: mqtt.h:473
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:381
uint32_t sec_tag_count
Indicates the number of entries in the sec tag list.
Definition: mqtt.h:357
const sec_tag_t * sec_tag_list
Indicates the list of security tags to be used for the session.
Definition: mqtt.h:360
const char * hostname
Peer hostname for ceritificate verification.
Definition: mqtt.h:378
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:414
int sock
Socket descriptor.
Definition: mqtt.h:426
enum mqtt_transport_type type
Transport type selection for client instance.
Definition: mqtt.h:419
struct mqtt_transport::@329::@331 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.