diff --git a/docs/dev/IncrementingTheMumbleAPI.md b/docs/dev/IncrementingTheMumbleAPI.md index 36327e2d62c..d1223717e70 100644 --- a/docs/dev/IncrementingTheMumbleAPI.md +++ b/docs/dev/IncrementingTheMumbleAPI.md @@ -1,34 +1,30 @@ # Incrementing the Mumble API version ## Overview -[Plugins](/docs/dev/plugins/) are used to extend the Mumble client with custom functionality. They are compiled against multiple [header files](/plugins/) which -contain all function and structure signatures that can be used by the plugin. If you are commiting breaking API changes (such as additions or deletions) to these function signatures -on the Mumble side, the API version will probably have to be increased. This is done to ensure plugins will have access to these functions when they -are compiled against the new API version, while old plugins, using previous API versions, will still work. - -## Instructions -If your commit includes breaking API changes, the following steps have to be followed: - -1) Create a new ``Mumble_API_v___x.h`` file in [plugins/](/plugins/). - * Replace ```` with the API major version and ```` with the API minor version. - * Usually, you will have to increase the ```` version by 1 compared to the previous latest version. So if the previous API string was ``1.2.0``, you would probably want to increase the second number by one and create the file ``MumbleAPI_v_1_3_x.h``. - * The last "patch" digit of the version string is reserved for non-breaking API changes such as small fixes. Since non-breaking changes do not require a major or minor API increment, we do not worry about the "patch" digit in this document. -1) Make sure you correctly set the ``MUMBLE_PLUGIN_API_MAJOR_MACRO``, ``MUMBLE_PLUGIN_API_MINOR_MACRO`` and [include guard](https://en.wikipedia.org/wiki/Include_guard) to the new API version. - * You probably want to set the ``MUMBLE_PLUGIN_API_PATCH_MACRO`` to ``0``. -1) Rename the ``struct`` within the file to match the new API version string. - * There is a ``typedef`` at the end of the file which has to use the new ``struct`` name, too. -1) Make your desired changes to the function signatures contained in the header file. -1) Open the [MumbleAPI_structs.h](/src/mumble/MumbleAPI_structs.h) file and add your new API header file as first include. - * Move the previous first include, the last most recent API version, into the ``NO_AUXILIARY_DEFINITIONS`` section. - * This will make sure auxiliary variables and macros always contain the most recent version on the mumble side. -1) Add an ``else`` case to the [Plugin.cpp](/src/mumble/Plugin.cpp) file in the ``Plugin::init`` method. - * You will want to return the newly created ``struct``, if the API version requested by the plugin matches your new one. -1) Create a new function signature in [API.h](/src/mumble/API.h). It should return your new ``struct`` and be of the name ``getMumbleAPI_v___x``. -1) Amend the previous ``API_v__x_x.cpp`` file, or create a new one in [this folder](/src/mumble/). - * For the foreseeable future, reuse the previous cpp file. Creating a new cpp file will probably only be useful on extensive API re-designs. - * If you have created a new ``API_v__x_x.cpp``, you must add it to the [CMakeLists.txt](/src/mumble/CMakeLists.txt). -1) Implement the ``getMumbleAPI_v___x`` function inside the ``API_v__x_x.cpp`` file and return a struct with all functions you want to expose in your API version. -1) When adding a new function or new function signature, copy an existing "C FUNCTION WRAPPER" inside the ``API_v__x_x.cpp`` file. That wrapper should then call your new function. -1) Implement your new API changes in the ``API_v__x_x.cpp`` file. - * If you change the signature of an old function, it is probably best to call the new function in the old implementation with default values. - * This way, old plugins will still be working more or less as expected. +[Plugins](/docs/dev/plugins/) are used to extend the Mumble client with custom functionality. They are compiled against the +[MumblePlugin.h](/plugins/MumblePlugin.h) header, which contains all required definitions (and utilities) that a plugin needs to "do its thing". +Among these definitions, are the functions that are part of the [Mumble API](/docs/dev/plugins/MumbleAPI.md) (search for `Mumble API`). If you modify +these definitions, you'll have to update the API's version number. + +Which version to increment, depends on what kind of change you have made: +- The change is only a minor correction (e.g. fixing a typo in a parameter name or fixing a bug in Mumble's implementation of an API function). + Increase the value of `MUMBLE_PLUGIN_API_PATCH_MACRO` by one. +- The change breaks existing plugins (e.g. adding a new parameter to an existing function or adding a new function altogether). Increase the value of + `MUMBLE_PLUGIN_API_MINOR_MACRO` by one and adapt the API code in Mumble (see below). +- The change is not compatible with the existing framework at all. You should never, ever do this without thorough discussions with the project + maintainers. As for the versioning: a custom procedure will have to be agreed on. + + +## Adapting the Mumble logic + +If the API's minor or major version number have been increased, you will have to adapt Mumble's code to make sure that it will be able to serve +individual plugins different versions of the API. For that, you will have to adapt the code inside the `init()` function of the `Plugin` class. More +specifically, you will have to add another branch to the if-statement that selects the requested API struct. + +The required `API::getMumbleAPI_v_*` functions are implemented inside the `API.h` and `API.cpp` files. Simply follow the already present examples and +create a specific implementation for the new version. Pointers to functions that have not changed can be used as before. + +If you have added a new parameter to an existing function, calling the old function (which should still be available in most cases) should internally +call the new implementation, with that parameter set to a sensible default. This way, all API function calls will end up using the same implementation +on Mumble's side (which reduces maintenance work). + diff --git a/docs/dev/plugins/CreatePlugin.md b/docs/dev/plugins/CreatePlugin.md index 2fc074d2c23..81903f2cfff 100644 --- a/docs/dev/plugins/CreatePlugin.md +++ b/docs/dev/plugins/CreatePlugin.md @@ -15,11 +15,7 @@ also intended to be used as the basis for everyone that wants to start writing a What you need for creating a plugin is - A working C compiler. It does not matter which one -- The Mumble plugin framework header files which are the following (the exact version number in the filename may change depending on which API version - you intend to use): - * [MumbleAPI_v_1_0_x.h](https://github.com/mumble-voip/mumble/blob/master/plugins/MumbleAPI_v_1_0_x.h) - * [MumblePlugin_v_1_0_x.h](https://github.com/mumble-voip/mumble/blob/master/plugins/MumblePlugin_v_1_0_x.h) - * [PluginComponents_v_1_0_x.h](https://github.com/mumble-voip/mumble/blob/master/plugins/PluginComponents_v_1_0_x.h) +- The Mumble plugin header file: [MumblePlugin.h](https://github.com/mumble-voip/mumble/blob/master/plugins/MumblePlugin.h) Although not strictly required, it usually is handy to use a build system for managing your plugin project. In this guide we'll use [cmake](https://cmake.org/). If you have never used cmake before, have a look at [this short guide](https://stackoverflow.com/a/26007567). @@ -28,9 +24,7 @@ All in all the following file structure is assumed to be present on your device: ``` . ├── include -│   ├── MumbleAPI_v_1_0_x.h -│   ├── MumblePlugin_v_1_0_x.h -│   └── PluginComponents_v_1_0_x.h +│   └── MumblePlugin.h ├── CMakeLists.txt └── plugin.c ``` @@ -70,9 +64,9 @@ to build a shared library from the source file `plugin.c` and that everything in Now that the boilerplate is out of the way, we can start writing the actual plugin. This will be done in the `plugin.c` source file. -The first thing you should do is to include `MumblePlugin_v_1_0_x.h`. Furthermore we'll need a few more C headers that we'll include as well: +The first thing you should do is to include `MumblePlugin.h`. Furthermore we'll need a few more C headers that we'll include as well: ```c -#include "MumblePlugin_v_1_0_x.h" +#include "MumblePlugin.h" #include #include @@ -82,7 +76,7 @@ The first thing you should do is to include `MumblePlugin_v_1_0_x.h`. Furthermor Furthermore every plugin needs a way to store at least the Mumble-API and its own ID. In C this can be done using global variables. Therefore go ahead and create the respective variables in the global namespace: ```c -struct MumbleAPI_v_1_0_x mumbleAPI; +MumbleAPI mumbleAPI; mumble_plugin_id_t ownID; ``` diff --git a/docs/dev/plugins/MumbleAPI.md b/docs/dev/plugins/MumbleAPI.md index 7acc7fa7141..cf08269a0ff 100644 --- a/docs/dev/plugins/MumbleAPI.md +++ b/docs/dev/plugins/MumbleAPI.md @@ -98,6 +98,6 @@ That is to say: You must not wait for a job to finish asynchronously that might ## Header files -The following header files describe the Mumble-API struct that contains the function pointers as well as descriptions of the respective functions: -- [Mumble-API v1.0.x](https://github.com/mumble-voip/mumble/blob/master/plugins/MumbleAPI_v_1_0_x.h) +The Mumble API definition is contained in the [MumblePlugin.h](https://github.com/mumble-voip/mumble/blob/master/plugins/MumblePlugin.h) header. It +contains a list of all available functions as well as documentation for every function. diff --git a/docs/dev/plugins/PluginAPI.md b/docs/dev/plugins/PluginAPI.md index 6374d369bf6..3267fa37563 100644 --- a/docs/dev/plugins/PluginAPI.md +++ b/docs/dev/plugins/PluginAPI.md @@ -38,6 +38,6 @@ Unless otherwise noted in the function's description, all functions are called f ## Header files -The following header files describe the plugin-API interface. They also contain a description of what each function is for. -- [Plugin-API v1.0.x](https://github.com/mumble-voip/mumble/blob/master/plugins/MumblePlugin_v_1_0_x.h) +The plugin function definitions are contained in the [MumblePlugin.h](https://github.com/mumble-voip/mumble/blob/master/plugins/MumblePlugin.h) header. It +contains a list of all available functions as well as documentation for every function. diff --git a/plugins/MumbleAPI_v_1_0_x.h b/plugins/MumbleAPI_v_1_0_x.h deleted file mode 100644 index 5d30c14af0b..00000000000 --- a/plugins/MumbleAPI_v_1_0_x.h +++ /dev/null @@ -1,537 +0,0 @@ -// Copyright 2021-2023 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 . - -/// This header file contains the definition of Mumble's API - -#ifndef EXTERNAL_MUMBLE_PLUGIN_API_1_0_x_H_ -#define EXTERNAL_MUMBLE_PLUGIN_API_1_0_x_H_ - -#include "PluginComponents_v_1_0_x.h" -#include - - -#ifndef EXTERNAL_MUMBLE_PLUGIN_API_NO_AUXILIARY_DEFINITIONS - -// API version -# define MUMBLE_PLUGIN_API_MAJOR_MACRO 1 -# define MUMBLE_PLUGIN_API_MINOR_MACRO 0 -# define MUMBLE_PLUGIN_API_PATCH_MACRO 3 - -const int32_t MUMBLE_PLUGIN_API_MAJOR = MUMBLE_PLUGIN_API_MAJOR_MACRO; -const int32_t MUMBLE_PLUGIN_API_MINOR = MUMBLE_PLUGIN_API_MINOR_MACRO; -const 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)) - -#endif // EXTERNAL_MUMBLE_PLUGIN_API_NO_AUXILIARY_DEFINITIONS - -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); -}; - -#ifndef EXTERNAL_MUMBLE_PLUGIN_API_NO_AUXILIARY_DEFINITIONS -typedef struct MumbleAPI_v_1_0_x mumble_api_t; -#endif - -#endif // EXTERNAL_MUMBLE_PLUGIN_API_1_0_x_H_ diff --git a/plugins/MumbleAPI_v_1_2_x.h b/plugins/MumbleAPI_v_1_2_x.h deleted file mode 100644 index 2924332a509..00000000000 --- a/plugins/MumbleAPI_v_1_2_x.h +++ /dev/null @@ -1,539 +0,0 @@ -// Copyright 2022-2023 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 . - -/// This header file contains the definition of Mumble's API - -#ifndef EXTERNAL_MUMBLE_PLUGIN_API_1_2_x_H_ -#define EXTERNAL_MUMBLE_PLUGIN_API_1_2_x_H_ - -#include "PluginComponents_v_1_0_x.h" -#include - - -#ifndef EXTERNAL_MUMBLE_PLUGIN_API_NO_AUXILIARY_DEFINITIONS - -// API version -# define MUMBLE_PLUGIN_API_MAJOR_MACRO 1 -# define MUMBLE_PLUGIN_API_MINOR_MACRO 2 -# define MUMBLE_PLUGIN_API_PATCH_MACRO 0 - -const int32_t MUMBLE_PLUGIN_API_MAJOR = MUMBLE_PLUGIN_API_MAJOR_MACRO; -const int32_t MUMBLE_PLUGIN_API_MINOR = MUMBLE_PLUGIN_API_MINOR_MACRO; -const 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)) - -#endif // EXTERNAL_MUMBLE_PLUGIN_API_NO_AUXILIARY_DEFINITIONS - -struct MumbleAPI_v_1_2_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) - /// @param volume The volume multiplier used when playing the sample (for no change use 1.0f) - /// @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, - float volume); -}; - -#ifndef EXTERNAL_MUMBLE_PLUGIN_API_NO_AUXILIARY_DEFINITIONS -typedef struct MumbleAPI_v_1_2_x mumble_api_t; -#endif - -#endif // EXTERNAL_MUMBLE_PLUGIN_API_1_2_x_H_ diff --git a/plugins/MumblePlugin.h b/plugins/MumblePlugin.h new file mode 100644 index 00000000000..7726f78583d --- /dev/null +++ b/plugins/MumblePlugin.h @@ -0,0 +1,1820 @@ +// Copyright 2023 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 . + +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +//////////////////////////// CONTROL OVER WHAT SECTIONS TO INCLUDE //////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// + +// Whether or not to include default implementations +#ifdef MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS +# undef EXTERNAL_MUMBLE_PLUGIN_DEFAULT_IMPLEMENTATIONS_ +# define EXTERNAL_MUMBLE_PLUGIN_DEFAULT_IMPLEMENTATIONS_ +#endif + +// Whether or not to create the MumbleAPI typedef +#undef MUMBLE_PLUGIN_CREATE_MUMBLE_API_TYPEDEF +#ifndef MUMBLE_PLUGIN_NO_API_TYPEDEF +# define MUMBLE_PLUGIN_CREATE_MUMBLE_API_TYPEDEF +#endif + + +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +////////////////////////////////////// MACRO DEFINITIONS ////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// + +#ifndef EXTERNAL_MUMBLE_PLUGIN_MACROS_ +# define EXTERNAL_MUMBLE_PLUGIN_MACROS_ + +/* + * Plugin version information + */ +# define MUMBLE_PLUGIN_INTERFACE_MAJOR_MACRO 1 +# define MUMBLE_PLUGIN_INTERFACE_MINOR_MACRO 2 +# define MUMBLE_PLUGIN_INTERFACE_PATCH_MACRO 0 + +// Allow the selected API version be overwritten by external definitions +# ifndef MUMBLE_PLUGIN_API_MAJOR_MACRO +# define MUMBLE_PLUGIN_API_MAJOR_MACRO 1 +# endif +# ifndef MUMBLE_PLUGIN_API_MINOR_MACRO +# define MUMBLE_PLUGIN_API_MINOR_MACRO 2 +# endif +# ifndef MUMBLE_PLUGIN_API_PATCH_MACRO +# define MUMBLE_PLUGIN_API_PATCH_MACRO 0 +# endif + +# define MUMBLE_PLUGIN_FUNCTIONS_MAJOR_MACRO 1 +# define MUMBLE_PLUGIN_FUNCTIONS_MINOR_MACRO 1 +# define MUMBLE_PLUGIN_FUNCTIONS_PATCH_MACRO 0 + +/* + * MUMBLE_PLUGIN_EXPORT + */ +# if defined(__GNUC__) && !defined(__MINGW32__) // GCC on Unix-like systems +# define MUMBLE_PLUGIN_EXPORT __attribute__((visibility("default"))) +# elif defined(_MSC_VER) +# define MUMBLE_PLUGIN_EXPORT __declspec(dllexport) +# elif defined(__MINGW32__) +# define MUMBLE_PLUGIN_EXPORT __attribute__((dllexport)) +# else +# error No MUMBLE_PLUGIN_EXPORT definition available +# endif + +/* + * MUMBLE_PLUGIN_CALLING_CONVENTION + */ +# if defined(_MSC_VER) +# define MUMBLE_PLUGIN_CALLING_CONVENTION __cdecl +# elif defined(__MINGW32__) +# define MUMBLE_PLUGIN_CALLING_CONVENTION __attribute__((cdecl)) +# else +# define MUMBLE_PLUGIN_CALLING_CONVENTION +# endif + +/* + * MUMBLE_PLUGIN_HAS_QT + */ +# if defined(QT_CORE_LIB) || defined(QT_VERSION) +# define MUMBLE_PLUGIN_HAS_QT +# endif + + +/* + * MUMBLE_PLUGIN_VERSION_CHECK + * Converts a major, minor and patch version number into a single integer to be used in preprocessor + * if conditions + */ +# define MUMBLE_PLUGIN_VERSION_CHECK(major, minor, patch) (((major) << 16) | ((minor) << 8) | (patch)) + +/* + * MUMBLE_PLUGIN_CONSTEXPR + */ +# ifdef __cplusplus +# define MUMBLE_PLUGIN_CONSTEXPR constexpr +# else +# define MUMBLE_PLUGIN_CONSTEXPR +# endif + +/* + * MUMBLE_EXTERN_C_BEGIN / MUMBLE_EXTERN_C_END + */ +# ifdef __cplusplus +# define MUMBLE_EXTERN_C_BEGIN extern "C" { +# define MUMBLE_EXTERN_C_END } +# else +# define MUMBLE_EXTERN_C_BEGIN +# define MUMBLE_EXTERN_C_END +# endif + +// For more info on the necessity of the with/without pattern have a look +// at https://stackoverflow.com/a/3419392 + +/* + * MUMBLE_CONCAT + * Concatenates the given values WITHOUT macro expansion + */ +# define MUMBLE_CONCAT(a, b) a##_##b +/** + * MUMBLE_ECONCAT + * Concatenates the given values WITH macro expansion + */ +# define MUMBLE_ECONCAT(a, b) MUMBLE_CONCAT(a, b) +/** + * MUMBLE_QUOTE + * Quotes the given value WITHOUT macro expansion + */ +# define MUMBLE_QUOTE(arg) # arg +/** + * MUMBLE_EQUOTE + * Quotes the given value WITH macro expansion + */ +# define MUMBLE_EQUOTE(arg) MUMBLE_QUOTE(arg) + +#endif // EXTERNAL_MUMBLE_PLUGIN_MACROS_ + + + +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +//////////////////////////////////////// PLUGIN TYPES ///////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// + +#ifndef EXTERNAL_MUMBLE_PLUGIN_TYPES_ +# define EXTERNAL_MUMBLE_PLUGIN_TYPES_ + +# include +# include +# include + +# ifdef __cplusplus +# include + +# ifdef MUMBLE_PLUGIN_HAS_QT +# include +# endif +# endif + +MUMBLE_EXTERN_C_BEGIN + +/** + * This enum's values correspond to special feature sets a plugin may provide. + * They are meant to be or'ed together to represent the total feature set of a plugin. + */ +enum Mumble_PluginFeature { + /** + * None of the below + */ + MUMBLE_FEATURE_NONE = 0, + /** + * The plugin provides positional data from a game + */ + MUMBLE_FEATURE_POSITIONAL = 1 << 0, + /** + * The plugin modifies the input/output audio itself + */ + MUMBLE_FEATURE_AUDIO = 1 << 1, +}; + +/** + * This enum's values represent talking states a user can be in when using Mumble. + */ +enum Mumble_TalkingState { + MUMBLE_TS_INVALID = -1, + MUMBLE_TS_PASSIVE = 0, + MUMBLE_TS_TALKING, + MUMBLE_TS_WHISPERING, + MUMBLE_TS_SHOUTING, + MUMBLE_TS_TALKING_MUTED, +}; + +/** + * This enum's values represent transmission modes a user might have configured. Transmission mode + * in this context is referring to a method that determines when a user is speaking and thus when + * to transmit audio packets. + */ +enum Mumble_TransmissionMode { + MUMBLE_TM_CONTINOUS, + MUMBLE_TM_VOICE_ACTIVATION, + MUMBLE_TM_PUSH_TO_TALK, +}; + +/** + * This enum's values represent the error codes that are being used by the MumbleAPI. + * You can get a string-representation for each error code via the errorMessage function. + */ +enum Mumble_ErrorCode { + MUMBLE_EC_INTERNAL_ERROR = -2, + MUMBLE_EC_GENERIC_ERROR = -1, + MUMBLE_EC_OK = 0, + MUMBLE_EC_POINTER_NOT_FOUND, + MUMBLE_EC_NO_ACTIVE_CONNECTION, + MUMBLE_EC_USER_NOT_FOUND, + MUMBLE_EC_CHANNEL_NOT_FOUND, + MUMBLE_EC_CONNECTION_NOT_FOUND, + MUMBLE_EC_UNKNOWN_TRANSMISSION_MODE, + MUMBLE_EC_AUDIO_NOT_AVAILABLE, + MUMBLE_EC_INVALID_SAMPLE, + MUMBLE_EC_INVALID_PLUGIN_ID, + MUMBLE_EC_INVALID_MUTE_TARGET, + MUMBLE_EC_CONNECTION_UNSYNCHRONIZED, + MUMBLE_EC_INVALID_API_VERSION, + MUMBLE_EC_UNSYNCHRONIZED_BLOB, + MUMBLE_EC_UNKNOWN_SETTINGS_KEY, + MUMBLE_EC_WRONG_SETTINGS_TYPE, + MUMBLE_EC_SETTING_WAS_REMOVED, + MUMBLE_EC_DATA_TOO_BIG, + MUMBLE_EC_DATA_ID_TOO_LONG, + MUMBLE_EC_API_REQUEST_TIMEOUT, + MUMBLE_EC_OPERATION_UNSUPPORTED_BY_SERVER, +}; + +/** + * This enum's values represent error codes specific to the framework of handling positional data + * gathering (needed for Mumble's positional audio feature). + */ +enum Mumble_PositionalDataErrorCode { + /** + * Positional data has been initialized properly + */ + MUMBLE_PDEC_OK = 0, + /** + * Positional data is temporarily unavailable (e.g. because the corresponding process isn't running) but might be + * at another point in time. + */ + MUMBLE_PDEC_ERROR_TEMP, + /** + * Positional data is permanently unavailable (e.g. because the respective memory offsets are outdated). + */ + MUMBLE_PDEC_ERROR_PERM, +}; + +/** + * This enum's values represent keys for specific settings inside Mumble. + */ +enum Mumble_SettingsKey { + MUMBLE_SK_INVALID = -1, + MUMBLE_SK_AUDIO_INPUT_VOICE_HOLD = 0, + MUMBLE_SK_AUDIO_INPUT_VAD_SILENCE_THRESHOLD = 1, + MUMBLE_SK_AUDIO_INPUT_VAD_SPEECH_THRESHOLD = 2, + MUMBLE_SK_AUDIO_OUTPUT_PA_MINIMUM_DISTANCE = 3, + MUMBLE_SK_AUDIO_OUTPUT_PA_MAXIMUM_DISTANCE = 4, + MUMBLE_SK_AUDIO_OUTPUT_PA_BLOOM = 5, + MUMBLE_SK_AUDIO_OUTPUT_PA_MINIMUM_VOLUME = 6, +}; + +/** + * This enum's values represent the key-codes Mumble's API uses to reference keys on the keyboard. + */ +enum Mumble_KeyCode { + MUMBLE_KC_INVALID = -1, + + // Non-printable characters first + MUMBLE_KC_NULL = 0, + MUMBLE_KC_END = 1, + MUMBLE_KC_LEFT = 2, + MUMBLE_KC_RIGHT = 4, + MUMBLE_KC_UP = 5, + MUMBLE_KC_DOWN = 6, + MUMBLE_KC_DELETE = 7, + MUMBLE_KC_BACKSPACE = 8, + MUMBLE_KC_TAB = 9, + MUMBLE_KC_ENTER = 10, // == '\n' + MUMBLE_KC_ESCAPE = 27, + MUMBLE_KC_PAGE_UP = 11, + MUMBLE_KC_PAGE_DOWN = 12, + MUMBLE_KC_SHIFT = 13, + MUMBLE_KC_CONTROL = 14, + MUMBLE_KC_META = 15, + MUMBLE_KC_ALT = 16, + MUMBLE_KC_ALT_GR = 17, + MUMBLE_KC_CAPSLOCK = 18, + MUMBLE_KC_NUMLOCK = 19, + MUMBLE_KC_SUPER = 20, // == windows key + MUMBLE_KC_HOME = 21, // == Pos1 + MUMBLE_KC_PRINT = 22, + MUMBLE_KC_SCROLLLOCK = 23, + + // Printable characters are assigned to their ASCII code + MUMBLE_KC_SPACE = ' ', + MUMBLE_KC_EXCLAMATION_MARK = '!', + MUMBLE_KC_DOUBLE_QUOTE = '"', + MUMBLE_KC_HASHTAG = '#', + MUMBLE_KC_DOLLAR = '$', + MUMBLE_KC_PERCENT = '%', + MUMBLE_KC_AMPERSAND = '&', + MUMBLE_KC_SINGLE_QUOTE = '\'', + MUMBLE_KC_OPEN_PARENTHESIS = '(', + MUMBLE_KC_CLOSE_PARENTHESIS = ')', + MUMBLE_KC_ASTERISK = '*', + MUMBLE_KC_PLUS = '+', + MUMBLE_KC_COMMA = ',', + MUMBLE_KC_MINUS = '-', + MUMBLE_KC_PERIOD = '.', + MUMBLE_KC_SLASH = '/', + MUMBLE_KC_0 = '0', + MUMBLE_KC_1 = '1', + MUMBLE_KC_2 = '2', + MUMBLE_KC_3 = '3', + MUMBLE_KC_4 = '4', + MUMBLE_KC_5 = '5', + MUMBLE_KC_6 = '6', + MUMBLE_KC_7 = '7', + MUMBLE_KC_8 = '8', + MUMBLE_KC_9 = '9', + MUMBLE_KC_COLON = ':', + MUMBLE_KC_SEMICOLON = ';', + MUMBLE_KC_LESS_THAN = '<', + MUMBLE_KC_EQUALS = '=', + MUMBLE_KC_GREATER_THAN = '>', + MUMBLE_KC_QUESTION_MARK = '?', + MUMBLE_KC_AT_SYMBOL = '@', + MUMBLE_KC_A = 'A', + MUMBLE_KC_B = 'B', + MUMBLE_KC_C = 'C', + MUMBLE_KC_D = 'D', + MUMBLE_KC_E = 'E', + MUMBLE_KC_F = 'F', + MUMBLE_KC_G = 'G', + MUMBLE_KC_H = 'H', + MUMBLE_KC_I = 'I', + MUMBLE_KC_J = 'J', + MUMBLE_KC_K = 'K', + MUMBLE_KC_L = 'L', + MUMBLE_KC_M = 'M', + MUMBLE_KC_N = 'N', + MUMBLE_KC_O = 'O', + MUMBLE_KC_P = 'P', + MUMBLE_KC_Q = 'Q', + MUMBLE_KC_R = 'R', + MUMBLE_KC_S = 'S', + MUMBLE_KC_T = 'T', + MUMBLE_KC_U = 'U', + MUMBLE_KC_V = 'V', + MUMBLE_KC_W = 'W', + MUMBLE_KC_X = 'X', + MUMBLE_KC_Y = 'Y', + MUMBLE_KC_Z = 'Z', + // leave out lowercase letters (for now) + MUMBLE_KC_OPEN_BRACKET = '[', + MUMBLE_KC_BACKSLASH = '\\', + MUMBLE_KC_CLOSE_BRACKET = ']', + MUMBLE_KC_CIRCUMFLEX = '^', + MUMBLE_KC_UNDERSCORE = '_', + MUMBLE_KC_GRAVE_AKCENT = '`', + MUMBLE_KC_OPEN_BRACE = '{', + MUMBLE_KC_VERTICAL_BAR = '|', + MUMBLE_KC_CLOSE_BRACE = '}', + MUMBLE_KC_TILDE = '~', + + // Some characters from the extended ASCII code + MUMBLE_KC_DEGREE_SIGN = 176, + + + + // F-keys + // Start at a value of 256 as extended ASCII codes range up to 255 + MUMBLE_KC_F1 = 256, + MUMBLE_KC_F2 = 257, + MUMBLE_KC_F3 = 258, + MUMBLE_KC_F4 = 259, + MUMBLE_KC_F5 = 260, + MUMBLE_KC_F6 = 261, + MUMBLE_KC_F7 = 262, + MUMBLE_KC_F8 = 263, + MUMBLE_KC_F9 = 264, + MUMBLE_KC_F10 = 265, + MUMBLE_KC_F11 = 266, + MUMBLE_KC_F12 = 267, + MUMBLE_KC_F13 = 268, + MUMBLE_KC_F14 = 269, + MUMBLE_KC_F15 = 270, + MUMBLE_KC_F16 = 271, + MUMBLE_KC_F17 = 272, + MUMBLE_KC_F18 = 273, + MUMBLE_KC_F19 = 274, +}; + +/** + * A struct for representing a version of the form major.minor.patch + */ +struct MumbleVersion { + int32_t major; + int32_t minor; + int32_t patch; +# ifdef __cplusplus + explicit operator std::string() const { + return std::string("v") + std::to_string(this->major) + std::string(".") + std::to_string(this->minor) + + std::string(".") + std::to_string(this->patch); + } + +# ifdef MUMBLE_PLUGIN_HAS_QT + explicit operator QString() const { + return QString::fromLatin1("v%0.%1.%2").arg(this->major).arg(this->minor).arg(this->patch); + } +# endif +# endif // __cplusplus +}; + +/** + * This struct is used to return Strings from a plugin to Mumble. It is needed in order to + * work around the limitation of std::string not being part of C (it holds important information + * about the String's lifetime management requirements). + */ +struct MumbleStringWrapper { + /** + * The pointer to the actual String data + */ + const char *data; + /** + * The size of the pointed String data + */ + size_t size; + /** + * Whether the wrapped String needs to be released + * after its usage. Instances for which this would be + * false: Static Strings, String literals + */ + bool needsReleasing; +}; + +MUMBLE_EXTERN_C_END + +#endif // EXTERNAL_MUMBLE_PLUGIN_TYPES_ + + +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +///////////////////////////////////// Type aliases / Typedefs ///////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// + +#ifndef EXTERNAL_MUMBLE_PLUGIN_TYPEDEFS_ +# define EXTERNAL_MUMBLE_PLUGIN_TYPEDEFS_ + +/** + * Typedef for the type of a talking state + */ +typedef enum Mumble_TalkingState mumble_talking_state_t; +/** + * Typedef for the type of a transmission mode + */ +typedef enum Mumble_TransmissionMode mumble_transmission_mode_t; +/** + * Typedef for the type of a version + */ +typedef struct MumbleVersion mumble_version_t; +/** + * Typedef for the type of a connection + */ +typedef int32_t mumble_connection_t; +/** + * Typedef for the type of a user + */ +typedef uint32_t mumble_userid_t; +/** + * Typedef for the type of a channel + */ +typedef int32_t mumble_channelid_t; +/** + * Typedef for the type of an error (code) + */ +typedef enum Mumble_ErrorCode mumble_error_t; +/** + * Typedef for the type of a plugin ID + */ +typedef uint32_t mumble_plugin_id_t; +/** + * Typedef for the type of a key to a setting in Mumble + */ +typedef enum Mumble_SettingsKey mumble_settings_key_t; +/** + * Typedef for the type of a key-code + */ +typedef enum Mumble_KeyCode mumble_keycode_t; + +#endif // EXTERNAL_MUMBLE_PLUGIN_TYPEDEFS_ + + + +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +////////////////////////////////////// Non-enum Constants ///////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// + +#ifndef EXTERNAL_MUMBLE_PLUGIN_CONSTANTS_ +# define EXTERNAL_MUMBLE_PLUGIN_CONSTANTS_ + +/* + * Version constants + */ + +static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_INTERFACE_MAJOR = MUMBLE_PLUGIN_INTERFACE_MAJOR_MACRO; +static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_INTERFACE_MINOR = MUMBLE_PLUGIN_INTERFACE_MINOR_MACRO; +static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_INTERFACE_PATCH = MUMBLE_PLUGIN_INTERFACE_PATCH_MACRO; +static const MUMBLE_PLUGIN_CONSTEXPR mumble_version_t MUMBLE_PLUGIN_INTERFACE_VERSION = { + MUMBLE_PLUGIN_INTERFACE_MAJOR, MUMBLE_PLUGIN_INTERFACE_MINOR, MUMBLE_PLUGIN_INTERFACE_PATCH +}; + +static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_API_MAJOR = MUMBLE_PLUGIN_API_MAJOR_MACRO; +static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_API_MINOR = MUMBLE_PLUGIN_API_MINOR_MACRO; +static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_API_PATCH = MUMBLE_PLUGIN_API_PATCH_MACRO; +static const MUMBLE_PLUGIN_CONSTEXPR mumble_version_t MUMBLE_PLUGIN_API_VERSION = { MUMBLE_PLUGIN_API_MAJOR, + MUMBLE_PLUGIN_API_MINOR, + MUMBLE_PLUGIN_API_PATCH }; + +static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_FUNCTIONS_MAJOR = MUMBLE_PLUGIN_FUNCTIONS_MAJOR_MACRO; +static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_FUNCTIONS_MINOR = MUMBLE_PLUGIN_FUNCTIONS_MINOR_MACRO; +static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_FUNCTIONS_PATCH = MUMBLE_PLUGIN_FUNCTIONS_PATCH_MACRO; +static const MUMBLE_PLUGIN_CONSTEXPR mumble_version_t MUMBLE_PLUGIN_FUNCTIONS_VERSION = { + MUMBLE_PLUGIN_FUNCTIONS_MAJOR, MUMBLE_PLUGIN_FUNCTIONS_MINOR, MUMBLE_PLUGIN_FUNCTIONS_PATCH +}; + +/** + * The exit status of a successful operation + */ +static const MUMBLE_PLUGIN_CONSTEXPR mumble_error_t MUMBLE_STATUS_OK = MUMBLE_EC_OK; +/** + * A version object that is considered to correspond to an unknown version + */ +static const MUMBLE_PLUGIN_CONSTEXPR mumble_version_t MUMBLE_VERSION_UNKNOWN = { 0, 0, 0 }; + +#endif // EXTERNAL_MUMBLE_PLUGIN_CONSTANTS_ + + + +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////// C convenience implementations ///////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// + +#ifndef EXTERNAL_MUMBLE_PLUGIN_C_CONVENIENCE_IMPLS_ +# define EXTERNAL_MUMBLE_PLUGIN_C_CONVENIENCE_IMPLS_ + +/** + * Obtains a String representation for the given numeric error code. + * Note that the exact String representation corresponding to an error code may change and is thus + * not part of the plugin API as such. This function acts merely as a convenience helper for printing + * errors in a meaningful way. + * + * @param errorCode The error code to get the String representation for + * @returns The error message coresponding to the given error code. The message + * is encoded as a C-string and is static, meaning that it is safe to use the + * returned pointer in your code. + */ +MUMBLE_PLUGIN_CONSTEXPR inline const char *mumble_errorMessage(int16_t errorCode) { + switch (errorCode) { + case MUMBLE_EC_GENERIC_ERROR: + return "Generic error"; + case MUMBLE_EC_OK: + return "Ok - this is not an error"; + case MUMBLE_EC_POINTER_NOT_FOUND: + return "Can't find the passed pointer"; + case MUMBLE_EC_NO_ACTIVE_CONNECTION: + return "There is currently no active connection to a server"; + case MUMBLE_EC_USER_NOT_FOUND: + return "Can't find the requested user"; + case MUMBLE_EC_CHANNEL_NOT_FOUND: + return "Can't find the requested channel"; + case MUMBLE_EC_CONNECTION_NOT_FOUND: + return "Can't identify the requested connection"; + case MUMBLE_EC_UNKNOWN_TRANSMISSION_MODE: + return "Unknown transmission mode encountered"; + case MUMBLE_EC_AUDIO_NOT_AVAILABLE: + return "There is currently no audio output available"; + case MUMBLE_EC_INVALID_SAMPLE: + return "Attempted to use invalid sample (can't play it)"; + case MUMBLE_EC_INVALID_PLUGIN_ID: + return "Used an invalid plugin ID"; + case MUMBLE_EC_INVALID_MUTE_TARGET: + return "Used an invalid mute-target"; + case MUMBLE_EC_CONNECTION_UNSYNCHRONIZED: + return "The requested server connection has not yet finished synchronizing"; + case MUMBLE_EC_INVALID_API_VERSION: + return "The used API version is invalid or not supported"; + case MUMBLE_EC_UNSYNCHRONIZED_BLOB: + return "The requested blob (content) has not yet been synchronized between the client and the server"; + case MUMBLE_EC_UNKNOWN_SETTINGS_KEY: + return "The used settings-key does not match any key known to Mumble"; + case MUMBLE_EC_WRONG_SETTINGS_TYPE: + return "The referenced setting has a different type than requested"; + case MUMBLE_EC_SETTING_WAS_REMOVED: + return "The referenced setting got removed from Mumble and is no longer used"; + case MUMBLE_EC_DATA_TOO_BIG: + return "The given data is too large (exceeds limit)"; + case MUMBLE_EC_DATA_ID_TOO_LONG: + return "The given data ID is too long (exceeds limit)"; + case MUMBLE_EC_API_REQUEST_TIMEOUT: + return "A blocking API call took too long and was thus aborted (probably preventing a deadlock)"; + case MUMBLE_EC_OPERATION_UNSUPPORTED_BY_SERVER: + return "The requested API operation depends on server-side functionality, not supported by the server " + "you're connected to"; + } + + return "Unknown error code"; +} +#endif // EXTERNAL_MUMBLE_PLUGIN_C_CONVENIENCE_IMPLS_ + + + +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +////////////////////////////////// C++ convenience implementations //////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// + +#if !defined(EXTERNAL_MUMBLE_PLUGIN_CPP_CONVENIENCE_IMPLS_) && defined(__cplusplus) +# define EXTERNAL_MUMBLE_PLUGIN_CPP_CONVENIENCE_IMPLS_ + +/* + * Comparison operator overloads for MumbleVersion structs + */ +constexpr bool operator<(const MumbleVersion &lhs, const MumbleVersion &rhs) { + if (lhs.major != rhs.major) { + return lhs.major < rhs.major; + } + if (lhs.minor != rhs.minor) { + return lhs.minor < rhs.minor; + } + // Major and Minor are equal + return lhs.patch < rhs.patch; +} + +constexpr bool operator==(const MumbleVersion &lhs, const MumbleVersion &rhs) { + return lhs.major == rhs.major && lhs.minor == rhs.minor && lhs.patch == rhs.patch; +} + + +constexpr bool operator!=(const MumbleVersion &lhs, const MumbleVersion &rhs) { + return !(lhs == rhs); +} + +constexpr bool operator>(const MumbleVersion &lhs, const MumbleVersion &rhs) { + return !(lhs == rhs || lhs < rhs); +} + +constexpr bool operator>=(const MumbleVersion &lhs, const MumbleVersion &rhs) { + return lhs == rhs || lhs > rhs; +} + +constexpr bool operator<=(const MumbleVersion &lhs, const MumbleVersion &rhs) { + return lhs == rhs || lhs < rhs; +} + +#endif // EXTERNAL_MUMBLE_PLUGIN_CPP_CONVENIENCE_IMPLS_ + + + +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////// Plugin functions ////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// + +#ifndef EXTERNAL_MUMBLE_PLUGIN_FUNCTIONS_ +# define EXTERNAL_MUMBLE_PLUGIN_FUNCTIONS_ + +# include +# include +# include + +MUMBLE_EXTERN_C_BEGIN + +// >>>>>>>>>>>>>>>>>>>> MANDATORY functions <<<<<<<<<<<<<<<<<<<< + +/** + * Gets called right after loading the plugin in order to let the plugin initialize. + * + * Registers the ID of this plugin. + * @param id The ID for this plugin. This is the ID Mumble will reference this plugin with + * and by which this plugin can identify itself when communicating with Mumble. + * @returns The status of the initialization. If everything went fine, return STATUS_OK + */ +MUMBLE_PLUGIN_EXPORT mumble_error_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_init(mumble_plugin_id_t id); + +/** + * Gets called when unloading the plugin in order to allow it to clean up after itself. + * Note that it is still safe to call API functions from within this callback. + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_shutdown(); + +/** + * Gets the name of the plugin. + * + * NOTE: This function may be called without the plugin being loaded + * + * @returns A String-wrapper containing the requested name + */ +MUMBLE_PLUGIN_EXPORT struct MumbleStringWrapper MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getName(); + +/** + * Gets the Version of the plugin-API this plugin intends to use. + * Mumble will decide whether this plugin is loadable or not based on the return value of this function. + * + * NOTE: This function may be called without the plugin being loaded + * + * @returns The respective API Version + */ +MUMBLE_PLUGIN_EXPORT mumble_version_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getAPIVersion(); + +/** + * Provides the MumbleAPI struct to the plugin. This struct contains function pointers that can be used + * to interact with the Mumble client. It is up to the plugin to store this struct somewhere if it wants to make use + * of it at some point. + * + * NOTE: This function may be called without the plugin being loaded + * + * @param api A pointer to the MumbleAPI struct. The API struct must be cast to the version corresponding to the + * user API version. If your plugin is e.g. using the 1.0.x API, then you have to cast this pointer to + * MumbleAPI_v_1_0_x. Note also that you **must not store this pointer**. It will become invalid. Therefore + * you have to copy the struct in order to use it later on. + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_registerAPIFunctions(void *apiStruct); + +/** + * Releases the resource pointed to by the given pointer. If the respective resource has been allocated before, + * this would be the time to free/delete it. + * The resources processed by this functions are only those that have been specifically allocated in order to return + * them in one of the plugin functions to Mumble (e.g. the String returned by mumble_getName) and has nothing to do + * with your plugin's internal resource management. + * In short: Only resources passed from the plugin to Mumble via a return value may be processed by this function. + * + * NOTE1: This function may be called without the plugin being loaded + * + * NOTE2: that the pointer might be pointing to memory that had to be allocated without the plugin being loaded. + * Therefore you should be very sure that there'll be another callback in which you want to free this memory, + * should you decide to not do it here (which is hereby explicitly advised against). + * + * NOTE3: The pointer is const as Mumble won't mess with the memory allocated by the plugin (no modifications). + * Nontheless this function is explicitly responsible for freeing the respective memory parts. If the memory has + * been allocated using malloc(), it needs to be freed using free() which requires a const-cast. If however the + * memory has been created using the new operator you have to cast the pointer back to its original type and then + * use the delete operator on it (no const-cast necessary in this case). + * See https://stackoverflow.com/questions/2819535/unable-to-free-const-pointers-in-c + * and https://stackoverflow.com/questions/941832/is-it-safe-to-delete-a-void-pointer + * + * @param pointer The pointer to the memory that needs free-ing + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_releaseResource(const void *pointer); + + + +// >>>>>>>>>>>>>>>>>>>> GENERAL functions <<<<<<<<<<<<<<<<<<<< + +/** + * Tells the plugin some basic information about the Mumble client loading it. + * This function will be the first one that is being called on this plugin - even before it is decided whether to load + * the plugin at all. + * + * @param mumbleVersion The Version of the Mumble client + * @param mumbleAPIVersion The Version of the plugin-API the Mumble client runs with + * @param minimumExpectedAPIVersion The minimum Version the Mumble clients expects this plugin to meet in order to load + * it + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_setMumbleInfo( + mumble_version_t mumbleVersion, mumble_version_t mumbleAPIVersion, mumble_version_t minimumExpectedAPIVersion); + +/** + * Gets the Version of this plugin + * + * NOTE: This function may be called without the plugin being loaded + * + * @returns The plugin's version + */ +MUMBLE_PLUGIN_EXPORT mumble_version_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getVersion(); + +/** + * Gets the name of the plugin author(s). + * + * NOTE: This function may be called without the plugin being loaded + * + * @returns A String-wrapper containing the requested author name(s) + */ +MUMBLE_PLUGIN_EXPORT struct MumbleStringWrapper MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getAuthor(); + +/** + * Gets the description of the plugin. + * + * NOTE: This function may be called without the plugin being loaded + * + * @returns A String-wrapper containing the requested description + */ +MUMBLE_PLUGIN_EXPORT struct MumbleStringWrapper MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getDescription(); + +/** + * Gets the feature set of this plugin. The feature set is described by bitwise or'ing the elements of the + * Mumble_PluginFeature enum together. + * + * NOTE: This function may be called without the plugin being loaded + * + * @returns The feature set of this plugin + */ +MUMBLE_PLUGIN_EXPORT uint32_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getFeatures(); + +/** + * Requests this plugin to deactivate the given (sub)set of provided features. + * If this is not possible, the features that can't be deactivated shall be returned by this function. + * + * Example (check if FEATURE_POSITIONAL shall be deactivated): + * @code + * if (features & FEATURE_POSITIONAL) { + * // positional shall be deactivated + * } + * @endcode + * + * @param features The feature set that shall be deactivated + * @returns The feature set that can't be disabled (bitwise or'ed). If all requested features can be disabled, return + * FEATURE_NONE. If none of the requested features can be disabled return the unmodified features parameter. + */ +MUMBLE_PLUGIN_EXPORT uint32_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_deactivateFeatures(uint32_t features); + + +// >>>>>>>>>>>>>>>>>>>> POSITIONAL DATA functions <<<<<<<<<<<<<<<<<<<< + +/* + * If this plugin wants to provide positional data, the mumble_initPositionalData, mumble_fetchPositionalData + * and mumble_shutdownPositionalData functions have to be implemented together (implementing only a subset + * will yield the same result as if no support for positional data was implemened). + */ + +/** + * Indicates that Mumble wants to use this plugin to request positional data. Therefore it should check whether it is + * currently able to do so and allocate memory that is needed for that process. As a parameter this function gets an + * array of names and an array of PIDs. They are of same length and the PID at index i belongs to a program whose name + * is listed at index i in the "name-array". + * + * @param programNames An array of pointers to the program names + * @param programPIDs An array of the corresponding program PIDs + * @param programCount The length of programNames and programPIDs + * @returns The error code. If everything went fine PDEC_OK shall be returned. In that case Mumble will start + * frequently calling fetchPositionalData. If this returns anything but PDEC_OK, Mumble will assume that the plugin is + * (currently) uncapable of providing positional data. In this case this function must not have allocated any memory + * that needs to be cleaned up later on. Depending on the returned error code, Mumble might try to call this function + * again at some point. + */ +MUMBLE_PLUGIN_EXPORT uint8_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_initPositionalData(const char *const *programNames, + const uint64_t *programPIDs, + size_t programCount); + +/** + * Retrieves the positional data. If no data can be fetched, set all float-vectors to 0 and return false. + * + * @param[out] avatarPos A float-array of size 3 representing the cartesian position of the player/avatar in the ingame + * world. One unit represents one meter of distance. + * @param[out] avatarDir A float-array of size 3 representing the cartesian direction-vector of the player/avatar + * ingame (where it is facing). + * @param[out] avatarAxis A float-array of size 3 representing the vector pointing from the toes of the character to + * its head. One unit represents one meter of distance. + * @param[out] cameraPos A float-array of size 3 representing the cartesian position of the camera in the ingame world. + * One unit represents one meter of distance. + * @param[out] cameraDir A float-array of size 3 representing the cartesian direction-vector of the camera ingame + * (where it is facing). + * @param[out] cameraAxis A float-array of size 3 representing a vector from the bottom of the camera to its top. One + * unit represents one meter of distance. + * @param[out] context A pointer to where the pointer to a C-encoded string storing the context of the provided + * positional data shall be written. This context should include information about the server (and team) the player is + * on. Only players with identical context will be able to hear each other's audio. The returned pointer has to remain + * valid until the next invokation of this function or until shutdownPositionalData is called. + * @param[out] identity A pointer to where the pointer to a C-encoded string storing the identity of the player shall + * be written. It can be polled by external scripts from the server and should uniquely identify the player in the + * game. The pointer has to remain valid until the next invokation of this function or until shutdownPositionalData is + * called. + * @returns Whether this plugin can continue delivering positional data. If this function returns false, + * shutdownPositionalData will be called. + */ +MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION + mumble_fetchPositionalData(float *avatarPos, float *avatarDir, float *avatarAxis, float *cameraPos, + float *cameraDir, float *cameraAxis, const char **context, const char **identity); + +/** + * Indicates that this plugin will not be asked for positional data any longer. Thus any memory allocated for this + * purpose should be freed at this point. + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_shutdownPositionalData(); + +/** + * The context in positional data is used to determine whether different positional data sets from different + * clients belong to the same game (and same server). Only if the contexts matches up across these clients, + * will Mumble activate the positional audio effects, as it will assume that these clients are playing the + * same game together. + * The context is set during fetching of the other positional data and is usually something like e.g. the + * current server's name. In order to avoid clashes between different plugins (that most likely work for + * different games), the context is prefixed by Mumble. If this function is not implemented, the name of + * the plugin is used as a prefix (which tends to be the supported game's name), but sometimes a different + * prefix is desirable. For these cases, a custom prefix can be provided through this function. + * + * NOTE that while it is possible to allocate a string for this purpose every time this function is called + * and then letting mumble release the resource again (via mumble_releaseResource), it is generally not the + * advised way of doing things (it may impact overall performance negatively, since this function will be + * called very frequently). Instead you should either return a static string (if your language supports that + * and if it actually fits your needs) or you should allocate a string during mumble_initPositionalData and + * free it in mumble_shutdownPositionalData and when returning the string in this function, tell Mumble that + * the string does not need releasing. + * + * @returns The context prefix to use for positional data fetched by this plugin. + * + * @since Plugin interface v1.1.0 + */ +MUMBLE_PLUGIN_EXPORT struct MumbleStringWrapper MUMBLE_PLUGIN_CALLING_CONVENTION + mumble_getPositionalDataContextPrefix(); + + + +// >>>>>>>>>>>>>>>>>>>> EVENTHANDLER / CALLBACK functions <<<<<<<<<<<<<<<<<<<< + +/** + * Called when connecting to a server. + * Note that in most cases you'll want to use mumble_onServerSynchronized instead. + * Note also that this callback will be called from a DIFFERENT THREAD! + * + * @param connection The ID of the newly established server-connection + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onServerConnected(mumble_connection_t connection); + +/** + * Called when disconnecting from a server. + * Note that this callback is called from a DIFFERENT THREAD! + * + * @param connection The ID of the server-connection that has been terminated + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onServerDisconnected(mumble_connection_t connection); + +/** + * Called when the client has finished synchronizing with the server + * + * @param connection The ID of the server-connection that has been terminated + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onServerSynchronized(mumble_connection_t connection); + +/** + * Called whenever any user on the server enters a channel + * This function will also be called when freshly connecting to a server as each user on that + * server needs to be "added" to the respective channel as far as the local client is concerned. + * + * @param connection The ID of the server-connection this event is connected to + * @param userID The ID of the user this event has been triggered for + * @param previousChannelID The ID of the chanel the user is coming from. Negative IDs indicate that there is no + * previous channel (e.g. the user freshly connected to the server) or the channel isn't available because of any other + * reason. + * @param newChannelID The ID of the channel the user has entered. If the ID is negative, the new channel could not be + * retrieved. This means that the ID is invalid. + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onChannelEntered(mumble_connection_t connection, + mumble_userid_t userID, + mumble_channelid_t previousChannelID, + mumble_channelid_t newChannelID); + +/** + * Called whenever a user leaves a channel. + * This includes a client disconnecting from the server as this will also lead to the user not being in that channel + * anymore. + * + * @param connection The ID of the server-connection this event is connected to + * @param userID The ID of the user that left the channel + * @param channelID The ID of the channel the user left. If the ID is negative, the channel could not be retrieved. + * This means that the ID is invalid. + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onChannelExited(mumble_connection_t connection, + mumble_userid_t userID, + mumble_channelid_t channelID); + +/** + * Called when any user changes his/her talking state. + * + * @param connection The ID of the server-connection this event is connected to + * @param userID The ID of the user whose talking state has been changed + * @param talkingState The new TalkingState the user has switched to. + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onUserTalkingStateChanged( + mumble_connection_t connection, mumble_userid_t userID, mumble_talking_state_t talkingState); + +/** + * Called whenever there is audio input. + * Note that this callback will be called from the AUDIO THREAD. + * Note also that blocking this callback will cause Mumble's audio processing to get suspended. + * + * @param inputPCM A pointer to a short-array holding the pulse-code-modulation (PCM) representing the audio input. Its + * length is sampleCount * channelCount. The PCM format for stereo input is [LRLRLR...] where L and R are samples of + * the left and right channel respectively. + * @param sampleCount The amount of sample points per channel + * @param channelCount The amount of channels in the audio + * @param sampleRate The used sample rate in Hz + * @param isSpeech A boolean flag indicating whether Mumble considers the input as part of speech (instead of + * background noise) + * @returns Whether this callback has modified the audio input-array + */ +MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onAudioInput(short *inputPCM, uint32_t sampleCount, + uint16_t channelCount, + uint32_t sampleRate, bool isSpeech); + +/** + * Called whenever Mumble fetches data from an active audio source (could be a voice packet or a playing sample). + * The provided audio buffer is the raw buffer without any processing applied to it yet. + * Note that this callback will be called from the AUDIO THREAD. + * Note also that blocking this callback will cause Mumble's audio processing to get suspended. + * + * @param outputPCM A pointer to a float-array holding the pulse-code-modulation (PCM) representing the audio output. + * Its length is sampleCount * channelCount. The PCM format for stereo output is [LRLRLR...] where L and R are samples + * of the left and right channel respectively. + * @param sampleCount The amount of sample points per channel + * @param channelCount The amount of channels in the audio + * @param sampleRate The used sample rate in Hz + * @param isSpeech Whether this audio belongs to a received voice packet (and will thus (most likely) contain speech) + * @param userID If isSpeech is true, this contains the ID of the user this voice packet belongs to. If isSpeech is + * false, the content of this parameter is unspecified and should not be accessed + * @returns Whether this callback has modified the audio output-array + */ +MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION + mumble_onAudioSourceFetched(float *outputPCM, uint32_t sampleCount, uint16_t channelCount, uint32_t sampleRate, + bool isSpeech, mumble_userid_t userID); + +/** + * Called whenever the fully mixed and processed audio is about to be handed to the audio backend (about to be played). + * Note that this happens immediately before Mumble clips the audio buffer. + * Note that this callback will be called from the AUDIO THREAD. + * Note also that blocking this callback will cause Mumble's audio processing to get suspended. + * + * @param outputPCM A pointer to a float-array holding the pulse-code-modulation (PCM) representing the audio output. + * Its length is sampleCount * channelCount. The PCM format for stereo output is [LRLRLR...] where L and R are samples + * of the left and right channel respectively. + * @param sampleCount The amount of sample points per channel + * @param channelCount The amount of channels in the audio + * @param sampleRate The used sample rate in Hz + * @returns Whether this callback has modified the audio output-array + */ +MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onAudioOutputAboutToPlay(float *outputPCM, + uint32_t sampleCount, + uint16_t channelCount, + uint32_t sampleRate); + +/** + * Called whenever data has been received that has been sent by a plugin. This data should only be processed by the + * intended plugin. For this reason a dataID is provided that should be used to determine whether the data is intended + * for this plugin or not. As soon as the data has been processed, no further plugins will be notified about it. + * + * @param connection The ID of the server-connection the data is coming from + * @param sender The ID of the user whose client's plugin has sent the data + * @param data The sent data array. This can be an arbitrary sequence of bytes. + * @param dataLength The length of the data array + * @param dataID The ID of this data (C-encoded) + * @return Whether the given data has been processed by this plugin + */ +MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onReceiveData(mumble_connection_t connection, + mumble_userid_t sender, + const uint8_t *data, size_t dataLength, + const char *dataID); + +/** + * Called when a new user gets added to the user model. This is the case when that new user freshly connects to the + * server the local user is on but also when the local user connects to a server other clients are already connected to + * (in this case this method will be called for every client already on that server). + * + * @param connection An object used to identify the current connection + * @param userID The ID of the user that has been added + */ + +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onUserAdded(mumble_connection_t connection, + mumble_userid_t userID); + +/** + * Called when a user gets removed from the user model. This is the case when that user disconnects from the server the + * local user is on but also when the local user disconnects from a server other clients are connected to (in this case + * this method will be called for every client on that server). + * + * @param connection An object used to identify the current connection + * @param userID The ID of the user that has been removed + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onUserRemoved(mumble_connection_t connection, + mumble_userid_t userID); + +/** + * Called when a new channel gets added to the user model. This is the case when a new channel is created on the server + * the local user is on but also when the local user connects to a server that contains channels other than the + * root-channel (in this case this method will be called for ever non-root channel on that server). + * + * @param connection An object used to identify the current connection + * @param channelID The ID of the channel that has been added + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onChannelAdded(mumble_connection_t connection, + mumble_channelid_t channelID); + +/** + * Called when a channel gets removed from the user model. This is the case when a channel is removed on the server the + * local user is on but also when the local user disconnects from a server that contains channels other than the + * root-channel (in this case this method will be called for ever non-root channel on that server). + * + * @param connection An object used to identify the current connection + * @param channelID The ID of the channel that has been removed + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onChannelRemoved(mumble_connection_t connection, + mumble_channelid_t channelID); + +/** + * Called when a channel gets renamed. This also applies when a new channel is created (thus assigning it an initial + * name is also considered renaming). + * + * @param connection An object used to identify the current connection + * @param channelID The ID of the channel that has been renamed + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onChannelRenamed(mumble_connection_t connection, + mumble_channelid_t channelID); + +/** + * Called when a key has been pressed or released while Mumble has keyboard focus. + * Note that this callback will only work if the user has explicitly given permission to monitor keyboard + * events for this plugin. Thus if you want to use this callback, make sure your users know that they have to + * enable that. + * + * @param keyCode The key code of the respective key. The character codes are defined + * via the Mumble_KeyCode enum. For printable 7-bit ASCII characters these codes conform + * to the ASCII code-page with the only difference that case is not distinguished. Therefore + * always the upper-case letter code will be used for letters. + * @param wasPres Whether the respective key has been pressed (instead of released) + */ +MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onKeyEvent(uint32_t keyCode, bool wasPress); + + + +// >>>>>>>>>>>>>>>>>>>> PLUGIN UPDATE functions <<<<<<<<<<<<<<<<<<<< + +/** + * This function is used to determine whether the plugin can find an update for itself that is available for download. + * + * NOTE: This function may be called without the plugin being loaded + * + * @return Whether the plugin was able to find an update for itself + */ +MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION mumble_hasUpdate(); + +/** + * This function is used to retrieve the URL for downloading the newer/updated version of this plugin. + * + * NOTE: This function may be called without the plugin being loaded + * + * @returns A String-wrapper containing the requested URL + */ +MUMBLE_PLUGIN_EXPORT struct MumbleStringWrapper MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getUpdateDownloadURL(); + + + +// >>>>>>>>>>>>>>>>>>>> DEFAULT functions <<<<<<<<<<<<<<<<<<<< +// These functions don't have to be implemented by you + +/** + * Gets the version of the plugin functions interface that this plugin uses or wants to use. + * Based on this, Mumble will decide what kind of functions to look for and load from your plugin. + */ +MUMBLE_PLUGIN_EXPORT mumble_version_t mumble_getPluginFunctionsVersion(); + +MUMBLE_EXTERN_C_END +#endif // EXTERNAL_MUMBLE_PLUGIN_FUNCTIONS_ + + +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +///////////////////////////////// DEFAULT IMPLEMENTATIONS ///////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// + +#ifndef EXTERNAL_MUMBLE_PLUGIN_DEFAULT_IMPLEMENTATIONS_ +# define EXTERNAL_MUMBLE_PLUGIN_DEFAULT_IMPLEMENTATIONS_ + +mumble_version_t mumble_getPluginFunctionsVersion() { + return MUMBLE_PLUGIN_FUNCTIONS_VERSION; +} + +#endif // EXTERNAL_MUMBLE_PLUGIN_DEFAULT_IMPLEMENTATIONS_ + + + +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +//////////////////////////////////////// Mumble API /////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// +/////////////////////////////////////////////////////////////////////////////////////////////////////// + +#ifndef EXTERNAL_MUMBLE_PLUGIN_MUMBLE_API_ +# define EXTERNAL_MUMBLE_PLUGIN_MUMBLE_API_ + +// Define a struct name that contains the respective version number +# undef MUMBLE_API_STRUCT_NAME +# define MUMBLE_API_STRUCT_NAME \ + MUMBLE_ECONCAT( \ + MUMBLE_ECONCAT(MUMBLE_ECONCAT(MumbleAPI_v, MUMBLE_PLUGIN_API_MAJOR_MACRO), MUMBLE_PLUGIN_API_MINOR_MACRO), \ + x) + +// Define some helper macros to make version-specific changes to the API functions +# define SELECTED_API_VERSION \ + MUMBLE_PLUGIN_VERSION_CHECK(MUMBLE_PLUGIN_API_MAJOR_MACRO, MUMBLE_PLUGIN_API_MINOR_MACRO, \ + MUMBLE_PLUGIN_API_PATCH_MACRO) +# if SELECTED_API_VERSION >= MUMBLE_PLUGIN_VERSION_CHECK(1, 2, 0) +# define PARAM_v1_2(arg) , arg +# else +# define PARAM_v1_2(arg) +# endif + +struct MUMBLE_API_STRUCT_NAME { + /* + * GENERAL NOTES + * + * All functions that take in a connection as a parameter 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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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(MUMBLE_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) + * @param volume The volume multiplier used when playing the sample (for no change use 1.0f) + * @returns The error code. If everything went well, STATUS_OK will be returned. + */ + mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *playSample)(mumble_plugin_id_t callerID, + const char *samplePath PARAM_v1_2(float volume)); +}; + +# ifdef MUMBLE_PLUGIN_CREATE_MUMBLE_API_TYPEDEF +/** + * Typedef for the Mumble API struct for convenient (unversioned) access + */ +typedef struct MUMBLE_API_STRUCT_NAME MumbleAPI; +# endif + +# undef SELECTED_API_VERSION +# undef MUMBLE_API_STRUCT_NAME +# undef PARAM_v1_2 + +#endif // EXTERNAL_MUMBLE_PLUGIN_MUMBLE_API_ diff --git a/plugins/MumblePlugin_v_1_0_x.h b/plugins/MumblePlugin_v_1_0_x.h deleted file mode 100644 index f309a8d90eb..00000000000 --- a/plugins/MumblePlugin_v_1_0_x.h +++ /dev/null @@ -1,439 +0,0 @@ -// Copyright 2021-2023 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 . - -/// This header file specifies the Mumble plugin interface - -#ifndef EXTERNAL_MUMBLE_PLUGIN_H_ -#define EXTERNAL_MUMBLE_PLUGIN_H_ - -#include "MumbleAPI_v_1_0_x.h" -#include "PluginComponents_v_1_0_x.h" -#include -#include -#include - -#if defined(__GNUC__) && !defined(__MINGW32__) // GCC on Unix-like systems -# define PLUGIN_EXPORT __attribute__((visibility("default"))) -#elif defined(_MSC_VER) -# define PLUGIN_EXPORT __declspec(dllexport) -#elif defined(__MINGW32__) -# define PLUGIN_EXPORT __attribute__((dllexport)) -#else -# error No PLUGIN_EXPORT definition available -#endif - - -// Plugin functions version -#define MUMBLE_PLUGIN_FUNCTIONS_MAJOR_MACRO 1 -#define MUMBLE_PLUGIN_FUNCTIONS_MINOR_MACRO 0 -#define MUMBLE_PLUGIN_FUNCTIONS_PATCH_MACRO 1 - -const int32_t MUMBLE_PLUGIN_FUNCTIONS_MAJOR = MUMBLE_PLUGIN_FUNCTIONS_MAJOR_MACRO; -const int32_t MUMBLE_PLUGIN_FUNCTIONS_MINOR = MUMBLE_PLUGIN_FUNCTIONS_MINOR_MACRO; -const int32_t MUMBLE_PLUGIN_FUNCTIONS_PATCH = MUMBLE_PLUGIN_FUNCTIONS_PATCH_MACRO; -const mumble_version_t MUMBLE_PLUGIN_FUNCTIONS_VERSION = { MUMBLE_PLUGIN_FUNCTIONS_MAJOR, MUMBLE_PLUGIN_FUNCTIONS_MINOR, - MUMBLE_PLUGIN_FUNCTIONS_PATCH }; - -#ifdef __cplusplus -extern "C" { -#endif - -////////////////////////////////////////////////////////////////////////////////// -////////////////////////////// MANDATORY FUNCTIONS /////////////////////////////// -////////////////////////////////////////////////////////////////////////////////// - -/// Gets called right after loading the plugin in order to let the plugin initialize. -/// -/// Registers the ID of this plugin. -/// @param id The ID for this plugin. This is the ID Mumble will reference this plugin with -/// and by which this plugin can identify itself when communicating with Mumble. -/// @returns The status of the initialization. If everything went fine, return STATUS_OK -PLUGIN_EXPORT mumble_error_t PLUGIN_CALLING_CONVENTION mumble_init(mumble_plugin_id_t id); - -/// Gets called when unloading the plugin in order to allow it to clean up after itself. -/// Note that it is still safe to call API functions from within this callback. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_shutdown(); - -/// Gets the name of the plugin. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns A String-wrapper containing the requested name -PLUGIN_EXPORT struct MumbleStringWrapper PLUGIN_CALLING_CONVENTION mumble_getName(); - -/// Gets the Version of the plugin-API this plugin intends to use. -/// Mumble will decide whether this plugin is loadable or not based on the return value of this function. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns The respective API Version -PLUGIN_EXPORT mumble_version_t PLUGIN_CALLING_CONVENTION mumble_getAPIVersion(); - -/// Provides the MumbleAPI struct to the plugin. This struct contains function pointers that can be used -/// to interact with the Mumble client. It is up to the plugin to store this struct somewhere if it wants to make use -/// of it at some point. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @param api A pointer to the MumbleAPI struct. The API struct must be cast to the version corresponding to the -/// user API version. If your plugin is e.g. using the 1.0.x API, then you have to cast this pointer to -/// MumbleAPI_v_1_0_x. Note also that you **must not store this pointer**. It will become invalid. Therefore -/// you have to copy the struct in order to use it later on. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_registerAPIFunctions(void *apiStruct); - -/// Releases the resource pointed to by the given pointer. If the respective resource has been allocated before, -/// this would be the time to free/delete it. -/// The resources processed by this functions are only those that have been specifically allocated in order to return -/// them in one of the plugin functions to Mumble (e.g. the String returned by mumble_getName) and has nothing to do -/// with your plugin's internal resource management. -/// In short: Only resources passed from the plugin to Mumble via a return value may be processed by this function. -/// -/// NOTE1: This function may be called without the plugin being loaded -/// -/// NOTE2: that the pointer might be pointing to memory that had to be allocated without the plugin being loaded. -/// Therefore you should be very sure that there'll be another callback in which you want to free this memory, -/// should you decide to not do it here (which is hereby explicitly advised against). -/// -/// NOTE3: The pointer is const as Mumble won't mess with the memory allocated by the plugin (no modifications). -/// Nontheless this function is explicitly responsible for freeing the respective memory parts. If the memory has -/// been allocated using malloc(), it needs to be freed using free() which requires a const-cast. If however the -/// memory has been created using the new operator you have to cast the pointer back to its original type and then -/// use the delete operator on it (no const-cast necessary in this case). -/// See https://stackoverflow.com/questions/2819535/unable-to-free-const-pointers-in-c -/// and https://stackoverflow.com/questions/941832/is-it-safe-to-delete-a-void-pointer -/// -/// @param pointer The pointer to the memory that needs free-ing -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_releaseResource(const void *pointer); - - - -////////////////////////////////////////////////////////////////////////////////// -///////////////////////////// GENERAL FUNCTIONS ////////////////////////////////// -////////////////////////////////////////////////////////////////////////////////// - -/// Tells the plugin some basic information about the Mumble client loading it. -/// This function will be the first one that is being called on this plugin - even before it is decided whether to load -/// the plugin at all. -/// -/// @param mumbleVersion The Version of the Mumble client -/// @param mumbleAPIVersion The Version of the plugin-API the Mumble client runs with -/// @param minimumExpectedAPIVersion The minimum Version the Mumble clients expects this plugin to meet in order to load -/// it -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_setMumbleInfo(mumble_version_t mumbleVersion, - mumble_version_t mumbleAPIVersion, - mumble_version_t minimumExpectedAPIVersion); - -/// Gets the Version of this plugin -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns The plugin's version -PLUGIN_EXPORT mumble_version_t PLUGIN_CALLING_CONVENTION mumble_getVersion(); - -/// Gets the name of the plugin author(s). -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns A String-wrapper containing the requested author name(s) -PLUGIN_EXPORT struct MumbleStringWrapper PLUGIN_CALLING_CONVENTION mumble_getAuthor(); - -/// Gets the description of the plugin. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns A String-wrapper containing the requested description -PLUGIN_EXPORT struct MumbleStringWrapper PLUGIN_CALLING_CONVENTION mumble_getDescription(); - -/// Gets the feature set of this plugin. The feature set is described by bitwise or'ing the elements of the -/// Mumble_PluginFeature enum together. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns The feature set of this plugin -PLUGIN_EXPORT uint32_t PLUGIN_CALLING_CONVENTION mumble_getFeatures(); - -/// Requests this plugin to deactivate the given (sub)set of provided features. -/// If this is not possible, the features that can't be deactivated shall be returned by this function. -/// -/// Example (check if FEATURE_POSITIONAL shall be deactivated): -/// @code -/// if (features & FEATURE_POSITIONAL) { -/// // positional shall be deactivated -/// }; -/// @endcode -/// -/// @param features The feature set that shall be deactivated -/// @returns The feature set that can't be disabled (bitwise or'ed). If all requested features can be disabled, return -/// FEATURE_NONE. If none of the requested features can be disabled return the unmodified features parameter. -PLUGIN_EXPORT uint32_t PLUGIN_CALLING_CONVENTION mumble_deactivateFeatures(uint32_t features); - - - -////////////////////////////////////////////////////////////////////////////////// -//////////////////////////// POSITIONAL DATA ///////////////////////////////////// -////////////////////////////////////////////////////////////////////////////////// -// If this plugin wants to provide positional data, ALL functions of this category -// have to be implemented - -/// Indicates that Mumble wants to use this plugin to request positional data. Therefore it should check whether it is -/// currently able to do so and allocate memory that is needed for that process. As a parameter this function gets an -/// array of names and an array of PIDs. They are of same length and the PID at index i belongs to a program whose name -/// is listed at index i in the "name-array". -/// -/// @param programNames An array of pointers to the program names -/// @param programPIDs An array of the corresponding program PIDs -/// @param programCount The length of programNames and programPIDs -/// @returns The error code. If everything went fine PDEC_OK shall be returned. In that case Mumble will start -/// frequently calling fetchPositionalData. If this returns anything but PDEC_OK, Mumble will assume that the plugin is -/// (currently) uncapable of providing positional data. In this case this function must not have allocated any memory -/// that needs to be cleaned up later on. Depending on the returned error code, Mumble might try to call this function -/// again at some point. -PLUGIN_EXPORT uint8_t PLUGIN_CALLING_CONVENTION mumble_initPositionalData(const char *const *programNames, - const uint64_t *programPIDs, - size_t programCount); - -/// Retrieves the positional data. If no data can be fetched, set all float-vectors to 0 and return false. -/// -/// @param[out] avatarPos A float-array of size 3 representing the cartesian position of the player/avatar in the ingame -/// world. One unit represents one meter of distance. -/// @param[out] avatarDir A float-array of size 3 representing the cartesian direction-vector of the player/avatar -/// ingame (where it is facing). -/// @param[out] avatarAxis A float-array of size 3 representing the vector pointing from the toes of the character to -/// its head. One unit represents one meter of distance. -/// @param[out] cameraPos A float-array of size 3 representing the cartesian position of the camera in the ingame world. -/// One unit represents one meter of distance. -/// @param[out] cameraDir A float-array of size 3 representing the cartesian direction-vector of the camera ingame -/// (where it is facing). -/// @param[out] cameraAxis A float-array of size 3 representing a vector from the bottom of the camera to its top. One -/// unit represents one meter of distance. -/// @param[out] context A pointer to where the pointer to a C-encoded string storing the context of the provided -/// positional data shall be written. This context should include information about the server (and team) the player is -/// on. Only players with identical context will be able to hear each other's audio. The returned pointer has to remain -/// valid until the next invokation of this function or until shutdownPositionalData is called. -/// @param[out] identity A pointer to where the pointer to a C-encoded string storing the identity of the player shall -/// be written. It can be polled by external scripts from the server and should uniquely identify the player in the -/// game. The pointer has to remain valid until the next invokation of this function or until shutdownPositionalData is -/// called. -/// @returns Whether this plugin can continue delivering positional data. If this function returns false, -/// shutdownPositionalData will be called. -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_fetchPositionalData(float *avatarPos, float *avatarDir, - float *avatarAxis, float *cameraPos, - float *cameraDir, float *cameraAxis, - const char **context, const char **identity); - -/// Indicates that this plugin will not be asked for positional data any longer. Thus any memory allocated for this -/// purpose should be freed at this point. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_shutdownPositionalData(); - - - -////////////////////////////////////////////////////////////////////////////////// -////////////////////// EVENTHANDLERS / CALLBACK FUNCTIONS //////////////////////// -////////////////////////////////////////////////////////////////////////////////// - -/// Called when connecting to a server. -/// Note that in most cases you'll want to use mumble_onServerSynchronized instead. -/// Note also that this callback will be called from a DIFFERENT THREAD! -/// -/// @param connection The ID of the newly established server-connection -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onServerConnected(mumble_connection_t connection); - -/// Called when disconnecting from a server. -/// Note that this callback is called from a DIFFERENT THREAD! -/// -/// @param connection The ID of the server-connection that has been terminated -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onServerDisconnected(mumble_connection_t connection); - -/// Called when the client has finished synchronizing with the server -/// -/// @param connection The ID of the server-connection that has been terminated -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onServerSynchronized(mumble_connection_t connection); - -/// Called whenever any user on the server enters a channel -/// This function will also be called when freshly connecting to a server as each user on that -/// server needs to be "added" to the respective channel as far as the local client is concerned. -/// -/// @param connection The ID of the server-connection this event is connected to -/// @param userID The ID of the user this event has been triggered for -/// @param previousChannelID The ID of the chanel the user is coming from. Negative IDs indicate that there is no -/// previous channel (e.g. the user freshly connected to the server) or the channel isn't available because of any other -/// reason. -/// @param newChannelID The ID of the channel the user has entered. If the ID is negative, the new channel could not be -/// retrieved. This means that the ID is invalid. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onChannelEntered(mumble_connection_t connection, - mumble_userid_t userID, - mumble_channelid_t previousChannelID, - mumble_channelid_t newChannelID); - -/// Called whenever a user leaves a channel. -/// This includes a client disconnecting from the server as this will also lead to the user not being in that channel -/// anymore. -/// -/// @param connection The ID of the server-connection this event is connected to -/// @param userID The ID of the user that left the channel -/// @param channelID The ID of the channel the user left. If the ID is negative, the channel could not be retrieved. -/// This means that the ID is invalid. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onChannelExited(mumble_connection_t connection, - mumble_userid_t userID, - mumble_channelid_t channelID); - -/// Called when any user changes his/her talking state. -/// -/// @param connection The ID of the server-connection this event is connected to -/// @param userID The ID of the user whose talking state has been changed -/// @param talkingState The new TalkingState the user has switched to. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onUserTalkingStateChanged(mumble_connection_t connection, - mumble_userid_t userID, - mumble_talking_state_t talkingState); - -/// Called whenever there is audio input. -/// Note that this callback will be called from the AUDIO THREAD. -/// Note also that blocking this callback will cause Mumble's audio processing to get suspended. -/// -/// @param inputPCM A pointer to a short-array holding the pulse-code-modulation (PCM) representing the audio input. Its -/// length is sampleCount * channelCount. The PCM format for stereo input is [LRLRLR...] where L and R are samples of -/// the left and right channel respectively. -/// @param sampleCount The amount of sample points per channel -/// @param channelCount The amount of channels in the audio -/// @param sampleRate The used sample rate in Hz -/// @param isSpeech A boolean flag indicating whether Mumble considers the input as part of speech (instead of -/// background noise) -/// @returns Whether this callback has modified the audio input-array -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_onAudioInput(short *inputPCM, uint32_t sampleCount, - uint16_t channelCount, uint32_t sampleRate, - bool isSpeech); - -/// Called whenever Mumble fetches data from an active audio source (could be a voice packet or a playing sample). -/// The provided audio buffer is the raw buffer without any processing applied to it yet. -/// Note that this callback will be called from the AUDIO THREAD. -/// Note also that blocking this callback will cause Mumble's audio processing to get suspended. -/// -/// @param outputPCM A pointer to a float-array holding the pulse-code-modulation (PCM) representing the audio output. -/// Its length is sampleCount * channelCount. The PCM format for stereo output is [LRLRLR...] where L and R are samples -/// of the left and right channel respectively. -/// @param sampleCount The amount of sample points per channel -/// @param channelCount The amount of channels in the audio -/// @param sampleRate The used sample rate in Hz -/// @param isSpeech Whether this audio belongs to a received voice packet (and will thus (most likely) contain speech) -/// @param userID If isSpeech is true, this contains the ID of the user this voice packet belongs to. If isSpeech is -/// false, the content of this parameter is unspecified and should not be accessed -/// @returns Whether this callback has modified the audio output-array -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_onAudioSourceFetched(float *outputPCM, uint32_t sampleCount, - uint16_t channelCount, uint32_t sampleRate, - bool isSpeech, mumble_userid_t userID); - -/// Called whenever the fully mixed and processed audio is about to be handed to the audio backend (about to be played). -/// Note that this happens immediately before Mumble clips the audio buffer. -/// Note that this callback will be called from the AUDIO THREAD. -/// Note also that blocking this callback will cause Mumble's audio processing to get suspended. -/// -/// @param outputPCM A pointer to a float-array holding the pulse-code-modulation (PCM) representing the audio output. -/// Its length is sampleCount * channelCount. The PCM format for stereo output is [LRLRLR...] where L and R are samples -/// of the left and right channel respectively. -/// @param sampleCount The amount of sample points per channel -/// @param channelCount The amount of channels in the audio -/// @param sampleRate The used sample rate in Hz -/// @returns Whether this callback has modified the audio output-array -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_onAudioOutputAboutToPlay(float *outputPCM, uint32_t sampleCount, - uint16_t channelCount, - uint32_t sampleRate); - -/// Called whenever data has been received that has been sent by a plugin. This data should only be processed by the -/// intended plugin. For this reason a dataID is provided that should be used to determine whether the data is intended -/// for this plugin or not. As soon as the data has been processed, no further plugins will be notified about it. -/// -/// @param connection The ID of the server-connection the data is coming from -/// @param sender The ID of the user whose client's plugin has sent the data -/// @param data The sent data array. This can be an arbitrary sequence of bytes. -/// @param dataLength The length of the data array -/// @param dataID The ID of this data (C-encoded) -/// @return Whether the given data has been processed by this plugin -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_onReceiveData(mumble_connection_t connection, - mumble_userid_t sender, const uint8_t *data, - size_t dataLength, const char *dataID); - -/// Called when a new user gets added to the user model. This is the case when that new user freshly connects to the -/// server the local user is on but also when the local user connects to a server other clients are already connected to -/// (in this case this method will be called for every client already on that server). -/// -/// @param connection An object used to identify the current connection -/// @param userID The ID of the user that has been added - -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onUserAdded(mumble_connection_t connection, mumble_userid_t userID); - -/// Called when a user gets removed from the user model. This is the case when that user disconnects from the server the -/// local user is on but also when the local user disconnects from a server other clients are connected to (in this case -/// this method will be called for every client on that server). -/// -/// @param connection An object used to identify the current connection -/// @param userID The ID of the user that has been removed -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onUserRemoved(mumble_connection_t connection, - mumble_userid_t userID); - -/// Called when a new channel gets added to the user model. This is the case when a new channel is created on the server -/// the local user is on but also when the local user connects to a server that contains channels other than the -/// root-channel (in this case this method will be called for ever non-root channel on that server). -/// -/// @param connection An object used to identify the current connection -/// @param channelID The ID of the channel that has been added -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onChannelAdded(mumble_connection_t connection, - mumble_channelid_t channelID); - -/// Called when a channel gets removed from the user model. This is the case when a channel is removed on the server the -/// local user is on but also when the local user disconnects from a server that contains channels other than the -/// root-channel (in this case this method will be called for ever non-root channel on that server). -/// -/// @param connection An object used to identify the current connection -/// @param channelID The ID of the channel that has been removed -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onChannelRemoved(mumble_connection_t connection, - mumble_channelid_t channelID); - -/// Called when a channel gets renamed. This also applies when a new channel is created (thus assigning it an initial -/// name is also considered renaming). -/// -/// @param connection An object used to identify the current connection -/// @param channelID The ID of the channel that has been renamed -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onChannelRenamed(mumble_connection_t connection, - mumble_channelid_t channelID); - -/// Called when a key has been pressed or released while Mumble has keyboard focus. -/// Note that this callback will only work if the user has explicitly given permission to monitor keyboard -/// events for this plugin. Thus if you want to use this callback, make sure your users know that they have to -/// enable that. -/// -/// @param keyCode The key code of the respective key. The character codes are defined -/// via the Mumble_KeyCode enum. For printable 7-bit ASCII characters these codes conform -/// to the ASCII code-page with the only difference that case is not distinguished. Therefore -/// always the upper-case letter code will be used for letters. -/// @param wasPres Whether the respective key has been pressed (instead of released) -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onKeyEvent(uint32_t keyCode, bool wasPress); - - - -////////////////////////////////////////////////////////////////////////////////// -////////////////////////////// PLUGIN UPDATES //////////////////////////////////// -////////////////////////////////////////////////////////////////////////////////// - -/// This function is used to determine whether the plugin can find an update for itself that is available for download. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @return Whether the plugin was able to find an update for itself -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_hasUpdate(); - -/// This function is used to retrieve the URL for downloading the newer/updated version of this plugin. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns A String-wrapper containing the requested URL -PLUGIN_EXPORT struct MumbleStringWrapper PLUGIN_CALLING_CONVENTION mumble_getUpdateDownloadURL(); - - -#ifdef __cplusplus -} -#endif - - -#endif diff --git a/plugins/MumblePlugin_v_1_1_x.h b/plugins/MumblePlugin_v_1_1_x.h deleted file mode 100644 index eb3b782f014..00000000000 --- a/plugins/MumblePlugin_v_1_1_x.h +++ /dev/null @@ -1,477 +0,0 @@ -// Copyright 2021-2023 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 . - -/// This header file specifies the Mumble plugin interface - -#ifndef EXTERNAL_MUMBLE_PLUGIN_H_ -#define EXTERNAL_MUMBLE_PLUGIN_H_ - -#include "PluginComponents_v_1_0_x.h" -#include -#include -#include - -#if defined(__GNUC__) && !defined(__MINGW32__) // GCC on Unix-like systems -# define PLUGIN_EXPORT __attribute__((visibility("default"))) -#elif defined(_MSC_VER) -# define PLUGIN_EXPORT __declspec(dllexport) -#elif defined(__MINGW32__) -# define PLUGIN_EXPORT __attribute__((dllexport)) -#else -# error No PLUGIN_EXPORT definition available -#endif - - -// Plugin functions version -#define MUMBLE_PLUGIN_FUNCTIONS_MAJOR_MACRO 1 -#define MUMBLE_PLUGIN_FUNCTIONS_MINOR_MACRO 1 -#define MUMBLE_PLUGIN_FUNCTIONS_PATCH_MACRO 0 - -const int32_t MUMBLE_PLUGIN_FUNCTIONS_MAJOR = MUMBLE_PLUGIN_FUNCTIONS_MAJOR_MACRO; -const int32_t MUMBLE_PLUGIN_FUNCTIONS_MINOR = MUMBLE_PLUGIN_FUNCTIONS_MINOR_MACRO; -const int32_t MUMBLE_PLUGIN_FUNCTIONS_PATCH = MUMBLE_PLUGIN_FUNCTIONS_PATCH_MACRO; -const mumble_version_t MUMBLE_PLUGIN_FUNCTIONS_VERSION = { MUMBLE_PLUGIN_FUNCTIONS_MAJOR, MUMBLE_PLUGIN_FUNCTIONS_MINOR, - MUMBLE_PLUGIN_FUNCTIONS_PATCH }; - -#ifdef __cplusplus -extern "C" { -#endif - -////////////////////////////////////////////////////////////////////////////////// -////////////////////////////// MANDATORY FUNCTIONS /////////////////////////////// -////////////////////////////////////////////////////////////////////////////////// - -/// Gets called right after loading the plugin in order to let the plugin initialize. -/// -/// Registers the ID of this plugin. -/// @param id The ID for this plugin. This is the ID Mumble will reference this plugin with -/// and by which this plugin can identify itself when communicating with Mumble. -/// @returns The status of the initialization. If everything went fine, return STATUS_OK -PLUGIN_EXPORT mumble_error_t PLUGIN_CALLING_CONVENTION mumble_init(mumble_plugin_id_t id); - -/// Gets called when unloading the plugin in order to allow it to clean up after itself. -/// Note that it is still safe to call API functions from within this callback. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_shutdown(); - -/// Gets the name of the plugin. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns A String-wrapper containing the requested name -PLUGIN_EXPORT struct MumbleStringWrapper PLUGIN_CALLING_CONVENTION mumble_getName(); - -/// Gets the Version of the plugin-API this plugin intends to use. -/// Mumble will decide whether this plugin is loadable or not based on the return value of this function. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns The respective API Version -PLUGIN_EXPORT mumble_version_t PLUGIN_CALLING_CONVENTION mumble_getAPIVersion(); - -/// Provides the MumbleAPI struct to the plugin. This struct contains function pointers that can be used -/// to interact with the Mumble client. It is up to the plugin to store this struct somewhere if it wants to make use -/// of it at some point. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @param api A pointer to the MumbleAPI struct. The API struct must be cast to the version corresponding to the -/// user API version. If your plugin is e.g. using the 1.0.x API, then you have to cast this pointer to -/// MumbleAPI_v_1_0_x. Note also that you **must not store this pointer**. It will become invalid. Therefore -/// you have to copy the struct in order to use it later on. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_registerAPIFunctions(void *apiStruct); - -/// Releases the resource pointed to by the given pointer. If the respective resource has been allocated before, -/// this would be the time to free/delete it. -/// The resources processed by this functions are only those that have been specifically allocated in order to return -/// them in one of the plugin functions to Mumble (e.g. the String returned by mumble_getName) and has nothing to do -/// with your plugin's internal resource management. -/// In short: Only resources passed from the plugin to Mumble via a return value may be processed by this function. -/// -/// NOTE1: This function may be called without the plugin being loaded -/// -/// NOTE2: that the pointer might be pointing to memory that had to be allocated without the plugin being loaded. -/// Therefore you should be very sure that there'll be another callback in which you want to free this memory, -/// should you decide to not do it here (which is hereby explicitly advised against). -/// -/// NOTE3: The pointer is const as Mumble won't mess with the memory allocated by the plugin (no modifications). -/// Nontheless this function is explicitly responsible for freeing the respective memory parts. If the memory has -/// been allocated using malloc(), it needs to be freed using free() which requires a const-cast. If however the -/// memory has been created using the new operator you have to cast the pointer back to its original type and then -/// use the delete operator on it (no const-cast necessary in this case). -/// See https://stackoverflow.com/questions/2819535/unable-to-free-const-pointers-in-c -/// and https://stackoverflow.com/questions/941832/is-it-safe-to-delete-a-void-pointer -/// -/// @param pointer The pointer to the memory that needs free-ing -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_releaseResource(const void *pointer); - - - -////////////////////////////////////////////////////////////////////////////////// -///////////////////////////// GENERAL FUNCTIONS ////////////////////////////////// -////////////////////////////////////////////////////////////////////////////////// - -/// Tells the plugin some basic information about the Mumble client loading it. -/// This function will be the first one that is being called on this plugin - even before it is decided whether to load -/// the plugin at all. -/// -/// @param mumbleVersion The Version of the Mumble client -/// @param mumbleAPIVersion The Version of the plugin-API the Mumble client runs with -/// @param minimumExpectedAPIVersion The minimum Version the Mumble clients expects this plugin to meet in order to load -/// it -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_setMumbleInfo(mumble_version_t mumbleVersion, - mumble_version_t mumbleAPIVersion, - mumble_version_t minimumExpectedAPIVersion); - -/// Gets the Version of this plugin -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns The plugin's version -PLUGIN_EXPORT mumble_version_t PLUGIN_CALLING_CONVENTION mumble_getVersion(); - -/// Gets the name of the plugin author(s). -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns A String-wrapper containing the requested author name(s) -PLUGIN_EXPORT struct MumbleStringWrapper PLUGIN_CALLING_CONVENTION mumble_getAuthor(); - -/// Gets the description of the plugin. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns A String-wrapper containing the requested description -PLUGIN_EXPORT struct MumbleStringWrapper PLUGIN_CALLING_CONVENTION mumble_getDescription(); - -/// Gets the feature set of this plugin. The feature set is described by bitwise or'ing the elements of the -/// Mumble_PluginFeature enum together. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns The feature set of this plugin -PLUGIN_EXPORT uint32_t PLUGIN_CALLING_CONVENTION mumble_getFeatures(); - -/// Requests this plugin to deactivate the given (sub)set of provided features. -/// If this is not possible, the features that can't be deactivated shall be returned by this function. -/// -/// Example (check if FEATURE_POSITIONAL shall be deactivated): -/// @code -/// if (features & FEATURE_POSITIONAL) { -/// // positional shall be deactivated -/// }; -/// @endcode -/// -/// @param features The feature set that shall be deactivated -/// @returns The feature set that can't be disabled (bitwise or'ed). If all requested features can be disabled, return -/// FEATURE_NONE. If none of the requested features can be disabled return the unmodified features parameter. -PLUGIN_EXPORT uint32_t PLUGIN_CALLING_CONVENTION mumble_deactivateFeatures(uint32_t features); - - - -////////////////////////////////////////////////////////////////////////////////// -//////////////////////////// POSITIONAL DATA ///////////////////////////////////// -////////////////////////////////////////////////////////////////////////////////// -// If this plugin wants to provide positional data, the mumble_initPositionalData, mumble_fetchPositionalData -// and mumble_shutdownPositionalData functions have to be implemented together (implementing only a subset -// will yield the same result as if no support for positional data was implemened). - -/// Indicates that Mumble wants to use this plugin to request positional data. Therefore it should check whether it is -/// currently able to do so and allocate memory that is needed for that process. As a parameter this function gets an -/// array of names and an array of PIDs. They are of same length and the PID at index i belongs to a program whose name -/// is listed at index i in the "name-array". -/// -/// @param programNames An array of pointers to the program names -/// @param programPIDs An array of the corresponding program PIDs -/// @param programCount The length of programNames and programPIDs -/// @returns The error code. If everything went fine PDEC_OK shall be returned. In that case Mumble will start -/// frequently calling fetchPositionalData. If this returns anything but PDEC_OK, Mumble will assume that the plugin is -/// (currently) uncapable of providing positional data. In this case this function must not have allocated any memory -/// that needs to be cleaned up later on. Depending on the returned error code, Mumble might try to call this function -/// again at some point. -PLUGIN_EXPORT uint8_t PLUGIN_CALLING_CONVENTION mumble_initPositionalData(const char *const *programNames, - const uint64_t *programPIDs, - size_t programCount); - -/// Retrieves the positional data. If no data can be fetched, set all float-vectors to 0 and return false. -/// -/// @param[out] avatarPos A float-array of size 3 representing the cartesian position of the player/avatar in the ingame -/// world. One unit represents one meter of distance. -/// @param[out] avatarDir A float-array of size 3 representing the cartesian direction-vector of the player/avatar -/// ingame (where it is facing). -/// @param[out] avatarAxis A float-array of size 3 representing the vector pointing from the toes of the character to -/// its head. One unit represents one meter of distance. -/// @param[out] cameraPos A float-array of size 3 representing the cartesian position of the camera in the ingame world. -/// One unit represents one meter of distance. -/// @param[out] cameraDir A float-array of size 3 representing the cartesian direction-vector of the camera ingame -/// (where it is facing). -/// @param[out] cameraAxis A float-array of size 3 representing a vector from the bottom of the camera to its top. One -/// unit represents one meter of distance. -/// @param[out] context A pointer to where the pointer to a C-encoded string storing the context of the provided -/// positional data shall be written. This context should include information about the server (and team) the player is -/// on. Only players with identical context will be able to hear each other's audio. The returned pointer has to remain -/// valid until the next invokation of this function or until shutdownPositionalData is called. -/// @param[out] identity A pointer to where the pointer to a C-encoded string storing the identity of the player shall -/// be written. It can be polled by external scripts from the server and should uniquely identify the player in the -/// game. The pointer has to remain valid until the next invokation of this function or until shutdownPositionalData is -/// called. -/// @returns Whether this plugin can continue delivering positional data. If this function returns false, -/// shutdownPositionalData will be called. -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_fetchPositionalData(float *avatarPos, float *avatarDir, - float *avatarAxis, float *cameraPos, - float *cameraDir, float *cameraAxis, - const char **context, const char **identity); - -/// Indicates that this plugin will not be asked for positional data any longer. Thus any memory allocated for this -/// purpose should be freed at this point. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_shutdownPositionalData(); - -/// The context in positional data is used to determine whether different positional data sets from different -/// clients belong to the same game (and same server). Only if the contexts matches up across these clients, -/// will Mumble activate the positional audio effects, as it will assume that these clients are playing the -/// same game together. -/// The context is set during fetching of the other positional data and is usually something like e.g. the -/// current server's name. In order to avoid clashes between different plugins (that most likely work for -/// different games), the context is prefixed by Mumble. If this function is not implemented, the name of -/// the plugin is used as a prefix (which tends to be the supported game's name), but sometimes a different -/// prefix is desirable. For these cases, a custom prefix can be provided through this function. -/// -/// NOTE that while it is possible to allocate a string for this purpose every time this function is called -/// and then letting mumble release the resource again (via mumble_releaseResource), it is generally not the -/// advised way of doing things (it may impact overall performance negatively, since this function will be -/// called very frequently). Instead you should either return a static string (if your language supports that -/// and if it actually fits your needs) or you should allocate a string during mumble_initPositionalData and -/// free it in mumble_shutdownPositionalData and when returning the string in this function, tell Mumble that -/// the string does not need releasing. -/// -/// @returns The context prefix to use for positional data fetched by this plugin. -/// -/// @since Plugin API v1.1.0 -PLUGIN_EXPORT struct MumbleStringWrapper PLUGIN_CALLING_CONVENTION mumble_getPositionalDataContextPrefix(); - - - -////////////////////////////////////////////////////////////////////////////////// -////////////////////// EVENTHANDLERS / CALLBACK FUNCTIONS //////////////////////// -////////////////////////////////////////////////////////////////////////////////// - -/// Called when connecting to a server. -/// Note that in most cases you'll want to use mumble_onServerSynchronized instead. -/// Note also that this callback will be called from a DIFFERENT THREAD! -/// -/// @param connection The ID of the newly established server-connection -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onServerConnected(mumble_connection_t connection); - -/// Called when disconnecting from a server. -/// Note that this callback is called from a DIFFERENT THREAD! -/// -/// @param connection The ID of the server-connection that has been terminated -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onServerDisconnected(mumble_connection_t connection); - -/// Called when the client has finished synchronizing with the server -/// -/// @param connection The ID of the server-connection that has been terminated -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onServerSynchronized(mumble_connection_t connection); - -/// Called whenever any user on the server enters a channel -/// This function will also be called when freshly connecting to a server as each user on that -/// server needs to be "added" to the respective channel as far as the local client is concerned. -/// -/// @param connection The ID of the server-connection this event is connected to -/// @param userID The ID of the user this event has been triggered for -/// @param previousChannelID The ID of the chanel the user is coming from. Negative IDs indicate that there is no -/// previous channel (e.g. the user freshly connected to the server) or the channel isn't available because of any other -/// reason. -/// @param newChannelID The ID of the channel the user has entered. If the ID is negative, the new channel could not be -/// retrieved. This means that the ID is invalid. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onChannelEntered(mumble_connection_t connection, - mumble_userid_t userID, - mumble_channelid_t previousChannelID, - mumble_channelid_t newChannelID); - -/// Called whenever a user leaves a channel. -/// This includes a client disconnecting from the server as this will also lead to the user not being in that channel -/// anymore. -/// -/// @param connection The ID of the server-connection this event is connected to -/// @param userID The ID of the user that left the channel -/// @param channelID The ID of the channel the user left. If the ID is negative, the channel could not be retrieved. -/// This means that the ID is invalid. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onChannelExited(mumble_connection_t connection, - mumble_userid_t userID, - mumble_channelid_t channelID); - -/// Called when any user changes his/her talking state. -/// -/// @param connection The ID of the server-connection this event is connected to -/// @param userID The ID of the user whose talking state has been changed -/// @param talkingState The new TalkingState the user has switched to. -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onUserTalkingStateChanged(mumble_connection_t connection, - mumble_userid_t userID, - mumble_talking_state_t talkingState); - -/// Called whenever there is audio input. -/// Note that this callback will be called from the AUDIO THREAD. -/// Note also that blocking this callback will cause Mumble's audio processing to get suspended. -/// -/// @param inputPCM A pointer to a short-array holding the pulse-code-modulation (PCM) representing the audio input. Its -/// length is sampleCount * channelCount. The PCM format for stereo input is [LRLRLR...] where L and R are samples of -/// the left and right channel respectively. -/// @param sampleCount The amount of sample points per channel -/// @param channelCount The amount of channels in the audio -/// @param sampleRate The used sample rate in Hz -/// @param isSpeech A boolean flag indicating whether Mumble considers the input as part of speech (instead of -/// background noise) -/// @returns Whether this callback has modified the audio input-array -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_onAudioInput(short *inputPCM, uint32_t sampleCount, - uint16_t channelCount, uint32_t sampleRate, - bool isSpeech); - -/// Called whenever Mumble fetches data from an active audio source (could be a voice packet or a playing sample). -/// The provided audio buffer is the raw buffer without any processing applied to it yet. -/// Note that this callback will be called from the AUDIO THREAD. -/// Note also that blocking this callback will cause Mumble's audio processing to get suspended. -/// -/// @param outputPCM A pointer to a float-array holding the pulse-code-modulation (PCM) representing the audio output. -/// Its length is sampleCount * channelCount. The PCM format for stereo output is [LRLRLR...] where L and R are samples -/// of the left and right channel respectively. -/// @param sampleCount The amount of sample points per channel -/// @param channelCount The amount of channels in the audio -/// @param sampleRate The used sample rate in Hz -/// @param isSpeech Whether this audio belongs to a received voice packet (and will thus (most likely) contain speech) -/// @param userID If isSpeech is true, this contains the ID of the user this voice packet belongs to. If isSpeech is -/// false, the content of this parameter is unspecified and should not be accessed -/// @returns Whether this callback has modified the audio output-array -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_onAudioSourceFetched(float *outputPCM, uint32_t sampleCount, - uint16_t channelCount, uint32_t sampleRate, - bool isSpeech, mumble_userid_t userID); - -/// Called whenever the fully mixed and processed audio is about to be handed to the audio backend (about to be played). -/// Note that this happens immediately before Mumble clips the audio buffer. -/// Note that this callback will be called from the AUDIO THREAD. -/// Note also that blocking this callback will cause Mumble's audio processing to get suspended. -/// -/// @param outputPCM A pointer to a float-array holding the pulse-code-modulation (PCM) representing the audio output. -/// Its length is sampleCount * channelCount. The PCM format for stereo output is [LRLRLR...] where L and R are samples -/// of the left and right channel respectively. -/// @param sampleCount The amount of sample points per channel -/// @param channelCount The amount of channels in the audio -/// @param sampleRate The used sample rate in Hz -/// @returns Whether this callback has modified the audio output-array -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_onAudioOutputAboutToPlay(float *outputPCM, uint32_t sampleCount, - uint16_t channelCount, - uint32_t sampleRate); - -/// Called whenever data has been received that has been sent by a plugin. This data should only be processed by the -/// intended plugin. For this reason a dataID is provided that should be used to determine whether the data is intended -/// for this plugin or not. As soon as the data has been processed, no further plugins will be notified about it. -/// -/// @param connection The ID of the server-connection the data is coming from -/// @param sender The ID of the user whose client's plugin has sent the data -/// @param data The sent data array. This can be an arbitrary sequence of bytes. -/// @param dataLength The length of the data array -/// @param dataID The ID of this data (C-encoded) -/// @return Whether the given data has been processed by this plugin -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_onReceiveData(mumble_connection_t connection, - mumble_userid_t sender, const uint8_t *data, - size_t dataLength, const char *dataID); - -/// Called when a new user gets added to the user model. This is the case when that new user freshly connects to the -/// server the local user is on but also when the local user connects to a server other clients are already connected to -/// (in this case this method will be called for every client already on that server). -/// -/// @param connection An object used to identify the current connection -/// @param userID The ID of the user that has been added - -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onUserAdded(mumble_connection_t connection, mumble_userid_t userID); - -/// Called when a user gets removed from the user model. This is the case when that user disconnects from the server the -/// local user is on but also when the local user disconnects from a server other clients are connected to (in this case -/// this method will be called for every client on that server). -/// -/// @param connection An object used to identify the current connection -/// @param userID The ID of the user that has been removed -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onUserRemoved(mumble_connection_t connection, - mumble_userid_t userID); - -/// Called when a new channel gets added to the user model. This is the case when a new channel is created on the server -/// the local user is on but also when the local user connects to a server that contains channels other than the -/// root-channel (in this case this method will be called for ever non-root channel on that server). -/// -/// @param connection An object used to identify the current connection -/// @param channelID The ID of the channel that has been added -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onChannelAdded(mumble_connection_t connection, - mumble_channelid_t channelID); - -/// Called when a channel gets removed from the user model. This is the case when a channel is removed on the server the -/// local user is on but also when the local user disconnects from a server that contains channels other than the -/// root-channel (in this case this method will be called for ever non-root channel on that server). -/// -/// @param connection An object used to identify the current connection -/// @param channelID The ID of the channel that has been removed -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onChannelRemoved(mumble_connection_t connection, - mumble_channelid_t channelID); - -/// Called when a channel gets renamed. This also applies when a new channel is created (thus assigning it an initial -/// name is also considered renaming). -/// -/// @param connection An object used to identify the current connection -/// @param channelID The ID of the channel that has been renamed -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onChannelRenamed(mumble_connection_t connection, - mumble_channelid_t channelID); - -/// Called when a key has been pressed or released while Mumble has keyboard focus. -/// Note that this callback will only work if the user has explicitly given permission to monitor keyboard -/// events for this plugin. Thus if you want to use this callback, make sure your users know that they have to -/// enable that. -/// -/// @param keyCode The key code of the respective key. The character codes are defined -/// via the Mumble_KeyCode enum. For printable 7-bit ASCII characters these codes conform -/// to the ASCII code-page with the only difference that case is not distinguished. Therefore -/// always the upper-case letter code will be used for letters. -/// @param wasPres Whether the respective key has been pressed (instead of released) -PLUGIN_EXPORT void PLUGIN_CALLING_CONVENTION mumble_onKeyEvent(uint32_t keyCode, bool wasPress); - - - -////////////////////////////////////////////////////////////////////////////////// -////////////////////////////// PLUGIN UPDATES //////////////////////////////////// -////////////////////////////////////////////////////////////////////////////////// - -/// This function is used to determine whether the plugin can find an update for itself that is available for download. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @return Whether the plugin was able to find an update for itself -PLUGIN_EXPORT bool PLUGIN_CALLING_CONVENTION mumble_hasUpdate(); - -/// This function is used to retrieve the URL for downloading the newer/updated version of this plugin. -/// -/// NOTE: This function may be called without the plugin being loaded -/// -/// @returns A String-wrapper containing the requested URL -PLUGIN_EXPORT struct MumbleStringWrapper PLUGIN_CALLING_CONVENTION mumble_getUpdateDownloadURL(); - - - -////////////////////////////////////////////////////////////////////////////////// -///////////////////////////// DEFAULT FUNCTIONS ////////////////////////////////// -////////////////////////////////////////////////////////////////////////////////// -// These functions don't have to be implemented by you -PLUGIN_EXPORT mumble_version_t mumble_getPluginFunctionsVersion(); - -#ifndef MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS - -PLUGIN_EXPORT mumble_version_t mumble_getPluginFunctionsVersion() { - return MUMBLE_PLUGIN_FUNCTIONS_VERSION; -} - -#endif - -#ifdef __cplusplus -} -#endif - - -#endif diff --git a/plugins/PluginComponents_v_1_0_x.h b/plugins/PluginComponents_v_1_0_x.h deleted file mode 100644 index 48ac8dcd659..00000000000 --- a/plugins/PluginComponents_v_1_0_x.h +++ /dev/null @@ -1,416 +0,0 @@ -// Copyright 2021-2023 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 . - -/// This header file contains definitions of types and other components used in Mumble's plugin system - -#ifndef EXTERNAL_MUMBLE_PLUGINCOMPONENT_H_ -#define EXTERNAL_MUMBLE_PLUGINCOMPONENT_H_ - -#include -#include -#include - -#ifdef __cplusplus -# include -#endif - -#if defined(QT_CORE_LIB) || defined(QT_VERSION) -# include -#endif - -// define the calling convention macro based on the compiler being used -#if defined(_MSC_VER) -# define PLUGIN_CALLING_CONVENTION __cdecl -#elif defined(__MINGW32__) -# define PLUGIN_CALLING_CONVENTION __attribute__((cdecl)) -#else -# define PLUGIN_CALLING_CONVENTION -#endif - - -/// This enum's values correspond to special feature sets a plugin may provide. -/// They are meant to be or'ed together to represent the total feature set of a plugin. -enum Mumble_PluginFeature { - /// None of the below - MUMBLE_FEATURE_NONE = 0, - /// The plugin provides positional data from a game - MUMBLE_FEATURE_POSITIONAL = 1 << 0, - /// The plugin modifies the input/output audio itself - MUMBLE_FEATURE_AUDIO = 1 << 1 -}; - -/// This enum's values represent talking states a user can be in when using Mumble. -enum Mumble_TalkingState { - MUMBLE_TS_INVALID = -1, - MUMBLE_TS_PASSIVE = 0, - MUMBLE_TS_TALKING, - MUMBLE_TS_WHISPERING, - MUMBLE_TS_SHOUTING, - MUMBLE_TS_TALKING_MUTED -}; - -/// This enum's values represent transmission modes a user might have configured. Transmission mode -/// in this context is referring to a method that determines when a user is speaking and thus when -/// to transmit audio packets. -enum Mumble_TransmissionMode { MUMBLE_TM_CONTINOUS, MUMBLE_TM_VOICE_ACTIVATION, MUMBLE_TM_PUSH_TO_TALK }; - -/// This enum's values represent the error codes that are being used by the MumbleAPI. -/// You can get a string-representation for each error code via the errorMessage function. -enum Mumble_ErrorCode { - MUMBLE_EC_INTERNAL_ERROR = -2, - MUMBLE_EC_GENERIC_ERROR = -1, - MUMBLE_EC_OK = 0, - MUMBLE_EC_POINTER_NOT_FOUND, - MUMBLE_EC_NO_ACTIVE_CONNECTION, - MUMBLE_EC_USER_NOT_FOUND, - MUMBLE_EC_CHANNEL_NOT_FOUND, - MUMBLE_EC_CONNECTION_NOT_FOUND, - MUMBLE_EC_UNKNOWN_TRANSMISSION_MODE, - MUMBLE_EC_AUDIO_NOT_AVAILABLE, - MUMBLE_EC_INVALID_SAMPLE, - MUMBLE_EC_INVALID_PLUGIN_ID, - MUMBLE_EC_INVALID_MUTE_TARGET, - MUMBLE_EC_CONNECTION_UNSYNCHRONIZED, - MUMBLE_EC_INVALID_API_VERSION, - MUMBLE_EC_UNSYNCHRONIZED_BLOB, - MUMBLE_EC_UNKNOWN_SETTINGS_KEY, - MUMBLE_EC_WRONG_SETTINGS_TYPE, - MUMBLE_EC_SETTING_WAS_REMOVED, - MUMBLE_EC_DATA_TOO_BIG, - MUMBLE_EC_DATA_ID_TOO_LONG, - MUMBLE_EC_API_REQUEST_TIMEOUT, - MUMBLE_EC_OPERATION_UNSUPPORTED_BY_SERVER, -}; - -/// This enum's values represent error codes specific to the framework of handling positional data -/// gathering (needed for Mumble's positional audio feature). -enum Mumble_PositionalDataErrorCode { - /// Positional data has been initialized properly - MUMBLE_PDEC_OK = 0, - /// Positional data is temporarily unavailable (e.g. because the corresponding process isn't running) but might be - /// at another point in time. - MUMBLE_PDEC_ERROR_TEMP, - /// Positional data is permanently unavailable (e.g. because the respective memory offsets are outdated). - MUMBLE_PDEC_ERROR_PERM -}; - -/// This enum's values represent keys for specific settings inside Mumble. -enum Mumble_SettingsKey { - MUMBLE_SK_INVALID = -1, - MUMBLE_SK_AUDIO_INPUT_VOICE_HOLD = 0, - MUMBLE_SK_AUDIO_INPUT_VAD_SILENCE_THRESHOLD = 1, - MUMBLE_SK_AUDIO_INPUT_VAD_SPEECH_THRESHOLD = 2, - MUMBLE_SK_AUDIO_OUTPUT_PA_MINIMUM_DISTANCE = 3, - MUMBLE_SK_AUDIO_OUTPUT_PA_MAXIMUM_DISTANCE = 4, - MUMBLE_SK_AUDIO_OUTPUT_PA_BLOOM = 5, - MUMBLE_SK_AUDIO_OUTPUT_PA_MINIMUM_VOLUME = 6, -}; - -/// This enum's values represent the key-codes Mumble's API uses to reference keys on the keyboard. -enum Mumble_KeyCode { - MUMBLE_KC_INVALID = -1, - - // Non-printable characters first - MUMBLE_KC_NULL = 0, - MUMBLE_KC_END = 1, - MUMBLE_KC_LEFT = 2, - MUMBLE_KC_RIGHT = 4, - MUMBLE_KC_UP = 5, - MUMBLE_KC_DOWN = 6, - MUMBLE_KC_DELETE = 7, - MUMBLE_KC_BACKSPACE = 8, - MUMBLE_KC_TAB = 9, - MUMBLE_KC_ENTER = 10, // == '\n' - MUMBLE_KC_ESCAPE = 27, - MUMBLE_KC_PAGE_UP = 11, - MUMBLE_KC_PAGE_DOWN = 12, - MUMBLE_KC_SHIFT = 13, - MUMBLE_KC_CONTROL = 14, - MUMBLE_KC_META = 15, - MUMBLE_KC_ALT = 16, - MUMBLE_KC_ALT_GR = 17, - MUMBLE_KC_CAPSLOCK = 18, - MUMBLE_KC_NUMLOCK = 19, - MUMBLE_KC_SUPER = 20, // == windows key - MUMBLE_KC_HOME = 21, // == Pos1 - MUMBLE_KC_PRINT = 22, - MUMBLE_KC_SCROLLLOCK = 23, - - // Printable characters are assigned to their ASCII code - MUMBLE_KC_SPACE = ' ', - MUMBLE_KC_EXCLAMATION_MARK = '!', - MUMBLE_KC_DOUBLE_QUOTE = '"', - MUMBLE_KC_HASHTAG = '#', - MUMBLE_KC_DOLLAR = '$', - MUMBLE_KC_PERCENT = '%', - MUMBLE_KC_AMPERSAND = '&', - MUMBLE_KC_SINGLE_QUOTE = '\'', - MUMBLE_KC_OPEN_PARENTHESIS = '(', - MUMBLE_KC_CLOSE_PARENTHESIS = ')', - MUMBLE_KC_ASTERISK = '*', - MUMBLE_KC_PLUS = '+', - MUMBLE_KC_COMMA = ',', - MUMBLE_KC_MINUS = '-', - MUMBLE_KC_PERIOD = '.', - MUMBLE_KC_SLASH = '/', - MUMBLE_KC_0 = '0', - MUMBLE_KC_1 = '1', - MUMBLE_KC_2 = '2', - MUMBLE_KC_3 = '3', - MUMBLE_KC_4 = '4', - MUMBLE_KC_5 = '5', - MUMBLE_KC_6 = '6', - MUMBLE_KC_7 = '7', - MUMBLE_KC_8 = '8', - MUMBLE_KC_9 = '9', - MUMBLE_KC_COLON = ':', - MUMBLE_KC_SEMICOLON = ';', - MUMBLE_KC_LESS_THAN = '<', - MUMBLE_KC_EQUALS = '=', - MUMBLE_KC_GREATER_THAN = '>', - MUMBLE_KC_QUESTION_MARK = '?', - MUMBLE_KC_AT_SYMBOL = '@', - MUMBLE_KC_A = 'A', - MUMBLE_KC_B = 'B', - MUMBLE_KC_C = 'C', - MUMBLE_KC_D = 'D', - MUMBLE_KC_E = 'E', - MUMBLE_KC_F = 'F', - MUMBLE_KC_G = 'G', - MUMBLE_KC_H = 'H', - MUMBLE_KC_I = 'I', - MUMBLE_KC_J = 'J', - MUMBLE_KC_K = 'K', - MUMBLE_KC_L = 'L', - MUMBLE_KC_M = 'M', - MUMBLE_KC_N = 'N', - MUMBLE_KC_O = 'O', - MUMBLE_KC_P = 'P', - MUMBLE_KC_Q = 'Q', - MUMBLE_KC_R = 'R', - MUMBLE_KC_S = 'S', - MUMBLE_KC_T = 'T', - MUMBLE_KC_U = 'U', - MUMBLE_KC_V = 'V', - MUMBLE_KC_W = 'W', - MUMBLE_KC_X = 'X', - MUMBLE_KC_Y = 'Y', - MUMBLE_KC_Z = 'Z', - // leave out lowercase letters (for now) - MUMBLE_KC_OPEN_BRACKET = '[', - MUMBLE_KC_BACKSLASH = '\\', - MUMBLE_KC_CLOSE_BRACKET = ']', - MUMBLE_KC_CIRCUMFLEX = '^', - MUMBLE_KC_UNDERSCORE = '_', - MUMBLE_KC_GRAVE_AKCENT = '`', - MUMBLE_KC_OPEN_BRACE = '{', - MUMBLE_KC_VERTICAL_BAR = '|', - MUMBLE_KC_CLOSE_BRACE = '}', - MUMBLE_KC_TILDE = '~', - - // Some characters from the extended ASCII code - MUMBLE_KC_DEGREE_SIGN = 176, - - - - // F-keys - // Start at a value of 256 as extended ASCII codes range up to 255 - MUMBLE_KC_F1 = 256, - MUMBLE_KC_F2 = 257, - MUMBLE_KC_F3 = 258, - MUMBLE_KC_F4 = 259, - MUMBLE_KC_F5 = 260, - MUMBLE_KC_F6 = 261, - MUMBLE_KC_F7 = 262, - MUMBLE_KC_F8 = 263, - MUMBLE_KC_F9 = 264, - MUMBLE_KC_F10 = 265, - MUMBLE_KC_F11 = 266, - MUMBLE_KC_F12 = 267, - MUMBLE_KC_F13 = 268, - MUMBLE_KC_F14 = 269, - MUMBLE_KC_F15 = 270, - MUMBLE_KC_F16 = 271, - MUMBLE_KC_F17 = 272, - MUMBLE_KC_F18 = 273, - MUMBLE_KC_F19 = 274, -}; - -/// A struct for representing a version of the form major.minor.patch -struct MumbleVersion { - int32_t major; - int32_t minor; - int32_t patch; -#ifdef __cplusplus - bool operator<(const MumbleVersion &other) const { - if (this->major != other.major) { - return this->major < other.major; - } - if (this->minor != other.minor) { - return this->minor < other.minor; - } - // Major and Minor are equal - return this->patch < other.patch; - } - - bool operator>(const MumbleVersion &other) const { - if (this->major != other.major) { - return this->major > other.major; - } - if (this->minor != other.minor) { - return this->minor > other.minor; - } - // Major and Minor are equal - return this->patch > other.patch; - } - - bool operator>=(const MumbleVersion &other) const { - if (this->major != other.major) { - return this->major > other.major; - } - if (this->minor != other.minor) { - return this->minor > other.minor; - } - // Major and Minor are equal - return this->patch >= other.patch; - } - - bool operator<=(const MumbleVersion &other) const { - if (this->major != other.major) { - return this->major < other.major; - } - if (this->minor != other.minor) { - return this->minor < other.minor; - } - // Major and Minor are equal - return this->patch <= other.patch; - } - - bool operator==(const MumbleVersion &other) const { - return this->major == other.major && this->minor == other.minor && this->patch == other.patch; - } - - bool operator!=(const MumbleVersion &other) const { - return this->major != other.major || this->minor != other.minor || this->patch != other.patch; - } - - operator std::string() const { - return std::string("v") + std::to_string(this->major) + std::string(".") + std::to_string(this->minor) - + std::string(".") + std::to_string(this->patch); - } - -# if defined(QT_CORE_LIB) || defined(QT_VERSION) - operator QString() const { - return QString::fromLatin1("v%0.%1.%2").arg(this->major).arg(this->minor).arg(this->patch); - } -# endif -#endif -}; - -/// Obtains a String representation for the given numeric error code. -/// Note that the exact String representation corresponding to an error code may change and is thus -/// not part of the plugin API as such. This function acts merely as a convenience helper for printing -/// errors in a meaningful way. -/// -/// @param errorCode The error code to get the String representation for -/// @returns The error message coresponding to the given error code. The message -/// is encoded as a C-string and is static, meaning that it is safe to use the -/// returned pointer in your code. -inline const char *mumble_errorMessage(int16_t errorCode) { - switch (errorCode) { - case MUMBLE_EC_GENERIC_ERROR: - return "Generic error"; - case MUMBLE_EC_OK: - return "Ok - this is not an error"; - case MUMBLE_EC_POINTER_NOT_FOUND: - return "Can't find the passed pointer"; - case MUMBLE_EC_NO_ACTIVE_CONNECTION: - return "There is currently no active connection to a server"; - case MUMBLE_EC_USER_NOT_FOUND: - return "Can't find the requested user"; - case MUMBLE_EC_CHANNEL_NOT_FOUND: - return "Can't find the requested channel"; - case MUMBLE_EC_CONNECTION_NOT_FOUND: - return "Can't identify the requested connection"; - case MUMBLE_EC_UNKNOWN_TRANSMISSION_MODE: - return "Unknown transmission mode encountered"; - case MUMBLE_EC_AUDIO_NOT_AVAILABLE: - return "There is currently no audio output available"; - case MUMBLE_EC_INVALID_SAMPLE: - return "Attempted to use invalid sample (can't play it)"; - case MUMBLE_EC_INVALID_PLUGIN_ID: - return "Used an invalid plugin ID"; - case MUMBLE_EC_INVALID_MUTE_TARGET: - return "Used an invalid mute-target"; - case MUMBLE_EC_CONNECTION_UNSYNCHRONIZED: - return "The requested server connection has not yet finished synchronizing"; - case MUMBLE_EC_INVALID_API_VERSION: - return "The used API version is invalid or not supported"; - case MUMBLE_EC_UNSYNCHRONIZED_BLOB: - return "The requested blob (content) has not yet been synchronized between the client and the server"; - case MUMBLE_EC_UNKNOWN_SETTINGS_KEY: - return "The used settings-key does not match any key known to Mumble"; - case MUMBLE_EC_WRONG_SETTINGS_TYPE: - return "The referenced setting has a different type than requested"; - case MUMBLE_EC_SETTING_WAS_REMOVED: - return "The referenced setting got removed from Mumble and is no longer used"; - case MUMBLE_EC_DATA_TOO_BIG: - return "The given data is too large (exceeds limit)"; - case MUMBLE_EC_DATA_ID_TOO_LONG: - return "The given data ID is too long (exceeds limit)"; - case MUMBLE_EC_API_REQUEST_TIMEOUT: - return "A blocking API call took too long and was thus aborted (probably preventing a deadlock)"; - case MUMBLE_EC_OPERATION_UNSUPPORTED_BY_SERVER: - return "The requested API operation depends on server-side functionality, not supported by the server " - "you're connected to"; - default: - return "Unknown error code"; - } -} - - -/// This struct is used to return Strings from a plugin to Mumble. It is needed in order to -/// work around the limitation of std::string not being part of C (it holds important information -/// about the String's lifetime management requirements). -struct MumbleStringWrapper { - /// The pointer to the actual String data - const char *data; - /// The size of the pointed String data - size_t size; - /// Whether the wrapped String needs to be released - /// after its usage. Instances for which this would be - /// false: Static Strings, String literals - bool needsReleasing; -}; - -/// Typedef for the type of a talking state -typedef enum Mumble_TalkingState mumble_talking_state_t; -/// Typedef for the type of a transmission mode -typedef enum Mumble_TransmissionMode mumble_transmission_mode_t; -/// Typedef for the type of a version -typedef struct MumbleVersion mumble_version_t; -/// Typedef for the type of a connection -typedef int32_t mumble_connection_t; -/// Typedef for the type of a user -typedef uint32_t mumble_userid_t; -/// Typedef for the type of a channel -typedef int32_t mumble_channelid_t; -/// Typedef for the type of an error (code) -typedef enum Mumble_ErrorCode mumble_error_t; -/// Typedef for the type of a plugin ID -typedef uint32_t mumble_plugin_id_t; -/// Typedef for the type of a key to a setting in Mumble -typedef enum Mumble_SettingsKey mumble_settings_key_t; -/// Typedef for the type of a key-code -typedef enum Mumble_KeyCode mumble_keycode_t; - - - -/// A constant holding the exit status of a successful operation -static const mumble_error_t MUMBLE_STATUS_OK = MUMBLE_EC_OK; -/// A constant holding the version object that is considered to correspond to an unknown version -static const mumble_version_t MUMBLE_VERSION_UNKNOWN = { 0, 0, 0 }; - -#endif // EXTERNAL_MUMBLE_PLUGINCOMPONENT_H_ diff --git a/plugins/amongus/Game.h b/plugins/amongus/Game.h index b0603aa5a2f..14388919474 100644 --- a/plugins/amongus/Game.h +++ b/plugins/amongus/Game.h @@ -9,7 +9,9 @@ #include "structs.h" #include "ProcessWindows.h" -#include "PluginComponents_v_1_0_x.h" +#define MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS +#include "MumblePlugin.h" +#undef MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS class Game { public: diff --git a/plugins/amongus/amongus.cpp b/plugins/amongus/amongus.cpp index 8e3db7362bd..9d9beae20f2 100644 --- a/plugins/amongus/amongus.cpp +++ b/plugins/amongus/amongus.cpp @@ -5,7 +5,7 @@ #include "Game.h" -#include "MumblePlugin_v_1_0_x.h" +#include "MumblePlugin.h" #include #include diff --git a/plugins/gtav/Game.h b/plugins/gtav/Game.h index daede465509..98184f61a3f 100644 --- a/plugins/gtav/Game.h +++ b/plugins/gtav/Game.h @@ -9,7 +9,9 @@ #include "structs.h" #include "ProcessWindows.h" -#include "PluginComponents_v_1_0_x.h" +#define MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS +#include "MumblePlugin.h" +#undef MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS class Game { public: diff --git a/plugins/gtav/gtav.cpp b/plugins/gtav/gtav.cpp index 30e02e7abf7..e2d651bb972 100644 --- a/plugins/gtav/gtav.cpp +++ b/plugins/gtav/gtav.cpp @@ -5,7 +5,7 @@ #include "Game.h" -#include "MumblePlugin_v_1_0_x.h" +#include "MumblePlugin.h" #include #include diff --git a/plugins/link/link.cpp b/plugins/link/link.cpp index 934f049a505..a0e9d4e4526 100644 --- a/plugins/link/link.cpp +++ b/plugins/link/link.cpp @@ -12,8 +12,7 @@ #include #include "LinkedMem.h" -#include "MumbleAPI_v_1_0_x.h" -#include "MumblePlugin_v_1_1_x.h" +#include "MumblePlugin.h" #include "SharedMemory.h" #define UNUSED(x) (void) x diff --git a/src/mumble/API_v_1_x_x.cpp b/src/mumble/API_v_1_x_x.cpp index 86e2f5b67f6..ca92cd87c0a 100644 --- a/src/mumble/API_v_1_x_x.cpp +++ b/src/mumble/API_v_1_x_x.cpp @@ -12,7 +12,6 @@ #include "Log.h" #include "MainWindow.h" #include "MumbleConstants.h" -#include "PluginComponents_v_1_0_x.h" #include "PluginManager.h" #include "ServerHandler.h" #include "Settings.h" @@ -20,6 +19,10 @@ #include "Version.h" #include "Global.h" +#define MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS +#include "MumblePlugin.h" +#undef MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS + #include #include #include @@ -1646,958 +1649,282 @@ void MumbleAPI::playSample_v_1_2_x(mumble_plugin_id_t callerID, const char *samp /////////////////// C FUNCTION WRAPPERS FOR USE IN API STRUCT /////////////////////////// ///////////////////////////////////////////////////////////////////////////////////////// -mumble_error_t PLUGIN_CALLING_CONVENTION freeMemory_v_1_0_x(mumble_plugin_id_t callerID, const void *ptr) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().freeMemory_v_1_0_x(callerID, ptr, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getActiveServerConnection_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t *connection) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getActiveServerConnection_v_1_0_x(callerID, connection, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION isConnectionSynchronized_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, - bool *synchronized) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().isConnectionSynchronized_v_1_0_x(callerID, connection, synchronized, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getLocalUserID_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, - mumble_userid_t *userID) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getLocalUserID_v_1_0_x(callerID, connection, userID, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getUserName_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, mumble_userid_t userID, - const char **name) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getUserName_v_1_0_x(callerID, connection, userID, name, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getChannelName_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, - mumble_channelid_t channelID, const char **name) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getChannelName_v_1_0_x(callerID, connection, channelID, name, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getAllUsers_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, mumble_userid_t **users, - size_t *userCount) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getAllUsers_v_1_0_x(callerID, connection, users, userCount, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getAllChannels_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, - mumble_channelid_t **channels, size_t *channelCount) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getAllChannels_v_1_0_x(callerID, connection, channels, channelCount, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getChannelOfUser_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, - mumble_userid_t userID, mumble_channelid_t *channel) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getChannelOfUser_v_1_0_x(callerID, connection, userID, channel, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getUsersInChannel_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, - mumble_channelid_t channelID, - mumble_userid_t **userList, size_t *userCount) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getUsersInChannel_v_1_0_x(callerID, connection, channelID, userList, userCount, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - - -mumble_error_t PLUGIN_CALLING_CONVENTION - getLocalUserTransmissionMode_v_1_0_x(mumble_plugin_id_t callerID, mumble_transmission_mode_t *transmissionMode) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getLocalUserTransmissionMode_v_1_0_x(callerID, transmissionMode, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION isUserLocallyMuted_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, - mumble_userid_t userID, bool *muted) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().isUserLocallyMuted_v_1_0_x(callerID, connection, userID, muted, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION isLocalUserMuted_v_1_0_x(mumble_plugin_id_t callerID, bool *muted) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().isLocalUserMuted_v_1_0_x(callerID, muted, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION isLocalUserDeafened_v_1_0_x(mumble_plugin_id_t callerID, bool *deafened) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().isLocalUserDeafened_v_1_0_x(callerID, deafened, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getUserHash_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, mumble_userid_t userID, - const char **hash) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getUserHash_v_1_0_x(callerID, connection, userID, hash, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getServerHash_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, const char **hash) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getServerHash_v_1_0_x(callerID, connection, hash, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - - -mumble_error_t PLUGIN_CALLING_CONVENTION - requestLocalUserTransmissionMode_v_1_0_x(mumble_plugin_id_t callerID, mumble_transmission_mode_t transmissionMode) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().requestLocalUserTransmissionMode_v_1_0_x(callerID, transmissionMode, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getUserComment_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, mumble_userid_t userID, - const char **comment) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getUserComment_v_1_0_x(callerID, connection, userID, comment, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getChannelDescription_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, - mumble_channelid_t channelID, - const char **description) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getChannelDescription_v_1_0_x(callerID, connection, channelID, description, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION requestUserMove_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, mumble_userid_t userID, - mumble_channelid_t channelID, const char *password) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().requestUserMove_v_1_0_x(callerID, connection, userID, channelID, password, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION requestMicrophoneActivationOverwrite_v_1_0_x(mumble_plugin_id_t callerID, - bool activate) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().requestMicrophoneActivationOverwrite_v_1_0_x(callerID, activate, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION requestLocalMute_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, - mumble_userid_t userID, bool muted) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().requestLocalMute_v_1_0_x(callerID, connection, userID, muted, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION requestLocalUserMute_v_1_0_x(mumble_plugin_id_t callerID, bool muted) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().requestLocalUserMute_v_1_0_x(callerID, muted, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION requestLocalUserDeaf_v_1_0_x(mumble_plugin_id_t callerID, bool deafened) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().requestLocalUserDeaf_v_1_0_x(callerID, deafened, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION requestSetLocalUserComment_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, - const char *comment) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().requestSetLocalUserComment_v_1_0_x(callerID, connection, comment, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION findUserByName_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, const char *userName, - mumble_userid_t *userID) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().findUserByName_v_1_0_x(callerID, connection, userName, userID, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION findChannelByName_v_1_0_x(mumble_plugin_id_t callerID, - mumble_connection_t connection, - const char *channelName, - mumble_channelid_t *channelID) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().findChannelByName_v_1_0_x(callerID, connection, channelName, channelID, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getMumbleSetting_bool_v_1_0_x(mumble_plugin_id_t callerID, - mumble_settings_key_t key, bool *outValue) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getMumbleSetting_bool_v_1_0_x(callerID, key, outValue, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getMumbleSetting_int_v_1_0_x(mumble_plugin_id_t callerID, - mumble_settings_key_t key, int64_t *outValue) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getMumbleSetting_int_v_1_0_x(callerID, key, outValue, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getMumbleSetting_double_v_1_0_x(mumble_plugin_id_t callerID, - mumble_settings_key_t key, double *outValue) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getMumbleSetting_double_v_1_0_x(callerID, key, outValue, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION getMumbleSetting_string_v_1_0_x(mumble_plugin_id_t callerID, - mumble_settings_key_t key, - const char **outValue) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().getMumbleSetting_string_v_1_0_x(callerID, key, outValue, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION setMumbleSetting_bool_v_1_0_x(mumble_plugin_id_t callerID, - mumble_settings_key_t key, bool value) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().setMumbleSetting_bool_v_1_0_x(callerID, key, value, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION setMumbleSetting_int_v_1_0_x(mumble_plugin_id_t callerID, - mumble_settings_key_t key, int64_t value) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().setMumbleSetting_int_v_1_0_x(callerID, key, value, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION setMumbleSetting_double_v_1_0_x(mumble_plugin_id_t callerID, - mumble_settings_key_t key, double value) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().setMumbleSetting_double_v_1_0_x(callerID, key, value, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION setMumbleSetting_string_v_1_0_x(mumble_plugin_id_t callerID, - mumble_settings_key_t key, const char *value) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().setMumbleSetting_string_v_1_0_x(callerID, key, value, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION sendData_v_1_0_x(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) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().sendData_v_1_0_x(callerID, connection, users, userCount, data, dataLength, dataID, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION log_v_1_0_x(mumble_plugin_id_t callerID, const char *message) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().log_v_1_0_x(callerID, message, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION playSample_v_1_0_x(mumble_plugin_id_t callerID, const char *samplePath) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().playSample_v_1_0_x(callerID, samplePath, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} - -mumble_error_t PLUGIN_CALLING_CONVENTION playSample_v_1_2_x(mumble_plugin_id_t callerID, const char *samplePath, - float volume) { - std::shared_ptr< api_promise_t > promise = std::make_shared< api_promise_t >(); - api_future_t future = promise->get_future(); - - MumbleAPI::get().playSample_v_1_2_x(callerID, samplePath, volume, promise); - - if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { - // The call to cancel may block until the operation is finished, if and only if the operation - // has already started and is thus in progress. - promise->cancel(); - - // If the cancel-operation above blocked, this means that the operation has now finished in which - // case this if will fail and we continue as if nothing had happened. - // If however it did not block the operation will immediately abort once it starts meaning that the - // check below will succeed. - if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { - promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); - } - } - - return future.get(); -} +#define C_WRAPPER(funcName) \ + mumble_error_t MUMBLE_PLUGIN_CALLING_CONVENTION funcName(TYPED_ARGS) { \ + auto promise = std::make_shared< api_promise_t >(); \ + api_future_t future = promise->get_future(); \ + \ + MumbleAPI::get().funcName(ARG_NAMES, promise); \ + \ + if (future.wait_for(std::chrono::milliseconds(800)) != std::future_status::ready) { \ + /* The call to cancel may block until the operation is finished, if and only if the operation \ + has already started and is thus in progress.*/ \ + promise->cancel(); \ + \ + /* If the cancel-operation above blocked, this means that the operation has now finished in which \ + case this will fail and we continue as if nothing had happened. \ + If however it did not block the operation will immediately abort once it starts, meaning that the \ + check below will succeed. */ \ + if (future.wait_for(std::chrono::milliseconds(0)) != std::future_status::ready) { \ + promise->set_value(MUMBLE_EC_API_REQUEST_TIMEOUT); \ + } \ + } \ + \ + return future.get(); \ + } + +#define TYPED_ARGS mumble_plugin_id_t callerID, const void *ptr +#define ARG_NAMES callerID, ptr +C_WRAPPER(freeMemory_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_connection_t *connection +#define ARG_NAMES callerID, connection +C_WRAPPER(getActiveServerConnection_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_connection_t connection, bool *synchronized +#define ARG_NAMES callerID, connection, synchronized +C_WRAPPER(isConnectionSynchronized_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t *userID +#define ARG_NAMES callerID, connection, userID +C_WRAPPER(getLocalUserID_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t userID, const char **name +#define ARG_NAMES callerID, connection, userID, name +C_WRAPPER(getUserName_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_channelid_t channelID, const char **name +#define ARG_NAMES callerID, connection, channelID, name +C_WRAPPER(getChannelName_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t **users, size_t *userCount +#define ARG_NAMES callerID, connection, users, userCount +C_WRAPPER(getAllUsers_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_channelid_t **channels, size_t *channelCount +#define ARG_NAMES callerID, connection, channels, channelCount +C_WRAPPER(getAllChannels_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t userID, mumble_channelid_t *channel +#define ARG_NAMES callerID, connection, userID, channel +C_WRAPPER(getChannelOfUser_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_channelid_t channelID, \ + mumble_userid_t **userList, size_t *userCount +#define ARG_NAMES callerID, connection, channelID, userList, userCount +C_WRAPPER(getUsersInChannel_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_transmission_mode_t *transmissionMode +#define ARG_NAMES callerID, transmissionMode +C_WRAPPER(getLocalUserTransmissionMode_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t userID, bool *muted +#define ARG_NAMES callerID, connection, userID, muted +C_WRAPPER(isUserLocallyMuted_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, bool *muted +#define ARG_NAMES callerID, muted +C_WRAPPER(isLocalUserMuted_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, bool *deafened +#define ARG_NAMES callerID, deafened +C_WRAPPER(isLocalUserDeafened_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t userID, const char **hash +#define ARG_NAMES callerID, connection, userID, hash +C_WRAPPER(getUserHash_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_connection_t connection, const char **hash +#define ARG_NAMES callerID, connection, hash +C_WRAPPER(getServerHash_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_transmission_mode_t transmissionMode +#define ARG_NAMES callerID, transmissionMode +C_WRAPPER(requestLocalUserTransmissionMode_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t userID, const char **comment +#define ARG_NAMES callerID, connection, userID, comment +C_WRAPPER(getUserComment_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_channelid_t channelID, const char **description +#define ARG_NAMES callerID, connection, channelID, description +C_WRAPPER(getChannelDescription_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t userID, mumble_channelid_t channelID, \ + const char *password +#define ARG_NAMES callerID, connection, userID, channelID, password +C_WRAPPER(requestUserMove_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, bool activate +#define ARG_NAMES callerID, activate +C_WRAPPER(requestMicrophoneActivationOverwrite_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t userID, bool muted +#define ARG_NAMES callerID, connection, userID, muted +C_WRAPPER(requestLocalMute_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, bool muted +#define ARG_NAMES callerID, muted +C_WRAPPER(requestLocalUserMute_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, bool deafened +#define ARG_NAMES callerID, deafened +C_WRAPPER(requestLocalUserDeaf_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_connection_t connection, const char *comment +#define ARG_NAMES callerID, connection, comment +C_WRAPPER(requestSetLocalUserComment_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, const char *userName, mumble_userid_t *userID +#define ARG_NAMES callerID, connection, userName, userID +C_WRAPPER(findUserByName_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + mumble_plugin_id_t callerID, mumble_connection_t connection, const char *channelName, mumble_channelid_t *channelID +#define ARG_NAMES callerID, connection, channelName, channelID +C_WRAPPER(findChannelByName_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_settings_key_t key, bool *outValue +#define ARG_NAMES callerID, key, outValue +C_WRAPPER(getMumbleSetting_bool_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_settings_key_t key, int64_t *outValue +#define ARG_NAMES callerID, key, outValue +C_WRAPPER(getMumbleSetting_int_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_settings_key_t key, double *outValue +#define ARG_NAMES callerID, key, outValue +C_WRAPPER(getMumbleSetting_double_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_settings_key_t key, const char **outValue +#define ARG_NAMES callerID, key, outValue +C_WRAPPER(getMumbleSetting_string_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_settings_key_t key, bool value +#define ARG_NAMES callerID, key, value +C_WRAPPER(setMumbleSetting_bool_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_settings_key_t key, int64_t value +#define ARG_NAMES callerID, key, value +C_WRAPPER(setMumbleSetting_int_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_settings_key_t key, double value +#define ARG_NAMES callerID, key, value +C_WRAPPER(setMumbleSetting_double_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, mumble_settings_key_t key, const char *value +#define ARG_NAMES callerID, key, value +C_WRAPPER(setMumbleSetting_string_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS \ + 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 +#define ARG_NAMES callerID, connection, users, userCount, data, dataLength, dataID +C_WRAPPER(sendData_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, const char *message +#define ARG_NAMES callerID, message +C_WRAPPER(log_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, const char *samplePath +#define ARG_NAMES callerID, samplePath +C_WRAPPER(playSample_v_1_0_x) +#undef TYPED_ARGS +#undef ARG_NAMES + +#define TYPED_ARGS mumble_plugin_id_t callerID, const char *samplePath, float volume +#define ARG_NAMES callerID, samplePath, volume +C_WRAPPER(playSample_v_1_2_x) +#undef TYPED_ARGS +#undef ARG_NAMES + + +#undef C_WRAPPER ///////////////////////////////////////////////////////////////////////////////////////// diff --git a/src/mumble/LegacyPlugin.cpp b/src/mumble/LegacyPlugin.cpp index 9a5082ecac6..303f29c5604 100644 --- a/src/mumble/LegacyPlugin.cpp +++ b/src/mumble/LegacyPlugin.cpp @@ -4,7 +4,10 @@ // Mumble source tree or at . #include "LegacyPlugin.h" -#include "MumblePlugin_v_1_0_x.h" + +#define MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS +#include "MumblePlugin.h" +#undef MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS #include #include diff --git a/src/mumble/MumbleAPI_structs.h b/src/mumble/MumbleAPI_structs.h index e90c7da5898..fe8da575e62 100644 --- a/src/mumble/MumbleAPI_structs.h +++ b/src/mumble/MumbleAPI_structs.h @@ -9,13 +9,23 @@ #ifndef EXTERNAL_MUMBLE_PLUGIN_API_STRUCTS_H_ #define EXTERNAL_MUMBLE_PLUGIN_API_STRUCTS_H_ +#define MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS +#define MUMBLE_PLUGIN_NO_API_TYPEDEF + // First, include the latest plugin API header file completely -#include "MumbleAPI_v_1_2_x.h" +#include "MumblePlugin.h" + + +// Re-include the API definition +#undef EXTERNAL_MUMBLE_PLUGIN_MUMBLE_API_ +// But this time, overwrite the version +#undef MUMBLE_PLUGIN_API_MAJOR_MACRO +#define MUMBLE_PLUGIN_API_MAJOR_MACRO 1 +#undef MUMBLE_PLUGIN_API_MINOR_MACRO +#define MUMBLE_PLUGIN_API_MINOR_MACRO 0 + +#include "MumblePlugin.h" -// Include all older API headers for their API structs, -// but prevent utility definitions (to prevent name clashes). -#define EXTERNAL_MUMBLE_PLUGIN_API_NO_AUXILIARY_DEFINITIONS -#include "MumbleAPI_v_1_0_x.h" -#undef EXTERNAL_MUMBLE_PLUGIN_API_NO_AUXILIARY_DEFINITIONS +#undef MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS #endif // EXTERNAL_MUMBLE_PLUGIN_API_STRUCTS_H_ diff --git a/src/mumble/OverlayUtils.h b/src/mumble/OverlayUtils.h new file mode 100644 index 00000000000..dbb96389572 --- /dev/null +++ b/src/mumble/OverlayUtils.h @@ -0,0 +1,37 @@ +// Copyright 2023 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 . + + +#ifndef MUMBLE_MUMBLE_OVERLAYUTILS_H_ +#define MUMBLE_MUMBLE_OVERLAYUTILS_H_ + +#include + +namespace mumble { +namespace overlay { + + std::string getIPCPath(); + + std::string getSocketPath(); + + std::string getPipePath(); + + std::string createSocket(); + + std::string createPipe(); + +} // namespace overlay +} // namespace mumble + + +extern "C" { + +char *mumble_overlay_create_and_get_socket(); + +char *mumble_overlay_create_and_get_pipe(); +} + + +#endif // MUMBLE_MUMBLE_OVERLAYUTILS_H_ diff --git a/src/mumble/Plugin.h b/src/mumble/Plugin.h index 3c2576c2d3f..428b2ef4d84 100644 --- a/src/mumble/Plugin.h +++ b/src/mumble/Plugin.h @@ -6,10 +6,11 @@ #ifndef MUMBLE_MUMBLE_PLUGIN_H_ #define MUMBLE_MUMBLE_PLUGIN_H_ -#include "MumbleAPI_structs.h" #define MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS -#include "MumblePlugin_v_1_1_x.h" -#include "PluginComponents_v_1_0_x.h" +#include "MumblePlugin.h" +#undef MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS + +#include "MumbleAPI_structs.h" #include "PositionalData.h" #include