Paho MQTT C Client Library
MQTTClient.h
Go to the documentation of this file.
1 /*******************************************************************************
2  * Copyright (c) 2009, 2025 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 
107 /*
109 */
110 #if !defined(MQTTCLIENT_H)
111 #define MQTTCLIENT_H
112 
113 #if defined(__cplusplus)
114  extern "C" {
115 #endif
116 
117 #include <stdio.h>
118 /*
120 */
121 
122 #include "MQTTExportDeclarations.h"
123 
124 #include "MQTTProperties.h"
125 #include "MQTTReasonCodes.h"
126 #include "MQTTSubscribeOpts.h"
127 #if !defined(NO_PERSISTENCE)
128 #include "MQTTClientPersistence.h"
129 #else
130 #define MQTTCLIENT_PERSISTENCE_NONE 1
131 #endif
132 
137 #define MQTTCLIENT_SUCCESS 0
138 
142 #define MQTTCLIENT_FAILURE -1
143 
144 /* error code -2 is MQTTCLIENT_PERSISTENCE_ERROR */
145 
149 #define MQTTCLIENT_DISCONNECTED -3
150 
154 #define MQTTCLIENT_MAX_MESSAGES_INFLIGHT -4
155 
158 #define MQTTCLIENT_BAD_UTF8_STRING -5
159 
162 #define MQTTCLIENT_NULL_PARAMETER -6
163 
168 #define MQTTCLIENT_TOPICNAME_TRUNCATED -7
169 
173 #define MQTTCLIENT_BAD_STRUCTURE -8
174 
177 #define MQTTCLIENT_BAD_QOS -9
178 
181 #define MQTTCLIENT_SSL_NOT_SUPPORTED -10
182 
185  #define MQTTCLIENT_BAD_MQTT_VERSION -11
186 
195 #define MQTTCLIENT_BAD_PROTOCOL -14
196 
199  #define MQTTCLIENT_BAD_MQTT_OPTION -15
200 
203  #define MQTTCLIENT_WRONG_MQTT_VERSION -16
204 
207  #define MQTTCLIENT_0_LEN_WILL_TOPIC -17
208 
209 
213 #define MQTTVERSION_DEFAULT 0
214 
217 #define MQTTVERSION_3_1 3
218 
221 #define MQTTVERSION_3_1_1 4
222 
225  #define MQTTVERSION_5 5
226 
229 #define MQTT_BAD_SUBSCRIBE 0x80
230 
234 typedef struct
235 {
237  char struct_id[4];
243 
244 #define MQTTClient_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
245 
250 LIBMQTT_API void MQTTClient_global_init(MQTTClient_init_options* inits);
251 
256 typedef void* MQTTClient;
268 typedef int MQTTClient_token;
269 
276 typedef struct
277 {
279  char struct_id[4];
286  void* payload;
300  int qos;
319  int retained;
326  int dup;
330  int msgid;
336 
337 #define MQTTClient_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }
338 
369 typedef int MQTTClient_messageArrived(void* context, char* topicName, int topicLen, MQTTClient_message* message);
370 
391 typedef void MQTTClient_deliveryComplete(void* context, MQTTClient_deliveryToken dt);
392 
408 typedef void MQTTClient_connectionLost(void* context, char* cause);
409 
439 LIBMQTT_API int MQTTClient_setCallbacks(MQTTClient handle, void* context, MQTTClient_connectionLost* cl,
441 
442 
452 typedef void MQTTClient_disconnected(void* context, MQTTProperties* properties,
453  enum MQTTReasonCodes reasonCode);
454 
468 LIBMQTT_API int MQTTClient_setDisconnected(MQTTClient handle, void* context, MQTTClient_disconnected* co);
469 
493 typedef void MQTTClient_published(void* context, int dt, int packet_type, MQTTProperties* properties,
494  enum MQTTReasonCodes reasonCode);
495 
496 LIBMQTT_API int MQTTClient_setPublished(MQTTClient handle, void* context, MQTTClient_published* co);
497 
550 LIBMQTT_API int MQTTClient_create(MQTTClient* handle, const char* serverURI, const char* clientId,
551  int persistence_type, void* persistence_context);
552 
554 typedef struct
555 {
557  char struct_id[4];
567 
568 #define MQTTClient_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 0, MQTTVERSION_DEFAULT }
569 
614 LIBMQTT_API int MQTTClient_createWithOptions(MQTTClient* handle, const char* serverURI, const char* clientId,
615  int persistence_type, void* persistence_context, MQTTClient_createOptions* options);
616 
629 typedef struct
630 {
632  char struct_id[4];
638  const char* topicName;
640  const char* message;
644  int retained;
649  int qos;
651  struct
652  {
653  int len;
654  const void* data;
655  } payload;
657 
658 #define MQTTClient_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, {0, NULL} }
659 
660 #define MQTT_SSL_VERSION_DEFAULT 0
661 #define MQTT_SSL_VERSION_TLS_1_0 1
662 #define MQTT_SSL_VERSION_TLS_1_1 2
663 #define MQTT_SSL_VERSION_TLS_1_2 3
664 
677 typedef struct
678 {
680  char struct_id[4];
681 
690 
692  const char* trustStore;
693 
697  const char* keyStore;
698 
702  const char* privateKey;
703 
705  const char* privateKeyPassword;
706 
715  const char* enabledCipherSuites;
716 
719 
725 
731  int verify;
732 
738  const char* CApath;
739 
744  int (*ssl_error_cb) (const char *str, size_t len, void *u);
745 
751 
757  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);
758 
764 
771 
779  const unsigned char *protos;
780 
785  unsigned int protos_len;
787 
788 #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 }
789 
797 typedef struct
798 {
799  const char* name;
800  const char* value;
802 
809 
830 typedef struct
831 {
833  char struct_id[4];
886  int reliable;
898  const char* username;
904  const char* password;
939  char* const* serverURIs;
951  struct
952  {
953  const char* serverURI;
954  int MQTTVersion;
956  } returned;
960  struct
961  {
962  int len;
963  const void* data;
964  } binarypwd;
969  /*
970  * MQTT V5 clean start flag. Only clears state at the beginning of the session.
971  */
982  const char* httpProxy;
986  const char* httpsProxy;
988 
990 #define MQTTClient_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 8, 60, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
991 0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
992 
994 #define MQTTClient_connectOptions_initializer5 { {'M', 'Q', 'T', 'C'}, 8, 60, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
995 0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
996 
1000 #define MQTTClient_connectOptions_initializer_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
1001 0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
1002 
1006 #define MQTTClient_connectOptions_initializer5_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
1007 0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
1008 
1029 LIBMQTT_API int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions* options);
1030 
1032 typedef struct MQTTResponse
1033 {
1034  int version; /* the version number of this structure */
1035  enum MQTTReasonCodes reasonCode; /* the MQTT 5.0 reason code returned */
1036  int reasonCodeCount; /* the number of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
1037  enum MQTTReasonCodes* reasonCodes; /* a list of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
1038  MQTTProperties* properties; /* optionally, the MQTT 5.0 properties returned */
1039 } MQTTResponse;
1040 
1041 #define MQTTResponse_initializer {1, MQTTREASONCODE_SUCCESS, 0, NULL, NULL}
1042 
1047 LIBMQTT_API void MQTTResponse_free(MQTTResponse response);
1048 
1062 LIBMQTT_API MQTTResponse MQTTClient_connect5(MQTTClient handle, MQTTClient_connectOptions* options,
1063  MQTTProperties* connectProperties, MQTTProperties* willProperties);
1064 
1083 LIBMQTT_API int MQTTClient_disconnect(MQTTClient handle, int timeout);
1084 
1085 LIBMQTT_API int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties* props);
1086 
1094 LIBMQTT_API int MQTTClient_isConnected(MQTTClient handle);
1095 
1096 
1097 /* Subscribe is synchronous. QoS list parameter is changed on return to granted QoSs.
1098  Returns return code, MQTTCLIENT_SUCCESS == success, non-zero some sort of error (TBD) */
1099 
1113 LIBMQTT_API int MQTTClient_subscribe(MQTTClient handle, const char* topic, int qos);
1114 
1128 LIBMQTT_API MQTTResponse MQTTClient_subscribe5(MQTTClient handle, const char* topic, int qos,
1129  MQTTSubscribe_options* opts, MQTTProperties* props);
1130 
1147 LIBMQTT_API int MQTTClient_subscribeMany(MQTTClient handle, int count, char* const* topic, int* qos);
1148 
1165 LIBMQTT_API MQTTResponse MQTTClient_subscribeMany5(MQTTClient handle, int count, char* const* topic,
1166  int* qos, MQTTSubscribe_options* opts, MQTTProperties* props);
1167 
1179 LIBMQTT_API int MQTTClient_unsubscribe(MQTTClient handle, const char* topic);
1180 
1191 LIBMQTT_API MQTTResponse MQTTClient_unsubscribe5(MQTTClient handle, const char* topic, MQTTProperties* props);
1192 
1204 LIBMQTT_API int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char* const* topic);
1205 
1217 LIBMQTT_API MQTTResponse MQTTClient_unsubscribeMany5(MQTTClient handle, int count, char* const* topic, MQTTProperties* props);
1218 
1240 LIBMQTT_API int MQTTClient_publish(MQTTClient handle, const char* topicName, int payloadlen, const void* payload, int qos, int retained,
1241  MQTTClient_deliveryToken* dt);
1242 
1264 LIBMQTT_API MQTTResponse MQTTClient_publish5(MQTTClient handle, const char* topicName, int payloadlen, const void* payload,
1265  int qos, int retained, MQTTProperties* properties, MQTTClient_deliveryToken* dt);
1285 LIBMQTT_API int MQTTClient_publishMessage(MQTTClient handle, const char* topicName, MQTTClient_message* msg, MQTTClient_deliveryToken* dt);
1286 
1287 
1307 LIBMQTT_API MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char* topicName, MQTTClient_message* msg,
1308  MQTTClient_deliveryToken* dt);
1309 
1325 LIBMQTT_API int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout);
1326 
1327 
1346 LIBMQTT_API int MQTTClient_getPendingDeliveryTokens(MQTTClient handle, MQTTClient_deliveryToken **tokens);
1347 
1354 LIBMQTT_API void MQTTClient_yield(void);
1355 
1387 LIBMQTT_API int MQTTClient_receive(MQTTClient handle, char** topicName, int* topicLen, MQTTClient_message** message,
1388  unsigned long timeout);
1389 
1400 LIBMQTT_API void MQTTClient_freeMessage(MQTTClient_message** msg);
1401 
1410 LIBMQTT_API void MQTTClient_free(void* ptr);
1411 
1418 LIBMQTT_API void* MQTTClient_malloc(size_t size);
1419 
1427 LIBMQTT_API void MQTTClient_destroy(MQTTClient* handle);
1428 
1429 
1431 {
1439 };
1440 
1441 
1447 LIBMQTT_API void MQTTClient_setTraceLevel(enum MQTTCLIENT_TRACE_LEVELS level);
1448 
1449 
1459 typedef void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char* message);
1460 
1467 LIBMQTT_API void MQTTClient_setTraceCallback(MQTTClient_traceCallback* callback);
1468 
1476 LIBMQTT_API int MQTTClient_setCommandTimeout(MQTTClient handle, unsigned long milliSeconds);
1477 
1483 LIBMQTT_API const char* MQTTClient_strerror(int code);
1484 
1485 #if defined(__cplusplus)
1486  }
1487 #endif
1488 
1489 #endif
1490 
int MQTTVersion
Definition: MQTTClient.h:565
Definition: MQTTClient.h:1434
void MQTTClient_free(void *ptr)
int MQTTVersion
Definition: MQTTClient.h:947
int MQTTClient_getPendingDeliveryTokens(MQTTClient handle, MQTTClient_deliveryToken **tokens)
void * MQTTClient
Definition: MQTTClient.h:256
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:770
int struct_version
Definition: MQTTClient.h:559
const char * MQTTClient_strerror(int code)
void MQTTClient_yield(void)
const char * message
Definition: MQTTClient.h:640
int struct_version
Definition: MQTTClient.h:844
const char * username
Definition: MQTTClient.h:898
const char * httpsProxy
Definition: MQTTClient.h:986
void MQTTClient_connectionLost(void *context, char *cause)
Definition: MQTTClient.h:408
int dup
Definition: MQTTClient.h:326
int MQTTClient_unsubscribe(MQTTClient handle, const char *topic)
const char * enabledCipherSuites
Definition: MQTTClient.h:715
int MQTTClient_subscribeMany(MQTTClient handle, int count, char *const *topic, int *qos)
int struct_version
Definition: MQTTClient.h:282
int qos
Definition: MQTTClient.h:300
const char * password
Definition: MQTTClient.h:904
const char * serverURI
Definition: MQTTClient.h:953
Definition: MQTTClient.h:1436
int msgid
Definition: MQTTClient.h:330
MQTTProperties * properties
Definition: MQTTClient.h:1038
int retained
Definition: MQTTClient.h:644
const void * data
Definition: MQTTClient.h:654
int retryInterval
Definition: MQTTClient.h:916
int maxInflightMessages
Definition: MQTTClient.h:968
int reliable
Definition: MQTTClient.h:886
Definition: MQTTClient.h:276
int MQTTClient_receive(MQTTClient handle, char **topicName, int *topicLen, MQTTClient_message **message, unsigned long timeout)
const unsigned char * protos
Definition: MQTTClient.h:779
MQTTProperties properties
Definition: MQTTClient.h:334
int cleanstart
Definition: MQTTClient.h:972
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:854
int payloadlen
Definition: MQTTClient.h:284
int verify
Definition: MQTTClient.h:731
void * ssl_psk_context
Definition: MQTTClient.h:763
unsigned int protos_len
Definition: MQTTClient.h:785
const char * topicName
Definition: MQTTClient.h:638
int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions *options)
int connectTimeout
Definition: MQTTClient.h:908
Definition: MQTTSubscribeOpts.h:21
Definition: MQTTClient.h:234
int struct_version
Definition: MQTTClient.h:689
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:1459
int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties *props)
void * MQTTClient_malloc(size_t size)
Definition: MQTTClient.h:1433
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:963
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:677
enum MQTTReasonCodes * reasonCodes
Definition: MQTTClient.h:1037
Definition: MQTTClient.h:1032
int struct_version
Definition: MQTTClient.h:239
int qos
Definition: MQTTClient.h:649
Definition: MQTTClient.h:1438
int sslVersion
Definition: MQTTClient.h:724
int len
Definition: MQTTClient.h:962
Definition: MQTTClient.h:629
void * ssl_error_context
Definition: MQTTClient.h:750
int version
Definition: MQTTClient.h:1034
const MQTTClient_nameValue * httpHeaders
Definition: MQTTClient.h:976
int reasonCodeCount
Definition: MQTTClient.h:1036
const char * trustStore
Definition: MQTTClient.h:692
Definition: MQTTClient.h:1435
int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char *const *topic)
int sessionPresent
Definition: MQTTClient.h:955
enum MQTTReasonCodes reasonCode
Definition: MQTTClient.h:1035
int MQTTClient_setCallbacks(MQTTClient handle, void *context, MQTTClient_connectionLost *cl, MQTTClient_messageArrived *ma, MQTTClient_deliveryComplete *dc)
Definition: MQTTClient.h:830
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:799
MQTTClient_willOptions * will
Definition: MQTTClient.h:892
void MQTTClient_deliveryComplete(void *context, MQTTClient_deliveryToken dt)
Definition: MQTTClient.h:391
const char * privateKeyPassword
Definition: MQTTClient.h:705
int MQTTClient_deliveryToken
Definition: MQTTClient.h:267
char *const * serverURIs
Definition: MQTTClient.h:939
int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout)
const char * privateKey
Definition: MQTTClient.h:702
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:921
Definition: MQTTProperties.h:115
Definition: MQTTClient.h:1432
MQTTReasonCodes
Definition: MQTTReasonCodes.h:23
int MQTTClient_isConnected(MQTTClient handle)
int MQTTClient_token
Definition: MQTTClient.h:268
int MQTTClient_setDisconnected(MQTTClient handle, void *context, MQTTClient_disconnected *co)
int serverURIcount
Definition: MQTTClient.h:925
Definition: MQTTClient.h:1437
int MQTTClient_create(MQTTClient *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context)
const char * keyStore
Definition: MQTTClient.h:697
void MQTTResponse_free(MQTTResponse response)
MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
int retained
Definition: MQTTClient.h:319
int enableServerCertAuth
Definition: MQTTClient.h:718
int len
Definition: MQTTClient.h:653
void MQTTClient_disconnected(void *context, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
Definition: MQTTClient.h:452
struct MQTTResponse MQTTResponse
const char * httpProxy
Definition: MQTTClient.h:982
MQTTClient_nameValue * MQTTClient_getVersionInfo(void)
const char * value
Definition: MQTTClient.h:800
void MQTTClient_published(void *context, int dt, int packet_type, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
Definition: MQTTClient.h:493
int cleansession
Definition: MQTTClient.h:876
int do_openssl_init
Definition: MQTTClient.h:241
This structure represents a persistent data store, used to store outbound and inbound messages...
Definition: MQTTClient.h:554
int struct_version
Definition: MQTTClient.h:636
void * payload
Definition: MQTTClient.h:286
int MQTTClient_messageArrived(void *context, char *topicName, int topicLen, MQTTClient_message *message)
Definition: MQTTClient.h:369
void MQTTClient_freeMessage(MQTTClient_message **msg)
Definition: MQTTClient.h:797
const char * CApath
Definition: MQTTClient.h:738
MQTTCLIENT_TRACE_LEVELS
Definition: MQTTClient.h:1430