From d07e3829f7c44d713b2677ef73f864af80b3dea3 Mon Sep 17 00:00:00 2001 From: Klaus Schmidinger Date: Mon, 13 May 2002 18:00:00 +0200 Subject: Version 1.1.2 - Changed the cPlugin::Start() function to return a boolean value that indicates if the plugin will not be able to perform its task (suggested by Stefan Huelswitt). - Added the cPlugin::Housekeeping() function (suggested by Stefan Huelswitt). - Updated channels.conf.cable (thanks to Uwe Scheffler). - Added 'insert' capabilities to cList (suggested by Stefan Huelswitt). - Changed the 'package' target in the plugin's Makefile to produce a package that expands to a directory with just the plugin name and version number (suggested by Stefan Huelswitt). - Made the config directory available to plugins (suggested by Stefan Huelswitt). See PLUGINS.html, section "Configuration files" for details. - Improved the [eid]syslog() macros, so that the LOG_... macros don't need to be given any more. --- PLUGINS.html | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 110 insertions(+), 10 deletions(-) (limited to 'PLUGINS.html') diff --git a/PLUGINS.html b/PLUGINS.html index 70d6f46..4cc27da 100644 --- a/PLUGINS.html +++ b/PLUGINS.html @@ -16,9 +16,12 @@ This document describes the "outside" interface of the plugin system. It handles everything necessary for a plugin to get hooked into the core VDR program and present itself to the user.

-
  +
  Important modifications introduced in version 1.1.1 are marked like this.
+
  +Important modifications introduced in version 1.1.2 are marked like this. +

Quick start

@@ -114,21 +117,25 @@ from the web, it will typically have a name like

and will unpack into a directory named

-vdr-hello-0.0.1 +
  +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 +
  



-ln -s vdr-hello-0.0.1 hello
+ln -s hello-0.0.1 hello

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-hello-0.0.1 and -vdr-hello-0.0.2) and define which one to actually use through the symbolic link. +have several different versions of a plugin source (like hello-0.0.1 and +hello-0.0.2) and define which one to actually use through the symbolic link. +

Initializing a new plugin directory

@@ -184,7 +191,7 @@ its memory. You don't need to worry about the details behind all this. If your plugin requires additional source files, simply add them to your plugin's source directory and adjust the Makefile accordingly.

-
  +
  Header files usually contain preprocessor statements that prevent the same file (or rather its contents, to be precise) from being included more than once, like @@ -403,9 +410,11 @@ If a plugin implements a function that runs in the background (presumably in a thread of its own), or wants to make use of internationalization, it needs to implement the function +
  



-virtual void Start(void);
+virtual bool Start(void);

+

which is called once for each plugin at program startup. Inside this function the plugin must set up everything necessary to perform @@ -413,6 +422,13 @@ its task. This may, for instance, be a thread that collects data from the DVB stream, which is later presented to the user via a function that is available from the main menu.

+
  +A return value of false indicates that something has gone wrong and the +plugin will not be able to perform its task. In that case, the plugin should +write a proper error message to the log file. The first plugin that returns +false from its Start() function will cause VDR to exit. +
+

If the plugin doesn't implement any background functionality or internationalized texts, it doesn't need to implement this function. @@ -470,7 +486,34 @@ interaction is possible. If a specific action takes longer than a few seconds, the plugin should launch a separate thread to do this. -

Setup parameters

+
  +

Housekeeping

+ +
Chores, chores...

+ +From time to time a plugin may want to do some regular tasks, like cleaning +up some files or other things. In order to do this it can implement the function + +



+virtual void Housekeeping(void);
+

+ +which gets called when VDR is otherwise idle. The intervals between subsequent +calls to this function are not defined. There may be several hours between two +calls (if, for instance, there are recordings or replays going on) or they may +be as close as ten seconds. The only thing that is guaranteed is that there are +at least ten seconds between two subsequent calls to the Housekeeping() +function of the same plugin. +

+ +It is very important that a call to Housekeeping() returns as soon +as possible! As long as the program stays inside this function, no other user +interaction is possible. If a specific action takes longer than a few seconds, +the plugin should launch a separate thread to do this. + +

+ +

Setup parameters

Remember me...

@@ -490,7 +533,7 @@ 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). -
  +
  A possible implementation of SetupParse() could look like this: 



@@ -545,7 +588,7 @@ 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

 
 
Have it your way!

@@ -605,6 +648,63 @@ your setup parameters and use that one to copy all parameters with one single st
 (like VDR does with its cSetup class).
 

 
+
 
+
Configuration files

+
+
I want my own stuff!

+
+There may be situations where a plugin requires configuration files of its own, maybe
+for data that can't be stored in the simple setup parameters
+of VDR, or maybe because it needs to launch other programs that simply need a separate
+configuration file. While the plugin is free to store such files anywhere it
+sees fit, it might be a good idea to put them in a common place, preferably
+where other configuration data already exists. VDR provides the function
+
+


+const char *ConfigDirectory(const char *PluginName = NULL);
+

+
+which returns a string containing the directory that VDR uses for its own configuration
+files (defined through the -c option in the call to VDR), extended by
+"/plugins". So assuming the VDR configuration directory is /video
+(the default if no -c or -v option is given),
+a call to ConfigDirectory() will return /video/plugins. The first
+call to ConfigDirectory() will automatically make sure that the plugins
+subdirectory will exist. If, for some reason, this cannot be achieved, NULL
+will be returned.
+

+The additional plugins directory is used to keep files from plugins apart
+from those of VDR itself, making sure there will be no name clashes. If a plugin
+needs only one extra configuration file, it is suggested that this file be named
+name.conf, where name shall be the name of the plugin.
+

+If a plugin needs more than one such file, it is suggested that the plugin stores
+these in a subdirectory of its own, named after the plugin. To easily get such a name
+the ConfigDirectory() function can be given an additional string that will
+be appended to the returned directory name, as in
+
+


+const char *MyConfigDir = ConfigDirectory(Name());
+

+
+where Name() is the member function of the plugin class that returns the
+plugin's name. Again, VDR will make sure that the requested directory will exist
+(or return NULL in case of an error).
+

+
+The returned string is statically allocated and will be overwritten by subsequent
+calls to ConfigDirectory()!
+
+

+The ConfigDirectory() function is a static member function of the cPlugin
+class. This allows it to be called even from outside any member function of the derived
+plugin class, by writing
+
+


+const char *MyConfigDir = cPlugin::ConfigDirectory();
+

+

+
 
Internationalization

 
 
Welcome to Babylon!

-- 
cgit v1.2.3