Added cPlugin::Stop()

2023-10-10 13:36:52 +02:00 · 2005-01-30 14:23:01 +01:00 · 2005-01-30 14:23:01 +01:00 · 2bec1d5ca0
commit 2bec1d5ca0
parent a430f64252
6 changed files with 82 additions and 32 deletions
--- a/4
+++ b/4
@ -3345,3 +3345,7 @@ Video Disk Recorder Revision History
  Christian Jacobsen for reporting this one).
 - Fixed masking SubStreamType in cDevice::PlayPesPacket() (thanks to Werner Fink
  for pointing out this one).
+- The new function cPlugin::Stop() shall be used to stop any background activities
+  of a plugin. Previously this was done in the plugin's desctructor, but it is
+  better to do this in a dedicated function that can be called early when shutting
+  down.
--- a/PLUGINS.html
+++ b/PLUGINS.html
@ -14,18 +14,18 @@ Copyright &copy; 2004 Klaus Schmidinger<br>
 <a href="http://www.cadsoft.de/vdr">www.cadsoft.de/vdr</a>
 </center>
 <p>
-<!--X1.3.7--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
-Important modifications introduced in version 1.3.7 are marked like this.
-<!--X1.3.7--></td></tr></table>
-<!--X1.3.8--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
+<!--X1.3.8--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
 Important modifications introduced in version 1.3.8 are marked like this.
 <!--X1.3.8--></td></tr></table>
-<!--X1.3.18--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
+<!--X1.3.18--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
 Important modifications introduced in version 1.3.18 are marked like this.
 <!--X1.3.18--></td></tr></table>
-<!--X1.3.19--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<!--X1.3.19--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
 Important modifications introduced in version 1.3.19 are marked like this.
 <!--X1.3.19--></td></tr></table>
+<!--X1.3.20--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+Important modifications introduced in version 1.3.20 are marked like this.
+<!--X1.3.20--></td></tr></table>
 <p>
 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,6 +58,9 @@ structures and allows it to hook itself into specific areas to perform special a
 <li><a href="#Command line arguments">Command line arguments</a>
 <li><a href="#Command line help">Command line help</a>
 <li><a href="#Getting started">Getting started</a>
+<!--X1.3.20--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<li><a href="#Shutting down">Shutting down</a>
+<!--X1.3.20--></td></tr></table>
 <li><a href="#Main menu entry">Main menu entry</a>
 <li><a href="#User interaction">User interaction</a>
 <li><a href="#Housekeeping">Housekeeping</a>
@ -75,10 +78,8 @@ structures and allows it to hook itself into specific areas to perform special a
 <li><a href="#Receivers">Receivers</a>
 <li><a href="#Filters">Filters</a>
 <li><a href="#The On Screen Display">The On Screen Display</a>
-<!--X1.3.7--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
 <li><a href="#Skins">Skins</a>
 <li><a href="#Themes">Themes</a>
-<!--X1.3.7--></td></tr></table>
 <li><a href="#Devices">Devices</a>
 <li><a href="#Dolby Digital">Dolby Digital</a>
 <li><a href="#Remote Control">Remote Control</a>
@ -304,8 +305,11 @@ Constructing a plugin object shall not have any side effects or produce any outp
 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.
 <p>
-The <b>destructor</b> 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.
+The <b>destructor</b> has to clean up any data created by the plugin.
+<!--X1.3.20--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+Any threads the plugin may have created shall be stopped in the
+<a href="#Shutting down"><tt>Stop()</tt></a> function.
+<!--X1.3.20--></td></tr></table>
 <p>
 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.
@ -500,6 +504,25 @@ 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.

+<!--X1.3.20--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<a name="Shutting down"><hr><h2>Shutting down</h2>
+
+<center><i><b>Stop it, right there!</b></i></center><p>
+
+If a plugin performs any background tasks, it shall implement the function
+
+<p><table><tr><td bgcolor=#F0F0F0><pre>
+virtual void Stop(void);
+</pre></td></tr></table><p>
+
+in which it shall stop them.
+<p>
+The <tt>Stop()</tt> function will only be called if a previous call to the 
+<a href="#Getting started"><tt>Start()</tt></a> function of that plugin has
+returned <i>true</i>. The <tt>Stop()</tt> functions are called in the reverse order
+as the <a href="#Getting started"><tt>Start()</tt></a> functions were called.
+<!--X1.3.20--></td></tr></table>
+
 <a name="Main menu entry"><hr><h2>Main menu entry</h2>

 <center><i><b>Today's special is...</b></i></center><p>
@ -1021,7 +1044,7 @@ public:
 Take a look at the files <tt>player.h</tt> and <tt>dvbplayer.c</tt> to see how VDR implements
 its own player for the VDR recordings.
 <p>
-<!--X1.3.18--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
+<!--X1.3.18--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
 To play the actual data, the player needs to call its member function

 <p><table><tr><td bgcolor=#F0F0F0><pre>
@ -1044,7 +1067,7 @@ bool DevicePoll(cPoller &amp;Poller, int TimeoutMs = 0);

 to determine whether the device is ready for further data.
 <p>
-<!--X1.3.18--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
+<!--X1.3.18--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
 By default all audio track handling is done by the device a player is
 attached to.
 If the player can provide more than a single audio track, and has special
@ -1181,7 +1204,7 @@ public:
  };

 cMyReceiver::cMyReceiver(int Pid)
-<!--X1.3.19--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<!--X1.3.19--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
 :cReceiver(0, -1, Pid)
 <!--X1.3.19--></td></tr></table>
 {
@ -1267,7 +1290,6 @@ and will automatically detach itself from the <tt>cDevice</tt>.
 <p>
 See VDR/eit.c or VDR/pat.c to learn how to process filter data.

-<!--X1.3.7--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
 <a name="The On Screen Display"><hr><h2>The On Screen Display</h2>

 <center><i><b>Window to the world</b></i></center><p>
@ -1360,7 +1382,7 @@ public:
  virtual cSkinDisplayMenu *DisplayMenu(void);
  virtual cSkinDisplayReplay *DisplayReplay(bool ModeOnly);
  virtual cSkinDisplayVolume *DisplayVolume(void);
-<!--X1.3.18--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
+<!--X1.3.18--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
  virtual cSkinDisplayMessage *DisplayTrack(int NumTracks, const char * const *Tracks);
 <!--X1.3.18--></td></tr></table>
  virtual cSkinDisplayMessage *DisplayMessage(void);
@ -1382,7 +1404,7 @@ new cMySkin;
 in the <a href="#Getting started"><tt>Start()</tt></a> function of your plugin.
 Do not delete this object, it will be automatically deleted when the program ends.
 <p>
-<!--X1.3.8--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
+<!--X1.3.8--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
 In order to be able to easily identify plugins that implement a skin it is recommended
 that the name of such a plugin should be

@ -1441,7 +1463,6 @@ osd-&gt;DrawText(x, y, s, Theme.Color(clrButtonRedFg), Theme.Color(clrButtonRedB
 By default this will use the colors that have been defined in the respective
 <tt>THEME_CLR()</tt> line, but may be overwritten through user supplied theme
 files (see <tt>man vdr(5)</tt> for information about the format of a theme file).
-<!--X1.3.7--></td></tr></table>

 <a name="Devices"><hr><h2>Devices</h2>

@ -1493,7 +1514,7 @@ repectively.
 If the device can provide more than a single audio track, it can implement the
 following function to make them available:

-<!--X1.3.18--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
+<!--X1.3.18--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
 <p><table><tr><td bgcolor=#F0F0F0><pre>
 virtual void SetAudioTrackDevice(eTrackType Type);
 virtual int GetAudioChannelDevice(void);
@ -1584,7 +1605,6 @@ handle section data.
 <p>
 <b>On Screen Display</b>
 <p>
-<!--X1.3.7--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
 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 shall implement
 an "OSD provider" class, derived from <tt>cOsdProvider</tt>, which, when its <tt>CreateOsd()</tt>
@ -1618,7 +1638,6 @@ in any way. All it needs to make sure is that the OSD will be visible to the
 user - whether this goes through OSD facilities of the physical device (like
 a "full featured" DVB card) or through a graphics adapter that overlays its
 output with the video signal, doesn't matter.
-<!--X1.3.7--></td></tr></table>

 <p>
 <b>Initializing new devices</b>
--- a/8
+++ b/8
@ -12,7 +12,7 @@
 # See the main source file 'vdr.c' for copyright information and
 # how to reach the author.
 #
-# $Id: newplugin 1.17 2004/10/16 12:12:43 kls Exp $
+# $Id: newplugin 1.18 2005/01/30 13:50:05 kls Exp $

 $PLUGIN_NAME = $ARGV[0] || die "Usage: newplugin <name>\n";

@ -164,6 +164,7 @@ public:
  virtual bool ProcessArgs(int argc, char *argv[]);
  virtual bool Initialize(void);
  virtual bool Start(void);
+  virtual void Stop(void);
  virtual void Housekeeping(void);
  virtual const char *MainMenuEntry(void) { return MAINMENUENTRY; }
  virtual cOsdObject *MainMenuAction(void);
@ -207,6 +208,11 @@ bool cPlugin${PLUGIN_CLASS}::Start(void)
  return true;
 }

+void cPlugin${PLUGIN_CLASS}::Stop(void)
+{
+  // Stop any background activities the plugin shall perform.
+}
+
 void cPlugin${PLUGIN_CLASS}::Housekeeping(void)
 {
  // Perform any cleanup or other regular tasks.
--- a/plugin.c
+++ b/plugin.c
@ -4,7 +4,7 @@
 * See the main source file 'vdr.c' for copyright information and
 * how to reach the author.
 *
- * $Id: plugin.c 1.12 2004/12/19 12:05:28 kls Exp $
+ * $Id: plugin.c 1.13 2005/01/30 14:05:20 kls Exp $
 */

 #include "plugin.h"
@ -28,6 +28,7 @@ char *cPlugin::configDirectory = NULL;
 cPlugin::cPlugin(void) 
 {
  name = NULL;
+  started = false;
 }

 cPlugin::~cPlugin()
@ -60,6 +61,10 @@ bool cPlugin::Start(void)
  return true;
 }

+void cPlugin::Stop(void)
+{
+}
+
 void cPlugin::Housekeeping(void)
 {
 }
@ -322,6 +327,7 @@ bool cPluginManager::StartPlugins(void)
         Setup.OSDLanguage = Language;
         if (!p->Start())
            return false;
+         p->started = true;
         }
      }
  return true;
@ -366,15 +372,25 @@ cPlugin *cPluginManager::GetPlugin(const char *Name)
  return NULL;
 }

-void cPluginManager::Shutdown(bool Log)
+void cPluginManager::StopPlugins(void)
+{
+  for (cDll *dll = dlls.Last(); dll; dll = dlls.Prev(dll)) {
+      cPlugin *p = dll->Plugin();
+      if (p && p->started) {
+         isyslog("stopping plugin: %s", p->Name());
+         p->Stop();
+         p->started = false;
+         }
+      }
+}
+
+void cPluginManager::Shutdown(void)
 {
  cDll *dll;
  while ((dll = dlls.Last()) != NULL) {
-        if (Log) {
-           cPlugin *p = dll->Plugin();
-           if (p)
-              isyslog("stopping plugin: %s", p->Name());
-           }
+        cPlugin *p = dll->Plugin();
+        if (p)
+           isyslog("deleting plugin: %s", p->Name());
        dlls.Del(dll);
        }
 }
--- a/plugin.h
+++ b/plugin.h
@ -4,7 +4,7 @@
 * See the main source file 'vdr.c' for copyright information and
 * how to reach the author.
 *
- * $Id: plugin.h 1.7 2004/04/30 13:46:21 kls Exp $
+ * $Id: plugin.h 1.8 2005/01/30 14:03:48 kls Exp $
 */

 #ifndef __PLUGIN_H
@ -19,9 +19,11 @@

 class cPlugin {
  friend class cDll;
+  friend class cPluginManager;
 private:
  static char *configDirectory;
  const char *name;
+  bool started;
  void SetName(const char *s);
 public:
  cPlugin(void);
@ -35,6 +37,7 @@ public:
  virtual bool ProcessArgs(int argc, char *argv[]);
  virtual bool Initialize(void);
  virtual bool Start(void);
+  virtual void Stop(void);
  virtual void Housekeeping(void);

  virtual const char *MainMenuEntry(void);
@ -85,7 +88,8 @@ public:
  static bool HasPlugins(void);
  static cPlugin *GetPlugin(int Index);
  static cPlugin *GetPlugin(const char *Name);
-  void Shutdown(bool Log = false);
+  void StopPlugins(void);
+  void Shutdown(void);
  };

 #endif //__PLUGIN_H
--- a/vdr.c
+++ b/vdr.c
@ -22,7 +22,7 @@
 *
 * The project's page is at http://www.cadsoft.de/vdr
 *
- * $Id: vdr.c 1.200 2005/01/14 16:50:39 kls Exp $
+ * $Id: vdr.c 1.201 2005/01/30 14:15:50 kls Exp $
 */

 #include <getopt.h>
@ -928,6 +928,7 @@ int main(int argc, char *argv[])

 Exit:

+  PluginManager.StopPlugins();
  cRecordControls::Shutdown();
  cCutter::Stop();
  delete Menu;
@ -941,7 +942,7 @@ Exit:
  Setup.CurrentVolume  = cDevice::CurrentVolume();
  Setup.Save();
  cDevice::Shutdown();
-  PluginManager.Shutdown(true);
+  PluginManager.Shutdown();
  ReportEpgBugFixStats();
  if (WatchdogTimeout > 0)
     dsyslog("max. latency time %d seconds", MaxLatencyTime);