Implemented cPlugin::Active()

PLUGINS.html

@@ -14,18 +14,18 @@ Copyright &copy; 2006 Klaus Schmidinger<br>
 <a href="http://www.cadsoft.de/vdr">www.cadsoft.de/vdr</a>
 </center>
 <p>
-<!--X1.3.30--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
-Important modifications introduced in version 1.3.30 are marked like this.
-<!--X1.3.30--></td></tr></table>
-<!--X1.3.31--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
+<!--X1.3.31--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
 Important modifications introduced in version 1.3.31 are marked like this.
 <!--X1.3.31--></td></tr></table>
-<!--X1.3.37--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
+<!--X1.3.37--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
 Important modifications introduced in version 1.3.37 are marked like this.
 <!--X1.3.37--></td></tr></table>
-<!--X1.3.38--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<!--X1.3.38--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
 Important modifications introduced in version 1.3.38 are marked like this.
 <!--X1.3.38--></td></tr></table>
+<!--X1.3.47--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+Important modifications introduced in version 1.3.46 are marked like this.
+<!--X1.3.47--></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.
@@ -62,14 +62,15 @@ structures and allows it to hook itself into specific areas to perform special a
 <li><a href="#Main menu entry">Main menu entry</a>
 <li><a href="#User interaction">User interaction</a>
 <li><a href="#Housekeeping">Housekeeping</a>
+<!--X1.3.47--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<li><a href="#Activity">Activity</a>
+<!--X1.3.47--></td></tr></table>
 <li><a href="#Setup parameters">Setup parameters</a>
 <li><a href="#The Setup menu">The Setup menu</a>
 <li><a href="#Configuration files">Configuration files</a>
 <li><a href="#Internationalization">Internationalization</a>
-<!--X1.3.30--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
 <li><a href="#Custom services">Custom services</a>
-<!--X1.3.30--></td></tr></table>
-<!--X1.3.31--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
+<!--X1.3.31--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
 <li><a href="#SVDRP commands">SVDRP commands</a>
 <!--X1.3.31--></td></tr></table>
 <li><a href="#Loading plugins into VDR">Loading plugins into VDR</a>
@@ -609,6 +610,44 @@ interaction is possible. If a specific action takes longer than a few seconds,
 the plugin should launch a separate thread to do this.
 </b>
 
+<!--X1.3.47--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<a name="Activity"><hr><h2>Activity</h2>
+
+<center><i><b>Now is not a good time!</b></i></center><p>
+
+If a plugin is running a background task that should be finished before shutting
+down the system, it can implement the function
+
+<p><table><tr><td bgcolor=#F0F0F0><pre>
+virtual cString Active(void);
+</pre></td></tr></table><p>
+
+which shall return an empty string if it is ok to shut down, and a proper message
+if not:
+
+<p><table><tr><td bgcolor=#F0F0F0><pre>
+cString cDoSomethingPlugin::Active(void)
+{
+  if (busy)
+     return tr("Doing something");
+  return NULL;
+}
+</pre></td></tr></table><p>
+
+The message should be short and should indicate what is currently going on.
+It will be presented to the user as a confirmation message, followed by a
+hyphen and a "shut down anyway?" prompt, as in
+<p>
+<b>Doing something - shut down anyway?</b>
+<p>
+All plugins will be queried, and the first one that returns a non empty
+string will cause the confirmation message to be shown. If the user confirms
+the prompt by pressing the "Ok" button, the rest of the plugins will also
+be queried, and further prompts may show up. If all prompts have been confirmed,
+the shutdown will take place. As soon as one prompt is not confirmed, no
+further plugins will be queried and no shutdown will be done.
+<!--X1.3.47--></td></tr></table>
+
 <a name="Setup parameters"><hr><h2>Setup parameters</h2>
 
 <center><i><b>Remember me...</b></i></center><p>
@@ -864,7 +903,6 @@ Texts are first searched for in the <i>Phrases</i> 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.
 
-<!--X1.3.30--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
 <a name="Custom services"><hr><h2>Custom services</h2>
 
 <center><i><b>What can I do for you?</b></i></center><p>
@@ -933,9 +971,7 @@ To send a message to all plugins, a plugin can call the function
 <tt>cPluginManager::CallAllServices()</tt>. This function returns <tt>true</tt> if
 any plugin handled the request, or <tt>false</tt> if no plugin handled the request.
 
-<!--X1.3.30--></td></tr></table>
-
-<!--X1.3.31--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
+<!--X1.3.31--><table width=100%><tr><td bgcolor=#0000AA>&nbsp;</td><td width=100%>
 <a name="SVDRP commands"><hr><h2>SVDRP commands</h2>
 
 <center><i><b>Infinite Diversity in Infinite Combinations</b></i></center><p>
@@ -1262,7 +1298,7 @@ public:
   cMyControl(void);
   virtual ~cMyControl();
   virtual void Hide(void);
-<!--X1.3.38--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<!--X1.3.38--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
   virtual cOsdObject *GetInfo(void);
 <!--X1.3.38--></td></tr></table>
   virtual eOSState ProcessKey(eKeys Key);
@@ -1294,7 +1330,7 @@ A derived <tt>cControl</tt> <b>must</b> implement the <tt>Hide()</tt> function,
 it has to hide itself from the OSD, in case it uses it. <tt>Hide()</tt> may be called at
 any time, and it may be called even if the <tt>cControl</tt> is not visible at the moment.
 <p>
-<!--X1.3.38--><table width=100%><tr><td bgcolor=#FF0000>&nbsp;</td><td width=100%>
+<!--X1.3.38--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
 The <tt>GetInfo()</tt> function is called when the user presses the <tt>Info</tt> button,
 and shall return a pointer to a <tt>cOsdObject</tt> that contains information
 about the currently played programme. The caller takes ownership of the returned
@@ -1522,7 +1558,7 @@ with the full required resolution. Only if this fails shall it use alternate
 areas. Drawing areas are always rectangular and may not overlap (but do not need
 to be adjacent).
 
-<!--X1.3.37--><table width=100%><tr><td bgcolor=#AA0000>&nbsp;</td><td width=100%>
+<!--X1.3.37--><table width=100%><tr><td bgcolor=#00AA00>&nbsp;</td><td width=100%>
 <p>
 Directly accessing the OSD is only allowed from the foreground thread, which
 restricts this to a <tt>cOsdObject</tt> returned from the plugin's <tt>MainMenuAction()</tt>