mirror of
https://github.com/mumble-voip/mumble.git
synced 2025-10-26 11:19:16 +00:00
03c9fc7a11
Previously all notification sounds were played as is, without taking anything into account. The only way to change the volume was to manually edit the sound files, or change the overall volume of the entire Mumble application. This commit adds the ability for the user to adjust the volume of notification sounds and audio cues. There are two new settings added "notificationVolume" and "cueVolume" to adjust the volume independently. Sliders in the "Messages" have been added and together with the existing TTS volume slider make up the new group "Message Volume". A side effect is the centralization of the db <-> factor conversion functions in the "VolumeAdjustment" class. Furthermore, this commit also introduces a change to the "playSample" API call, accepting a volume parameter, and therefore bumps the Mumble API version to 1.2.x. Implements #3963
538 lines
31 KiB
C
538 lines
31 KiB
C
// Copyright 2021-2022 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 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 <stdint.h>
|
|
|
|
|
|
#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_
|