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
|
// 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>.
// Include the definitions of the plugin functions
// Not that this will also include ../PluginComponents.h
#include "../MumblePlugin_v_1_0_x.h"
#include "../MumbleAPI_v_1_0_x.h"
#include <iostream>
#include <cstring>
// These are just some utility functions facilitating writing logs and the like
// The actual implementation of the plugin is further down
std::ostream& pLog() {
std::cout << "TestPlugin: ";
return std::cout;
}
template<typename T>
void pluginLog(T log) {
pLog() << log << std::endl;
}
std::ostream& operator<<(std::ostream& stream, const mumble_version_t version) {
stream << "v" << version.major << "." << version.minor << "." << version.patch;
return stream;
}
//////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////
//////////////////// PLUGIN IMPLEMENTATION ///////////////////
//////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////
MumbleAPI_v_1_0_x mumAPI;
mumble_connection_t activeConnection;
mumble_plugin_id_t ownID;
//////////////////////////////////////////////////////////////
//////////////////// OBLIGATORY FUNCTIONS ////////////////////
//////////////////////////////////////////////////////////////
// All of the following function must be implemented in order for Mumble to load the plugin
mumble_error_t mumble_init(uint32_t id) {
pluginLog("Initialized plugin");
ownID = id;
// Print the connection ID at initialization. If not connected to a server it should be -1.
pLog() << "Plugin ID is " << id << std::endl;
mumAPI.log(ownID, "Intitialized");
// Little showcase for how to retrieve a setting from Mumble
int64_t voiceHold;
mumble_error_t error = mumAPI.getMumbleSetting_int(ownID, MSK_AUDIO_INPUT_VOICE_HOLD, &voiceHold);
if (error == STATUS_OK) {
pLog() << "The voice hold is set to " << voiceHold << std::endl;
} else {
pluginLog("Failed to retrieve voice hold");
pLog() << errorMessage(error) << std::endl;
}
// STATUS_OK is a macro set to the appropriate status flag (ErrorCode)
// If you need to return any other status have a look at the ErrorCode enum
// inside PluginComponents.h and use one of its values
return STATUS_OK;
}
void mumble_shutdown() {
pluginLog("Shutdown plugin");
mumAPI.log(ownID, "Shutdown");
}
MumbleStringWrapper mumble_getName() {
static const char *name = "TestPlugin";
MumbleStringWrapper wrapper;
wrapper.data = name;
wrapper.size = strlen(name);
// It's a static String and therefore doesn't need releasing
wrapper.needsReleasing = false;
return wrapper;
}
mumble_version_t mumble_getAPIVersion() {
// MUMBLE_PLUGIN_API_VERSION will always contain the API version of the used header file (the one used to build
// this plugin against). Thus you should always return that here in order to no have to worry about it.
return MUMBLE_PLUGIN_API_VERSION;
}
void mumble_registerAPIFunctions(void *api) {
// In this function the plugin is presented with a struct of function pointers that can be used
// to interact with Mumble. Thus you should store it somewhere safe for later usage.
// The pointer has to be cast to the respective API struct. You always have to cast to the same API version
// as this plugin itself is using. Thus if this plugin is compiled using the API version 1.0.x (where x is an arbitrary version)
// the pointer has to be cast to MumbleAPI_v_1_0_x (where x is a literal "x").
// Furthermore the struct HAS TO BE COPIED!!! Storing the pointer is not an option as it will become invalid quickly!
// **If** you are using the same API version that is specified in the included header file (as you should), you
// can simply use the MUMBLE_API_CAST to cast the pointer to the correct type and automatically dereferencing it.
mumAPI = MUMBLE_API_CAST(api);
pluginLog("Registered Mumble's API functions");
}
void mumble_releaseResource(const void *pointer) {
std::cerr << "[ERROR]: Unexpected call to mumble_releaseResources" << std::endl;
std::terminate();
// This plugin doesn't use resources that are explicitly allocated (only static Strings are used). Therefore
// we don't have to implement this function.
//
// If you allocated resources using malloc(), you're implementation for releasing that would be
// free(const_cast<void *>(pointer));
//
// If however you allocated a resource using the new operator (C++ only), you have figure out the pointer's
// original type and then invoke
// delete static_cast<ActualType *>(pointer);
// Mark as unused
(void) pointer;
}
//////////////////////////////////////////////////////////////
///////////////////// OPTIONAL FUNCTIONS /////////////////////
//////////////////////////////////////////////////////////////
// The implementation of below functions is optional. If you don't need them, don't include them in your
// plugin
void mumble_setMumbleInfo(mumble_version_t mumbleVersion, mumble_version_t mumbleAPIVersion, mumble_version_t minimumExpectedAPIVersion) {
// this function will always be the first one to be called. Even before init()
// In here you can get info about the Mumble version this plugin is about to run in.
pLog() << "Mumble version: " << mumbleVersion << "; Mumble API-Version: " << mumbleAPIVersion << "; Minimal expected API-Version: "
<< minimumExpectedAPIVersion << std::endl;
}
mumble_version_t mumble_getVersion() {
// Mumble uses semantic versioning (see https://semver.org/)
// { major, minor, patch }
return { 1, 0, 0 };
}
MumbleStringWrapper mumble_getAuthor() {
static const char *author = "MumbleDevelopers";
MumbleStringWrapper wrapper;
wrapper.data = author;
wrapper.size = strlen(author);
// It's a static String and therefore doesn't need releasing
wrapper.needsReleasing = false;
return wrapper;
}
MumbleStringWrapper mumble_getDescription() {
static const char *description =
"This plugin is merely a reference implementation without any real functionality. It shouldn't be included in the release build of Mumble.";
MumbleStringWrapper wrapper;
wrapper.data = description;
wrapper.size = strlen(description);
// It's a static String and therefore doesn't need releasing
wrapper.needsReleasing = false;
return wrapper;
}
uint32_t mumble_getFeatures() {
// Tells Mumble whether this plugin delivers some known common functionality. See the PluginFeature enum in
// PluginComponents.h for what is available.
// If you want your plugin to deliver positional data, you'll want to return FEATURE_POSITIONAL
return FEATURE_NONE;
}
uint32_t mumble_deactivateFeatures(uint32_t features) {
pLog() << "Asked to deactivate feature set " << features << std::endl;
// All features that can't be deactivated should be returned
return features;
}
uint8_t mumble_initPositionalData(const char *const*programNames, const uint64_t *programPIDs, size_t programCount) {
std::ostream& stream = pLog() << "Got " << programCount << " programs to init positional data.";
if (programCount > 0) {
stream << " The first name is " << programNames[0] << " and has PID " << programPIDs[0];
}
stream << std::endl;
// As this plugin doesn't provide PD, we return PDEC_ERROR_PERM to indicate that even in the future we won't do so
// If your plugin is indeed delivering positional data but is only temporarily unable to do so, return PDEC_ERROR_TEMP.
// and if you deliver PD and succeeded initializing return PDEC_OK.
return PDEC_ERROR_PERM;
}
#define SET_TO_ZERO(name) name[0] = 0.0f; name[1] = 0.0f; name[2] = 0.0f
bool mumble_fetchPositionalData(float *avatarPos, float *avatarDir, float *avatarAxis, float *cameraPos, float *cameraDir,
float *cameraAxis, const char **context, const char **identity) {
pluginLog("Has been asked to deliver positional data");
// If unable to provide positional data, this function should return false and reset all given values to 0 / empty Strings
SET_TO_ZERO(avatarPos);
SET_TO_ZERO(avatarDir);
SET_TO_ZERO(avatarAxis);
SET_TO_ZERO(cameraPos);
SET_TO_ZERO(cameraDir);
SET_TO_ZERO(cameraAxis);
*context = "";
*identity = "";
// This function returns whether it can continue to deliver positional data
return false;
}
#undef SET_TO_ZERO
void mumble_shutdownPositionalData() {
pluginLog("Shutting down positional data");
}
void mumble_onServerConnected(mumble_connection_t connection) {
activeConnection = connection;
pLog() << "Established server-connection with ID " << connection << std::endl;
// Use API function that'll block
mumAPI.log(ownID, "Connected to a server");
}
void mumble_onServerDisconnected(mumble_connection_t connection) {
activeConnection = -1;
const char *serverHash;
if (mumAPI.getServerHash(ownID, connection, &serverHash) == STATUS_OK) {
pLog() << "Disconnected from server-connection with ID " << connection << "(hash: " << serverHash << ")" << std::endl;
mumAPI.freeMemory(ownID, serverHash);
} else {
pluginLog("[ERROR]: mumble_onServerDisconnected - Unable to fetch server-hash");
}
}
void mumble_onServerSynchronized(mumble_connection_t connection) {
// The client has finished synchronizing with the server. Thus we can now obtain a list of all users on this server
const char *serverHash;
if (mumAPI.getServerHash(ownID, connection, &serverHash) == STATUS_OK) {
pLog() << "Server has finished synchronizing (ServerConnection: " << connection << "; hash: " << serverHash << ")" << std::endl ;
mumAPI.freeMemory(ownID, serverHash);
} else {
pluginLog("[ERROR]: mumble_onServerSynchronized - Unable to fetch server-hash");
}
size_t userCount;
mumble_userid_t *userIDs;
if (mumAPI.getAllUsers(ownID, activeConnection, &userIDs, &userCount) != STATUS_OK) {
pluginLog("[ERROR]: Can't obtain user list");
return;
}
mumble_userid_t localUserID;
if (mumAPI.getLocalUserID(ownID, connection, &localUserID) != STATUS_OK) {
pluginLog("[ERROR]: Can't obtain ID of local user");
return;
}
pLog() << "There are " << userCount << " users on this server. Their names are:" << std::endl;
for(size_t i=0; i<userCount; i++) {
const char *userName;
if (mumAPI.getUserName(ownID, connection, userIDs[i], &userName) != STATUS_OK) {
pLog() << "<Unable to fetch user name>" << std::endl;
continue;
}
const char *userHash;
if (mumAPI.getUserHash(ownID, connection, userIDs[i], &userHash) != STATUS_OK) {
pluginLog("<Unable to get user-hash>");
}
pLog() << "\t" << userName << " (" << userHash << ")" << std::endl;
// Mute the user "MuteMe" if this is not the name of the local user (in which case it'd fail)
if (userIDs[i] != localUserID && std::strcmp(userName, "MuteMe") == 0) {
if (mumAPI.requestLocalMute(ownID, connection, userIDs[i], true) != STATUS_OK) {
pluginLog("[ERROR]: Failed at muting user \"MuteMe\"!");
}
}
mumAPI.freeMemory(ownID, userName);
mumAPI.freeMemory(ownID, userHash);
}
mumAPI.freeMemory(ownID, userIDs);
size_t channelCount;
mumble_channelid_t *channelIDs;
if (mumAPI.getAllChannels(ownID, activeConnection, &channelIDs, &channelCount) != STATUS_OK) {
pluginLog("[ERROR]: Failed to fetch channel list!");
return;
}
pLog() << "There are " << channelCount << " channels on this server" << std::endl;
mumAPI.freeMemory(ownID, channelIDs);
mumble_userid_t localUser;
if (mumAPI.getLocalUserID(ownID, activeConnection, &localUser) != STATUS_OK) {
pluginLog("Failed to retrieve local user ID");
return;
}
if (mumAPI.sendData(ownID, activeConnection, &localUser, 1, reinterpret_cast<const uint8_t *>("Just a test"), 12, "testMsg") == STATUS_OK) {
pluginLog("Successfully sent plugin message");
// Try break the rate-limiter for plugin messages
for (int i = 0; i < 40; i++) {
std::string data = "Rate-limit message #" + std::to_string(i);
mumAPI.sendData(ownID, activeConnection, &localUser, 1, reinterpret_cast<const uint8_t * >(data.c_str()), data.size(), "testMsg");
}
} else {
pluginLog("Failed at sending message");
}
if (mumAPI.requestSetLocalUserComment(ownID, connection, "This user has the TestPlugin enabled - <b>hand over a cookie!</b>") != STATUS_OK) {
pluginLog("Failed at setting the local user's comment");
}
}
void mumble_onChannelEntered(mumble_connection_t connection, mumble_userid_t userID, mumble_channelid_t previousChannelID, mumble_channelid_t newChannelID) {
std::ostream& stream = pLog() << "User with ID " << userID << " entered channel with ID " << newChannelID << ".";
// negative ID means that there was no previous channel (e.g. because the user just connected)
if (previousChannelID >= 0) {
stream << " Came from channel with ID " << previousChannelID << ".";
}
stream << " (ServerConnection: " << connection << ")" << std::endl;
}
void mumble_onChannelExited(mumble_connection_t connection, mumble_userid_t userID, mumble_channelid_t channelID) {
pLog() << "User with ID " << userID << " has left channel with ID " << channelID << ". (ServerConnection: " << connection << ")" << std::endl;
}
void mumble_onUserTalkingStateChanged(mumble_connection_t connection, mumble_userid_t userID, mumble_talking_state_t talkingState) {
std::ostream& stream = pLog() << "User with ID " << userID << " changed his talking state to ";
// The possible values are contained in the TalkingState enum inside PluginComponent.h
switch(talkingState) {
case INVALID:
stream << "Invalid";
break;
case PASSIVE:
stream << "Passive";
break;
case TALKING:
stream << "Talking";
break;
case WHISPERING:
stream << "Whispering";
break;
case SHOUTING:
stream << "Shouting";
break;
default:
stream << "Unknown (" << talkingState << ")";
}
stream << ". (ServerConnection: " << connection << ")" << std::endl;
}
bool mumble_onAudioInput(short *inputPCM, uint32_t sampleCount, uint16_t channelCount, uint32_t sampleRate, bool isSpeech) {
// pLog() << "Audio input with " << channelCount << " channels and " << sampleCount << " samples per channel encountered. IsSpeech: "
// << isSpeech << " Sample rate is " << sampleRate << "Hz" << std::endl;
// mark variables as unused
(void) inputPCM;
(void) sampleCount;
(void) channelCount;
(void) sampleRate;
(void) isSpeech;
// This function returns whether it has modified the audio stream
return false;
}
bool mumble_onAudioSourceFetched(float *outputPCM, uint32_t sampleCount, uint16_t channelCount, uint32_t sampleRate, bool isSpeech, mumble_userid_t userID) {
std::ostream& stream = pLog() << "Audio output source with " << channelCount << " channels and " << sampleCount << " samples per channel "
<< "(" << sampleRate << " Hz) fetched.";
if (isSpeech) {
stream << " The output is speech from user with ID " << userID << ".";
}
stream << std::endl;
// Mark ouputPCM as unused
(void) outputPCM;
// This function returns whether it has modified the audio stream
return false;
}
bool mumble_onAudioOutputAboutToPlay(float *outputPCM, uint32_t sampleCount, uint16_t channelCount, uint32_t sampleRate) {
// pLog() << "The resulting audio output has " << channelCount << " channels with " << sampleCount << " samples per channel ("
// sampleRate << " Hz)" << std::endl;
// mark variables as unused
(void) outputPCM;
(void) sampleCount;
(void) channelCount;
(void) sampleRate;
// This function returns whether it has modified the audio stream
return false;
}
bool mumble_onReceiveData(mumble_connection_t connection, mumble_userid_t sender, const uint8_t *data, size_t dataLength, const char *dataID) {
pLog() << "Received data with ID \"" << dataID << "\" from user with ID " << sender << ". Its length is " << dataLength
<< ". (ServerConnection:" << connection << ")" << std::endl;
if (std::strcmp(dataID, "testMsg") == 0) {
// We know that data is only a normal C-encoded String, so the reinterpret_cast is safe
pLog() << "The received data: " << reinterpret_cast<const char *>(data) << std::endl;
}
// This function returns whether it has processed the data (preventing further plugins from seeing it)
return false;
}
void mumble_onUserAdded(mumble_connection_t connection, mumble_userid_t userID) {
pLog() << "Added user with ID " << userID << " (ServerConnection: " << connection << ")" << std::endl;
}
void mumble_onUserRemoved(mumble_connection_t connection, mumble_userid_t userID) {
pLog() << "Removed user with ID " << userID << " (ServerConnection: " << connection << ")" << std::endl;
}
void mumble_onChannelAdded(mumble_connection_t connection, mumble_channelid_t channelID) {
pLog() << "Added channel with ID " << channelID << " (ServerConnection: " << connection << ")" << std::endl;
}
void mumble_onChannelRemoved(mumble_connection_t connection, mumble_channelid_t channelID) {
pLog() << "Removed channel with ID " << channelID << " (ServerConnection: " << connection << ")" << std::endl;
}
void mumble_onChannelRenamed(mumble_connection_t connection, mumble_channelid_t channelID) {
pLog() << "Renamed channel with ID " << channelID << " (ServerConnection: " << connection << ")" << std::endl;
}
void mumble_onKeyEvent(uint32_t keyCode, bool wasPress) {
pLog() << "Encountered key " << (wasPress ? "press" : "release") << " of key with code " << keyCode << std::endl;
}
bool mumble_hasUpdate() {
// This plugin never has an update
return false;
}
MumbleStringWrapper mumble_getUpdateDownloadURL() {
static const char *url = "https://i.dont.exist/testplugin.zip";
MumbleStringWrapper wrapper;
wrapper.data = url;
wrapper.size = strlen(url);
// It's a static String and therefore doesn't need releasing
wrapper.needsReleasing = false;
return wrapper;
}
|