This document is divided into two parts, the first one describing the outside interface of the plugin system, and the second one describing the inside interface. The outside interface handles everything necessary for a plugin to get hooked into the core VDR program and present itself to the user. The inside interface provides the plugin code access to VDR's internal data structures and allows it to hook itself into specific areas to perform special actions.
| Important modifications introduced in version 1.1.11 are marked like this. |
| Important modifications introduced in version 1.1.12 are marked like this. |
| Important modifications introduced in version 1.1.13 are marked like this. |
| Important modifications introduced in version 1.1.14 are marked like this. |
Actually you should read this entire document before starting to work with VDR plugins, but you probably want to see something happening right away ;-)
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:
One of the first things to consider when writing a VDR plugin is giving the thing a proper name. This name will be used in the VDR command line in order to load the plugin, and will also be the name of the plugin's source directory, as well as part of the final library name.
The plugin's name should typically be as short as possible. Three letter abbreviations like dvd (for a DVD player) or mp3 (for an MP3 player) would be good choices. It is also recommended that the name consists of only lowercase letters and digits. No other characters should be used here.
A plugin can access its name through the (non virtual) member function
|
The actual name is derived from the plugin's library file name, as defined in the
next chapter.
By default plugins are located in a directory named PLUGINS below the
VDR source directory. Inside this directory the following subdirectory structure
is used:
The plugin directory structure
|
The src directory contains one subdirectory for each plugin, which carries 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 loadable library file for that plugin (we'll get to the details later).
The lib directory contains the dynamically loadable libraries of all available plugins. Note that the names of these files are created by concatenating
| 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 |
The plugin library files can be stored in any directory. If the default organization is not used, the path to the plugin directory has be be given to VDR through the -L option.
The VDR Makefile contains the target plugins, which calls make all in every directory found under VDR/PLUGINS/src, plus the target plugins-clean, which calls make clean in each of these directories.
If you download a plugin package from the web, it will typically have a name like
vdr-hello-0.0.1.tgz
and will unpack into a directory named
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 hello-0.0.1 and
hello-0.0.2) and define which one to actually use through the symbolic link.
Call the Perl script newplugin from the VDR source directory to create
a new plugin directory with a Makefile and a main source file implementing
the basic derived plugin class.
You will also find a README file there with some inital text, where you
should fill in actual information about your project.
A HISTORY file is set up with an "Initial revision" entry. As your project
evolves, you should add the changes here with date and version number.
newplugin also creates a copy of the GPL license file COPYING,
assuming that you will release your work under that license. Change this if you
have other plans.
Add further files and maybe subdirectories to your plugin source directory as
necessary. Don't forget to adapt the Makefile appropriately.
A newly initialized plugin doesn't really do very much yet.
If you load it into VDR you will find a new
entry in the main menu, with the same name as your plugin (where the first character
has been converted to uppercase). There will also be a new entry named "Plugins" in
the "Setup" menu, which will bring up a list of all loaded plugins, through which you
can access each plugin's own setup parameters (if it provides any).
To implement actual functionality into your plugin you need to edit the source file
that was generated as PLUGINS/src/name.c. Read the comments in that file
to see where you can bring in your own code. The following sections of this document
will walk you through the individual member functions of the plugin class.
Depending on what your plugin shall do, you may or may not need all of the given
member functions. Except for the MainMenuEntry() function they all by default
return values that will result in no actual functionality. You can either completely
delete unused functions from your source file, or just leave them as they are.
If your plugin shall not be accessible through VDR's main menu, simply remove
(or comment out) the line implementing the MainMenuEntry() function.
At the end of the plugin's source file you will find a line that looks like this:
Initializing a new plugin directory
The actual implementation
|
This is the "magic" hook that allows VDR to actually load the plugin into 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
|
The example shown here is the way VDR does this in its core source files. It takes the header file's name, converts it to all uppercase, replaces the dot with an underline and preceedes the whole thing with two underlines. The GNU library header files do this pretty much the same way, except that they usually precede the name with only one underline (there are exceptions, though).
As long as you make shure that none of your plugin's header files will be named like one of VDR's header files, you can use the same method as VDR. However, if you want to name a header file like one that is already existing in VDR's source (i18n.h would be a possible candidate for this), you may want to make sure that the macros used here don't clash. How you do this is completely up to you. You could, for instance, prepend the macro with a 'P', as in P__I18N_H, or leave out the trailing _H, as in __I18N, or use a completely different way to make sure a header file is included only once.
The 'hello' example that comes with VDR makes use of internationalization and implements a file named i18n.h. To make sure it won't clash with VDR's i18n.h it uses the macro _I18N__H (one underline at the beginning and two replacing the dot).
The constructor and destructor of a plugin are defined as
|
The constructor shall initialize any member variables the plugin defines, but must not access any global structures of VDR. It also must not create any threads or other large data structures. These things are done in the Start() function later. Constructing a plugin object shall not have any side effects or produce any output, since VDR, for instance, has to create the plugin objects in order to get their command line help - and after that immediately destroys them again.
The destructor has to clean up any data created by the plugin, and has to take care that any threads the plugin may have created will be stopped.
Of course, if your plugin doesn't define any member variables that need to be initialized (and deleted), you don't need to implement either of these functions.
Every plugin must have a version number of its own, which does not necessarily have to be in any way related to the VDR version number. VDR requests a plugin's version number through a call to the function
|
Since this is a "pure" virtual function, any derived plugin class must implement it. The returned string should identify this version of the plugin. Typically this would be something like "0.0.1", but it may also contain other information, like for instance "0.0.1pre2" or the like. The string should only be as long as really necessary, and shall not contain the plugin's name itself. Here's an example:
|
Note that the definition of the version number is expected to be located in the main source file, and must be written as
static const char *VERSION = ...just like shown in the above example. This is a convention that allows the Makefile to extract the version number when generating the file name for the distribution archive.
A new plugin project should start with version number 0.0.1 and should reach version 1.0.0 once it is completely operative and well tested. Following the Linux kernel version numbering scheme, versions with even release numbers (like 1.0.x, 1.2.x, 1.4.x...) should be stable releases, while those with odd release numbers (like 1.1.x, 1.3.x, 1.5.x...) are usually considered "under development". The three parts of a version number are not limited to single digits, so a version number of 1.2.15 would be acceptable.
In order to tell the user what exactly a plugin does, it must implement the function
|
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.
A VDR plugin can have command line arguments just like any normal program. If a plugin wants to react on command line arguments, it needs to implement the function
|
The parameters argc and argv have exactly the same meaning as in a normal C program's main() function. argv[0] contains the name of the plugin (as given in the -P option of the vdr call).
Each plugin has its own set of command line options, which are totally independent from those of any other plugin or VDR itself.
You can use the getopt() or getopt_long() function to process these arguments. As with any normal C program, the strings pointed to by argv will survive the entire lifetime of the plugin, so it is safe to store pointers to these values inside the plugin. Here's an example:
|
The return value must be true if all options have been processed correctly, or false in case of an error. The first plugin that returns false from a call to its ProcessArgs() function will cause VDR to exit.
If a plugin accepts command line options, it should implement the function
|
which will be called if the user enters the -h option when starting VDR. The returned string should contain the command line help for this plugin, formatted in the same way as done by VDR itself:
|
This command line help will be printed directly below VDR's help texts (separated
by a line indicating the plugin's name, version and description), so if you use the
same formatting as shown here it will line up nicely.
Note that all lines should be terminated with a newline character, and should
be shorter than 80 characters.
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
Getting started
|
which is called once for each plugin at program startup. Inside this function the plugin must set up everything necessary to perform 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.
If the plugin implements a feature that the user shall be able to access from VDR's main menu, it needs to implement the function
|
The default implementation returns a NULL pointer, which means that this plugin will not have an item in the main menu. Here's an example of a plugin that will have a main menu item:
|
The menu entries of all plugins will be inserted into VDR's main menu right after the Recordings item, in the same sequence as they were given in the call to VDR.
If the user selects the main menu entry of a plugin, VDR calls the function
|
which can do one of two things:
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
|
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.
If a plugin requires its own setup parameters, it needs to implement the following
functions to handle these parameters:
Setup parameters
|
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 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:
|
It is important to make sure that the parameter names are exactly the same as used in the Setup menu's Store() function.
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
hello.GreetingTime = 3
The prefix will be handled by the core VDR setup code, so the individual plugins need not worry about this.
To store its values in the global setup, a plugin has to call the function
|
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.
To remove a parameter from the setup data, call SetupStore() with the appropriate name and without any value, as in
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 the plugin's "Setup" menu if that plugin has implemented the SetupMenu() function.
Finally, a plugin doesn't have to implement the SetupMenu() if it only
needs setup parameters that are not directly user adjustable. It can use
SetupStore() and SetupParse() without presenting these
parameters to the user.
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:
The Setup menu
|
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).
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
|
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
|
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
|
|
to register them with VDR's internationalization mechanism.
The call to this function must be done in the Start() function of the plugin:
|
Each entry of type tI18nPhrase must have exactly as many members as defined
by the constant I18nNumLanguages in the file VDR/i18n.h, and the
sequence of the various languages must be the same as defined in VDR/i18n.c.
It is very important that the array is terminated with a { NULL }
entry!.
Usually you won't be able to fill in all the different translations by yourself, so you may want to contact the maintainers of these languages (listed in the file VDR/i18n.c) and ask them to provide the additional translations.
The actual runtime selection of the texts corresponding to the selected language is done by wrapping each internationalized text with the tr() macro:
|
The text given here must be the first one defined in the related Phrases
entry (which is the English version), and the returned pointer is either a translated
version (if available) or the original string. In the latter case a message will be
written to the log file, indicating that a translation is missing.
Texts are first searched for in the Phrases registered for this plugin (if any)
and then in the global VDR texts. So a plugin can make use of texts defined by the
core VDR code.
Plugins are loaded into VDR using the command line option -P, as in
Loading plugins into VDR
|
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 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 -P options following it.
When started with the -h or -V option (for help
or version information, respectively), VDR will automatically load all plugins
in the default or given directory that match the VDR plugin
naming convention,
and display their help and/or version information in addition to its own output.
If you want to make your plugin available to other VDR users, you'll need to
make a package that can be easily distributed.
The Makefile that has been created by the call to
newplugin
provides the target dist, which does this for you.
Simply change into your source directory and execute make dist:
Building the distribution package
|
After this you should find a file named like
|
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.
If a plugin wants to get informed on various events in VDR, it can derive a class from
cStatus, as in
Part II - The Inside Interface
Status monitor
|
An object of this class will be informed whenever the channel is switched on one of the DVB devices. It could be used in a plugin like this:
|
Note that the actual object is created in the Start() function, not in the constructor! It is also important to delete the object in the destructor, in order to avoid memory leaks.
A Plugin can implement any number of cStatus derived objects, and once the plugin has been started it may create and delete them as necessary. No further action apart from creating an object derived from cStatus is necessary. VDR will automatically hook it into a list of status monitors, with their individual virtual member functions being called in the same sequence as the objects were created.
See the file status.h for detailed information on which status monitor member functions are available in cStatus. You only need to implement the functions you actually want to use.
Implementing a player is a two step process. First you need the actual player class, which is derived from the abstract cPlayer:
|
What exactly you do in this class is entirely up to you. If you want to run a separate thread which, e.g., reads data from a file, you can additionally derive your class from cThread and implement the necessary functionality:
|
Take a look at the files player.h and dvbplayer.c to see how VDR implements its own player for the VDR recordings.
To play the video data, the player needs to call its member function
|
where Data points to a block of Length bytes of a PES data stream. There are no prerequisites regarding the length or alignment of an individual block of data. The sum of all blocks must simply result in the desired video data stream, and it must be delivered fast enough so that the DVB device doesn't run out of data. To avoid busy loops the player should call its member function
|
to determine whether the device is ready for further data.
|
If the player can provide more than a single audio track, it can implement the following functions to make them available:
|
TODO: PlayAudio()???
The second part needed here is a control object that receives user input from the main program loop and reacts on this by telling the player what to do:
|
cMyControl shall create an object of type cMyPlayer and hand over a pointer to it to the cControl base class, so that it can be later attached to the primary DVB device:
|
cMyControl will receive the user's key presses through the ProcessKey() function. It will get all button presses, except for the volume control buttons (kVolUp, kVolDn, kMute), the power button (kPower) and the menu button (kMenu). If the user has not pressed a button for a while (which is typically in the area of about one second), ProcessKey() will be called with kNone, so that the cMyControl gets a chance to check whether its player is still active. Once the player has become inactive (because the user has decided to stop it or the DVB device has detached it), ProcessKey() must return osEnd to make the main program loop shut down the player control.
A derived cControl must implement the Hide() function, in which it has to hide itself from the OSD, in case it uses it. Hide() may be called at any time, and it may be called even if the cControl is not visible at the moment. The reason for this is that the Menu button shall always bring up the main VDR menu, so any active cControl needs to be hidden when that button is pressed.
Finally, to get things going, a plugin that implements a player (and the surrounding infrastructure like displaying a list of playable stuff etc) simply has to call the static function cControl::Launch() with the player control object, as in
|
Ownership of the MyControl object is handed over to the VDR core code, so the plugin should not keep a pointer to it, because VDR will destroy the object whenever it sees fit (for instance because a recording shall start that needs to use the primary DVB device, or the user decides to start a different replay).
The cPlayer class has a member function
|
which can be called to display a still picture. VDR uses this function when handling its editing marks. A special case of a "player" might use this function to implement a "picture viewer".
For detailed information on how to implement your own player, please take a look at VDR's cDvbPlayer and cDvbPlayerControl classes.
User interface
In order for a new player to nicely "blend in" to the overall VDR appearance it is recommended that it implements the same functionality with the same keys as the VDR player does (as far as this is possible and makes sense). The main points to consider here are
In order to receive any kind of data from a cDevice, a plugin must set up an object derived from the cReceiver class:
|
See the comments in VDR/receiver.h for details about the various member functions of cReceiver.
The above example sets up a receiver that wants to receive data from only one PID (for example the Teletext PID). In order to not interfere with other recording operations, it sets its priority to -1 (any negative value will allow a cReceiver to be detached from its cDevice at any time.
Once a cReceiver has been created, it needs to be attached to a cDevice:
|
If the cReceiver isn't needed any more, it may simply be deleted and will automatically detach itself from the cDevice.
Most of the time a plugin should be able to access the OSD through the standard mechanisms also used by VDR itself. However, these set up the OSD in a manner of textual rows and columns, and automatically set the various windows and color depths.
If a plugin needs to have total control over the OSD, it can call the static function
|
where x and y are the coordinates of the upper left corner of the OSD area on the screen. Such a "raw" OSD doesn't display anything yet, so you need to at least call the function
|
to define an actual OSD drawing area (see VDR/osdbase.h for the declarations of these functions, and VDR/osd.c to see how VDR opens the OSD and sets up its windows and color depths).
By default VDR is based on using DVB PCI cards that are supported by the LinuxDVB driver. However, a plugin can implement additional devices that can be used as sources of MPEG data for viewing or recording, and also as output devices for replaying. Such a device can be a physical card that is installed in the PC (like, for instance, an MPEG encoder card that allows the analog signal of a proprietary set-top box to be integrated into a VDR system; or an analog TV receiver card, which does the MPEG encoding "on the fly" - assuming your machine is fast enough), or just a software program that takes an MPEG data stream and displays it, for instance, on an existing graphics adapter.
To implement an additional device, a plugin must derive a class from cDevice:
|
The derived class must implement several virtual functions, according to the abilities this new class of devices can provide. See the comments in the file VDR/device.h for more information on the various functions, and also VDR/dvbdevice.[hc] for details on the implementation of the cDvbDevice, which is used to access the DVB PCI cards.
Channel selection
If the new device can receive, it most likely needs to provide a way of selecting which channel it shall tune to:
|
These functions will be called with the desired source or channel and shall return whether this device can provide the requested source or channel and whether tuning to it was successful, repectively.
|
Audio selection If the device can provide more than a single audio track, it can implement the following functions to make them available:
|
Recording
A device that can be used for recording must implement the functions
|
which allow VDR to set the PIDs that shall be recorded, set up the device for recording (and shut it down again), and receive the MPEG data stream. The data must be delivered in the form of a Transport Stream (TS), which consists of packets that are all 188 bytes in size. Each call to GetTSPacket() must deliver exactly one such packet (if one is currently available).
If this device allows receiving several different data streams, it can implement
|
to indicate this to VDR.
Replaying
The functions to implement replaying capabilites are
|
In addition, the following functions may be implemented to provide further functionality:
|
On Screen Display
If your device provides On Screen Display (OSD) capabilities (which every device that is supposed to be used as a primary device should do), it can implement the function
|
which must return a newly created object of a derived cOsdBase class that implements the functions necessary to display OSD information on your device. The caller of this function will delete the object as soon as it is no longer needed.
Initializing new devices
A derived cDevice class shall implement a static function
|
in which it determines whether the necessary hardware to run this sort of device is actually present in this machine (or whatever other prerequisites might be important), and then creates as many device objects as necessary. See VDR/dvbdevice.c for the implementation of the cDvbDevice initialize function.
A plugin that adds devices to a VDR instance shall call this initializing function from its Start() function.
Nothing needs to be done to shut down the devices. VDR will automatically shut down (delete) all devices when the program terminates. It is therefore important that the devices are created on the heap, using the new operator!
Remote ControlThere are several ways to control the operation of VDR. The builtin methods are using the PC keyboard, a homebuilt RCU unit or the LIRC interface. Of course there may be many more ways you might think of to implement a remote control, so a plugin can use the cRemote class to do that. The simplest method for a plugin to issue commands to VDR is to call the static function cRemote::Put(eKeys Key), as in
In this case the plugin must do the mapping of whatever incoming signal or code it processes to the eKeys values itself. This makes sense if the incoming codes are well known and won't ever change. In cases where the incoming codes are not known, or not all available keys may be supported by the actual remote control in use, you may want to derive your own remote control class from cRemote, as in
Note that deriving from cThread is not required for a remote control class to work, but typically you may want to have a separate thread running that collects the input and delivers it to the cRemote base class. You should create your derived remote control object in the Start() function of your plugin. Note that the object has to be created on the heap (using new), and you shall not delete it at any point (it will be deleted automatically when the program ends). The constructor of your remote control class should look like this
The Name is important in order for the cRemote base class to be able to distinguish the codes for the various remote controls. When creating your cMyRemote object you should use the value returned by the Name() member function of the plugin class, which returns the plugin's name. Calling Start() will start the thread that collects the incoming data (by calling your Action() function). In case you need to do any other setup steps, like opening a file or initializing member variables, you should do so before calling Start(). VDR will handle everything necessary to learn the key mappings of your remote control. In order to do so, it will first call the virtual function Initialize(), in which you should take all necessary steps to make sure your remote control can be accessed. This may, for instance, include trying various communications protocols. Initialize(), if implemented, shall only return after it has made sure data can be received from the remote control. Before calling this function, VDR will prompt the user on the OSD to press any key on the remote control. As soon as your derived cRemote class has detected useful incoming data, Initialize() should return true. If any fatal error occurs, false should be returned. If your remote control class needs some setup data that shall be readily available next time VDR starts (without having to go through the initialization procedure again) it can use the cRemote member functions
to store and retrieve a character string containing whatever data is needed. Note that the Initialize() function will only be called if there are no key mappings known for this remote control. Once the key mappings have been learned, Initialize() will never be called again. The cRemote class assumes that any incoming remote control code can be expressed as a character string. So whatever data your remote control provides needs to be given to the base class by calling
where Code is the string representation of the remote control's incoming data. Repeat and Release are boolean flags that indicate whether this is a repeated keypress, or the key has been released. Since a common case for remote control data is to be given as a numerical value, there is another Put() function available for your convenience, which takes a 64 bit unsigned integer value instead of a character string:
The other parameters have the same meaning as in the first version of this function. |