Paho MQTT C Client Library
Loading...
Searching...
No Matches
MQTTClient.h
Go to the documentation of this file.
1/*******************************************************************************
2 * Copyright (c) 2009, 2021 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
104/*
106*/
107#if !defined(MQTTCLIENT_H)
108#define MQTTCLIENT_H
109
110#if defined(__cplusplus)
111 extern "C" {
112#endif
113
114#include <stdio.h>
115/*
117*/
118
119#include "MQTTExportDeclarations.h"
120
121#include "MQTTProperties.h"
122#include "MQTTReasonCodes.h"
123#include "MQTTSubscribeOpts.h"
124#if !defined(NO_PERSISTENCE)
126#endif
127
132#define MQTTCLIENT_SUCCESS 0
137#define MQTTCLIENT_FAILURE -1
138
139/* error code -2 is MQTTCLIENT_PERSISTENCE_ERROR */
140
144#define MQTTCLIENT_DISCONNECTED -3
149#define MQTTCLIENT_MAX_MESSAGES_INFLIGHT -4
153#define MQTTCLIENT_BAD_UTF8_STRING -5
157#define MQTTCLIENT_NULL_PARAMETER -6
163#define MQTTCLIENT_TOPICNAME_TRUNCATED -7
168#define MQTTCLIENT_BAD_STRUCTURE -8
172#define MQTTCLIENT_BAD_QOS -9
176#define MQTTCLIENT_SSL_NOT_SUPPORTED -10
180 #define MQTTCLIENT_BAD_MQTT_VERSION -11
186#define MQTTCLIENT_BAD_PROTOCOL -14
190 #define MQTTCLIENT_BAD_MQTT_OPTION -15
194 #define MQTTCLIENT_WRONG_MQTT_VERSION -16
198 #define MQTTCLIENT_0_LEN_WILL_TOPIC -17
199
200
204#define MQTTVERSION_DEFAULT 0
208#define MQTTVERSION_3_1 3
212#define MQTTVERSION_3_1_1 4
216 #define MQTTVERSION_5 5
220#define MQTT_BAD_SUBSCRIBE 0x80
221
225typedef struct
226{
228 char struct_id[4];
234
235#define MQTTClient_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
236
242
247typedef void* MQTTClient;
260
267typedef struct
268{
270 char struct_id[4];
277 void* payload;
291 int qos;
317 int dup;
321 int msgid;
327
328#define MQTTClient_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }
329
360typedef int MQTTClient_messageArrived(void* context, char* topicName, int topicLen, MQTTClient_message* message);
361
383
399typedef void MQTTClient_connectionLost(void* context, char* cause);
400
429LIBMQTT_API int MQTTClient_setCallbacks(MQTTClient handle, void* context, MQTTClient_connectionLost* cl,
431
432
442typedef void MQTTClient_disconnected(void* context, MQTTProperties* properties,
443 enum MQTTReasonCodes reasonCode);
444
458LIBMQTT_API int MQTTClient_setDisconnected(MQTTClient handle, void* context, MQTTClient_disconnected* co);
459
483typedef void MQTTClient_published(void* context, int dt, int packet_type, MQTTProperties* properties,
484 enum MQTTReasonCodes reasonCode);
485
486LIBMQTT_API int MQTTClient_setPublished(MQTTClient handle, void* context, MQTTClient_published* co);
487
532LIBMQTT_API int MQTTClient_create(MQTTClient* handle, const char* serverURI, const char* clientId,
533 int persistence_type, void* persistence_context);
534
536typedef struct
537{
539 char struct_id[4];
549
550#define MQTTClient_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 0, MQTTVERSION_DEFAULT }
551
596LIBMQTT_API int MQTTClient_createWithOptions(MQTTClient* handle, const char* serverURI, const char* clientId,
597 int persistence_type, void* persistence_context, MQTTClient_createOptions* options);
598
611typedef struct
612{
614 char struct_id[4];
620 const char* topicName;
622 const char* message;
631 int qos;
633 struct
634 {
635 int len;
636 const void* data;
637 } payload;
639
640#define MQTTClient_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, {0, NULL} }
641
642#define MQTT_SSL_VERSION_DEFAULT 0
643#define MQTT_SSL_VERSION_TLS_1_0 1
644#define MQTT_SSL_VERSION_TLS_1_1 2
645#define MQTT_SSL_VERSION_TLS_1_2 3
646
659typedef struct
660{
662 char struct_id[4];
663
672
674 const char* trustStore;
675
679 const char* keyStore;
680
684 const char* privateKey;
685
688
698
701
707
714
720 const char* CApath;
721
726 int (*ssl_error_cb) (const char *str, size_t len, void *u);
727
733
739 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);
740
746
753
761 const unsigned char *protos;
762
767 unsigned int protos_len;
769
770#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 }
771
779typedef struct
780{
781 const char* name;
782 const char* value;
784
791
806typedef struct
807{
809 char struct_id[4];
874 const char* username;
880 const char* password;
915 char* const* serverURIs;
927 struct
928 {
929 const char* serverURI;
930 int MQTTVersion;
932 } returned;
936 struct
937 {
938 int len;
939 const void* data;
940 } binarypwd;
945 /*
946 * MQTT V5 clean start flag. Only clears state at the beginning of the session.
947 */
956 const char* httpProxy;
960 const char* httpsProxy;
962
963#define MQTTClient_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 8, 60, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
9640, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
965
966#define MQTTClient_connectOptions_initializer5 { {'M', 'Q', 'T', 'C'}, 8, 60, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
9670, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
968
969#define MQTTClient_connectOptions_initializer_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
9700, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
971
972#define MQTTClient_connectOptions_initializer5_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
9730, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
974
996
998typedef struct MQTTResponse
999{
1000 int version; /* the version number of this structure */
1001 enum MQTTReasonCodes reasonCode; /* the MQTT 5.0 reason code returned */
1002 int reasonCodeCount; /* the number of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
1003 enum MQTTReasonCodes* reasonCodes; /* a list of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
1004 MQTTProperties* properties; /* optionally, the MQTT 5.0 properties returned */
1006
1007#define MQTTResponse_initializer {1, MQTTREASONCODE_SUCCESS, 0, NULL, NULL}
1008
1013LIBMQTT_API void MQTTResponse_free(MQTTResponse response);
1014
1029 MQTTProperties* connectProperties, MQTTProperties* willProperties);
1030
1049LIBMQTT_API int MQTTClient_disconnect(MQTTClient handle, int timeout);
1050
1051LIBMQTT_API int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties* props);
1052
1060LIBMQTT_API int MQTTClient_isConnected(MQTTClient handle);
1061
1062
1063/* Subscribe is synchronous. QoS list parameter is changed on return to granted QoSs.
1064 Returns return code, MQTTCLIENT_SUCCESS == success, non-zero some sort of error (TBD) */
1065
1079LIBMQTT_API int MQTTClient_subscribe(MQTTClient handle, const char* topic, int qos);
1080
1094LIBMQTT_API MQTTResponse MQTTClient_subscribe5(MQTTClient handle, const char* topic, int qos,
1096
1113LIBMQTT_API int MQTTClient_subscribeMany(MQTTClient handle, int count, char* const* topic, int* qos);
1114
1131LIBMQTT_API MQTTResponse MQTTClient_subscribeMany5(MQTTClient handle, int count, char* const* topic,
1132 int* qos, MQTTSubscribe_options* opts, MQTTProperties* props);
1133
1145LIBMQTT_API int MQTTClient_unsubscribe(MQTTClient handle, const char* topic);
1146
1157LIBMQTT_API MQTTResponse MQTTClient_unsubscribe5(MQTTClient handle, const char* topic, MQTTProperties* props);
1158
1170LIBMQTT_API int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char* const* topic);
1171
1183LIBMQTT_API MQTTResponse MQTTClient_unsubscribeMany5(MQTTClient handle, int count, char* const* topic, MQTTProperties* props);
1184
1206LIBMQTT_API int MQTTClient_publish(MQTTClient handle, const char* topicName, int payloadlen, const void* payload, int qos, int retained,
1208
1230LIBMQTT_API MQTTResponse MQTTClient_publish5(MQTTClient handle, const char* topicName, int payloadlen, const void* payload,
1231 int qos, int retained, MQTTProperties* properties, MQTTClient_deliveryToken* dt);
1251LIBMQTT_API int MQTTClient_publishMessage(MQTTClient handle, const char* topicName, MQTTClient_message* msg, MQTTClient_deliveryToken* dt);
1252
1253
1273LIBMQTT_API MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char* topicName, MQTTClient_message* msg,
1275
1291LIBMQTT_API int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout);
1292
1293
1313
1320LIBMQTT_API void MQTTClient_yield(void);
1321
1353LIBMQTT_API int MQTTClient_receive(MQTTClient handle, char** topicName, int* topicLen, MQTTClient_message** message,
1354 unsigned long timeout);
1355
1367
1376LIBMQTT_API void MQTTClient_free(void* ptr);
1377
1385LIBMQTT_API void MQTTClient_destroy(MQTTClient* handle);
1386
1387
1389{
1397};
1398
1399
1406
1407
1416typedef void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char* message);
1417
1425
1433LIBMQTT_API int MQTTClient_setCommandTimeout(MQTTClient handle, unsigned long milliSeconds);
1434
1440LIBMQTT_API const char* MQTTClient_strerror(int code);
1441
1442#if defined(__cplusplus)
1443 }
1444#endif
1445
1446#endif
1447
void MQTTResponse_free(MQTTResponse response)
int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties *props)
int MQTTClient_disconnect(MQTTClient handle, int timeout)
void MQTTClient_free(void *ptr)
void MQTTClient_global_init(MQTTClient_init_options *inits)
void MQTTClient_setTraceCallback(MQTTClient_traceCallback *callback)
int MQTTClient_getPendingDeliveryTokens(MQTTClient handle, MQTTClient_deliveryToken **tokens)
MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
void MQTTClient_disconnected(void *context, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
Definition: MQTTClient.h:442
MQTTResponse MQTTClient_unsubscribeMany5(MQTTClient handle, int count, char *const *topic, MQTTProperties *props)
int MQTTClient_receive(MQTTClient handle, char **topicName, int *topicLen, MQTTClient_message **message, unsigned long timeout)
void MQTTClient_setTraceLevel(enum MQTTCLIENT_TRACE_LEVELS level)
int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char *const *topic)
MQTTResponse MQTTClient_subscribeMany5(MQTTClient handle, int count, char *const *topic, int *qos, MQTTSubscribe_options *opts, MQTTProperties *props)
MQTTResponse MQTTClient_unsubscribe5(MQTTClient handle, const char *topic, MQTTProperties *props)
const char * MQTTClient_strerror(int code)
void MQTTClient_connectionLost(void *context, char *cause)
Definition: MQTTClient.h:399
void MQTTClient_published(void *context, int dt, int packet_type, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
Definition: MQTTClient.h:483
int MQTTClient_isConnected(MQTTClient handle)
int MQTTClient_deliveryToken
Definition: MQTTClient.h:258
void * MQTTClient
Definition: MQTTClient.h:247
MQTTResponse MQTTClient_publish5(MQTTClient handle, const char *topicName, int payloadlen, const void *payload, int qos, int retained, MQTTProperties *properties, MQTTClient_deliveryToken *dt)
int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout)
void MQTTClient_yield(void)
int MQTTClient_setDisconnected(MQTTClient handle, void *context, MQTTClient_disconnected *co)
int MQTTClient_token
Definition: MQTTClient.h:259
int MQTTClient_subscribeMany(MQTTClient handle, int count, char *const *topic, int *qos)
int MQTTClient_setCommandTimeout(MQTTClient handle, unsigned long milliSeconds)
int MQTTClient_create(MQTTClient *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context)
int MQTTClient_subscribe(MQTTClient handle, const char *topic, int qos)
int MQTTClient_setPublished(MQTTClient handle, void *context, MQTTClient_published *co)
MQTTCLIENT_TRACE_LEVELS
Definition: MQTTClient.h:1389
@ MQTTCLIENT_TRACE_PROTOCOL
Definition: MQTTClient.h:1393
@ MQTTCLIENT_TRACE_FATAL
Definition: MQTTClient.h:1396
@ MQTTCLIENT_TRACE_MAXIMUM
Definition: MQTTClient.h:1390
@ MQTTCLIENT_TRACE_MEDIUM
Definition: MQTTClient.h:1391
@ MQTTCLIENT_TRACE_ERROR
Definition: MQTTClient.h:1394
@ MQTTCLIENT_TRACE_MINIMUM
Definition: MQTTClient.h:1392
@ MQTTCLIENT_TRACE_SEVERE
Definition: MQTTClient.h:1395
int MQTTClient_messageArrived(void *context, char *topicName, int topicLen, MQTTClient_message *message)
Definition: MQTTClient.h:360
MQTTResponse MQTTClient_connect5(MQTTClient handle, MQTTClient_connectOptions *options, MQTTProperties *connectProperties, MQTTProperties *willProperties)
int MQTTClient_unsubscribe(MQTTClient handle, const char *topic)
int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions *options)
int MQTTClient_setCallbacks(MQTTClient handle, void *context, MQTTClient_connectionLost *cl, MQTTClient_messageArrived *ma, MQTTClient_deliveryComplete *dc)
void MQTTClient_freeMessage(MQTTClient_message **msg)
void MQTTClient_deliveryComplete(void *context, MQTTClient_deliveryToken dt)
Definition: MQTTClient.h:382
int MQTTClient_publishMessage(MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
int MQTTClient_createWithOptions(MQTTClient *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context, MQTTClient_createOptions *options)
void MQTTClient_destroy(MQTTClient *handle)
MQTTClient_nameValue * MQTTClient_getVersionInfo(void)
MQTTResponse MQTTClient_subscribe5(MQTTClient handle, const char *topic, int qos, MQTTSubscribe_options *opts, MQTTProperties *props)
void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char *message)
Definition: MQTTClient.h:1416
int MQTTClient_publish(MQTTClient handle, const char *topicName, int payloadlen, const void *payload, int qos, int retained, MQTTClient_deliveryToken *dt)
This structure represents a persistent data store, used to store outbound and inbound messages,...
MQTTReasonCodes
Definition: MQTTReasonCodes.h:23
Definition: MQTTClient.h:660
const char * trustStore
Definition: MQTTClient.h:674
int struct_version
Definition: MQTTClient.h:671
int disableDefaultTrustStore
Definition: MQTTClient.h:752
void * ssl_error_context
Definition: MQTTClient.h:732
unsigned int protos_len
Definition: MQTTClient.h:767
const char * CApath
Definition: MQTTClient.h:720
const char * keyStore
Definition: MQTTClient.h:679
int sslVersion
Definition: MQTTClient.h:706
const unsigned char * protos
Definition: MQTTClient.h:761
int enableServerCertAuth
Definition: MQTTClient.h:700
const char * privateKey
Definition: MQTTClient.h:684
int verify
Definition: MQTTClient.h:713
const char * enabledCipherSuites
Definition: MQTTClient.h:697
void * ssl_psk_context
Definition: MQTTClient.h:745
const char * privateKeyPassword
Definition: MQTTClient.h:687
Definition: MQTTClient.h:807
const MQTTClient_nameValue * httpHeaders
Definition: MQTTClient.h:952
int cleansession
Definition: MQTTClient.h:852
int struct_version
Definition: MQTTClient.h:820
MQTTClient_willOptions * will
Definition: MQTTClient.h:868
const void * data
Definition: MQTTClient.h:939
int MQTTVersion
Definition: MQTTClient.h:923
const char * serverURI
Definition: MQTTClient.h:929
const char * httpsProxy
Definition: MQTTClient.h:960
int connectTimeout
Definition: MQTTClient.h:884
int sessionPresent
Definition: MQTTClient.h:931
MQTTClient_SSLOptions * ssl
Definition: MQTTClient.h:897
int reliable
Definition: MQTTClient.h:862
const char * password
Definition: MQTTClient.h:880
int serverURIcount
Definition: MQTTClient.h:901
char *const * serverURIs
Definition: MQTTClient.h:915
const char * username
Definition: MQTTClient.h:874
int retryInterval
Definition: MQTTClient.h:892
int keepAliveInterval
Definition: MQTTClient.h:830
int cleanstart
Definition: MQTTClient.h:948
const char * httpProxy
Definition: MQTTClient.h:956
int maxInflightMessages
Definition: MQTTClient.h:944
int len
Definition: MQTTClient.h:938
Definition: MQTTClient.h:537
int struct_version
Definition: MQTTClient.h:541
int MQTTVersion
Definition: MQTTClient.h:547
Definition: MQTTClient.h:226
int struct_version
Definition: MQTTClient.h:230
int do_openssl_init
Definition: MQTTClient.h:232
Definition: MQTTClient.h:268
int struct_version
Definition: MQTTClient.h:273
MQTTProperties properties
Definition: MQTTClient.h:325
int qos
Definition: MQTTClient.h:291
int msgid
Definition: MQTTClient.h:321
int retained
Definition: MQTTClient.h:310
void * payload
Definition: MQTTClient.h:277
int payloadlen
Definition: MQTTClient.h:275
int dup
Definition: MQTTClient.h:317
Definition: MQTTClient.h:780
const char * value
Definition: MQTTClient.h:782
const char * name
Definition: MQTTClient.h:781
Definition: MQTTClient.h:612
int struct_version
Definition: MQTTClient.h:618
const void * data
Definition: MQTTClient.h:636
const char * topicName
Definition: MQTTClient.h:620
const char * message
Definition: MQTTClient.h:622
int qos
Definition: MQTTClient.h:631
int retained
Definition: MQTTClient.h:626
int len
Definition: MQTTClient.h:635
Definition: MQTTProperties.h:113
Definition: MQTTClient.h:999
enum MQTTReasonCodes * reasonCodes
Definition: MQTTClient.h:1003
enum MQTTReasonCodes reasonCode
Definition: MQTTClient.h:1001
MQTTProperties * properties
Definition: MQTTClient.h:1004
int version
Definition: MQTTClient.h:1000
int reasonCodeCount
Definition: MQTTClient.h:1002
Definition: MQTTSubscribeOpts.h:22