FEAT(plugin-api): Add function to mumble api to obtain current positional audio data provided by another plugin

plugins/MumblePlugin.h

@@ -43,7 +43,7 @@
 #		define MUMBLE_PLUGIN_API_MAJOR_MACRO 1
 #	endif
 #	ifndef MUMBLE_PLUGIN_API_MINOR_MACRO
-#		define MUMBLE_PLUGIN_API_MINOR_MACRO 2
+#		define MUMBLE_PLUGIN_API_MINOR_MACRO 3
 #	endif
 #	ifndef MUMBLE_PLUGIN_API_PATCH_MACRO
 #		define MUMBLE_PLUGIN_API_PATCH_MACRO 0
@@ -444,6 +444,15 @@ struct MumbleStringWrapper {
 	bool needsReleasing;
 };
 
+struct PositionalDataNoQt {
+	float m_playerPos[3];
+	float m_playerDir[3];
+	float m_playerAxis[3];
+	float m_cameraPos[3];
+	float m_cameraDir[3];
+	float m_cameraAxis[3];
+};
+
 MUMBLE_EXTERN_C_END
 
 #endif // EXTERNAL_MUMBLE_PLUGIN_TYPES_
@@ -1515,6 +1524,49 @@ struct MUMBLE_API_STRUCT_NAME {
 																			mumble_channelid_t channelID,
 																			const char **description);
 
+#if SELECTED_API_VERSION >= MUMBLE_PLUGIN_VERSION_CHECK(1, 3, 0)
+	/**
+     * Gets the currently used positional data
+     *
+     * @param callerID The ID of the plugin calling this function
+     * @param[out] outPositionalData A pointer to the PositionalData object that should be written to
+     * @returns The error code. If everything went well, STATUS_OK will be returned.
+     *
+     * @since Plugin interface v1.3.0
+	 */
+	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getPositionalData)(mumble_plugin_id_t callerID,
+																		PositionalDataNoQt *outPositionalData);
+
+	/**
+	 * Gets the currently used positional data context
+	 *
+     * @param callerID The ID of the plugin calling this function
+	 * @param[out] outContext A pointer to the char * that should be written to,
+	 *   please note that the context has 2 null terminators,
+	 *   the first of which will contain the name of the plugin providing the data
+	 *   whereas the second null terminator contains the actual context data returned by the plugin
+	 * @returns The error code. If everything went well, STATUS_OK will be returned.
+	 *
+	 * @since Plugin interface v1.3.0
+	 */
+	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getPositionalContext)(mumble_plugin_id_t callerID,
+	                                                                            char **outContext);
+
+	/**
+	 * Gets the currently used positional data identity
+	 *
+	 * @param callerID The ID of the plugin calling this function
+	 * @param[out] outIdentity A pointer to the char * that should be written to
+	 * @returns The error code. If everything went well, STATUS_OK will be returned.
+	 *
+	 * @since Plugin interface v1.3.0
+	 */
+	mumble_error_t(MUMBLE_PLUGIN_CALLING_CONVENTION *getPositionalIdentity)(mumble_plugin_id_t callerID,
+																				char **outIdentity);
+
+#endif
+
+
 
 	// -------- Request functions --------
 

src/mumble/API.h

@@ -119,6 +119,12 @@ public slots:
 	void getChannelDescription_v_1_0_x(mumble_plugin_id_t callerID, mumble_connection_t connection,
 									   mumble_channelid_t channelID, const char **description,
 									   std::shared_ptr< api_promise_t > promise);
+	void getPositionalData_v_1_3_x(mumble_plugin_id_t callerID, PositionalDataNoQt *outPositionalData,
+										std::shared_ptr< api_promise_t > promise);
+	void getPositionalContext_v_1_3_x(mumble_plugin_id_t callerID, char **outContext,
+									std::shared_ptr< api_promise_t > promise);
+	void getPositionalIdentity_v_1_3_x(mumble_plugin_id_t callerID, char **outIdentity,
+									std::shared_ptr< api_promise_t > promise);
 	void requestUserMove_v_1_0_x(mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t userID,
 								 mumble_channelid_t channelID, const char *password,
 								 std::shared_ptr< api_promise_t > promise);
@@ -174,6 +180,9 @@ MumbleAPI_v_1_0_x getMumbleAPI_v_1_0_x();
 /// @returns The Mumble API struct (v1.2.x)
 MumbleAPI_v_1_2_x getMumbleAPI_v_1_2_x();
 
+/// @returns The Mumble API struct (v1.3.x)
+MumbleAPI_v_1_3_x getMumbleAPI_v_1_3_x();
+
 /// Converts from the Qt key-encoding to the API's key encoding.
 ///
 /// @param keyCode The Qt key-code that shall be converted

src/mumble/API_v_1_x_x.cpp

@@ -894,6 +894,110 @@ void MumbleAPI::getChannelDescription_v_1_0_x(mumble_plugin_id_t callerID, mumbl
 	EXIT_WITH(MUMBLE_STATUS_OK);
 }
 
+void MumbleAPI::getPositionalData_v_1_3_x(mumble_plugin_id_t callerID,
+											   PositionalDataNoQt *outPositionalData,
+											   std::shared_ptr< api_promise_t > promise) {
+	if (QThread::currentThread() != thread()) {
+		// Invoke in main thread
+		QMetaObject::invokeMethod(this, "getPositionalData_v_1_3_x", Qt::QueuedConnection,
+								  Q_ARG(mumble_plugin_id_t, callerID), Q_ARG(PositionalDataNoQt *, outPositionalData),
+								  Q_ARG(std::shared_ptr< api_promise_t >, promise));
+		return;
+	}
+
+	api_promise_t::lock_guard_t guard = promise->lock();
+	if (promise->isCancelled()) {
+		return;
+	}
+
+	VERIFY_PLUGIN_ID(callerID);
+
+	PluginManager *pluginManager = Global::get().pluginManager;
+	if (!pluginManager) {
+		EXIT_WITH(MUMBLE_EC_INTERNAL_ERROR);
+	}
+
+	const PositionalData &posData = pluginManager->getPositionalData();
+
+	for (int i = 0; i < 3; i++) {
+		Coord coord = static_cast< Coord >(i);
+
+		outPositionalData->m_playerPos[i]  = posData.getPlayerPos()[coord];
+		outPositionalData->m_playerDir[i]  = posData.getPlayerDir()[coord];
+		outPositionalData->m_playerAxis[i] = posData.getPlayerAxis()[coord];
+
+		outPositionalData->m_cameraPos[i]  = posData.getCameraPos()[coord];
+		outPositionalData->m_cameraDir[i]  = posData.getCameraDir()[coord];
+		outPositionalData->m_cameraAxis[i] = posData.getCameraAxis()[coord];
+	}
+
+	EXIT_WITH(MUMBLE_STATUS_OK);
+}
+
+void MumbleAPI::getPositionalContext_v_1_3_x(mumble_plugin_id_t callerID, char **outContext,
+									std::shared_ptr< api_promise_t > promise) {
+	if (QThread::currentThread() != thread()) {
+		// Invoke in main thread
+		QMetaObject::invokeMethod(this, "getPositionalContext_v_1_3_x", Qt::QueuedConnection,
+								  Q_ARG(mumble_plugin_id_t, callerID), Q_ARG(char **, outContext),
+								  Q_ARG(std::shared_ptr< api_promise_t >, promise));
+		return;
+	}
+
+	api_promise_t::lock_guard_t guard = promise->lock();
+	if (promise->isCancelled()) {
+		return;
+	}
+
+	VERIFY_PLUGIN_ID(callerID);
+
+	PluginManager *pluginManager = Global::get().pluginManager;
+	if (!pluginManager) {
+		EXIT_WITH(MUMBLE_EC_INTERNAL_ERROR);
+	}
+
+	const PositionalData &posData = pluginManager->getPositionalData();
+	const QString contextQString = posData.getContext();
+
+	char *context = contextQString.toUtf8().data();
+
+	std::memcpy(*outContext, context, static_cast<size_t>(contextQString.size()));
+
+	EXIT_WITH(MUMBLE_STATUS_OK);
+}
+
+void MumbleAPI::getPositionalIdentity_v_1_3_x(mumble_plugin_id_t callerID, char **outIdentity,
+										std::shared_ptr< api_promise_t > promise) {
+	if (QThread::currentThread() != thread()) {
+		// Invoke in main thread
+		QMetaObject::invokeMethod(this, "getPositionalIdentity_v_1_3_x", Qt::QueuedConnection,
+								  Q_ARG(mumble_plugin_id_t, callerID), Q_ARG(char **, outIdentity),
+								  Q_ARG(std::shared_ptr< api_promise_t >, promise));
+		return;
+	}
+
+	api_promise_t::lock_guard_t guard = promise->lock();
+	if (promise->isCancelled()) {
+		return;
+	}
+
+	VERIFY_PLUGIN_ID(callerID);
+
+	PluginManager *pluginManager = Global::get().pluginManager;
+	if (!pluginManager) {
+		EXIT_WITH(MUMBLE_EC_INTERNAL_ERROR);
+	}
+
+	const PositionalData &posData = pluginManager->getPositionalData();
+
+	char *identity = posData.getPlayerIdentity().toUtf8().data();
+	size_t size = strlen(identity) + 1;
+
+	std::memcpy(*outIdentity, identity, size);
+
+	EXIT_WITH(MUMBLE_STATUS_OK);
+}
+
 void MumbleAPI::requestUserMove_v_1_0_x(mumble_plugin_id_t callerID, mumble_connection_t connection,
 										mumble_userid_t userID, mumble_channelid_t channelID, const char *password,
 										std::shared_ptr< api_promise_t > promise) {
@@ -1800,6 +1904,27 @@ C_WRAPPER(getChannelDescription_v_1_0_x)
 #undef TYPED_ARGS
 #undef ARG_NAMES
 
+#define TYPED_ARGS \
+	mumble_plugin_id_t callerID, PositionalDataNoQt *outPositionalData
+#define ARG_NAMES callerID, outPositionalData
+C_WRAPPER(getPositionalData_v_1_3_x)
+#undef TYPED_ARGS
+#undef ARG_NAMES
+
+#define TYPED_ARGS \
+mumble_plugin_id_t callerID, char **outContext
+#define ARG_NAMES callerID, outContext
+C_WRAPPER(getPositionalContext_v_1_3_x)
+#undef TYPED_ARGS
+#undef ARG_NAMES
+
+#define TYPED_ARGS \
+mumble_plugin_id_t callerID, char **outIdentity
+#define ARG_NAMES callerID, outIdentity
+C_WRAPPER(getPositionalIdentity_v_1_3_x)
+#undef TYPED_ARGS
+#undef ARG_NAMES
+
 #define TYPED_ARGS                                                                                                     \
 	mumble_plugin_id_t callerID, mumble_connection_t connection, mumble_userid_t userID, mumble_channelid_t channelID, \
 		const char *password
@@ -2016,6 +2141,50 @@ MumbleAPI_v_1_2_x getMumbleAPI_v_1_2_x() {
 			 playSample_v_1_2_x };
 }
 
+MumbleAPI_v_1_3_x getMumbleAPI_v_1_3_x() {
+	return { freeMemory_v_1_0_x,
+			 getActiveServerConnection_v_1_0_x,
+			 isConnectionSynchronized_v_1_0_x,
+			 getLocalUserID_v_1_0_x,
+			 getUserName_v_1_0_x,
+			 getChannelName_v_1_0_x,
+			 getAllUsers_v_1_0_x,
+			 getAllChannels_v_1_0_x,
+			 getChannelOfUser_v_1_0_x,
+			 getUsersInChannel_v_1_0_x,
+			 getLocalUserTransmissionMode_v_1_0_x,
+			 isUserLocallyMuted_v_1_0_x,
+			 isLocalUserMuted_v_1_0_x,
+			 isLocalUserDeafened_v_1_0_x,
+			 getUserHash_v_1_0_x,
+			 getServerHash_v_1_0_x,
+			 getUserComment_v_1_0_x,
+			 getChannelDescription_v_1_0_x,
+			 getPositionalData_v_1_3_x,
+			 getPositionalContext_v_1_3_x,
+			 getPositionalIdentity_v_1_3_x,
+			 requestLocalUserTransmissionMode_v_1_0_x,
+			 requestUserMove_v_1_0_x,
+			 requestMicrophoneActivationOverwrite_v_1_0_x,
+			 requestLocalMute_v_1_0_x,
+			 requestLocalUserMute_v_1_0_x,
+			 requestLocalUserDeaf_v_1_0_x,
+			 requestSetLocalUserComment_v_1_0_x,
+			 findUserByName_v_1_0_x,
+			 findChannelByName_v_1_0_x,
+			 getMumbleSetting_bool_v_1_0_x,
+			 getMumbleSetting_int_v_1_0_x,
+			 getMumbleSetting_double_v_1_0_x,
+			 getMumbleSetting_string_v_1_0_x,
+			 setMumbleSetting_bool_v_1_0_x,
+			 setMumbleSetting_int_v_1_0_x,
+			 setMumbleSetting_double_v_1_0_x,
+			 setMumbleSetting_string_v_1_0_x,
+			 sendData_v_1_0_x,
+			 log_v_1_0_x,
+			 playSample_v_1_2_x };
+}
+
 #define MAP(qtName, apiName) \
 	case Qt::Key_##qtName:   \
 		return MUMBLE_KC_##apiName

src/mumble/MumbleAPI_structs.h

@@ -15,6 +15,16 @@
 // First, include the latest plugin API header file completely
 #include "MumblePlugin.h"
 
+// Now, include all older API structs for backward compatibility
+// Re-include the API definition
+#undef EXTERNAL_MUMBLE_PLUGIN_MUMBLE_API_
+// But this time, overwrite the version
+#undef MUMBLE_PLUGIN_API_MAJOR_MACRO
+#define MUMBLE_PLUGIN_API_MAJOR_MACRO 1
+#undef MUMBLE_PLUGIN_API_MINOR_MACRO
+#define MUMBLE_PLUGIN_API_MINOR_MACRO 2
+
+#include "MumblePlugin.h"
 
 // Re-include the API definition
 #undef EXTERNAL_MUMBLE_PLUGIN_MUMBLE_API_

src/mumble/Plugin.cpp

@@ -329,6 +329,9 @@ mumble_error_t Plugin::init() {
 	} else if (apiVersion >= mumble_version_t({ 1, 2, 0 }) && apiVersion < mumble_version_t({ 1, 3, 0 })) {
 		MumbleAPI_v_1_2_x api = API::getMumbleAPI_v_1_2_x();
 		registerAPIFunctions(&api);
+	} else if (apiVersion >= mumble_version_t({ 1, 3, 0 })) {
+		MumbleAPI_v_1_3_x api = API::getMumbleAPI_v_1_3_x();
+		registerAPIFunctions(&api);
 	} else {
 		// The API version could not be obtained -> this is an invalid plugin that shouldn't have been loaded in the
 		// first place