Paho MQTT C Client Library
MQTTClient.h
Go to the documentation of this file.
1 /*******************************************************************************
2  * Copyright (c) 2009, 2018 IBM Corp.
3  *
4  * All rights reserved. This program and the accompanying materials
5  * are made available under the terms of the Eclipse Public License v1.0
6  * and Eclipse Distribution License v1.0 which accompany this distribution.
7  *
8  * The Eclipse Public License is available at
9  * http://www.eclipse.org/legal/epl-v10.html
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 #if defined(WIN32) || defined(WIN64)
114  #define DLLImport __declspec(dllimport)
115  #define DLLExport __declspec(dllexport)
116 #else
117  #define DLLImport extern
118  #define DLLExport __attribute__ ((visibility ("default")))
119 #endif
120 
121 #include <stdio.h>
122 /*
124 */
125 
126 #include "MQTTProperties.h"
127 #include "MQTTReasonCodes.h"
128 #include "MQTTSubscribeOpts.h"
129 #if !defined(NO_PERSISTENCE)
130 #include "MQTTClientPersistence.h"
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 
191 #define MQTTCLIENT_BAD_PROTOCOL -14
192 
195  #define MQTTCLIENT_BAD_MQTT_OPTION -15
196 
199  #define MQTTCLIENT_WRONG_MQTT_VERSION -16
200 
201 
205 #define MQTTVERSION_DEFAULT 0
206 
209 #define MQTTVERSION_3_1 3
210 
213 #define MQTTVERSION_3_1_1 4
214 
217  #define MQTTVERSION_5 5
218 
221 #define MQTT_BAD_SUBSCRIBE 0x80
222 
226 typedef struct
227 {
229  char struct_id[4];
235 
236 #define MQTTClient_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
237 
243 
248 typedef void* MQTTClient;
260 typedef int MQTTClient_token;
261 
268 typedef struct
269 {
271  char struct_id[4];
278  void* payload;
292  int qos;
311  int retained;
318  int dup;
322  int msgid;
328 
329 #define MQTTClient_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }
330 
357 typedef int MQTTClient_messageArrived(void* context, char* topicName, int topicLen, MQTTClient_message* message);
358 
380 
396 typedef void MQTTClient_connectionLost(void* context, char* cause);
397 
427 
428 
438 typedef void MQTTClient_disconnected(void* context, MQTTProperties* properties,
439  enum MQTTReasonCodes reasonCode);
440 
455 
479 typedef void MQTTClient_published(void* context, int dt, int packet_type, MQTTProperties* properties,
480  enum MQTTReasonCodes reasonCode);
481 
482 DLLExport int MQTTClient_setPublished(MQTTClient handle, void* context, MQTTClient_published* co);
483 
526 DLLExport int MQTTClient_create(MQTTClient* handle, const char* serverURI, const char* clientId,
527  int persistence_type, void* persistence_context);
528 
529 typedef struct
530 {
532  char struct_id[4];
542 
543 #define MQTTClient_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 0, MQTTVERSION_DEFAULT }
544 
589 DLLExport int MQTTClient_createWithOptions(MQTTClient* handle, const char* serverURI, const char* clientId,
590  int persistence_type, void* persistence_context, MQTTClient_createOptions* options);
591 
604 typedef struct
605 {
607  char struct_id[4];
613  const char* topicName;
615  const char* message;
619  int retained;
624  int qos;
626  struct
627  {
628  int len;
629  const void* data;
630  } payload;
632 
633 #define MQTTClient_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, {0, NULL} }
634 
635 #define MQTT_SSL_VERSION_DEFAULT 0
636 #define MQTT_SSL_VERSION_TLS_1_0 1
637 #define MQTT_SSL_VERSION_TLS_1_1 2
638 #define MQTT_SSL_VERSION_TLS_1_2 3
639 
652 typedef struct
653 {
655  char struct_id[4];
658 
660  const char* trustStore;
661 
665  const char* keyStore;
666 
670  const char* privateKey;
672  const char* privateKeyPassword;
673 
682  const char* enabledCipherSuites;
683 
686 
692 
698  int verify;
699 
705  const char* CApath;
706 
711  int (*ssl_error_cb) (const char *str, size_t len, void *u);
712 
718 
724  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);
725 
731 
738 
740 
741 #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 }
742 
757 typedef struct
758 {
760  char struct_id[4];
811  int reliable;
823  const char* username;
829  const char* password;
861  char* const* serverURIs;
873  struct
874  {
875  const char* serverURI;
876  int MQTTVersion;
878  } returned;
882  struct
883  {
884  int len;
885  const void* data;
886  } binarypwd;
891  /*
892  * MQTT V5 clean start flag. Only clears state at the beginning of the session.
893  */
896 
897 #define MQTTClient_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 6, 60, 1, 1, NULL, NULL, NULL, 30, 0, NULL, 0, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0}
898 
899 #define MQTTClient_connectOptions_initializer5 { {'M', 'Q', 'T', 'C'}, 6, 60, 0, 1, NULL, NULL, NULL, 30, 0, NULL, 0, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1}
900 
908 typedef struct
909 {
910  const char* name;
911  const char* value;
913 
920 
942 
943 
944 typedef struct MQTTResponse
945 {
946  int version;
948  int reasonCodeCount; /* used for subscribeMany5 and unsubscribeMany5 */
949  enum MQTTReasonCodes* reasonCodes; /* used for subscribeMany5 and unsubscribeMany5 */
950  MQTTProperties* properties; /* optional */
951 } MQTTResponse;
952 
953 #define MQTTResponse_initializer {1, MQTTREASONCODE_SUCCESS, 0, NULL, NULL}
954 
956 
958  MQTTProperties* connectProperties, MQTTProperties* willProperties);
959 
978 DLLExport int MQTTClient_disconnect(MQTTClient handle, int timeout);
979 
980 DLLExport int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties* props);
981 
990 
991 
992 /* Subscribe is synchronous. QoS list parameter is changed on return to granted QoSs.
993  Returns return code, MQTTCLIENT_SUCCESS == success, non-zero some sort of error (TBD) */
994 
1008 DLLExport int MQTTClient_subscribe(MQTTClient handle, const char* topic, int qos);
1009 
1010 
1011 DLLExport MQTTResponse MQTTClient_subscribe5(MQTTClient handle, const char* topic, int qos,
1012  MQTTSubscribe_options* opts, MQTTProperties* props);
1013 
1030 DLLExport int MQTTClient_subscribeMany(MQTTClient handle, int count, char* const* topic, int* qos);
1031 
1032 DLLExport MQTTResponse MQTTClient_subscribeMany5(MQTTClient handle, int count, char* const* topic,
1033  int* qos, MQTTSubscribe_options* opts, MQTTProperties* props);
1034 
1046 DLLExport int MQTTClient_unsubscribe(MQTTClient handle, const char* topic);
1047 
1048 DLLExport MQTTResponse MQTTClient_unsubscribe5(MQTTClient handle, const char* topic, MQTTProperties* props);
1049 
1061 DLLExport int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char* const* topic);
1062 
1063 DLLExport MQTTResponse MQTTClient_unsubscribeMany5(MQTTClient handle, int count, char* const* topic, MQTTProperties* props);
1064 
1086 DLLExport int MQTTClient_publish(MQTTClient handle, const char* topicName, int payloadlen, const void* payload, int qos, int retained,
1088 
1089 DLLExport MQTTResponse MQTTClient_publish5(MQTTClient handle, const char* topicName, int payloadlen, const void* payload,
1090  int qos, int retained, MQTTProperties* properties, MQTTClient_deliveryToken* dt);
1110 DLLExport int MQTTClient_publishMessage(MQTTClient handle, const char* topicName, MQTTClient_message* msg, MQTTClient_deliveryToken* dt);
1111 
1112 
1115 
1131 DLLExport int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout);
1132 
1133 
1153 
1160 DLLExport void MQTTClient_yield(void);
1161 
1193 DLLExport int MQTTClient_receive(MQTTClient handle, char** topicName, int* topicLen, MQTTClient_message** message,
1194  unsigned long timeout);
1195 
1207 
1216 DLLExport void MQTTClient_free(void* ptr);
1217 
1226 
1227 
1229 {
1237 };
1238 
1239 
1246 
1247 
1256 typedef void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char* message);
1257 
1265 
1271 DLLExport const char* MQTTClient_strerror(int code);
1272 
1273 #ifdef __cplusplus
1274  }
1275 #endif
1276 
1277 #endif
1278 
int MQTTVersion
Definition: MQTTClient.h:540
Definition: MQTTClient.h:1232
void MQTTClient_free(void *ptr)
int MQTTVersion
Definition: MQTTClient.h:869
int MQTTClient_getPendingDeliveryTokens(MQTTClient handle, MQTTClient_deliveryToken **tokens)
void * MQTTClient
Definition: MQTTClient.h:248
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:737
int struct_version
Definition: MQTTClient.h:534
const char * MQTTClient_strerror(int code)
void MQTTClient_yield(void)
const char * message
Definition: MQTTClient.h:615
int struct_version
Definition: MQTTClient.h:769
const char * username
Definition: MQTTClient.h:823
void MQTTClient_connectionLost(void *context, char *cause)
Definition: MQTTClient.h:396
int dup
Definition: MQTTClient.h:318
int MQTTClient_unsubscribe(MQTTClient handle, const char *topic)
const char * enabledCipherSuites
Definition: MQTTClient.h:682
int MQTTClient_subscribeMany(MQTTClient handle, int count, char *const *topic, int *qos)
int struct_version
Definition: MQTTClient.h:274
int qos
Definition: MQTTClient.h:292
const char * password
Definition: MQTTClient.h:829
const char * serverURI
Definition: MQTTClient.h:875
Definition: MQTTClient.h:1234
int msgid
Definition: MQTTClient.h:322
MQTTProperties * properties
Definition: MQTTClient.h:950
int retained
Definition: MQTTClient.h:619
const void * data
Definition: MQTTClient.h:629
int retryInterval
Definition: MQTTClient.h:841
int maxInflightMessages
Definition: MQTTClient.h:890
int reliable
Definition: MQTTClient.h:811
Definition: MQTTClient.h:268
int MQTTClient_receive(MQTTClient handle, char **topicName, int *topicLen, MQTTClient_message **message, unsigned long timeout)
MQTTProperties properties
Definition: MQTTClient.h:326
int cleanstart
Definition: MQTTClient.h:894
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:779
int payloadlen
Definition: MQTTClient.h:276
int verify
Definition: MQTTClient.h:698
void * ssl_psk_context
Definition: MQTTClient.h:730
const char * topicName
Definition: MQTTClient.h:613
int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions *options)
int connectTimeout
Definition: MQTTClient.h:833
Definition: MQTTSubscribeOpts.h:21
Definition: MQTTClient.h:226
int struct_version
Definition: MQTTClient.h:657
int MQTTClient_disconnect(MQTTClient handle, int timeout)
void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char *message)
Definition: MQTTClient.h:1256
int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties *props)
Definition: MQTTClient.h:1231
void MQTTClient_setTraceCallback(MQTTClient_traceCallback *callback)
int MQTTClient_publishMessage(MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
#define DLLExport
Definition: MQTTProperties.h:58
MQTTResponse MQTTClient_subscribe5(MQTTClient handle, const char *topic, int qos, MQTTSubscribe_options *opts, MQTTProperties *props)
const void * data
Definition: MQTTClient.h:885
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:652
enum MQTTReasonCodes * reasonCodes
Definition: MQTTClient.h:949
Definition: MQTTClient.h:944
int struct_version
Definition: MQTTClient.h:231
int qos
Definition: MQTTClient.h:624
Definition: MQTTClient.h:1236
int sslVersion
Definition: MQTTClient.h:691
int len
Definition: MQTTClient.h:884
Definition: MQTTClient.h:604
void * ssl_error_context
Definition: MQTTClient.h:717
int version
Definition: MQTTClient.h:946
int reasonCodeCount
Definition: MQTTClient.h:948
const char * trustStore
Definition: MQTTClient.h:660
Definition: MQTTClient.h:1233
int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char *const *topic)
int sessionPresent
Definition: MQTTClient.h:877
enum MQTTReasonCodes reasonCode
Definition: MQTTClient.h:947
int MQTTClient_setCallbacks(MQTTClient handle, void *context, MQTTClient_connectionLost *cl, MQTTClient_messageArrived *ma, MQTTClient_deliveryComplete *dc)
Definition: MQTTClient.h:757
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:910
MQTTClient_willOptions * will
Definition: MQTTClient.h:817
void MQTTClient_deliveryComplete(void *context, MQTTClient_deliveryToken dt)
Definition: MQTTClient.h:379
const char * privateKeyPassword
Definition: MQTTClient.h:672
int MQTTClient_deliveryToken
Definition: MQTTClient.h:259
char *const * serverURIs
Definition: MQTTClient.h:861
int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout)
const char * privateKey
Definition: MQTTClient.h:670
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:846
Definition: MQTTProperties.h:118
Definition: MQTTClient.h:1230
MQTTReasonCodes
Definition: MQTTReasonCodes.h:21
int MQTTClient_isConnected(MQTTClient handle)
int MQTTClient_token
Definition: MQTTClient.h:260
int MQTTClient_setDisconnected(MQTTClient handle, void *context, MQTTClient_disconnected *co)
int serverURIcount
Definition: MQTTClient.h:850
Definition: MQTTClient.h:1235
int MQTTClient_create(MQTTClient *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context)
const char * keyStore
Definition: MQTTClient.h:665
void MQTTResponse_free(MQTTResponse response)
MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
int retained
Definition: MQTTClient.h:311
int enableServerCertAuth
Definition: MQTTClient.h:685
int len
Definition: MQTTClient.h:628
void MQTTClient_disconnected(void *context, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
Definition: MQTTClient.h:438
struct MQTTResponse MQTTResponse
MQTTClient_nameValue * MQTTClient_getVersionInfo(void)
const char * value
Definition: MQTTClient.h:911
void MQTTClient_published(void *context, int dt, int packet_type, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
Definition: MQTTClient.h:479
int cleansession
Definition: MQTTClient.h:801
int do_openssl_init
Definition: MQTTClient.h:233
This structure represents a persistent data store, used to store outbound and inbound messages...
Definition: MQTTClient.h:529
int struct_version
Definition: MQTTClient.h:611
void * payload
Definition: MQTTClient.h:278
int MQTTClient_messageArrived(void *context, char *topicName, int topicLen, MQTTClient_message *message)
Definition: MQTTClient.h:357
void MQTTClient_freeMessage(MQTTClient_message **msg)
Definition: MQTTClient.h:908
const char * CApath
Definition: MQTTClient.h:705
MQTTCLIENT_TRACE_LEVELS
Definition: MQTTClient.h:1228