                              The OSDServer Plugin


Written by:                  Udo Richter <udo_richter@gmx.de>

Project's homepage:          http://www.udo-richter.de/vdr/osdserver.html
                             http://www.udo-richter.de/vdr/osdserver.en.html

See the file COPYING for license information.




Todo: Write me. ;)



Ok, lets make this short. OSDServer provides VDR OSD access to external
programs and scripts. The examples folder contains a hello world sample in
perl and in shell script using netcat. OSDServer listens for commands on port 
2010 and re-uses the svdrphosts.conf for now.

Command format looks like this:

[Varname = ] [Object.] Command [Parameters]

Everything is case-insensitive. Some commands return objects, these can be
assigned to variable names for later use. Some commands are global, some are
object-local. Parameters are evaluated shell-like, separated by whitespace.
""-quotes preserve whitespace, except newlines. The parser understands
\\, \" and \n. Flags start with -. Flags and parameters can be mixed in any 
order. If needed, -- marks the last flag, everything past that is not 
interpreted as flag any more.

All reply-lines start with a 3-digit decimal number and a whitespace. The
first digit is the category:

1xx Debugging messages
2xx End-of-reply messages
3xx Simple data return
4xx Error messages
5xx Quoted text return, single line (not used yet)
6xx Unquoted text return, multiline (not used yet)

Each server reply can be identified by its code. Several mixed reply lines
are possible. The reply always contains exactly one 2xx line at the end,
after which the server will start listening for new commands, except after 
202 Good Bye. There will be no more than one line of 3xx type.

After connecting, the first expected command is "VERSION 0". This identifies
the protocol version, for future changes.

The following commands are available:

QUIT
  Guess what.

IDLE
  does nothing.

MESSAGE [-info|-warn|-error] -queue [-timeout #] [-seconds #] message
MESSAGE [-info|-warn|-error] [-seconds #] message
MESSAGE -status message
MESSAGE -statusclear
  Issue OSD message. Defaults to -info messages. With -queue, use VDR message
  queue system with specified queue timeout. Without -queue, show message
  immediately. The message is shown the specified number of seconds. With
  -status, show the message until -statusclear is used again.

  -info, -warn and -error return a key event, "300 Message keyOk" for example.
  With -queue, a "301 timeout" is also possible.


menu = NEWMENU Title
  Create a new OSD menu. (Doesnt display)

menuitem = menu.ADDOSDITEM Text
  Add a menu item to the menu with given text

menu.SETCURRENT number
  Set menu item number as currently selected item

menuitem.SETCURRENT
  Set menu item as the currently selected item in its menu

menu.GETCURRENT
  Get currently selected menu item. Returns something like "302 4 myitem" if
  the menu item "myitem" in line 5 is currently selected. If nothing is
  selected, "302 -1" is returned.

menu.SHOW
  Actually push menu to display. All changes to menus are hold back until
  SHOW is called.

menu.ENABLEEVENT event
  Enable event receiving for menu. Currently only two events exist, "keyOk"
  and "close".

menu.SLEEPEVENT [-timeout #|-timeoutms #]
  Wait for the next enabled event to happen, for specified time in seconds or
  miliseconds. Menu must be visible for this. Returns like "300 menu keyOk"
  or "301 timeout".

menu.SENDSTATE state
  Let menu return VDR eOSState. Currently supports osEnd, osBack and
  osContinue.


