mqtt.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_NET_MQTT_H_
#define ZEPHYR_INCLUDE_NET_MQTT_H_
 
#include <stddef.h>
 
#include <zephyr/kernel.h>
#include <zephyr/types.h>
#include <zephyr/net/tls_credentials.h>
#include <zephyr/net/net_ip.h>
#include <zephyr/sys/mutex.h>
#include <zephyr/net/websocket.h>
 
#ifdef __cplusplus
extern "C" {
#endif

enum mqtt_evt_type {
        MQTT_EVT_CONNACK,

        MQTT_EVT_DISCONNECT,

        MQTT_EVT_PUBLISH,

        MQTT_EVT_PUBACK,

        MQTT_EVT_PUBREC,

        MQTT_EVT_PUBREL,

        MQTT_EVT_PUBCOMP,

        MQTT_EVT_SUBACK,

        MQTT_EVT_UNSUBACK,

        MQTT_EVT_PINGRESP,
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        MQTT_EVT_AUTH,
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

enum mqtt_version {
        MQTT_VERSION_3_1_0 = 3, 
        MQTT_VERSION_3_1_1 = 4, 
        MQTT_VERSION_5_0 = 5,   
};

enum mqtt_qos {
        MQTT_QOS_0_AT_MOST_ONCE = 0x00,

        MQTT_QOS_1_AT_LEAST_ONCE = 0x01,

        MQTT_QOS_2_EXACTLY_ONCE  = 0x02
};
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
enum mqtt_retain_handling {
        MQTT_RH_0_SEND_AT_SUBSCRIBE = 0x00,

        MQTT_RH_1_SEND_IF_NEW = 0x01,

        MQTT_RH_2_DO_NOT_SEND = 0x02
};
#endif /* CONFIG_MQTT_VERSION_5_0 */

enum mqtt_conn_return_code {
        MQTT_CONNECTION_ACCEPTED                = 0x00,

        MQTT_UNACCEPTABLE_PROTOCOL_VERSION      = 0x01,

        MQTT_IDENTIFIER_REJECTED                = 0x02,

        MQTT_SERVER_UNAVAILABLE                 = 0x03,

        MQTT_BAD_USER_NAME_OR_PASSWORD          = 0x04,

        MQTT_NOT_AUTHORIZED                     = 0x05
};

enum mqtt_connack_reason_code {
        MQTT_CONNACK_SUCCESS = 0,
        MQTT_CONNACK_UNSPECIFIED_ERROR = 128,
        MQTT_CONNACK_MALFORMED_PACKET = 129,
        MQTT_CONNACK_PROTOCOL_ERROR = 130,
        MQTT_CONNACK_IMPL_SPECIFIC_ERROR = 131,
        MQTT_CONNACK_UNSUPPORTED_PROTO_ERROR = 132,
        MQTT_CONNACK_CLIENT_ID_NOT_VALID = 133,
        MQTT_CONNACK_BAD_USERNAME_OR_PASS = 134,
        MQTT_CONNACK_NOT_AUTHORIZED = 135,
        MQTT_CONNACK_SERVER_UNAVAILABLE = 136,
        MQTT_CONNACK_SERVER_BUSY = 137,
        MQTT_CONNACK_BANNED = 138,
        MQTT_CONNACK_BAD_AUTH_METHOD = 140,
        MQTT_CONNACK_TOPIC_NAME_INVALID = 144,
        MQTT_CONNACK_PACKET_TOO_LARGE = 149,
        MQTT_CONNACK_QUOTA_EXCEEDED = 151,
        MQTT_CONNACK_PAYLOAD_FORMAT_INVALID = 153,
        MQTT_CONNACK_RETAIN_NOT_SUPPORTED = 154,
        MQTT_CONNACK_QOS_NOT_SUPPORTED = 155,
        MQTT_CONNACK_USE_ANOTHER_SERVER = 156,
        MQTT_CONNACK_SERVER_MOVED = 157,
        MQTT_CONNACK_CONNECTION_RATE_EXCEEDED = 159,
};

enum mqtt_suback_return_code {
        MQTT_SUBACK_SUCCESS_QoS_0 = 0x00,

        MQTT_SUBACK_SUCCESS_QoS_1 = 0x01,

        MQTT_SUBACK_SUCCESS_QoS_2 = 0x02,

        MQTT_SUBACK_FAILURE = 0x80
};

enum mqtt_disconnect_reason_code {
        MQTT_DISCONNECT_NORMAL = 0,
        MQTT_DISCONNECT_WITH_WILL_MSG = 4,
        MQTT_DISCONNECT_UNSPECIFIED_ERROR = 128,
        MQTT_DISCONNECT_MALFORMED_PACKET = 129,
        MQTT_DISCONNECT_PROTOCOL_ERROR = 130,
        MQTT_DISCONNECT_IMPL_SPECIFIC_ERROR = 131,
        MQTT_DISCONNECT_NOT_AUTHORIZED = 135,
        MQTT_DISCONNECT_SERVER_BUSY = 137,
        MQTT_DISCONNECT_SERVER_SHUTTING_DOWN = 139,
        MQTT_DISCONNECT_KEEP_ALIVE_TIMEOUT = 141,
        MQTT_DISCONNECT_SESSION_TAKE_OVER = 142,
        MQTT_DISCONNECT_TOPIC_FILTER_INVALID = 143,
        MQTT_DISCONNECT_TOPIC_NAME_INVALID = 144,
        MQTT_DISCONNECT_RECV_MAX_EXCEEDED = 147,
        MQTT_DISCONNECT_TOPIC_ALIAS_INVALID = 148,
        MQTT_DISCONNECT_PACKET_TOO_LARGE = 149,
        MQTT_DISCONNECT_MESSAGE_RATE_TOO_HIGH = 150,
        MQTT_DISCONNECT_QUOTA_EXCEEDED = 151,
        MQTT_DISCONNECT_ADMIN_ACTION = 152,
        MQTT_DISCONNECT_PAYLOAD_FORMAT_INVALID = 153,
        MQTT_DISCONNECT_RETAIN_NOT_SUPPORTED = 154,
        MQTT_DISCONNECT_QOS_NOT_SUPPORTED = 155,
        MQTT_DISCONNECT_USE_ANOTHER_SERVER = 156,
        MQTT_DISCONNECT_SERVER_MOVED = 157,
        MQTT_DISCONNECT_SHARED_SUB_NOT_SUPPORTED = 158,
        MQTT_DISCONNECT_CONNECTION_RATE_EXCEEDED = 159,
        MQTT_DISCONNECT_MAX_CONNECT_TIME = 160,
        MQTT_DISCONNECT_SUB_ID_NOT_SUPPORTED = 161,
        MQTT_DISCONNECT_WILDCARD_SUB_NOT_SUPPORTED = 162,
};

enum mqtt_auth_reason_code {
        MQTT_AUTH_SUCCESS = 0,
        MQTT_AUTH_CONTINUE_AUTHENTICATION = 24,
        MQTT_AUTH_RE_AUTHENTICATE = 25,
};

struct mqtt_utf8 {
        const uint8_t *utf8;       
        uint32_t size;             
};

#define MQTT_UTF8_LITERAL(literal)                              \
        ((struct mqtt_utf8) {literal, sizeof(literal) - 1})

struct mqtt_binstr {
        uint8_t *data;             
        uint32_t len;              
};

struct mqtt_topic_alias {
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        uint8_t topic_buf[CONFIG_MQTT_TOPIC_ALIAS_STRING_MAX];

        uint16_t topic_size;
#elif defined(CONFIG_CPP)
        /* C++ does not allow empty structs, add an extra 1 byte. */
        uint8_t c;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_topic {
        struct mqtt_utf8 topic;

        uint8_t qos;
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        uint8_t no_local;
        uint8_t retain_as_published;
        uint8_t retain_handling;
#endif
};

struct mqtt_utf8_pair {
        struct mqtt_utf8 name;
        struct mqtt_utf8 value;
};

struct mqtt_publish_message {
        struct mqtt_topic topic;     
        struct mqtt_binstr payload; 
};

struct mqtt_connack_param {
        uint8_t session_present_flag;

        uint8_t return_code;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        struct {
                struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];

                struct mqtt_utf8 assigned_client_id;

                struct mqtt_utf8 reason_string;

                struct mqtt_utf8 response_information;

                struct mqtt_utf8 server_reference;

                struct mqtt_utf8 auth_method;

                struct mqtt_binstr auth_data;

                uint32_t session_expiry_interval;

                uint32_t maximum_packet_size;

                uint16_t receive_maximum;

                uint16_t topic_alias_maximum;

                uint16_t server_keep_alive;

                uint8_t maximum_qos;

                uint8_t retain_available;

                uint8_t wildcard_sub_available;

                uint8_t subscription_ids_available;

                uint8_t shared_sub_available;

                struct {
                        bool has_session_expiry_interval;
                        bool has_receive_maximum;
                        bool has_maximum_qos;
                        bool has_retain_available;
                        bool has_maximum_packet_size;
                        bool has_assigned_client_id;
                        bool has_topic_alias_maximum;
                        bool has_reason_string;
                        bool has_user_prop;
                        bool has_wildcard_sub_available;
                        bool has_subscription_ids_available;
                        bool has_shared_sub_available;
                        bool has_server_keep_alive;
                        bool has_response_information;
                        bool has_server_reference;
                        bool has_auth_method;
                        bool has_auth_data;
                } rx;
        } prop;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_common_ack_properties {
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];

        struct mqtt_utf8 reason_string;

        struct {
                bool has_reason_string;
                bool has_user_prop;
        } rx;
#elif defined(CONFIG_CPP)
        /* C++ does not allow empty structs, add an extra 1 byte. */
        uint8_t c;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_puback_param {
        uint16_t message_id;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        uint8_t reason_code;

        struct mqtt_common_ack_properties prop;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_pubrec_param {
        uint16_t message_id;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        uint8_t reason_code;

        struct mqtt_common_ack_properties prop;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_pubrel_param {
        uint16_t message_id;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        uint8_t reason_code;

        struct mqtt_common_ack_properties prop;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_pubcomp_param {
        uint16_t message_id;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        uint8_t reason_code;

        struct mqtt_common_ack_properties prop;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_suback_param {
        uint16_t message_id;

        struct mqtt_binstr return_codes;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        struct mqtt_common_ack_properties prop;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_unsuback_param {
        uint16_t message_id;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        struct mqtt_binstr reason_codes;

        struct mqtt_common_ack_properties prop;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_publish_param {
        struct mqtt_publish_message message;

        uint16_t message_id;

        uint8_t dup_flag : 1;

        uint8_t retain_flag : 1;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        struct {
                struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];

                struct mqtt_utf8 response_topic;

                struct mqtt_binstr correlation_data;

                struct mqtt_utf8 content_type;

                uint32_t subscription_identifier[CONFIG_MQTT_SUBSCRIPTION_ID_PROPERTIES_MAX];

                uint32_t message_expiry_interval;

                uint16_t topic_alias;

                uint8_t payload_format_indicator;

                struct {
                        bool has_payload_format_indicator;
                        bool has_message_expiry_interval;
                        bool has_topic_alias;
                        bool has_response_topic;
                        bool has_correlation_data;
                        bool has_user_prop;
                        bool has_subscription_identifier;
                        bool has_content_type;
                } rx;
        } prop;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_subscription_list {
        const struct mqtt_topic *list;

        uint16_t list_count;

        uint16_t message_id;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        struct {
                struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];

                uint32_t subscription_identifier;
        } prop;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_disconnect_param {
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        /* MQTT 5.0 Disconnect reason code. */
        enum mqtt_disconnect_reason_code reason_code;

        struct {
                struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];

                struct mqtt_utf8 reason_string;

                struct mqtt_utf8 server_reference;

                uint32_t session_expiry_interval;

                struct {
                        bool has_session_expiry_interval;
                        bool has_reason_string;
                        bool has_user_prop;
                        bool has_server_reference;
                } rx;
        } prop;
#elif defined(CONFIG_CPP)
        /* C++ does not allow empty structs, add an extra 1 byte. */
        uint8_t c;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_auth_param {
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        /* MQTT 5.0, chapter 3.15.2.1 Authenticate Reason Code */
        enum mqtt_auth_reason_code reason_code;
 
        struct {
                struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];

                struct mqtt_utf8 auth_method;

                struct mqtt_binstr auth_data;

                struct mqtt_utf8 reason_string;

                struct {
                        bool has_auth_method;
                        bool has_auth_data;
                        bool has_reason_string;
                        bool has_user_prop;
                } rx;
        } prop;
#elif defined(CONFIG_CPP)
        /* C++ does not allow empty structs, add an extra 1 byte. */
        uint8_t c;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

union mqtt_evt_param {
        struct mqtt_connack_param connack;

        struct mqtt_publish_param publish;

        struct mqtt_puback_param puback;

        struct mqtt_pubrec_param pubrec;

        struct mqtt_pubrel_param pubrel;

        struct mqtt_pubcomp_param pubcomp;

        struct mqtt_suback_param suback;

        struct mqtt_unsuback_param unsuback;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        struct mqtt_disconnect_param disconnect;

        struct mqtt_auth_param auth;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_evt {
        enum mqtt_evt_type type;

        union mqtt_evt_param param;

        int result;
};
 
struct mqtt_client;

typedef void (*mqtt_evt_cb_t)(struct mqtt_client *client,
                              const struct mqtt_evt *evt);

struct mqtt_sec_config {
        int peer_verify;

        uint32_t cipher_count;

        const int *cipher_list;

        uint32_t sec_tag_count;

        const sec_tag_t *sec_tag_list;
 
#if defined(CONFIG_MQTT_LIB_TLS_USE_ALPN)
        const char **alpn_protocol_name_list;

        uint32_t alpn_protocol_name_count;
#endif

        const char *hostname;

        int cert_nocopy;

        bool set_native_tls;
};

enum mqtt_transport_type {
        MQTT_TRANSPORT_NON_SECURE,
 
#if defined(CONFIG_MQTT_LIB_TLS)
        MQTT_TRANSPORT_SECURE,
#endif /* CONFIG_MQTT_LIB_TLS */
 
#if defined(CONFIG_MQTT_LIB_WEBSOCKET)
        MQTT_TRANSPORT_NON_SECURE_WEBSOCKET,
#if defined(CONFIG_MQTT_LIB_TLS)
        MQTT_TRANSPORT_SECURE_WEBSOCKET,
#endif
#endif /* CONFIG_MQTT_LIB_WEBSOCKET */
#if defined(CONFIG_MQTT_LIB_CUSTOM_TRANSPORT)
        MQTT_TRANSPORT_CUSTOM,
#endif /* CONFIG_MQTT_LIB_CUSTOM_TRANSPORT */

        MQTT_TRANSPORT_NUM
};

struct mqtt_transport {
        enum mqtt_transport_type type;

        const char *if_name;

        union {
                struct {
                        int sock;
                } tcp;
 
#if defined(CONFIG_MQTT_LIB_TLS)
                struct {
                        int sock;

                        struct mqtt_sec_config config;
                } tls;
#endif /* CONFIG_MQTT_LIB_TLS */
        };
 
#if defined(CONFIG_MQTT_LIB_WEBSOCKET)
        struct {
                struct websocket_request config;

                int sock;

                int32_t timeout;
        } websocket;
#endif
 
#if defined(CONFIG_MQTT_LIB_CUSTOM_TRANSPORT)
        void *custom_transport_data;
#endif /* CONFIG_MQTT_LIB_CUSTOM_TRANSPORT */
 
#if defined(CONFIG_SOCKS)
        struct {
                union {
                        struct net_sockaddr_storage addr_storage;
                        /* Use the addr_storage instead of this one. */
                        struct net_sockaddr addr;
                };
                net_socklen_t addrlen;
        } proxy;
#endif
};

struct mqtt_internal {
        struct sys_mutex mutex;

        uint32_t last_activity;

        uint32_t state;

        uint32_t rx_buf_datalen;

        uint32_t remaining_payload;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        struct mqtt_topic_alias topic_aliases[CONFIG_MQTT_TOPIC_ALIAS_MAX];

        enum mqtt_disconnect_reason_code disconnect_reason;
#endif /* CONFIG_MQTT_VERSION_5_0 */
};

struct mqtt_client {
        struct mqtt_internal internal;

        struct mqtt_transport transport;

        struct mqtt_utf8 client_id;

        const void *broker;

        struct mqtt_utf8 *user_name;

        struct mqtt_utf8 *password;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        struct {
                struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];

                struct mqtt_utf8 content_type;

                struct mqtt_utf8 response_topic;

                struct mqtt_binstr correlation_data;

                uint32_t will_delay_interval;

                uint32_t message_expiry_interval;

                uint8_t payload_format_indicator;
        } will_prop;
#endif /* CONFIG_MQTT_VERSION_5_0 */

        struct mqtt_topic *will_topic;

        struct mqtt_utf8 *will_message;

        mqtt_evt_cb_t evt_cb;

        uint8_t *rx_buf;

        uint32_t rx_buf_size;

        uint8_t *tx_buf;

        uint32_t tx_buf_size;

        uint16_t keepalive;

        uint8_t protocol_version;

        int8_t unacked_ping;
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
        struct {
                struct mqtt_utf8_pair user_prop[CONFIG_MQTT_USER_PROPERTIES_MAX];

                struct mqtt_utf8 auth_method;

                struct mqtt_binstr auth_data;

                uint32_t session_expiry_interval;

                uint32_t maximum_packet_size;

                uint16_t receive_maximum;

                bool request_response_info;

                bool request_problem_info;
        } prop;
#endif /* CONFIG_MQTT_VERSION_5_0 */

        uint8_t will_retain : 1;

        uint8_t clean_session : 1;

        void *user_data;
};

void mqtt_client_init(struct mqtt_client *client);
 
#if defined(CONFIG_SOCKS)
/*
 * @brief Set proxy server details
 *
 * @param[in] client Client instance for which the procedure is requested,
 *                   Shall not be NULL.
 * @param[in] proxy_addr Proxy server address.
 * @param[in] addrlen Proxy server address length.
 *
 * @return 0 or a negative error code (errno.h) indicating reason of failure.
 *
 * @note Must be called before calling mqtt_connect().
 */
int mqtt_client_set_proxy(struct mqtt_client *client,
                          struct net_sockaddr *proxy_addr,
                          net_socklen_t addrlen);
#endif

int mqtt_connect(struct mqtt_client *client);

int mqtt_publish(struct mqtt_client *client,
                 const struct mqtt_publish_param *param);

int mqtt_publish_qos1_ack(struct mqtt_client *client,
                          const struct mqtt_puback_param *param);

int mqtt_publish_qos2_receive(struct mqtt_client *client,
                              const struct mqtt_pubrec_param *param);

int mqtt_publish_qos2_release(struct mqtt_client *client,
                              const struct mqtt_pubrel_param *param);

int mqtt_publish_qos2_complete(struct mqtt_client *client,
                               const struct mqtt_pubcomp_param *param);

int mqtt_subscribe(struct mqtt_client *client,
                   const struct mqtt_subscription_list *param);

int mqtt_unsubscribe(struct mqtt_client *client,
                     const struct mqtt_subscription_list *param);

int mqtt_ping(struct mqtt_client *client);

int mqtt_disconnect(struct mqtt_client *client,
                    const struct mqtt_disconnect_param *param);
 
#if defined(CONFIG_MQTT_VERSION_5_0) || defined(__DOXYGEN__)
int mqtt_auth(struct mqtt_client *client, const struct mqtt_auth_param *param);
#endif /* CONFIG_MQTT_VERSION_5_0 */

int mqtt_abort(struct mqtt_client *client);

int mqtt_live(struct mqtt_client *client);

int mqtt_keepalive_time_left(const struct mqtt_client *client);

int mqtt_input(struct mqtt_client *client);

int mqtt_read_publish_payload(struct mqtt_client *client, void *buffer,
                              size_t length);

int mqtt_read_publish_payload_blocking(struct mqtt_client *client, void *buffer,
                                       size_t length);

int mqtt_readall_publish_payload(struct mqtt_client *client, uint8_t *buffer,
                                 size_t length);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_NET_MQTT_H_ */