From 6445b9a0864a945d50e5ea4744f3bfa4ee8622dd Mon Sep 17 00:00:00 2001 From: Klaus Schmidinger Date: Sat, 27 Aug 2005 16:42:28 +0200 Subject: Implemented SVDRP command for plugins --- PLUGINS.html | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 107 insertions(+), 15 deletions(-) (limited to 'PLUGINS.html') diff --git a/PLUGINS.html b/PLUGINS.html index bcd6e581..7123f74c 100644 --- a/PLUGINS.html +++ b/PLUGINS.html @@ -14,18 +14,18 @@ Copyright © 2005 Klaus Schmidinger
www.cadsoft.de/vdr

-
  -Important modifications introduced in version 1.3.19 are marked like this. -
-
  +
  Important modifications introduced in version 1.3.20 are marked like this.
-
  +
  Important modifications introduced in version 1.3.21 are marked like this.
-
  +
  Important modifications introduced in version 1.3.30 are marked like this.
+
  +Important modifications introduced in version 1.3.31 are marked like this. +

VDR provides an easy to use plugin interface that allows additional functionality to be added to the program by implementing a dynamically loadable library file. @@ -58,7 +58,7 @@ structures and allows it to hook itself into specific areas to perform special a

  • Command line arguments
  • Command line help
  • Getting started -
      +
     
  • Shutting down
  • Main menu entry @@ -68,9 +68,12 @@ structures and allows it to hook itself into specific areas to perform special a
  • The Setup menu
  • Configuration files
  • Internationalization -
      +
     
  • Custom services
    • +
      +
  • SVDRP commands +
  • Loading plugins into VDR
  • Building the distribution package @@ -84,7 +87,7 @@ structures and allows it to hook itself into specific areas to perform special a
  • Skins
  • Themes
  • Devices -
      +
     
  • Audio
  • Remote Control @@ -311,7 +314,7 @@ 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. -
      +
      Any threads the plugin may have created shall be stopped in the Stop() function.
    @@ -509,7 +512,7 @@ VDR to exit. If the plugin doesn't implement any background functionality or internationalized texts, it doesn't need to implement either of these functions. -
      +
     

    Shutting down

    Stop it, right there!

    @@ -869,7 +872,7 @@ Texts are first searched for in the Phrases registered for this plugin (i and then in the global VDR texts. So a plugin can make use of texts defined by the core VDR code. -
      +
     

    Custom services

    What can I do for you?

    @@ -940,6 +943,97 @@ any plugin handled the request, or false if no plugin handled the reque

    +
      +

    SVDRP commands

    + +
    Infinite Diversity in Infinite Combinations

    + +A plugin can implement its own SVDRP commands through the two functions + +

    +virtual const char **SVDRPHelpPages(void);
+virtual cString SVDRPCommand(const char *Cmd, const char *Option, int &ReplyCode);
+

    + +The SVDRPHelpPages() function must return a pointer to a list of help +strings for all of the plugin's SVDRP commands, like this + +

    +const char **cPluginSvdrpdemo::SVDRPHelpPages(void)
+{
+  static const char *HelpPages[] = {
+    "DATE\n"
+    "    Print the current date.",
+    "TIME [ raw ]\n"
+    "    Print the current time.\n"
+    "    If the optional keyword 'raw' is given, the result will be the\n"
+    "    raw time_t data.",
+    NULL
+    };
+  return HelpPages;
+}
+

    + +Note that the first line of each entry contains the actual command and its +parameters, while the following lines explain what the command does and what +the parameters (if any) mean. All lines of the explanation shall be indented +by exactly 4 blanks (no tabs), and none of them shall be longer than 79 characters +(to avoid messy output on 80 character wide terminals). The last entry in the +list must be NULL. +

    +The actual processing of SVDRP commands for a plugin is done in its +SVDRPCommand() function. +Here's an example of such a function, which implements the commands advertised in +the above help texts: + +

    +cString cPluginSvdrpdemo::SVDRPCommand(const char *Command, const char *Option, int &ReplyCode)
+{
+  if (strcasecmp(Command, "DATE") == 0) {
+     // we use the default reply code here
+     return DateString(time(NULL));
+     }
+  else if (strcasecmp(Command, "TIME") == 0) {
+     ReplyCode = 901;
+     if (*Option) {
+        if (strcasecmp(Option, "RAW") == 0)
+           return cString::sprintf("%ld\nThis is the number of seconds since the epoch\n"
+                                   "and a demo of a multi-line reply", time(NULL));
+        else {
+           ReplyCode = 504;
+           return cString::sprintf("Unknown option: \"%s\"", Option);
+           }
+        }
+     return TimeString(time(NULL));
+     }
+  return NULL;
+}
+

    + +The command is given to this function in the Command parameter, and any optional parameters +are given in the Option string. Command always points to an actual, non-empty string, while +Option may point to an empty string (it is never NULL, though). +

    +If a plugin doesn't implement the given command, it shall return NULL, and VDR will +automatically issue a proper error message. If it encounters an unknown or invalid +option, it shall set the ReplyCode to one of the codes defined in VDR/svdrp.c +and return a proper error message. +

    +The default ReplyCode is 900, and if the plugin doesn't care about reply +codes, it doesn't have to set it to anything else (unless there is an error, of +course). The codes in the range 901..999 are reserved for plugins that want +to use special reply codes. Any plugin can use any of these values and doesn't +have to coordinate this with any other plugin, since the caller knows which +plugin was called, and will therefore process the values according to the +particular plugin's definitions. +

    +The returned string may consist of several lines, separated by the newline character +('\n'). Each of these lines will be preceeded with the ReplyCode +when presenting them to the caller, and the continuation character ('-') +will be set for all but the last one. + +

    +

    Loading plugins into VDR

    Saddling up!

    @@ -1276,9 +1370,7 @@ public: }; cMyReceiver::cMyReceiver(int Pid) -
      :cReceiver(0, -1, Pid) -
    { } @@ -1735,7 +1827,7 @@ private: virtual void Action(void); public: cMyAudio(void); -
      +
      virtual void Play(const uchar *Data, int Length, uchar Id);
    virtual void Mute(bool On); -- cgit v1.2.3