frodovdr/vdr
1
0
Fork 0
mirror of https://github.com/vdr-projects/vdr.git synced 2025-03-01 10:50:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Version 1.1.2

Browse Source 
- 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.
This commit is contained in:
Klaus Schmidinger
2002-05-13 18:00:00 +02:00
parent 803c6c6bf6
commit d07e3829f7
31 changed files with 556 additions and 301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
PLUGINS.html
View File

@@ -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>