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
|
// Copyright 2021 The Mumble Developers. All rights reserved.
// Use of this source code is governed by a BSD-style license
// that can be found in the LICENSE file at the root of the
// Mumble source tree or at <https://www.mumble.info/LICENSE>.
/// This header file contains the definition of Mumble's API
#ifndef MUMBLE_PLUGIN_API_H_
#define MUMBLE_PLUGIN_API_H_
#include "PluginComponents_v_1_0_x.h"
#include <stdint.h>
// API version
#define MUMBLE_PLUGIN_API_MAJOR_MACRO 1
#define MUMBLE_PLUGIN_API_MINOR_MACRO 0
#define MUMBLE_PLUGIN_API_PATCH_MACRO 0
constexpr int32_t MUMBLE_PLUGIN_API_MAJOR = MUMBLE_PLUGIN_API_MAJOR_MACRO;
constexpr int32_t MUMBLE_PLUGIN_API_MINOR = MUMBLE_PLUGIN_API_MINOR_MACRO;
constexpr int32_t MUMBLE_PLUGIN_API_PATCH = MUMBLE_PLUGIN_API_PATCH_MACRO;
const mumble_version_t MUMBLE_PLUGIN_API_VERSION = { MUMBLE_PLUGIN_API_MAJOR, MUMBLE_PLUGIN_API_MINOR, MUMBLE_PLUGIN_API_PATCH };
// Create macro for casting the pointer to the API object to the proper struct.
// Note that this must only be used if the API uses MUMBLE_PLUGIN_API_VERSION of the API.
#define MUMBLE_CONCAT_HELPER(a, b) a ## _ ## b
#define MUMBLE_CONCAT(a, b) MUMBLE_CONCAT_HELPER(a, b)
#define MUMBLE_API_STRUCT MUMBLE_CONCAT(MumbleAPI_v, MUMBLE_CONCAT(MUMBLE_PLUGIN_API_MAJOR_MACRO, MUMBLE_CONCAT(MUMBLE_PLUGIN_API_MINOR_MACRO, x)))
#define MUMBLE_API_CAST(ptrName) ( *((struct MUMBLE_API_STRUCT *) ptrName) )
struct MumbleAPI_v_1_0_x {
/////////////////////////////////////////////////////////
////////////////////// GENERAL NOTES ////////////////////
/////////////////////////////////////////////////////////
//
// All functions that take in a connection as a paremeter may only be called **after** the connection
// has finished synchronizing. The only exception from this is isConnectionSynchronized.
//
// Strings returned by the API are UTF-8 encoded
// Strings passed to the API are expected to be UTF-8 encoded
//
// All API functions are synchronized and will be executed in Mumble's "main thread" from which most plugin
// callbacks are called as well. Note however that an API call is BLOCKING if invoked from a different
// thread. This means that they can cause deadlocks if used without caution. An example that will lead
// to a deadlock is:
// - plugin callback gets called from the main thread
// - callback messages a separate thread to do something and waits for the action to have completed
// - Separate thread calls an API function
// - The function blocks and waits to be executed in the main thread which is currently blocked waiting
// - deadlock
// -------- Memory management --------
/// Frees the given pointer.
///
/// @param callerID The ID of the plugin calling this function
/// @param pointer The pointer to free
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *freeMemory)(mumble_plugin_id_t callerID, const void *pointer);
// -------- Getter functions --------
/// Gets the connection ID of the server the user is currently active on (the user's audio output is directed at).
///
/// @param callerID The ID of the plugin calling this function
/// @param[out] connection A pointer to the memory location the ID should be written to
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then it is valid to access the
/// value of the provided pointer
mumble_error_t (PLUGIN_CALLING_CONVENTION *getActiveServerConnection)(mumble_plugin_id_t callerID, mumble_connection_t *connection);
/// Checks whether the given connection has finished initializing yet.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param[out] A pointer to the boolean variable that'll hold the info whether the server has finished synchronization yet
/// after this function has executed successfully.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *isConnectionSynchronized)(mumble_plugin_id_t callerID, mumble_connection_t connection, bool *synchronized);
/// Fills in the information about the local user.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param[out] userID A pointer to the memory the user's ID shall be written to
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getLocalUserID)(mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t *userID);
/// Fills in the information about the given user's name.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param userID The user's ID whose name should be obtained
/// @param[out] userName A pointer to where the pointer to the allocated string (C-encoded) should be written to. The
/// allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
/// allocated if this function returns STATUS_OK.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getUserName)(mumble_plugin_id_t callerID, mumble_connection_t connection,
mumble_userid_t userID, const char **userName);
/// Fills in the information about the given channel's name.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param channelID The channel's ID whose name should be obtained
/// @param[out] channelName A pointer to where the pointer to the allocated string (C-ecoded) should be written to. The
/// allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
/// allocated if this function returns STATUS_OK.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getChannelName)(mumble_plugin_id_t callerID, mumble_connection_t connection,
mumble_channelid_t channelID, const char **channelName);
/// Gets an array of all users that are currently connected to the provided server. Passing a nullptr as any of the out-parameter
/// will prevent that property to be set/allocated. If you are only interested in the user count you can thus pass nullptr as the
/// users parameter and save time on allocating + freeing the channels-array while still getting the size out.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param[out] users A pointer to where the pointer of the allocated array shall be written. The
/// allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
/// allocated if this function returns STATUS_OK.
/// @param[out] userCount A pointer to where the size of the allocated user-array shall be written to
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getAllUsers)(mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t **users,
size_t *userCount);
/// Gets an array of all channels on the provided server. Passing a nullptr as any of the out-parameter will prevent
/// that property to be set/allocated. If you are only interested in the channel count you can thus pass nullptr as the
/// channels parameter and save time on allocating + freeing the channels-array while still getting the size out.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param[out] channels A pointer to where the pointer of the allocated array shall be written. The
/// allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
/// allocated if this function returns STATUS_OK.
/// @param[out] channelCount A pointer to where the size of the allocated channel-array shall be written to
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getAllChannels)(mumble_plugin_id_t callerID, mumble_connection_t connection,
mumble_channelid_t **channels, size_t *channelCount);
/// Gets the ID of the channel the given user is currently connected to.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param userID The ID of the user to search for
/// @param[out] A pointer to where the ID of the channel shall be written
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getChannelOfUser)(mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t userID,
mumble_channelid_t *channel);
/// Gets an array of all users in the specified channel.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param channelID The ID of the channel whose users shall be retrieved
/// @param[out] userList A pointer to where the pointer of the allocated array shall be written. The allocated memory has
/// to be freed by a call to freeMemory by the plugin eventually. The memory will only be allocated if this function
/// returns STATUS_OK.
/// @param[out] userCount A pointer to where the size of the allocated user-array shall be written to
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getUsersInChannel)(mumble_plugin_id_t callerID, mumble_connection_t connection,
mumble_channelid_t channelID, mumble_userid_t **userList, size_t *userCount);
/// Gets the current transmission mode of the local user.
///
/// @param callerID The ID of the plugin calling this function
/// @param[out] transmissionMode A pointer to where the transmission mode shall be written.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getLocalUserTransmissionMode)(mumble_plugin_id_t callerID, mumble_transmission_mode_t *transmissionMode);
/// Checks whether the given user is currently locally muted.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param userID The ID of the user to check for
/// @param[out] muted A pointer to where the local mute state of that user shall be written
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *isUserLocallyMuted)(mumble_plugin_id_t callerID, mumble_connection_t connection,
mumble_userid_t userID, bool *muted);
/// Checks whether the local user is currently muted.
///
/// @param callerID The ID of the plugin calling this function
/// @param[out] muted A pointer to where the mute state of the local user shall be written
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *isLocalUserMuted)(mumble_plugin_id_t callerID, bool *muted);
/// Checks whether the local user is currently deafened.
///
/// @param callerID The ID of the plugin calling this function
/// @param[out] deafened A pointer to where the deaf state of the local user shall be written
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *isLocalUserDeafened)(mumble_plugin_id_t callerID, bool *deafened);
/// Gets the hash of the given user (can be used to recognize users between restarts)
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param userID The ID of the user to search for
/// @param[out] hash A pointer to where the pointer to the allocated string (C-encoded) should be written to. The
/// allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
/// allocated if this function returns STATUS_OK.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getUserHash)(mumble_plugin_id_t callerID, mumble_connection_t connection,
mumble_userid_t userID, const char **hash);
/// Gets the hash of the server for the given connection (can be used to recognize servers between restarts)
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection
/// @param[out] hash A pointer to where the pointer to the allocated string (C-encoded) should be written to. The
/// allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
/// allocated if this function returns STATUS_OK.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getServerHash)(mumble_plugin_id_t callerID, mumble_connection_t connection, const char **hash);
/// Gets the comment of the given user. Note that a user might have a comment configured that hasn't been synchronized
/// to this client yet. In this case this function will return EC_UNSYNCHRONIZED_BLOB. As of now there is now way
/// to request the synchronization to happen via the Plugin-API.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection
/// @param userID the ID of the user whose comment should be obtained
/// @param[out] comment A pointer to where the pointer to the allocated string (C-encoded) should be written to. The
/// allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
/// allocated if this function returns STATUS_OK.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getUserComment)(mumble_plugin_id_t callerID, mumble_connection_t connection,
mumble_userid_t userID, const char **comment);
/// Gets the description of the given channel. Note that a channel might have a description configured that hasn't been synchronized
/// to this client yet. In this case this function will return EC_UNSYNCHRONIZED_BLOB. As of now there is now way
/// to request the synchronization to happen via the Plugin-API.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection
/// @param channelID the ID of the channel whose comment should be obtained
/// @param[out] description A pointer to where the pointer to the allocated string (C-encoded) should be written to. The
/// allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
/// allocated if this function returns STATUS_OK.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *getChannelDescription)(mumble_plugin_id_t callerID, mumble_connection_t connection,
mumble_channelid_t channelID, const char **description);
// -------- Request functions --------
/// Requests Mumble to set the local user's transmission mode to the specified one. If you only need to temporarily set
/// the transmission mode to continous, use requestMicrophoneActivationOverwrite instead as this saves you the work of
/// restoring the previous state afterwards.
///
/// @param callerID The ID of the plugin calling this function
/// @param transmissionMode The requested transmission mode
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *requestLocalUserTransmissionMode)(mumble_plugin_id_t callerID, mumble_transmission_mode_t transmissionMode);
/// Requests Mumble to move the given user into the given channel
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param userID The ID of the user that shall be moved
/// @param channelID The ID of the channel to move the user to
/// @param password The password of the target channel (UTF-8 encoded as a C-string). Pass NULL if the target channel does not require a
/// password for entering
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *requestUserMove)(mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t userID,
mumble_channelid_t channelID, const char *password);
/// Requests Mumble to overwrite the microphone activation so that the microphone is always on (same as if the user had chosen
/// the continous transmission mode). If a plugin requests this overwrite, it is responsible for deactivating the overwrite again
/// once it is no longer required
///
/// @param callerID The ID of the plugin calling this function
/// @param activate Whether to activate the overwrite (false deactivates an existing overwrite)
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *requestMicrophoneActivationOvewrite)(mumble_plugin_id_t callerID, bool activate);
/// Requests Mumble to set the local mute state of the given client. Note that this only affects the **local** mute state
/// opposed to a server-mute (client is globally muted by the server) or the client's own mute-state (client has muted its
/// microphone and thus isn't transmitting any audio).
/// Furthermore it must be noted that muting the local user with this function does not work (it doesn't make sense). If
/// you try to do so, this function will fail. In order to make this work, this function will also fail if the server
/// has not finished synchronizing with the client yet.
/// For muting the local user, use requestLocalUserMute instead.
///
/// @param callerID The ID of the plugin calling this function.
/// @param connection The ID of the server-connection to use as a context
/// @param userID The ID of the user that shall be muted
/// @param muted Whether to locally mute the given client (opposed to unmuting it)
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *requestLocalMute)(mumble_plugin_id_t callerID, mumble_connection_t connection,
mumble_userid_t userID, bool muted);
/// Requests Mumble to set the mute state of the local user. In the UI this is referred to as "self-mute".
///
/// @param callerID The ID of the plugin calling this function.
/// @param muted Whether to locally mute the local user (opposed to unmuting it)
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *requestLocalUserMute)(mumble_plugin_id_t callerID, bool muted);
/// Requests Mumble to set the deaf state of the local user. In the UI this is referred to as "self-deaf".
///
/// @param callerID The ID of the plugin calling this function.
/// @param deafened Whether to locally deafen the local user (opposed to undeafening it)
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *requestLocalUserDeaf)(mumble_plugin_id_t callerID, bool deafened);
/// Sets the comment of the local user
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection
/// @param comment The new comment to use (C-encoded). A subset of HTML formatting is supported.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
/// may be accessed
mumble_error_t (PLUGIN_CALLING_CONVENTION *requestSetLocalUserComment)(mumble_plugin_id_t callerID, mumble_connection_t connection,
const char *comment);
// -------- Find functions --------
/// Fills in the information about a user with the specified name, if such a user exists. The search is case-sensitive.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param userName The respective user's name
/// @param[out] userID A pointer to the memory the user's ID shall be written to
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
/// be accessed.
mumble_error_t (PLUGIN_CALLING_CONVENTION *findUserByName)(mumble_plugin_id_t callerID, mumble_connection_t connection, const char *userName,
mumble_userid_t *userID);
/// Fills in the information about a channel with the specified name, if such a channel exists. The search is case-sensitive.
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to use as a context
/// @param channelName The respective channel's name
/// @param[out] channelID A pointer to the memory the channel's ID shall be written to
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
/// be accessed.
mumble_error_t (PLUGIN_CALLING_CONVENTION *findChannelByName)(mumble_plugin_id_t callerID, mumble_connection_t connection,
const char *channelName, mumble_channelid_t *channelID);
// -------- Settings --------
/// Fills in the current value of the setting with the given key. Note that this function can only be used for settings whose value
/// is a bool!
///
/// @param callerID The ID of the plugin calling this function
/// @param key The key to the desired setting
/// @param[out] outValue A pointer to the memory the setting's value shall be written to.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
/// be accessed.
mumble_error_t (PLUGIN_CALLING_CONVENTION *getMumbleSetting_bool)(mumble_plugin_id_t callerID, mumble_settings_key_t key, bool *outValue);
/// Fills in the current value of the setting with the given key. Note that this function can only be used for settings whose value
/// is an int!
///
/// @param callerID The ID of the plugin calling this function
/// @param key The key to the desired setting
/// @param[out] outValue A pointer to the memory the setting's value shall be written to.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
/// be accessed.
mumble_error_t (PLUGIN_CALLING_CONVENTION *getMumbleSetting_int)(mumble_plugin_id_t callerID, mumble_settings_key_t key, int64_t *outValue);
/// Fills in the current value of the setting with the given key. Note that this function can only be used for settings whose value
/// is a double!
///
/// @param callerID The ID of the plugin calling this function
/// @param key The key to the desired setting
/// @param[out] outValue A pointer to the memory the setting's value shall be written to.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
/// be accessed.
mumble_error_t (PLUGIN_CALLING_CONVENTION *getMumbleSetting_double)(mumble_plugin_id_t callerID, mumble_settings_key_t key, double *outValue);
/// Fills in the current value of the setting with the given key. Note that this function can only be used for settings whose value
/// is a String!
///
/// @param callerID The ID of the plugin calling this function
/// @param key The key to the desired setting
/// @param[out] outValue The memory address to which the pointer to the setting's value (the String) will be written. The
/// allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
/// allocated if this function returns STATUS_OK.
/// @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
/// be accessed.
mumble_error_t (PLUGIN_CALLING_CONVENTION *getMumbleSetting_string)(mumble_plugin_id_t callerID, mumble_settings_key_t key, const char **outValue);
/// Sets the value of the setting with the given key. Note that this function can only be used for settings whose value
/// is a bool!
///
/// @param callerID The ID of the plugin calling this function
/// @param key The key to the desired setting
/// @param value The value that should be set for the given setting
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *setMumbleSetting_bool)(mumble_plugin_id_t callerID, mumble_settings_key_t key, bool value);
/// Sets the value of the setting with the given key. Note that this function can only be used for settings whose value
/// is an int!
///
/// @param callerID The ID of the plugin calling this function
/// @param key The key to the desired setting
/// @param value The value that should be set for the given setting
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *setMumbleSetting_int)(mumble_plugin_id_t callerID, mumble_settings_key_t key, int64_t value);
/// Sets the value of the setting with the given key. Note that this function can only be used for settings whose value
/// is a double!
///
/// @param callerID The ID of the plugin calling this function
/// @param key The key to the desired setting
/// @param value The value that should be set for the given setting
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *setMumbleSetting_double)(mumble_plugin_id_t callerID, mumble_settings_key_t key, double value);
/// Sets the value of the setting with the given key. Note that this function can only be used for settings whose value
/// is a string!
///
/// @param callerID The ID of the plugin calling this function
/// @param key The key to the desired setting
/// @param value The value that should be set for the given setting
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *setMumbleSetting_string)(mumble_plugin_id_t callerID, mumble_settings_key_t key, const char *value);
// -------- Miscellaneous --------
/// Sends the provided data to the provided client(s). This kind of data can only be received by another plugin active
/// on that client. The sent data can be seen by any active plugin on the receiving client. Therefore the sent data
/// must not contain sensitive information or anything else that shouldn't be known by others.
///
/// NOTE: Messages sent via this API function are rate-limited by the server. If the rate-limit is hit, the message
/// will be dropped without an error message. The rate-limiting is global (e.g. it doesn't matter which plugin sent
/// the respective messages - they all count to the same limit).
/// Therefore if you have multiple messages to send, you should consider sending them asynchronously one at a time
/// with a little delay in between (~1 second).
///
/// @param callerID The ID of the plugin calling this function
/// @param connection The ID of the server-connection to send the data through (the server the given users are on)
/// @param users An array of user IDs to send the data to
/// @param userCount The size of the provided user-array
/// @param data The data array that shall be sent. This can be an arbitrary sequence of bytes. Note that the size of
/// is restricted to <= 1KB.
/// @param dataLength The length of the data array
/// @param dataID The ID of the sent data. This has to be used by the receiving plugin(s) to figure out what to do with
/// the data. This has to be a C-encoded String. It is recommended that the ID starts with a plugin-specific prefix
/// in order to avoid name clashes. Note that the size of this string is restricted to <= 100 bytes.
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *sendData)(mumble_plugin_id_t callerID, mumble_connection_t connection, const mumble_userid_t *users,
size_t userCount, const uint8_t *data, size_t dataLength, const char *dataID);
/// Logs the given message (typically to Mumble's console). All passed strings have to be UTF-8 encoded.
///
/// @param callerID The ID of the plugin calling this function
/// @param message The message to log
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *log)(mumble_plugin_id_t callerID, const char *message);
/// Plays the provided sample. It uses libsndfile as a backend so the respective file format needs to be supported by it
/// in order for this to work out (see http://www.mega-nerd.com/libsndfile/).
///
/// @param callerID The ID of the plugin calling this function
/// @param samplePath The path to the sample that shall be played (UTF-8 encoded)
/// @returns The error code. If everything went well, STATUS_OK will be returned.
mumble_error_t (PLUGIN_CALLING_CONVENTION *playSample)(mumble_plugin_id_t callerID, const char *samplePath);
};
#endif
|