Paho MQTT C Client Library
MQTTClient.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 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 #if defined(__cplusplus)
105  extern "C" {
106 #endif
107 #if !defined(MQTTCLIENT_H)
108 #define MQTTCLIENT_H
109 
110 #if defined(WIN32) || defined(WIN64)
111  #define DLLImport __declspec(dllimport)
112  #define DLLExport __declspec(dllexport)
113 #else
114  #define DLLImport extern
115  #define DLLExport __attribute__ ((visibility ("default")))
116 #endif
117 
118 #include <stdio.h>
120 
121 #if !defined(NO_PERSISTENCE)
122 #include "MQTTClientPersistence.h"
123 #endif
124 
129 #define MQTTCLIENT_SUCCESS 0
130 
134 #define MQTTCLIENT_FAILURE -1
135 
136 /* error code -2 is MQTTCLIENT_PERSISTENCE_ERROR */
137 
141 #define MQTTCLIENT_DISCONNECTED -3
142 
146 #define MQTTCLIENT_MAX_MESSAGES_INFLIGHT -4
147 
150 #define MQTTCLIENT_BAD_UTF8_STRING -5
151 
154 #define MQTTCLIENT_NULL_PARAMETER -6
155 
160 #define MQTTCLIENT_TOPICNAME_TRUNCATED -7
161 
165 #define MQTTCLIENT_BAD_STRUCTURE -8
166 
169 #define MQTTCLIENT_BAD_QOS -9
170 
173 #define MQTTCLIENT_SSL_NOT_SUPPORTED -10
174 
178 #define MQTTVERSION_DEFAULT 0
179 
182 #define MQTTVERSION_3_1 3
183 
186 #define MQTTVERSION_3_1_1 4
187 
190 #define MQTT_BAD_SUBSCRIBE 0x80
191 
195 typedef struct
196 {
198  char struct_id[4];
204 
205 #define MQTTClient_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }
206 
212 
217 typedef void* MQTTClient;
229 typedef int MQTTClient_token;
230 
237 typedef struct
238 {
240  char struct_id[4];
246  void* payload;
260  int qos;
279  int retained;
286  int dup;
290  int msgid;
292 
293 #define MQTTClient_message_initializer { {'M', 'Q', 'T', 'M'}, 0, 0, NULL, 0, 0, 0, 0 }
294 
321 typedef int MQTTClient_messageArrived(void* context, char* topicName, int topicLen, MQTTClient_message* message);
322 
344 
360 typedef void MQTTClient_connectionLost(void* context, char* cause);
361 
389 DLLExport int MQTTClient_setCallbacks(MQTTClient handle, void* context, MQTTClient_connectionLost* cl,
391 
392 
435 DLLExport int MQTTClient_create(MQTTClient* handle, const char* serverURI, const char* clientId,
436  int persistence_type, void* persistence_context);
437 
450 typedef struct
451 {
453  char struct_id[4];
459  const char* topicName;
461  const char* message;
465  int retained;
470  int qos;
472  struct
473  {
474  int len;
475  const void* data;
476  } payload;
478 
479 #define MQTTClient_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, {0, NULL} }
480 
493 typedef struct
494 {
496  char struct_id[4];
499 
501  const char* trustStore;
502 
506  const char* keyStore;
507 
511  const char* privateKey;
513  const char* privateKeyPassword;
514 
523  const char* enabledCipherSuites;
524 
527 
529 
530 #define MQTTClient_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 0, NULL, NULL, NULL, NULL, NULL, 1 }
531 
546 typedef struct
547 {
549  char struct_id[4];
599  int reliable;
611  const char* username;
617  const char* password;
645  char* const* serverURIs;
656  struct
657  {
658  const char* serverURI;
659  int MQTTVersion;
661  } returned;
665  struct {
666  int len;
667  const void* data;
668  } binarypwd;
670 
671 #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} }
672 
680 typedef struct
681 {
682  const char* name;
683  const char* value;
685 
692 
713 DLLExport int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions* options);
714 
733 DLLExport int MQTTClient_disconnect(MQTTClient handle, int timeout);
734 
742 DLLExport int MQTTClient_isConnected(MQTTClient handle);
743 
744 
745 /* Subscribe is synchronous. QoS list parameter is changed on return to granted QoSs.
746  Returns return code, MQTTCLIENT_SUCCESS == success, non-zero some sort of error (TBD) */
747 
761 DLLExport int MQTTClient_subscribe(MQTTClient handle, const char* topic, int qos);
762 
779 DLLExport int MQTTClient_subscribeMany(MQTTClient handle, int count, char* const* topic, int* qos);
780 
792 DLLExport int MQTTClient_unsubscribe(MQTTClient handle, const char* topic);
793 
805 DLLExport int MQTTClient_unsubscribeMany(MQTTClient handle, int count, char* const* topic);
806 
828 DLLExport int MQTTClient_publish(MQTTClient handle, const char* topicName, int payloadlen, void* payload, int qos, int retained,
849 DLLExport int MQTTClient_publishMessage(MQTTClient handle, const char* topicName, MQTTClient_message* msg, MQTTClient_deliveryToken* dt);
850 
851 
867 DLLExport int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout);
868 
869 
889 
896 DLLExport void MQTTClient_yield(void);
897 
929 DLLExport int MQTTClient_receive(MQTTClient handle, char** topicName, int* topicLen, MQTTClient_message** message,
930  unsigned long timeout);
931 
942 DLLExport void MQTTClient_freeMessage(MQTTClient_message** msg);
943 
952 DLLExport void MQTTClient_free(void* ptr);
953 
961 DLLExport void MQTTClient_destroy(MQTTClient* handle);
962 
963 #endif
964 #ifdef __cplusplus
965  }
966 #endif
967 
int MQTTVersion
Definition: MQTTClient.h:652
void * MQTTClient
Definition: MQTTClient.h:217
const char * message
Definition: MQTTClient.h:461
int struct_version
Definition: MQTTClient.h:557
const char * username
Definition: MQTTClient.h:611
DLLExport int MQTTClient_connect(MQTTClient handle, MQTTClient_connectOptions *options)
void MQTTClient_connectionLost(void *context, char *cause)
Definition: MQTTClient.h:360
int dup
Definition: MQTTClient.h:286
const char * enabledCipherSuites
Definition: MQTTClient.h:523
int struct_version
Definition: MQTTClient.h:242
int qos
Definition: MQTTClient.h:260
DLLExport void MQTTClient_free(void *ptr)
const char * password
Definition: MQTTClient.h:617
const char * serverURI
Definition: MQTTClient.h:658
int msgid
Definition: MQTTClient.h:290
int retained
Definition: MQTTClient.h:465
const void * data
Definition: MQTTClient.h:475
int retryInterval
Definition: MQTTClient.h:625
DLLExport int MQTTClient_subscribeMany(MQTTClient handle, int count, char *const *topic, int *qos)
int reliable
Definition: MQTTClient.h:599
Definition: MQTTClient.h:237
DLLExport void MQTTClient_freeMessage(MQTTClient_message **msg)
void MQTTClient_global_init(MQTTClient_init_options *inits)
int keepAliveInterval
Definition: MQTTClient.h:567
int payloadlen
Definition: MQTTClient.h:244
const char * topicName
Definition: MQTTClient.h:459
int connectTimeout
Definition: MQTTClient.h:621
Definition: MQTTClient.h:195
int struct_version
Definition: MQTTClient.h:498
DLLExport int MQTTClient_create(MQTTClient *handle, const char *serverURI, const char *clientId, int persistence_type, void *persistence_context)
const void * data
Definition: MQTTClient.h:667
DLLExport void MQTTClient_destroy(MQTTClient *handle)
Definition: MQTTClient.h:493
DLLExport MQTTClient_nameValue * MQTTClient_getVersionInfo(void)
int struct_version
Definition: MQTTClient.h:200
DLLExport int MQTTClient_publishMessage(MQTTClient handle, const char *topicName, MQTTClient_message *msg, MQTTClient_deliveryToken *dt)
int qos
Definition: MQTTClient.h:470
int len
Definition: MQTTClient.h:666
Definition: MQTTClient.h:450
DLLExport int MQTTClient_isConnected(MQTTClient handle)
const char * trustStore
Definition: MQTTClient.h:501
DLLExport void MQTTClient_yield(void)
int sessionPresent
Definition: MQTTClient.h:660
Definition: MQTTClient.h:546
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:682
MQTTClient_willOptions * will
Definition: MQTTClient.h:605
void MQTTClient_deliveryComplete(void *context, MQTTClient_deliveryToken dt)
Definition: MQTTClient.h:343
const char * privateKeyPassword
Definition: MQTTClient.h:513
int MQTTClient_deliveryToken
Definition: MQTTClient.h:228
char *const * serverURIs
Definition: MQTTClient.h:645
const char * privateKey
Definition: MQTTClient.h:511
MQTTClient_SSLOptions * ssl
Definition: MQTTClient.h:630
DLLExport int MQTTClient_receive(MQTTClient handle, char **topicName, int *topicLen, MQTTClient_message **message, unsigned long timeout)
int MQTTClient_token
Definition: MQTTClient.h:229
int serverURIcount
Definition: MQTTClient.h:634
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:506
DLLExport int MQTTClient_unsubscribe(MQTTClient handle, const char *topic)
int retained
Definition: MQTTClient.h:279
int enableServerCertAuth
Definition: MQTTClient.h:526
int len
Definition: MQTTClient.h:474
DLLExport int MQTTClient_waitForCompletion(MQTTClient handle, MQTTClient_deliveryToken dt, unsigned long timeout)
const char * value
Definition: MQTTClient.h:683
DLLExport int MQTTClient_setCallbacks(MQTTClient handle, void *context, MQTTClient_connectionLost *cl, MQTTClient_messageArrived *ma, MQTTClient_deliveryComplete *dc)
int cleansession
Definition: MQTTClient.h:589
int do_openssl_init
Definition: MQTTClient.h:202
This structure represents a persistent data store, used to store outbound and inbound messages...
int struct_version
Definition: MQTTClient.h:457
void * payload
Definition: MQTTClient.h:246
DLLExport int MQTTClient_getPendingDeliveryTokens(MQTTClient handle, MQTTClient_deliveryToken **tokens)
int MQTTClient_messageArrived(void *context, char *topicName, int topicLen, MQTTClient_message *message)
Definition: MQTTClient.h:321
Definition: MQTTClient.h:680