lws-mqtt.h

Go to the documentation of this file.

/*
 * libwebsockets - protocol - mqtt
 *
 * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 *
 * included from libwebsockets.h
 */
 
#ifndef _LWS_MQTT_H
#define _LWS_MQTT_H 1
 
struct _lws_mqtt_related;
typedef struct _lws_mqtt_related lws_mqtt_related_t;
struct lws_mqtt_str_st;
typedef struct lws_mqtt_str_st lws_mqtt_str_t;
 
#define MQTT_VER_3_1_1 4
#if MQTT_VER_3_1_1 == 4
        #define MQTT_VER_STRING "3.1.1"
#else
        #define MQTT_VER_STRING "unknown"
#endif
 
#define LWS_MQTT_FINAL_PART 1
 
#define LWS_MQTT_MAX_AWSIOT_TOPICLEN  256
#define LWS_MQTT_MAX_TOPICLEN  65535
#define LWS_MQTT_MAX_CIDLEN    128
#define LWS_MQTT_RANDOM_CIDLEN 23 /* 3.1.3.1-5: Server MUST... between
                                     1 and 23 chars... */
 
#define LWS_MQTT_SHADOW_MAX_THING_LEN 128
#define LWS_MQTT_SHADOW_MAX_SHADOW_LEN 64
#define LWS_MQTT_SHADOW_UPDATE_STR "/update"
#define LWS_MQTT_SHADOW_DELETE_STR "/delete"
#define LWS_MQTT_SHADOW_GET_STR "/get"
#define LWS_MQTT_SHADOW_RESP_ACCEPTED_STR  "/accepted"
#define LWS_MQTT_SHADOW_RESP_REJECTED_STR "/rejected"
#define LWS_MQTT_SHADOW_RESP_DELTA_STR "/delta"
#define LWS_MQTT_SHADOW_RESP_DOCUMENT_STR "/documents"
#define LWS_MQTT_SHADOW_UPDATE_ACCEPTED_STR LWS_MQTT_SHADOW_UPDATE_STR LWS_MQTT_SHADOW_RESP_ACCEPTED_STR
#define LWS_MQTT_SHADOW_UPDATE_REJECTED_STR LWS_MQTT_SHADOW_UPDATE_STR LWS_MQTT_SHADOW_RESP_REJECTED_STR
#define LWS_MQTT_SHADOW_UPDATE_DELTA_STR LWS_MQTT_SHADOW_UPDATE_STR LWS_MQTT_SHADOW_RESP_DELTA_STR
#define LWS_MQTT_SHADOW_UPDATE_DOCUMENT_STR LWS_MQTT_SHADOW_UPDATE_STR LWS_MQTT_SHADOW_RESP_DOCUMENT_STR
#define LWS_MQTT_SHADOW_DELETE_ACCEPTED_STR LWS_MQTT_SHADOW_DELETE_STR LWS_MQTT_SHADOW_RESP_ACCEPTED_STR
#define LWS_MQTT_SHADOW_DELETE_REJECTED_STR LWS_MQTT_SHADOW_DELETE_STR LWS_MQTT_SHADOW_RESP_REJECTED_STR
#define LWS_MQTT_SHADOW_GET_ACCEPTED_STR LWS_MQTT_SHADOW_GET_STR LWS_MQTT_SHADOW_RESP_ACCEPTED_STR
#define LWS_MQTT_SHADOW_GET_REJECTED_STR LWS_MQTT_SHADOW_GET_STR LWS_MQTT_SHADOW_RESP_REJECTED_STR
#define LWS_MQTT_SHADOW_PREFIX_FORMAT "$aws/things/%s"
#define LWS_MQTT_SHADOW_NAMED_SHADOW_TOPIC_FORMAT LWS_MQTT_SHADOW_PREFIX_FORMAT "/shadow/name/%s%s"
#define LWS_MQTT_SHADOW_UNNAMED_SHADOW_TOPIC_FORMAT  LWS_MQTT_SHADOW_PREFIX_FORMAT "/shadow%s"
#define LWS_MQTT_SHADOW_UNNAMED_TOPIC_MATCH     "$aws/things/+/shadow/+"
#define LWS_MQTT_SHADOW_NAMED_TOPIC_MATCH       "$aws/things/+/shadow/name/+/+"
 
typedef enum {
        QOS0,
        QOS1,
        QOS2,                               /* not supported */
        RESERVED_QOS_LEVEL,
        FAILURE_QOS_LEVEL = 0x80
} lws_mqtt_qos_levels_t;
 
typedef union {
        struct {
                uint8_t          retain:1;
                uint8_t  qos:2;
                uint8_t  dup:1;
                uint8_t  ctrl_pkt_type:4;
        } flags;
        uint8_t          bits;
} lws_mqtt_fixed_hdr_t;
 
/*
 * MQTT connection parameters, passed into struct
 * lws_client_connect_info to establish a connection using
 * lws_client_connect_via_info().
*/
typedef struct lws_mqtt_client_connect_param_s {
        const char                      *client_id;    /* Client ID */
        uint16_t                        keep_alive;   /* MQTT keep alive
                                                           interval in
                                                           seconds */
        uint8_t                  clean_start:1;       /* MQTT clean
                                                           session */
        uint8_t                          client_id_nofree:1;
        uint8_t                          username_nofree:1;
        uint8_t                          password_nofree:1;
        /**< do not free the password */
        struct {
                const char              *topic;
                const char              *message;
                lws_mqtt_qos_levels_t      qos;
                uint8_t          retain;
        } will_param;                         /* MQTT LWT
                                                   parameters */
        struct {
                const char              *topic;
                const char              *message;
                lws_mqtt_qos_levels_t      qos;
                uint8_t          retain;
        } birth_param;                               /* MQTT Birth
                                                   parameters */
        const char                      *username;
        const char                      *password;
        uint8_t                          aws_iot;
} lws_mqtt_client_connect_param_t;
 
/*
 * MQTT publish parameters
*/
typedef struct lws_mqtt_publish_param_s {
        char                    *topic;            /* Topic Name */
        uint16_t                topic_len;
        const void              *payload;        /* Publish Payload */
        uint32_t                payload_len; /* Size of the
                                                   complete payload */
        uint32_t                payload_pos; /* where we are in payload */
        lws_mqtt_qos_levels_t      qos;
 
        /*--v-Following will be used by LWS-v--*/
        uint16_t                packet_id;     /* Packet ID for QoS >
                                                   0 */
        uint8_t          dup:1;               /* Retried PUBLISH,
                                                   for QoS > 0 */
        uint8_t                  retain:1; /* Retained message */
} lws_mqtt_publish_param_t;
 
typedef struct topic_elem {
        const char              *name;              /* Topic Name */
        lws_mqtt_qos_levels_t      qos;         /* Requested QoS */
 
        /*--v-Following will be used by LWS-v--*/
        uint8_t          acked;
} lws_mqtt_topic_elem_t;
 
/*
 * MQTT publish parameters
*/
typedef struct lws_mqtt_subscribe_param_s {
        uint32_t                num_topics;   /* Number of topics */
        lws_mqtt_topic_elem_t      *topic;            /* Array of topic elements */
 
        /*--v-Following will be used by LWS-v--*/
        uint16_t                packet_id;
} lws_mqtt_subscribe_param_t;
 
typedef enum {
        LMQCP_RESERVED,
        LMQCP_CTOS_CONNECT,   /* Connection request */
        LMQCP_STOC_CONNACK,   /* Connection acknowledgment */
        LMQCP_PUBLISH,             /* Publish Message */
        LMQCP_PUBACK,               /* QoS 1:   Publish acknowledgment */
        LMQCP_PUBREC,               /* QoS 2.1: Publish received */
        LMQCP_PUBREL,               /* QoS 2.2: Publish release */
        LMQCP_PUBCOMP,             /* QoS 2.3: Publish complete */
        LMQCP_CTOS_SUBSCRIBE,       /* Subscribe request */
        LMQCP_STOC_SUBACK,     /* Subscribe acknowledgment */
        LMQCP_CTOS_UNSUBSCRIBE, /* Unsubscribe request */
        LMQCP_STOC_UNSUBACK, /* Unsubscribe acknowledgment */
        LMQCP_CTOS_PINGREQ,   /* PING request */
        LMQCP_STOC_PINGRESP, /* PONG response */
        LMQCP_DISCONNECT,       /* Disconnect notification */
        LMQCP_AUTH            /* Authentication exchange */
} lws_mqtt_control_packet_t;
 
/* flags from byte 8 of C_TO_S CONNECT */
typedef enum {
        LMQCFT_USERNAME_NOFREE                                    = (1 << 10),
        LMQCFT_PASSWORD_NOFREE                                    = (1 << 9),
        LMQCFT_CLIENT_ID_NOFREE                                  = (1 << 8),
        /* only the low 8 are standardized and go out in the protocol */
        LMQCFT_USERNAME                                          = (1 << 7),
        LMQCFT_PASSWORD                                          = (1 << 6),
        LMQCFT_WILL_RETAIN                                    = (1 << 5),
        LMQCFT_WILL_QOS                                          = (1 << 3),
        LMQCFT_WILL_FLAG                                        = (1 << 2),
        LMQCFT_CLEAN_START                                    = (1 << 1),
        LMQCFT_RESERVED                                          = (1 << 0),
 
        LMQCFT_WILL_QOS_MASK                                        = (3 << 3),
} lws_mqtt_connect_flags_t;
 
/* flags for S_TO_C CONNACK */
typedef enum {
        LMQCFT_SESSION_PRESENT                                    = (1 << 0),
} lws_mqtt_connack_flags_t;
 
typedef enum {
        LMQCP_REASON_SUCCESS                                        = 0x00,
        LMQCP_REASON_NORMAL_DISCONNECTION                      = 0x00,
        LMQCP_REASON_GRANTED_QOS0                              = 0x00,
        LMQCP_REASON_GRANTED_QOS1                              = 0x01,
        LMQCP_REASON_GRANTED_QOS2                              = 0x02,
        LMQCP_REASON_DISCONNECT_WILL                                = 0x04,
        LMQCP_REASON_NO_MATCHING_SUBSCRIBER                  = 0x10,
        LMQCP_REASON_NO_SUBSCRIPTION_EXISTED                        = 0x11,
        LMQCP_REASON_CONTINUE_AUTHENTICATION                        = 0x18,
        LMQCP_REASON_RE_AUTHENTICATE                                = 0x19,
 
        LMQCP_REASON_UNSPECIFIED_ERROR                            = 0x80,
        LMQCP_REASON_MALFORMED_PACKET                              = 0x81,
        LMQCP_REASON_PROTOCOL_ERROR                          = 0x82,
        LMQCP_REASON_IMPLEMENTATION_SPECIFIC_ERROR            = 0x83,
 
        /* Begin - Error codes for CONNACK */
        LMQCP_REASON_UNSUPPORTED_PROTOCOL                      = 0x84,
        LMQCP_REASON_CLIENT_ID_INVALID                            = 0x85,
        LMQCP_REASON_BAD_CREDENTIALS                                = 0x86,
        LMQCP_REASON_NOT_AUTHORIZED                          = 0x87,
        /* End - Error codes for CONNACK */
 
        LMQCP_REASON_SERVER_UNAVAILABLE                          = 0x88,
        LMQCP_REASON_SERVER_BUSY                                = 0x89,
        LMQCP_REASON_BANNED                                  = 0x8a,
        LMQCP_REASON_SERVER_SHUTTING_DOWN                      = 0x8b,
        LMQCP_REASON_BAD_AUTHENTICATION_METHOD                    = 0x8c,
        LMQCP_REASON_KEEPALIVE_TIMEOUT                            = 0x8d,
        LMQCP_REASON_SESSION_TAKEN_OVER                          = 0x8e,
        LMQCP_REASON_TOPIC_FILTER_INVALID                      = 0x8f,
        LMQCP_REASON_TOPIC_NAME_INVALID                          = 0x90,
        LMQCP_REASON_PACKET_ID_IN_USE                              = 0x91,
        LMQCP_REASON_PACKET_ID_NOT_FOUND                        = 0x92,
        LMQCP_REASON_MAX_RX_EXCEEDED                                = 0x93,
        LMQCP_REASON_TOPIC_ALIAS_INVALID                        = 0x94,
        LMQCP_REASON_PACKET_TOO_LARGE                              = 0x95,
        LMQCP_REASON_RATELIMIT                                    = 0x96,
        LMQCP_REASON_QUOTA_EXCEEDED                          = 0x97,
        LMQCP_REASON_ADMINISTRATIVE_ACTION                    = 0x98,
        LMQCP_REASON_PAYLOAD_FORMAT_INVALID                  = 0x99,
        LMQCP_REASON_RETAIN_NOT_SUPPORTED                      = 0x9a,
        LMQCP_REASON_QOS_NOT_SUPPORTED                            = 0x9b,
        LMQCP_REASON_USE_ANOTHER_SERVER                          = 0x9c,
        LMQCP_REASON_SERVER_MOVED                              = 0x9d,
        LMQCP_REASON_SHARED_SUBSCRIPTIONS_NOT_SUPPORTED          = 0x9e,
        LMQCP_REASON_CONNECTION_RATE_EXCEEDED                      = 0x9f,
        LMQCP_REASON_MAXIMUM_CONNECT_TIME                      = 0xa0,
        LMQCP_REASON_SUBSCRIPTION_IDS_NOT_SUPPORTED          = 0xa1,
        LMQCP_REASON_WILDCARD_SUBSCRIPTIONS_NOT_SUPPORTED      = 0xa2,
} lws_mqtt_reason_t;
 
typedef enum {
        LMQPROP_INVALID,
        LMQPROP_PAYLOAD_FORMAT_INDICATOR                        = 0x01,
        LMQPROP_MESSAGE_EXPIRY_INTERVAL                          = 0x02,
        LMQPROP_CONTENT_TYPE                                        = 0x03,
        LMQPROP_RESPONSE_TOPIC                                    = 0x08,
        LMQPROP_CORRELATION_DATA                                = 0x09,
        LMQPROP_SUBSCRIPTION_IDENTIFIER                          = 0x0b,
        LMQPROP_SESSION_EXPIRY_INTERVAL                          = 0x11,
        LMQPROP_ASSIGNED_CLIENT_IDENTIFIER                    = 0x12,
        LMQPROP_SERVER_KEEP_ALIVE                              = 0x13,
        LMQPROP_AUTHENTICATION_METHOD                              = 0x15,
        LMQPROP_AUTHENTICATION_DATA                          = 0x16,
        LMQPROP_REQUEST_PROBLEM_INFORMATION                  = 0x17,
        LMQPROP_WILL_DELAY_INTERVAL                          = 0x18,
        LMQPROP_REQUEST_RESPONSE_INFORMATION                        = 0x19,
        LMQPROP_RESPONSE_INFORMATION                                = 0x1a,
        LMQPROP_SERVER_REFERENCE                                = 0x1c,
        LMQPROP_REASON_STRING                                      = 0x1f,
        LMQPROP_RECEIVE_MAXIMUM                                  = 0x21,
        LMQPROP_TOPIC_ALIAS_MAXIMUM                          = 0x22,
        LMQPROP_TOPIC_ALIAS                                  = 0x23,
        LMQPROP_MAXIMUM_QOS                                  = 0x24,
        LMQPROP_RETAIN_AVAILABLE                                = 0x25,
        LMQPROP_USER_PROPERTY                                      = 0x26,
        LMQPROP_MAXIMUM_PACKET_SIZE                          = 0x27,
        LMQPROP_WILDCARD_SUBSCRIPTION_AVAIL                  = 0x28,
        LMQPROP_SUBSCRIPTION_IDENTIFIER_AVAIL                      = 0x29,
        LMQPROP_SHARED_SUBSCRIPTION_AVAIL                      = 0x2a
} lws_mqtt_property;
 
int
lws_read_mqtt(struct lws *wsi, unsigned char *buf, lws_filepos_t len);
 
/* returns 0 if bd1 and bd2 are "the same", that includes empty, else nonzero */
LWS_VISIBLE LWS_EXTERN int
lws_mqtt_bindata_cmp(const lws_mqtt_str_t *bd1, const lws_mqtt_str_t *bd2);
 
LWS_VISIBLE LWS_EXTERN void
lws_mqtt_str_init(lws_mqtt_str_t *s, uint8_t *buf, uint16_t lim, char nf);
 
LWS_VISIBLE LWS_EXTERN lws_mqtt_str_t *
lws_mqtt_str_create(uint16_t lim);
 
LWS_VISIBLE LWS_EXTERN lws_mqtt_str_t *
lws_mqtt_str_create_init(uint8_t *buf, uint16_t len, uint16_t lim);
 
LWS_VISIBLE LWS_EXTERN lws_mqtt_str_t *
lws_mqtt_str_create_cstr_dup(const char *buf, uint16_t lim);
 
LWS_VISIBLE LWS_EXTERN uint8_t *
lws_mqtt_str_next(lws_mqtt_str_t *s, uint16_t *budget);
 
LWS_VISIBLE LWS_EXTERN int
lws_mqtt_str_advance(lws_mqtt_str_t *s, int n);
 
LWS_VISIBLE LWS_EXTERN void
lws_mqtt_str_free(lws_mqtt_str_t **s);
 

LWS_VISIBLE LWS_EXTERN int
lws_mqtt_client_send_publish(struct lws *wsi, lws_mqtt_publish_param_t *pub,
                             const void *buf, uint32_t len, int final);

LWS_VISIBLE LWS_EXTERN int
lws_mqtt_client_send_subcribe(struct lws *wsi, lws_mqtt_subscribe_param_t *sub);

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_mqtt_client_send_unsubcribe(struct lws *wsi,
                                const lws_mqtt_subscribe_param_t *unsub);
 
#endif /* _LWS_MQTT_H */