1LIBMOSQUITTO(3)                  Library calls                 LIBMOSQUITTO(3)
2
3
4

NAME

6       libmosquitto - MQTT version 3.1.1 client library
7

DESCRIPTION

9       This is an overview of how to use libmosquitto to create MQTT aware
10       client programs. There may be separate man pages on each of the
11       functions described here in the future. There is also a binding for
12       libmosquitto for C++ and a Python implementation. They are not
13       documented here but operate in a similar way.
14
15       This is fairly incomplete, please see mosquitto.h for a better
16       description of the functions.
17

LIBMOSQUITTO SYMBOL NAMES

19       All public functions in libmosquitto have the prefix "mosquitto_". Any
20       other functions defined in the source code are to be treated as private
21       functions and may change between any release. Do not use these
22       functions!
23

FUNCTIONS

25   Library version
26       int mosquitto_lib_version(int *major, int *minor, int *revision);
27
28       Obtain version information about the library. If any of major, minor or
29       revision are not NULL they will return the corresponding version
30       numbers. The return value is an integer representation of the complete
31       version number (e.g. 1009001 for 1.9.1) that can be used for
32       comparisons.
33
34   Library initialisation and cleanup
35       int mosquitto_lib_init(void);
36
37       int mosquitto_lib_cleanup(void);
38
39       Call mosquitto_lib_init() before using any of the other library
40       functions and mosquitto_lib_cleanup() after finishing with the library.
41
42   Client constructor/destructor
43       struct mosquitto *mosquitto_new(const char *id, bool clean_session,
44                                       void *userdata);
45
46       Create a new mosquitto client instance.
47
48       void mosquitto_destroy(struct mosquitto *mosq);
49
50       Use to free memory associated with a mosquitto client instance.
51
52       int mosquitto_reinitialise(struct mosquitto *mosq, const char *id,
53                                  bool clean_session, void *userdata);
54
55   Authentication and encryption
56       int mosquitto_username_pw_set(struct mosquitto *mosq,
57                                     const char *username,
58                                     const char *password);
59
60       int mosquitto_tls_set(struct mosquitto *mosq, const char *cafile,
61                             const char *capath, const char *certfile,
62                             const char *keyfile,
63                             int (*pw_callback)(char *buf, int size, int rwflag, void *userdata));
64
65       int mosquitto_tls_opts_set(struct mosquitto *mosq, int cert_reqs,
66                                  const char *tls_version,
67                                  const char *ciphers);
68
69       int mosquitto_tls_insecure_set(struct mosquitto *mosq, bool value);
70
71       int mosquitto_tls_psk_set(struct mosquitto *mosq, const char *psk,
72                                 const char *identity, const char *ciphers);
73
74   Wills
75       int mosquitto_will_set(struct mosquitto *mosq, const char *topic,
76                              int payloadlen, const void *payload, int qos,
77                              bool retain);
78
79       int mosquitto_will_clear(struct mosquitto *mosq);
80
81   Connect/disconnect
82       int mosquitto_connect(struct mosquitto *mosq, const char *host,
83                             int port, int keepalive);
84
85       int mosquitto_connect_bind(struct mosquitto *mosq, const char *host,
86                                  int port, int keepalive,
87                                  const char *bind_address);
88
89       int mosquitto_connect_async(struct mosquitto *mosq, const char *host,
90                                   int port, int keepalive);
91
92       int mosquitto_connect_bind_async(struct mosquitto *mosq,
93                                        const char *host, int port,
94                                        int keepalive,
95                                        const char *bind_address);
96
97       int mosquitto_reconnect(struct mosquitto *mosq);
98
99       int mosquitto_reconnect_async(struct mosquitto *mosq);
100
101       int mosquitto_disconnect(struct mosquitto *mosq);
102
103   Publish
104       int mosquitto_publish(struct mosquitto *mosq, int *mid,
105                             const char *topic, int payloadlen,
106                             const void *payload, int qos, bool retain);
107
108   Subscribe/unsubscribe
109       int mosquitto_subscribe(struct mosquitto *mosq, int *mid,
110                               const char *sub, int qos);
111
112       int mosquitto_unsubscribe(struct mosquitto *mosq, int *mid,
113                                 const char *sub);
114
115   Network loop
116       int mosquitto_loop(struct mosquitto *mosq, int timeout,
117                          int max_packets);
118
119       int mosquitto_loop_read(struct mosquitto *mosq, int max_packets);
120
121       int mosquitto_loop_write(struct mosquitto *mosq, int max_packets);
122
123       int mosquitto_loop_misc(struct mosquitto *mosq);
124
125       int mosquitto_loop_forever(struct mosquitto *mosq, int timeout,
126                                  int max_packets);
127
128       int mosquitto_socket(struct mosquitto *mosq);
129
130       bool mosquitto_want_write(struct mosquitto *mosq);
131
132   Threaded network loop
133       int mosquitto_loop_start(struct mosquitto *mosq);
134
135       int mosquitto_loop_stop(struct mosquitto *mosq, bool force);
136
137   Misc client functions
138       int mosquitto_max_inflight_messages_set(struct mosquitto *mosq,
139                                               unsigned int max_inflight_messages);
140
141       int mosquitto_reconnect_delay_set(struct mosquitto *mosq,
142                                         unsigned int reconnect_delay,
143                                         unsigned int reconnect_delay_max,
144                                         bool reconnect_exponential_backoff);
145
146       int mosquitto_user_data_set(struct mosquitto *mosq, void *userdata);
147
148   Callbacks
149       int mosquitto_connect_callback_set(struct mosquitto *mosq,
150                                          void (*on_connect)(struct mosquitto *, void *, int));
151
152       int mosquitto_disconnect_callback_set(struct mosquitto *mosq,
153                                             void (*on_disconnect)(struct mosquitto *, void *, int));
154
155       int mosquitto_publish_callback_set(struct mosquitto *mosq,
156                                          void (*on_publish)(struct mosquitto *, void *, int));
157
158       int mosquitto_message_callback_set(struct mosquitto *mosq,
159                                          void (*on_message)(struct mosquitto *, void *, const struct mosquitto_message *));
160
161       int mosquitto_subscribe_callback_set(struct mosquitto *mosq,
162                                            void (*on_subscribe)(struct mosquitto *, void *, int, int, const int *));
163
164       int mosquitto_unsubscribe_callback_set(struct mosquitto *mosq,
165                                              void (*on_unsubscribe)(struct mosquitto *, void *, int));
166
167       int mosquitto_log_callback_set(struct mosquitto *mosq,
168                                      void (*on_unsubscribe)(struct mosquitto *, void *, int, const char *));
169
170   Utility functions
171       const char *mosquitto_connack_string(int connack_code);
172
173       int mosquitto_message_copy(struct mosquitto_message *dst,
174                                  const struct mosquitto_message *src);
175
176       int mosquitto_message_free(struct mosquitto_message **message);
177
178       const char *mosquitto_strerror(int mosq_errno);
179
180       int mosquitto_sub_topic_tokenise(const char *subtopic, char ***topics,
181                                        int *count);
182
183       int mosquitto_sub_topic_tokens_free(char ***topics, int count);
184
185       int mosquitto_topic_matches_sub(const char *sub, const char *topic,
186                                       bool *result);
187
188   Helper functions
189       int mosquitto_subscribe_simple(struct mosquitto_message **message,
190                                      int msg_count, bool want_retained,
191                                      const char *topic, intqos,
192                                      const char *host, int port,
193                                      const char *client_id, int keepalive,
194                                      bool clean_session,
195                                      const char *username,
196                                      const char *password,
197                                      const struct libmosquitto_will *will,
198                                      const struct libmosquitto_tls *tls);
199
200       int
201                                        mosquitto_subscribe_callback(int (*callback)(struct mosquitto *, void *, const struct mosquitto_message *),
202                                        void *userdata, const char *topic,
203                                        int qos, const char *host, int port,
204                                        const char *client_id, int keepalive,
205                                        bool clean_session,
206                                        const char *username,
207                                        const char *password,
208                                        const struct libmosquitto_will *will,
209                                        const struct libmosquitto_tls *tls);
210

EXAMPLES

212           #include <stdio.h>
213           #include <mosquitto.h>
214
215           void my_message_callback(struct mosquitto *mosq, void *userdata, const struct mosquitto_message *message)
216           {
217                if(message->payloadlen){
218                     printf("%s %s\n", message->topic, message->payload);
219                }else{
220                     printf("%s (null)\n", message->topic);
221                }
222                fflush(stdout);
223           }
224
225           void my_connect_callback(struct mosquitto *mosq, void *userdata, int result)
226           {
227                int i;
228                if(!result){
229                     /* Subscribe to broker information topics on successful connect. */
230                     mosquitto_subscribe(mosq, NULL, "$SYS/#", 2);
231                }else{
232                     fprintf(stderr, "Connect failed\n");
233                }
234           }
235
236           void my_subscribe_callback(struct mosquitto *mosq, void *userdata, int mid, int qos_count, const int *granted_qos)
237           {
238                int i;
239
240                printf("Subscribed (mid: %d): %d", mid, granted_qos[0]);
241                for(i=1; i<qos_count; i++){
242                     printf(", %d", granted_qos[i]);
243                }
244                printf("\n");
245           }
246
247           void my_log_callback(struct mosquitto *mosq, void *userdata, int level, const char *str)
248           {
249                /* Pring all log messages regardless of level. */
250                printf("%s\n", str);
251           }
252
253           int main(int argc, char *argv[])
254           {
255                int i;
256                char *host = "localhost";
257                int port = 1883;
258                int keepalive = 60;
259                bool clean_session = true;
260                struct mosquitto *mosq = NULL;
261
262                mosquitto_lib_init();
263                mosq = mosquitto_new(NULL, clean_session, NULL);
264                if(!mosq){
265                     fprintf(stderr, "Error: Out of memory.\n");
266                     return 1;
267                }
268                mosquitto_log_callback_set(mosq, my_log_callback);
269                mosquitto_connect_callback_set(mosq, my_connect_callback);
270                mosquitto_message_callback_set(mosq, my_message_callback);
271                mosquitto_subscribe_callback_set(mosq, my_subscribe_callback);
272
273                if(mosquitto_connect(mosq, host, port, keepalive)){
274                     fprintf(stderr, "Unable to connect.\n");
275                     return 1;
276                }
277
278                mosquitto_loop_forever(mosq, -1, 1);
279
280                mosquitto_destroy(mosq);
281                mosquitto_lib_cleanup();
282                return 0;
283           }
284
285

SEE ALSO

287       mosquitto(8)mqtt(7)
288

AUTHOR

290       Roger Light <roger@atchoo.org>
291
292
293
294Mosquitto Project                 04/26/2019                   LIBMOSQUITTO(3)