Paho MQTT C Client Library
Loading...
Searching...
No Matches
MQTTClient.h
Go to the documentation of this file.
1/*******************************************************************************
2 * Copyright (c) 2009, 2023 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
190#define MQTTCLIENT_BAD_PROTOCOL -14
194 #define MQTTCLIENT_BAD_MQTT_OPTION -15
198 #define MQTTCLIENT_WRONG_MQTT_VERSION -16
202 #define MQTTCLIENT_0_LEN_WILL_TOPIC -17
203
204
208#define MQTTVERSION_DEFAULT 0
212#define MQTTVERSION_3_1 3
216#define MQTTVERSION_3_1_1 4
220 #define MQTTVERSION_5 5
224#define MQTT_BAD_SUBSCRIBE 0x80
225
229typedef struct
230{
232 char struct_id[4];
238
239#define MQTTClient_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
240
246
251typedef void* MQTTClient;
264
271typedef struct
272{
274 char struct_id[4];
281 void* payload;
295 int qos;
321 int dup;
325 int msgid;
331
332#define MQTTClient_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }
333
364typedef int MQTTClient_messageArrived(void* context, char* topicName, int topicLen, MQTTClient_message* message);
365
387
403typedef void MQTTClient_connectionLost(void* context, char* cause);
404
433LIBMQTT_API int MQTTClient_setCallbacks(MQTTClient handle, void* context, MQTTClient_connectionLost* cl,
435
436
446typedef void MQTTClient_disconnected(void* context, MQTTProperties* properties,
447 enum MQTTReasonCodes reasonCode);
448
462LIBMQTT_API int MQTTClient_setDisconnected(MQTTClient handle, void* context, MQTTClient_disconnected* co);
463
487typedef void MQTTClient_published(void* context, int dt, int packet_type, MQTTProperties* properties,
488 enum MQTTReasonCodes reasonCode);
489
490LIBMQTT_API int MQTTClient_setPublished(MQTTClient handle, void* context, MQTTClient_published* co);
491
544LIBMQTT_API int MQTTClient_create(MQTTClient* handle, const char* serverURI, const char* clientId,
545 int persistence_type, void* persistence_context);
546
548typedef struct
549{
551 char struct_id[4];
561
562#define MQTTClient_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 0, MQTTVERSION_DEFAULT }
563
608LIBMQTT_API int MQTTClient_createWithOptions(MQTTClient* handle, const char* serverURI, const char* clientId,
609 int persistence_type, void* persistence_context, MQTTClient_createOptions* options);
610
623typedef struct
624{
626 char struct_id[4];
632 const char* topicName;
634 const char* message;
643 int qos;
645 struct
646 {
647 int len;
648 const void* data;
649 } payload;
651
652#define MQTTClient_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, {0, NULL} }
653
654#define MQTT_SSL_VERSION_DEFAULT 0
655#define MQTT_SSL_VERSION_TLS_1_0 1
656#define MQTT_SSL_VERSION_TLS_1_1 2
657#define MQTT_SSL_VERSION_TLS_1_2 3
658
671typedef struct
672{
674 char struct_id[4];
675
684
686 const char* trustStore;
687
691 const char* keyStore;
692
696 const char* privateKey;
697
700
710
713
719
726
732 const char* CApath;
733
738 int (*ssl_error_cb) (const char *str, size_t len, void *u);
739
745
751 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);
752
758
765
773 const unsigned char *protos;
774
779 unsigned int protos_len;
781
782#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 }
783
791typedef struct
792{
793 const char* name;
794 const char* value;
796
803
824typedef struct
825{
827 char struct_id[4];
892 const char* username;
898 const char* password;
933 char* const* serverURIs;
945 struct
946 {
947 const char* serverURI;
948 int MQTTVersion;
950 } returned;
954 struct
955 {
956 int len;
957 const void* data;
958 } binarypwd;
963 /*
964 * MQTT V5 clean start flag. Only clears state at the beginning of the session.
965 */
974 const char* httpProxy;
978 const char* httpsProxy;
980
982#define MQTTClient_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 8, 60, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
9830, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
984
986#define MQTTClient_connectOptions_initializer5 { {'M', 'Q', 'T', 'C'}, 8, 60, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
9870, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
988
992#define MQTTClient_connectOptions_initializer_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 1, 1, NULL, NULL, NULL, 30, 0, NULL,\
9930, NULL, MQTTVERSION_DEFAULT, {NULL, 0, 0}, {0, NULL}, -1, 0, NULL, NULL, NULL}
994
998#define MQTTClient_connectOptions_initializer5_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 0, 1, NULL, NULL, NULL, 30, 0, NULL,\
9990, NULL, MQTTVERSION_5, {NULL, 0, 0}, {0, NULL}, -1, 1, NULL, NULL, NULL}
1000
1022
1024typedef struct MQTTResponse
1025{
1026 int version; /* the version number of this structure */
1027 enum MQTTReasonCodes reasonCode; /* the MQTT 5.0 reason code returned */
1028 int reasonCodeCount; /* the number of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
1029 enum MQTTReasonCodes* reasonCodes; /* a list of reason codes. Used for subscribeMany5 and unsubscribeMany5 */
1030 MQTTProperties* properties; /* optionally, the MQTT 5.0 properties returned */
1032
1033#define MQTTResponse_initializer {1, MQTTREASONCODE_SUCCESS, 0, NULL, NULL}
1034
1039LIBMQTT_API void MQTTResponse_free(MQTTResponse response);
1040
1055 MQTTProperties* connectProperties, MQTTProperties* willProperties);
1056
1075LIBMQTT_API int MQTTClient_disconnect(MQTTClient handle, int timeout);
1076
1077LIBMQTT_API int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties* props);
1078
1086LIBMQTT_API int MQTTClient_isConnected(MQTTClient handle);
1087
1088
1089/* Subscribe is synchronous. QoS list parameter is changed on return to granted QoSs.
1090 Returns return code, MQTTCLIENT_SUCCESS == success, non-zero some sort of error (TBD) */
1091
1105LIBMQTT_API int MQTTClient_subscribe(MQTTClient handle, const char* topic, int qos);
1106
1120LIBMQTT_API MQTTResponse MQTTClient_subscribe5(MQTTClient handle, const char* topic, int qos,
1122
1139LIBMQTT_API int MQTTClient_subscribeMany(MQTTClient handle, int count, char* const* topic, int* qos);
1140
1157LIBMQTT_API MQTTResponse MQTTClient_subscribeMany5(MQTTClient handle, int count, char* const* topic,
1158 int* qos, MQTTSubscribe_options* opts, MQTTProperties* props);
1159
1171LIBMQTT_API int MQTTClient_unsubscribe(MQTTClient handle, const char* topic);
1172
1183LIBMQTT_API MQTTResponse MQTTClient_unsubscribe5(MQTTClient handle, const char* topic, MQTTProperties* props);
1184
1196LIBMQTT_API int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char* const* topic);
1197
1209LIBMQTT_API MQTTResponse MQTTClient_unsubscribeMany5(MQTTClient handle, int count, char* const* topic, MQTTProperties* props);
1210
1232LIBMQTT_API int MQTTClient_publish(MQTTClient handle, const char* topicName, int payloadlen, const void* payload, int qos, int retained,
1234
1256LIBMQTT_API MQTTResponse MQTTClient_publish5(MQTTClient handle, const char* topicName, int payloadlen, const void* payload,
1257 int qos, int retained, MQTTProperties* properties, MQTTClient_deliveryToken* dt);
1277LIBMQTT_API int MQTTClient_publishMessage(MQTTClient handle, const char* topicName, MQTTClient_message* msg, MQTTClient_deliveryToken* dt);
1278
1279
1299LIBMQTT_API MQTTResponse MQTTClient_publishMessage5(MQTTClient handle, const char* topicName, MQTTClient_message* msg,
1301
1317LIBMQTT_API int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout);
1318
1319
1339
1346LIBMQTT_API void MQTTClient_yield(void);
1347
1379LIBMQTT_API int MQTTClient_receive(MQTTClient handle, char** topicName, int* topicLen, MQTTClient_message** message,
1380 unsigned long timeout);
1381
1393
1402LIBMQTT_API void MQTTClient_free(void* ptr);
1403
1410LIBMQTT_API void* MQTTClient_malloc(size_t size);
1411
1419LIBMQTT_API void MQTTClient_destroy(MQTTClient* handle);
1420
1421
1432
1433
1440
1441
1451typedef void MQTTClient_traceCallback(enum MQTTCLIENT_TRACE_LEVELS level, char* message);
1452
1460
1468LIBMQTT_API int MQTTClient_setCommandTimeout(MQTTClient handle, unsigned long milliSeconds);
1469
1475LIBMQTT_API const char* MQTTClient_strerror(int code);
1476
1477#if defined(__cplusplus)
1478 }
1479#endif
1480
1481#endif
1482
void MQTTResponse_free(MQTTResponse response)
struct MQTTResponse MQTTResponse
int MQTTClient_disconnect5(MQTTClient handle, int timeout, enum MQTTReasonCodes reason, MQTTProperties *props)
int MQTTClient_disconnect(MQTTClient handle, int timeout)
void * MQTTClient_malloc(size_t size)
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:446
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:403
void MQTTClient_published(void *context, int dt, int packet_type, MQTTProperties *properties, enum MQTTReasonCodes reasonCode)
Definition MQTTClient.h:487
int MQTTClient_isConnected(MQTTClient handle)
int MQTTClient_deliveryToken
Definition MQTTClient.h:262
void * MQTTClient
Definition MQTTClient.h:251
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:263
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:1423
@ MQTTCLIENT_TRACE_PROTOCOL
Definition MQTTClient.h:1427
@ MQTTCLIENT_TRACE_FATAL
Definition MQTTClient.h:1430
@ MQTTCLIENT_TRACE_MAXIMUM
Definition MQTTClient.h:1424
@ MQTTCLIENT_TRACE_MEDIUM
Definition MQTTClient.h:1425
@ MQTTCLIENT_TRACE_ERROR
Definition MQTTClient.h:1428
@ MQTTCLIENT_TRACE_MINIMUM
Definition MQTTClient.h:1426
@ MQTTCLIENT_TRACE_SEVERE
Definition MQTTClient.h:1429
int MQTTClient_messageArrived(void *context, char *topicName, int topicLen, MQTTClient_message *message)
Definition MQTTClient.h:364
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:386
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:1451
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:672
const char * trustStore
Definition MQTTClient.h:686
int struct_version
Definition MQTTClient.h:683
int disableDefaultTrustStore
Definition MQTTClient.h:764
void * ssl_error_context
Definition MQTTClient.h:744
unsigned int protos_len
Definition MQTTClient.h:779
const char * CApath
Definition MQTTClient.h:732
const char * keyStore
Definition MQTTClient.h:691
int sslVersion
Definition MQTTClient.h:718
const unsigned char * protos
Definition MQTTClient.h:773
int enableServerCertAuth
Definition MQTTClient.h:712
const char * privateKey
Definition MQTTClient.h:696
int verify
Definition MQTTClient.h:725
const char * enabledCipherSuites
Definition MQTTClient.h:709
void * ssl_psk_context
Definition MQTTClient.h:757
const char * privateKeyPassword
Definition MQTTClient.h:699
Definition MQTTClient.h:825
const MQTTClient_nameValue * httpHeaders
Definition MQTTClient.h:970
int cleansession
Definition MQTTClient.h:870
int struct_version
Definition MQTTClient.h:838
MQTTClient_willOptions * will
Definition MQTTClient.h:886
const void * data
Definition MQTTClient.h:957
int MQTTVersion
Definition MQTTClient.h:941
const char * serverURI
Definition MQTTClient.h:947
const char * httpsProxy
Definition MQTTClient.h:978
int connectTimeout
Definition MQTTClient.h:902
int sessionPresent
Definition MQTTClient.h:949
MQTTClient_SSLOptions * ssl
Definition MQTTClient.h:915
int reliable
Definition MQTTClient.h:880
const char * password
Definition MQTTClient.h:898
int serverURIcount
Definition MQTTClient.h:919
char *const * serverURIs
Definition MQTTClient.h:933
const char * username
Definition MQTTClient.h:892
int retryInterval
Definition MQTTClient.h:910
int keepAliveInterval
Definition MQTTClient.h:848
int cleanstart
Definition MQTTClient.h:966
const char * httpProxy
Definition MQTTClient.h:974
int maxInflightMessages
Definition MQTTClient.h:962
int len
Definition MQTTClient.h:956
Definition MQTTClient.h:549
int struct_version
Definition MQTTClient.h:553
int MQTTVersion
Definition MQTTClient.h:559
Definition MQTTClient.h:230
int struct_version
Definition MQTTClient.h:234
int do_openssl_init
Definition MQTTClient.h:236
Definition MQTTClient.h:272
int struct_version
Definition MQTTClient.h:277
MQTTProperties properties
Definition MQTTClient.h:329
int qos
Definition MQTTClient.h:295
int msgid
Definition MQTTClient.h:325
int retained
Definition MQTTClient.h:314
void * payload
Definition MQTTClient.h:281
int payloadlen
Definition MQTTClient.h:279
int dup
Definition MQTTClient.h:321
Definition MQTTClient.h:792
const char * value
Definition MQTTClient.h:794
const char * name
Definition MQTTClient.h:793
Definition MQTTClient.h:624
int struct_version
Definition MQTTClient.h:630
const void * data
Definition MQTTClient.h:648
const char * topicName
Definition MQTTClient.h:632
const char * message
Definition MQTTClient.h:634
int qos
Definition MQTTClient.h:643
int retained
Definition MQTTClient.h:638
int len
Definition MQTTClient.h:647
Definition MQTTProperties.h:113
Definition MQTTClient.h:1025
enum MQTTReasonCodes * reasonCodes
Definition MQTTClient.h:1029
enum MQTTReasonCodes reasonCode
Definition MQTTClient.h:1027
MQTTProperties * properties
Definition MQTTClient.h:1030
int version
Definition MQTTClient.h:1026
int reasonCodeCount
Definition MQTTClient.h:1028
Definition MQTTSubscribeOpts.h:22