// Copyright 2023 The Mumble Developers. All rights reserved.
// Use of this source code is governed by a BSD-style license
// that can be found in the LICENSE file at the root of the
// Mumble source tree or at <https://www.mumble.info/LICENSE>.

///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////// CONTROL OVER WHAT SECTIONS TO INCLUDE ////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////

// Whether or not to include default implementations
#ifdef MUMBLE_PLUGIN_NO_DEFAULT_FUNCTION_DEFINITIONS
#	undef EXTERNAL_MUMBLE_PLUGIN_DEFAULT_IMPLEMENTATIONS_
#	define EXTERNAL_MUMBLE_PLUGIN_DEFAULT_IMPLEMENTATIONS_
#endif

// Whether or not to create the MumbleAPI typedef
#undef MUMBLE_PLUGIN_CREATE_MUMBLE_API_TYPEDEF
#ifndef MUMBLE_PLUGIN_NO_API_TYPEDEF
#	define MUMBLE_PLUGIN_CREATE_MUMBLE_API_TYPEDEF
#endif


///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////// MACRO DEFINITIONS //////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef EXTERNAL_MUMBLE_PLUGIN_MACROS_
#	define EXTERNAL_MUMBLE_PLUGIN_MACROS_

/*
 * Plugin version information
 */
#	define MUMBLE_PLUGIN_INTERFACE_MAJOR_MACRO 1
#	define MUMBLE_PLUGIN_INTERFACE_MINOR_MACRO 2
#	define MUMBLE_PLUGIN_INTERFACE_PATCH_MACRO 0

// Allow the selected API version be overwritten by external definitions
#	ifndef MUMBLE_PLUGIN_API_MAJOR_MACRO
#		define MUMBLE_PLUGIN_API_MAJOR_MACRO 1
#	endif
#	ifndef MUMBLE_PLUGIN_API_MINOR_MACRO
#		define MUMBLE_PLUGIN_API_MINOR_MACRO 2
#	endif
#	ifndef MUMBLE_PLUGIN_API_PATCH_MACRO
#		define MUMBLE_PLUGIN_API_PATCH_MACRO 0
#	endif

#	define MUMBLE_PLUGIN_FUNCTIONS_MAJOR_MACRO 1
#	define MUMBLE_PLUGIN_FUNCTIONS_MINOR_MACRO 1
#	define MUMBLE_PLUGIN_FUNCTIONS_PATCH_MACRO 0

/*
 * MUMBLE_PLUGIN_EXPORT
 */
#	if defined(__GNUC__) && !defined(__MINGW32__) // GCC on Unix-like systems
#		define MUMBLE_PLUGIN_EXPORT __attribute__((visibility("default")))
#	elif defined(_MSC_VER)
#		define MUMBLE_PLUGIN_EXPORT __declspec(dllexport)
#	elif defined(__MINGW32__)
#		define MUMBLE_PLUGIN_EXPORT __attribute__((dllexport))
#	else
#		error No MUMBLE_PLUGIN_EXPORT definition available
#	endif

/*
 * MUMBLE_PLUGIN_CALLING_CONVENTION
 */
#	if defined(_MSC_VER)
#		define MUMBLE_PLUGIN_CALLING_CONVENTION __cdecl
#	elif defined(__MINGW32__)
#		define MUMBLE_PLUGIN_CALLING_CONVENTION __attribute__((cdecl))
#	else
#		define MUMBLE_PLUGIN_CALLING_CONVENTION
#	endif

/*
 * MUMBLE_PLUGIN_HAS_QT
 */
#	if defined(QT_CORE_LIB) || defined(QT_VERSION)
#		define MUMBLE_PLUGIN_HAS_QT
#	endif


/*
 * MUMBLE_PLUGIN_VERSION_CHECK
 * Converts a major, minor and patch version number into a single integer to be used in preprocessor
 * if conditions
 */
#	define MUMBLE_PLUGIN_VERSION_CHECK(major, minor, patch) (((major) << 16) | ((minor) << 8) | (patch))

/*
 * MUMBLE_PLUGIN_CONSTEXPR
 */
#	ifdef __cplusplus
#		define MUMBLE_PLUGIN_CONSTEXPR constexpr
#	else
#		define MUMBLE_PLUGIN_CONSTEXPR
#	endif

/*
 * MUMBLE_EXTERN_C_BEGIN / MUMBLE_EXTERN_C_END
 */
#	ifdef __cplusplus
#		define MUMBLE_EXTERN_C_BEGIN extern "C" {
#		define MUMBLE_EXTERN_C_END }
#	else
#		define MUMBLE_EXTERN_C_BEGIN
#		define MUMBLE_EXTERN_C_END
#	endif

// For more info on the necessity of the with/without pattern have a look
// at https://stackoverflow.com/a/3419392

/*
 * MUMBLE_CONCAT
 * Concatenates the given values WITHOUT macro expansion
 */
#	define MUMBLE_CONCAT(a, b) a##_##b
/**
 * MUMBLE_ECONCAT
 * Concatenates the given values WITH macro expansion
 */
#	define MUMBLE_ECONCAT(a, b) MUMBLE_CONCAT(a, b)
/**
 * MUMBLE_QUOTE
 * Quotes the given value WITHOUT macro expansion
 */
#	define MUMBLE_QUOTE(arg) #    arg
/**
 * MUMBLE_EQUOTE
 * Quotes the given value WITH macro expansion
 */
#	define MUMBLE_EQUOTE(arg) MUMBLE_QUOTE(arg)

#endif // EXTERNAL_MUMBLE_PLUGIN_MACROS_



///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////// PLUGIN TYPES /////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef EXTERNAL_MUMBLE_PLUGIN_TYPES_
#	define EXTERNAL_MUMBLE_PLUGIN_TYPES_

#	include <stdint.h>
#	include <stddef.h>
#	include <stdbool.h>

#	ifdef __cplusplus
#		include <string>

#		ifdef MUMBLE_PLUGIN_HAS_QT
#			include <QString>
#		endif
#	endif

MUMBLE_EXTERN_C_BEGIN

/**
 * This enum's values correspond to special feature sets a plugin may provide.
 * They are meant to be or'ed together to represent the total feature set of a plugin.
 */
enum Mumble_PluginFeature {
	/**
	 * None of the below
	 */
	MUMBLE_FEATURE_NONE = 0,
	/**
	 * The plugin provides positional data from a game
	 */
	MUMBLE_FEATURE_POSITIONAL = 1 << 0,
	/**
	 * The plugin modifies the input/output audio itself
	 */
	MUMBLE_FEATURE_AUDIO = 1 << 1,
};

/**
 * This enum's values represent talking states a user can be in when using Mumble.
 */
enum Mumble_TalkingState {
	MUMBLE_TS_INVALID = -1,
	MUMBLE_TS_PASSIVE = 0,
	MUMBLE_TS_TALKING,
	MUMBLE_TS_WHISPERING,
	MUMBLE_TS_SHOUTING,
	MUMBLE_TS_TALKING_MUTED,
};

/**
 * This enum's values represent transmission modes a user might have configured. Transmission mode
 * in this context is referring to a method that determines when a user is speaking and thus when
 * to transmit audio packets.
 */
enum Mumble_TransmissionMode {
	MUMBLE_TM_CONTINOUS,
	MUMBLE_TM_VOICE_ACTIVATION,
	MUMBLE_TM_PUSH_TO_TALK,
};

/**
 * This enum's values represent the error codes that are being used by the MumbleAPI.
 * You can get a string-representation for each error code via the errorMessage function.
 */
enum Mumble_ErrorCode {
	MUMBLE_EC_INTERNAL_ERROR = -2,
	MUMBLE_EC_GENERIC_ERROR  = -1,
	MUMBLE_EC_OK             = 0,
	MUMBLE_EC_POINTER_NOT_FOUND,
	MUMBLE_EC_NO_ACTIVE_CONNECTION,
	MUMBLE_EC_USER_NOT_FOUND,
	MUMBLE_EC_CHANNEL_NOT_FOUND,
	MUMBLE_EC_CONNECTION_NOT_FOUND,
	MUMBLE_EC_UNKNOWN_TRANSMISSION_MODE,
	MUMBLE_EC_AUDIO_NOT_AVAILABLE,
	MUMBLE_EC_INVALID_SAMPLE,
	MUMBLE_EC_INVALID_PLUGIN_ID,
	MUMBLE_EC_INVALID_MUTE_TARGET,
	MUMBLE_EC_CONNECTION_UNSYNCHRONIZED,
	MUMBLE_EC_INVALID_API_VERSION,
	MUMBLE_EC_UNSYNCHRONIZED_BLOB,
	MUMBLE_EC_UNKNOWN_SETTINGS_KEY,
	MUMBLE_EC_WRONG_SETTINGS_TYPE,
	MUMBLE_EC_SETTING_WAS_REMOVED,
	MUMBLE_EC_DATA_TOO_BIG,
	MUMBLE_EC_DATA_ID_TOO_LONG,
	MUMBLE_EC_API_REQUEST_TIMEOUT,
	MUMBLE_EC_OPERATION_UNSUPPORTED_BY_SERVER,
};

/**
 * This enum's values represent error codes specific to the framework of handling positional data
 * gathering (needed for Mumble's positional audio feature).
 */
enum Mumble_PositionalDataErrorCode {
	/**
	 * Positional data has been initialized properly
	 */
	MUMBLE_PDEC_OK = 0,
	/**
	 * Positional data is temporarily unavailable (e.g. because the corresponding process isn't running) but might be
	 * at another point in time.
	 */
	MUMBLE_PDEC_ERROR_TEMP,
	/**
	 * Positional data is permanently unavailable (e.g. because the respective memory offsets are outdated).
	 */
	MUMBLE_PDEC_ERROR_PERM,
};

/**
 * This enum's values represent keys for specific settings inside Mumble.
 */
enum Mumble_SettingsKey {
	MUMBLE_SK_INVALID                           = -1,
	MUMBLE_SK_AUDIO_INPUT_VOICE_HOLD            = 0,
	MUMBLE_SK_AUDIO_INPUT_VAD_SILENCE_THRESHOLD = 1,
	MUMBLE_SK_AUDIO_INPUT_VAD_SPEECH_THRESHOLD  = 2,
	MUMBLE_SK_AUDIO_OUTPUT_PA_MINIMUM_DISTANCE  = 3,
	MUMBLE_SK_AUDIO_OUTPUT_PA_MAXIMUM_DISTANCE  = 4,
	MUMBLE_SK_AUDIO_OUTPUT_PA_BLOOM             = 5,
	MUMBLE_SK_AUDIO_OUTPUT_PA_MINIMUM_VOLUME    = 6,
};

/**
 * This enum's values represent the key-codes Mumble's API uses to reference keys on the keyboard.
 */
enum Mumble_KeyCode {
	MUMBLE_KC_INVALID = -1,

	// Non-printable characters first
	MUMBLE_KC_NULL       = 0,
	MUMBLE_KC_END        = 1,
	MUMBLE_KC_LEFT       = 2,
	MUMBLE_KC_RIGHT      = 4,
	MUMBLE_KC_UP         = 5,
	MUMBLE_KC_DOWN       = 6,
	MUMBLE_KC_DELETE     = 7,
	MUMBLE_KC_BACKSPACE  = 8,
	MUMBLE_KC_TAB        = 9,
	MUMBLE_KC_ENTER      = 10, // == '\n'
	MUMBLE_KC_ESCAPE     = 27,
	MUMBLE_KC_PAGE_UP    = 11,
	MUMBLE_KC_PAGE_DOWN  = 12,
	MUMBLE_KC_SHIFT      = 13,
	MUMBLE_KC_CONTROL    = 14,
	MUMBLE_KC_META       = 15,
	MUMBLE_KC_ALT        = 16,
	MUMBLE_KC_ALT_GR     = 17,
	MUMBLE_KC_CAPSLOCK   = 18,
	MUMBLE_KC_NUMLOCK    = 19,
	MUMBLE_KC_SUPER      = 20, // == windows key
	MUMBLE_KC_HOME       = 21, // == Pos1
	MUMBLE_KC_PRINT      = 22,
	MUMBLE_KC_SCROLLLOCK = 23,

	// Printable characters are assigned to their ASCII code
	MUMBLE_KC_SPACE             = ' ',
	MUMBLE_KC_EXCLAMATION_MARK  = '!',
	MUMBLE_KC_DOUBLE_QUOTE      = '"',
	MUMBLE_KC_HASHTAG           = '#',
	MUMBLE_KC_DOLLAR            = '$',
	MUMBLE_KC_PERCENT           = '%',
	MUMBLE_KC_AMPERSAND         = '&',
	MUMBLE_KC_SINGLE_QUOTE      = '\'',
	MUMBLE_KC_OPEN_PARENTHESIS  = '(',
	MUMBLE_KC_CLOSE_PARENTHESIS = ')',
	MUMBLE_KC_ASTERISK          = '*',
	MUMBLE_KC_PLUS              = '+',
	MUMBLE_KC_COMMA             = ',',
	MUMBLE_KC_MINUS             = '-',
	MUMBLE_KC_PERIOD            = '.',
	MUMBLE_KC_SLASH             = '/',
	MUMBLE_KC_0                 = '0',
	MUMBLE_KC_1                 = '1',
	MUMBLE_KC_2                 = '2',
	MUMBLE_KC_3                 = '3',
	MUMBLE_KC_4                 = '4',
	MUMBLE_KC_5                 = '5',
	MUMBLE_KC_6                 = '6',
	MUMBLE_KC_7                 = '7',
	MUMBLE_KC_8                 = '8',
	MUMBLE_KC_9                 = '9',
	MUMBLE_KC_COLON             = ':',
	MUMBLE_KC_SEMICOLON         = ';',
	MUMBLE_KC_LESS_THAN         = '<',
	MUMBLE_KC_EQUALS            = '=',
	MUMBLE_KC_GREATER_THAN      = '>',
	MUMBLE_KC_QUESTION_MARK     = '?',
	MUMBLE_KC_AT_SYMBOL         = '@',
	MUMBLE_KC_A                 = 'A',
	MUMBLE_KC_B                 = 'B',
	MUMBLE_KC_C                 = 'C',
	MUMBLE_KC_D                 = 'D',
	MUMBLE_KC_E                 = 'E',
	MUMBLE_KC_F                 = 'F',
	MUMBLE_KC_G                 = 'G',
	MUMBLE_KC_H                 = 'H',
	MUMBLE_KC_I                 = 'I',
	MUMBLE_KC_J                 = 'J',
	MUMBLE_KC_K                 = 'K',
	MUMBLE_KC_L                 = 'L',
	MUMBLE_KC_M                 = 'M',
	MUMBLE_KC_N                 = 'N',
	MUMBLE_KC_O                 = 'O',
	MUMBLE_KC_P                 = 'P',
	MUMBLE_KC_Q                 = 'Q',
	MUMBLE_KC_R                 = 'R',
	MUMBLE_KC_S                 = 'S',
	MUMBLE_KC_T                 = 'T',
	MUMBLE_KC_U                 = 'U',
	MUMBLE_KC_V                 = 'V',
	MUMBLE_KC_W                 = 'W',
	MUMBLE_KC_X                 = 'X',
	MUMBLE_KC_Y                 = 'Y',
	MUMBLE_KC_Z                 = 'Z',
	// leave out lowercase letters (for now)
	MUMBLE_KC_OPEN_BRACKET  = '[',
	MUMBLE_KC_BACKSLASH     = '\\',
	MUMBLE_KC_CLOSE_BRACKET = ']',
	MUMBLE_KC_CIRCUMFLEX    = '^',
	MUMBLE_KC_UNDERSCORE    = '_',
	MUMBLE_KC_GRAVE_AKCENT  = '`',
	MUMBLE_KC_OPEN_BRACE    = '{',
	MUMBLE_KC_VERTICAL_BAR  = '|',
	MUMBLE_KC_CLOSE_BRACE   = '}',
	MUMBLE_KC_TILDE         = '~',

	// Some characters from the extended ASCII code
	MUMBLE_KC_DEGREE_SIGN = 176,



	// F-keys
	// Start at a value of 256 as extended ASCII codes range up to 255
	MUMBLE_KC_F1  = 256,
	MUMBLE_KC_F2  = 257,
	MUMBLE_KC_F3  = 258,
	MUMBLE_KC_F4  = 259,
	MUMBLE_KC_F5  = 260,
	MUMBLE_KC_F6  = 261,
	MUMBLE_KC_F7  = 262,
	MUMBLE_KC_F8  = 263,
	MUMBLE_KC_F9  = 264,
	MUMBLE_KC_F10 = 265,
	MUMBLE_KC_F11 = 266,
	MUMBLE_KC_F12 = 267,
	MUMBLE_KC_F13 = 268,
	MUMBLE_KC_F14 = 269,
	MUMBLE_KC_F15 = 270,
	MUMBLE_KC_F16 = 271,
	MUMBLE_KC_F17 = 272,
	MUMBLE_KC_F18 = 273,
	MUMBLE_KC_F19 = 274,
};

/**
 * A struct for representing a version of the form major.minor.patch
 */
struct MumbleVersion {
	int32_t major;
	int32_t minor;
	int32_t patch;
#	ifdef __cplusplus
	explicit operator std::string() const {
		return std::string("v") + std::to_string(this->major) + std::string(".") + std::to_string(this->minor)
			   + std::string(".") + std::to_string(this->patch);
	}

#		ifdef MUMBLE_PLUGIN_HAS_QT
	explicit operator QString() const {
		return QString::fromLatin1("v%0.%1.%2").arg(this->major).arg(this->minor).arg(this->patch);
	}
#		endif
#	endif // __cplusplus
};

/**
 * This struct is used to return Strings from a plugin to Mumble. It is needed in order to
 * work around the limitation of std::string not being part of C (it holds important information
 * about the String's lifetime management requirements).
 */
struct MumbleStringWrapper {
	/**
	 * The pointer to the actual String data
	 */
	const char *data;
	/**
	 * The size of the pointed String data
	 */
	size_t size;
	/**
	 * Whether the wrapped String needs to be released
	 * after its usage. Instances for which this would be
	 * false: Static Strings, String literals
	 */
	bool needsReleasing;
};

MUMBLE_EXTERN_C_END

#endif // EXTERNAL_MUMBLE_PLUGIN_TYPES_


///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////// Type aliases / Typedefs /////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef EXTERNAL_MUMBLE_PLUGIN_TYPEDEFS_
#	define EXTERNAL_MUMBLE_PLUGIN_TYPEDEFS_

/**
 * Typedef for the type of a talking state
 */
typedef enum Mumble_TalkingState mumble_talking_state_t;
/**
 * Typedef for the type of a transmission mode
 */
typedef enum Mumble_TransmissionMode mumble_transmission_mode_t;
/**
 * Typedef for the type of a version
 */
typedef struct MumbleVersion mumble_version_t;
/**
 * Typedef for the type of a connection
 */
typedef int32_t mumble_connection_t;
/**
 * Typedef for the type of a user
 */
typedef uint32_t mumble_userid_t;
/**
 * Typedef for the type of a channel
 */
typedef int32_t mumble_channelid_t;
/**
 * Typedef for the type of an error (code)
 */
typedef enum Mumble_ErrorCode mumble_error_t;
/**
 * Typedef for the type of a plugin ID
 */
typedef uint32_t mumble_plugin_id_t;
/**
 * Typedef for the type of a key to a setting in Mumble
 */
typedef enum Mumble_SettingsKey mumble_settings_key_t;
/**
 * Typedef for the type of a key-code
 */
typedef enum Mumble_KeyCode mumble_keycode_t;

#endif // EXTERNAL_MUMBLE_PLUGIN_TYPEDEFS_



///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////// Non-enum Constants /////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef EXTERNAL_MUMBLE_PLUGIN_CONSTANTS_
#	define EXTERNAL_MUMBLE_PLUGIN_CONSTANTS_

/*
 * Version constants
 */

static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_INTERFACE_MAJOR = MUMBLE_PLUGIN_INTERFACE_MAJOR_MACRO;
static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_INTERFACE_MINOR = MUMBLE_PLUGIN_INTERFACE_MINOR_MACRO;
static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_INTERFACE_PATCH = MUMBLE_PLUGIN_INTERFACE_PATCH_MACRO;
static const MUMBLE_PLUGIN_CONSTEXPR mumble_version_t MUMBLE_PLUGIN_INTERFACE_VERSION = {
	MUMBLE_PLUGIN_INTERFACE_MAJOR, MUMBLE_PLUGIN_INTERFACE_MINOR, MUMBLE_PLUGIN_INTERFACE_PATCH
};

static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_API_MAJOR            = MUMBLE_PLUGIN_API_MAJOR_MACRO;
static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_API_MINOR            = MUMBLE_PLUGIN_API_MINOR_MACRO;
static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_API_PATCH            = MUMBLE_PLUGIN_API_PATCH_MACRO;
static const MUMBLE_PLUGIN_CONSTEXPR mumble_version_t MUMBLE_PLUGIN_API_VERSION = { MUMBLE_PLUGIN_API_MAJOR,
																					MUMBLE_PLUGIN_API_MINOR,
																					MUMBLE_PLUGIN_API_PATCH };

static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_FUNCTIONS_MAJOR = MUMBLE_PLUGIN_FUNCTIONS_MAJOR_MACRO;
static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_FUNCTIONS_MINOR = MUMBLE_PLUGIN_FUNCTIONS_MINOR_MACRO;
static const MUMBLE_PLUGIN_CONSTEXPR int32_t MUMBLE_PLUGIN_FUNCTIONS_PATCH = MUMBLE_PLUGIN_FUNCTIONS_PATCH_MACRO;
static const MUMBLE_PLUGIN_CONSTEXPR mumble_version_t MUMBLE_PLUGIN_FUNCTIONS_VERSION = {
	MUMBLE_PLUGIN_FUNCTIONS_MAJOR, MUMBLE_PLUGIN_FUNCTIONS_MINOR, MUMBLE_PLUGIN_FUNCTIONS_PATCH
};

/**
 * The exit status of a successful operation
 */
static const MUMBLE_PLUGIN_CONSTEXPR mumble_error_t MUMBLE_STATUS_OK = MUMBLE_EC_OK;
/**
 * A version object that is considered to correspond to an unknown version
 */
static const MUMBLE_PLUGIN_CONSTEXPR mumble_version_t MUMBLE_VERSION_UNKNOWN = { 0, 0, 0 };

#endif // EXTERNAL_MUMBLE_PLUGIN_CONSTANTS_



///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
/////////////////////////////////// C convenience implementations /////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef EXTERNAL_MUMBLE_PLUGIN_C_CONVENIENCE_IMPLS_
#	define EXTERNAL_MUMBLE_PLUGIN_C_CONVENIENCE_IMPLS_

/**
 * Obtains a String representation for the given numeric error code.
 * Note that the exact String representation corresponding to an error code may change and is thus
 * not part of the plugin API as such. This function acts merely as a convenience helper for printing
 * errors in a meaningful way.
 *
 * @param errorCode The error code to get the String representation for
 * @returns The error message coresponding to the given error code. The message
 * is encoded as a C-string and is static, meaning that it is safe to use the
 * returned pointer in your code.
 */
MUMBLE_PLUGIN_CONSTEXPR inline const char *mumble_errorMessage(int16_t errorCode) {
	switch (errorCode) {
		case MUMBLE_EC_GENERIC_ERROR:
			return "Generic error";
		case MUMBLE_EC_OK:
			return "Ok - this is not an error";
		case MUMBLE_EC_POINTER_NOT_FOUND:
			return "Can't find the passed pointer";
		case MUMBLE_EC_NO_ACTIVE_CONNECTION:
			return "There is currently no active connection to a server";
		case MUMBLE_EC_USER_NOT_FOUND:
			return "Can't find the requested user";
		case MUMBLE_EC_CHANNEL_NOT_FOUND:
			return "Can't find the requested channel";
		case MUMBLE_EC_CONNECTION_NOT_FOUND:
			return "Can't identify the requested connection";
		case MUMBLE_EC_UNKNOWN_TRANSMISSION_MODE:
			return "Unknown transmission mode encountered";
		case MUMBLE_EC_AUDIO_NOT_AVAILABLE:
			return "There is currently no audio output available";
		case MUMBLE_EC_INVALID_SAMPLE:
			return "Attempted to use invalid sample (can't play it)";
		case MUMBLE_EC_INVALID_PLUGIN_ID:
			return "Used an invalid plugin ID";
		case MUMBLE_EC_INVALID_MUTE_TARGET:
			return "Used an invalid mute-target";
		case MUMBLE_EC_CONNECTION_UNSYNCHRONIZED:
			return "The requested server connection has not yet finished synchronizing";
		case MUMBLE_EC_INVALID_API_VERSION:
			return "The used API version is invalid or not supported";
		case MUMBLE_EC_UNSYNCHRONIZED_BLOB:
			return "The requested blob (content) has not yet been synchronized between the client and the server";
		case MUMBLE_EC_UNKNOWN_SETTINGS_KEY:
			return "The used settings-key does not match any key known to Mumble";
		case MUMBLE_EC_WRONG_SETTINGS_TYPE:
			return "The referenced setting has a different type than requested";
		case MUMBLE_EC_SETTING_WAS_REMOVED:
			return "The referenced setting got removed from Mumble and is no longer used";
		case MUMBLE_EC_DATA_TOO_BIG:
			return "The given data is too large (exceeds limit)";
		case MUMBLE_EC_DATA_ID_TOO_LONG:
			return "The given data ID is too long (exceeds limit)";
		case MUMBLE_EC_API_REQUEST_TIMEOUT:
			return "A blocking API call took too long and was thus aborted (probably preventing a deadlock)";
		case MUMBLE_EC_OPERATION_UNSUPPORTED_BY_SERVER:
			return "The requested API operation depends on server-side functionality, not supported by the server "
				   "you're connected to";
	}

	return "Unknown error code";
}
#endif // EXTERNAL_MUMBLE_PLUGIN_C_CONVENIENCE_IMPLS_



///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////// C++ convenience implementations ////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////

#if !defined(EXTERNAL_MUMBLE_PLUGIN_CPP_CONVENIENCE_IMPLS_) && defined(__cplusplus)
#	define EXTERNAL_MUMBLE_PLUGIN_CPP_CONVENIENCE_IMPLS_

/*
 * Comparison operator overloads for MumbleVersion structs
 */
constexpr bool operator<(const MumbleVersion &lhs, const MumbleVersion &rhs) {
	if (lhs.major != rhs.major) {
		return lhs.major < rhs.major;
	}
	if (lhs.minor != rhs.minor) {
		return lhs.minor < rhs.minor;
	}
	// Major and Minor are equal
	return lhs.patch < rhs.patch;
}

constexpr bool operator==(const MumbleVersion &lhs, const MumbleVersion &rhs) {
	return lhs.major == rhs.major && lhs.minor == rhs.minor && lhs.patch == rhs.patch;
}


constexpr bool operator!=(const MumbleVersion &lhs, const MumbleVersion &rhs) {
	return !(lhs == rhs);
}

constexpr bool operator>(const MumbleVersion &lhs, const MumbleVersion &rhs) {
	return !(lhs == rhs || lhs < rhs);
}

constexpr bool operator>=(const MumbleVersion &lhs, const MumbleVersion &rhs) {
	return lhs == rhs || lhs > rhs;
}

constexpr bool operator<=(const MumbleVersion &lhs, const MumbleVersion &rhs) {
	return lhs == rhs || lhs < rhs;
}

#endif // EXTERNAL_MUMBLE_PLUGIN_CPP_CONVENIENCE_IMPLS_



///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////// Plugin functions //////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef EXTERNAL_MUMBLE_PLUGIN_FUNCTIONS_
#	define EXTERNAL_MUMBLE_PLUGIN_FUNCTIONS_

#	include <stdint.h>
#	include <stddef.h>
#	include <stdbool.h>

MUMBLE_EXTERN_C_BEGIN

// >>>>>>>>>>>>>>>>>>>> MANDATORY functions <<<<<<<<<<<<<<<<<<<<

/**
 * Gets called right after loading the plugin in order to let the plugin initialize.
 *
 * Registers the ID of this plugin.
 * @param id The ID for this plugin. This is the ID Mumble will reference this plugin with
 * and by which this plugin can identify itself when communicating with Mumble.
 * @returns The status of the initialization. If everything went fine, return STATUS_OK
 */
MUMBLE_PLUGIN_EXPORT mumble_error_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_init(mumble_plugin_id_t id);

/**
 * Gets called when unloading the plugin in order to allow it to clean up after itself.
 * Note that it is still safe to call API functions from within this callback.
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_shutdown();

/**
 * Gets the name of the plugin.
 *
 * NOTE: This function may be called without the plugin being loaded
 *
 * @returns A String-wrapper containing the requested name
 */
MUMBLE_PLUGIN_EXPORT struct MumbleStringWrapper MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getName();

/**
 * Gets the Version of the plugin-API this plugin intends to use.
 * Mumble will decide whether this plugin is loadable or not based on the return value of this function.
 *
 * NOTE: This function may be called without the plugin being loaded
 *
 * @returns The respective API Version
 */
MUMBLE_PLUGIN_EXPORT mumble_version_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getAPIVersion();

/**
 * Provides the MumbleAPI struct to the plugin. This struct contains function pointers that can be used
 * to interact with the Mumble client. It is up to the plugin to store this struct somewhere if it wants to make use
 * of it at some point.
 *
 * NOTE: This function may be called without the plugin being loaded
 *
 * @param api A pointer to the MumbleAPI struct. The API struct must be cast to the version corresponding to the
 * user API version. If your plugin is e.g. using the 1.0.x API, then you have to cast this pointer to
 * MumbleAPI_v_1_0_x. Note also that you **must not store this pointer**. It will become invalid. Therefore
 * you have to copy the struct in order to use it later on.
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_registerAPIFunctions(void *apiStruct);

/**
 * Releases the resource pointed to by the given pointer. If the respective resource has been allocated before,
 * this would be the time to free/delete it.
 * The resources processed by this functions are only those that have been specifically allocated in order to return
 * them in one of the plugin functions to Mumble (e.g. the String returned by mumble_getName) and has nothing to do
 * with your plugin's internal resource management.
 * In short: Only resources passed from the plugin to Mumble via a return value may be processed by this function.
 *
 * NOTE1: This function may be called without the plugin being loaded
 *
 * NOTE2: that the pointer might be pointing to memory that had to be allocated without the plugin being loaded.
 * Therefore you should be very sure that there'll be another callback in which you want to free this memory,
 * should you decide to not do it here (which is hereby explicitly advised against).
 *
 * NOTE3: The pointer is const as Mumble won't mess with the memory allocated by the plugin (no modifications).
 * Nontheless this function is explicitly responsible for freeing the respective memory parts. If the memory has
 * been allocated using malloc(), it needs to be freed using free() which requires a const-cast. If however the
 * memory has been created using the new operator you have to cast the pointer back to its original type and then
 * use the  delete operator on it (no const-cast necessary in this case).
 * See https://stackoverflow.com/questions/2819535/unable-to-free-const-pointers-in-c
 * and https://stackoverflow.com/questions/941832/is-it-safe-to-delete-a-void-pointer
 *
 * @param pointer The pointer to the memory that needs free-ing
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_releaseResource(const void *pointer);



// >>>>>>>>>>>>>>>>>>>> GENERAL functions <<<<<<<<<<<<<<<<<<<<

/**
 * Tells the plugin some basic information about the Mumble client loading it.
 * This function will be the first one that is being called on this plugin - even before it is decided whether to load
 * the plugin at all.
 *
 * @param mumbleVersion The Version of the Mumble client
 * @param mumbleAPIVersion The Version of the plugin-API the Mumble client runs with
 * @param minimumExpectedAPIVersion The minimum Version the Mumble clients expects this plugin to meet in order to load
 * it
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_setMumbleInfo(
	mumble_version_t mumbleVersion, mumble_version_t mumbleAPIVersion, mumble_version_t minimumExpectedAPIVersion);

/**
 * Gets the Version of this plugin
 *
 * NOTE: This function may be called without the plugin being loaded
 *
 * @returns The plugin's version
 */
MUMBLE_PLUGIN_EXPORT mumble_version_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getVersion();

/**
 * Gets the name of the plugin author(s).
 *
 * NOTE: This function may be called without the plugin being loaded
 *
 * @returns A String-wrapper containing the requested author name(s)
 */
MUMBLE_PLUGIN_EXPORT struct MumbleStringWrapper MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getAuthor();

/**
 * Gets the description of the plugin.
 *
 * NOTE: This function may be called without the plugin being loaded
 *
 * @returns A String-wrapper containing the requested description
 */
MUMBLE_PLUGIN_EXPORT struct MumbleStringWrapper MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getDescription();

/**
 * Gets the feature set of this plugin. The feature set is described by bitwise or'ing the elements of the
 * Mumble_PluginFeature enum together.
 *
 * NOTE: This function may be called without the plugin being loaded
 *
 * @returns The feature set of this plugin
 */
MUMBLE_PLUGIN_EXPORT uint32_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getFeatures();

/**
 * Requests this plugin to deactivate the given (sub)set of provided features.
 * If this is not possible, the features that can't be deactivated shall be returned by this function.
 *
 * Example (check if FEATURE_POSITIONAL shall be deactivated):
 * @code
 * if (features & FEATURE_POSITIONAL) {
 *   // positional shall be deactivated
 * }
 * @endcode
 *
 * @param features The feature set that shall be deactivated
 * @returns The feature set that can't be disabled (bitwise or'ed). If all requested features can be disabled, return
 * FEATURE_NONE. If none of the requested features can be disabled return the unmodified features parameter.
 */
MUMBLE_PLUGIN_EXPORT uint32_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_deactivateFeatures(uint32_t features);


// >>>>>>>>>>>>>>>>>>>> POSITIONAL DATA functions <<<<<<<<<<<<<<<<<<<<

/*
 * If this plugin wants to provide positional data, the mumble_initPositionalData, mumble_fetchPositionalData
 * and mumble_shutdownPositionalData functions have to be implemented together (implementing only a subset
 * will yield the same result as if no support for positional data was implemened).
 */

/**
 * Indicates that Mumble wants to use this plugin to request positional data. Therefore it should check whether it is
 * currently able to do so and allocate memory that is needed for that process. As a parameter this function gets an
 * array of names and an array of PIDs. They are of same length and the PID at index i belongs to a program whose name
 * is listed at index i in the "name-array".
 *
 * @param programNames An array of pointers to the program names
 * @param programPIDs An array of the corresponding program PIDs
 * @param programCount The length of programNames and programPIDs
 * @returns The error code. If everything went fine PDEC_OK shall be returned. In that case Mumble will start
 * frequently calling fetchPositionalData. If this returns anything but PDEC_OK, Mumble will assume that the plugin is
 * (currently) uncapable of providing positional data. In this case this function must not have allocated any memory
 * that needs to be cleaned up later on. Depending on the returned error code, Mumble might try to call this function
 * again at some point.
 */
MUMBLE_PLUGIN_EXPORT uint8_t MUMBLE_PLUGIN_CALLING_CONVENTION mumble_initPositionalData(const char *const *programNames,
																						const uint64_t *programPIDs,
																						size_t programCount);

/**
 * Retrieves the positional data. If no data can be fetched, set all float-vectors to 0 and return false.
 *
 * @param[out] avatarPos A float-array of size 3 representing the cartesian position of the player/avatar in the ingame
 * world. One unit represents one meter of distance.
 * @param[out] avatarDir A float-array of size 3 representing the cartesian direction-vector of the player/avatar
 * ingame (where it is facing).
 * @param[out] avatarAxis A float-array of size 3 representing the vector pointing from the toes of the character to
 * its head. One unit represents one meter of distance.
 * @param[out] cameraPos A float-array of size 3 representing the cartesian position of the camera in the ingame world.
 * One unit represents one meter of distance.
 * @param[out] cameraDir A float-array of size 3 representing the cartesian direction-vector of the camera ingame
 * (where it is facing).
 * @param[out] cameraAxis A float-array of size 3 representing a vector from the bottom of the camera to its top. One
 * unit represents one meter of distance.
 * @param[out] context A pointer to where the pointer to a C-encoded string storing the context of the provided
 * positional data shall be written. This context should include information about the server (and team) the player is
 * on. Only players with identical context will be able to hear each other's audio. The returned pointer has to remain
 * valid until the next invokation of this function or until shutdownPositionalData is called.
 * @param[out] identity A pointer to where the pointer to a C-encoded string storing the identity of the player shall
 * be written. It can be polled by external scripts from the server and should uniquely identify the player in the
 * game. The pointer has to remain valid until the next invokation of this function or until shutdownPositionalData is
 * called.
 * @returns Whether this plugin can continue delivering positional data. If this function returns false,
 * shutdownPositionalData will be called.
 */
MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION
	mumble_fetchPositionalData(float *avatarPos, float *avatarDir, float *avatarAxis, float *cameraPos,
							   float *cameraDir, float *cameraAxis, const char **context, const char **identity);

/**
 * Indicates that this plugin will not be asked for positional data any longer. Thus any memory allocated for this
 * purpose should be freed at this point.
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_shutdownPositionalData();

/**
 * The context in positional data is used to determine whether different positional data sets from different
 * clients belong to the same game (and same server). Only if the contexts matches up across these clients,
 * will Mumble activate the positional audio effects, as it will assume that these clients are playing the
 * same game together.
 * The context is set during fetching of the other positional data and is usually something like e.g. the
 * current server's name. In order to avoid clashes between different plugins (that most likely work for
 * different games), the context is prefixed by Mumble. If this function is not implemented, the name of
 * the plugin is used as a prefix (which tends to be the supported game's name), but sometimes a different
 * prefix is desirable. For these cases, a custom prefix can be provided through this function.
 *
 * NOTE that while it is possible to allocate a string for this purpose every time this function is called
 * and then letting mumble release the resource again (via mumble_releaseResource), it is generally not the
 * advised way of doing things (it may impact overall performance negatively, since this function will be
 * called very frequently). Instead you should either return a static string (if your language supports that
 * and if it actually fits your needs) or you should allocate a string during mumble_initPositionalData and
 * free it in mumble_shutdownPositionalData and when returning the string in this function, tell Mumble that
 * the string does not need releasing.
 *
 * @returns The context prefix to use for positional data fetched by this plugin.
 *
 * @since Plugin interface v1.1.0
 */
MUMBLE_PLUGIN_EXPORT struct MumbleStringWrapper MUMBLE_PLUGIN_CALLING_CONVENTION
	mumble_getPositionalDataContextPrefix();



// >>>>>>>>>>>>>>>>>>>> EVENTHANDLER / CALLBACK functions <<<<<<<<<<<<<<<<<<<<

/**
 * Called when connecting to a server.
 * Note that in most cases you'll want to use mumble_onServerSynchronized instead.
 * Note also that this callback will be called from a DIFFERENT THREAD!
 *
 * @param connection The ID of the newly established server-connection
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onServerConnected(mumble_connection_t connection);

/**
 * Called when disconnecting from a server.
 * Note that this callback is called from a DIFFERENT THREAD!
 *
 * @param connection The ID of the server-connection that has been terminated
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onServerDisconnected(mumble_connection_t connection);

/**
 * Called when the client has finished synchronizing with the server
 *
 * @param connection The ID of the server-connection that has been terminated
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onServerSynchronized(mumble_connection_t connection);

/**
 * Called whenever any user on the server enters a channel
 * This function will also be called when freshly connecting to a server as each user on that
 * server needs to be "added" to the respective channel as far as the local client is concerned.
 *
 * @param connection The ID of the server-connection this event is connected to
 * @param userID The ID of the user this event has been triggered for
 * @param previousChannelID The ID of the chanel the user is coming from. Negative IDs indicate that there is no
 * previous channel (e.g. the user freshly connected to the server) or the channel isn't available because of any other
 * reason.
 * @param newChannelID The ID of the channel the user has entered. If the ID is negative, the new channel could not be
 * retrieved. This means that the ID is invalid.
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onChannelEntered(mumble_connection_t connection,
																				   mumble_userid_t userID,
																				   mumble_channelid_t previousChannelID,
																				   mumble_channelid_t newChannelID);

/**
 * Called whenever a user leaves a channel.
 * This includes a client disconnecting from the server as this will also lead to the user not being in that channel
 * anymore.
 *
 * @param connection The ID of the server-connection this event is connected to
 * @param userID The ID of the user that left the channel
 * @param channelID The ID of the channel the user left. If the ID is negative, the channel could not be retrieved.
 * This means that the ID is invalid.
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onChannelExited(mumble_connection_t connection,
																				  mumble_userid_t userID,
																				  mumble_channelid_t channelID);

/**
 * Called when any user changes his/her talking state.
 *
 * @param connection The ID of the server-connection this event is connected to
 * @param userID The ID of the user whose talking state has been changed
 * @param talkingState The new TalkingState the user has switched to.
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onUserTalkingStateChanged(
	mumble_connection_t connection, mumble_userid_t userID, mumble_talking_state_t talkingState);

/**
 * Called whenever there is audio input.
 * Note that this callback will be called from the AUDIO THREAD.
 * Note also that blocking this callback will cause Mumble's audio processing to get suspended.
 *
 * @param inputPCM A pointer to a short-array holding the pulse-code-modulation (PCM) representing the audio input. Its
 * length is sampleCount * channelCount. The PCM format for stereo input is [LRLRLR...] where L and R are samples of
 * the left and right channel respectively.
 * @param sampleCount The amount of sample points per channel
 * @param channelCount The amount of channels in the audio
 * @param sampleRate The used sample rate in Hz
 * @param isSpeech A boolean flag indicating whether Mumble considers the input as part of speech (instead of
 * background noise)
 * @returns Whether this callback has modified the audio input-array
 */
MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onAudioInput(short *inputPCM, uint32_t sampleCount,
																			   uint16_t channelCount,
																			   uint32_t sampleRate, bool isSpeech);

/**
 * Called whenever Mumble fetches data from an active audio source (could be a voice packet or a playing sample).
 * The provided audio buffer is the raw buffer without any processing applied to it yet.
 * Note that this callback will be called from the AUDIO THREAD.
 * Note also that blocking this callback will cause Mumble's audio processing to get suspended.
 *
 * @param outputPCM A pointer to a float-array holding the pulse-code-modulation (PCM) representing the audio output.
 * Its length is sampleCount * channelCount. The PCM format for stereo output is [LRLRLR...] where L and R are samples
 * of the left and right channel respectively.
 * @param sampleCount The amount of sample points per channel
 * @param channelCount The amount of channels in the audio
 * @param sampleRate The used sample rate in Hz
 * @param isSpeech Whether this audio belongs to a received voice packet (and will thus (most likely) contain speech)
 * @param userID If isSpeech is true, this contains the ID of the user this voice packet belongs to. If isSpeech is
 * false, the content of this parameter is unspecified and should not be accessed
 * @returns Whether this callback has modified the audio output-array
 */
MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION
	mumble_onAudioSourceFetched(float *outputPCM, uint32_t sampleCount, uint16_t channelCount, uint32_t sampleRate,
								bool isSpeech, mumble_userid_t userID);

/**
 * Called whenever the fully mixed and processed audio is about to be handed to the audio backend (about to be played).
 * Note that this happens immediately before Mumble clips the audio buffer.
 * Note that this callback will be called from the AUDIO THREAD.
 * Note also that blocking this callback will cause Mumble's audio processing to get suspended.
 *
 * @param outputPCM A pointer to a float-array holding the pulse-code-modulation (PCM) representing the audio output.
 * Its length is sampleCount * channelCount. The PCM format for stereo output is [LRLRLR...] where L and R are samples
 * of the left and right channel respectively.
 * @param sampleCount The amount of sample points per channel
 * @param channelCount The amount of channels in the audio
 * @param sampleRate The used sample rate in Hz
 * @returns Whether this callback has modified the audio output-array
 */
MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onAudioOutputAboutToPlay(float *outputPCM,
																						   uint32_t sampleCount,
																						   uint16_t channelCount,
																						   uint32_t sampleRate);

/**
 * Called whenever data has been received that has been sent by a plugin. This data should only be processed by the
 * intended plugin. For this reason a dataID is provided that should be used to determine whether the data is intended
 * for this plugin or not. As soon as the data has been processed, no further plugins will be notified about it.
 *
 * @param connection The ID of the server-connection the data is coming from
 * @param sender The ID of the user whose client's plugin has sent the data
 * @param data The sent data array. This can be an arbitrary sequence of bytes.
 * @param dataLength The length of the data array
 * @param dataID The ID of this data (C-encoded)
 * @return Whether the given data has been processed by this plugin
 */
MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onReceiveData(mumble_connection_t connection,
																				mumble_userid_t sender,
																				const uint8_t *data, size_t dataLength,
																				const char *dataID);

/**
 * Called when a new user gets added to the user model. This is the case when that new user freshly connects to the
 * server the local user is on but also when the local user connects to a server other clients are already connected to
 * (in this case this method will be called for every client already on that server).
 *
 * @param connection An object used to identify the current connection
 * @param userID The ID of the user that has been added
 */

MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onUserAdded(mumble_connection_t connection,
																			  mumble_userid_t userID);

/**
 * Called when a user gets removed from the user model. This is the case when that user disconnects from the server the
 * local user is on but also when the local user disconnects from a server other clients are connected to (in this case
 * this method will be called for every client on that server).
 *
 * @param connection An object used to identify the current connection
 * @param userID The ID of the user that has been removed
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onUserRemoved(mumble_connection_t connection,
																				mumble_userid_t userID);

/**
 * Called when a new channel gets added to the user model. This is the case when a new channel is created on the server
 * the local user is on but also when the local user connects to a server that contains channels other than the
 * root-channel (in this case this method will be called for ever non-root channel on that server).
 *
 * @param connection An object used to identify the current connection
 * @param channelID The ID of the channel that has been added
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onChannelAdded(mumble_connection_t connection,
																				 mumble_channelid_t channelID);

/**
 * Called when a channel gets removed from the user model. This is the case when a channel is removed on the server the
 * local user is on but also when the local user disconnects from a server that contains channels other than the
 * root-channel (in this case this method will be called for ever non-root channel on that server).
 *
 * @param connection An object used to identify the current connection
 * @param channelID The ID of the channel that has been removed
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onChannelRemoved(mumble_connection_t connection,
																				   mumble_channelid_t channelID);

/**
 * Called when a channel gets renamed. This also applies when a new channel is created (thus assigning it an initial
 * name is also considered renaming).
 *
 * @param connection An object used to identify the current connection
 * @param channelID The ID of the channel that has been renamed
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onChannelRenamed(mumble_connection_t connection,
																				   mumble_channelid_t channelID);

/**
 * Called when a key has been pressed or released while Mumble has keyboard focus.
 * Note that this callback will only work if the user has explicitly given permission to monitor keyboard
 * events for this plugin. Thus if you want to use this callback, make sure your users know that they have to
 * enable that.
 *
 * @param keyCode The key code of the respective key. The character codes are defined
 * via the Mumble_KeyCode enum. For printable 7-bit ASCII characters these codes conform
 * to the ASCII code-page with the only difference that case is not distinguished. Therefore
 * always the upper-case letter code will be used for letters.
 * @param wasPres Whether the respective key has been pressed (instead of released)
 */
MUMBLE_PLUGIN_EXPORT void MUMBLE_PLUGIN_CALLING_CONVENTION mumble_onKeyEvent(uint32_t keyCode, bool wasPress);



// >>>>>>>>>>>>>>>>>>>> PLUGIN UPDATE functions <<<<<<<<<<<<<<<<<<<<

/**
 * This function is used to determine whether the plugin can find an update for itself that is available for download.
 *
 * NOTE: This function may be called without the plugin being loaded
 *
 * @return Whether the plugin was able to find an update for itself
 */
MUMBLE_PLUGIN_EXPORT bool MUMBLE_PLUGIN_CALLING_CONVENTION mumble_hasUpdate();

/**
 * This function is used to retrieve the URL for downloading the newer/updated version of this plugin.
 *
 * NOTE: This function may be called without the plugin being loaded
 *
 * @returns A String-wrapper containing the requested URL
 */
MUMBLE_PLUGIN_EXPORT struct MumbleStringWrapper MUMBLE_PLUGIN_CALLING_CONVENTION mumble_getUpdateDownloadURL();



// >>>>>>>>>>>>>>>>>>>> DEFAULT functions <<<<<<<<<<<<<<<<<<<<
// These functions don't have to be implemented by you

/**
 * Gets the version of the plugin functions interface that this plugin uses or wants to use.
 * Based on this, Mumble will decide what kind of functions to look for and load from your plugin.
 */
MUMBLE_PLUGIN_EXPORT mumble_version_t mumble_getPluginFunctionsVersion();

MUMBLE_EXTERN_C_END
#endif // EXTERNAL_MUMBLE_PLUGIN_FUNCTIONS_


///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////// DEFAULT IMPLEMENTATIONS /////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef EXTERNAL_MUMBLE_PLUGIN_DEFAULT_IMPLEMENTATIONS_
#	define EXTERNAL_MUMBLE_PLUGIN_DEFAULT_IMPLEMENTATIONS_

mumble_version_t mumble_getPluginFunctionsVersion() {
	return MUMBLE_PLUGIN_FUNCTIONS_VERSION;
}

#endif // EXTERNAL_MUMBLE_PLUGIN_DEFAULT_IMPLEMENTATIONS_



///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////// Mumble API ///////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef EXTERNAL_MUMBLE_PLUGIN_MUMBLE_API_
#	define EXTERNAL_MUMBLE_PLUGIN_MUMBLE_API_

// Define a struct name that contains the respective version number
#	undef MUMBLE_API_STRUCT_NAME
#	define MUMBLE_API_STRUCT_NAME                                                                                     \
		MUMBLE_ECONCAT(                                                                                                \
			MUMBLE_ECONCAT(MUMBLE_ECONCAT(MumbleAPI_v, MUMBLE_PLUGIN_API_MAJOR_MACRO), MUMBLE_PLUGIN_API_MINOR_MACRO), \
			x)

#	undef MUMBLE_API_CAST
#	define MUMBLE_API_CAST(ptr) (*((MUMBLE_API_STRUCT_NAME *) ptr))

// Define some helper macros to make version-specific changes to the API functions
#	define SELECTED_API_VERSION                                                                  \
		MUMBLE_PLUGIN_VERSION_CHECK(MUMBLE_PLUGIN_API_MAJOR_MACRO, MUMBLE_PLUGIN_API_MINOR_MACRO, \
									MUMBLE_PLUGIN_API_PATCH_MACRO)
#	if SELECTED_API_VERSION >= MUMBLE_PLUGIN_VERSION_CHECK(1, 2, 0)
#		define PARAM_v1_2(arg) , arg
#	else
#		define PARAM_v1_2(arg)
#	endif

struct MUMBLE_API_STRUCT_NAME {
	/*
	 * GENERAL NOTES
	 *
	 * All functions that take in a connection as a parameter may only be called **after** the connection
	 * has finished synchronizing. The only exception from this is isConnectionSynchronized.
	 *
	 * Strings returned by the API are UTF-8 encoded
	 * Strings passed to the API are expected to be UTF-8 encoded
	 *
	 * All API functions are synchronized and will be executed in Mumble's "main thread" from which most plugin
	 * callbacks are called as well. Note however that an API call is BLOCKING if invoked from a different
	 * thread. This means that they can cause deadlocks if used without caution. An example that will lead
	 * to a deadlock is:
	 * - plugin callback gets called from the main thread
	 * - callback messages a separate thread to do something and waits for the action to have completed
	 * - Separate thread calls an API function
	 * - The function blocks and waits to be executed in the main thread which is currently blocked waiting
	 * - deadlock
	 */


	// -------- Memory management --------

	/**
	 * Frees the given pointer.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param pointer The pointer to free
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *freeMemory)(mumble_plugin_id_t callerID, const void *pointer);



	// -------- Getter functions --------

	/**
	 * Gets the connection ID of the server the user is currently active on (the user's audio output is directed at).
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param[out] connection A pointer to the memory location the ID should be written to
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then it is valid to access
	 * the value of the provided pointer
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getActiveServerConnection)(mumble_plugin_id_t callerID,
																				mumble_connection_t *connection);

	/**
	 * Checks whether the given connection has finished initializing yet.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param[out] A pointer to the boolean variable that'll hold the info whether the server has finished
	 * synchronization yet after this function has executed successfully.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *isConnectionSynchronized)(mumble_plugin_id_t callerID,
																			   mumble_connection_t connection,
																			   bool *synchronized);

	/**
	 * Fills in the information about the local user.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param[out] userID A pointer to the memory the user's ID shall be written to
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getLocalUserID)(mumble_plugin_id_t callerID,
																	 mumble_connection_t connection,
																	 mumble_userid_t *userID);

	/**
	 * Fills in the information about the given user's name.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param userID The user's ID whose name should be obtained
	 * @param[out] userName A pointer to where the pointer to the allocated string (C-encoded) should be written to.
	 * The allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
	 * allocated if this function returns STATUS_OK.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getUserName)(mumble_plugin_id_t callerID,
																  mumble_connection_t connection,
																  mumble_userid_t userID, const char **userName);

	/**
	 * Fills in the information about the given channel's name.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param channelID The channel's ID whose name should be obtained
	 * @param[out] channelName A pointer to where the pointer to the allocated string (C-ecoded) should be written to.
	 * The allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
	 * allocated if this function returns STATUS_OK.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getChannelName)(mumble_plugin_id_t callerID,
																	 mumble_connection_t connection,
																	 mumble_channelid_t channelID,
																	 const char **channelName);

	/**
	 * Gets an array of all users that are currently connected to the provided server. Passing a nullptr as any of the
	 * out-parameter will prevent that property to be set/allocated. If you are only interested in the user count you
	 * can thus pass nullptr as the users parameter and save time on allocating + freeing the channels-array while
	 * still getting the size out.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param[out] users A pointer to where the pointer of the allocated array shall be written. The
	 * allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
	 * allocated if this function returns STATUS_OK.
	 * @param[out] userCount A pointer to where the size of the allocated user-array shall be written to
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getAllUsers)(mumble_plugin_id_t callerID,
																  mumble_connection_t connection,
																  mumble_userid_t **users, size_t *userCount);

	/**
	 * Gets an array of all channels on the provided server. Passing a nullptr as any of the out-parameter will prevent
	 * that property to be set/allocated. If you are only interested in the channel count you can thus pass nullptr as
	 * the channels parameter and save time on allocating + freeing the channels-array while still getting the size
	 * out.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param[out] channels A pointer to where the pointer of the allocated array shall be written. The
	 * allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
	 * allocated if this function returns STATUS_OK.
	 * @param[out] channelCount A pointer to where the size of the allocated channel-array shall be written to
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getAllChannels)(mumble_plugin_id_t callerID,
																	 mumble_connection_t connection,
																	 mumble_channelid_t **channels,
																	 size_t *channelCount);

	/**
	 * Gets the ID of the channel the given user is currently connected to.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param userID The ID of the user to search for
	 * @param[out] A pointer to where the ID of the channel shall be written
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getChannelOfUser)(mumble_plugin_id_t callerID,
																	   mumble_connection_t connection,
																	   mumble_userid_t userID,
																	   mumble_channelid_t *channel);

	/**
	 * Gets an array of all users in the specified channel.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param channelID The ID of the channel whose users shall be retrieved
	 * @param[out] userList A pointer to where the pointer of the allocated array shall be written. The allocated
	 * memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be allocated if
	 * this function returns STATUS_OK.
	 * @param[out] userCount A pointer to where the size of the allocated user-array shall be written to
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getUsersInChannel)(mumble_plugin_id_t callerID,
																		mumble_connection_t connection,
																		mumble_channelid_t channelID,
																		mumble_userid_t **userList, size_t *userCount);

	/**
	 * Gets the current transmission mode of the local user.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param[out] transmissionMode A pointer to where the transmission mode shall be written.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getLocalUserTransmissionMode)(
		mumble_plugin_id_t callerID, mumble_transmission_mode_t *transmissionMode);

	/**
	 * Checks whether the given user is currently locally muted.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param userID The ID of the user to check for
	 * @param[out] muted A pointer to where the local mute state of that user shall be written
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *isUserLocallyMuted)(mumble_plugin_id_t callerID,
																		 mumble_connection_t connection,
																		 mumble_userid_t userID, bool *muted);

	/**
	 * Checks whether the local user is currently muted.
	 *	/// @param callerID The ID of the plugin calling this function
	 * @param[out] muted A pointer to where the mute state of the local user shall be written
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *isLocalUserMuted)(mumble_plugin_id_t callerID, bool *muted);

	/**
	 * Checks whether the local user is currently deafened.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param[out] deafened A pointer to where the deaf state of the local user shall be written
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *isLocalUserDeafened)(mumble_plugin_id_t callerID, bool *deafened);

	/**
	 * Gets the hash of the given user (can be used to recognize users between restarts)
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param userID The ID of the user to search for
	 * @param[out] hash A pointer to where the pointer to the allocated string (C-encoded) should be written to. The
	 * allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
	 * allocated if this function returns STATUS_OK.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getUserHash)(mumble_plugin_id_t callerID,
																  mumble_connection_t connection,
																  mumble_userid_t userID, const char **hash);

	/**
	 * Gets the hash of the server for the given connection (can be used to recognize servers between restarts)
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection
	 * @param[out] hash A pointer to where the pointer to the allocated string (C-encoded) should be written to. The
	 * allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
	 * allocated if this function returns STATUS_OK.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getServerHash)(mumble_plugin_id_t callerID,
																	mumble_connection_t connection, const char **hash);

	/**
	 * Gets the comment of the given user. Note that a user might have a comment configured that hasn't been
	 * synchronized to this client yet. In this case this function will return EC_UNSYNCHRONIZED_BLOB. As of now there
	 * is now way to request the synchronization to happen via the Plugin-API.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection
	 * @param userID the ID of the user whose comment should be obtained
	 * @param[out] comment A pointer to where the pointer to the allocated string (C-encoded) should be written to. The
	 * allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
	 * allocated if this function returns STATUS_OK.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getUserComment)(mumble_plugin_id_t callerID,
																	 mumble_connection_t connection,
																	 mumble_userid_t userID, const char **comment);

	/**
	 * Gets the description of the given channel. Note that a channel might have a description configured that hasn't
	 * been synchronized to this client yet. In this case this function will return EC_UNSYNCHRONIZED_BLOB. As of now
	 * there is now way to request the synchronization to happen via the Plugin-API.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection
	 * @param channelID the ID of the channel whose comment should be obtained
	 * @param[out] description A pointer to where the pointer to the allocated string (C-encoded) should be written to.
	 * The allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will only be
	 * allocated if this function returns STATUS_OK.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getChannelDescription)(mumble_plugin_id_t callerID,
																			mumble_connection_t connection,
																			mumble_channelid_t channelID,
																			const char **description);


	// -------- Request functions --------

	/**
	 * Requests Mumble to set the local user's transmission mode to the specified one. If you only need to temporarily
	 * set the transmission mode to continous, use requestMicrophoneActivationOverwrite instead as this saves you the
	 * work of restoring the previous state afterwards.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param transmissionMode The requested transmission mode
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *requestLocalUserTransmissionMode)(
		mumble_plugin_id_t callerID, mumble_transmission_mode_t transmissionMode);

	/**
	 * Requests Mumble to move the given user into the given channel
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param userID The ID of the user that shall be moved
	 * @param channelID The ID of the channel to move the user to
	 * @param password The password of the target channel (UTF-8 encoded as a C-string). Pass NULL if the target
	 * channel does not require a password for entering
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *requestUserMove)(mumble_plugin_id_t callerID,
																	  mumble_connection_t connection,
																	  mumble_userid_t userID,
																	  mumble_channelid_t channelID,
																	  const char *password);

	/**
	 * Requests Mumble to overwrite the microphone activation so that the microphone is always on (same as if the user
	 * had chosen the continous transmission mode). If a plugin requests this overwrite, it is responsible for
	 * deactivating the overwrite again once it is no longer required
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param activate Whether to activate the overwrite (false deactivates an existing overwrite)
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *requestMicrophoneActivationOvewrite)(mumble_plugin_id_t callerID,
																						  bool activate);

	/**
	 * Requests Mumble to set the local mute state of the given client. Note that this only affects the **local** mute
	 * state opposed to a server-mute (client is globally muted by the server) or the client's own mute-state (client
	 * has muted its microphone and thus isn't transmitting any audio). Furthermore it must be noted that muting the
	 * local user with this function does not work (it doesn't make sense). If you try to do so, this function will
	 * fail. In order to make this work, this function will also fail if the server has not finished synchronizing with
	 * the client yet. For muting the local user, use requestLocalUserMute instead.
	 *
	 * @param callerID The ID of the plugin calling this function.
	 * @param connection The ID of the server-connection to use as a context
	 * @param userID The ID of the user that shall be muted
	 * @param muted Whether to locally mute the given client (opposed to unmuting it)
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *requestLocalMute)(mumble_plugin_id_t callerID,
																	   mumble_connection_t connection,
																	   mumble_userid_t userID, bool muted);

	/**
	 * Requests Mumble to set the mute state of the local user. In the UI this is referred to as "self-mute".
	 *
	 * @param callerID The ID of the plugin calling this function.
	 * @param muted Whether to locally mute the local user (opposed to unmuting it)
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *requestLocalUserMute)(mumble_plugin_id_t callerID, bool muted);

	/**
	 * Requests Mumble to set the deaf state of the local user. In the UI this is referred to as "self-deaf".
	 *
	 * @param callerID The ID of the plugin calling this function.
	 * @param deafened Whether to locally deafen the local user (opposed to undeafening it)
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *requestLocalUserDeaf)(mumble_plugin_id_t callerID, bool deafened);

	/**
	 * Sets the comment of the local user
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection
	 * @param comment The new comment to use (C-encoded). A subset of HTML formatting is supported.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer
	 * may be accessed
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *requestSetLocalUserComment)(mumble_plugin_id_t callerID,
																				 mumble_connection_t connection,
																				 const char *comment);



	// -------- Find functions --------

	/**
	 * Fills in the information about a user with the specified name, if such a user exists. The search is
	 * case-sensitive.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param userName The respective user's name
	 * @param[out] userID A pointer to the memory the user's ID shall be written to
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
	 * be accessed.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *findUserByName)(mumble_plugin_id_t callerID,
																	 mumble_connection_t connection,
																	 const char *userName, mumble_userid_t *userID);

	/**
	 * Fills in the information about a channel with the specified name, if such a channel exists. The search is
	 * case-sensitive.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to use as a context
	 * @param channelName The respective channel's name
	 * @param[out] channelID A pointer to the memory the channel's ID shall be written to
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
	 * be accessed.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *findChannelByName)(mumble_plugin_id_t callerID,
																		mumble_connection_t connection,
																		const char *channelName,
																		mumble_channelid_t *channelID);



	// -------- Settings --------

	/**
	 * Fills in the current value of the setting with the given key. Note that this function can only be used for
	 * settings whose value is a bool!
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param key The key to the desired setting
	 * @param[out] outValue A pointer to the memory the setting's value shall be written to.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
	 * be accessed.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getMumbleSetting_bool)(mumble_plugin_id_t callerID,
																			mumble_settings_key_t key, bool *outValue);

	/**
	 * Fills in the current value of the setting with the given key. Note that this function can only be used for
	 * settings whose value is an int!
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param key The key to the desired setting
	 * @param[out] outValue A pointer to the memory the setting's value shall be written to.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
	 * be accessed.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getMumbleSetting_int)(mumble_plugin_id_t callerID,
																		   mumble_settings_key_t key,
																		   int64_t *outValue);

	/**
	 * Fills in the current value of the setting with the given key. Note that this function can only be used for
	 * settings whose value is a double!
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param key The key to the desired setting
	 * @param[out] outValue A pointer to the memory the setting's value shall be written to.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
	 * be accessed.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getMumbleSetting_double)(mumble_plugin_id_t callerID,
																			  mumble_settings_key_t key,
																			  double *outValue);

	/**
	 * Fills in the current value of the setting with the given key. Note that this function can only be used for
	 * settings whose value is a String!
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param key The key to the desired setting
	 * @param[out] outValue The memory address to which the pointer to the setting's value (the String) will be
	 * written. The allocated memory has to be freed by a call to freeMemory by the plugin eventually. The memory will
	 * only be allocated if this function returns STATUS_OK.
	 * @returns The error code. If everything went well, STATUS_OK will be returned. Only then the passed pointer may
	 * be accessed.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getMumbleSetting_string)(mumble_plugin_id_t callerID,
																			  mumble_settings_key_t key,
																			  const char **outValue);


	/**
	 * Sets the value of the setting with the given key. Note that this function can only be used for settings whose
	 * value is a bool!
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param key The key to the desired setting
	 * @param value The value that should be set for the given setting
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *setMumbleSetting_bool)(mumble_plugin_id_t callerID,
																			mumble_settings_key_t key, bool value);

	/**
	 * Sets the value of the setting with the given key. Note that this function can only be used for settings whose
	 * value is an int!
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param key The key to the desired setting
	 * @param value The value that should be set for the given setting
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *setMumbleSetting_int)(mumble_plugin_id_t callerID,
																		   mumble_settings_key_t key, int64_t value);

	/**
	 * Sets the value of the setting with the given key. Note that this function can only be used for settings whose
	 * value is a double!
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param key The key to the desired setting
	 * @param value The value that should be set for the given setting
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *setMumbleSetting_double)(mumble_plugin_id_t callerID,
																			  mumble_settings_key_t key, double value);

	/**
	 * Sets the value of the setting with the given key. Note that this function can only be used for settings whose
	 * value is a string!
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param key The key to the desired setting
	 * @param value The value that should be set for the given setting
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *setMumbleSetting_string)(mumble_plugin_id_t callerID,
																			  mumble_settings_key_t key,
																			  const char *value);



	// -------- Miscellaneous --------

	/**
	 * Sends the provided data to the provided client(s). This kind of data can only be received by another plugin
	 * active on that client. The sent data can be seen by any active plugin on the receiving client. Therefore the
	 * sent data must not contain sensitive information or anything else that shouldn't be known by others.
	 *
	 * NOTE: Messages sent via this API function are rate-limited by the server. If the rate-limit is hit, the message
	 * will be dropped without an error message. The rate-limiting is global (e.g. it doesn't matter which plugin sent
	 * the respective messages - they all count to the same limit).
	 * Therefore if you have multiple messages to send, you should consider sending them asynchronously one at a time
	 * with a little delay in between (~1 second).
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param connection The ID of the server-connection to send the data through (the server the given users are on)
	 * @param users An array of user IDs to send the data to
	 * @param userCount The size of the provided user-array
	 * @param data The data array that shall be sent. This can be an arbitrary sequence of bytes. Note that the size of
	 * is restricted to <= 1KB.
	 * @param dataLength The length of the data array
	 * @param dataID The ID of the sent data. This has to be used by the receiving plugin(s) to figure out what to do
	 * with the data. This has to be a C-encoded String. It is recommended that the ID starts with a plugin-specific
	 * prefix in order to avoid name clashes. Note that the size of this string is restricted to <= 100 bytes.
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *sendData)(mumble_plugin_id_t callerID,
															   mumble_connection_t connection,
															   const mumble_userid_t *users, size_t userCount,
															   const uint8_t *data, size_t dataLength,
															   const char *dataID);

	/**
	 * Logs the given message (typically to Mumble's console). All passed strings have to be UTF-8 encoded.
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param message The message to log
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *log)(mumble_plugin_id_t callerID, const char *message);

	/**
	 * Plays the provided sample. It uses libsndfile as a backend so the respective file format needs to be supported
	 * by it in order for this to work out (see http://www.mega-nerd.com/libsndfile/).
	 *
	 * @param callerID The ID of the plugin calling this function
	 * @param samplePath The path to the sample that shall be played (UTF-8 encoded)
	 * @param volume The volume multiplier used when playing the sample (for no change use 1.0f)
	 * @returns The error code. If everything went well, STATUS_OK will be returned.
	 */
	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *playSample)(mumble_plugin_id_t callerID,
																 const char *samplePath PARAM_v1_2(float volume));
};

#	ifdef MUMBLE_PLUGIN_CREATE_MUMBLE_API_TYPEDEF
/**
 * Typedef for the Mumble API struct for convenient (unversioned) access
 */
typedef struct MUMBLE_API_STRUCT_NAME MumbleAPI;
typedef struct MUMBLE_API_STRUCT_NAME mumble_api_t;
#	endif

#	undef SELECTED_API_VERSION
#	undef PARAM_v1_2

#endif // EXTERNAL_MUMBLE_PLUGIN_MUMBLE_API_