Paho MQTT C Client Library
MQTTClient.h
Go to the documentation of this file.
1 /*******************************************************************************
2  * Copyright (c) 2009, 2021 IBM Corp., Ian Craggs and others
3  *
4  * All rights reserved. This program and the accompanying materials
5  * are made available under the terms of the Eclipse Public License v2.0
6  * and Eclipse Distribution License v1.0 which accompany this distribution.
7  *
8  * The Eclipse Public License is available at
9  * https://www.eclipse.org/legal/epl-2.0/
10  * and the Eclipse Distribution License is available at
11  * http://www.eclipse.org/org/documents/edl-v10.php.
12  *
13  * Contributors:
14  * Ian Craggs - initial API and implementation and/or initial documentation
15  * Ian Craggs, Allan Stockdill-Mander - SSL updates
16  * Ian Craggs - multiple server connection support
17  * Ian Craggs - MQTT 3.1.1 support
18  * Ian Craggs - remove const from eyecatchers #168
19  *******************************************************************************/
20 
104 /*
106 */
107 #if !defined(MQTTCLIENT_H)
108 #define MQTTCLIENT_H
109 
110 #if defined(__cplusplus)
111  extern "C" {
112 #endif
113 
114 #include <stdio.h>
115 /*
117 */
118 
119 #include "MQTTExportDeclarations.h"
120 
121 #include "MQTTProperties.h"
122 #include "MQTTReasonCodes.h"
123 #include "MQTTSubscribeOpts.h"
124 #if !defined(NO_PERSISTENCE)
125 #include "MQTTClientPersistence.h"
126 #endif
127 
132 #define MQTTCLIENT_SUCCESS 0
133 
137 #define MQTTCLIENT_FAILURE -1
138 
139 /* error code -2 is MQTTCLIENT_PERSISTENCE_ERROR */
140 
144 #define MQTTCLIENT_DISCONNECTED -3
145 
149 #define MQTTCLIENT_MAX_MESSAGES_INFLIGHT -4
150 
153 #define MQTTCLIENT_BAD_UTF8_STRING -5
154 
157 #define MQTTCLIENT_NULL_PARAMETER -6
158 
163 #define MQTTCLIENT_TOPICNAME_TRUNCATED -7
164 
168 #define MQTTCLIENT_BAD_STRUCTURE -8
169 
172 #define MQTTCLIENT_BAD_QOS -9
173 
176 #define MQTTCLIENT_SSL_NOT_SUPPORTED -10
177 
180  #define MQTTCLIENT_BAD_MQTT_VERSION -11
181 
186 #define MQTTCLIENT_BAD_PROTOCOL -14
187 
190  #define MQTTCLIENT_BAD_MQTT_OPTION -15
191 
194  #define MQTTCLIENT_WRONG_MQTT_VERSION -16
195 
198  #define MQTTCLIENT_0_LEN_WILL_TOPIC -17
199 
200 
204 #define MQTTVERSION_DEFAULT 0
205 
208 #define MQTTVERSION_3_1 3
209 
212 #define MQTTVERSION_3_1_1 4
213 
216  #define MQTTVERSION_5 5
217 
220 #define MQTT_BAD_SUBSCRIBE 0x80
221 
225 typedef struct
226 {
228  char struct_id[4];
234 
235 #define MQTTClient_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
236 
241 LIBMQTT_API void MQTTClient_global_init(MQTTClient_init_options* inits);
242 
247 typedef void* MQTTClient;
259 typedef int MQTTClient_token;
260 
267 typedef struct
268 {
270  char struct_id[4];
277  void* payload;
291  int qos;
310  int retained;
317  int dup;
321  int msgid;
327 
328 #define MQTTClient_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }
329 
360 typedef int MQTTClient_messageArrived(void* context, char* topicName, int topicLen, MQTTClient_message* message);
361 
383 
399 typedef void MQTTClient_connectionLost(void* context, char* cause);
400 
429 LIBMQTT_API int MQTTClient_setCallbacks(MQTTClient handle, void* context, MQTTClient_connectionLost* cl,
431 
432 
442 typedef void MQTTClient_disconnected(void* context, MQTTProperties* properties,
443  enum MQTTReasonCodes reasonCode);
444 
458 LIBMQTT_API int MQTTClient_setDisconnected(MQTTClient handle, void* context, MQTTClient_disconnected* co);
459 
483 typedef void MQTTClient_published(void* context, int dt, int packet_type, MQTTProperties* properties,
484  enum MQTTReasonCodes reasonCode);
485 
486 LIBMQTT_API int MQTTClient_setPublished(MQTTClient handle, void* context, MQTTClient_published* co);
487 
532 LIBMQTT_API int MQTTClient_create(MQTTClient* handle, const char* serverURI, const char* clientId,
533  int persistence_type, void* persistence_context);
534 
536 typedef struct
537 {
539  char struct_id[4];
549 
550 #define MQTTClient_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 0, MQTTVERSION_DEFAULT }
551 
596 LIBMQTT_API int MQTTClient_createWithOptions(MQTTClient* handle, const char* serverURI, const char* clientId,
597  int persistence_type, void* persistence_context, MQTTClient_createOptions* options);
598 
611 typedef struct
612 {
614  char struct_id[4];
620  const char* topicName;
622  const char* message;
626  int retained;
631  int qos;
633  struct
634  {
635  int len;
636  const void* data;
637  } payload;
639 
640 #define MQTTClient_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, {0, NULL} }
641 
642 #define MQTT_SSL_VERSION_DEFAULT 0
643 #define MQTT_SSL_VERSION_TLS_1_0 1
644 #define MQTT_SSL_VERSION_TLS_1_1 2
645 #define MQTT_SSL_VERSION_TLS_1_2 3
646 
659 typedef struct
660 {
662  char struct_id[4];
663 
672 
674  const char* trustStore;
675 
679  const char* keyStore;
680 
684  const char* privateKey;
685 
687  const char* privateKeyPassword;
688 
697  const char* enabledCipherSuites;
698 
701 
707 
713  int verify;
714 
720  const char* CApath;
721 
726  int (*ssl_error_cb) (const char *str, size_t len, void *u);
727 
733 
739  unsigned int (*ssl_psk_cb) (const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len, void *u);
740 
746 
753 
761  const unsigned char *protos;
762 
767  unsigned int protos_len;
769 
770 #define MQTTClient_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 5, NULL, NULL, NULL, NULL, NULL, 1, MQTT_SSL_VERSION_DEFAULT, 0, NULL, NULL, NULL, NULL, NULL, 0, NULL, 0 }
771 
779 typedef struct
780 {
781  const char* name;
782  const char* value;
784 
791 
806 typedef struct
807 {
809  char struct_id[4];
862  int reliable;
874  const char* username;
880  const char* password;
915  char* const* serverURIs;
927  struct
928  {
929  const char* serverURI;
930  int MQTTVersion;
932  } returned;
936  struct
937  {
938  int len;
939  const void* data;
940  } binarypwd;
945  /*
946  * MQTT V5 clean start flag. Only clears state at the beginning of the session.
947  */
956  const char* httpProxy;
960  const char* httpsProxy;
962 
963 #define MQTTClient_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 8, 60, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
964 0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
965 
966 #define MQTTClient_connectOptions_initializer5 { {'M', 'Q', 'T', 'C'}, 8, 60, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
967 0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
968 
969 #define MQTTClient_connectOptions_initializer_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
970 0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
971 
972 #define MQTTClient_connectOptions_initializer5_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
973 0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
974 
995 LIBMQTT_API int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions* options);
996 
998 typedef struct MQTTResponse
999 {
1000  int version; /* the version number of this structure */
1001  enum MQTTReasonCodes reasonCode; /* the MQTT 5.0 reason code returned */
1002  int reasonCodeCount; /* the number of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
1003  enum MQTTReasonCodes* reasonCodes; /* a list of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
1004  MQTTProperties* properties; /* optionally, the MQTT 5.0 properties returned */
1005 } MQTTResponse;
1006 
1007 #define MQTTResponse_initializer {1, MQTTREASONCODE_SUCCESS, 0, NULL, NULL}
1008 
1013 LIBMQTT_API void MQTTResponse_free(MQTTResponse response);
1014 
1029  MQTTProperties* connectProperties, MQTTProperties* willProperties);
1030 
1049 LIBMQTT_API int MQTTClient_disconnect(MQTTClient handle, int timeout);
1050 
1051 LIBMQTT_API int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties* props);
1052 
1060 LIBMQTT_API int MQTTClient_isConnected(MQTTClient handle);
1061 
1062 
1063 /* Subscribe is synchronous. QoS list parameter is changed on return to granted QoSs.
1064  Returns return code, MQTTCLIENT_SUCCESS == success, non-zero some sort of error (TBD) */
1065 
1079 LIBMQTT_API int MQTTClient_subscribe(MQTTClient handle, const char* topic, int qos);
1080 
1094 LIBMQTT_API MQTTResponse MQTTClient_subscribe5(MQTTClient handle, const char* topic, int qos,
1095  MQTTSubscribe_options* opts, MQTTProperties* props);
1096 
1113 LIBMQTT_API int MQTTClient_subscribeMany(MQTTClient handle, int count, char* const* topic, int* qos);
1114 
1131 LIBMQTT_API MQTTResponse MQTTClient_subscribeMany5(MQTTClient handle, int count, char* const* topic,
1132  int* qos, MQTTSubscribe_options* opts, MQTTProperties* props);
1133 
1145 LIBMQTT_API int MQTTClient_unsubscribe(MQTTClient handle, const char* topic);
1146 
1157 LIBMQTT_API MQTTResponse MQTTClient_unsubscribe5(MQTTClient handle, const char* topic, MQTTProperties* props);
1158 
1170 LIBMQTT_API int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char* const* topic);
1171 
1183 LIBMQTT_API MQTTResponse MQTTClient_unsubscribeMany5(MQTTClient handle, int count, char* const* topic, MQTTProperties* props);
1184 
1206 LIBMQTT_API int MQTTClient_publish(MQTTClient handle, const char* topicName, int payloadlen, const void* payload, int qos, int retained,
1208 
1230 LIBMQTT_API MQTTResponse MQTTClient_publish5(MQTTClient handle, const char* topicName, int payloadlen, const void* payload,
1231  int qos, int retained, MQTTProperties* properties, MQTTClient_deliveryToken* dt);
1251 LIBMQTT_API int MQTTClient_publishMessage(MQTTClient handle, const char* topicName, MQTTClient_message* msg, MQTTClient_deliveryToken* dt);
1252 
1253 
1273 LIBMQTT_API MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char* topicName, MQTTClient_message* msg,
1275 
1291 LIBMQTT_API int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout);
1292 
1293 
1313 
1320 LIBMQTT_API void MQTTClient_yield(void);
1321 
1353 LIBMQTT_API int MQTTClient_receive(MQTTClient handle, char** topicName, int* topicLen, MQTTClient_message** message,
1354  unsigned long timeout);
1355 
1366 LIBMQTT_API void MQTTClient_freeMessage(MQTTClient_message** msg);
1367 
1376 LIBMQTT_API void MQTTClient_free(void* ptr);
1377 
1385 LIBMQTT_API void MQTTClient_destroy(MQTTClient* handle);
1386 
1387 
1389 {
1397 };
1398 
1399 
1405 LIBMQTT_API void MQTTClient_setTraceLevel(enum MQTTCLIENT_TRACE_LEVELS level);
1406 
1407 
1416 typedef void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char* message);
1417 
1424 LIBMQTT_API void MQTTClient_setTraceCallback(MQTTClient_traceCallback* callback);
1425 
1433 LIBMQTT_API int MQTTClient_setCommandTimeout(MQTTClient handle, unsigned long milliSeconds);
1434 
1440 LIBMQTT_API const char* MQTTClient_strerror(int code);
1441 
1442 #if defined(__cplusplus)
1443  }
1444 #endif
1445 
1446 #endif
1447 
int MQTTVersion
Definition: MQTTClient.h:547
Definition: MQTTClient.h:1392
void MQTTClient_free(void *ptr)
int MQTTVersion
Definition: MQTTClient.h:923
int MQTTClient_getPendingDeliveryTokens(MQTTClient handle, MQTTClient_deliveryToken **tokens)
void * MQTTClient
Definition: MQTTClient.h:247
int MQTTClient_publish(MQTTClient handle, const char *topicName, int payloadlen, const void *payload, int qos, int retained, MQTTClient_deliveryToken *dt)
int disableDefaultTrustStore
Definition: MQTTClient.h:752
int struct_version
Definition: MQTTClient.h:541
const char * MQTTClient_strerror(int code)
void MQTTClient_yield(void)
const char * message
Definition: MQTTClient.h:622
int struct_version
Definition: MQTTClient.h:820
const char * username
Definition: MQTTClient.h:874
const char * httpsProxy
Definition: MQTTClient.h:960
void MQTTClient_connectionLost(void *context, char *cause)
Definition: MQTTClient.h:399
int dup
Definition: MQTTClient.h:317
int MQTTClient_unsubscribe(MQTTClient handle, const char *topic)
const char * enabledCipherSuites
Definition: MQTTClient.h:697
int MQTTClient_subscribeMany(MQTTClient handle, int count, char *const *topic, int *qos)
int struct_version
Definition: MQTTClient.h:273
int qos
Definition: MQTTClient.h:291
const char * password
Definition: MQTTClient.h:880
const char * serverURI
Definition: MQTTClient.h:929
Definition: MQTTClient.h:1394
int msgid
Definition: MQTTClient.h:321
MQTTProperties * properties
Definition: MQTTClient.h:1004
int retained
Definition: MQTTClient.h:626
const void * data
Definition: MQTTClient.h:636
int retryInterval
Definition: MQTTClient.h:892
int maxInflightMessages
Definition: MQTTClient.h:944
int reliable
Definition: MQTTClient.h:862
Definition: MQTTClient.h:267
int MQTTClient_receive(MQTTClient handle, char **topicName, int *topicLen, MQTTClient_message **message, unsigned long timeout)
const unsigned char * protos
Definition: MQTTClient.h:761
MQTTProperties properties
Definition: MQTTClient.h:325
int cleanstart
Definition: MQTTClient.h:948
MQTTResponse MQTTClient_unsubscribeMany5(MQTTClient handle, int count, char *const *topic, MQTTProperties *props)
void MQTTClient_global_init(MQTTClient_init_options *inits)
int keepAliveInterval
Definition: MQTTClient.h:830
int payloadlen
Definition: MQTTClient.h:275
int verify
Definition: MQTTClient.h:713
void * ssl_psk_context
Definition: MQTTClient.h:745
unsigned int protos_len
Definition: MQTTClient.h:767
const char * topicName
Definition: MQTTClient.h:620
int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions *options)
int connectTimeout
Definition: MQTTClient.h:884
Definition: MQTTSubscribeOpts.h:21
Definition: MQTTClient.h:225
int struct_version
Definition: MQTTClient.h:671
int MQTTClient_setCommandTimeout(MQTTClient handle, unsigned long milliSeconds)
int MQTTClient_disconnect(MQTTClient handle, int timeout)
void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char *message)
Definition: MQTTClient.h:1416
int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties *props)
Definition: MQTTClient.h:1391
void MQTTClient_setTraceCallback(MQTTClient_traceCallback *callback)
int MQTTClient_publishMessage(MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
MQTTResponse MQTTClient_subscribe5(MQTTClient handle, const char *topic, int qos, MQTTSubscribe_options *opts, MQTTProperties *props)
const void * data
Definition: MQTTClient.h:939
MQTTResponse MQTTClient_connect5(MQTTClient handle, MQTTClient_connectOptions *options, MQTTProperties *connectProperties, MQTTProperties *willProperties)
int MQTTClient_setPublished(MQTTClient handle, void *context, MQTTClient_published *co)
Definition: MQTTClient.h:659
enum MQTTReasonCodes * reasonCodes
Definition: MQTTClient.h:1003
Definition: MQTTClient.h:998
int struct_version
Definition: MQTTClient.h:230
int qos
Definition: MQTTClient.h:631
Definition: MQTTClient.h:1396
int sslVersion
Definition: MQTTClient.h:706
int len
Definition: MQTTClient.h:938
Definition: MQTTClient.h:611
void * ssl_error_context
Definition: MQTTClient.h:732
int version
Definition: MQTTClient.h:1000
const MQTTClient_nameValue * httpHeaders
Definition: MQTTClient.h:952
int reasonCodeCount
Definition: MQTTClient.h:1002
const char * trustStore
Definition: MQTTClient.h:674
Definition: MQTTClient.h:1393
int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char *const *topic)
int sessionPresent
Definition: MQTTClient.h:931
enum MQTTReasonCodes reasonCode
Definition: MQTTClient.h:1001
int MQTTClient_setCallbacks(MQTTClient handle, void *context, MQTTClient_connectionLost *cl, MQTTClient_messageArrived *ma, MQTTClient_deliveryComplete *dc)
Definition: MQTTClient.h:806
void MQTTClient_destroy(MQTTClient *handle)
int MQTTClient_createWithOptions(MQTTClient *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context, MQTTClient_createOptions *options)
int MQTTClient_subscribe(MQTTClient handle, const char *topic, int qos)
MQTTResponse MQTTClient_unsubscribe5(MQTTClient handle, const char *topic, MQTTProperties *props)
MQTTResponse MQTTClient_subscribeMany5(MQTTClient handle, int count, char *const *topic, int *qos, MQTTSubscribe_options *opts, MQTTProperties *props)
const char * name
Definition: MQTTClient.h:781
MQTTClient_willOptions * will
Definition: MQTTClient.h:868
void MQTTClient_deliveryComplete(void *context, MQTTClient_deliveryToken dt)
Definition: MQTTClient.h:382
const char * privateKeyPassword
Definition: MQTTClient.h:687
int MQTTClient_deliveryToken
Definition: MQTTClient.h:258
char *const * serverURIs
Definition: MQTTClient.h:915
int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout)
const char * privateKey
Definition: MQTTClient.h:684
void MQTTClient_setTraceLevel(enum MQTTCLIENT_TRACE_LEVELS level)
MQTTResponse MQTTClient_publish5(MQTTClient handle, const char *topicName, int payloadlen, const void *payload, int qos, int retained, MQTTProperties *properties, MQTTClient_deliveryToken *dt)
MQTTClient_SSLOptions * ssl
Definition: MQTTClient.h:897
Definition: MQTTProperties.h:112
Definition: MQTTClient.h:1390
MQTTReasonCodes
Definition: MQTTReasonCodes.h:23
int MQTTClient_isConnected(MQTTClient handle)
int MQTTClient_token
Definition: MQTTClient.h:259
int MQTTClient_setDisconnected(MQTTClient handle, void *context, MQTTClient_disconnected *co)
int serverURIcount
Definition: MQTTClient.h:901
Definition: MQTTClient.h:1395
int MQTTClient_create(MQTTClient *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context)
const char * keyStore
Definition: MQTTClient.h:679
void MQTTResponse_free(MQTTResponse response)
MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
int retained
Definition: MQTTClient.h:310
int enableServerCertAuth
Definition: MQTTClient.h:700
int len
Definition: MQTTClient.h:635
void MQTTClient_disconnected(void *context, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
Definition: MQTTClient.h:442
struct MQTTResponse MQTTResponse
const char * httpProxy
Definition: MQTTClient.h:956
MQTTClient_nameValue * MQTTClient_getVersionInfo(void)
const char * value
Definition: MQTTClient.h:782
void MQTTClient_published(void *context, int dt, int packet_type, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
Definition: MQTTClient.h:483
int cleansession
Definition: MQTTClient.h:852
int do_openssl_init
Definition: MQTTClient.h:232
This structure represents a persistent data store, used to store outbound and inbound messages...
Definition: MQTTClient.h:536
int struct_version
Definition: MQTTClient.h:618
void * payload
Definition: MQTTClient.h:277
int MQTTClient_messageArrived(void *context, char *topicName, int topicLen, MQTTClient_message *message)
Definition: MQTTClient.h:360
void MQTTClient_freeMessage(MQTTClient_message **msg)
Definition: MQTTClient.h:779
const char * CApath
Definition: MQTTClient.h:720
MQTTCLIENT_TRACE_LEVELS
Definition: MQTTClient.h:1388