mqtt_client.h
Go to the documentation of this file.
1 /**
2  * @file mqtt_client.h
3  * @brief MQTT client
4  *
5  * @section License
6  *
7  * Copyright (C) 2010-2018 Oryx Embedded SARL. All rights reserved.
8  *
9  * This file is part of CycloneTCP Open.
10  *
11  * This program is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU General Public License
13  * as published by the Free Software Foundation; either version 2
14  * of the License, or (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software Foundation,
23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
24  *
25  * @author Oryx Embedded SARL (www.oryx-embedded.com)
26  * @version 1.9.0
27  **/
28 
29 #ifndef _MQTT_CLIENT_H
30 #define _MQTT_CLIENT_H
31 
32 //Dependencies
33 #include "core/net.h"
34 #include "mqtt/mqtt_common.h"
35 
36 //MQTT client support
37 #ifndef MQTT_CLIENT_SUPPORT
38  #define MQTT_CLIENT_SUPPORT ENABLED
39 #elif (MQTT_CLIENT_SUPPORT != ENABLED && MQTT_CLIENT_SUPPORT != DISABLED)
40  #error MQTT_CLIENT_SUPPORT parameter is not valid
41 #endif
42 
43 //MQTT over TLS
44 #ifndef MQTT_CLIENT_TLS_SUPPORT
45  #define MQTT_CLIENT_TLS_SUPPORT DISABLED
46 #elif (MQTT_CLIENT_TLS_SUPPORT != ENABLED && MQTT_CLIENT_TLS_SUPPORT != DISABLED)
47  #error MQTT_CLIENT_TLS_SUPPORT parameter is not valid
48 #endif
49 
50 //MQTT over WebSocket
51 #ifndef MQTT_CLIENT_WS_SUPPORT
52  #define MQTT_CLIENT_WS_SUPPORT DISABLED
53 #elif (MQTT_CLIENT_WS_SUPPORT != ENABLED && MQTT_CLIENT_WS_SUPPORT != DISABLED)
54  #error MQTT_CLIENT_WS_SUPPORT parameter is not valid
55 #endif
56 
57 //Default keep-alive time interval, in seconds
58 #ifndef MQTT_CLIENT_DEFAULT_KEEP_ALIVE
59  #define MQTT_CLIENT_DEFAULT_KEEP_ALIVE 0
60 #elif (MQTT_CLIENT_DEFAULT_KEEP_ALIVE < 0)
61  #error MQTT_CLIENT_DEFAULT_KEEP_ALIVE parameter is not valid
62 #endif
63 
64 //Default communication timeout, in milliseconds
65 #ifndef MQTT_CLIENT_DEFAULT_TIMEOUT
66  #define MQTT_CLIENT_DEFAULT_TIMEOUT 20000
67 #elif (MQTT_CLIENT_DEFAULT_TIMEOUT < 0)
68  #error MQTT_CLIENT_DEFAULT_TIMEOUT parameter is not valid
69 #endif
70 
71 //Maximum length of the hostname
72 #ifndef MQTT_CLIENT_MAX_HOST_LEN
73  #define MQTT_CLIENT_MAX_HOST_LEN 32
74 #elif (MQTT_CLIENT_MAX_HOST_LEN < 1)
75  #error MQTT_CLIENT_MAX_HOST_LEN parameter is not valid
76 #endif
77 
78 //Maximum length of the resource name
79 #ifndef MQTT_CLIENT_MAX_URI_LEN
80  #define MQTT_CLIENT_MAX_URI_LEN 16
81 #elif (MQTT_CLIENT_MAX_URI_LEN < 1)
82  #error MQTT_CLIENT_MAX_URI_LEN parameter is not valid
83 #endif
84 
85 //Maximum length of the client identifier
86 #ifndef MQTT_CLIENT_MAX_ID_LEN
87  #define MQTT_CLIENT_MAX_ID_LEN 23
88 #elif (MQTT_CLIENT_MAX_ID_LEN < 0)
89  #error MQTT_CLIENT_MAX_ID_LEN parameter is not valid
90 #endif
91 
92 //Maximum length of the user name
93 #ifndef MQTT_CLIENT_MAX_USERNAME_LEN
94  #define MQTT_CLIENT_MAX_USERNAME_LEN 16
95 #elif (MQTT_CLIENT_MAX_USERNAME_LEN < 0)
96  #error MQTT_CLIENT_MAX_USERNAME_LEN parameter is not valid
97 #endif
98 
99 //Maximum length of the password
100 #ifndef MQTT_CLIENT_MAX_PASSWORD_LEN
101  #define MQTT_CLIENT_MAX_PASSWORD_LEN 16
102 #elif (MQTT_CLIENT_MAX_PASSWORD_LEN < 0)
103  #error MQTT_CLIENT_MAX_PASSWORD_LEN parameter is not valid
104 #endif
105 
106 //Maximum length of the will topic
107 #ifndef MQTT_CLIENT_MAX_WILL_TOPIC_LEN
108  #define MQTT_CLIENT_MAX_WILL_TOPIC_LEN 16
109 #elif (MQTT_CLIENT_MAX_WILL_TOPIC_LEN < 0)
110  #error MQTT_CLIENT_MAX_WILL_TOPIC_LEN parameter is not valid
111 #endif
112 
113 //Maximum length of the will message payload
114 #ifndef MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN
115  #define MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN 16
116 #elif (MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN < 0)
117  #error MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN parameter is not valid
118 #endif
119 
120 //Size of the MQTT client buffer
121 #ifndef MQTT_CLIENT_BUFFER_SIZE
122  #define MQTT_CLIENT_BUFFER_SIZE 1024
123 #elif (MQTT_CLIENT_BUFFER_SIZE < 1)
124  #error MQTT_CLIENT_BUFFER_SIZE parameter is not valid
125 #endif
126 
127 //TLS supported?
128 #if (MQTT_CLIENT_TLS_SUPPORT == ENABLED)
129  #include "core/crypto.h"
130  #include "tls.h"
131 #endif
132 
133 //WebSocket supported?
134 #if (MQTT_CLIENT_WS_SUPPORT == ENABLED)
135  #include "web_socket/web_socket.h"
136 #endif
137 
138 //Forward declaration of MqttClientContext structure
139 struct _MqttClientContext;
140 #define MqttClientContext struct _MqttClientContext
141 
142 //C++ guard
143 #ifdef __cplusplus
144  extern "C" {
145 #endif
146 
147 
148 /**
149  * @brief MQTT client states
150  **/
151 
152 typedef enum
153 {
166 
167 
168 /**
169  * @brief CONNACK message received callback
170  **/
171 
173  uint8_t connectAckFlags, uint8_t connectReturnCode);
174 
175 
176 /**
177  * @brief PUBLISH message received callback
178  **/
179 
181  const char_t *topic, const uint8_t *message, size_t length,
183 
184 
185 /**
186  * @brief PUBACK message received callback
187  **/
188 
190  uint16_t packetId);
191 
192 
193 /**
194  * @brief PUBREC message received callback
195  **/
196 
198  uint16_t packetId);
199 
200 
201 /**
202  * @brief PUBREL message received callback
203  **/
204 
206  uint16_t packetId);
207 
208 
209 /**
210  * @brief PUBCOMP message received callback
211  **/
212 
214  uint16_t packetId);
215 
216 
217 /**
218  * @brief SUBACK message received callback
219  **/
220 
222  uint16_t packetId);
223 
224 
225 /**
226  * @brief UNSUBACK message received callback
227  **/
228 
230  uint16_t packetId);
231 
232 
233 /**
234  * @brief PINGRESP message received callback
235  **/
236 
238 
239 
240 //TLS supported?
241 #if (MQTT_CLIENT_TLS_SUPPORT == ENABLED)
242 
243 /**
244  * @brief TLS initialization callback
245  **/
246 
249 
250 #endif
251 
252 
253 /**
254  * @brief Will message
255  **/
256 
257 typedef struct
258 {
259  char_t topic[MQTT_CLIENT_MAX_WILL_TOPIC_LEN + 1]; ///<Will topic name
260  uint8_t payload[MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN]; ///<Will message payload
261  size_t length; ///<Length of the Will message payload
262  MqttQosLevel qos; ///<QoS level to be used when publishing the Will message
263  bool_t retain; ///<Specifies if the Will message is to be retained
265 
266 
267 /**
268  * @brief MQTT client callback functions
269  **/
270 
271 typedef struct
272 {
273  MqttClientConnAckCallback connAckCallback; ///<CONNACK message received callback
274  MqttClientPublishCallback publishCallback; ///<PUBLISH message received callback
275  MqttClientPubAckCallback pubAckCallback; ///<PUBACK message received callback
276  MqttClientPubAckCallback pubRecCallback; ///<PUBREC message received callback
277  MqttClientPubAckCallback pubRelCallback; ///<PUBREL message received callback
278  MqttClientPubAckCallback pubCompCallback; ///<PUBCOMP message received callback
279  MqttClientPubAckCallback subAckCallback; ///<SUBACK message received callback
280  MqttClientPubAckCallback unsubAckCallback; ///<UNSUBACK message received callback
281  MqttClientPingRespCallback pingRespCallback; ///<PINGRESP message received callback
282 #if (MQTT_CLIENT_TLS_SUPPORT == ENABLED)
283  MqttClientTlsInitCallback tlsInitCallback; ///<TLS initialization callback
284 #endif
286 
287 
288 /**
289  * @brief MQTT client settings
290  **/
291 
292 typedef struct
293 {
294  MqttProtocolLevel protocolLevel; ///<MQTT protocol version
295  MqttTransportProtocol transportProtocol; ///<Transport protocol
296  uint16_t keepAlive; ///<Keep-alive time interval
297  systime_t timeout; ///<Communication timeout
298 #if (MQTT_CLIENT_WS_SUPPORT == ENABLED)
299  char_t host[MQTT_CLIENT_MAX_HOST_LEN + 1]; ///<Hostname of the resource being requested
300  char_t uri[MQTT_CLIENT_MAX_URI_LEN + 1]; ///<Resource name
301 #endif
302  char_t clientId[MQTT_CLIENT_MAX_ID_LEN + 1]; ///<Client identifier
303  char_t username[MQTT_CLIENT_MAX_USERNAME_LEN + 1]; ///<User name
304  char_t password[MQTT_CLIENT_MAX_PASSWORD_LEN + 1]; ///<Password
307 
308 
309 /**
310  * @brief MQTT client context
311  **/
312 
314 {
315  MqttClientSettings settings; ///<MQTT client settings
316  MqttClientCallbacks callbacks; ///<MQTT client callback functions
317  MqttClientState state; ///<MQTT client state
318  systime_t keepAliveTimestamp; ///<Timestamp used to manage keep-alive
319  systime_t pingTimestamp; ///<Timestamp used to measure round-trip time
320  NetInterface *interface; ///<Underlying network interface
321  Socket *socket; ///<Underlying TCP socket
322 #if (MQTT_CLIENT_TLS_SUPPORT == ENABLED)
323  TlsContext *tlsContext; ///<TLS context
324  TlsSessionState tlsSession; ///<TLS session state
325 #endif
326 #if (MQTT_CLIENT_WS_SUPPORT == ENABLED)
327  WebSocket *webSocket; ///<Underlying WebSocket
328 #endif
329  uint8_t buffer[MQTT_CLIENT_BUFFER_SIZE]; ///<Internal buffer
330  uint8_t *packet; ///<Pointer to the incoming/outgoing MQTT packet
331  size_t packetPos; ///<Current position
332  size_t packetLen; ///<Length of the entire MQTT packet
333  MqttPacketType packetType; ///<Control packet type
334  uint16_t packetId; ///<Packet identifier
335  size_t remainingLen; ///<Length of the variable header and payload
336 };
337 
338 
339 //MQTT client related functions
342 
344  const MqttClientCallbacks *callbacks);
345 
347  MqttProtocolLevel protocolLevel);
348 
350  MqttTransportProtocol transportProtocol);
351 
352 error_t mqttClientSetTimeout(MqttClientContext *context, uint16_t timeout);
353 error_t mqttClientSetKeepAlive(MqttClientContext *context, uint16_t keepAlive);
354 
355 error_t mqttClientSetHost(MqttClientContext *context, const char_t *host);
356 error_t mqttClientSetUri(MqttClientContext *context, const char_t *uri);
357 
359  const char_t *clientId);
360 
362  const char_t *username, const char_t *password);
363 
365  const void *message, size_t length, MqttQosLevel qos, bool_t retain);
366 
368  NetInterface *interface);
369 
371  const IpAddr *serverIpAddr, uint16_t serverPort, bool_t cleanSession);
372 
374  const char_t *topic, const void *message, size_t length,
375  MqttQosLevel qos, bool_t retain, uint16_t *packetId);
376 
378  const char_t *topic, MqttQosLevel qos, uint16_t *packetId);
379 
381  const char_t *topic, uint16_t *packetId);
382 
384 
387 
389 
390 //C++ guard
391 #ifdef __cplusplus
392  }
393 #endif
394 
395 #endif
TLS (Transport Layer Security)
MqttClientPubAckCallback pubAckCallback
PUBACK message received callback.
Definition: mqtt_client.h:275
uint32_t systime_t
Definition: compiler_port.h:44
uint16_t packetId
Packet identifier.
Definition: mqtt_client.h:334
Will message.
Definition: mqtt_client.h:257
#define MQTT_CLIENT_MAX_HOST_LEN
Definition: mqtt_client.h:73
char char_t
Definition: compiler_port.h:41
#define MQTT_CLIENT_BUFFER_SIZE
Definition: mqtt_client.h:122
systime_t pingTimestamp
Timestamp used to measure round-trip time.
Definition: mqtt_client.h:319
MqttTransportProtocol
Transport protocol.
Definition: mqtt_common.h:71
MqttClientPubAckCallback subAckCallback
SUBACK message received callback.
Definition: mqtt_client.h:279
MqttPacketType
MQTT control packet type.
Definition: mqtt_common.h:96
TCP/IP stack core.
error_t mqttClientDisconnect(MqttClientContext *context)
Gracefully disconnect from the MQTT server.
Definition: mqtt_client.c:993
Definitions common to MQTT client and server.
#define WebSocket
Definition: web_socket.h:175
error_t mqttClientSetIdentifier(MqttClientContext *context, const char_t *clientId)
Set client identifier.
Definition: mqtt_client.c:280
error_t mqttClientRegisterCallbacks(MqttClientContext *context, const MqttClientCallbacks *callbacks)
Register MQTT client callbacks.
Definition: mqtt_client.c:115
MqttProtocolLevel protocolLevel
MQTT protocol version.
Definition: mqtt_client.h:294
uint8_t message[]
Definition: chap.h:150
void(* MqttClientPubAckCallback)(MqttClientContext *context, uint16_t packetId)
PUBACK message received callback.
Definition: mqtt_client.h:189
error_t mqttClientSetTimeout(MqttClientContext *context, uint16_t timeout)
Set communication timeout.
Definition: mqtt_client.c:182
General definitions for cryptographic algorithms.
#define MQTT_CLIENT_MAX_USERNAME_LEN
Definition: mqtt_client.h:94
size_t packetLen
Length of the entire MQTT packet.
Definition: mqtt_client.h:332
MqttPacketType packetType
Control packet type.
Definition: mqtt_client.h:333
WebSocket * webSocket
Underlying WebSocket.
Definition: mqtt_client.h:327
MqttClientState state
MQTT client state.
Definition: mqtt_client.h:317
IP network address.
Definition: ip.h:57
error_t mqttClientClose(MqttClientContext *context)
Close the connection with the MQTT server.
Definition: mqtt_client.c:1077
MqttClientPubAckCallback unsubAckCallback
UNSUBACK message received callback.
Definition: mqtt_client.h:280
TlsContext * tlsContext
TLS context.
Definition: mqtt_client.h:323
void(* MqttClientPubRelCallback)(MqttClientContext *context, uint16_t packetId)
PUBREL message received callback.
Definition: mqtt_client.h:205
TLS session state.
Definition: tls.h:1820
error_t mqttClientProcessEvents(MqttClientContext *context, systime_t timeout)
Process MQTT client events.
Definition: mqtt_client.c:1106
error_t mqttClientSetProtocolLevel(MqttClientContext *context, MqttProtocolLevel protocolLevel)
Set the MQTT protocol version to be used.
Definition: mqtt_client.c:137
MqttClientPubAckCallback pubRecCallback
PUBREC message received callback.
Definition: mqtt_client.h:276
MqttClientSettings settings
MQTT client settings.
Definition: mqtt_client.h:315
void(* MqttClientPubRecCallback)(MqttClientContext *context, uint16_t packetId)
PUBREC message received callback.
Definition: mqtt_client.h:197
systime_t timeout
Communication timeout.
Definition: mqtt_client.h:297
uint8_t qos
Definition: mqtt_common.h:177
MqttClientPingRespCallback pingRespCallback
PINGRESP message received callback.
Definition: mqtt_client.h:281
uint8_t * packet
Pointer to the incoming/outgoing MQTT packet.
Definition: mqtt_client.h:330
error_t mqttClientPing(MqttClientContext *context, systime_t *rtt)
Send ping request.
Definition: mqtt_client.c:885
#define Socket
Definition: socket.h:34
MQTT client callback functions.
Definition: mqtt_client.h:271
size_t length
Length of the Will message payload.
Definition: mqtt_client.h:261
size_t remainingLen
Length of the variable header and payload.
Definition: mqtt_client.h:335
void(* MqttClientConnAckCallback)(MqttClientContext *context, uint8_t connectAckFlags, uint8_t connectReturnCode)
CONNACK message received callback.
Definition: mqtt_client.h:172
error_t mqttClientUnsubscribe(MqttClientContext *context, const char_t *topic, uint16_t *packetId)
Unsubscribe from topic.
Definition: mqtt_client.c:782
void(* MqttClientSubAckCallback)(MqttClientContext *context, uint16_t packetId)
SUBACK message received callback.
Definition: mqtt_client.h:221
MqttQosLevel
Quality of service level.
Definition: mqtt_common.h:84
uint8_t cleanSession
MqttQosLevel qos
QoS level to be used when publishing the Will message.
Definition: mqtt_client.h:262
char_t clientId[]
error_t mqttClientConnect(MqttClientContext *context, const IpAddr *serverIpAddr, uint16_t serverPort, bool_t cleanSession)
Establish connection with the MQTT server.
Definition: mqtt_client.c:423
MqttClientConnAckCallback connAckCallback
CONNACK message received callback.
Definition: mqtt_client.h:273
error_t mqttClientSetUri(MqttClientContext *context, const char_t *uri)
Set the name of the resource being requested.
Definition: mqtt_client.c:253
NetInterface * interface
Underlying network interface.
Definition: mqtt_client.h:320
void(* MqttClientPingRespCallback)(MqttClientContext *context)
PINGRESP message received callback.
Definition: mqtt_client.h:237
MqttClientPubAckCallback pubRelCallback
PUBREL message received callback.
Definition: mqtt_client.h:277
error_t mqttClientSetAuthInfo(MqttClientContext *context, const char_t *username, const char_t *password)
Set authentication information.
Definition: mqtt_client.c:307
void mqttClientInitCallbacks(MqttClientCallbacks *callbacks)
Initialize callback structure.
Definition: mqtt_client.c:101
MQTT client context.
Definition: mqtt_client.h:313
error_t mqttClientBindToInterface(MqttClientContext *context, NetInterface *interface)
Bind the MQTT client to a particular network interface.
Definition: mqtt_client.c:397
error_t mqttClientSetTransportProtocol(MqttClientContext *context, MqttTransportProtocol transportProtocol)
Set the transport protocol to be used.
Definition: mqtt_client.c:160
error_t mqttClientSetKeepAlive(MqttClientContext *context, uint16_t keepAlive)
Set keep-alive value.
Definition: mqtt_client.c:205
systime_t keepAliveTimestamp
Timestamp used to manage keep-alive.
Definition: mqtt_client.h:318
#define MQTT_CLIENT_MAX_WILL_TOPIC_LEN
Definition: mqtt_client.h:108
MqttClientCallbacks callbacks
MQTT client callback functions.
Definition: mqtt_client.h:316
TlsSessionState tlsSession
TLS session state.
Definition: mqtt_client.h:324
#define MQTT_CLIENT_MAX_URI_LEN
Definition: mqtt_client.h:80
MqttTransportProtocol transportProtocol
Transport protocol.
Definition: mqtt_client.h:295
error_t mqttClientPublish(MqttClientContext *context, const char_t *topic, const void *message, size_t length, MqttQosLevel qos, bool_t retain, uint16_t *packetId)
Publish message.
Definition: mqtt_client.c:559
MqttClientTlsInitCallback tlsInitCallback
TLS initialization callback.
Definition: mqtt_client.h:283
#define MQTT_CLIENT_MAX_ID_LEN
Definition: mqtt_client.h:87
uint8_t buffer[MQTT_CLIENT_BUFFER_SIZE]
Internal buffer.
Definition: mqtt_client.h:329
error_t mqttClientSetWillMessage(MqttClientContext *context, const char_t *topic, const void *message, size_t length, MqttQosLevel qos, bool_t retain)
Specify the Will message.
Definition: mqtt_client.c:344
error_t
Error codes.
Definition: error.h:40
uint8_t retain
Definition: mqtt_common.h:176
#define MQTT_CLIENT_MAX_PASSWORD_LEN
Definition: mqtt_client.h:101
void(* MqttClientPublishCallback)(MqttClientContext *context, const char_t *topic, const uint8_t *message, size_t length, bool_t dup, MqttQosLevel qos, bool_t retain, uint16_t packetId)
PUBLISH message received callback.
Definition: mqtt_client.h:180
#define MQTT_CLIENT_MAX_WILL_PAYLOAD_LEN
Definition: mqtt_client.h:115
MQTT client settings.
Definition: mqtt_client.h:292
void(* MqttClientUnsubAckCallback)(MqttClientContext *context, uint16_t packetId)
UNSUBACK message received callback.
Definition: mqtt_client.h:229
MqttClientWillMessage willMessage
Will message.
Definition: mqtt_client.h:305
void(* MqttClientPubCompCallback)(MqttClientContext *context, uint16_t packetId)
PUBCOMP message received callback.
Definition: mqtt_client.h:213
#define NetInterface
Definition: net.h:34
MqttClientPubAckCallback pubCompCallback
PUBCOMP message received callback.
Definition: mqtt_client.h:278
error_t mqttClientSubscribe(MqttClientContext *context, const char_t *topic, MqttQosLevel qos, uint16_t *packetId)
Subscribe to topic.
Definition: mqtt_client.c:678
uint8_t dup
Definition: mqtt_common.h:178
error_t mqttClientSetHost(MqttClientContext *context, const char_t *host)
Set the hostname of the resource being requested.
Definition: mqtt_client.c:226
uint16_t keepAlive
Keep-alive time interval.
Definition: mqtt_client.h:296
Socket * socket
Underlying TCP socket.
Definition: mqtt_client.h:321
size_t packetPos
Current position.
Definition: mqtt_client.h:331
uint8_t length
Definition: dtls_misc.h:140
error_t(* MqttClientTlsInitCallback)(MqttClientContext *context, TlsContext *tlsContext)
TLS initialization callback.
Definition: mqtt_client.h:247
#define MqttClientContext
Definition: mqtt_client.h:140
#define TlsContext
Definition: tls.h:34
MqttClientState
MQTT client states.
Definition: mqtt_client.h:152
int bool_t
Definition: compiler_port.h:47
MqttClientPublishCallback publishCallback
PUBLISH message received callback.
Definition: mqtt_client.h:274
MqttProtocolLevel
MQTT protocol level.
Definition: mqtt_common.h:60
bool_t retain
Specifies if the Will message is to be retained.
Definition: mqtt_client.h:263
error_t mqttClientInit(MqttClientContext *context)
Initialize MQTT client context.
Definition: mqtt_client.c:50
WebSocket API (client and server)