-
Notifications
You must be signed in to change notification settings - Fork 2.4k
/
mosquitto.h
3243 lines (3075 loc) · 122 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-2020 Roger Light <[email protected]>
All rights reserved. This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
and Eclipse Distribution License v1.0 which accompany this distribution.
The Eclipse Public License is available at
https://www.eclipse.org/legal/epl-2.0/
and the Eclipse Distribution License is available at
https://www.eclipse.org/org/documents/edl-v10.php.
SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
Contributors:
Roger Light - initial implementation and documentation.
*/
#ifndef MOSQUITTO_H
#define MOSQUITTO_H
/*
* File: mosquitto.h
*
* This header contains functions and definitions for use with libmosquitto, the Mosquitto client library.
*
* The definitions are also used in Mosquitto broker plugins, and some functions are available to plugins.
*/
#ifdef __cplusplus
extern "C" {
#endif
#ifdef WIN32
# ifdef mosquitto_EXPORTS
# define libmosq_EXPORT __declspec(dllexport)
# else
# ifndef LIBMOSQUITTO_STATIC
# ifdef libmosquitto_EXPORTS
# define libmosq_EXPORT __declspec(dllexport)
# else
# define libmosq_EXPORT __declspec(dllimport)
# endif
# else
# define libmosq_EXPORT
# endif
# endif
#else
# define libmosq_EXPORT
#endif
#if defined(_MSC_VER) && _MSC_VER < 1900 && !defined(bool)
# ifndef __cplusplus
# define bool char
# define true 1
# define false 0
# endif
#else
# ifndef __cplusplus
# include <stdbool.h>
# endif
#endif
#include <stddef.h>
#include <stdint.h>
#define LIBMOSQUITTO_MAJOR 2
#define LIBMOSQUITTO_MINOR 0
#define LIBMOSQUITTO_REVISION 14
/* 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 0
#define MOSQ_LOG_INFO (1<<0)
#define MOSQ_LOG_NOTICE (1<<1)
#define MOSQ_LOG_WARNING (1<<2)
#define MOSQ_LOG_ERR (1<<3)
#define MOSQ_LOG_DEBUG (1<<4)
#define MOSQ_LOG_SUBSCRIBE (1<<5)
#define MOSQ_LOG_UNSUBSCRIBE (1<<6)
#define MOSQ_LOG_WEBSOCKETS (1<<7)
#define MOSQ_LOG_INTERNAL 0x80000000U
#define MOSQ_LOG_ALL 0xFFFFFFFFU
/* Error values */
enum mosq_err_t {
MOSQ_ERR_AUTH_CONTINUE = -4,
MOSQ_ERR_NO_SUBSCRIBERS = -3,
MOSQ_ERR_SUB_EXISTS = -2,
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,
MOSQ_ERR_PROXY = 16,
MOSQ_ERR_PLUGIN_DEFER = 17,
MOSQ_ERR_MALFORMED_UTF8 = 18,
MOSQ_ERR_KEEPALIVE = 19,
MOSQ_ERR_LOOKUP = 20,
MOSQ_ERR_MALFORMED_PACKET = 21,
MOSQ_ERR_DUPLICATE_PROPERTY = 22,
MOSQ_ERR_TLS_HANDSHAKE = 23,
MOSQ_ERR_QOS_NOT_SUPPORTED = 24,
MOSQ_ERR_OVERSIZE_PACKET = 25,
MOSQ_ERR_OCSP = 26,
MOSQ_ERR_TIMEOUT = 27,
MOSQ_ERR_RETAIN_NOT_SUPPORTED = 28,
MOSQ_ERR_TOPIC_ALIAS_INVALID = 29,
MOSQ_ERR_ADMINISTRATIVE_ACTION = 30,
MOSQ_ERR_ALREADY_EXISTS = 31,
};
/* Option values */
enum mosq_opt_t {
MOSQ_OPT_PROTOCOL_VERSION = 1,
MOSQ_OPT_SSL_CTX = 2,
MOSQ_OPT_SSL_CTX_WITH_DEFAULTS = 3,
MOSQ_OPT_RECEIVE_MAXIMUM = 4,
MOSQ_OPT_SEND_MAXIMUM = 5,
MOSQ_OPT_TLS_KEYFORM = 6,
MOSQ_OPT_TLS_ENGINE = 7,
MOSQ_OPT_TLS_ENGINE_KPASS_SHA1 = 8,
MOSQ_OPT_TLS_OCSP_REQUIRED = 9,
MOSQ_OPT_TLS_ALPN = 10,
MOSQ_OPT_TCP_NODELAY = 11,
MOSQ_OPT_BIND_ADDRESS = 12,
MOSQ_OPT_TLS_USE_OS_CERTS = 13,
};
/* MQTT specification restricts client ids to a maximum of 23 characters */
#define MOSQ_MQTT_ID_MAX_LENGTH 23
#define MQTT_PROTOCOL_V31 3
#define MQTT_PROTOCOL_V311 4
#define MQTT_PROTOCOL_V5 5
struct mosquitto_message{
int mid;
char *topic;
void *payload;
int payloadlen;
int qos;
bool retain;
};
struct mosquitto;
typedef struct mqtt5__property mosquitto_property;
/*
* Topic: Threads
* libmosquitto provides thread safe operation, with the exception of
* <mosquitto_lib_init> which is not thread safe.
*
* If the library has been compiled without thread support it is *not*
* guaranteed to be 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()
***************************************************/
/* ======================================================================
*
* Section: Library version, init, and cleanup
*
* ====================================================================== */
/*
* 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 - on success.
* MOSQ_ERR_UNKNOWN - on Windows, if sockets couldn't be initialized.
*
* 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);
/* ======================================================================
*
* Section: Client creation, destruction, and reinitialisation
*
* ====================================================================== */
/*
* 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);
/* ======================================================================
*
* Section: Will
*
* ====================================================================== */
/*
* 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>.
*
* It is valid to use this function for clients using all MQTT protocol versions.
* If you need to set MQTT v5 Will properties, use <mosquitto_will_set_v5> instead.
*
* 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.
* MOSQ_ERR_MALFORMED_UTF8 - if the topic is not valid UTF-8.
*/
libmosq_EXPORT int mosquitto_will_set(struct mosquitto *mosq, const char *topic, int payloadlen, const void *payload, int qos, bool retain);
/*
* Function: mosquitto_will_set_v5
*
* Configure will information for a mosquitto instance, with attached
* properties. By default, clients do not have a will. This must be called
* before calling <mosquitto_connect>.
*
* If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument
* will be applied to the Will. For MQTT v3.1.1 and below, the `properties`
* argument will be ignored.
*
* Set your client to use MQTT v5 immediately after it is created:
*
* mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5);
*
* 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.
* properties - list of MQTT 5 properties. Can be NULL. On success only, the
* property list becomes the property of libmosquitto once this
* function is called and will be freed by the library. The
* property list must be freed by the application on error.
*
* 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.
* MOSQ_ERR_MALFORMED_UTF8 - if the topic is not valid UTF-8.
* MOSQ_ERR_NOT_SUPPORTED - if properties is not NULL and the client is not
* using MQTT v5
* MOSQ_ERR_PROTOCOL - if a property is invalid for use with wills.
* MOSQ_ERR_DUPLICATE_PROPERTY - if a property is duplicated where it is forbidden.
*/
libmosq_EXPORT int mosquitto_will_set_v5(struct mosquitto *mosq, const char *topic, int payloadlen, const void *payload, int qos, bool retain, mosquitto_property *properties);
/*
* 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);
/* ======================================================================
*
* Section: Username and password
*
* ====================================================================== */
/*
* Function: mosquitto_username_pw_set
*
* Configure username and password for a mosquitto instance. By default, no
* username or password will be sent. For v3.1 and v3.1.1 clients, if username
* is NULL, the password argument is ignored.
*
* 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);
/* ======================================================================
*
* Section: Connecting, reconnecting, disconnecting
*
* ====================================================================== */
/*
* Function: mosquitto_connect
*
* Connect to an MQTT broker.
*
* It is valid to use this function for clients using all MQTT protocol versions.
* If you need to set MQTT v5 CONNECT properties, use <mosquitto_connect_bind_v5>
* instead.
*
* 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, which could be any of:
* * mosq == NULL
* * host == NULL
* * port < 0
* * keepalive < 5
* 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. If you do not want to bind to a specific interface,
* set this to NULL.
*
* 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_bind_v5
*
* Connect to an MQTT broker. This extends the functionality of
* <mosquitto_connect> by adding the bind_address parameter and MQTT v5
* properties. Use this function if you need to restrict network communication
* over a particular interface.
*
* Use e.g. <mosquitto_property_add_string> and similar to create a list of
* properties, then attach them to this publish. Properties need freeing with
* <mosquitto_property_free_all>.
*
* If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument
* will be applied to the CONNECT message. For MQTT v3.1.1 and below, the
* `properties` argument will be ignored.
*
* Set your client to use MQTT v5 immediately after it is created:
*
* mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5);
*
* 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. If you do not want to bind to a specific interface,
* set this to NULL.
* properties - the MQTT 5 properties for the connect (not for the Will).
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid, which could be any of:
* * mosq == NULL
* * host == NULL
* * port < 0
* * keepalive < 5
* 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.
* MOSQ_ERR_DUPLICATE_PROPERTY - if a property is duplicated where it is forbidden.
* MOSQ_ERR_PROTOCOL - if any property is invalid for use with CONNECT.
*
* See Also:
* <mosquitto_connect>, <mosquitto_connect_async>, <mosquitto_connect_bind_async>
*/
libmosq_EXPORT int mosquitto_connect_bind_v5(struct mosquitto *mosq, const char *host, int port, int keepalive, const char *bind_address, const mosquitto_property *properties);
/*
* 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_bind_async
*
* Connect to an MQTT broker. This is a non-blocking call. If you use
* <mosquitto_connect_bind_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. If you do not want to bind to a specific interface,
* set this to NULL.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid, which could be any of:
* * mosq == NULL
* * host == NULL
* * port < 0
* * keepalive < 5
* 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.
*
* If you set `host` to `example.com`, then this call will attempt to retrieve
* the DNS SRV record for `_secure-mqtt._tcp.example.com` or
* `_mqtt._tcp.example.com` to discover which actual host to connect to.
*
* DNS SRV support is not usually compiled in to libmosquitto, use of this call
* is not recommended.
*
* Parameters:
* mosq - a valid mosquitto instance.
* host - the hostname to search for an SRV record.
* 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. If you do not want to bind to a specific interface,
* set this to NULL.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success.
* MOSQ_ERR_INVAL - if the input parameters were invalid, which could be any of:
* * mosq == NULL
* * host == NULL
* * port < 0
* * keepalive < 5
* 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.
* 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.
* 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.
*
* It is valid to use this function for clients using all MQTT protocol versions.
* If you need to set MQTT v5 DISCONNECT properties, use
* <mosquitto_disconnect_v5> instead.
*
* 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_disconnect_v5
*
* Disconnect from the broker, with attached MQTT properties.
*
* Use e.g. <mosquitto_property_add_string> and similar to create a list of
* properties, then attach them to this publish. Properties need freeing with
* <mosquitto_property_free_all>.
*
* If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument
* will be applied to the DISCONNECT message. For MQTT v3.1.1 and below, the
* `properties` argument will be ignored.
*
* Set your client to use MQTT v5 immediately after it is created:
*
* mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5);
*
* Parameters:
* mosq - a valid mosquitto instance.
* reason_code - the disconnect reason code.
* properties - a valid mosquitto_property list, or NULL.
*
* 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.
* MOSQ_ERR_DUPLICATE_PROPERTY - if a property is duplicated where it is forbidden.
* MOSQ_ERR_PROTOCOL - if any property is invalid for use with DISCONNECT.
*/
libmosq_EXPORT int mosquitto_disconnect_v5(struct mosquitto *mosq, int reason_code, const mosquitto_property *properties);
/* ======================================================================
*
* Section: Publishing, subscribing, unsubscribing
*
* ====================================================================== */
/*
* Function: mosquitto_publish
*
* Publish a message on a given topic.
*
* It is valid to use this function for clients using all MQTT protocol versions.
* If you need to set MQTT v5 PUBLISH properties, use <mosquitto_publish_v5>
* instead.
*
* 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.
* topic - null terminated string of the topic to publish to.
* 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.
* MOSQ_ERR_MALFORMED_UTF8 - if the topic is not valid UTF-8
* MOSQ_ERR_QOS_NOT_SUPPORTED - if the QoS is greater than that supported by
* the broker.
* MOSQ_ERR_OVERSIZE_PACKET - if the resulting packet would be larger than
* supported by the broker.
*
* 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_publish_v5
*
* Publish a message on a given topic, with attached MQTT properties.
*
* Use e.g. <mosquitto_property_add_string> and similar to create a list of
* properties, then attach them to this publish. Properties need freeing with
* <mosquitto_property_free_all>.
*
* If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument
* will be applied to the PUBLISH message. For MQTT v3.1.1 and below, the
* `properties` argument will be ignored.
*
* Set your client to use MQTT v5 immediately after it is created:
*
* mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5);
*
* 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.
* topic - null terminated string of the topic to publish to.
* 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.
* properties - a valid mosquitto_property list, or NULL.
*
* 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.
* MOSQ_ERR_MALFORMED_UTF8 - if the topic is not valid UTF-8
* MOSQ_ERR_DUPLICATE_PROPERTY - if a property is duplicated where it is forbidden.
* MOSQ_ERR_PROTOCOL - if any property is invalid for use with PUBLISH.
* MOSQ_ERR_QOS_NOT_SUPPORTED - if the QoS is greater than that supported by
* the broker.
* MOSQ_ERR_OVERSIZE_PACKET - if the resulting packet would be larger than
* supported by the broker.
*/
libmosq_EXPORT int mosquitto_publish_v5(
struct mosquitto *mosq,
int *mid,
const char *topic,
int payloadlen,
const void *payload,
int qos,
bool retain,
const mosquitto_property *properties);
/*
* Function: mosquitto_subscribe
*
* Subscribe to a topic.
*
* It is valid to use this function for clients using all MQTT protocol versions.
* If you need to set MQTT v5 SUBSCRIBE properties, use <mosquitto_subscribe_v5>
* instead.
*
* 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.
* MOSQ_ERR_MALFORMED_UTF8 - if the topic is not valid UTF-8
* MOSQ_ERR_OVERSIZE_PACKET - if the resulting packet would be larger than
* supported by the broker.
*/
libmosq_EXPORT int mosquitto_subscribe(struct mosquitto *mosq, int *mid, const char *sub, int qos);
/*
* Function: mosquitto_subscribe_v5
*
* Subscribe to a topic, with attached MQTT properties.
*
* Use e.g. <mosquitto_property_add_string> and similar to create a list of
* properties, then attach them to this publish. Properties need freeing with
* <mosquitto_property_free_all>.
*
* If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument
* will be applied to the PUBLISH message. For MQTT v3.1.1 and below, the
* `properties` argument will be ignored.
*
* Set your client to use MQTT v5 immediately after it is created:
*
* mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5);
*
* 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.
* options - options to apply to this subscription, OR'd together. Set to 0 to
* use the default options, otherwise choose from list of <mqtt5_sub_options>
* properties - a valid mosquitto_property list, or NULL.
*
* 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_MALFORMED_UTF8 - if the topic is not valid UTF-8
* MOSQ_ERR_DUPLICATE_PROPERTY - if a property is duplicated where it is forbidden.
* MOSQ_ERR_PROTOCOL - if any property is invalid for use with SUBSCRIBE.
* MOSQ_ERR_OVERSIZE_PACKET - if the resulting packet would be larger than
* supported by the broker.
*/
libmosq_EXPORT int mosquitto_subscribe_v5(struct mosquitto *mosq, int *mid, const char *sub, int qos, int options, const mosquitto_property *properties);
/*
* Function: mosquitto_subscribe_multiple
*
* Subscribe to multiple topics.
*
* 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_count - the count of subscriptions to be made
* sub - array of sub_count pointers, each pointing to a subscription string.
* The "char *const *const" datatype ensures that neither the array of
* pointers nor the strings that they point to are mutable. If you aren't
* familiar with this, just think of it as a safer "char **",
* equivalent to "const char *" for a simple string pointer.
* qos - the requested Quality of Service for each subscription.
* options - options to apply to this subscription, OR'd together. This
* argument is not used for MQTT v3 susbcriptions. Set to 0 to use