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_PACKET_SIZE (1 * 1024 * 1024)
#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,
        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;
 
typedef struct lws_mqtt_qos2_state_ops {
        int (*rx_add)(struct lws *wsi, const char *client_id, uint16_t pkt_id);
        int (*rx_remove)(struct lws *wsi, const char *client_id, uint16_t pkt_id);
} lws_mqtt_qos2_state_ops_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;
        const lws_mqtt_qos2_state_ops_t *qos2_state_ops;
        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;
 
/*
 * The maximum number of topic elements that can be passed in a single
 * lws_mqtt_client_send_subcribe() or lws_mqtt_client_send_unsubcribe()
 * call, ie, the top end of the valid range for
 * lws_mqtt_subscribe_param_t.num_topics.  Calls with a num_topics of
 * zero or greater than this are rejected with a nonzero return.
 */
#define LWS_MQTT_MAX_TOPICS 8
 
/*
 * 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);

LWS_VISIBLE LWS_EXTERN int
lws_mqtt_client_qos2_rx_add(struct lws *wsi, uint16_t pkt_id);
 
#endif /* _LWS_MQTT_H */