From 1976c49f835267d33ef88bd3fc20d18363e12c0b Mon Sep 17 00:00:00 2001 From: Chris Xiong Date: Wed, 8 Feb 2017 23:45:18 +0800 Subject: Add API version verification. This breaks compatibility with old versions of plugins. Add RIFF MIDI support to the SMF reader. Documentation. --- doc/APIdoc.md | 65 ++++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 47 insertions(+), 18 deletions(-) (limited to 'doc/APIdoc.md') diff --git a/doc/APIdoc.md b/doc/APIdoc.md index 043c1c0..5b69b5e 100644 --- a/doc/APIdoc.md +++ b/doc/APIdoc.md @@ -5,43 +5,72 @@ # 0. Overview -Plugin for QMidiPlayer is a dynamically-loaded library that exports the symbol "qmpPluginGetInterface". +Plugin for QMidiPlayer is a dynamically-loaded library that exports the symbol `qmpPluginGetInterface` and `qmpPluginGetAPIRev`. Before starting developing your own plugin, make sure to have a look at the sample plugin in the "sample-plugin" folder. # 1. "QMidiPlayer Plugin SDK" -SDK for developing QMidiPlayer plugins is merely the "qmpcorepublic.hpp" header found in the "include" directory in +SDK for developing QMidiPlayer plugins is merely the `qmpcorepublic.hpp` header found in the "include" directory in the source tree. It includes classes used by QMidiPlayer's internal plugin infrastructure. -# 2. Basics for a working plugin. +# 2. Basics for a working plugin First of all, you should make your library distinct from other libraries that are not QMidiPlayer plugins. You can achive -it by exporting the symbol "qmpPluginGetInterface". Specifically, what you should do is to add the following snipplet to -somewhere of your code: +it by exporting the symbols `qmpPluginGetInterface` and `qmpPluginGetAPIRev`. Specifically, what you should do is to add +the following snipplet to somewhere of your code: -> extern "C"{ -> EXPORTSYM qmpPluginIntf* qmpPluginGetInterface(qmpPluginAPI* api) -> //semicolon or implementation here. -> } +``` +extern "C"{ + EXPORTSYM qmpPluginIntf* qmpPluginGetInterface(qmpPluginAPI* api) + //semicolon or implementation here. + EXPORTSYM const char* qmpPluginGetAPIRev() + {return QMP_PLUGIN_API_REV;} +} +``` -The EXPORTSYM macro tells the compiler to export the following symbol. qmpPluginIntf is the abstract class which every +The `EXPORTSYM` macro tells the compiler to export the following symbol. `qmpPluginIntf` is the abstract class which every plugin class should derive from. The parameter api provides access to QMidiPlayer's plugin API, which should be stored -for future use. +for future use. `qmpPluginGetAPIRev` helps the core to determine whether the plugin is compatible with the API it exports. -Next you should create your own plugin class which implements the abstract class "qmpPluginIntf". +Next you should create your own plugin class which implements the abstract class `qmpPluginIntf`. -# 3. A Peek into the class "qmpPluginIntf" +# 3. A peek into the class `qmpPluginIntf` It has 6 public members: one default constructor, one default destructor and four methods: -- void init() +- `void init()` Called on start up if the plugin is loaded successfully and enabled. -- void deinit() +- `void deinit()` Called on shutdown if the plugin is enabled. -- const char* pluginGetName() +- `const char* pluginGetName()` This function should return the display name of the plugin. -- const char* pluginGetVersion() +- `const char* pluginGetVersion()` This function should return the version of the plugin, which will be shown in the plugin manager. -Your plugin is expected to register handlers and functionalities when init() is called by the host, +Your plugin is expected to register handlers (hooks) and functionalities when init() is called by the host, and do clean-up jobs when deinit() is caled. + +Currently plugins can register handlers for these functionalities: + +- Visualization (via `(un)registerVisualizationIntf`) +- MIDI File Reader (via `(un)registerFileReader`) + +...and can hooks into the following processes: + +- Event reader, after an event is read or after the whole file reading process is completed + (via `(un)registerEventReaderIntf` and `(un)registerFileReadFinishedHandlerIntf`) +- Event handler, when an event is going to be sent by the player (via `(un)registerEventHandlerIntf`) + +Functionalities has their own interfaces you need to implement(`qmpVisualizationIntf` and `IMidiFileReader`, respectively), +while hooks uses the universal `IMidiCallBack` interface. Functionalities are discussed later. + +When you register a hook, you provide the core with a instance of your class that implements the `IMidiCallBack` interface +and your `userdata` to be used when the core is calling the callback. When the callback is called, it will be fed with +proper `callerdata` generated by the core and the `userdata` you provided. Type of `callerdata` varies by hooks. Event +reader and handler hooks have `SEventCallBackData*` as their `callerdata` while file read finish hook doesn't provide +`callerdata` (`NULL`). + +# 4. Functionalities +Plugins extend the hosts with extra functionalities. With hooks, handlers and the built-in core API, you can already do a +lot of hacking. If that cannot make you satisfied, QMidiPlayer have several vacancies that are expected to be implemented +by plugins. -- cgit v1.2.3