gnome-session r4858 - in branches/dbus_based: . gnome-session

[mccann svn gnome org]

Author: mccann
Date: Sun Jul 27 18:13:30 2008
New Revision: 4858
URL: http://svn.gnome.org/viewvc/gnome-session?rev=4858&view=rev

Log:
2008-07-27  William Jon McCann  <jmccann redhat com>

	* gnome-session/gsm-dbus-client.xml:
	Add docs for dbus-client.



Modified:
   branches/dbus_based/ChangeLog
   branches/dbus_based/gnome-session/gsm-dbus-client.xml

Modified: branches/dbus_based/gnome-session/gsm-dbus-client.xml
==============================================================================
--- branches/dbus_based/gnome-session/gsm-dbus-client.xml	(original)
+++ branches/dbus_based/gnome-session/gsm-dbus-client.xml	Sun Jul 27 18:13:30 2008
@@ -1,23 +1,120 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd";>
-<node>
+<node xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd";>
   <interface name="org.gnome.SessionManager.DBusClient">
 
     <method name="EndSessionResponse">
       <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
-      <arg name="is_ok" type="b" direction="in"/>
-      <arg name="reason" type="s" direction="in"/>
+      <arg name="is_ok" type="b" direction="in">
+        <doc:doc>
+          <doc:summary>Whether or not it is OK to preceed</doc:summary>
+        </doc:doc>
+      </arg>
+      <arg name="reason" type="s" direction="in">
+        <doc:doc>
+          <doc:summary>The reason string</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description>
+          <doc:para>This method should be used by the client in response to
+            the <doc:ref type="signal" to="org.gnome.SessionManager.DBusClient::QueryEndSession">QueryEndSession</doc:ref>
+            and <doc:ref type="signal" to="org.gnome.SessionManager.DBusClient::EndSession">EndSession</doc:ref> signals.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
     </method>
 
     <signal name="Stop">
+      <doc:doc>
+        <doc:summary>Stop client</doc:summary>
+        <doc:description>
+          The client should stop and remove itself from the session in
+          response to this signal.
+        </doc:description>
+      </doc:doc>
     </signal>
+
     <signal name="QueryEndSession">
-      <arg name="flags" type="u"/>
+      <arg name="flags" type="u">
+        <doc:doc>
+          <doc:summary>Flags</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description>
+          <doc:para>This signal is used to inform the client that the
+            session is about to end.  The client must respond by
+            calling
+            <doc:ref type="method" to="org.gnome.SessionManager.DBusClient.EndSessionResponse">EndSessionResponse</doc:ref>
+            within one second of the signal emission.
+          </doc:para>
+          <doc:para>
+            The flags may include:
+            <doc:list>
+              <doc:item>
+                <doc:term>1</doc:term>
+                <doc:definition>Logout is forced.
+                  <doc:ref type="method" to="org.gnome.SessionManager.DBusClient.EndSessionResponse">EndSessionResponse</doc:ref>
+                reason and any inhibit from client will be
+                ignored.</doc:definition>
+              </doc:item>
+            </doc:list>
+          </doc:para>
+          <doc:para>
+            If the client responds with an EndSessionResponse is-ok
+            argument equal to FALSE and a reason then this reason may
+            be displayed to the user.
+          </doc:para>
+          <doc:para>
+            The client must not attempt to perform any actions or
+            interact with the user in response to this signal.  Any
+            actions required for a clean shutdown should take place in
+            response to the
+            <doc:ref type="signal" to="org.gnome.SessionManager.DBusClient::EndSession">EndSession</doc:ref> signal.
+          </doc:para>
+          <doc:para>
+            The client should limit operations until either a
+            <doc:ref type="signal" to="org.gnome.SessionManager.DBusClient::EndSession">EndSession</doc:ref>
+            <doc:ref type="signal" to="org.gnome.SessionManager.DBusClient::CancelEndSession">CancelEndSession</doc:ref>
+            signal is received.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
     </signal>
+
     <signal name="EndSession">
-      <arg name="flags" type="u"/>
+      <arg name="flags" type="u">
+        <doc:doc>
+          <doc:summary>Flags</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description>
+          <doc:para>This signal is used to inform the client that the
+            session is about to end.  The client must respond by
+            calling
+            <doc:ref type="method" to="org.gnome.SessionManager.DBusClient.EndSessionResponse">EndSessionResponse</doc:ref>
+            within ten seconds of the signal emission.
+          </doc:para>
+          <doc:para>
+            The client must not attempt to interact with the user in
+            response to this signal.  The application will be given a
+            maxium of ten seconds to perform any actions required for
+            a clean shutdown.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
     </signal>
+
     <signal name="CancelEndSession">
+      <doc:doc>
+        <doc:description>
+          This signal indicates to the client that a previous emission of
+          <doc:ref type="signal" to="org.gnome.SessionManager.DBusClient::QueryEndSession">QueryEndSession</doc:ref>
+          has been cancelled.  The client should resume normal operations.
+        </doc:description>
+      </doc:doc>
     </signal>
 
   </interface>