From e86a92f42379e5beeb1fdc37b8bfd2a727f8a13f Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Thu, 4 Feb 2010 23:40:19 -0500
Subject: [PATCH 21/22] Add docs

Add a section to the design docs that explains the shutdown api.
---
 doc/dbus/ck-design.xml |   41 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 41 insertions(+), 0 deletions(-)

diff --git a/doc/dbus/ck-design.xml b/doc/dbus/ck-design.xml
index 8aca968..39da991 100644
--- a/doc/dbus/ck-design.xml
+++ b/doc/dbus/ck-design.xml
@@ -29,6 +29,44 @@ The Session will remain open until the Session Leader disconnects from the D-Bus
   </sect1>
 
   <sect1>
+    <title>Shutdown Operation</title>
+    <para>
+      Generally, a user sitting at the local console should be allowed to shut
+      down the machine; after all, he or she can just hit the power button
+      anyway. However, there are circumstances under which shutting down the
+      machine might not be advisable:
+      <itemizedlist>
+        <listitem><para>Multiple users might have active or inactive sessions</para></listitem>
+        <listitem><para>A system service might perform an uninterruptible operation,
+          such as a disk backup, a software update, etc.</para></listitem>
+      </itemizedlist>
+      Under these circumstances, ConsoleKit will require elevated privileges
+      before it allows the shutdown to proceed.
+    </para>
+    <para>
+      In order to allow an orderly shutdown in the presence of multiple
+      sessions, the shutdown operation has to tie into the session lifecycle
+      as described in the org.gnome.SessionManager documentation:
+      <orderedlist>
+        <listitem><para>User initiates Shutdown operation</para></listitem>
+        <listitem><para>Session leader calls QueryStop() on the ConsoleKit manager object</para></listitem>
+        <listitem><para>ConsoleKit emits the QueryStop signal on all session objects</para></listitem>
+        <listitem><para>All sessions enter their QueryEnd phase</para></listitem>
+        <listitem><para>All session leaders respond back with StopResponse()</para></listitem>
+        <listitem><para>The initial QueryStop() call returns</para></listitem>
+        <listitem><para>Session leader uses GetSessions() and GetInhibitors() to assemble information to present to the user, in addition to its own inhibitors. Depending on the can_proceed value returned by QueryStop(), the dialog will offer the user to proceed with the shutdown operation</para></listitem>
+        <listitem><para>Assuming the user chooses to proceed, the session leader calls Stop() or Restart()</para></listitem>
+        <listitem><para>ConsoleKit sets the Stopping property</para></listitem>
+        <listitem><para>ConsoleKit verifies that the user has the necessary privileges</para></listitem>
+        <listitem><para>ConsoleKit emits the Stop signal on all session objects</para></listitem>
+        <listitem><para>All sessions enter their End phase</para></listitem>
+        <listitem><para>All session leaders respond back with StopResponse()</para></listitem>
+        <listitem><para>ConsoleKit shuts down the machine</para></listitem>
+      </orderedlist>
+    </para>
+  </sect1>
+
+  <sect1>
     <title>Expected Usage</title>
     <para>Use of this service will usually follow one of the following patterns:</para>
 
@@ -92,6 +130,9 @@ The Session will remain open until the Session Leader disconnects from the D-Bus
         <listitem>
           <simpara>To know if the system is currently being used.</simpara>
         </listitem>
+        <listitem>
+          <simpara>To inhibit shutdown during uninterruptible operations.</simpara>
+        </listitem>
       </orderedlist>
     </sect2>
 
-- 
1.6.6