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(__cplusplus)
107  extern "C" {
108 #endif
109 #if !defined(MQTTCLIENT_H)
110 #define MQTTCLIENT_H
111 
112 #if defined(WIN32) || defined(WIN64)
113  #define DLLImport __declspec(dllimport)
114  #define DLLExport __declspec(dllexport)
115 #else
116  #define DLLImport extern
117  #define DLLExport __attribute__ ((visibility ("default")))
118 #endif
119 
120 #include <stdio.h>
121 /*
123 */
124 
125 #if !defined(NO_PERSISTENCE)
126 #include "MQTTClientPersistence.h"
127 #endif
128 
133 #define MQTTCLIENT_SUCCESS 0
134 
138 #define MQTTCLIENT_FAILURE -1
139 
140 /* error code -2 is MQTTCLIENT_PERSISTENCE_ERROR */
141 
145 #define MQTTCLIENT_DISCONNECTED -3
146 
150 #define MQTTCLIENT_MAX_MESSAGES_INFLIGHT -4
151 
154 #define MQTTCLIENT_BAD_UTF8_STRING -5
155 
158 #define MQTTCLIENT_NULL_PARAMETER -6
159 
164 #define MQTTCLIENT_TOPICNAME_TRUNCATED -7
165 
169 #define MQTTCLIENT_BAD_STRUCTURE -8
170 
173 #define MQTTCLIENT_BAD_QOS -9
174 
177 #define MQTTCLIENT_SSL_NOT_SUPPORTED -10
178 
181 #define MQTTCLIENT_BAD_PROTOCOL -14
182 
186 #define MQTTVERSION_DEFAULT 0
187 
190 #define MQTTVERSION_3_1 3
191 
194 #define MQTTVERSION_3_1_1 4
195 
198 #define MQTT_BAD_SUBSCRIBE 0x80
199 
203 typedef struct
204 {
206  char struct_id[4];
212 
213 #define MQTTClient_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
214 
219 DLLExport void MQTTClient_global_init(MQTTClient_init_options* inits);
220 
225 typedef void* MQTTClient;
237 typedef int MQTTClient_token;
238 
245 typedef struct
246 {
248  char struct_id[4];
254  void* payload;
268  int qos;
287  int retained;
294  int dup;
298  int msgid;
300 
301 #define MQTTClient_message_initializer { {'M', 'Q', 'T', 'M'}, 0, 0, NULL, 0, 0, 0, 0 }
302 
329 typedef int MQTTClient_messageArrived(void* context, char* topicName, int topicLen, MQTTClient_message* message);
330 
352 
368 typedef void MQTTClient_connectionLost(void* context, char* cause);
369 
397 DLLExport int MQTTClient_setCallbacks(MQTTClient handle, void* context, MQTTClient_connectionLost* cl,
399 
400 
443 DLLExport int MQTTClient_create(MQTTClient* handle, const char* serverURI, const char* clientId,
444  int persistence_type, void* persistence_context);
445 
458 typedef struct
459 {
461  char struct_id[4];
467  const char* topicName;
469  const char* message;
473  int retained;
478  int qos;
480  struct
481  {
482  int len;
483  const void* data;
484  } payload;
486 
487 #define MQTTClient_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, {0, NULL} }
488 
489 #define MQTT_SSL_VERSION_DEFAULT 0
490 #define MQTT_SSL_VERSION_TLS_1_0 1
491 #define MQTT_SSL_VERSION_TLS_1_1 2
492 #define MQTT_SSL_VERSION_TLS_1_2 3
493 
506 typedef struct
507 {
509  char struct_id[4];
512 
514  const char* trustStore;
515 
519  const char* keyStore;
520 
524  const char* privateKey;
526  const char* privateKeyPassword;
527 
536  const char* enabledCipherSuites;
537 
540 
546 
552  int verify;
553 
559  const char* CApath;
560 
562 
563 #define MQTTClient_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 2, NULL, NULL, NULL, NULL, NULL, 1, MQTT_SSL_VERSION_DEFAULT, 0, NULL }
564 
579 typedef struct
580 {
582  char struct_id[4];
632  int reliable;
644  const char* username;
650  const char* password;
678  char* const* serverURIs;
689  struct
690  {
691  const char* serverURI;
692  int MQTTVersion;
694  } returned;
698  struct {
699  int len;
700  const void* data;
701  } binarypwd;
703 
704 #define MQTTClient_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 5, 60, 1, 1, NULL, NULL, NULL, 30, 20, NULL, 0, NULL, 0, {NULL, 0, 0}, {0, NULL} }
705 
713 typedef struct
714 {
715  const char* name;
716  const char* value;
718 
725 
746 DLLExport int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions* options);
747 
766 DLLExport int MQTTClient_disconnect(MQTTClient handle, int timeout);
767 
775 DLLExport int MQTTClient_isConnected(MQTTClient handle);
776 
777 
778 /* Subscribe is synchronous. QoS list parameter is changed on return to granted QoSs.
779  Returns return code, MQTTCLIENT_SUCCESS == success, non-zero some sort of error (TBD) */
780 
794 DLLExport int MQTTClient_subscribe(MQTTClient handle, const char* topic, int qos);
795 
812 DLLExport int MQTTClient_subscribeMany(MQTTClient handle, int count, char* const* topic, int* qos);
813 
825 DLLExport int MQTTClient_unsubscribe(MQTTClient handle, const char* topic);
826 
838 DLLExport int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char* const* topic);
839 
861 DLLExport int MQTTClient_publish(MQTTClient handle, const char* topicName, int payloadlen, void* payload, int qos, int retained,
882 DLLExport int MQTTClient_publishMessage(MQTTClient handle, const char* topicName, MQTTClient_message* msg, MQTTClient_deliveryToken* dt);
883 
884 
900 DLLExport int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout);
901 
902 
922 
929 DLLExport void MQTTClient_yield(void);
930 
962 DLLExport int MQTTClient_receive(MQTTClient handle, char** topicName, int* topicLen, MQTTClient_message** message,
963  unsigned long timeout);
964 
975 DLLExport void MQTTClient_freeMessage(MQTTClient_message** msg);
976 
985 DLLExport void MQTTClient_free(void* ptr);
986 
994 DLLExport void MQTTClient_destroy(MQTTClient* handle);
995 
996 #endif
997 #ifdef __cplusplus
998  }
999 #endif
1000 
int MQTTVersion
Definition: MQTTClient.h:685
void * MQTTClient
Definition: MQTTClient.h:225
const char * message
Definition: MQTTClient.h:469
int struct_version
Definition: MQTTClient.h:590
const char * username
Definition: MQTTClient.h:644
DLLExport int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions *options)
void MQTTClient_connectionLost(void *context, char *cause)
Definition: MQTTClient.h:368
int dup
Definition: MQTTClient.h:294
const char * enabledCipherSuites
Definition: MQTTClient.h:536
int struct_version
Definition: MQTTClient.h:250
int qos
Definition: MQTTClient.h:268
DLLExport void MQTTClient_free(void *ptr)
const char * password
Definition: MQTTClient.h:650
const char * serverURI
Definition: MQTTClient.h:691
int msgid
Definition: MQTTClient.h:298
int retained
Definition: MQTTClient.h:473
const void * data
Definition: MQTTClient.h:483
int retryInterval
Definition: MQTTClient.h:658
DLLExport int MQTTClient_subscribeMany(MQTTClient handle, int count, char *const *topic, int *qos)
int reliable
Definition: MQTTClient.h:632
Definition: MQTTClient.h:245
DLLExport void MQTTClient_freeMessage(MQTTClient_message **msg)
int keepAliveInterval
Definition: MQTTClient.h:600
int payloadlen
Definition: MQTTClient.h:252
int verify
Definition: MQTTClient.h:552
const char * topicName
Definition: MQTTClient.h:467
int connectTimeout
Definition: MQTTClient.h:654
Definition: MQTTClient.h:203
int struct_version
Definition: MQTTClient.h:511
DLLExport int MQTTClient_create(MQTTClient *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context)
const void * data
Definition: MQTTClient.h:700
DLLExport void MQTTClient_destroy(MQTTClient *handle)
Definition: MQTTClient.h:506
DLLExport MQTTClient_nameValue * MQTTClient_getVersionInfo(void)
int struct_version
Definition: MQTTClient.h:208
DLLExport int MQTTClient_publishMessage(MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
int qos
Definition: MQTTClient.h:478
int sslVersion
Definition: MQTTClient.h:545
int len
Definition: MQTTClient.h:699
Definition: MQTTClient.h:458
DLLExport int MQTTClient_isConnected(MQTTClient handle)
const char * trustStore
Definition: MQTTClient.h:514
DLLExport void MQTTClient_yield(void)
int sessionPresent
Definition: MQTTClient.h:693
Definition: MQTTClient.h:579
DLLExport int MQTTClient_publish(MQTTClient handle, const char *topicName, int payloadlen, void *payload, int qos, int retained, MQTTClient_deliveryToken *dt)
DLLExport int MQTTClient_disconnect(MQTTClient handle, int timeout)
const char * name
Definition: MQTTClient.h:715
MQTTClient_willOptions * will
Definition: MQTTClient.h:638
void MQTTClient_deliveryComplete(void *context, MQTTClient_deliveryToken dt)
Definition: MQTTClient.h:351
const char * privateKeyPassword
Definition: MQTTClient.h:526
int MQTTClient_deliveryToken
Definition: MQTTClient.h:236
char *const * serverURIs
Definition: MQTTClient.h:678
const char * privateKey
Definition: MQTTClient.h:524
MQTTClient_SSLOptions * ssl
Definition: MQTTClient.h:663
DLLExport int MQTTClient_receive(MQTTClient handle, char **topicName, int *topicLen, MQTTClient_message **message, unsigned long timeout)
int MQTTClient_token
Definition: MQTTClient.h:237
int serverURIcount
Definition: MQTTClient.h:667
DLLExport int MQTTClient_subscribe(MQTTClient handle, const char *topic, int qos)
DLLExport int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char *const *topic)
const char * keyStore
Definition: MQTTClient.h:519
DLLExport int MQTTClient_unsubscribe(MQTTClient handle, const char *topic)
int retained
Definition: MQTTClient.h:287
int enableServerCertAuth
Definition: MQTTClient.h:539
int len
Definition: MQTTClient.h:482
DLLExport int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout)
const char * value
Definition: MQTTClient.h:716
DLLExport int MQTTClient_setCallbacks(MQTTClient handle, void *context, MQTTClient_connectionLost *cl, MQTTClient_messageArrived *ma, MQTTClient_deliveryComplete *dc)
DLLExport void MQTTClient_global_init(MQTTClient_init_options *inits)
int cleansession
Definition: MQTTClient.h:622
int do_openssl_init
Definition: MQTTClient.h:210
This structure represents a persistent data store, used to store outbound and inbound messages...
int struct_version
Definition: MQTTClient.h:465
void * payload
Definition: MQTTClient.h:254
DLLExport int MQTTClient_getPendingDeliveryTokens(MQTTClient handle, MQTTClient_deliveryToken **tokens)
int MQTTClient_messageArrived(void *context, char *topicName, int topicLen, MQTTClient_message *message)
Definition: MQTTClient.h:329
Definition: MQTTClient.h:713
const char * CApath
Definition: MQTTClient.h:559