Paho Asynchronous MQTT C Client Library
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
MQTTAsync.h
Go to the documentation of this file.
1 /*******************************************************************************
2  * Copyright (c) 2009, 2017 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 #if defined(__cplusplus)
87  extern "C" {
88 #endif
89 
90 #if !defined(MQTTASYNC_H)
91 #define MQTTASYNC_H
92 
93 #if defined(WIN32) || defined(WIN64)
94  #define DLLImport __declspec(dllimport)
95  #define DLLExport __declspec(dllexport)
96 #else
97  #define DLLImport extern
98  #define DLLExport __attribute__ ((visibility ("default")))
99 #endif
100 
101 #include <stdio.h>
103 
104 #if !defined(NO_PERSISTENCE)
105 #include "MQTTClientPersistence.h"
106 #endif
107 
112 #define MQTTASYNC_SUCCESS 0
113 
117 #define MQTTASYNC_FAILURE -1
118 
119 /* error code -2 is MQTTAsync_PERSISTENCE_ERROR */
120 
121 #define MQTTASYNC_PERSISTENCE_ERROR -2
122 
126 #define MQTTASYNC_DISCONNECTED -3
127 
131 #define MQTTASYNC_MAX_MESSAGES_INFLIGHT -4
132 
135 #define MQTTASYNC_BAD_UTF8_STRING -5
136 
139 #define MQTTASYNC_NULL_PARAMETER -6
140 
145 #define MQTTASYNC_TOPICNAME_TRUNCATED -7
146 
150 #define MQTTASYNC_BAD_STRUCTURE -8
151 
154 #define MQTTASYNC_BAD_QOS -9
155 
158 #define MQTTASYNC_NO_MORE_MSGIDS -10
159 
162 #define MQTTASYNC_OPERATION_INCOMPLETE -11
163 
166 #define MQTTASYNC_MAX_BUFFERED_MESSAGES -12
167 
170 #define MQTTASYNC_SSL_NOT_SUPPORTED -13
171 
175 #define MQTTVERSION_DEFAULT 0
176 
179 #define MQTTVERSION_3_1 3
180 
183 #define MQTTVERSION_3_1_1 4
184 
187 #define MQTT_BAD_SUBSCRIBE 0x80
188 
189 
193 typedef struct
194 {
196  char struct_id[4];
202 
203 #define MQTTAsync_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
204 
210 
215 typedef void* MQTTAsync;
225 typedef int MQTTAsync_token;
226 
233 typedef struct
234 {
236  char struct_id[4];
242  void* payload;
256  int qos;
275  int retained;
282  int dup;
286  int msgid;
288 
289 #define MQTTAsync_message_initializer { {'M', 'Q', 'T', 'M'}, 0, 0, NULL, 0, 0, 0, 0 }
290 
317 typedef int MQTTAsync_messageArrived(void* context, char* topicName, int topicLen, MQTTAsync_message* message);
318 
337 typedef void MQTTAsync_deliveryComplete(void* context, MQTTAsync_token token);
338 
354 typedef void MQTTAsync_connectionLost(void* context, char* cause);
355 
356 
369 typedef void MQTTAsync_connected(void* context, char* cause);
370 
371 
372 
374 typedef struct
375 {
377  MQTTAsync_token token;
379  int code;
381  const char *message;
383 
385 typedef struct
386 {
388  MQTTAsync_token token;
390  union
391  {
393  int qos;
395  int* qosList;
397  struct
398  {
401  } pub;
402  /* For connect, the server connected to, MQTT version used, and sessionPresent flag */
403  struct
404  {
405  char* serverURI;
408  } connect;
409  } alt;
411 
422 typedef void MQTTAsync_onSuccess(void* context, MQTTAsync_successData* response);
423 
434 typedef void MQTTAsync_onFailure(void* context, MQTTAsync_failureData* response);
435 
436 typedef struct
437 {
439  char struct_id[4];
459  void* context;
460  MQTTAsync_token token; /* output */
462 
463 #define MQTTAsync_responseOptions_initializer { {'M', 'Q', 'T', 'R'}, 0, NULL, NULL, 0, 0 }
464 
465 
494 DLLExport int MQTTAsync_setCallbacks(MQTTAsync handle, void* context, MQTTAsync_connectionLost* cl,
496 
497 
510 DLLExport int MQTTAsync_setConnected(MQTTAsync handle, void* context, MQTTAsync_connected* co);
511 
512 
521 DLLExport int MQTTAsync_reconnect(MQTTAsync handle);
522 
523 
565 DLLExport int MQTTAsync_create(MQTTAsync* handle, const char* serverURI, const char* clientId,
566  int persistence_type, void* persistence_context);
567 
568 typedef struct
569 {
571  char struct_id[4];
579 
580 #define MQTTAsync_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 0, 0, 100 }
581 
582 
583 DLLExport int MQTTAsync_createWithOptions(MQTTAsync* handle, const char* serverURI, const char* clientId,
584  int persistence_type, void* persistence_context, MQTTAsync_createOptions* options);
585 
598 typedef struct
599 {
601  char struct_id[4];
607  const char* topicName;
609  const char* message;
613  int retained;
618  int qos;
620  struct
621  {
622  int len;
623  const void* data;
624  } payload;
626 
627 #define MQTTAsync_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, { 0, NULL } }
628 
641 typedef struct
642 {
644  char struct_id[4];
647 
649  const char* trustStore;
650 
654  const char* keyStore;
655 
659  const char* privateKey;
661  const char* privateKeyPassword;
662 
671  const char* enabledCipherSuites;
672 
675 
677 
678 #define MQTTAsync_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 0, NULL, NULL, NULL, NULL, NULL, 1 }
679 
685 typedef struct
686 {
688  char struct_id[4];
745  const char* username;
751  const char* password;
782  void* context;
795  char* const* serverURIs;
818  struct {
819  int len;
820  const void* data;
821  } binarypwd;
823 
824 
825 #define MQTTAsync_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 5, 60, 1, 10, NULL, NULL, NULL, 30, 0,\
826 NULL, NULL, NULL, NULL, 0, NULL, 0, 0, 1, 60, {0, NULL}}
827 
848 DLLExport int MQTTAsync_connect(MQTTAsync handle, const MQTTAsync_connectOptions* options);
849 
850 
851 typedef struct
852 {
854  char struct_id[4];
861  int timeout;
879  void* context;
881 
882 #define MQTTAsync_disconnectOptions_initializer { {'M', 'Q', 'T', 'D'}, 0, 0, NULL, NULL, NULL }
883 
884 
903 DLLExport int MQTTAsync_disconnect(MQTTAsync handle, const MQTTAsync_disconnectOptions* options);
904 
905 
913 DLLExport int MQTTAsync_isConnected(MQTTAsync handle);
914 
915 
930 DLLExport int MQTTAsync_subscribe(MQTTAsync handle, const char* topic, int qos, MQTTAsync_responseOptions* response);
931 
932 
950 DLLExport int MQTTAsync_subscribeMany(MQTTAsync handle, int count, char* const* topic, int* qos, MQTTAsync_responseOptions* response);
951 
964 DLLExport int MQTTAsync_unsubscribe(MQTTAsync handle, const char* topic, MQTTAsync_responseOptions* response);
965 
978 DLLExport int MQTTAsync_unsubscribeMany(MQTTAsync handle, int count, char* const* topic, MQTTAsync_responseOptions* response);
979 
980 
999 DLLExport int MQTTAsync_send(MQTTAsync handle, const char* destinationName, int payloadlen, void* payload, int qos, int retained,
1000  MQTTAsync_responseOptions* response);
1001 
1002 
1018 DLLExport int MQTTAsync_sendMessage(MQTTAsync handle, const char* destinationName, const MQTTAsync_message* msg, MQTTAsync_responseOptions* response);
1019 
1020 
1039 DLLExport int MQTTAsync_getPendingTokens(MQTTAsync handle, MQTTAsync_token **tokens);
1040 
1049 #define MQTTASYNC_TRUE 1
1050 DLLExport int MQTTAsync_isComplete(MQTTAsync handle, MQTTAsync_token token);
1051 
1052 
1063 DLLExport int MQTTAsync_waitForCompletion(MQTTAsync handle, MQTTAsync_token token, unsigned long timeout);
1064 
1065 
1076 DLLExport void MQTTAsync_freeMessage(MQTTAsync_message** msg);
1077 
1086 DLLExport void MQTTAsync_free(void* ptr);
1087 
1095 DLLExport void MQTTAsync_destroy(MQTTAsync* handle);
1096 
1097 
1098 
1100 {
1108 };
1109 
1110 
1116 DLLExport void MQTTAsync_setTraceLevel(enum MQTTASYNC_TRACE_LEVELS level);
1117 
1118 
1127 typedef void MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char* message);
1128 
1135 DLLExport void MQTTAsync_setTraceCallback(MQTTAsync_traceCallback* callback);
1136 
1137 
1138 typedef struct
1139 {
1140  const char* name;
1141  const char* value;
1143 
1151 
1152 
1709 #endif
1710 
1711 #ifdef __cplusplus
1712  }
1713 #endif
int sendWhileDisconnected
Definition: MQTTAsync.h:575
MQTTAsync_token token
Definition: MQTTAsync.h:388
Definition: MQTTAsync.h:1105
int len
Definition: MQTTAsync.h:622
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:381
int MQTTAsync_token
Definition: MQTTAsync.h:225
int * qosList
Definition: MQTTAsync.h:395
DLLExport int MQTTAsync_waitForCompletion(MQTTAsync handle, MQTTAsync_token token, unsigned long timeout)
char *const * serverURIs
Definition: MQTTAsync.h:795
int struct_version
Definition: MQTTAsync.h:696
MQTTAsync_token token
Definition: MQTTAsync.h:377
Definition: MQTTAsync.h:598
void MQTTAsync_connectionLost(void *context, char *cause)
Definition: MQTTAsync.h:354
int MQTTVersion
Definition: MQTTAsync.h:406
MQTTAsync_willOptions * will
Definition: MQTTAsync.h:739
MQTTAsync_token token
Definition: MQTTAsync.h:460
void MQTTAsync_connected(void *context, char *cause)
Definition: MQTTAsync.h:369
int struct_version
Definition: MQTTAsync.h:198
const char * keyStore
Definition: MQTTAsync.h:654
const void * data
Definition: MQTTAsync.h:820
int sessionPresent
Definition: MQTTAsync.h:407
Definition: MQTTAsync.h:233
int MQTTVersion
Definition: MQTTAsync.h:802
int struct_version
Definition: MQTTAsync.h:441
const char * password
Definition: MQTTAsync.h:751
DLLExport int MQTTAsync_getPendingTokens(MQTTAsync handle, MQTTAsync_token **tokens)
MQTTAsync_onFailure * onFailure
Definition: MQTTAsync.h:453
int keepAliveInterval
Definition: MQTTAsync.h:707
void MQTTAsync_deliveryComplete(void *context, MQTTAsync_token token)
Definition: MQTTAsync.h:337
int qos
Definition: MQTTAsync.h:256
DLLExport int MQTTAsync_subscribe(MQTTAsync handle, const char *topic, int qos, MQTTAsync_responseOptions *response)
MQTTASYNC_TRACE_LEVELS
Definition: MQTTAsync.h:1099
int automaticReconnect
Definition: MQTTAsync.h:806
void * payload
Definition: MQTTAsync.h:242
const char * trustStore
Definition: MQTTAsync.h:649
void * context
Definition: MQTTAsync.h:459
DLLExport int MQTTAsync_subscribeMany(MQTTAsync handle, int count, char *const *topic, int *qos, MQTTAsync_responseOptions *response)
int payloadlen
Definition: MQTTAsync.h:240
MQTTAsync_message message
Definition: MQTTAsync.h:399
DLLExport int MQTTAsync_unsubscribeMany(MQTTAsync handle, int count, char *const *topic, MQTTAsync_responseOptions *response)
Definition: MQTTAsync.h:436
int msgid
Definition: MQTTAsync.h:286
int struct_version
Definition: MQTTAsync.h:646
DLLExport int MQTTAsync_disconnect(MQTTAsync handle, const MQTTAsync_disconnectOptions *options)
int struct_version
Definition: MQTTAsync.h:573
MQTTAsync_onFailure * onFailure
Definition: MQTTAsync.h:776
int struct_version
Definition: MQTTAsync.h:856
DLLExport void MQTTAsync_destroy(MQTTAsync *handle)
MQTTAsync_SSLOptions * ssl
Definition: MQTTAsync.h:764
const char * privateKeyPassword
Definition: MQTTAsync.h:661
const char * topicName
Definition: MQTTAsync.h:607
Definition: MQTTAsync.h:1104
int MQTTAsync_messageArrived(void *context, char *topicName, int topicLen, MQTTAsync_message *message)
Definition: MQTTAsync.h:317
MQTTAsync_onSuccess * onSuccess
Definition: MQTTAsync.h:867
Definition: MQTTAsync.h:685
const char * name
Definition: MQTTAsync.h:1140
Definition: MQTTAsync.h:1106
Definition: MQTTAsync.h:641
void * context
Definition: MQTTAsync.h:879
MQTTAsync_onSuccess * onSuccess
Definition: MQTTAsync.h:447
int struct_version
Definition: MQTTAsync.h:605
char * destinationName
Definition: MQTTAsync.h:400
int retryInterval
Definition: MQTTAsync.h:759
MQTTAsync_onSuccess * onSuccess
Definition: MQTTAsync.h:770
Definition: MQTTAsync.h:568
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:1107
DLLExport int MQTTAsync_connect(MQTTAsync handle, const MQTTAsync_connectOptions *options)
DLLExport MQTTAsync_nameValue * MQTTAsync_getVersionInfo(void)
void MQTTAsync_onSuccess(void *context, MQTTAsync_successData *response)
Definition: MQTTAsync.h:422
DLLExport int MQTTAsync_setConnected(MQTTAsync handle, void *context, MQTTAsync_connected *co)
void MQTTAsync_global_init(MQTTAsync_init_options *inits)
int do_openssl_init
Definition: MQTTAsync.h:200
Definition: MQTTAsync.h:374
int connectTimeout
Definition: MQTTAsync.h:755
int maxBufferedMessages
Definition: MQTTAsync.h:577
int maxInflight
Definition: MQTTAsync.h:733
DLLExport void MQTTAsync_setTraceLevel(enum MQTTASYNC_TRACE_LEVELS level)
Definition: MQTTAsync.h:1138
Definition: MQTTAsync.h:1101
DLLExport int MQTTAsync_unsubscribe(MQTTAsync handle, const char *topic, MQTTAsync_responseOptions *response)
int len
Definition: MQTTAsync.h:819
const void * data
Definition: MQTTAsync.h:623
Definition: MQTTAsync.h:1102
int serverURIcount
Definition: MQTTAsync.h:786
const char * value
Definition: MQTTAsync.h:1141
void * MQTTAsync
Definition: MQTTAsync.h:215
int qos
Definition: MQTTAsync.h:393
DLLExport int MQTTAsync_sendMessage(MQTTAsync handle, const char *destinationName, const MQTTAsync_message *msg, MQTTAsync_responseOptions *response)
const char * username
Definition: MQTTAsync.h:745
int enableServerCertAuth
Definition: MQTTAsync.h:674
void MQTTAsync_onFailure(void *context, MQTTAsync_failureData *response)
Definition: MQTTAsync.h:434
Definition: MQTTAsync.h:851
int retained
Definition: MQTTAsync.h:613
int timeout
Definition: MQTTAsync.h:861
void MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char *message)
Definition: MQTTAsync.h:1127
int struct_version
Definition: MQTTAsync.h:238
void * context
Definition: MQTTAsync.h:782
int code
Definition: MQTTAsync.h:379
DLLExport int MQTTAsync_reconnect(MQTTAsync handle)
MQTTAsync_onFailure * onFailure
Definition: MQTTAsync.h:873
Definition: MQTTAsync.h:193
const char * privateKey
Definition: MQTTAsync.h:659
int maxRetryInterval
Definition: MQTTAsync.h:814
const char * enabledCipherSuites
Definition: MQTTAsync.h:671
int qos
Definition: MQTTAsync.h:618
int cleansession
Definition: MQTTAsync.h:729
DLLExport int MQTTAsync_isConnected(MQTTAsync handle)
const char * message
Definition: MQTTAsync.h:609
This structure represents a persistent data store, used to store outbound and inbound messages...
int minRetryInterval
Definition: MQTTAsync.h:810
int retained
Definition: MQTTAsync.h:275
Definition: MQTTAsync.h:1103
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:282
Definition: MQTTAsync.h:385
char * serverURI
Definition: MQTTAsync.h:405