mqtt_client.h

00001 /**
00002  * @file mqtt_client.h
00003  * @brief MQTT client
00004  *
00005  * @section License
00006  *
00007  * Copyright (C) 2010-2017 Oryx Embedded SARL. All rights reserved.
00008  *
00009  * This file is part of CycloneTCP Open.
00010  *
00011  * This program is free software; you can redistribute it and/or
00012  * modify it under the terms of the GNU General Public License
00013  * as published by the Free Software Foundation; either version 2
00014  * of the License, or (at your option) any later version.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program; if not, write to the Free Software Foundation,
00023  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
00024  *
00025  * @author Oryx Embedded SARL (www.oryx-embedded.com)
00026  * @version 1.7.6
00027  **/
00028 
00029 #ifndef _MQTT_CLIENT_H
00030 #define _MQTT_CLIENT_H
00031 
00032 //Dependencies
00033 #include "core/net.h"
00034 #include "mqtt/mqtt_common.h"
00035 
00036 //MQTT client support
00037 #ifndef MQTT_CLIENT_SUPPORT
00038    #define MQTT_CLIENT_SUPPORT ENABLED
00039 #elif (MQTT_CLIENT_SUPPORT != ENABLED && MQTT_CLIENT_SUPPORT != DISABLED)
00040    #error MQTT_CLIENT_SUPPORT parameter is not valid
00041 #endif
00042 
00043 //MQTT over SSL/TLS
00044 #ifndef MQTT_CLIENT_TLS_SUPPORT
00045    #define MQTT_CLIENT_TLS_SUPPORT DISABLED
00046 #elif (MQTT_CLIENT_TLS_SUPPORT != ENABLED && MQTT_CLIENT_TLS_SUPPORT != DISABLED)
00047    #error MQTT_CLIENT_TLS_SUPPORT parameter is not valid
00048 #endif
00049 
00050 //MQTT over WebSocket
00051 #ifndef MQTT_CLIENT_WS_SUPPORT
00052    #define MQTT_CLIENT_WS_SUPPORT DISABLED
00053 #elif (MQTT_CLIENT_WS_SUPPORT != ENABLED && MQTT_CLIENT_WS_SUPPORT != DISABLED)
00054    #error MQTT_CLIENT_WS_SUPPORT parameter is not valid
00055 #endif
00056 
00057 //Default keep-alive time interval, in seconds
00058 #ifndef MQTT_CLIENT_DEFAULT_KEEP_ALIVE
00059    #define MQTT_CLIENT_DEFAULT_KEEP_ALIVE 0
00060 #elif (MQTT_CLIENT_DEFAULT_KEEP_ALIVE < 0)
00061    #error MQTT_CLIENT_DEFAULT_KEEP_ALIVE parameter is not valid
00062 #endif
00063 
00064 //Default communication timeout, in milliseconds
00065 #ifndef MQTT_CLIENT_DEFAULT_TIMEOUT
00066    #define MQTT_CLIENT_DEFAULT_TIMEOUT 20000
00067 #elif (MQTT_CLIENT_DEFAULT_TIMEOUT < 0)
00068    #error MQTT_CLIENT_DEFAULT_TIMEOUT parameter is not valid
00069 #endif
00070 
00071 //Maximum length of the hostname
00072 #ifndef MQTT_CLIENT_MAX_HOST_LEN
00073    #define MQTT_CLIENT_MAX_HOST_LEN 32
00074 #elif (MQTT_CLIENT_MAX_HOST_LEN < 1)
00075    #error MQTT_CLIENT_MAX_HOST_LEN parameter is not valid
00076 #endif
00077 
00078 //Maximum length of the resource name
00079 #ifndef MQTT_CLIENT_MAX_URI_LEN
00080    #define MQTT_CLIENT_MAX_URI_LEN 16
00081 #elif (MQTT_CLIENT_MAX_URI_LEN < 1)
00082    #error MQTT_CLIENT_MAX_URI_LEN parameter is not valid
00083 #endif
00084 
00085 //Maximum length of the client identifier
00086 #ifndef MQTT_CLIENT_MAX_ID_LEN
00087    #define MQTT_CLIENT_MAX_ID_LEN 16
00088 #elif (MQTT_CLIENT_MAX_ID_LEN < 0)
00089    #error MQTT_CLIENT_MAX_ID_LEN parameter is not valid
00090 #endif
00091 
00092 //Maximum length of the user name
00093 #ifndef MQTT_CLIENT_MAX_USERNAME_LEN
00094    #define MQTT_CLIENT_MAX_USERNAME_LEN 16
00095 #elif (MQTT_CLIENT_MAX_USERNAME_LEN < 0)
00096    #error MQTT_CLIENT_MAX_USERNAME_LEN parameter is not valid
00097 #endif
00098 
00099 //Maximum length of the password
00100 #ifndef MQTT_CLIENT_MAX_PASSWORD_LEN
00101    #define MQTT_CLIENT_MAX_PASSWORD_LEN 16
00102 #elif (MQTT_CLIENT_MAX_PASSWORD_LEN < 0)
00103    #error MQTT_CLIENT_MAX_PASSWORD_LEN parameter is not valid
00104 #endif
00105 
00106 //Maximum length of the will topic
00107 #ifndef MQTT_CLIENT_MAX_WILL_TOPIC_LEN
00108    #define MQTT_CLIENT_MAX_WILL_TOPIC_LEN 16
00109 #elif (MQTT_CLIENT_MAX_WILL_TOPIC_LEN < 0)
00110    #error MQTT_CLIENT_MAX_WILL_TOPIC_LEN parameter is not valid
00111 #endif
00112 
00113 //Maximum length of the will message payload
00114 #ifndef MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN
00115    #define MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN 16
00116 #elif (MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN < 0)
00117    #error MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN parameter is not valid
00118 #endif
00119 
00120 //Size of the MQTT client buffer
00121 #ifndef MQTT_CLIENT_BUFFER_SIZE
00122    #define MQTT_CLIENT_BUFFER_SIZE 1024
00123 #elif (MQTT_CLIENT_BUFFER_SIZE < 1)
00124    #error MQTT_CLIENT_BUFFER_SIZE parameter is not valid
00125 #endif
00126 
00127 //SSL/TLS supported?
00128 #if (MQTT_CLIENT_TLS_SUPPORT == ENABLED)
00129    #include "crypto.h"
00130    #include "tls.h"
00131 #endif
00132 
00133 //WebSocket supported?
00134 #if (MQTT_CLIENT_WS_SUPPORT == ENABLED)
00135    #include "web_socket/web_socket.h"
00136 #endif
00137 
00138 //Forward declaration of MqttClientContext structure
00139 struct _MqttClientContext;
00140 #define MqttClientContext struct _MqttClientContext
00141 
00142 
00143 /**
00144  * @brief MQTT client states
00145  **/
00146 
00147 typedef enum
00148 {
00149    MQTT_CLIENT_STATE_CLOSED              = 0,
00150    MQTT_CLIENT_STATE_CONNECTING          = 1,
00151    MQTT_CLIENT_STATE_CONNECTED           = 2,
00152    MQTT_CLIENT_STATE_IDLE                = 3,
00153    MQTT_CLIENT_STATE_SENDING_PACKET      = 4,
00154    MQTT_CLIENT_STATE_PACKET_SENT         = 5,
00155    MQTT_CLIENT_STATE_WAITING_PACKET      = 6,
00156    MQTT_CLIENT_STATE_RECEIVING_PACKET    = 7,
00157    MQTT_CLIENT_STATE_PACKET_RECEIVED     = 8,
00158    MQTT_CLIENT_STATE_DISCONNECTING       = 9,
00159    MQTT_CLIENT_STATE_DISCONNECTED        = 10
00160 } MqttClientState;
00161 
00162 
00163 /**
00164  * @brief CONNACK message received callback
00165  **/
00166 
00167 typedef void (*MqttClientConnAckCallback)(MqttClientContext *context,
00168    uint8_t connectAckFlags, uint8_t connectReturnCode);
00169 
00170 
00171 /**
00172  * @brief PUBLISH message received callback
00173  **/
00174 
00175 typedef void (*MqttClientPublishCallback)(MqttClientContext *context,
00176    const char_t *topic, const uint8_t *message, size_t length,
00177    bool_t dup, MqttQosLevel qos, bool_t retain, uint16_t packetId);
00178 
00179 
00180 /**
00181  * @brief PUBACK message received callback
00182  **/
00183 
00184 typedef void (*MqttClientPubAckCallback)(MqttClientContext *context,
00185    uint16_t packetId);
00186 
00187 
00188 /**
00189  * @brief PUBREC message received callback
00190  **/
00191 
00192 typedef void (*MqttClientPubRecCallback)(MqttClientContext *context,
00193    uint16_t packetId);
00194 
00195 
00196 /**
00197  * @brief PUBREL message received callback
00198  **/
00199 
00200 typedef void (*MqttClientPubRelCallback)(MqttClientContext *context,
00201    uint16_t packetId);
00202 
00203 
00204 /**
00205  * @brief PUBCOMP message received callback
00206  **/
00207 
00208 typedef void (*MqttClientPubCompCallback)(MqttClientContext *context,
00209    uint16_t packetId);
00210 
00211 
00212 /**
00213  * @brief SUBACK message received callback
00214  **/
00215 
00216 typedef void (*MqttClientSubAckCallback)(MqttClientContext *context,
00217    uint16_t packetId);
00218 
00219 
00220 /**
00221  * @brief UNSUBACK message received callback
00222  **/
00223 
00224 typedef void (*MqttClientUnsubAckCallback)(MqttClientContext *context,
00225    uint16_t packetId);
00226 
00227 
00228 /**
00229  * @brief PINGRESP message received callback
00230  **/
00231 
00232 typedef void (*MqttClientPingRespCallback)(MqttClientContext *context);
00233 
00234 
00235 //SSL/TLS supported?
00236 #if (MQTT_CLIENT_TLS_SUPPORT == ENABLED)
00237 
00238 /**
00239  * @brief SSL initialization callback
00240  **/
00241 
00242 typedef error_t (*MqttClientTlsInitCallback)(MqttClientContext *context,
00243    TlsContext *tlsContext);
00244 
00245 #endif
00246 
00247 
00248 /**
00249  * @brief Will message
00250  **/
00251 
00252 typedef struct
00253 {
00254    char_t topic[MQTT_CLIENT_MAX_WILL_TOPIC_LEN + 1];  ///<Will topic name
00255    uint8_t payload[MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN]; ///<Will message payload
00256    size_t length;                                     ///<Length of the Will message payload
00257    MqttQosLevel qos;                                  ///<QoS level to be used when publishing the Will message
00258    bool_t retain;                                     ///<Specifies if the Will message is to be retained
00259 } MqttClientWillMessage;
00260 
00261 
00262 /**
00263  * @brief MQTT client callback functions
00264  **/
00265 
00266 typedef struct
00267 {
00268    MqttClientConnAckCallback connAckCallback;   ///<CONNACK message received callback
00269    MqttClientPublishCallback publishCallback;   ///<PUBLISH message received callback
00270    MqttClientPubAckCallback pubAckCallback;     ///<PUBACK message received callback
00271    MqttClientPubAckCallback pubRecCallback;     ///<PUBREC message received callback
00272    MqttClientPubAckCallback pubRelCallback;     ///<PUBREL message received callback
00273    MqttClientPubAckCallback pubCompCallback;    ///<PUBCOMP message received callback
00274    MqttClientPubAckCallback subAckCallback;     ///<SUBACK message received callback
00275    MqttClientPubAckCallback unsubAckCallback;   ///<UNSUBACK message received callback
00276    MqttClientPingRespCallback pingRespCallback; ///<PINGRESP message received callback
00277 #if (MQTT_CLIENT_TLS_SUPPORT == ENABLED)
00278    MqttClientTlsInitCallback tlsInitCallback;   ///<SSL initialization callback
00279 #endif
00280 } MqttClientCallbacks;
00281 
00282 
00283 /**
00284  * @brief MQTT client settings
00285  **/
00286 
00287 typedef struct
00288 {
00289    MqttProtocolLevel protocolLevel;                   ///<MQTT protocol version
00290    MqttTransportProtocol transportProtocol;           ///<Transport protocol
00291    uint16_t keepAlive;                                ///<Keep-alive time interval
00292    systime_t timeout;                                 ///<Communication timeout
00293 #if (MQTT_CLIENT_WS_SUPPORT == ENABLED)
00294    char_t host[MQTT_CLIENT_MAX_HOST_LEN + 1];         ///<Hostname of the resource being requested
00295    char_t uri[MQTT_CLIENT_MAX_URI_LEN + 1];           ///<Resource name
00296 #endif
00297    char_t clientId[MQTT_CLIENT_MAX_ID_LEN + 1];       ///<Client identifier
00298    char_t username[MQTT_CLIENT_MAX_USERNAME_LEN + 1]; ///<User name
00299    char_t password[MQTT_CLIENT_MAX_PASSWORD_LEN + 1]; ///<Password
00300    MqttClientWillMessage willMessage;                 ///<Will message
00301 } MqttClientSettings;
00302 
00303 
00304 /**
00305  * @brief MQTT client context
00306  **/
00307 
00308 struct _MqttClientContext
00309 {
00310    MqttClientSettings settings;             ///<MQTT client settings
00311    MqttClientCallbacks callbacks;           ///<MQTT client callback functions
00312    MqttClientState state;                   ///<MQTT client state
00313    systime_t keepAliveTimestamp;            ///<Timestamp used to manage keep-alive
00314    systime_t pingTimestamp;                 ///<Timestamp used to measure round-trip time
00315    NetInterface *interface;                 ///<Underlying network interface
00316    Socket *socket;                          ///<Underlying TCP socket
00317 #if (MQTT_CLIENT_TLS_SUPPORT == ENABLED)
00318    TlsContext *tlsContext;                  ///<SSL context
00319    TlsSession tlsSession;                   ///<SSL session
00320 #endif
00321 #if (MQTT_CLIENT_WS_SUPPORT == ENABLED)
00322    WebSocket *webSocket;                    ///<Underlying WebSocket
00323 #endif
00324    uint8_t buffer[MQTT_CLIENT_BUFFER_SIZE]; ///<Internal buffer
00325    uint8_t *packet;                         ///<Pointer to the incoming/outgoing MQTT packet
00326    size_t packetPos;                        ///<Current position
00327    size_t packetLen;                        ///<Length of the entire MQTT packet
00328    MqttPacketType packetType;               ///<Control packet type
00329    uint16_t packetId;                       ///<Packet identifier
00330    size_t remainingLen;                     ///<Length of the variable header and payload
00331 };
00332 
00333 
00334 //MQTT client related functions
00335 void mqttClientInit(MqttClientContext *context);
00336 void mqttClientInitCallbacks(MqttClientCallbacks *callbacks);
00337 
00338 error_t mqttClientRegisterCallbacks(MqttClientContext *context,
00339    const MqttClientCallbacks *callbacks);
00340 
00341 error_t mqttClientSetProtocolLevel(MqttClientContext *context,
00342    MqttProtocolLevel protocolLevel);
00343 
00344 error_t mqttClientSetTransportProtocol(MqttClientContext *context,
00345    MqttTransportProtocol transportProtocol);
00346 
00347 error_t mqttClientSetKeepAlive(MqttClientContext *context, uint16_t keepAlive);
00348 error_t mqttClientSetTimeout(MqttClientContext *context, uint16_t timeout);
00349 
00350 error_t mqttClientSetHost(MqttClientContext *context, const char_t *host);
00351 error_t mqttClientSetUri(MqttClientContext *context, const char_t *uri);
00352 
00353 error_t mqttClientSetIdentifier(MqttClientContext *context,
00354    const char_t *clientId);
00355 
00356 error_t mqttClientSetAuthInfo(MqttClientContext *context,
00357    const char_t *username, const char_t *password);
00358 
00359 error_t mqttClientSetWillMessage(MqttClientContext *context, const char_t *topic,
00360    const void *message, size_t length, MqttQosLevel qos, bool_t retain);
00361 
00362 error_t mqttClientBindToInterface(MqttClientContext *context,
00363    NetInterface *interface);
00364 
00365 error_t mqttClientConnect(MqttClientContext *context,
00366    const IpAddr *serverIpAddr, uint16_t serverPort, bool_t cleanSession);
00367 
00368 error_t mqttClientPublish(MqttClientContext *context,
00369    const char_t *topic, const void *message, size_t length,
00370    MqttQosLevel qos, bool_t retain, uint16_t *packetId);
00371 
00372 error_t mqttClientSubscribe(MqttClientContext *context,
00373    const char_t *topic, MqttQosLevel qos, uint16_t *packetId);
00374 
00375 error_t mqttClientUnsubscribe(MqttClientContext *context,
00376    const char_t *topic, uint16_t *packetId);
00377 
00378 error_t mqttClientPing(MqttClientContext *context, systime_t *rtt);
00379 
00380 error_t mqttClientDisconnect(MqttClientContext *context);
00381 error_t mqttClientClose(MqttClientContext *context);
00382 
00383 error_t mqttClientProcessEvents(MqttClientContext *context, systime_t timeout);
00384 
00385 #endif
00386