forked from eclipse/mosquitto
-
Notifications
You must be signed in to change notification settings - Fork 0
/
mosquitto_broker.h
561 lines (492 loc) · 15.5 KB
/
mosquitto_broker.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
/*
Copyright (c) 2009-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
http: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.
*/
/*
* File: mosquitto_broker.h
*
* This header contains functions for use by plugins.
*/
#ifndef MOSQUITTO_BROKER_H
#define MOSQUITTO_BROKER_H
#ifdef __cplusplus
extern "C" {
#endif
#if defined(WIN32) && defined(mosquitto_EXPORTS)
# define mosq_EXPORT __declspec(dllexport)
#else
# define mosq_EXPORT
#endif
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>
struct mosquitto;
typedef struct mqtt5__property mosquitto_property;
enum mosquitto_protocol {
mp_mqtt,
mp_mqttsn,
mp_websockets
};
/* =========================================================================
*
* Section: Register callbacks.
*
* ========================================================================= */
/* Callback events */
enum mosquitto_plugin_event {
MOSQ_EVT_RELOAD = 1,
MOSQ_EVT_ACL_CHECK = 2,
MOSQ_EVT_BASIC_AUTH = 3,
MOSQ_EVT_EXT_AUTH_START = 4,
MOSQ_EVT_EXT_AUTH_CONTINUE = 5,
MOSQ_EVT_CONTROL = 6,
MOSQ_EVT_MESSAGE = 7,
MOSQ_EVT_PSK_KEY = 8,
MOSQ_EVT_TICK = 9,
MOSQ_EVT_DISCONNECT = 10,
};
/* Data for the MOSQ_EVT_RELOAD event */
struct mosquitto_evt_reload {
void *future;
struct mosquitto_opt *options;
int option_count;
void *future2[4];
};
/* Data for the MOSQ_EVT_ACL_CHECK event */
struct mosquitto_evt_acl_check {
void *future;
struct mosquitto *client;
const char *topic;
const void *payload;
mosquitto_property *properties;
int access;
uint32_t payloadlen;
uint8_t qos;
bool retain;
void *future2[4];
};
/* Data for the MOSQ_EVT_BASIC_AUTH event */
struct mosquitto_evt_basic_auth {
void *future;
struct mosquitto *client;
char *username;
char *password;
void *future2[4];
};
/* Data for the MOSQ_EVT_PSK_KEY event */
struct mosquitto_evt_psk_key {
void *future;
struct mosquitto *client;
const char *hint;
const char *identity;
char *key;
int max_key_len;
void *future2[4];
};
/* Data for the MOSQ_EVT_EXTENDED_AUTH event */
struct mosquitto_evt_extended_auth {
void *future;
struct mosquitto *client;
const void *data_in;
void *data_out;
uint16_t data_in_len;
uint16_t data_out_len;
const char *auth_method;
void *future2[3];
};
/* Data for the MOSQ_EVT_CONTROL event */
struct mosquitto_evt_control {
void *future;
struct mosquitto *client;
const char *topic;
const void *payload;
const mosquitto_property *properties;
char *reason_string;
uint32_t payloadlen;
uint8_t qos;
uint8_t reason_code;
bool retain;
void *future2[4];
};
/* Data for the MOSQ_EVT_MESSAGE event */
struct mosquitto_evt_message {
void *future;
struct mosquitto *client;
char *topic;
void *payload;
mosquitto_property *properties;
char *reason_string;
uint32_t payloadlen;
uint8_t qos;
uint8_t reason_code;
bool retain;
void *future2[4];
};
/* Data for the MOSQ_EVT_TICK event */
struct mosquitto_evt_tick {
void *future;
long now_ns;
long next_ns;
time_t now_s;
time_t next_s;
void *future2[4];
};
/* Data for the MOSQ_EVT_DISCONNECT event */
struct mosquitto_evt_disconnect {
void *future;
struct mosquitto *client;
int reason;
void *future2[4];
};
/* Callback definition */
typedef int (*MOSQ_FUNC_generic_callback)(int, void *, void *);
typedef struct mosquitto_plugin_id_t mosquitto_plugin_id_t;
/*
* Function: mosquitto_callback_register
*
* Register a callback for an event.
*
* Parameters:
* identifier - the plugin identifier, as provided by <mosquitto_plugin_init>.
* event - the event to register a callback for. Can be one of:
* * MOSQ_EVT_RELOAD
* * MOSQ_EVT_ACL_CHECK
* * MOSQ_EVT_BASIC_AUTH
* * MOSQ_EVT_EXT_AUTH_START
* * MOSQ_EVT_EXT_AUTH_CONTINUE
* * MOSQ_EVT_CONTROL
* * MOSQ_EVT_MESSAGE
* * MOSQ_EVT_PSK_KEY
* * MOSQ_EVT_TICK
* * MOSQ_EVT_DISCONNECT
* cb_func - the callback function
* event_data - event specific data
*
* Returns:
* MOSQ_ERR_SUCCESS - on success
* MOSQ_ERR_INVAL - if cb_func is NULL
* MOSQ_ERR_NOMEM - on out of memory
* MOSQ_ERR_ALREADY_EXISTS - if cb_func has already been registered for this event
* MOSQ_ERR_NOT_SUPPORTED - if the event is not supported
*/
mosq_EXPORT int mosquitto_callback_register(
mosquitto_plugin_id_t *identifier,
int event,
MOSQ_FUNC_generic_callback cb_func,
const void *event_data,
void *userdata);
/*
* Function: mosquitto_callback_unregister
*
* Unregister a previously registered callback function.
*
* Parameters:
* identifier - the plugin identifier, as provided by <mosquitto_plugin_init>.
* event - the event to register a callback for. Can be one of:
* * MOSQ_EVT_RELOAD
* * MOSQ_EVT_ACL_CHECK
* * MOSQ_EVT_BASIC_AUTH
* * MOSQ_EVT_EXT_AUTH_START
* * MOSQ_EVT_EXT_AUTH_CONTINUE
* * MOSQ_EVT_CONTROL
* * MOSQ_EVT_MESSAGE
* * MOSQ_EVT_PSK_KEY
* * MOSQ_EVT_TICK
* * MOSQ_EVT_DISCONNECT
* cb_func - the callback function
* event_data - event specific data
*
* Returns:
* MOSQ_ERR_SUCCESS - on success
* MOSQ_ERR_INVAL - if cb_func is NULL
* MOSQ_ERR_NOT_FOUND - if cb_func was not registered for this event
* MOSQ_ERR_NOT_SUPPORTED - if the event is not supported
*/
mosq_EXPORT int mosquitto_callback_unregister(
mosquitto_plugin_id_t *identifier,
int event,
MOSQ_FUNC_generic_callback cb_func,
const void *event_data);
/* =========================================================================
*
* Section: Memory allocation.
*
* Use these functions when allocating or freeing memory to have your memory
* included in the memory tracking on the broker.
*
* ========================================================================= */
/*
* Function: mosquitto_calloc
*/
mosq_EXPORT void *mosquitto_calloc(size_t nmemb, size_t size);
/*
* Function: mosquitto_free
*/
mosq_EXPORT void mosquitto_free(void *mem);
/*
* Function: mosquitto_malloc
*/
mosq_EXPORT void *mosquitto_malloc(size_t size);
/*
* Function: mosquitto_realloc
*/
mosq_EXPORT void *mosquitto_realloc(void *ptr, size_t size);
/*
* Function: mosquitto_strdup
*/
mosq_EXPORT char *mosquitto_strdup(const char *s);
/* =========================================================================
*
* Section: Utility Functions
*
* Use these functions from within your plugin.
*
* ========================================================================= */
/*
* Function: mosquitto_log_printf
*
* Write a log message using the broker configured logging.
*
* Parameters:
* level - Log message priority. Can currently be one of:
*
* * MOSQ_LOG_INFO
* * MOSQ_LOG_NOTICE
* * MOSQ_LOG_WARNING
* * MOSQ_LOG_ERR
* * MOSQ_LOG_DEBUG
* * MOSQ_LOG_SUBSCRIBE (not recommended for use by plugins)
* * MOSQ_LOG_UNSUBSCRIBE (not recommended for use by plugins)
*
* These values are defined in mosquitto.h.
*
* fmt, ... - printf style format and arguments.
*/
mosq_EXPORT void mosquitto_log_printf(int level, const char *fmt, ...);
/* =========================================================================
*
* Client Functions
*
* Use these functions to access client information.
*
* ========================================================================= */
/*
* Function: mosquitto_client_address
*
* Retrieve the IP address of the client as a string.
*/
mosq_EXPORT const char *mosquitto_client_address(const struct mosquitto *client);
/*
* Function: mosquitto_client_clean_session
*
* Retrieve the clean session flag value for a client.
*/
mosq_EXPORT bool mosquitto_client_clean_session(const struct mosquitto *client);
/*
* Function: mosquitto_client_id
*
* Retrieve the client id associated with a client.
*/
mosq_EXPORT const char *mosquitto_client_id(const struct mosquitto *client);
/*
* Function: mosquitto_client_keepalive
*
* Retrieve the keepalive value for a client.
*/
mosq_EXPORT int mosquitto_client_keepalive(const struct mosquitto *client);
/*
* Function: mosquitto_client_certificate
*
* If TLS support is enabled, return the certificate provided by a client as an
* X509 pointer from openssl. If the client did not provide a certificate, then
* NULL will be returned. This function will only ever return a non-NULL value
* if the `require_certificate` option is set to true.
*
* When you have finished with the x509 pointer, it must be freed using
* X509_free().
*
* If TLS is not supported, this function will always return NULL.
*/
mosq_EXPORT void *mosquitto_client_certificate(const struct mosquitto *client);
/*
* Function: mosquitto_client_protocol
*
* Retrieve the protocol with which the client has connected. Can be one of:
*
* mp_mqtt (MQTT over TCP)
* mp_mqttsn (MQTT-SN)
* mp_websockets (MQTT over Websockets)
*/
mosq_EXPORT int mosquitto_client_protocol(const struct mosquitto *client);
/*
* Function: mosquitto_client_protocol_version
*
* Retrieve the MQTT protocol version with which the client has connected. Can be one of:
*
* Returns:
* 3 - for MQTT v3 / v3.1
* 4 - for MQTT v3.1.1
* 5 - for MQTT v5
*/
mosq_EXPORT int mosquitto_client_protocol_version(const struct mosquitto *client);
/*
* Function: mosquitto_client_sub_count
*
* Retrieve the number of subscriptions that have been made by a client.
*/
mosq_EXPORT int mosquitto_client_sub_count(const struct mosquitto *client);
/*
* Function: mosquitto_client_username
*
* Retrieve the username associated with a client.
*/
mosq_EXPORT const char *mosquitto_client_username(const struct mosquitto *client);
/* Function: mosquitto_set_username
*
* Set the username for a client.
*
* This removes and replaces the current username for a client and hence
* updates its access.
*
* username can be NULL, in which case the client will become anonymous, but
* must not be zero length.
*
* In the case of error, the client will be left with its original username.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success
* MOSQ_ERR_INVAL - if client is NULL, or if username is zero length
* MOSQ_ERR_NOMEM - on out of memory
*/
mosq_EXPORT int mosquitto_set_username(struct mosquitto *client, const char *username);
/* =========================================================================
*
* Section: Client control
*
* ========================================================================= */
/* Function: mosquitto_kick_client_by_clientid
*
* Forcefully disconnect a client from the broker.
*
* If clientid != NULL, then the client with the matching client id is
* disconnected from the broker.
* If clientid == NULL, then all clients are disconnected from the broker.
*
* If with_will == true, then if the client has a Last Will and Testament
* defined then this will be sent. If false, the LWT will not be sent.
*/
mosq_EXPORT int mosquitto_kick_client_by_clientid(const char *clientid, bool with_will);
/* Function: mosquitto_kick_client_by_username
*
* Forcefully disconnect a client from the broker.
*
* If username != NULL, then all clients with a matching username are kicked
* from the broker.
* If username == NULL, then all clients that do not have a username are
* kicked.
*
* If with_will == true, then if the client has a Last Will and Testament
* defined then this will be sent. If false, the LWT will not be sent.
*/
mosq_EXPORT int mosquitto_kick_client_by_username(const char *username, bool with_will);
/* =========================================================================
*
* Section: Publishing functions
*
* ========================================================================= */
/* Function: mosquitto_broker_publish
*
* Publish a message from within a plugin.
*
* This function allows a plugin to publish a message. Messages published in
* this way are treated as coming from the broker and so will not be passed to
* `mosquitto_auth_acl_check(, MOSQ_ACL_WRITE, , )` for checking. Read access
* will be enforced as normal for individual clients when they are due to
* receive the message.
*
* It can be used to send messages to all clients that have a matching
* subscription, or to a single client whether or not it has a matching
* subscription.
*
* Parameters:
* clientid - optional string. If set to NULL, the message is delivered to all
* clients. If non-NULL, the message is delivered only to the
* client with the corresponding client id. If the client id
* specified is not connected, the message will be dropped.
* topic - message topic
* payloadlen - payload length in bytes. Can be 0 for an empty payload.
* payload - payload bytes. If payloadlen > 0 this must not be NULL. Must
* be allocated on the heap. Will be freed by mosquitto after use if the
* function returns success.
* qos - message QoS to use.
* retain - should retain be set on the message. This does not apply if
* clientid is non-NULL.
* properties - MQTT v5 properties to attach to the message. If the function
* returns success, then properties is owned by the broker and
* will be freed at a later point.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success
* MOSQ_ERR_INVAL - if topic is NULL, if payloadlen < 0, if payloadlen > 0
* and payload is NULL, if qos is not 0, 1, or 2.
* MOSQ_ERR_NOMEM - on out of memory
*/
mosq_EXPORT int mosquitto_broker_publish(
const char *clientid,
const char *topic,
int payloadlen,
void *payload,
int qos,
bool retain,
mosquitto_property *properties);
/* Function: mosquitto_broker_publish_copy
*
* Publish a message from within a plugin.
*
* This function is identical to mosquitto_broker_publish, except that a copy
* of `payload` is taken.
*
* Parameters:
* clientid - optional string. If set to NULL, the message is delivered to all
* clients. If non-NULL, the message is delivered only to the
* client with the corresponding client id. If the client id
* specified is not connected, the message will be dropped.
* topic - message topic
* payloadlen - payload length in bytes. Can be 0 for an empty payload.
* payload - payload bytes. If payloadlen > 0 this must not be NULL.
* Memory remains the property of the calling function.
* qos - message QoS to use.
* retain - should retain be set on the message. This does not apply if
* clientid is non-NULL.
* properties - MQTT v5 properties to attach to the message. If the function
* returns success, then properties is owned by the broker and
* will be freed at a later point.
*
* Returns:
* MOSQ_ERR_SUCCESS - on success
* MOSQ_ERR_INVAL - if topic is NULL, if payloadlen < 0, if payloadlen > 0
* and payload is NULL, if qos is not 0, 1, or 2.
* MOSQ_ERR_NOMEM - on out of memory
*/
mosq_EXPORT int mosquitto_broker_publish_copy(
const char *clientid,
const char *topic,
int payloadlen,
const void *payload,
int qos,
bool retain,
mosquitto_property *properties);
#ifdef __cplusplus
}
#endif
#endif