-
Notifications
You must be signed in to change notification settings - Fork 2.4k
/
mosquitto.h
1431 lines (1361 loc) · 52.6 KB
/
mosquitto.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
Copyright (c) 2010-2014 Roger Light <[email protected]>
All rights reserved. This program and the accompanying materials
are made available under the terms of the Eclipse Public License v1.0
and Eclipse Distribution License v1.0 which accompany this distribution.
The Eclipse Public License is available at
http:https://www.eclipse.org/legal/epl-v10.html
and the Eclipse Distribution License is available at
http:https://www.eclipse.org/org/documents/edl-v10.php.
Contributors:
Roger Light - initial implementation and documentation.
*/
#ifndef _MOSQUITTO_H_
#define _MOSQUITTO_H_
#ifdef __cplusplus
extern "C" {
#endif
#if defined(WIN32) && !defined(WITH_BROKER)
# ifdef libmosquitto_EXPORTS
# define libmosq_EXPORT __declspec(dllexport)
# else
# define libmosq_EXPORT __declspec(dllimport)
# endif
#else
# define libmosq_EXPORT
#endif
#ifdef WIN32
# ifndef __cplusplus
# define bool char
# define true 1
# define false 0
# endif
#else
# ifndef __cplusplus
# include <stdbool.h>
# endif
#endif
#define LIBMOSQUITTO_MAJOR 1
#define LIBMOSQUITTO_MINOR 4
#define LIBMOSQUITTO_REVISION 0
/* LIBMOSQUITTO_VERSION_NUMBER looks like 1002001 for e.g. version 1.2.1. */
#define LIBMOSQUITTO_VERSION_NUMBER (LIBMOSQUITTO_MAJOR*1000000+LIBMOSQUITTO_MINOR*1000+LIBMOSQUITTO_REVISION)
/* Log types */
#define MOSQ_LOG_NONE 0x00
#define MOSQ_LOG_INFO 0x01
#define MOSQ_LOG_NOTICE 0x02
#define MOSQ_LOG_WARNING 0x04
#define MOSQ_LOG_ERR 0x08
#define MOSQ_LOG_DEBUG 0x10
#define MOSQ_LOG_SUBSCRIBE 0x20
#define MOSQ_LOG_UNSUBSCRIBE 0x40
#define MOSQ_LOG_ALL 0xFFFF
/* Error values */
enum mosq_err_t {
MOSQ_ERR_CONN_PENDING = -1,
MOSQ_ERR_SUCCESS = 0,
MOSQ_ERR_NOMEM = 1,
MOSQ_ERR_PROTOCOL = 2,
MOSQ_ERR_INVAL = 3,
MOSQ_ERR_NO_CONN = 4,
MOSQ_ERR_CONN_REFUSED = 5,
MOSQ_ERR_NOT_FOUND = 6,
MOSQ_ERR_CONN_LOST = 7,
MOSQ_ERR_TLS = 8,
MOSQ_ERR_PAYLOAD_SIZE = 9,
MOSQ_ERR_NOT_SUPPORTED = 10,
MOSQ_ERR_AUTH = 11,
MOSQ_ERR_ACL_DENIED = 12,
MOSQ_ERR_UNKNOWN = 13,
MOSQ_ERR_ERRNO = 14,
MOSQ_ERR_EAI = 15
};
/* MQTT specification restricts client ids to a maximum of 23 characters */
#define MOSQ_MQTT_ID_MAX_LENGTH 23
struct mosquitto_message{
int mid;
char *topic;
void *payload;
int payloadlen;
int qos;
bool retain;
};
struct mosquitto;
/*
* Topic: Threads
* libmosquitto provides thread safe operation, with the exception of
* <mosquitto_lib_init> which is not thread safe.
*
* If your application uses threads you must use <mosquitto_threaded_set> to
* tell the library this is the case, otherwise it makes some optimisations
* for the single threaded case that may result in unexpected behaviour for
* the multi threaded case.
*/
/***************************************************
* Important note
*
* The following functions that deal with network operations will return
* MOSQ_ERR_SUCCESS on success, but this does not mean that the operation has
* taken place. An attempt will be made to write the network data, but if the
* socket is not available for writing at that time then the packet will not be
* sent. To ensure the packet is sent, call mosquitto_loop() (which must also
* be called to process incoming network data).
* This is especially important when disconnecting a client that has a will. If
* the broker does not receive the DISCONNECT command, it will assume that the
* client has disconnected unexpectedly and send the will.
*
* mosquitto_connect()
* mosquitto_disconnect()
* mosquitto_subscribe()
* mosquitto_unsubscribe()
* mosquitto_publish()
***************************************************/
/*
* Function: mosquitto_lib_version
*
* Can be used to obtain version information for the mosquitto library.
* This allows the application to compare the library version against the
* version it was compiled against by using the LIBMOSQUITTO_MAJOR,
* LIBMOSQUITTO_MINOR and LIBMOSQUITTO_REVISION defines.
*
* Parameters:
* major - an integer pointer. If not NULL, the major version of the
* library will be returned in this variable.
* minor - an integer pointer. If not NULL, the minor version of the
* library will be returned in this variable.
* revision - an integer pointer. If not NULL, the revision of the library will
* be returned in this variable.
*
* Returns:
* LIBMOSQUITTO_VERSION_NUMBER, which is a unique number based on the major,
* minor and revision values.
* See Also:
* <mosquitto_lib_cleanup>, <mosquitto_lib_init>
*/
libmosq_EXPORT int mosquitto_lib_version(int *major, int *minor, int *revision);
/*
* Function: mosquitto_lib_init
*
* Must be called before any other mosquitto functions.
*
* This function is *not* thread safe.
*
* Returns:
* MOSQ_ERR_SUCCESS - always
*
* See Also:
* <mosquitto_lib_cleanup>, <mosquitto_lib_version>
*/
libmosq_EXPORT int mosquitto_lib_init(void);
/*
* Function: mosquitto_lib_cleanup
*
* Call to free resources associated with the library.
*
* Returns:
* MOSQ_ERR_SUCCESS - always
*
* See Also:
* <mosquitto_lib_init>, <mosquitto_lib_version>
*/
libmosq_EXPORT int mosquitto_lib_cleanup(void);
/*
* Function: mosquitto_new
*
* Create a new mosquitto client instance.
*
* Parameters:
* id - String to use as the client id. If NULL, a random client id
* will be generated. If id is NULL, clean_session must be true.
* clean_session - set to true to instruct the broker to clean all messages
* and subscriptions on disconnect, false to instruct it to
* keep them. See the man page mqtt(7) for more details.
* Note that a client will never discard its own outgoing
* messages on disconnect. Calling <mosquitto_connect> or
* <mosquitto_reconnect> will cause the messages to be resent.
* Use <mosquitto_reinitialise> to reset a client to its
* original state.
* Must be set to true if the id parameter is NULL.
* obj - A user pointer that will be passed as an argument to any
* callbacks that are specified.
*
* Returns:
* Pointer to a struct mosquitto on success.
* NULL on failure. Interrogate errno to determine the cause for the failure:
* - ENOMEM on out of memory.
* - EINVAL on invalid input parameters.
*
* See Also:
* <mosquitto_reinitialise>, <mosquitto_destroy>, <mosquitto_user_data_set>
*/
libmosq_EXPORT struct mosquitto *mosquitto_new(const char *id, bool clean_session, void *obj);
/*
* Function: mosquitto_destroy
*
* Use to free memory associated with a mosquitto client instance.
*
* Parameters:
* mosq - a struct mosquitto pointer to free.
*
* See Also:
* <mosquitto_new>, <mosquitto_reinitialise>
*/
libmosq_EXPORT void mosquitto_destroy(struct mosquitto *mosq);
/*
* Function: mosquitto_reinitialise
*
* This function allows an existing mosquitto client to be reused. Call on a
* mosquitto instance to close any open network connections, free memory
* and reinitialise the client with the new parameters. The end result is the
* same as the output of <mosquitto_new>.
*
* Parameters:
* mosq - a valid mosquitto instance.
* id - string to use as the client id. If NULL, a random client id
* will be generated. If id is NULL, clean_session must be true.
* clean_session - set to true to instruct the broker to clean all messages
* and subscriptions on disconnect, false to instruct it to
* keep them. See the man page mqtt(7) for more details.
* Must be set to true if the id parameter is NULL.
* obj - A user pointer that will be passed as an argument to any
* callbacks that are specified.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
*
* See Also:
* <mosquitto_new>, <mosquitto_destroy>
*/
libmosq_EXPORT int mosquitto_reinitialise(struct mosquitto *mosq, const char *id, bool clean_session, void *obj);
/*
* Function: mosquitto_will_set
*
* Configure will information for a mosquitto instance. By default, clients do
* not have a will. This must be called before calling <mosquitto_connect>.
*
* Parameters:
* mosq - a valid mosquitto instance.
* topic - the topic on which to publish the will.
* payloadlen - the size of the payload (bytes). Valid values are between 0 and
* 268,435,455.
* payload - pointer to the data to send. If payloadlen > 0 this must be a
* valid memory location.
* qos - integer value 0, 1 or 2 indicating the Quality of Service to be
* used for the will.
* retain - set to true to make the will a retained message.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
* MOSQ_ERR_PAYLOAD_SIZE - if payloadlen is too large.
*/
libmosq_EXPORT int mosquitto_will_set(struct mosquitto *mosq, const char *topic, int payloadlen, const void *payload, int qos, bool retain);
/*
* Function: mosquitto_will_clear
*
* Remove a previously configured will. This must be called before calling
* <mosquitto_connect>.
*
* Parameters:
* mosq - a valid mosquitto instance.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
*/
libmosq_EXPORT int mosquitto_will_clear(struct mosquitto *mosq);
/*
* Function: mosquitto_username_pw_set
*
* Configure username and password for a mosquitton instance. This is only
* supported by brokers that implement the MQTT spec v3.1. By default, no
* username or password will be sent.
* If username is NULL, the password argument is ignored.
* This must be called before calling mosquitto_connect().
*
* This is must be called before calling <mosquitto_connect>.
*
* Parameters:
* mosq - a valid mosquitto instance.
* username - the username to send as a string, or NULL to disable
* authentication.
* password - the password to send as a string. Set to NULL when username is
* valid in order to send just a username.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
*/
libmosq_EXPORT int mosquitto_username_pw_set(struct mosquitto *mosq, const char *username, const char *password);
/*
* Function: mosquitto_connect
*
* Connect to an MQTT broker.
*
* Parameters:
* mosq - a valid mosquitto instance.
* host - the hostname or ip address of the broker to connect to.
* port - the network port to connect to. Usually 1883.
* keepalive - the number of seconds after which the broker should send a PING
* message to the client if no other messages have been exchanged
* in that time.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_ERRNO - if a system call returned an error. The variable errno
* contains the error code, even on Windows.
* Use strerror_r() where available or FormatMessage() on
* Windows.
*
* See Also:
* <mosquitto_connect_bind>, <mosquitto_connect_async>, <mosquitto_reconnect>, <mosquitto_disconnect>, <mosquitto_tls_set>
*/
libmosq_EXPORT int mosquitto_connect(struct mosquitto *mosq, const char *host, int port, int keepalive);
/*
* Function: mosquitto_connect_bind
*
* Connect to an MQTT broker. This extends the functionality of
* <mosquitto_connect> by adding the bind_address parameter. Use this function
* if you need to restrict network communication over a particular interface.
*
* Parameters:
* mosq - a valid mosquitto instance.
* host - the hostname or ip address of the broker to connect to.
* port - the network port to connect to. Usually 1883.
* keepalive - the number of seconds after which the broker should send a PING
* message to the client if no other messages have been exchanged
* in that time.
* bind_address - the hostname or ip address of the local network interface to
* bind to.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_ERRNO - if a system call returned an error. The variable errno
* contains the error code, even on Windows.
* Use strerror_r() where available or FormatMessage() on
* Windows.
*
* See Also:
* <mosquitto_connect>, <mosquitto_connect_async>, <mosquitto_connect_bind_async>
*/
libmosq_EXPORT int mosquitto_connect_bind(struct mosquitto *mosq, const char *host, int port, int keepalive, const char *bind_address);
/*
* Function: mosquitto_connect_async
*
* Connect to an MQTT broker. This is a non-blocking call. If you use
* <mosquitto_connect_async> your client must use the threaded interface
* <mosquitto_loop_start>. If you need to use <mosquitto_loop>, you must use
* <mosquitto_connect> to connect the client.
*
* May be called before or after <mosquitto_loop_start>.
*
* Parameters:
* mosq - a valid mosquitto instance.
* host - the hostname or ip address of the broker to connect to.
* port - the network port to connect to. Usually 1883.
* keepalive - the number of seconds after which the broker should send a PING
* message to the client if no other messages have been exchanged
* in that time.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_ERRNO - if a system call returned an error. The variable errno
* contains the error code, even on Windows.
* Use strerror_r() where available or FormatMessage() on
* Windows.
*
* See Also:
* <mosquitto_connect_bind_async>, <mosquitto_connect>, <mosquitto_reconnect>, <mosquitto_disconnect>, <mosquitto_tls_set>
*/
libmosq_EXPORT int mosquitto_connect_async(struct mosquitto *mosq, const char *host, int port, int keepalive);
/*
* Function: mosquitto_connect_async
*
* Connect to an MQTT broker. This is a non-blocking call. If you use
* <mosquitto_connect_async> your client must use the threaded interface
* <mosquitto_loop_start>. If you need to use <mosquitto_loop>, you must use
* <mosquitto_connect> to connect the client.
*
* This extends the functionality of <mosquitto_connect_async> by adding the
* bind_address parameter. Use this function if you need to restrict network
* communication over a particular interface.
*
* May be called before or after <mosquitto_loop_start>.
*
* Parameters:
* mosq - a valid mosquitto instance.
* host - the hostname or ip address of the broker to connect to.
* port - the network port to connect to. Usually 1883.
* keepalive - the number of seconds after which the broker should send a PING
* message to the client if no other messages have been exchanged
* in that time.
* bind_address - the hostname or ip address of the local network interface to
* bind to.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_ERRNO - if a system call returned an error. The variable errno
* contains the error code, even on Windows.
* Use strerror_r() where available or FormatMessage() on
* Windows.
*
* See Also:
* <mosquitto_connect_async>, <mosquitto_connect>, <mosquitto_connect_bind>
*/
libmosq_EXPORT int mosquitto_connect_bind_async(struct mosquitto *mosq, const char *host, int port, int keepalive, const char *bind_address);
/*
* Function: mosquitto_connect_srv
*
* Connect to an MQTT broker. This is a non-blocking call. If you use
* <mosquitto_connect_async> your client must use the threaded interface
* <mosquitto_loop_start>. If you need to use <mosquitto_loop>, you must use
* <mosquitto_connect> to connect the client.
*
* This extends the functionality of <mosquitto_connect_async> by adding the
* bind_address parameter. Use this function if you need to restrict network
* communication over a particular interface.
*
* May be called before or after <mosquitto_loop_start>.
*
* Parameters:
* mosq - a valid mosquitto instance.
* host - the hostname or ip address of the broker to connect to.
* keepalive - the number of seconds after which the broker should send a PING
* message to the client if no other messages have been exchanged
* in that time.
* bind_address - the hostname or ip address of the local network interface to
* bind to.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_ERRNO - if a system call returned an error. The variable errno
* contains the error code, even on Windows.
* Use strerror_r() where available or FormatMessage() on
* Windows.
*
* See Also:
* <mosquitto_connect_async>, <mosquitto_connect>, <mosquitto_connect_bind>
*/
libmosq_EXPORT int mosquitto_connect_srv(struct mosquitto *mosq, const char *host, int keepalive, const char *bind_address);
/*
* Function: mosquitto_reconnect
*
* Reconnect to a broker.
*
* This function provides an easy way of reconnecting to a broker after a
* connection has been lost. It uses the values that were provided in the
* <mosquitto_connect> call. It must not be called before
* <mosquitto_connect>.
*
* Parameters:
* mosq - a valid mosquitto instance.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_ERRNO - if a system call returned an error. The variable errno
* contains the error code, even on Windows.
* Use strerror_r() where available or FormatMessage() on
* Windows.
*
* See Also:
* <mosquitto_connect>, <mosquitto_disconnect>, <mosquitto_reconnect_async>
*/
libmosq_EXPORT int mosquitto_reconnect(struct mosquitto *mosq);
/*
* Function: mosquitto_reconnect_async
*
* Reconnect to a broker. Non blocking version of <mosquitto_reconnect>.
*
* This function provides an easy way of reconnecting to a broker after a
* connection has been lost. It uses the values that were provided in the
* <mosquitto_connect> or <mosquitto_connect_async> calls. It must not be
* called before <mosquitto_connect>.
*
* Parameters:
* mosq - a valid mosquitto instance.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_ERRNO - if a system call returned an error. The variable errno
* contains the error code, even on Windows.
* Use strerror_r() where available or FormatMessage() on
* Windows.
*
* See Also:
* <mosquitto_connect>, <mosquitto_disconnect>
*/
libmosq_EXPORT int mosquitto_reconnect_async(struct mosquitto *mosq);
/*
* Function: mosquitto_disconnect
*
* Disconnect from the broker.
*
* Parameters:
* mosq - a valid mosquitto instance.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NO_CONN - if the client isn't connected to a broker.
*/
libmosq_EXPORT int mosquitto_disconnect(struct mosquitto *mosq);
/*
* Function: mosquitto_publish
*
* Publish a message on a given topic.
*
* Parameters:
* mosq - a valid mosquitto instance.
* mid - pointer to an int. If not NULL, the function will set this
* to the message id of this particular message. This can be then
* used with the publish callback to determine when the message
* has been sent.
* Note that although the MQTT protocol doesn't use message ids
* for messages with QoS=0, libmosquitto assigns them message ids
* so they can be tracked with this parameter.
* payloadlen - the size of the payload (bytes). Valid values are between 0 and
* 268,435,455.
* payload - pointer to the data to send. If payloadlen > 0 this must be a
* valid memory location.
* qos - integer value 0, 1 or 2 indicating the Quality of Service to be
* used for the message.
* retain - set to true to make the message retained.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
* MOSQ_ERR_NO_CONN - if the client isn't connected to a broker.
* MOSQ_ERR_PROTOCOL - if there is a protocol error communicating with the
* broker.
* MOSQ_ERR_PAYLOAD_SIZE - if payloadlen is too large.
*
* See Also:
* <mosquitto_max_inflight_messages_set>
*/
libmosq_EXPORT int mosquitto_publish(struct mosquitto *mosq, int *mid, const char *topic, int payloadlen, const void *payload, int qos, bool retain);
/*
* Function: mosquitto_subscribe
*
* Subscribe to a topic.
*
* Parameters:
* mosq - a valid mosquitto instance.
* mid - a pointer to an int. If not NULL, the function will set this to
* the message id of this particular message. This can be then used
* with the subscribe callback to determine when the message has been
* sent.
* sub - the subscription pattern.
* qos - the requested Quality of Service for this subscription.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
* MOSQ_ERR_NO_CONN - if the client isn't connected to a broker.
*/
libmosq_EXPORT int mosquitto_subscribe(struct mosquitto *mosq, int *mid, const char *sub, int qos);
/*
* Function: mosquitto_unsubscribe
*
* Unsubscribe from a topic.
*
* Parameters:
* mosq - a valid mosquitto instance.
* mid - a pointer to an int. If not NULL, the function will set this to
* the message id of this particular message. This can be then used
* with the unsubscribe callback to determine when the message has been
* sent.
* sub - the unsubscription pattern.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
* MOSQ_ERR_NO_CONN - if the client isn't connected to a broker.
*/
libmosq_EXPORT int mosquitto_unsubscribe(struct mosquitto *mosq, int *mid, const char *sub);
/*
* Function: mosquitto_message_copy
*
* Copy the contents of a mosquitto message to another message.
* Useful for preserving a message received in the on_message() callback.
*
* Parameters:
* dst - a pointer to a valid mosquitto_message struct to copy to.
* src - a pointer to a valid mosquitto_message struct to copy from.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
*
* See Also:
* <mosquitto_message_free>
*/
libmosq_EXPORT int mosquitto_message_copy(struct mosquitto_message *dst, const struct mosquitto_message *src);
/*
* Function: mosquitto_message_free
*
* Completely free a mosquitto_message struct.
*
* Parameters:
* message - pointer to a mosquitto_message pointer to free.
*
* See Also:
* <mosquitto_message_copy>
*/
libmosq_EXPORT void mosquitto_message_free(struct mosquitto_message **message);
/*
* Function: mosquitto_loop
*
* The main network loop for the client. You must call this frequently in order
* to keep communications between the client and broker working. If incoming
* data is present it will then be processed. Outgoing commands, from e.g.
* <mosquitto_publish>, are normally sent immediately that their function is
* called, but this is not always possible. <mosquitto_loop> will also attempt
* to send any remaining outgoing messages, which also includes commands that
* are part of the flow for messages with QoS>0.
*
* An alternative approach is to use <mosquitto_loop_start> to run the client
* loop in its own thread.
*
* This calls select() to monitor the client network socket. If you want to
* integrate mosquitto client operation with your own select() call, use
* <mosquitto_socket>, <mosquitto_loop_read>, <mosquitto_loop_write> and
* <mosquitto_loop_misc>.
*
* Threads:
*
* Parameters:
* mosq - a valid mosquitto instance.
* timeout - Maximum number of milliseconds to wait for network activity
* in the select() call before timing out. Set to 0 for instant
* return. Set negative to use the default of 1000ms.
* max_packets - this parameter is currently unused and should be set to 1 for
* future compatibility.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
* MOSQ_ERR_NO_CONN - if the client isn't connected to a broker.
* MOSQ_ERR_CONN_LOST - if the connection to the broker was lost.
* MOSQ_ERR_PROTOCOL - if there is a protocol error communicating with the
* broker.
* MOSQ_ERR_ERRNO - if a system call returned an error. The variable errno
* contains the error code, even on Windows.
* Use strerror_r() where available or FormatMessage() on
* Windows.
* See Also:
* <mosquitto_loop_forever>, <mosquitto_loop_start>, <mosquitto_loop_stop>
*/
libmosq_EXPORT int mosquitto_loop(struct mosquitto *mosq, int timeout, int max_packets);
/*
* Function: mosquitto_loop_forever
*
* This function call loop() for you in an infinite blocking loop. It is useful
* for the case where you only want to run the MQTT client loop in your
* program.
*
* It handles reconnecting in case server connection is lost. If you call
* mosquitto_disconnect() in a callback it will return.
*
* Parameters:
* mosq - a valid mosquitto instance.
* timeout - Maximum number of milliseconds to wait for network activity
* in the select() call before timing out. Set to 0 for instant
* return. Set negative to use the default of 1000ms.
* max_packets - this parameter is currently unused and should be set to 1 for
* future compatibility.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
* MOSQ_ERR_NO_CONN - if the client isn't connected to a broker.
* MOSQ_ERR_CONN_LOST - if the connection to the broker was lost.
* MOSQ_ERR_PROTOCOL - if there is a protocol error communicating with the
* broker.
* MOSQ_ERR_ERRNO - if a system call returned an error. The variable errno
* contains the error code, even on Windows.
* Use strerror_r() where available or FormatMessage() on
* Windows.
*
* See Also:
* <mosquitto_loop>, <mosquitto_loop_start>
*/
libmosq_EXPORT int mosquitto_loop_forever(struct mosquitto *mosq, int timeout, int max_packets);
/*
* Function: mosquitto_loop_start
*
* This is part of the threaded client interface. Call this once to start a new
* thread to process network traffic. This provides an alternative to
* repeatedly calling <mosquitto_loop> yourself.
*
* Parameters:
* mosq - a valid mosquitto instance.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOT_SUPPORTED - if thread support is not available.
*
* See Also:
* <mosquitto_connect_async>, <mosquitto_loop>, <mosquitto_loop_forever>, <mosquitto_loop_stop>
*/
libmosq_EXPORT int mosquitto_loop_start(struct mosquitto *mosq);
/*
* Function: mosquitto_loop_stop
*
* This is part of the threaded client interface. Call this once to stop the
* network thread previously created with <mosquitto_loop_start>. This call
* will block until the network thread finishes. For the network thread to end,
* you must have previously called <mosquitto_disconnect> or have set the force
* parameter to true.
*
* Parameters:
* mosq - a valid mosquitto instance.
* force - set to true to force thread cancellation. If false,
* <mosquitto_disconnect> must have already been called.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOT_SUPPORTED - if thread support is not available.
*
* See Also:
* <mosquitto_loop>, <mosquitto_loop_start>
*/
libmosq_EXPORT int mosquitto_loop_stop(struct mosquitto *mosq, bool force);
/*
* Function: mosquitto_socket
*
* Return the socket handle for a mosquitto instance. Useful if you want to
* include a mosquitto client in your own select() calls.
*
* Parameters:
* mosq - a valid mosquitto instance.
*
* Returns:
* The socket for the mosquitto client or -1 on failure.
*/
libmosq_EXPORT int mosquitto_socket(struct mosquitto *mosq);
/*
* Function: mosquitto_loop_read
*
* Carry out network read operations.
* This should only be used if you are not using mosquitto_loop() and are
* monitoring the client network socket for activity yourself.
*
* Parameters:
* mosq - a valid mosquitto instance.
* max_packets - this parameter is currently unused and should be set to 1 for
* future compatibility.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
* MOSQ_ERR_NO_CONN - if the client isn't connected to a broker.
* MOSQ_ERR_CONN_LOST - if the connection to the broker was lost.
* MOSQ_ERR_PROTOCOL - if there is a protocol error communicating with the
* broker.
* MOSQ_ERR_ERRNO - if a system call returned an error. The variable errno
* contains the error code, even on Windows.
* Use strerror_r() where available or FormatMessage() on
* Windows.
*
* See Also:
* <mosquitto_socket>, <mosquitto_loop_write>, <mosquitto_loop_misc>
*/
libmosq_EXPORT int mosquitto_loop_read(struct mosquitto *mosq, int max_packets);
/*
* Function: mosquitto_loop_write
*
* Carry out network write operations.
* This should only be used if you are not using mosquitto_loop() and are
* monitoring the client network socket for activity yourself.
*
* Parameters:
* mosq - a valid mosquitto instance.
* max_packets - this parameter is currently unused and should be set to 1 for
* future compatibility.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
* MOSQ_ERR_NO_CONN - if the client isn't connected to a broker.
* MOSQ_ERR_CONN_LOST - if the connection to the broker was lost.
* MOSQ_ERR_PROTOCOL - if there is a protocol error communicating with the
* broker.
* MOSQ_ERR_ERRNO - if a system call returned an error. The variable errno
* contains the error code, even on Windows.
* Use strerror_r() where available or FormatMessage() on
* Windows.
*
* See Also:
* <mosquitto_socket>, <mosquitto_loop_read>, <mosquitto_loop_misc>, <mosquitto_want_write>
*/
libmosq_EXPORT int mosquitto_loop_write(struct mosquitto *mosq, int max_packets);
/*
* Function: mosquitto_loop_misc
*
* Carry out miscellaneous operations required as part of the network loop.
* This should only be used if you are not using mosquitto_loop() and are
* monitoring the client network socket for activity yourself.
*
* This function deals with handling PINGs and checking whether messages need
* to be retried, so should be called fairly frequently.
*
* Parameters:
* mosq - a valid mosquitto instance.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NO_CONN - if the client isn't connected to a broker.
*
* See Also:
* <mosquitto_socket>, <mosquitto_loop_read>, <mosquitto_loop_write>
*/
libmosq_EXPORT int mosquitto_loop_misc(struct mosquitto *mosq);
/*
* Function: mosquitto_want_write
*
* Returns true if there is data ready to be written on the socket.
*
* Parameters:
* mosq - a valid mosquitto instance.
*
* See Also:
* <mosquitto_socket>, <mosquitto_loop_read>, <mosquitto_loop_write>
*/
libmosq_EXPORT bool mosquitto_want_write(struct mosquitto *mosq);
/*
* Function: mosquitto_threaded_set
*
* Used to tell the library that your application is using threads, but not
* using <mosquitto_loop_start>. The library operates slightly differently when
* not in threaded mode in order to simplify its operation. If you are managing
* your own threads and do not use this function you will experience crashes
* due to race conditions.
*
* When using <mosquitto_loop_start>, this is set automatically.
*
* Parameters:
* mosq - a valid mosquitto instance.
* threaded - true if your application is using threads, false otherwise.
*/
libmosq_EXPORT int mosquitto_threaded_set(struct mosquitto *mosq, bool threaded);
/*
* Function: mosquitto_tls_set
*
* Configure the client for certificate based SSL/TLS support. Must be called
* before <mosquitto_connect>.
*
* Cannot be used in conjunction with <mosquitto_tls_psk_set>.
*
* Define the Certificate Authority certificates to be trusted (ie. the server
* certificate must be signed with one of these certificates) using cafile.
*
* If the server you are connecting to requires clients to provide a
* certificate, define certfile and keyfile with your client certificate and
* private key. If your private key is encrypted, provide a password callback
* function or you will have to enter the password at the command line.
*
* Parameters:
* mosq - a valid mosquitto instance.
* cafile - path to a file containing the PEM encoded trusted CA
* certificate files. Either cafile or capath must not be NULL.
* capath - path to a directory containing the PEM encoded trusted CA
* certificate files. See mosquitto.conf for more details on
* configuring this directory. Either cafile or capath must not
* be NULL.
* certfile - path to a file containing the PEM encoded certificate file
* for this client. If NULL, keyfile must also be NULL and no
* client certificate will be used.
* keyfile - path to a file containing the PEM encoded private key for
* this client. If NULL, certfile must also be NULL and no
* client certificate will be used.
* pw_callback - if keyfile is encrypted, set pw_callback to allow your client
* to pass the correct password for decryption. If set to NULL,
* the password must be entered on the command line.
* Your callback must write the password into "buf", which is
* "size" bytes long. The return value must be the length of the
* password. "userdata" will be set to the calling mosquitto
* instance.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
* MOSQ_ERR_NOMEM - if an out of memory condition occurred.
*
* See Also:
* <mosquitto_tls_opts_set>, <mosquitto_tls_psk_set>, <mosquitto_tls_insecure_set>
*/
libmosq_EXPORT int mosquitto_tls_set(struct mosquitto *mosq,
const char *cafile, const char *capath,
const char *certfile, const char *keyfile,
int (*pw_callback)(char *buf, int size, int rwflag, void *userdata));
/*
* Function: mosquitto_tls_insecure_set
*
* Configure verification of the server hostname in the server certificate. If
* value is set to true, it is impossible to guarantee that the host you are
* connecting to is not impersonating your server. This can be useful in
* initial server testing, but makes it possible for a malicious third party to
* impersonate your server through DNS spoofing, for example.
* Do not use this function in a real system. Setting value to true makes the
* connection encryption pointless.
* Must be called before <mosquitto_connect>.
*
* Parameters:
* mosq - a valid mosquitto instance.
* value - if set to false, the default, certificate hostname checking is
* performed. If set to true, no hostname checking is performed and
* the connection is insecure.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid.
*
* See Also:
* <mosquitto_tls_set>
*/
libmosq_EXPORT int mosquitto_tls_insecure_set(struct mosquitto *mosq, bool value);
/*
* Function: mosquitto_tls_opts_set
*