MQTTClient.h

00001 /*******************************************************************************
00002  * Copyright (c) 2014, 2017 IBM Corp.
00003  *
00004  * All rights reserved. This program and the accompanying materials
00005  * are made available under the terms of the Eclipse Public License v1.0
00006  * and Eclipse Distribution License v1.0 which accompany this distribution.
00007  *
00008  * The Eclipse Public License is available at
00009  *    http://www.eclipse.org/legal/epl-v10.html
00010  * and the Eclipse Distribution License is available at
00011  *   http://www.eclipse.org/org/documents/edl-v10.php.
00012  *
00013  * Contributors:
00014  *    Allan Stockdill-Mander/Ian Craggs - initial API and implementation and/or initial documentation
00015  *    Ian Craggs - documentation and platform specific header
00016  *    Ian Craggs - add setMessageHandler function
00017  *******************************************************************************/
00018 
00019 #if !defined(MQTT_CLIENT_H)
00020 #define MQTT_CLIENT_H
00021 
00022 #if defined(__cplusplus)
00023  extern "C" {
00024 #endif
00025 
00026 #if defined(WIN32_DLL) || defined(WIN64_DLL)
00027   #define DLLImport __declspec(dllimport)
00028   #define DLLExport __declspec(dllexport)
00029 #elif defined(LINUX_SO)
00030   #define DLLImport extern
00031   #define DLLExport  __attribute__ ((visibility ("default")))
00032 #else
00033   #define DLLImport
00034   #define DLLExport
00035 #endif
00036 
00037 #include "MQTTPacket.h"
00038 
00039 #if defined(MQTTCLIENT_PLATFORM_HEADER)
00040 /* The following sequence of macros converts the MQTTCLIENT_PLATFORM_HEADER value
00041  * into a string constant suitable for use with include.
00042  */
00043 #define xstr(s) str(s)
00044 #define str(s) #s
00045 #include xstr(MQTTCLIENT_PLATFORM_HEADER)
00046 #endif
00047 
00048 #define MAX_PACKET_ID 65535 /* according to the MQTT specification - do not change! */
00049 
00050 #if !defined(MAX_MESSAGE_HANDLERS)
00051 #define MAX_MESSAGE_HANDLERS 5 /* redefinable - how many subscriptions do you want? */
00052 #endif
00053 
00054 enum QoS { QOS0, QOS1, QOS2, SUBFAIL=0x80 };
00055 
00056 /* all failure return codes must be negative */
00057 enum returnCode { BUFFER_OVERFLOW = -2, FAILURE = -1, SUCCESS = 0 };
00058 
00059 /* The Platform specific header must define the Network and Timer structures and functions
00060  * which operate on them.
00061  *
00062 typedef struct Network
00063 {
00064     int (*mqttread)(Network*, unsigned char* read_buffer, int, int);
00065     int (*mqttwrite)(Network*, unsigned char* send_buffer, int, int);
00066 } Network;*/
00067 
00068 /* The Timer structure must be defined in the platform specific header,
00069  * and have the following functions to operate on it.  */
00070 extern void TimerInit(Timer*);
00071 extern char TimerIsExpired(Timer*);
00072 extern void TimerCountdownMS(Timer*, unsigned int);
00073 extern void TimerCountdown(Timer*, unsigned int);
00074 extern int TimerLeftMS(Timer*);
00075 
00076 typedef struct MQTTMessage
00077 {
00078     enum QoS qos;
00079     unsigned char retained;
00080     unsigned char dup;
00081     unsigned short id;
00082     void *payload;
00083     size_t payloadlen;
00084 } MQTTMessage;
00085 
00086 typedef struct MessageData
00087 {
00088     MQTTMessage* message;
00089     MQTTString* topicName;
00090 } MessageData;
00091 
00092 typedef struct MQTTConnackData
00093 {
00094     unsigned char rc;
00095     unsigned char sessionPresent;
00096 } MQTTConnackData;
00097 
00098 typedef struct MQTTSubackData
00099 {
00100     enum QoS grantedQoS;
00101 } MQTTSubackData;
00102 
00103 typedef void (*messageHandler)(MessageData*);
00104 
00105 typedef struct MQTTClient
00106 {
00107     unsigned int next_packetid,
00108       command_timeout_ms;
00109     size_t buf_size,
00110       readbuf_size;
00111     unsigned char *buf,
00112       *readbuf;
00113     unsigned int keepAliveInterval;
00114     char ping_outstanding;
00115     int isconnected;
00116     int cleansession;
00117 
00118     struct MessageHandlers
00119     {
00120         const char* topicFilter;
00121         void (*fp) (MessageData*);
00122     } messageHandlers[MAX_MESSAGE_HANDLERS];      /* Message handlers are indexed by subscription topic */
00123 
00124     void (*defaultMessageHandler) (MessageData*);
00125 
00126     Network* ipstack;
00127     Timer last_sent, last_received;
00128 #if defined(MQTT_TASK)
00129     Mutex mutex;
00130     Thread thread;
00131 #endif
00132 } MQTTClient;
00133 
00134 #define DefaultClient {0, 0, 0, 0, NULL, NULL, 0, 0, 0}
00135 
00136 
00137 /**
00138  * Create an MQTT client object
00139  * @param client
00140  * @param network
00141  * @param command_timeout_ms
00142  * @param
00143  */
00144 DLLExport void MQTTClientInit(MQTTClient* client, Network* network, unsigned int command_timeout_ms,
00145         unsigned char* sendbuf, size_t sendbuf_size, unsigned char* readbuf, size_t readbuf_size);
00146 
00147 /** MQTT Connect - send an MQTT connect packet down the network and wait for a Connack
00148  *  The nework object must be connected to the network endpoint before calling this
00149  *  @param options - connect options
00150  *  @return success code
00151  */
00152 DLLExport int MQTTConnectWithResults(MQTTClient* client, MQTTPacket_connectData* options,
00153     MQTTConnackData* data);
00154 
00155 /** MQTT Connect - send an MQTT connect packet down the network and wait for a Connack
00156  *  The nework object must be connected to the network endpoint before calling this
00157  *  @param options - connect options
00158  *  @return success code
00159  */
00160 DLLExport int MQTTConnect(MQTTClient* client, MQTTPacket_connectData* options);
00161 
00162 /** MQTT Publish - send an MQTT publish packet and wait for all acks to complete for all QoSs
00163  *  @param client - the client object to use
00164  *  @param topic - the topic to publish to
00165  *  @param message - the message to send
00166  *  @return success code
00167  */
00168 DLLExport int MQTTPublish(MQTTClient* client, const char*, MQTTMessage*);
00169 
00170 /** MQTT SetMessageHandler - set or remove a per topic message handler
00171  *  @param client - the client object to use
00172  *  @param topicFilter - the topic filter set the message handler for
00173  *  @param messageHandler - pointer to the message handler function or NULL to remove
00174  *  @return success code
00175  */
00176 DLLExport int MQTTSetMessageHandler(MQTTClient* c, const char* topicFilter, messageHandler messageHandler);
00177 
00178 /** MQTT Subscribe - send an MQTT subscribe packet and wait for suback before returning.
00179  *  @param client - the client object to use
00180  *  @param topicFilter - the topic filter to subscribe to
00181  *  @param message - the message to send
00182  *  @return success code
00183  */
00184 DLLExport int MQTTSubscribe(MQTTClient* client, const char* topicFilter, enum QoS, messageHandler);
00185 
00186 /** MQTT Subscribe - send an MQTT subscribe packet and wait for suback before returning.
00187  *  @param client - the client object to use
00188  *  @param topicFilter - the topic filter to subscribe to
00189  *  @param message - the message to send
00190  *  @param data - suback granted QoS returned
00191  *  @return success code
00192  */
00193 DLLExport int MQTTSubscribeWithResults(MQTTClient* client, const char* topicFilter, enum QoS, messageHandler, MQTTSubackData* data);
00194 
00195 /** MQTT Subscribe - send an MQTT unsubscribe packet and wait for unsuback before returning.
00196  *  @param client - the client object to use
00197  *  @param topicFilter - the topic filter to unsubscribe from
00198  *  @return success code
00199  */
00200 DLLExport int MQTTUnsubscribe(MQTTClient* client, const char* topicFilter);
00201 
00202 /** MQTT Disconnect - send an MQTT disconnect packet and close the connection
00203  *  @param client - the client object to use
00204  *  @return success code
00205  */
00206 DLLExport int MQTTDisconnect(MQTTClient* client);
00207 
00208 /** MQTT Yield - MQTT background
00209  *  @param client - the client object to use
00210  *  @param time - the time, in milliseconds, to yield for
00211  *  @return success code
00212  */
00213 DLLExport int MQTTYield(MQTTClient* client, int time);
00214 
00215 /** MQTT isConnected
00216  *  @param client - the client object to use
00217  *  @return truth value indicating whether the client is connected to the server
00218  */
00219 DLLExport int MQTTIsConnected(MQTTClient* client);
00220 
00221 #if defined(MQTT_TASK)
00222 /** MQTT start background thread for a client.  After this, MQTTYield should not be called.
00223 *  @param client - the client object to use
00224 *  @return success code
00225 */
00226 DLLExport int MQTTStartTask(MQTTClient* client);
00227 #endif
00228 
00229 #if defined(__cplusplus)
00230      }
00231 #endif
00232 
00233 #endif