1 /** 2 * @file 3 * MQTT client 4 */ 5 6 /* 7 * Copyright (c) 2016 Erik Andersson 8 * All rights reserved. 9 * 10 * Redistribution and use in source and binary forms, with or without modification, 11 * are permitted provided that the following conditions are met: 12 * 13 * 1. Redistributions of source code must retain the above copyright notice, 14 * this list of conditions and the following disclaimer. 15 * 2. Redistributions in binary form must reproduce the above copyright notice, 16 * this list of conditions and the following disclaimer in the documentation 17 * and/or other materials provided with the distribution. 18 * 3. The name of the author may not be used to endorse or promote products 19 * derived from this software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 22 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 23 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 24 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 26 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 29 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 30 * OF SUCH DAMAGE. 31 * 32 * This file is part of the lwIP TCP/IP stack. 33 * 34 * Author: Erik Andersson 35 * 36 */ 37 #ifndef LWIP_HDR_APPS_MQTT_CLIENT_H 38 #define LWIP_HDR_APPS_MQTT_CLIENT_H 39 40 #include "lwip/apps/mqtt_opts.h" 41 #include "lwip/err.h" 42 #include "lwip/ip_addr.h" 43 #include "lwip/prot/iana.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 typedef struct mqtt_client_s mqtt_client_t; 50 51 #if LWIP_ALTCP && LWIP_ALTCP_TLS 52 struct altcp_tls_config; 53 #endif 54 55 /** @ingroup mqtt 56 * Default MQTT port (non-TLS) */ 57 #define MQTT_PORT LWIP_IANA_PORT_MQTT 58 /** @ingroup mqtt 59 * Default MQTT TLS port */ 60 #define MQTT_TLS_PORT LWIP_IANA_PORT_SECURE_MQTT 61 62 /*---------------------------------------------------------------------------------------------- */ 63 /* Connection with server */ 64 65 /** 66 * @ingroup mqtt 67 * Client information and connection parameters */ 68 struct mqtt_connect_client_info_t { 69 /** Client identifier, must be set by caller */ 70 const char *client_id; 71 /** User name, set to NULL if not used */ 72 const char* client_user; 73 /** Password, set to NULL if not used */ 74 const char* client_pass; 75 /** keep alive time in seconds, 0 to disable keep alive functionality*/ 76 u16_t keep_alive; 77 /** will topic, set to NULL if will is not to be used, 78 will_msg, will_qos and will retain are then ignored */ 79 const char* will_topic; 80 /** will_msg, see will_topic */ 81 const char* will_msg; 82 /** will_msg length, 0 to compute length from will_msg string */ 83 u8_t will_msg_len; 84 /** will_qos, see will_topic */ 85 u8_t will_qos; 86 /** will_retain, see will_topic */ 87 u8_t will_retain; 88 #if LWIP_ALTCP && LWIP_ALTCP_TLS 89 /** TLS configuration for secure connections */ 90 struct altcp_tls_config *tls_config; 91 #endif 92 }; 93 94 /** 95 * @ingroup mqtt 96 * Connection status codes */ 97 typedef enum 98 { 99 /** Accepted */ 100 MQTT_CONNECT_ACCEPTED = 0, 101 /** Refused protocol version */ 102 MQTT_CONNECT_REFUSED_PROTOCOL_VERSION = 1, 103 /** Refused identifier */ 104 MQTT_CONNECT_REFUSED_IDENTIFIER = 2, 105 /** Refused server */ 106 MQTT_CONNECT_REFUSED_SERVER = 3, 107 /** Refused user credentials */ 108 MQTT_CONNECT_REFUSED_USERNAME_PASS = 4, 109 /** Refused not authorized */ 110 MQTT_CONNECT_REFUSED_NOT_AUTHORIZED_ = 5, 111 /** Disconnected */ 112 MQTT_CONNECT_DISCONNECTED = 256, 113 /** Timeout */ 114 MQTT_CONNECT_TIMEOUT = 257 115 } mqtt_connection_status_t; 116 117 /** 118 * @ingroup mqtt 119 * Function prototype for mqtt connection status callback. Called when 120 * client has connected to the server after initiating a mqtt connection attempt by 121 * calling mqtt_client_connect() or when connection is closed by server or an error 122 * 123 * @param client MQTT client itself 124 * @param arg Additional argument to pass to the callback function 125 * @param status Connect result code or disconnection notification @see mqtt_connection_status_t 126 * 127 */ 128 typedef void (*mqtt_connection_cb_t)(mqtt_client_t *client, void *arg, mqtt_connection_status_t status); 129 130 131 /** 132 * @ingroup mqtt 133 * Data callback flags */ 134 enum { 135 /** Flag set when last fragment of data arrives in data callback */ 136 MQTT_DATA_FLAG_LAST = 1 137 }; 138 139 /** 140 * @ingroup mqtt 141 * Function prototype for MQTT incoming publish data callback function. Called when data 142 * arrives to a subscribed topic @see mqtt_subscribe 143 * 144 * @param arg Additional argument to pass to the callback function 145 * @param data User data, pointed object, data may not be referenced after callback return, 146 NULL is passed when all publish data are delivered 147 * @param len Length of publish data fragment 148 * @param flags MQTT_DATA_FLAG_LAST set when this call contains the last part of data from publish message 149 * 150 */ 151 typedef void (*mqtt_incoming_data_cb_t)(void *arg, const u8_t *data, u16_t len, u8_t flags); 152 153 154 /** 155 * @ingroup mqtt 156 * Function prototype for MQTT incoming publish function. Called when an incoming publish 157 * arrives to a subscribed topic @see mqtt_subscribe 158 * 159 * @param arg Additional argument to pass to the callback function 160 * @param topic Zero terminated Topic text string, topic may not be referenced after callback return 161 * @param tot_len Total length of publish data, if set to 0 (no publish payload) data callback will not be invoked 162 */ 163 typedef void (*mqtt_incoming_publish_cb_t)(void *arg, const char *topic, u32_t tot_len); 164 165 166 /** 167 * @ingroup mqtt 168 * Function prototype for mqtt request callback. Called when a subscribe, unsubscribe 169 * or publish request has completed 170 * @param arg Pointer to user data supplied when invoking request 171 * @param err ERR_OK on success 172 * ERR_TIMEOUT if no response was received within timeout, 173 * ERR_ABRT if (un)subscribe was denied 174 */ 175 typedef void (*mqtt_request_cb_t)(void *arg, err_t err); 176 177 178 err_t mqtt_client_connect(mqtt_client_t *client, const ip_addr_t *ipaddr, u16_t port, mqtt_connection_cb_t cb, void *arg, 179 const struct mqtt_connect_client_info_t *client_info); 180 181 void mqtt_disconnect(mqtt_client_t *client); 182 183 mqtt_client_t *mqtt_client_new(void); 184 void mqtt_client_free(mqtt_client_t* client); 185 186 u8_t mqtt_client_is_connected(mqtt_client_t *client); 187 188 void mqtt_set_inpub_callback(mqtt_client_t *client, mqtt_incoming_publish_cb_t pub_cb, 189 mqtt_incoming_data_cb_t data_cb, void *arg); 190 191 err_t mqtt_sub_unsub(mqtt_client_t *client, const char *topic, u8_t qos, mqtt_request_cb_t cb, void *arg, u8_t sub); 192 193 /** @ingroup mqtt 194 *Subscribe to topic */ 195 #define mqtt_subscribe(client, topic, qos, cb, arg) mqtt_sub_unsub(client, topic, qos, cb, arg, 1) 196 /** @ingroup mqtt 197 * Unsubscribe to topic */ 198 #define mqtt_unsubscribe(client, topic, cb, arg) mqtt_sub_unsub(client, topic, 0, cb, arg, 0) 199 200 err_t mqtt_publish(mqtt_client_t *client, const char *topic, const void *payload, u16_t payload_length, u8_t qos, u8_t retain, 201 mqtt_request_cb_t cb, void *arg); 202 203 #ifdef __cplusplus 204 } 205 #endif 206 207 #endif /* LWIP_HDR_APPS_MQTT_CLIENT_H */ 208