mirrors/mumble
2
0
Fork 0
mirror of https://github.com/mumble-voip/mumble.git synced 2025-10-26 11:19:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
0dea9d6e82
mumble/plugins/MumbleAPI_v_1_0_x.h
Robert Adam 923045ac60 FORMAT: Run clang-format 10 on all source files
2021-04-16 21:05:52 +02:00

531 lines
31 KiB
C++
Raw Blame History

// 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
Reference in New Issue View Git Blame Copy Permalink