
                                Das Proxy-Plugin



Geschrieben von:             Udo Richter <udo_richter@gmx.de>

Projek Homepage:             http://urichter.cjb.net/vdr/

Siehe Datei COPYING für lizenzinformationen.


Über
----

Proxy ist ein Plugin, das ein anderes Plugin lädt. Das Proxy-Plugin dient
dabei als Kapselung für ein anderes VDR Plugin, und leitet alle Interfaces
durch. Um dies tatsächlich nützlich zu machen, kann das Proxy-Plugin das
Verhalten des gekapselten Plugins modifizieren, und so den Menüeintrag
verändern, mehrere Plugins in ein Untermenü gruppieren, und Plugins im 
laufenden Betrieb laden und entladen. Dies alles funktioniert, obwohl Proxy
nur ein Plugin ist, und keine Patches an VDR erfordert.

All dies ist eher trickreich, da VDR-Plugins normalerweise nicht für solche
Dinge entworfen wurden. Daher wird Proxy immer zu manchen Plugins 
inkompatibel sein. Due Benutzung von Proxy erfolgt auf eigenes Risiko. 
Siehe Kapitel 'Kompatibilität' für Details.

Das Proxy-Plugin würde auf den VDR-Versionen 1.3.23 - 1.4.0 entwickelt, 
sollte aber auch auf älteren und neueren Versionen funktionieren.


Installing
----------

Extract and compile like other plugins:

   cd vdr-x.x.xx/PLUGINS/src
   tar xzf vdr-proxy-x.x.x.tgz
   ln -s proxy-x.x.x proxy
   cd ../..
   make plugins

If you encounter errors regarding #include linux/dvb, add this to your 
VDR global Make.config or to a local Make.config in the proxy folder:

   INCLUDES += -I/path/to/DVB/driver/include

Proxy will accept some switches and a plugin name on command line. For 
example, if your VDR command line has been like this before:

   vdr -P someplugin -P "someother -foo"
   
... you can use proxy like this:

   vdr -P "proxy someplugin" -P "proxy someother -foo"

The general format is -P "proxy [proxy-options] plugin [plugin-options]".

The following command line options are available:

--menu-hide, -h
    Versteckt den Hauptmenüeintrag des Plugins. Die Hauptmenü-Aktion kann
    weiterhin von anderen Plugins etc. aufgerufen werden.

--menu-name name, -n name
    Ersetzt den Menü-Eintrag des Plugins. Damit kann auch eine sonst 
    unsichtbare Menü-Aktion wieder sichtbar machen, falls diese vom
    Plugin versteckt wurde.

--menu-group name, -g name
    Weist dieses Plugin der Menü-Gruppe 'name' zu. Alle Plugins aus der 
    gleichen Gruppe teilen sich einen Hauptmenüeintrag, der ein Untermenü
    öffnet, in der sich die eigentlichen Plugin-Menüeinträge befinden.

--suspended, -s
    Lädt das Plugin im angehaltenen Zustand. Nur der Proxy wird beim 
    Start geladen, das eigentliche Plugin wird erst geladen, wenn es 
    'fortgesetzt' wird. Angehaltene Plugins können durch Auswahl des 
    Menüeintrags, durch SVDRP-Kommandos und durch das Setup-Menü des
    Proxy-Plugins gestartet werden.

--hide-on-suspend, -i
    Normalerweise haben angehaltene Plugins einen Hauptmenüeintrag,
    über den sie fortgesetzt und gestartet werden können. Mit dieser
    Option verschwindet der Hauptmenüeintrag von angehaltenen Plugins.
    Das Plugin kann dann nur noch über das Setup-Menü des Proxy-Plugin
    und über SVDRP-Kommandos gestartet werden.

--suspend-on-error, -e
    Plugin-Fehler beim VDR-Start bewirken, dass VDR anhält. Mit dieser
    Option wird das Plugin im Fehlerfall im angehaltenen Zustand geladen,
    so dass VDR normal starten kann.


Plugins loaded by proxy will show their usual setup page as long as they 
are running.

The proxy plugin adds an additional setup menu page, and a dummy setup 
entry for each menu group. The proxy setup page allows suspending and 
resuming of most plugins loaded with proxy. For some plugins, suspending 
is denied automatically. 

Suspended plugins will be unloaded from memory, and can even be updated to 
newer versions while VDR is running.


SVDRP control interface
-----------------------

The proxy plugin can suspend and resume plugins on SVDRP commands. These 
commands are available:

   PLUG proxy RSUM <plugin>
      Startet das angegebene Plugin, falls es sich im angehaltenen 
      Zustand befindet.
      
   PLUG proxy SUSP <plugin>
      Hält das Plugin an, falls es gerade läuft.

   PLUG proxy RELD <plugin>
      Hält das Plugin an und setzt es dann fort, wodurch das Plugin erneut
      von der Festplatte geladen wird.


Compatibility
-------------

The proxy plugin goes far beyond what actually is intended plugin behavior.
Although proxy should work more or less with most plugins, all proxified 
plugins should be tested throughly. Some general hints on compatibility 
issues that will cause trouble:

General issues:

- Cross-plugin communication. If two plugins directly access each other,
  using nonstandard interfaces, there's a high risk of crashes. Simple 
  invocations of the main menu action of other plugins, and using the 
  Service() interface should work though.

- Plugin interface extensions. Plugins that depend on VDR patches to the
  plugin system to enhance plugin capabilities wont work, because VDR
  has no direct access to the real plugin.

Suspend/Resume issues:

- Skins, receiver devices, display devices, remote plugins, audio plugins:
  These plugins cannot be suspended safely. Proxy tries to detect them
  automatically and denies suspending for them. Otherwise, VDR will
  likely crash.

- Incomplete termination: Plugins that dont terminate well may cause a 
  crash when unloaded from memory.

- Initialization and destruction order is not the same as VDR default, 
  especially if the plugin depends on VDR internal state. Some plugins
  may require a channel change after resuming to be fully working.


