+
| +Important modifications introduced in version 1.1.1 are marked like this. + |
-So, for a quick demonstration of the plugin system, there is a demo plugin called +So, for a quick demonstration of the plugin system, there is a sample plugin called "hello" that comes with the VDR source. To test drive this one, do the following:
|
The src directory contains one subdirectory for each plugin, which carries -the name of that plugin (in the above example that would be demo and -hello, respectively). What's inside the individual source directory of a +the name of that plugin (in the above example that would be hello). +What's inside the individual source directory of a plugin is entirely up to the author of that plugin. The only prerequisites are that there is a Makefile that provides the targets all and clean, and that a call to make all actually produces a dynamically @@ -93,7 +94,7 @@ The lib directory contains the dynamically loadable libraries of all available plugins. Note that the names of these files are created by concatenating
| libvdr- | demo | .so. | 1.1.0 |
| libvdr- | hello | .so. | 1.1.0 |
| VDR plugin library prefix | name of the plugin | shared object indicator | VDR version number this plugin was compiled for |
@@ -109,25 +110,25 @@ each of these directories. If you download a plugin package from the web, it will typically have a name like
-vdr-demo-0.0.1.tgz +vdr-hello-0.0.1.tgz
and will unpack into a directory named
-vdr-demo-0.0.1 +vdr-hello-0.0.1
To use the plugins and plugins-clean targets from the VDR Makefile you need to unpack such an archive into the VDR/PLUGINS/src directory and create a symbolic link with the basic plugin name, as in
|
Since the VDR Makefile only searches for directories with names consisting
of only lowercase characters and digits, it will only follow the symbolic links, which
should lead to the current version of the plugin you want to use. This way you can
-have several different versions of a plugin source (like vdr-demo-0.0.1 and
-vdr-demo-0.0.2) and define which one to actually use through the symbolic link.
+have several different versions of a plugin source (like vdr-hello-0.0.1 and
+vdr-hello-0.0.2) and define which one to actually use through the symbolic link.
Initializing a new plugin directory
@@ -174,7 +175,7 @@ If your plugin shall not be accessible through VDR's main menu, simply remove
At the end of the plugin's source file you will find a line that looks like this:
|
This is the "magic" hook that allows VDR to actually load the plugin into @@ -230,9 +231,7 @@ Here's an example:
|
-which returns a short, one line description of the plugin's purpose. +which returns a short, one line description of the plugin's purpose:
|
+Note the tr() around the DESCRIPTION, which allows the description +to be internationalized. +
@@ -300,20 +304,21 @@ will survive the entire lifetime of the plugin, so it is safe to store pointers these values inside the plugin. Here's an example:
-The SetupMenu() function shall return the plugin's "Setup" menu +The SetupMenu() function shall return the plugin's Setup menu page, where the user can adjust all the parameters known to this plugin. SetupParse() will be called for each parameter the plugin has @@ -448,13 +456,30 @@ previously stored in the global setup data (see below). It shall return true if the parameter was parsed correctly, false in case of an error. If false is returned, an error message will be written to the log file (and program execution will continue). +
The plugin's setup parameters are stored in the same file as VDR's parameters. In order to allow each plugin (and VDR itself) to have its own set of parameters, the Name of each parameter will be preceeded with the plugin's name, as in -demo.SomeParameter = 123 +hello.GreetingTime = 3 The prefix will be handled by the core VDR setup code, so the individual plugins need not worry about this. @@ -465,8 +490,8 @@ To store its values in the global setup, a plugin has to call the function void SetupStore(const char *Name, type Value); |
-where Name is the name of the parameter ("SomeParameter" in the above -example, without the prefix "demo.") and Value is a simple data type (like +where Name is the name of the parameter ("GreetingTime" in the above +example, without the prefix "hello.") and Value is a simple data type (like char *, int etc). Note that this is not a function that the individual plugin class needs to implement! SetupStore() is a non-virtual member function of the cPlugin class. @@ -474,7 +499,7 @@ Note that this is not a function that the individual plugin class needs to imple To remove a parameter from the setup data, call SetupStore() with the appropriate name and without any value, as in
-SetupStore("SomeParameter"); +SetupStore("GreetingTime");
The VDR menu "Setup/Plugins" will list all loaded plugins with their name, version number and description. Selecting an item in this list will bring up @@ -486,6 +511,66 @@ needs setup parameters that are not directly user adjustable. It can use SetupStore() and SetupParse() without presenting these parameters to the user. +
+The Setup menu+ ++ +To implement a Setup menu, a plugin needs to derive a class from +cMenuSetupPage and implement its constructor and the pure virtual +Store() member function: + +
+ +In this example we have two global setup parameters (GreetingTime and UseAlternateGreeting). +The constructor initializes two private members with the values of these parameters, so +that the Setup menu can work with temporary copies (in order to discard any changes +if the user doesn't confirm them by pressing the "Ok" button). +After this the constructor adds the appropriate menu items, using internationalized texts +and the addresses of the temporary variables. That's all there is to inizialize a Setup +menu - the rest will be done by the core VDR code. + +Once the user has pressed the "Ok" button to confirm the changes, the Store() function will +be called, in which all setup parameters must be actually stored in VDR's global setup data. +This is done by calling the SetupStore() function for each of the parameters. +The Name string given here will be used to identify the parameter in VDR's +setup.conf file, and will be automatically prepended with the plugin's name. + +Note that in this small example the new values of the parameters are copied into the +global variables within each SetupStore() call. This is not mandatory, however. +You can first assign the temporary values to the global variables and then do the +SetupStore() calls, or you can define a class or struct that contains all +your setup parameters and use that one to copy all parameters with one single statement +(like VDR does with its cSetup class). + |
@@ -519,7 +604,7 @@ const tI18nPhrase Phrases[] = { { NULL } }; -void cPluginDemo::Start(void) +void cPluginHello::Start(void) { RegisterI18n(Phrases); } @@ -557,20 +642,20 @@ core VDR code. Plugins are loaded into VDR using the command line option -P, as in
|
If the plugin accepts command line options, they are given as part of the argument to the -P option, which then has to be enclosed in quotes:
|
Any number of plugins can be loaded this way, each with its own -P option:
|
If you are not starting VDR from the VDR source directory (and thus your plugins @@ -578,7 +663,7 @@ cannot be found at their default location) you need to tell VDR the location of the plugins through the -L option:
|
There can be any number of -L options, and each of them will apply to the @@ -603,17 +688,17 @@ provides the target package, which does this for you. Simply change into your source directory and execute make package:
|
After this you should find a file named like
|
-in your source directory, where demo will be replaced with your actual +in your source directory, where hello will be replaced with your actual plugin's name, and 0.0.1 will be your plugin's current version number.