Merge PR #6170: REFAC(plugins): Unified Mumble plugin headers

Having different include files that are needed (and which are inter-dependent) to create your own plugin, makes things harder than it needs to be.

Therefore, all plugin header files (those for the "new" (1.4) plugin framework anyway) have been combined into one header file. Thus, developers now only have to download a single file and include that instead of having to figure out what files to download and what to include where.

Taking the chance, the version number has been removed from the header file's name. This allows one to track changes made to the API via git (which is not quite as easy if you create a new file every time you make a change).

docs/dev/IncrementingTheMumbleAPI.md

@@ -1,34 +1,30 @@
 # Incrementing the Mumble API version
 
 ## Overview
-[Plugins](/docs/dev/plugins/) are used to extend the Mumble client with custom functionality. They are compiled against multiple [header files](/plugins/) which
-contain all function and structure signatures that can be used by the plugin. If you are commiting breaking API changes (such as additions or deletions) to these function signatures
-on the Mumble side, the API version will probably have to be increased. This is done to ensure plugins will have access to these functions when they
-are compiled against the new API version, while old plugins, using previous API versions, will still work.
-
-## Instructions
-If your commit includes breaking API changes, the following steps have to be followed:
-
-1) Create a new ``Mumble_API_v_<MA>_<MI>_x.h`` file in [plugins/](/plugins/).
-	* Replace ``<MA>`` with the API major version and ``<MI>`` with the API minor version.
-	* Usually, you will have to increase the ``<MI>`` version by 1 compared to the previous latest version. So if the previous API string was ``1.2.0``, you would probably want to increase the second number by one and create the file ``MumbleAPI_v_1_3_x.h``.
-	* The last "patch" digit of the version string is reserved for non-breaking API changes such as small fixes. Since non-breaking changes do not require a major or minor API increment, we do not worry about the "patch" digit in this document.
-1) Make sure you correctly set the ``MUMBLE_PLUGIN_API_MAJOR_MACRO``, ``MUMBLE_PLUGIN_API_MINOR_MACRO`` and [include guard](https://en.wikipedia.org/wiki/Include_guard) to the new API version. 
-	* You probably want to set the ``MUMBLE_PLUGIN_API_PATCH_MACRO`` to ``0``.
-1) Rename the ``struct`` within the file to match the new API version string.
-	* There is a ``typedef`` at the end of the file which has to use the new ``struct`` name, too.
-1) Make your desired changes to the function signatures contained in the header file.
-1) Open the [MumbleAPI_structs.h](/src/mumble/MumbleAPI_structs.h) file and add your new API header file as first include.
-	* Move the previous first include, the last most recent API version, into the ``NO_AUXILIARY_DEFINITIONS`` section.
-	* This will make sure auxiliary variables and macros always contain the most recent version on the mumble side.
-1) Add an ``else`` case to the [Plugin.cpp](/src/mumble/Plugin.cpp) file in the ``Plugin::init`` method.
-	* You will want to return the newly created ``struct``, if the API version requested by the plugin matches your new one.
-1) Create a new function signature in [API.h](/src/mumble/API.h). It should return your new ``struct`` and be of the name ``getMumbleAPI_v_<MA>_<MI>_x``.
-1) Amend the previous ``API_v_<MA>_x_x.cpp`` file, or create a new one in [this folder](/src/mumble/).
-	* For the foreseeable future, reuse the previous cpp file. Creating a new cpp file will probably only be useful on extensive API re-designs.
-	* If you have created a new ``API_v_<MA>_x_x.cpp``, you must add it to the [CMakeLists.txt](/src/mumble/CMakeLists.txt).
-1) Implement the ``getMumbleAPI_v_<MA>_<MI>_x`` function inside the ``API_v_<MA>_x_x.cpp`` file and return a struct with all functions you want to expose in your API version.
-1) When adding a new function or new function signature, copy an existing "C FUNCTION WRAPPER" inside the ``API_v_<MA>_x_x.cpp`` file. That wrapper should then call your new function.
-1) Implement your new API changes in the ``API_v_<MA>_x_x.cpp`` file.
-	* If you change the signature of an old function, it is probably best to call the new function in the old implementation with default values.
-	* This way, old plugins will still be working more or less as expected.
+[Plugins](/docs/dev/plugins/) are used to extend the Mumble client with custom functionality. They are compiled against the
+[MumblePlugin.h](/plugins/MumblePlugin.h) header, which contains all required definitions (and utilities) that a plugin needs to "do its thing".
+Among these definitions, are the functions that are part of the [Mumble API](/docs/dev/plugins/MumbleAPI.md) (search for `Mumble API`). If you modify
+these definitions, you'll have to update the API's version number.
+
+Which version to increment, depends on what kind of change you have made:
+- The change is only a minor correction (e.g. fixing a typo in a parameter name or fixing a bug in Mumble's implementation of an API function).
+  Increase the value of `MUMBLE_PLUGIN_API_PATCH_MACRO` by one.
+- The change breaks existing plugins (e.g. adding a new parameter to an existing function or adding a new function altogether). Increase the value of
+  `MUMBLE_PLUGIN_API_MINOR_MACRO` by one and adapt the API code in Mumble (see below).
+- The change is not compatible with the existing framework at all. You should never, ever do this without thorough discussions with the project
+  maintainers. As for the versioning: a custom procedure will have to be agreed on.
+
+
+## Adapting the Mumble logic
+
+If the API's minor or major version number have been increased, you will have to adapt Mumble's code to make sure that it will be able to serve
+individual plugins different versions of the API. For that, you will have to adapt the code inside the `init()` function of the `Plugin` class. More
+specifically, you will have to add another branch to the if-statement that selects the requested API struct.
+
+The required `API::getMumbleAPI_v_*` functions are implemented inside the `API.h` and `API.cpp` files. Simply follow the already present examples and
+create a specific implementation for the new version. Pointers to functions that have not changed can be used as before.
+
+If you have added a new parameter to an existing function, calling the old function (which should still be available in most cases) should internally
+call the new implementation, with that parameter set to a sensible default. This way, all API function calls will end up using the same implementation
+on Mumble's side (which reduces maintenance work).
+

docs/dev/plugins/CreatePlugin.md

@@ -15,11 +15,7 @@ also intended to be used as the basis for everyone that wants to start writing a
 
 What you need for creating a plugin is
 - A working C compiler. It does not matter which one
-- The Mumble plugin framework header files which are the following (the exact version number in the filename may change depending on which API version
-  you intend to use):
-    * [MumbleAPI_v_1_0_x.h](https://github.com/mumble-voip/mumble/blob/master/plugins/MumbleAPI_v_1_0_x.h)
-	* [MumblePlugin_v_1_0_x.h](https://github.com/mumble-voip/mumble/blob/master/plugins/MumblePlugin_v_1_0_x.h)
-	* [PluginComponents_v_1_0_x.h](https://github.com/mumble-voip/mumble/blob/master/plugins/PluginComponents_v_1_0_x.h)
+- The Mumble plugin header file: [MumblePlugin.h](https://github.com/mumble-voip/mumble/blob/master/plugins/MumblePlugin.h)
 
 Although not strictly required, it usually is handy to use a build system for managing your plugin project. In this guide we'll use
 [cmake](https://cmake.org/). If you have never used cmake before, have a look at [this short guide](https://stackoverflow.com/a/26007567).
@@ -28,9 +24,7 @@ All in all the following file structure is assumed to be present on your device:
 ```
 .
 ├── include
-│   ├── MumbleAPI_v_1_0_x.h
-│   ├── MumblePlugin_v_1_0_x.h
-│   └── PluginComponents_v_1_0_x.h
+│   └── MumblePlugin.h
 ├── CMakeLists.txt
 └── plugin.c
 ```
@@ -70,9 +64,9 @@ to build a shared library from the source file `plugin.c` and that everything in
 
 Now that the boilerplate is out of the way, we can start writing the actual plugin. This will be done in the `plugin.c` source file.
 
-The first thing you should do is to include `MumblePlugin_v_1_0_x.h`. Furthermore we'll need a few more C headers that we'll include as well:
+The first thing you should do is to include `MumblePlugin.h`. Furthermore we'll need a few more C headers that we'll include as well:
 ```c
-#include "MumblePlugin_v_1_0_x.h"
+#include "MumblePlugin.h"
 
 #include <stdio.h>
 #include <stdlib.h>
@@ -82,7 +76,7 @@ The first thing you should do is to include `MumblePlugin_v_1_0_x.h`. Furthermor
 Furthermore every plugin needs a way to store at least the Mumble-API and its own ID. In C this can be done using global variables. Therefore go ahead
 and create the respective variables in the global namespace:
 ```c
-struct MumbleAPI_v_1_0_x mumbleAPI;
+MumbleAPI mumbleAPI;
 mumble_plugin_id_t ownID;
 ```
 

docs/dev/plugins/MumbleAPI.md

@@ -98,6 +98,6 @@ That is to say: You must not wait for a job to finish asynchronously that might
 
 ## Header files
 
-The following header files describe the Mumble-API struct that contains the function pointers as well as descriptions of the respective functions:
-- [Mumble-API v1.0.x](https://github.com/mumble-voip/mumble/blob/master/plugins/MumbleAPI_v_1_0_x.h)
+The Mumble API definition is contained in the [MumblePlugin.h](https://github.com/mumble-voip/mumble/blob/master/plugins/MumblePlugin.h) header. It
+contains a list of all available functions as well as documentation for every function.
 

docs/dev/plugins/PluginAPI.md

@@ -38,6 +38,6 @@ Unless otherwise noted in the function's description, all functions are called f
 
 ## Header files
 
-The following header files describe the plugin-API interface. They also contain a description of what each function is for.
-- [Plugin-API v1.0.x](https://github.com/mumble-voip/mumble/blob/master/plugins/MumblePlugin_v_1_0_x.h)
+The plugin function definitions are contained in the [MumblePlugin.h](https://github.com/mumble-voip/mumble/blob/master/plugins/MumblePlugin.h) header. It
+contains a list of all available functions as well as documentation for every function.