Version 1.1.2vdr-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.

1 files changed, 110 insertions, 10 deletions

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.
 <p>
-<!--X1.1.1--><table width=100%><tr><td bgcolor=red>&nbsp;</td><td width=100%>
+<!--X1.1.1--><table width=100%><tr><td bgcolor=cyan>&nbsp;</td><td width=100%>
 Important modifications introduced in version 1.1.1 are marked like this.
 <!--X1.1.1--></td></tr></table>
+<!--X1.1.2--><table width=100%><tr><td bgcolor=red>&nbsp;</td><td width=100%>
+Important modifications introduced in version 1.1.2 are marked like this.
+<!--X1.1.2--></td></tr></table>
 <!--<p>TODO: Link to the document about VDR base classes to use when implementing actual functionality (yet to be written).-->
 
 <hr><h2>Quick start</h2>
@@ -114,21 +117,25 @@ from the web, it will typically have a name like
 <p>
 and will unpack into a directory named
 <p>
-<tt>vdr-hello-0.0.1</tt>
+<!--X1.1.2--><table width=100%><tr><td bgcolor=red>&nbsp;</td><td width=100%>
+<tt>hello-0.0.1</tt>
+<!--X1.1.2--></td></tr></table>
 <p>
 To use the <tt>plugins</tt> and <tt>plugins-clean</tt> targets from the VDR <tt>Makefile</tt>
 you need to unpack such an archive into the <tt>VDR/PLUGINS/SRC</tt> directory and
 create a symbolic link with the basic plugin name, as in
 
+<!--X1.1.2--><table width=100%><tr><td bgcolor=red>&nbsp;</td><td width=100%>
 <p><table><tr><td bgcolor=#F0F0F0><pre><br>
-ln -s vdr-hello-0.0.1 hello
+ln -s hello-0.0.1 hello
 </pre></td></tr></table><p>
 
 Since the VDR <tt>Makefile</tt> 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 <tt>vdr-hello-0.0.1</tt> and
-<tt>vdr-hello-0.0.2</tt>) and define which one to actually use through the symbolic link.
+have several different versions of a plugin source (like <tt>hello-0.0.1</tt> and
+<tt>hello-0.0.2</tt>) and define which one to actually use through the symbolic link.
+<!--X1.1.2--></td></tr></table>
 
 <a name="Initializing a new plugin directory"><hr><h2>Initializing a new plugin directory</h2>
 
@@ -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 <tt>Makefile</tt> accordingly.
 <p>
-<!--X1.1.1--><table width=100%><tr><td bgcolor=red>&nbsp;</td><td width=100%>
+<!--X1.1.1--><table width=100%><tr><td bgcolor=cyan>&nbsp;</td><td width=100%>
 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 <a href="#Internationalization">internationalization</a>,
 it needs to implement the function
 
+<!--X1.1.2--><table width=100%><tr><td bgcolor=red>&nbsp;</td><td width=100%>
 <p><table><tr><td bgcolor=#F0F0F0><pre><br>
-virtual void Start(void);
+virtual bool Start(void);
 </pre></td></tr></table><p>
+<!--X1.1.2--></td></tr></table>
 
 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.
 <p>
+<!--X1.1.2--><table width=100%><tr><td bgcolor=red>&nbsp;</td><td width=100%>
+A return value of <i>false</i> 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
+<i>false</i> from its <tt>Start()</tt> function will cause VDR to exit.
+<!--X1.1.2--></td></tr></table>
+<p>
 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.
 </b>
 
-<hr><h2>Setup parameters</h2>
+<!--X1.1.2--><table width=100%><tr><td bgcolor=red>&nbsp;</td><td width=100%>
+<hr><h2>Housekeeping</h2>
+
+<center><i><b>Chores, chores...</b></i></center><p>
+
+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
+
+<p><table><tr><td bgcolor=#F0F0F0><pre><br>
+virtual void Housekeeping(void);
+</pre></td></tr></table><p>
+
+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 <tt>Housekeeping()</tt>
+function of the same plugin.
+<p>
+<b>
+It is very important that a call to <tt>Housekeeping()</tt> 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.
+</b>
+<!--X1.1.2--></td></tr></table>
+
+<a name="Setup parameters"><hr><h2>Setup parameters</h2>
 
 <center><i><b>Remember me...</b></i></center><p>
 
@@ -490,7 +533,7 @@ previously stored in the global setup data (see below). It shall return
 <i>true</i> if the parameter was parsed correctly, <i>false</i> in case of
 an error. If <i>false</i> is returned, an error message will be written to
 the log file (and program execution will continue).
-<!--X1.1.1--><table width=100%><tr><td bgcolor=red>&nbsp;</td><td width=100%>
+<!--X1.1.1--><table width=100%><tr><td bgcolor=cyan>&nbsp;</td><td width=100%>
 A possible implementation of <tt>SetupParse()</tt> could look like this:
 
 <p><table><tr><td bgcolor=#F0F0F0><pre><br>
@@ -545,7 +588,7 @@ needs setup parameters that are not directly user adjustable. It can use
 <tt>SetupStore()</tt> and <tt>SetupParse()</tt> without presenting these
 parameters to the user.
 
-<!--X1.1.1--><table width=100%><tr><td bgcolor=red>&nbsp;</td><td width=100%>
+<!--X1.1.1--><table width=100%><tr><td bgcolor=cyan>&nbsp;</td><td width=100%>
 <a name="The Setup menu"><hr><h2>The Setup menu</h2>
 
 <center><i><b>Have it your way!</b></i></center><p>
@@ -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).
 <!--X1.1.1--></td></tr></table>
 
+<!--X1.1.2--><table width=100%><tr><td bgcolor=red>&nbsp;</td><td width=100%>
+<hr><h2>Configuration files</h2>
+
+<center><i><b>I want my own stuff!</b></i></center><p>
+
+There may be situations where a plugin requires configuration files of its own, maybe
+for data that can't be stored in the simple <a href="#Setup parameters">setup parameters</a>
+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
+
+<p><table><tr><td bgcolor=#F0F0F0><pre><br>
+const char *ConfigDirectory(const char *PluginName = NULL);
+</pre></td></tr></table><p>
+
+which returns a string containing the directory that VDR uses for its own configuration
+files (defined through the <tt><b>-c</b></tt> option in the call to VDR), extended by
+<tt>"/plugins"</tt>. So assuming the VDR configuration directory is <tt>/video</tt>
+(the default if no <tt><b>-c</b></tt> or <tt><b>-v</b></tt> option is given),
+a call to <tt>ConfigDirectory()</tt> will return <tt>/video/plugins</tt>. The first
+call to <tt>ConfigDirectory()</tt> will automatically make sure that the <tt>plugins</tt>
+subdirectory will exist. If, for some reason, this cannot be achieved, <tt>NULL</tt>
+will be returned.
+<p>
+The additional <tt>plugins</tt> 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
+<tt>name.conf</tt>, where <i>name</i> shall be the name of the plugin.
+<p>
+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 <tt>ConfigDirectory()</tt> function can be given an additional string that will
+be appended to the returned directory name, as in
+
+<p><table><tr><td bgcolor=#F0F0F0><pre><br>
+const char *MyConfigDir = ConfigDirectory(Name());
+</pre></td></tr></table><p>
+
+where <tt>Name()</tt> 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 <tt>NULL</tt> in case of an error).
+<p>
+<b>
+The returned string is statically allocated and will be overwritten by subsequent
+calls to ConfigDirectory()!
+</b>
+<p>
+The <tt>ConfigDirectory()</tt> function is a static member function of the <tt>cPlugin</tt>
+class. This allows it to be called even from outside any member function of the derived
+plugin class, by writing
+
+<p><table><tr><td bgcolor=#F0F0F0><pre><br>
+const char *MyConfigDir = cPlugin::ConfigDirectory();
+</pre></td></tr></table><p>
+<!--X1.1.2--></td></tr></table>
+
 <a name="Internationalization"><hr><h2>Internationalization</h2>
 
 <center><i><b>Welcome to Babylon!</b></i></center><p>