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_qos, see will_topic */ 83 u8_t will_qos; 84 /** will_retain, see will_topic */ 85 u8_t will_retain; 86 #if LWIP_ALTCP && LWIP_ALTCP_TLS 87 /** TLS configuration for secure connections */ 88 struct altcp_tls_config *tls_config; 89 #endif 90 }; 91 92 /** 93 * @ingroup mqtt 94 * Connection status codes */ 95 typedef enum 96 { 97 /** Accepted */ 98 MQTT_CONNECT_ACCEPTED = 0, 99 /** Refused protocol version */ 100 MQTT_CONNECT_REFUSED_PROTOCOL_VERSION = 1, 101 /** Refused identifier */ 102 MQTT_CONNECT_REFUSED_IDENTIFIER = 2, 103 /** Refused server */ 104 MQTT_CONNECT_REFUSED_SERVER = 3, 105 /** Refused user credentials */ 106 MQTT_CONNECT_REFUSED_USERNAME_PASS = 4, 107 /** Refused not authorized */ 108 MQTT_CONNECT_REFUSED_NOT_AUTHORIZED_ = 5, 109 /** Disconnected */ 110 MQTT_CONNECT_DISCONNECTED = 256, 111 /** Timeout */ 112 MQTT_CONNECT_TIMEOUT = 257 113 } mqtt_connection_status_t; 114 115 /** 116 * @ingroup mqtt 117 * Function prototype for mqtt connection status callback. Called when 118 * client has connected to the server after initiating a mqtt connection attempt by 119 * calling mqtt_client_connect() or when connection is closed by server or an error 120 * 121 * @param client MQTT client itself 122 * @param arg Additional argument to pass to the callback function 123 * @param status Connect result code or disconnection notification @see mqtt_connection_status_t 124 * 125 */ 126 typedef void (*mqtt_connection_cb_t)(mqtt_client_t *client, void *arg, mqtt_connection_status_t status); 127 128 129 /** 130 * @ingroup mqtt 131 * Data callback flags */ 132 enum { 133 /** Flag set when last fragment of data arrives in data callback */ 134 MQTT_DATA_FLAG_LAST = 1 135 }; 136 137 /** 138 * @ingroup mqtt 139 * Function prototype for MQTT incoming publish data callback function. Called when data 140 * arrives to a subscribed topic @see mqtt_subscribe 141 * 142 * @param arg Additional argument to pass to the callback function 143 * @param data User data, pointed object, data may not be referenced after callback return, 144 NULL is passed when all publish data are delivered 145 * @param len Length of publish data fragment 146 * @param flags MQTT_DATA_FLAG_LAST set when this call contains the last part of data from publish message 147 * 148 */ 149 typedef void (*mqtt_incoming_data_cb_t)(void *arg, const u8_t *data, u16_t len, u8_t flags); 150 151 152 /** 153 * @ingroup mqtt 154 * Function prototype for MQTT incoming publish function. Called when an incoming publish 155 * arrives to a subscribed topic @see mqtt_subscribe 156 * 157 * @param arg Additional argument to pass to the callback function 158 * @param topic Zero terminated Topic text string, topic may not be referenced after callback return 159 * @param tot_len Total length of publish data, if set to 0 (no publish payload) data callback will not be invoked 160 */ 161 typedef void (*mqtt_incoming_publish_cb_t)(void *arg, const char *topic, u32_t tot_len); 162 163 164 /** 165 * @ingroup mqtt 166 * Function prototype for mqtt request callback. Called when a subscribe, unsubscribe 167 * or publish request has completed 168 * @param arg Pointer to user data supplied when invoking request 169 * @param err ERR_OK on success 170 * ERR_TIMEOUT if no response was received within timeout, 171 * ERR_ABRT if (un)subscribe was denied 172 */ 173 typedef void (*mqtt_request_cb_t)(void *arg, err_t err); 174 175 176 err_t mqtt_client_connect(mqtt_client_t *client, const ip_addr_t *ipaddr, u16_t port, mqtt_connection_cb_t cb, void *arg, 177 const struct mqtt_connect_client_info_t *client_info); 178 179 void mqtt_disconnect(mqtt_client_t *client); 180 181 mqtt_client_t *mqtt_client_new(void); 182 void mqtt_client_free(mqtt_client_t* client); 183 184 u8_t mqtt_client_is_connected(mqtt_client_t *client); 185 186 void mqtt_set_inpub_callback(mqtt_client_t *client, mqtt_incoming_publish_cb_t, 187 mqtt_incoming_data_cb_t data_cb, void *arg); 188 189 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); 190 191 /** @ingroup mqtt 192 *Subscribe to topic */ 193 #define mqtt_subscribe(client, topic, qos, cb, arg) mqtt_sub_unsub(client, topic, qos, cb, arg, 1) 194 /** @ingroup mqtt 195 * Unsubscribe to topic */ 196 #define mqtt_unsubscribe(client, topic, cb, arg) mqtt_sub_unsub(client, topic, 0, cb, arg, 0) 197 198 err_t mqtt_publish(mqtt_client_t *client, const char *topic, const void *payload, u16_t payload_length, u8_t qos, u8_t retain, 199 mqtt_request_cb_t cb, void *arg); 200 201 #ifdef __cplusplus 202 } 203 #endif 204 205 #endif /* LWIP_HDR_APPS_MQTT_CLIENT_H */ 206