From 08e4f36ccdee163b6925f09f591fbc8ce8c2611b Mon Sep 17 00:00:00 2001 From: Klaus Schmidinger Date: Sun, 24 Nov 2002 10:45:39 +0100 Subject: Plugins can now have their own raw OSD --- PLUGINS.html | 125 ++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 85 insertions(+), 40 deletions(-) (limited to 'PLUGINS.html') diff --git a/PLUGINS.html b/PLUGINS.html index e5948868..fe651303 100644 --- a/PLUGINS.html +++ b/PLUGINS.html @@ -13,30 +13,68 @@ separate from the core VDR source, without the need of patching the original VDR code (and all the problems of correlating various patches).

This document is divided into two parts, the first one describing the -outside interface +external 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 +internal interface. +The external 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 +The internal 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.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.
-
  +
  Important modifications introduced in version 1.1.15 are marked like this.
+
  +Important modifications introduced in version 1.1.17 are marked like this. +
-

Part I - The Outside Interface

+
+

Table Of Contents

+ + +

Part I - The External Interface

-

Quick start

+

Quick start

Can't wait, can't wait!

@@ -58,7 +96,7 @@ So, for a quick demonstration of the plugin system, there is a sample plugin cal If you enjoyed this brief glimpse into VDR plugin handling, read through the rest of this document and eventually write your own VDR plugin. -

The name of the plugin

+

The name of the plugin

Give me some I.D.!

@@ -164,7 +202,7 @@ have other plans. Add further files and maybe subdirectories to your plugin source directory as necessary. Don't forget to adapt the Makefile appropriately. -

The actual implementation

+

The actual implementation

Use the source, Luke!

@@ -231,7 +269,7 @@ and implements a file named i18n.h. To make sure it won't clash with VD i18n.h it uses the macro _I18N__H (one underline at the beginning and two replacing the dot). -

Construction and Destruction

+

Construction and Destruction

What goes up, must come down...

@@ -256,7 +294,7 @@ 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. -

Version number

+

Version number

Which incarnation is this?

@@ -301,7 +339,7 @@ while those with odd release numbers (like 1.1.x, 1.3.x a version number are not limited to single digits, so a version number of 1.2.15 would be acceptable. -

Description

+

Description

What is it that you do?

@@ -325,7 +363,7 @@ virtual const char *Description(void) Note the tr() around the DESCRIPTION, which allows the description to be internationalized. -

Command line arguments

+

Command line arguments

Taking orders

@@ -379,7 +417,7 @@ 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. -

Command line help

+

Command line help

Tell me about it...

@@ -434,7 +472,7 @@ write a proper error message to the log file. The first plugin that returns If the plugin doesn't implement any background functionality or internationalized texts, it doesn't need to implement this function. -

Main menu entry

+

Main menu entry

Today's special is...

@@ -462,25 +500,34 @@ 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. -

User interaction

+

User interaction

It's showtime!

If the user selects the main menu entry of a plugin, VDR calls the function +
  



-virtual cOsdMenu *MainMenuAction(void);
+virtual cOsdObject *MainMenuAction(void);

-which can do one of two things: +which can do one of three things:

  • Return a pointer to a cOsdMenu object which will be displayed as a submenu of the main menu (just like the Recordings menu, for instance). That menu can then implement further functionality and, for instance, could eventually start a custom player to replay a file other than a VDR recording. +
  • Return a pointer to a cOsdObject object which will be displayed + instead of the normal menu. The derived cOsdObject can open a + raw OSD from within its Show() + function (it should not attempt to do so from within its constructor, since + at that time the OSD is still in use by the main menu). + See the 'osddemo' example that comes with VDR for a demonstration of how this + is done.
  • Perform a specific action and return NULL. In that case the main menu will be closed after calling MainMenuAction().
+
It is very important that a call to MainMenuAction() returns as soon as possible! As long as the program stays inside this function, no other user @@ -488,7 +535,7 @@ interaction is possible. If a specific action takes longer than a few seconds, the plugin should launch a separate thread to do this. -

Housekeeping

+

Housekeeping

Chores, chores...

@@ -644,7 +691,7 @@ You can first assign the temporary values to the global variables and then do th your setup parameters and use that one to copy all parameters with one single statement (like VDR does with its cSetup class). -

Configuration files

+

Configuration files

I want my own stuff!

@@ -832,9 +879,9 @@ vdr-hello-0.0.1.tgz 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. -

Part II - The Inside Interface

+

Part II - The Internal Interface

-

Status monitor

+

Status monitor

A piece of the action

@@ -907,7 +954,7 @@ 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. -

Players

+

Players

Play it again, Sam!

@@ -964,7 +1011,7 @@ bool DevicePoll(cPoller &Poller, int TimeoutMs = 0);

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: @@ -977,7 +1024,7 @@ virtual void SetAudioTrack(int Index);

-
  +
  If there is an additional audio track that has to be replayed with external hardware, the player shall call its member function @@ -1085,7 +1132,7 @@ enjoy additional players, since they will be able to control them with actions that they already know. If you absolutely want to do things differently, just go ahead - it's your show... -

Receivers

+

Receivers

Tapping into the stream...

@@ -1139,7 +1186,7 @@ cDevice::PrimaryDevice()->AttachReceiver(Receiver); If the cReceiver isn't needed any more, it may simply be deleted and will automatically detach itself from the cDevice. -

The On Screen Display

+

The On Screen Display

Express yourself

@@ -1169,7 +1216,7 @@ 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). -

Devices

+

Devices

Expanding the possibilities

@@ -1205,9 +1252,7 @@ If the new device can receive, it most likely needs to provide a way of selecting which channel it shall tune to: 



-
 
 virtual bool ProvidesSource(int Source) const;
-

 virtual bool ProvidesChannel(const cChannel *Channel, int Priority = -1, bool *NeedsDetachReceivers = NULL);
 virtual bool SetChannelDevice(const cChannel *Channel, bool LiveView);

@@ -1215,7 +1260,7 @@ virtual bool SetChannelDevice(const cChannel *Channel, bool LiveView); 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

@@ -1262,7 +1307,7 @@ The functions to implement replaying capabilites are 



 virtual bool HasDecoder(void) const;
-
 
+
 
 virtual bool CanReplay(void) const;
 

 virtual bool SetPlayMode(ePlayMode PlayMode);
@@ -1324,8 +1369,8 @@ 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!
 
-
 
-
Dolby Digital

+
 
+
Dolby Digital

 
 
"The stereo effect may only be experienced if stereo equipment is used!"

 
@@ -1369,7 +1414,7 @@ The Mute() and Clear() functions will be called whenever the a
 be muted, or any buffered data shall be cleared, respectively.
 

 
-
Remote Control

+
Remote Control

 
 
The joy of zapping!

 
-- 
cgit v1.2.3