mqtt.h

00001 /**
00002  * @file
00003  * MQTT client
00004  */
00005 
00006 /*
00007  * Copyright (c) 2016 Erik Andersson
00008  * All rights reserved.
00009  *
00010  * Redistribution and use in source and binary forms, with or without modification,
00011  * are permitted provided that the following conditions are met:
00012  *
00013  * 1. Redistributions of source code must retain the above copyright notice,
00014  *    this list of conditions and the following disclaimer.
00015  * 2. Redistributions in binary form must reproduce the above copyright notice,
00016  *    this list of conditions and the following disclaimer in the documentation
00017  *    and/or other materials provided with the distribution.
00018  * 3. The name of the author may not be used to endorse or promote products
00019  *    derived from this software without specific prior written permission.
00020  *
00021  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
00022  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00023  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
00024  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00025  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
00026  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00027  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00028  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
00029  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
00030  * OF SUCH DAMAGE.
00031  *
00032  * This file is part of the lwIP TCP/IP stack.
00033  *
00034  * Author: Erik Andersson
00035  *
00036  */
00037 #ifndef LWIP_HDR_APPS_MQTT_CLIENT_H
00038 #define LWIP_HDR_APPS_MQTT_CLIENT_H
00039 
00040 #include "lwip/apps/mqtt_opts.h"
00041 #include "lwip/err.h"
00042 
00043 #ifdef  __cplusplus
00044 extern "C" {
00045 #endif
00046 
00047 typedef struct mqtt_client_t mqtt_client_t;
00048 
00049 /** @ingroup mqtt
00050  * Default MQTT port */
00051 #define MQTT_PORT 1883
00052 
00053 /*---------------------------------------------------------------------------------------------- */
00054 /* Connection with server */
00055 
00056 /**
00057  * @ingroup mqtt
00058  * Client information and connection parameters */
00059 struct mqtt_connect_client_info_t {
00060   /** Client identifier, must be set by caller */
00061   const char *client_id;
00062   /** User name and password, set to NULL if not used */
00063   const char* client_user;
00064   const char* client_pass;
00065   /** keep alive time in seconds, 0 to disable keep alive functionality*/
00066   u16_t keep_alive;
00067   /** will topic, set to NULL if will is not to be used,
00068       will_msg, will_qos and will retain are then ignored */
00069   const char* will_topic;
00070   const char* will_msg;
00071   u8_t will_qos;
00072   u8_t will_retain;
00073 };
00074 
00075 /**
00076  * @ingroup mqtt
00077  * Connection status codes */
00078 typedef enum
00079 {
00080   MQTT_CONNECT_ACCEPTED                 = 0,
00081   MQTT_CONNECT_REFUSED_PROTOCOL_VERSION = 1,
00082   MQTT_CONNECT_REFUSED_IDENTIFIER       = 2,
00083   MQTT_CONNECT_REFUSED_SERVER           = 3,
00084   MQTT_CONNECT_REFUSED_USERNAME_PASS    = 4,
00085   MQTT_CONNECT_REFUSED_NOT_AUTHORIZED_  = 5,
00086   MQTT_CONNECT_DISCONNECTED             = 256,
00087   MQTT_CONNECT_TIMEOUT                  = 257
00088 } mqtt_connection_status_t;
00089 
00090 /**
00091  * @ingroup mqtt
00092  * Function prototype for mqtt connection status callback. Called when
00093  * client has connected to the server after initiating a mqtt connection attempt by
00094  * calling mqtt_connect() or when connection is closed by server or an error
00095  *
00096  * @param client MQTT client itself
00097  * @param arg Additional argument to pass to the callback function
00098  * @param status Connect result code or disconnection notification @see mqtt_connection_status_t
00099  *
00100  */
00101 typedef void (*mqtt_connection_cb_t)(mqtt_client_t *client, void *arg, mqtt_connection_status_t status);
00102 
00103 
00104 /**
00105  * @ingroup mqtt
00106  * Data callback flags */
00107 enum {
00108   /** Flag set when last fragment of data arrives in data callback */
00109   MQTT_DATA_FLAG_LAST = 1
00110 };
00111 
00112 /** 
00113  * @ingroup mqtt
00114  * Function prototype for MQTT incoming publish data callback function. Called when data
00115  * arrives to a subscribed topic @see mqtt_subscribe
00116  *
00117  * @param arg Additional argument to pass to the callback function
00118  * @param data User data, pointed object, data may not be referenced after callback return,
00119           NULL is passed when all publish data are delivered
00120  * @param len Length of publish data fragment
00121  * @param flags MQTT_DATA_FLAG_LAST set when this call contains the last part of data from publish message
00122  *
00123  */
00124 typedef void (*mqtt_incoming_data_cb_t)(void *arg, const u8_t *data, u16_t len, u8_t flags);
00125 
00126 
00127 /** 
00128  * @ingroup mqtt
00129  * Function prototype for MQTT incoming publish function. Called when an incoming publish
00130  * arrives to a subscribed topic @see mqtt_subscribe
00131  *
00132  * @param arg Additional argument to pass to the callback function
00133  * @param topic Zero terminated Topic text string, topic may not be referenced after callback return
00134  * @param tot_len Total length of publish data, if set to 0 (no publish payload) data callback will not be invoked
00135  */
00136 typedef void (*mqtt_incoming_publish_cb_t)(void *arg, const char *topic, u32_t tot_len);
00137 
00138 
00139 /**
00140  * @ingroup mqtt
00141  * Function prototype for mqtt request callback. Called when a subscribe, unsubscribe
00142  * or publish request has completed
00143  * @param arg Pointer to user data supplied when invoking request
00144  * @param err ERR_OK on success
00145  *            ERR_TIMEOUT if no response was received within timeout,
00146  *            ERR_ABRT if (un)subscribe was denied
00147  */
00148 typedef void (*mqtt_request_cb_t)(void *arg, err_t err);
00149 
00150 
00151 /**
00152  * Pending request item, binds application callback to pending server requests
00153  */
00154 struct mqtt_request_t
00155 {
00156   /** Next item in list, NULL means this is the last in chain,
00157       next pointing at itself means request is unallocated */
00158   struct mqtt_request_t *next;
00159   /** Callback to upper layer */
00160   mqtt_request_cb_t cb;
00161   void *arg;
00162   /** MQTT packet identifier */
00163   u16_t pkt_id;
00164   /** Expire time relative to element before this  */
00165   u16_t timeout_diff;
00166 };
00167 
00168 /** Ring buffer */
00169 struct mqtt_ringbuf_t {
00170   u16_t put;
00171   u16_t get;
00172   u8_t buf[MQTT_OUTPUT_RINGBUF_SIZE];
00173 };
00174 
00175 /** MQTT client */
00176 struct mqtt_client_t
00177 {
00178   /** Timers and timeouts */
00179   u16_t cyclic_tick;
00180   u16_t keep_alive;
00181   u16_t server_watchdog;
00182   /** Packet identifier generator*/
00183   u16_t pkt_id_seq;
00184   /** Packet identifier of pending incoming publish */
00185   u16_t inpub_pkt_id;
00186   /** Connection state */
00187   u8_t conn_state;
00188   struct tcp_pcb *conn;
00189   /** Connection callback */
00190   void *connect_arg;
00191   mqtt_connection_cb_t connect_cb;
00192   /** Pending requests to server */
00193   struct mqtt_request_t *pend_req_queue;
00194   struct mqtt_request_t req_list[MQTT_REQ_MAX_IN_FLIGHT];
00195   void *inpub_arg;
00196   /** Incoming data callback */
00197   mqtt_incoming_data_cb_t data_cb;
00198   mqtt_incoming_publish_cb_t pub_cb;
00199   /** Input */
00200   u32_t msg_idx;
00201   u8_t rx_buffer[MQTT_VAR_HEADER_BUFFER_LEN];
00202   /** Output ring-buffer */
00203   struct mqtt_ringbuf_t output;
00204 };
00205 
00206 
00207 /** Connect to server */
00208 err_t mqtt_client_connect(mqtt_client_t *client, const ip_addr_t *ipaddr, u16_t port, mqtt_connection_cb_t cb, void *arg,
00209                    const struct mqtt_connect_client_info_t *client_info);
00210 
00211 /** Disconnect from server */
00212 void mqtt_disconnect(mqtt_client_t *client);
00213 
00214 /** Create new client */
00215 mqtt_client_t *mqtt_client_new(void);
00216 
00217 /** Check connection status */
00218 u8_t mqtt_client_is_connected(mqtt_client_t *client);
00219 
00220 /** Set callback to call for incoming publish */
00221 void mqtt_set_inpub_callback(mqtt_client_t *client, mqtt_incoming_publish_cb_t,
00222                              mqtt_incoming_data_cb_t data_cb, void *arg);
00223 
00224 /** Common function for subscribe and unsubscribe */
00225 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);
00226 
00227 /** @ingroup mqtt
00228  *Subscribe to topic */
00229 #define mqtt_subscribe(client, topic, qos, cb, arg) mqtt_sub_unsub(client, topic, qos, cb, arg, 1)
00230 /** @ingroup mqtt
00231  *  Unsubscribe to topic */
00232 #define mqtt_unsubscribe(client, topic, cb, arg) mqtt_sub_unsub(client, topic, 0, cb, arg, 0)
00233 
00234 
00235 /** Publish data to topic */
00236 err_t mqtt_publish(mqtt_client_t *client, const char *topic, const void *payload, u16_t payload_length, u8_t qos, u8_t retain,
00237                                     mqtt_request_cb_t cb, void *arg);
00238 
00239 #ifdef  __cplusplus
00240 }
00241 #endif
00242 
00243 #endif /* LWIP_HDR_APPS_MQTT_CLIENT_H */