Paho Asynchronous MQTT C Client Library
MQTTAsync.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
15  * Ian Craggs, Allan Stockdill-Mander - SSL connections
16  * Ian Craggs - multiple server connection support
17  * Ian Craggs - MQTT 3.1.1 support
18  * Ian Craggs - fix for bug 444103 - success/failure callbacks not invoked
19  * Ian Craggs - automatic reconnect and offline buffering (send while disconnected)
20  * Ian Craggs - binary will message
21  * Ian Craggs - binary password
22  * Ian Craggs - remove const on eyecatchers #168
23  *******************************************************************************/
24 
25 /********************************************************************/
26 
85 /*
87 */
88 #if defined(__cplusplus)
89  extern "C" {
90 #endif
91 
92 #if !defined(MQTTASYNC_H)
93 #define MQTTASYNC_H
94 
95 #if defined(WIN32) || defined(WIN64)
96  #define DLLImport __declspec(dllimport)
97  #define DLLExport __declspec(dllexport)
98 #else
99  #define DLLImport extern
100  #define DLLExport __attribute__ ((visibility ("default")))
101 #endif
102 
103 #include <stdio.h>
104 /*
106 */
107 
108 #if !defined(NO_PERSISTENCE)
109 #include "MQTTClientPersistence.h"
110 #endif
111 
116 #define MQTTASYNC_SUCCESS 0
117 
121 #define MQTTASYNC_FAILURE -1
122 
123 /* error code -2 is MQTTAsync_PERSISTENCE_ERROR */
124 
125 #define MQTTASYNC_PERSISTENCE_ERROR -2
126 
130 #define MQTTASYNC_DISCONNECTED -3
131 
135 #define MQTTASYNC_MAX_MESSAGES_INFLIGHT -4
136 
139 #define MQTTASYNC_BAD_UTF8_STRING -5
140 
143 #define MQTTASYNC_NULL_PARAMETER -6
144 
149 #define MQTTASYNC_TOPICNAME_TRUNCATED -7
150 
154 #define MQTTASYNC_BAD_STRUCTURE -8
155 
158 #define MQTTASYNC_BAD_QOS -9
159 
162 #define MQTTASYNC_NO_MORE_MSGIDS -10
163 
166 #define MQTTASYNC_OPERATION_INCOMPLETE -11
167 
170 #define MQTTASYNC_MAX_BUFFERED_MESSAGES -12
171 
174 #define MQTTASYNC_SSL_NOT_SUPPORTED -13
175 
178 #define MQTTASYNC_BAD_PROTOCOL -14
179 
180 
184 #define MQTTVERSION_DEFAULT 0
185 
188 #define MQTTVERSION_3_1 3
189 
192 #define MQTTVERSION_3_1_1 4
193 
196 #define MQTT_BAD_SUBSCRIBE 0x80
197 
198 
202 typedef struct
203 {
205  char struct_id[4];
211 
212 #define MQTTAsync_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
213 
218 DLLExport void MQTTAsync_global_init(MQTTAsync_init_options* inits);
219 
224 typedef void* MQTTAsync;
234 typedef int MQTTAsync_token;
235 
242 typedef struct
243 {
245  char struct_id[4];
251  void* payload;
265  int qos;
284  int retained;
291  int dup;
295  int msgid;
297 
298 #define MQTTAsync_message_initializer { {'M', 'Q', 'T', 'M'}, 0, 0, NULL, 0, 0, 0, 0 }
299 
326 typedef int MQTTAsync_messageArrived(void* context, char* topicName, int topicLen, MQTTAsync_message* message);
327 
346 typedef void MQTTAsync_deliveryComplete(void* context, MQTTAsync_token token);
347 
363 typedef void MQTTAsync_connectionLost(void* context, char* cause);
364 
365 
378 typedef void MQTTAsync_connected(void* context, char* cause);
379 
380 
381 
383 typedef struct
384 {
386  MQTTAsync_token token;
388  int code;
390  const char *message;
392 
394 typedef struct
395 {
397  MQTTAsync_token token;
399  union
400  {
402  int qos;
404  int* qosList;
406  struct
407  {
410  } pub;
411  /* For connect, the server connected to, MQTT version used, and sessionPresent flag */
412  struct
413  {
414  char* serverURI;
417  } connect;
418  } alt;
420 
431 typedef void MQTTAsync_onSuccess(void* context, MQTTAsync_successData* response);
432 
443 typedef void MQTTAsync_onFailure(void* context, MQTTAsync_failureData* response);
444 
445 typedef struct
446 {
448  char struct_id[4];
468  void* context;
474  MQTTAsync_token token;
476 
477 #define MQTTAsync_responseOptions_initializer { {'M', 'Q', 'T', 'R'}, 0, NULL, NULL, 0, 0 }
478 
479 
508 DLLExport int MQTTAsync_setCallbacks(MQTTAsync handle, void* context, MQTTAsync_connectionLost* cl,
510 
511 
524 DLLExport int MQTTAsync_setConnected(MQTTAsync handle, void* context, MQTTAsync_connected* co);
525 
526 
535 DLLExport int MQTTAsync_reconnect(MQTTAsync handle);
536 
537 
579 DLLExport int MQTTAsync_create(MQTTAsync* handle, const char* serverURI, const char* clientId,
580  int persistence_type, void* persistence_context);
581 
582 typedef struct
583 {
585  char struct_id[4];
593 
594 #define MQTTAsync_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 0, 0, 100 }
595 
596 
597 DLLExport int MQTTAsync_createWithOptions(MQTTAsync* handle, const char* serverURI, const char* clientId,
598  int persistence_type, void* persistence_context, MQTTAsync_createOptions* options);
599 
612 typedef struct
613 {
615  char struct_id[4];
621  const char* topicName;
623  const char* message;
627  int retained;
632  int qos;
634  struct
635  {
636  int len;
637  const void* data;
638  } payload;
640 
641 #define MQTTAsync_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, { 0, NULL } }
642 
643 #define MQTT_SSL_VERSION_DEFAULT 0
644 #define MQTT_SSL_VERSION_TLS_1_0 1
645 #define MQTT_SSL_VERSION_TLS_1_1 2
646 #define MQTT_SSL_VERSION_TLS_1_2 3
647 
660 typedef struct
661 {
663  char struct_id[4];
666 
668  const char* trustStore;
669 
673  const char* keyStore;
674 
678  const char* privateKey;
680  const char* privateKeyPassword;
681 
690  const char* enabledCipherSuites;
691 
694 
700 
706  int verify;
707 
713  const char* CApath;
715 
716 #define MQTTAsync_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 2, NULL, NULL, NULL, NULL, NULL, 1, MQTT_SSL_VERSION_DEFAULT, 0, NULL }
717 
723 typedef struct
724 {
726  char struct_id[4];
783  const char* username;
789  const char* password;
820  void* context;
833  char* const* serverURIs;
856  struct {
857  int len;
858  const void* data;
859  } binarypwd;
861 
862 
863 #define MQTTAsync_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 5, 60, 1, 10, NULL, NULL, NULL, 30, 0,\
864 NULL, NULL, NULL, NULL, 0, NULL, 0, 0, 1, 60, {0, NULL}}
865 
886 DLLExport int MQTTAsync_connect(MQTTAsync handle, const MQTTAsync_connectOptions* options);
887 
888 
889 typedef struct
890 {
892  char struct_id[4];
899  int timeout;
917  void* context;
919 
920 #define MQTTAsync_disconnectOptions_initializer { {'M', 'Q', 'T', 'D'}, 0, 0, NULL, NULL, NULL }
921 
922 
941 DLLExport int MQTTAsync_disconnect(MQTTAsync handle, const MQTTAsync_disconnectOptions* options);
942 
943 
951 DLLExport int MQTTAsync_isConnected(MQTTAsync handle);
952 
953 
968 DLLExport int MQTTAsync_subscribe(MQTTAsync handle, const char* topic, int qos, MQTTAsync_responseOptions* response);
969 
970 
988 DLLExport int MQTTAsync_subscribeMany(MQTTAsync handle, int count, char* const* topic, int* qos, MQTTAsync_responseOptions* response);
989 
1002 DLLExport int MQTTAsync_unsubscribe(MQTTAsync handle, const char* topic, MQTTAsync_responseOptions* response);
1003 
1016 DLLExport int MQTTAsync_unsubscribeMany(MQTTAsync handle, int count, char* const* topic, MQTTAsync_responseOptions* response);
1017 
1018 
1037 DLLExport int MQTTAsync_send(MQTTAsync handle, const char* destinationName, int payloadlen, void* payload, int qos, int retained,
1038  MQTTAsync_responseOptions* response);
1039 
1040 
1056 DLLExport int MQTTAsync_sendMessage(MQTTAsync handle, const char* destinationName, const MQTTAsync_message* msg, MQTTAsync_responseOptions* response);
1057 
1058 
1077 DLLExport int MQTTAsync_getPendingTokens(MQTTAsync handle, MQTTAsync_token **tokens);
1078 
1087 #define MQTTASYNC_TRUE 1
1088 DLLExport int MQTTAsync_isComplete(MQTTAsync handle, MQTTAsync_token token);
1089 
1090 
1101 DLLExport int MQTTAsync_waitForCompletion(MQTTAsync handle, MQTTAsync_token token, unsigned long timeout);
1102 
1103 
1114 DLLExport void MQTTAsync_freeMessage(MQTTAsync_message** msg);
1115 
1124 DLLExport void MQTTAsync_free(void* ptr);
1125 
1133 DLLExport void MQTTAsync_destroy(MQTTAsync* handle);
1134 
1135 
1136 
1138 {
1146 };
1147 
1148 
1154 DLLExport void MQTTAsync_setTraceLevel(enum MQTTASYNC_TRACE_LEVELS level);
1155 
1156 
1165 typedef void MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char* message);
1166 
1173 DLLExport void MQTTAsync_setTraceCallback(MQTTAsync_traceCallback* callback);
1174 
1175 
1176 typedef struct
1177 {
1178  const char* name;
1179  const char* value;
1181 
1189 
1190 
1747 #endif
1748 
1749 #ifdef __cplusplus
1750  }
1751 #endif
int sendWhileDisconnected
Definition: MQTTAsync.h:589
MQTTAsync_token token
Definition: MQTTAsync.h:397
Definition: MQTTAsync.h:1143
int len
Definition: MQTTAsync.h:636
DLLExport int MQTTAsync_setCallbacks(MQTTAsync handle, void *context, MQTTAsync_connectionLost *cl, MQTTAsync_messageArrived *ma, MQTTAsync_deliveryComplete *dc)
DLLExport void MQTTAsync_freeMessage(MQTTAsync_message **msg)
DLLExport int MQTTAsync_send(MQTTAsync handle, const char *destinationName, int payloadlen, void *payload, int qos, int retained, MQTTAsync_responseOptions *response)
DLLExport void MQTTAsync_free(void *ptr)
const char * message
Definition: MQTTAsync.h:390
int MQTTAsync_token
Definition: MQTTAsync.h:234
int * qosList
Definition: MQTTAsync.h:404
DLLExport int MQTTAsync_waitForCompletion(MQTTAsync handle, MQTTAsync_token token, unsigned long timeout)
char *const * serverURIs
Definition: MQTTAsync.h:833
int struct_version
Definition: MQTTAsync.h:734
MQTTAsync_token token
Definition: MQTTAsync.h:386
Definition: MQTTAsync.h:612
void MQTTAsync_connectionLost(void *context, char *cause)
Definition: MQTTAsync.h:363
int MQTTVersion
Definition: MQTTAsync.h:415
MQTTAsync_willOptions * will
Definition: MQTTAsync.h:777
MQTTAsync_token token
Definition: MQTTAsync.h:474
void MQTTAsync_connected(void *context, char *cause)
Definition: MQTTAsync.h:378
int struct_version
Definition: MQTTAsync.h:207
const char * keyStore
Definition: MQTTAsync.h:673
const void * data
Definition: MQTTAsync.h:858
int sessionPresent
Definition: MQTTAsync.h:416
Definition: MQTTAsync.h:242
int MQTTVersion
Definition: MQTTAsync.h:840
int struct_version
Definition: MQTTAsync.h:450
const char * password
Definition: MQTTAsync.h:789
DLLExport int MQTTAsync_getPendingTokens(MQTTAsync handle, MQTTAsync_token **tokens)
MQTTAsync_onFailure * onFailure
Definition: MQTTAsync.h:462
int keepAliveInterval
Definition: MQTTAsync.h:745
void MQTTAsync_deliveryComplete(void *context, MQTTAsync_token token)
Definition: MQTTAsync.h:346
int qos
Definition: MQTTAsync.h:265
DLLExport int MQTTAsync_subscribe(MQTTAsync handle, const char *topic, int qos, MQTTAsync_responseOptions *response)
MQTTASYNC_TRACE_LEVELS
Definition: MQTTAsync.h:1137
int automaticReconnect
Definition: MQTTAsync.h:844
void * payload
Definition: MQTTAsync.h:251
const char * trustStore
Definition: MQTTAsync.h:668
void * context
Definition: MQTTAsync.h:468
const char * CApath
Definition: MQTTAsync.h:713
DLLExport int MQTTAsync_subscribeMany(MQTTAsync handle, int count, char *const *topic, int *qos, MQTTAsync_responseOptions *response)
int payloadlen
Definition: MQTTAsync.h:249
MQTTAsync_message message
Definition: MQTTAsync.h:408
DLLExport int MQTTAsync_unsubscribeMany(MQTTAsync handle, int count, char *const *topic, MQTTAsync_responseOptions *response)
Definition: MQTTAsync.h:445
int msgid
Definition: MQTTAsync.h:295
int struct_version
Definition: MQTTAsync.h:665
DLLExport int MQTTAsync_disconnect(MQTTAsync handle, const MQTTAsync_disconnectOptions *options)
int struct_version
Definition: MQTTAsync.h:587
MQTTAsync_onFailure * onFailure
Definition: MQTTAsync.h:814
int struct_version
Definition: MQTTAsync.h:894
DLLExport void MQTTAsync_destroy(MQTTAsync *handle)
MQTTAsync_SSLOptions * ssl
Definition: MQTTAsync.h:802
const char * privateKeyPassword
Definition: MQTTAsync.h:680
int sslVersion
Definition: MQTTAsync.h:699
const char * topicName
Definition: MQTTAsync.h:621
Definition: MQTTAsync.h:1142
int MQTTAsync_messageArrived(void *context, char *topicName, int topicLen, MQTTAsync_message *message)
Definition: MQTTAsync.h:326
MQTTAsync_onSuccess * onSuccess
Definition: MQTTAsync.h:905
Definition: MQTTAsync.h:723
const char * name
Definition: MQTTAsync.h:1178
Definition: MQTTAsync.h:1144
Definition: MQTTAsync.h:660
void * context
Definition: MQTTAsync.h:917
MQTTAsync_onSuccess * onSuccess
Definition: MQTTAsync.h:456
int struct_version
Definition: MQTTAsync.h:619
char * destinationName
Definition: MQTTAsync.h:409
int retryInterval
Definition: MQTTAsync.h:797
MQTTAsync_onSuccess * onSuccess
Definition: MQTTAsync.h:808
Definition: MQTTAsync.h:582
DLLExport int MQTTAsync_create(MQTTAsync *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context)
DLLExport void MQTTAsync_setTraceCallback(MQTTAsync_traceCallback *callback)
DLLExport int MQTTAsync_isComplete(MQTTAsync handle, MQTTAsync_token token)
Definition: MQTTAsync.h:1145
DLLExport int MQTTAsync_connect(MQTTAsync handle, const MQTTAsync_connectOptions *options)
int verify
Definition: MQTTAsync.h:706
DLLExport MQTTAsync_nameValue * MQTTAsync_getVersionInfo(void)
void MQTTAsync_onSuccess(void *context, MQTTAsync_successData *response)
Definition: MQTTAsync.h:431
DLLExport void MQTTAsync_global_init(MQTTAsync_init_options *inits)
DLLExport int MQTTAsync_setConnected(MQTTAsync handle, void *context, MQTTAsync_connected *co)
int do_openssl_init
Definition: MQTTAsync.h:209
Definition: MQTTAsync.h:383
int connectTimeout
Definition: MQTTAsync.h:793
int maxBufferedMessages
Definition: MQTTAsync.h:591
int maxInflight
Definition: MQTTAsync.h:771
DLLExport void MQTTAsync_setTraceLevel(enum MQTTASYNC_TRACE_LEVELS level)
Definition: MQTTAsync.h:1176
Definition: MQTTAsync.h:1139
DLLExport int MQTTAsync_unsubscribe(MQTTAsync handle, const char *topic, MQTTAsync_responseOptions *response)
int len
Definition: MQTTAsync.h:857
const void * data
Definition: MQTTAsync.h:637
Definition: MQTTAsync.h:1140
int serverURIcount
Definition: MQTTAsync.h:824
const char * value
Definition: MQTTAsync.h:1179
void * MQTTAsync
Definition: MQTTAsync.h:224
int qos
Definition: MQTTAsync.h:402
DLLExport int MQTTAsync_sendMessage(MQTTAsync handle, const char *destinationName, const MQTTAsync_message *msg, MQTTAsync_responseOptions *response)
const char * username
Definition: MQTTAsync.h:783
int enableServerCertAuth
Definition: MQTTAsync.h:693
void MQTTAsync_onFailure(void *context, MQTTAsync_failureData *response)
Definition: MQTTAsync.h:443
Definition: MQTTAsync.h:889
int retained
Definition: MQTTAsync.h:627
int timeout
Definition: MQTTAsync.h:899
void MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char *message)
Definition: MQTTAsync.h:1165
int struct_version
Definition: MQTTAsync.h:247
void * context
Definition: MQTTAsync.h:820
int code
Definition: MQTTAsync.h:388
DLLExport int MQTTAsync_reconnect(MQTTAsync handle)
MQTTAsync_onFailure * onFailure
Definition: MQTTAsync.h:911
Definition: MQTTAsync.h:202
const char * privateKey
Definition: MQTTAsync.h:678
int maxRetryInterval
Definition: MQTTAsync.h:852
const char * enabledCipherSuites
Definition: MQTTAsync.h:690
int qos
Definition: MQTTAsync.h:632
int cleansession
Definition: MQTTAsync.h:767
DLLExport int MQTTAsync_isConnected(MQTTAsync handle)
const char * message
Definition: MQTTAsync.h:623
This structure represents a persistent data store, used to store outbound and inbound messages...
int minRetryInterval
Definition: MQTTAsync.h:848
int retained
Definition: MQTTAsync.h:284
Definition: MQTTAsync.h:1141
DLLExport int MQTTAsync_createWithOptions(MQTTAsync *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context, MQTTAsync_createOptions *options)
int dup
Definition: MQTTAsync.h:291
Definition: MQTTAsync.h:394
char * serverURI
Definition: MQTTAsync.h:414