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