1 // Copyright 2005-2019 The Mumble Developers. All rights reserved. 2 // Use of this source code is governed by a BSD-style license 3 // that can be found in the LICENSE file at the root of the 4 // Mumble source tree or at <https://www.mumble.info/LICENSE>. 5 6 #ifndef MUMBLE_MUMBLE_PLUGIN_H_ 7 #define MUMBLE_MUMBLE_PLUGIN_H_ 8 9 typedef unsigned long long procptr_t; 10 11 #define LENGTH_OF(array) (sizeof(array) / sizeof((array)[0])) 12 13 #include <string> 14 #include <map> 15 16 #if defined(_MSC_VER) 17 # define MUMBLE_PLUGIN_CALLING_CONVENTION __cdecl 18 #elif defined(__MINGW32__) 19 # define MUMBLE_PLUGIN_CALLING_CONVENTION __attribute__((cdecl)) 20 #else 21 # define MUMBLE_PLUGIN_CALLING_CONVENTION 22 #endif 23 24 #if defined(__GNUC__) && !defined(__MINGW32__) // GCC on Unix-like systems 25 # define MUMBLE_PLUGIN_EXPORT __attribute__((visibility("default"))) 26 #elif defined(_MSC_VER) 27 # define MUMBLE_PLUGIN_EXPORT __declspec(dllexport) 28 #elif defined(__MINGW32__) 29 # define MUMBLE_PLUGIN_EXPORT __attribute__((dllexport)) 30 #else 31 # error No MUMBLE_PLUGIN_EXPORT definition available 32 #endif 33 34 // Visual Studio 2008 x86 35 #if _MSC_VER == 1500 && defined(_M_IX86) 36 # define MUMBLE_PLUGIN_MAGIC 0xd63ab7ef 37 # define MUMBLE_PLUGIN_MAGIC_2 0xd63ab7fe 38 # define MUMBLE_PLUGIN_MAGIC_QT 0xd63ab7ee 39 // Visual Studio 2010 x86 40 #elif _MSC_VER == 1600 && defined(_M_IX86) 41 # define MUMBLE_PLUGIN_MAGIC 0xd63ab7f0 42 # define MUMBLE_PLUGIN_MAGIC_2 0xd63ab7ff 43 # define MUMBLE_PLUGIN_MAGIC_QT 0xd63ab70f 44 // Visual Studio 2013 x86 45 #elif _MSC_VER == 1800 && defined(_M_IX86) 46 # define MUMBLE_PLUGIN_MAGIC 0xd63ab7c0 47 # define MUMBLE_PLUGIN_MAGIC_2 0xd63ab7cf 48 # define MUMBLE_PLUGIN_MAGIC_QT 0xd63ab7ca 49 // Visual Studio 2013 x64 50 #elif _MSC_VER == 1800 && defined(_M_X64) 51 # define MUMBLE_PLUGIN_MAGIC 0x9f3ed4c0 52 # define MUMBLE_PLUGIN_MAGIC_2 0x9f3ed4cf 53 # define MUMBLE_PLUGIN_MAGIC_QT 0x9f3ed4ca 54 // Visual Studio 2015 x86 55 #elif _MSC_VER == 1900 && defined(_M_IX86) 56 # define MUMBLE_PLUGIN_MAGIC 0xa9b8c7c0 57 # define MUMBLE_PLUGIN_MAGIC_2 0xa9b8c7cf 58 # define MUMBLE_PLUGIN_MAGIC_QT 0xa9b8c7ca 59 // Visual Studio 2015 x64 60 #elif _MSC_VER == 1900 && defined(_M_X64) 61 # define MUMBLE_PLUGIN_MAGIC 0x1f2e3dc0 62 # define MUMBLE_PLUGIN_MAGIC_2 0x1f2e3dcf 63 # define MUMBLE_PLUGIN_MAGIC_QT 0x1f2e3dca 64 // Generic plugin magic values for platforms 65 // where we do not officially plugins other 66 // than "link". 67 #else 68 # define MUMBLE_PLUGIN_MAGIC 0xf4573570 69 # define MUMBLE_PLUGIN_MAGIC_2 0xf457357f 70 # define MUMBLE_PLUGIN_MAGIC_QT 0xf457357a 71 #endif 72 73 #define MUMBLE_PLUGIN_VERSION 2 74 75 typedef struct _MumblePlugin { 76 unsigned int magic; 77 const std::wstring &description; 78 const std::wstring &shortname; 79 void (MUMBLE_PLUGIN_CALLING_CONVENTION *about)(void *); 80 void (MUMBLE_PLUGIN_CALLING_CONVENTION *config)(void *); 81 int (MUMBLE_PLUGIN_CALLING_CONVENTION *trylock)(); 82 void (MUMBLE_PLUGIN_CALLING_CONVENTION *unlock)(); 83 const std::wstring(MUMBLE_PLUGIN_CALLING_CONVENTION *longdesc)(); 84 int (MUMBLE_PLUGIN_CALLING_CONVENTION *fetch)(float *avatar_pos, float *avatar_front, float *avatar_top, float *camera_pos, float *camera_front, float *camera_top, std::string &context, std::wstring &identity); 85 } MumblePlugin; 86 87 typedef struct _MumblePlugin2 { 88 unsigned int magic; 89 unsigned int version; 90 int (MUMBLE_PLUGIN_CALLING_CONVENTION *trylock)(const std::multimap<std::wstring, unsigned long long int> &); 91 } MumblePlugin2; 92 93 /// MumblePluginQt provides an extra set of functions that will 94 /// provide a plugin with a pointer to a QWidget that should be 95 /// used as the parent for any dialogs Qt widgets shown by the 96 /// plugin. 97 /// 98 /// This interface should only be used if a plugin intends to 99 /// present Qt-based dialogs to the user. 100 /// 101 /// This interface is most useful for plugins that are internal 102 /// to Mumble. This is because plugins can't integrate with Mumble's 103 /// QWidgets unless they're built into Mumble itself. 104 typedef struct _MumblePluginQt { 105 unsigned int magic; 106 107 /// about is called when Mumble requests the plugin 108 /// to show an about dialog. 109 /// 110 /// The ptr argument is a pointer to a QWidget that 111 /// should be used as the parent for a Qt-based 112 /// about dialog. 113 void (MUMBLE_PLUGIN_CALLING_CONVENTION *about)(void *ptr); 114 115 /// config is called when Mumble requests the plugin 116 /// to show its configuration dialog. 117 /// 118 /// The ptr argument is a pointer to a QWidget that 119 /// should be used as the parent for a Qt-based 120 /// configuration dialog. 121 void (MUMBLE_PLUGIN_CALLING_CONVENTION *config)(void *ptr); 122 } MumblePluginQt; 123 124 typedef MumblePlugin *(MUMBLE_PLUGIN_CALLING_CONVENTION *mumblePluginFunc)(); 125 typedef MumblePlugin2 *(MUMBLE_PLUGIN_CALLING_CONVENTION *mumblePlugin2Func)(); 126 typedef MumblePluginQt *(MUMBLE_PLUGIN_CALLING_CONVENTION *mumblePluginQtFunc)(); 127 128 /* 129 * All plugins must implement one function called getMumblePlugin(), which 130 * follows the mumblePluginFunc type and returns a MumblePlugin struct. 131 * 132 * magic should be initialized to MUMBLE_PLUGIN_MAGIC. description is the 133 * name of the plugin shown in the GUI, while shortname is used for TTS. 134 * 135 * The individual functions are: 136 * about(void *parent) - Player clicked the about button over plugin 137 * config(void *parent) - Player clicked the config button 138 * trylock() - Search system for likely process and try to lock on. 139 * The parameter is a set of process names and associated PIDs. 140 * Return 1 if succeeded, else 0. Note that once a plugin is locked on, 141 * no other plugins will be queried. 142 * unlock() - Unlock from process. Either from user intervention or 143 * because fetch failed. 144 * fetch(...) - Fetch data from locked process. avatar_pos is position in 145 * world coordinates (1 meter per unit). avatar_front and avatar_top 146 * specify the heading of the player, as in where he is looking. 147 * You need at minimum to figure out pos and front, otherwise 148 * sounds cannot be placed. If you do not fetch top, make it the 149 * same as front but rotated 90 degrees "upwards". 150 * 151 * camera_x is the same, but for the camera. Make this identical to the 152 * avatar position if you don't know (or if it's a 1st person 153 * perspective). 154 * 155 * It is important that you set all fields to 0.0 if you can't 156 * fetch meaningfull values, like between rounds and such. 157 * 158 * context and identity are transmitted to the server. Only players 159 * with identical context will hear positional audio from each other. 160 * Mumble will automatically prepend the shortname of the plugin to 161 * the context, so make this a representation of the game server and 162 * team the player is on. 163 * 164 * identity is retained by the server and is pollable over Ice/DBus, 165 * to be used by external scripts. This should uniquiely identify the 166 * player inside the game. 167 * 168 * ctx_len and id_len are initialized to the bufferspace available. Set these 169 * to -1 to keep the previous value (as parsing and optimizing can be CPU 170 * intensive) 171 * 172 * The function should return 1 if it is still "locked on", 173 * otherwise it should return 0. Mumble will call unlock() 174 * if it return 0, and go back to polling with trylock() 175 * once in a while. 176 */ 177 178 #endif 179