Add API version verification. This breaks compatibility

with old versions of plugins.
Add RIFF MIDI support to the SMF reader.
Documentation.

2 files changed, 48 insertions, 19 deletions

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.
diff --git a/doc/version.html b/doc/version.html
index 93bd344..d3b3218 100644
--- a/doc/version.html
+++ b/doc/version.html
@@ -26,7 +26,7 @@
 	<h1>Version information</h1>
 	<div style="text-align:center;">
 		<img src="../img/qmidiplyr.png"><br>
-		QMidiPlayer documentation for version 0.8.2<br>
+		QMidiPlayer documentation for version 0.8.5<br>
 		An MIDI player based on fluidsynth and Qt.<br>
 		Written by Chris Xiong.<br>
 	</div><br>