Paho MQTT C Client Library
MQTTClient.h
Go to the documentation of this file.
1 /*******************************************************************************
2  * Copyright (c) 2009, 2020 IBM Corp. 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 
103 /*
105 */
106 #if !defined(MQTTCLIENT_H)
107 #define MQTTCLIENT_H
108 
109 #if defined(__cplusplus)
110  extern "C" {
111 #endif
112 
113 #include <stdio.h>
114 /*
116 */
117 
118 #include "MQTTExportDeclarations.h"
119 
120 #include "MQTTProperties.h"
121 #include "MQTTReasonCodes.h"
122 #include "MQTTSubscribeOpts.h"
123 #if !defined(NO_PERSISTENCE)
124 #include "MQTTClientPersistence.h"
125 #endif
126 
131 #define MQTTCLIENT_SUCCESS 0
132 
136 #define MQTTCLIENT_FAILURE -1
137 
138 /* error code -2 is MQTTCLIENT_PERSISTENCE_ERROR */
139 
143 #define MQTTCLIENT_DISCONNECTED -3
144 
148 #define MQTTCLIENT_MAX_MESSAGES_INFLIGHT -4
149 
152 #define MQTTCLIENT_BAD_UTF8_STRING -5
153 
156 #define MQTTCLIENT_NULL_PARAMETER -6
157 
162 #define MQTTCLIENT_TOPICNAME_TRUNCATED -7
163 
167 #define MQTTCLIENT_BAD_STRUCTURE -8
168 
171 #define MQTTCLIENT_BAD_QOS -9
172 
175 #define MQTTCLIENT_SSL_NOT_SUPPORTED -10
176 
179  #define MQTTCLIENT_BAD_MQTT_VERSION -11
180 
185 #define MQTTCLIENT_BAD_PROTOCOL -14
186 
189  #define MQTTCLIENT_BAD_MQTT_OPTION -15
190 
193  #define MQTTCLIENT_WRONG_MQTT_VERSION -16
194 
197  #define MQTTCLIENT_0_LEN_WILL_TOPIC -17
198 
199 
203 #define MQTTVERSION_DEFAULT 0
204 
207 #define MQTTVERSION_3_1 3
208 
211 #define MQTTVERSION_3_1_1 4
212 
215  #define MQTTVERSION_5 5
216 
219 #define MQTT_BAD_SUBSCRIBE 0x80
220 
224 typedef struct
225 {
227  char struct_id[4];
233 
234 #define MQTTClient_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
235 
240 LIBMQTT_API void MQTTClient_global_init(MQTTClient_init_options* inits);
241 
246 typedef void* MQTTClient;
258 typedef int MQTTClient_token;
259 
266 typedef struct
267 {
269  char struct_id[4];
276  void* payload;
290  int qos;
309  int retained;
316  int dup;
320  int msgid;
326 
327 #define MQTTClient_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }
328 
359 typedef int MQTTClient_messageArrived(void* context, char* topicName, int topicLen, MQTTClient_message* message);
360 
382 
398 typedef void MQTTClient_connectionLost(void* context, char* cause);
399 
427 LIBMQTT_API int MQTTClient_setCallbacks(MQTTClient handle, void* context, MQTTClient_connectionLost* cl,
429 
430 
440 typedef void MQTTClient_disconnected(void* context, MQTTProperties* properties,
441  enum MQTTReasonCodes reasonCode);
442 
456 LIBMQTT_API int MQTTClient_setDisconnected(MQTTClient handle, void* context, MQTTClient_disconnected* co);
457 
481 typedef void MQTTClient_published(void* context, int dt, int packet_type, MQTTProperties* properties,
482  enum MQTTReasonCodes reasonCode);
483 
484 LIBMQTT_API int MQTTClient_setPublished(MQTTClient handle, void* context, MQTTClient_published* co);
485 
528 LIBMQTT_API int MQTTClient_create(MQTTClient* handle, const char* serverURI, const char* clientId,
529  int persistence_type, void* persistence_context);
530 
532 typedef struct
533 {
535  char struct_id[4];
545 
546 #define MQTTClient_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 0, MQTTVERSION_DEFAULT }
547 
592 LIBMQTT_API int MQTTClient_createWithOptions(MQTTClient* handle, const char* serverURI, const char* clientId,
593  int persistence_type, void* persistence_context, MQTTClient_createOptions* options);
594 
607 typedef struct
608 {
610  char struct_id[4];
616  const char* topicName;
618  const char* message;
622  int retained;
627  int qos;
629  struct
630  {
631  int len;
632  const void* data;
633  } payload;
635 
636 #define MQTTClient_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, {0, NULL} }
637 
638 #define MQTT_SSL_VERSION_DEFAULT 0
639 #define MQTT_SSL_VERSION_TLS_1_0 1
640 #define MQTT_SSL_VERSION_TLS_1_1 2
641 #define MQTT_SSL_VERSION_TLS_1_2 3
642 
655 typedef struct
656 {
658  char struct_id[4];
661 
663  const char* trustStore;
664 
668  const char* keyStore;
669 
673  const char* privateKey;
675  const char* privateKeyPassword;
676 
685  const char* enabledCipherSuites;
686 
689 
695 
701  int verify;
702 
708  const char* CApath;
709 
714  int (*ssl_error_cb) (const char *str, size_t len, void *u);
715 
721 
727  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);
728 
734 
741 
743 
744 #define MQTTClient_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 4, NULL, NULL, NULL, NULL, NULL, 1, MQTT_SSL_VERSION_DEFAULT, 0, NULL, NULL, NULL, NULL, NULL, 0 }
745 
753 typedef struct
754 {
755  const char* name;
756  const char* value;
758 
765 
780 typedef struct
781 {
783  char struct_id[4];
835  int reliable;
847  const char* username;
853  const char* password;
885  char* const* serverURIs;
897  struct
898  {
899  const char* serverURI;
900  int MQTTVersion;
902  } returned;
906  struct
907  {
908  int len;
909  const void* data;
910  } binarypwd;
919  /*
920  * MQTT V5 clean start flag. Only clears state at the beginning of the session.
921  */
924 
925 #define MQTTClient_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 7, 60, 1, 1, NULL, NULL, NULL, 30, 0, NULL, 0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, NULL, -1, 0}
926 
927 #define MQTTClient_connectOptions_initializer5 { {'M', 'Q', 'T', 'C'}, 7, 60, 0, 1, NULL, NULL, NULL, 30, 0, NULL, 0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, NULL, -1, 1}
928 
949 LIBMQTT_API int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions* options);
950 
952 typedef struct MQTTResponse
953 {
954  int version; /* the version number of this structure */
955  enum MQTTReasonCodes reasonCode; /* the MQTT 5.0 reason code returned */
956  int reasonCodeCount; /* the number of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
957  enum MQTTReasonCodes* reasonCodes; /* a list of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
958  MQTTProperties* properties; /* optionally, the MQTT 5.0 properties returned */
959 } MQTTResponse;
960 
961 #define MQTTResponse_initializer {1, MQTTREASONCODE_SUCCESS, 0, NULL, NULL}
962 
967 LIBMQTT_API void MQTTResponse_free(MQTTResponse response);
968 
982  MQTTProperties* connectProperties, MQTTProperties* willProperties);
983 
1002 LIBMQTT_API int MQTTClient_disconnect(MQTTClient handle, int timeout);
1003 
1004 LIBMQTT_API int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties* props);
1005 
1013 LIBMQTT_API int MQTTClient_isConnected(MQTTClient handle);
1014 
1015 
1016 /* Subscribe is synchronous. QoS list parameter is changed on return to granted QoSs.
1017  Returns return code, MQTTCLIENT_SUCCESS == success, non-zero some sort of error (TBD) */
1018 
1032 LIBMQTT_API int MQTTClient_subscribe(MQTTClient handle, const char* topic, int qos);
1033 
1047 LIBMQTT_API MQTTResponse MQTTClient_subscribe5(MQTTClient handle, const char* topic, int qos,
1048  MQTTSubscribe_options* opts, MQTTProperties* props);
1049 
1066 LIBMQTT_API int MQTTClient_subscribeMany(MQTTClient handle, int count, char* const* topic, int* qos);
1067 
1084 LIBMQTT_API MQTTResponse MQTTClient_subscribeMany5(MQTTClient handle, int count, char* const* topic,
1085  int* qos, MQTTSubscribe_options* opts, MQTTProperties* props);
1086 
1098 LIBMQTT_API int MQTTClient_unsubscribe(MQTTClient handle, const char* topic);
1099 
1110 LIBMQTT_API MQTTResponse MQTTClient_unsubscribe5(MQTTClient handle, const char* topic, MQTTProperties* props);
1111 
1123 LIBMQTT_API int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char* const* topic);
1124 
1136 LIBMQTT_API MQTTResponse MQTTClient_unsubscribeMany5(MQTTClient handle, int count, char* const* topic, MQTTProperties* props);
1137 
1159 LIBMQTT_API int MQTTClient_publish(MQTTClient handle, const char* topicName, int payloadlen, const void* payload, int qos, int retained,
1161 
1183 LIBMQTT_API MQTTResponse MQTTClient_publish5(MQTTClient handle, const char* topicName, int payloadlen, const void* payload,
1184  int qos, int retained, MQTTProperties* properties, MQTTClient_deliveryToken* dt);
1204 LIBMQTT_API int MQTTClient_publishMessage(MQTTClient handle, const char* topicName, MQTTClient_message* msg, MQTTClient_deliveryToken* dt);
1205 
1206 
1226 LIBMQTT_API MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char* topicName, MQTTClient_message* msg,
1228 
1244 LIBMQTT_API int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout);
1245 
1246 
1266 
1273 LIBMQTT_API void MQTTClient_yield(void);
1274 
1306 LIBMQTT_API int MQTTClient_receive(MQTTClient handle, char** topicName, int* topicLen, MQTTClient_message** message,
1307  unsigned long timeout);
1308 
1319 LIBMQTT_API void MQTTClient_freeMessage(MQTTClient_message** msg);
1320 
1329 LIBMQTT_API void MQTTClient_free(void* ptr);
1330 
1338 LIBMQTT_API void MQTTClient_destroy(MQTTClient* handle);
1339 
1340 
1342 {
1350 };
1351 
1352 
1358 LIBMQTT_API void MQTTClient_setTraceLevel(enum MQTTCLIENT_TRACE_LEVELS level);
1359 
1360 
1369 typedef void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char* message);
1370 
1377 LIBMQTT_API void MQTTClient_setTraceCallback(MQTTClient_traceCallback* callback);
1378 
1384 LIBMQTT_API const char* MQTTClient_strerror(int code);
1385 
1386 #ifdef __cplusplus
1387  }
1388 #endif
1389 
1390 #endif
1391 
int MQTTVersion
Definition: MQTTClient.h:543
Definition: MQTTClient.h:1345
void MQTTClient_free(void *ptr)
int MQTTVersion
Definition: MQTTClient.h:893
int MQTTClient_getPendingDeliveryTokens(MQTTClient handle, MQTTClient_deliveryToken **tokens)
void * MQTTClient
Definition: MQTTClient.h:246
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:740
int struct_version
Definition: MQTTClient.h:537
const char * MQTTClient_strerror(int code)
void MQTTClient_yield(void)
const char * message
Definition: MQTTClient.h:618
int struct_version
Definition: MQTTClient.h:793
const char * username
Definition: MQTTClient.h:847
void MQTTClient_connectionLost(void *context, char *cause)
Definition: MQTTClient.h:398
int dup
Definition: MQTTClient.h:316
int MQTTClient_unsubscribe(MQTTClient handle, const char *topic)
const char * enabledCipherSuites
Definition: MQTTClient.h:685
int MQTTClient_subscribeMany(MQTTClient handle, int count, char *const *topic, int *qos)
int struct_version
Definition: MQTTClient.h:272
int qos
Definition: MQTTClient.h:290
const char * password
Definition: MQTTClient.h:853
const char * serverURI
Definition: MQTTClient.h:899
Definition: MQTTClient.h:1347
int msgid
Definition: MQTTClient.h:320
MQTTProperties * properties
Definition: MQTTClient.h:958
int retained
Definition: MQTTClient.h:622
const void * data
Definition: MQTTClient.h:632
int retryInterval
Definition: MQTTClient.h:865
int maxInflightMessages
Definition: MQTTClient.h:918
int reliable
Definition: MQTTClient.h:835
Definition: MQTTClient.h:266
int MQTTClient_receive(MQTTClient handle, char **topicName, int *topicLen, MQTTClient_message **message, unsigned long timeout)
MQTTProperties properties
Definition: MQTTClient.h:324
int cleanstart
Definition: MQTTClient.h:922
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:803
int payloadlen
Definition: MQTTClient.h:274
int verify
Definition: MQTTClient.h:701
void * ssl_psk_context
Definition: MQTTClient.h:733
const char * topicName
Definition: MQTTClient.h:616
int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions *options)
int connectTimeout
Definition: MQTTClient.h:857
Definition: MQTTSubscribeOpts.h:21
Definition: MQTTClient.h:224
int struct_version
Definition: MQTTClient.h:660
int MQTTClient_disconnect(MQTTClient handle, int timeout)
void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char *message)
Definition: MQTTClient.h:1369
int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties *props)
Definition: MQTTClient.h:1344
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:909
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:655
enum MQTTReasonCodes * reasonCodes
Definition: MQTTClient.h:957
Definition: MQTTClient.h:952
int struct_version
Definition: MQTTClient.h:229
int qos
Definition: MQTTClient.h:627
Definition: MQTTClient.h:1349
int sslVersion
Definition: MQTTClient.h:694
int len
Definition: MQTTClient.h:908
Definition: MQTTClient.h:607
void * ssl_error_context
Definition: MQTTClient.h:720
int version
Definition: MQTTClient.h:954
const MQTTClient_nameValue * httpHeaders
Definition: MQTTClient.h:914
int reasonCodeCount
Definition: MQTTClient.h:956
const char * trustStore
Definition: MQTTClient.h:663
Definition: MQTTClient.h:1346
int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char *const *topic)
int sessionPresent
Definition: MQTTClient.h:901
enum MQTTReasonCodes reasonCode
Definition: MQTTClient.h:955
int MQTTClient_setCallbacks(MQTTClient handle, void *context, MQTTClient_connectionLost *cl, MQTTClient_messageArrived *ma, MQTTClient_deliveryComplete *dc)
Definition: MQTTClient.h:780
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:755
MQTTClient_willOptions * will
Definition: MQTTClient.h:841
void MQTTClient_deliveryComplete(void *context, MQTTClient_deliveryToken dt)
Definition: MQTTClient.h:381
const char * privateKeyPassword
Definition: MQTTClient.h:675
int MQTTClient_deliveryToken
Definition: MQTTClient.h:257
char *const * serverURIs
Definition: MQTTClient.h:885
int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout)
const char * privateKey
Definition: MQTTClient.h:673
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:870
Definition: MQTTProperties.h:112
Definition: MQTTClient.h:1343
MQTTReasonCodes
Definition: MQTTReasonCodes.h:23
int MQTTClient_isConnected(MQTTClient handle)
int MQTTClient_token
Definition: MQTTClient.h:258
int MQTTClient_setDisconnected(MQTTClient handle, void *context, MQTTClient_disconnected *co)
int serverURIcount
Definition: MQTTClient.h:874
Definition: MQTTClient.h:1348
int MQTTClient_create(MQTTClient *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context)
const char * keyStore
Definition: MQTTClient.h:668
void MQTTResponse_free(MQTTResponse response)
MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
int retained
Definition: MQTTClient.h:309
int enableServerCertAuth
Definition: MQTTClient.h:688
int len
Definition: MQTTClient.h:631
void MQTTClient_disconnected(void *context, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
Definition: MQTTClient.h:440
struct MQTTResponse MQTTResponse
MQTTClient_nameValue * MQTTClient_getVersionInfo(void)
const char * value
Definition: MQTTClient.h:756
void MQTTClient_published(void *context, int dt, int packet_type, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
Definition: MQTTClient.h:481
int cleansession
Definition: MQTTClient.h:825
int do_openssl_init
Definition: MQTTClient.h:231
This structure represents a persistent data store, used to store outbound and inbound messages...
Definition: MQTTClient.h:532
int struct_version
Definition: MQTTClient.h:614
void * payload
Definition: MQTTClient.h:276
int MQTTClient_messageArrived(void *context, char *topicName, int topicLen, MQTTClient_message *message)
Definition: MQTTClient.h:359
void MQTTClient_freeMessage(MQTTClient_message **msg)
Definition: MQTTClient.h:753
const char * CApath
Definition: MQTTClient.h:708
MQTTCLIENT_TRACE_LEVELS
Definition: MQTTClient.h:1341