Re: Session Management Proposal

[Ray Strode <halfline hawaii rr com>]

Hi,

Attached is the latest version of the DSME. As always,
improvements appreciated.

It is also available as HTML here:

http://www.grokthecruft.org/dsme/

If there are no major concerns with this after 2 weeks,
then I'd like to put it up on freedesktop.org.  That
should give those on vacation for the holidays time to
look it over and make comments or suggestions if
required.

Thanks.

--Ray

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
<article id="index">
  <articleinfo>
    <title>Desktop Session Management Extensions</title>
    <releaseinfo>Version 0.7</releaseinfo>
    <date>1 January 2003</date>
    <authorgroup>
      <author>
	    <firstname>Ray</firstname>
	    <surname>Strode</surname>
        <affiliation>
            <address>
              <email>halfline hawaii rr com</email>
            </address>
        </affiliation>
      </author>
    </authorgroup>
  </articleinfo>

  <sect1 id="overview">
    <title>Overview</title>
    <para>
      The X Session Management Protocol (XSMP) specification
      introduces a protocol between a session manager and its
      clients.  The protocol gives the session manager control
      over when clients are started, stopped, and told to save
      and restore state.  While the basic protocol presented in
      the XSMP specification is useful, desktop environments
      require certain features not specified in the XSMP to be
      fully functional.
    </para>
    <para>
      This document serves to extend, clarify and when necessary
      override the XSMP for improved session management within
      desktop environments through the Desktop Session Management
      Extensions (DSME).  The document will primarily extend the 
      XSMP through the use of newly defined properties.  These
      properties should be treated similarly to the properties
      that are defined in section 11 of the XSMP.  Namely, each
      property, regardless of type, should be packed into a
      LISTofARRAY8 when sent to the session manager.  Also,
      unless explicitly stated otherwise, all properties should
      be first set after the client sends a
      <command>RegisterClient</command> message but before the
      client sends a <command>SaveYourselfDone</command> message.
    </para>
  </sect1>

  <sect1 id="definitions">
    <title>Definitions</title>
    <variablelist>
      <varlistentry>
	    <term>Active Session</term>
        <listitem>
          <para>
            An <firstterm>active session</firstterm> is the
            collection of application instances currently loaded
            and available to the user.  
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Application-specific State</term>
        <listitem>
          <para>
            One type of state associated with an application
            instance is <firstterm>application-specific
            state</firstterm>, which is information about the
            number of currently opened windows, what documents
            are open, and other information that is important for
            presenting to the user a consistent interface across
            login sessions.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Client</term>
        <listitem>
          <para>
            In the context of application-session manager
            interaction, a <firstterm>client</firstterm> is a
            session-managed application.  It connects to the
            session manager, identifies itself, and listens for
            commands (See the XSMP).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Desktop Environment</term>
        <listitem>
          <para>
            For this document a <firstterm>desktop
            environment</firstterm> is a collection of integrated
            applications and libraries written to provide an
            intuitive interface to the computer for users.
            Commonly, desktop environments have panels,
            desktop icons, and window managers.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Desktop Session Manager</term>
        <listitem>
          <para>
            A <firstterm>desktop session manager</firstterm> is a
            session manager (as defined by the XSMP) that is
            designed for managing clients in a desktop
            environment.  Desktop session managers are usually
            written specifically for a particular desktop
            environment and interact with users using facilities
            provided by that desktop environment.  It plays a 
            very important role for a desktop environment.  
            Namely, it serves to start all applications when the 
            user first logs in, to instruct all applications 
            to save their associated state, and also to terminate
            the active session when the user is ready to log out.

          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Document-specific State</term>
        <listitem>
          <para>
            One type of state associated with an application
            instance is <firstterm>document-specific
            state</firstterm>, which is the currently open
            documents.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Session</term>
        <listitem>
          <para>
            A <firstterm>session</firstterm> is a collection of
            saved instances of applications.  Each application
            instance has saved state that is specific to the
            session.  The session manager controls which session
            is loaded and made active on login by some
            implementation specific means.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect1>
  
  <sect1 id="identification">
    <title>Client Identification</title>
    <para>
      The XSMP provides mechanisms for clients to identify
      themselves to the session manager, but the mechanisms
      provided only give low-level representations of the
      clients.  There is no appropriate means of displaying the
      client to the user.  This section seeks to provide a means
      from which a desktop session manager can represent clients
      to the user through both localized client names and
      graphical icons.
    </para>
    <para>
      Some desktop environments have certain programs which
      provide integral functionality for the environment&apos;s
      proper operation. These programs need to be treated
      specially.  This section also seeks to provide a means for
      clients to identify themselves as special.
    </para>
    <sect2 id="client_name">
      <title>Localized Client Names</title>
      <para>
        Clients that support the DSME should set the
        <varname>_DSME_Name</varname> property to a preferred
        human-readable, localized application name encoded in
        UTF-8.  <varname>_DSME_Name</varname> is an ARRAY8
        property.
      </para>
    </sect2>
    <sect2 id="client_icon">
      <title>Client Icon</title>
      <para>
        Clients that support the DSME should set the
        <varname>_DSME_Icon</varname> property to a preferred icon
        name, which should be looked up by the desktop session
        manager using the procedure described in the Icon Theme
        Specification.  <varname>_DSME_Icon</varname> is an ARRAY8
        property.
      </para>
    </sect2>
    <sect2 id="client_role">
      <title>Client Role</title>
      <para>
        Clients that support the DSME may set the
        <varname>_DSME_Roles</varname> property to reflect their
        roles in the desktop environment.  If a client chooses
        not to set the <varname>_DSME_Roles</varname> property the
        desktop session manager should assume the client has an
        implicit role of <literal>_DSME_RoleNormal</literal>.
        <varname>_DSME_Roles</varname> is a CARD8 property.  A
        client can specify more than one role by performing a
        bitwise <command>OR</command> operation on the possible
        role values:
        <itemizedlist>
            <listitem>
                <para>
                    <literal>_DSME_RoleNormal</literal>
                    (<literal>0x0</literal>).  All clients that
                    do not set any other role may set this role.
                    A client with only this role set should not
                    be treated specially by the session manager.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_RoleWindowManager</literal>
                    (<literal>0x1</literal>).  Window managers
                    must set this role.  Desktop session managers
                    must only allow one client per session with
                    this role set.  In the event that more than
                    one client sets this role during login then
                    the client with lowest priority should be
                    loaded.  If a client attempts to register
                    with the session manager in the middle of an
                    active session and another client is already
                    running with this role set, then the desktop
                    session manager should send a
                    <command>Die</command> message to the newer
                    client.  If a session manager detects that a
                    session is lacking a client with this role
                    set, then it may optionally start a suitable
                    client.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_RoleDesktopHandler</literal>
                    (<literal>0x2</literal>). Programs that take
                    control of desktop handling (like some file
                    managers) must set this role. Desktop session
                    managers must only allow one client per
                    session with this role set.  In the event
                    that more than one client sets this role
                    during login then the client with lowest
                    priority should be loaded.  If a client
                    attempts to register with the session manager
                    in the middle of an active session and
                    another client is already running with this
                    role set, then the desktop session manager
                    should send a <command>Die</command> message
                    to the newer client.  If a session manager
                    detects that a session is lacking a client
                    with this role set, then it may optionally
                    start a suitable client.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_RolePanel</literal>
                    (<literal>0x4</literal>).  Panels must set
                    this role.  If a session manager detects that
                    a session is lacking a client with this role
                    set, then it may optionally start a suitable
                    client.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_RoleDesktopComponent</literal>
                    (<literal>0x8</literal>).  All resident
                    components of the desktop not specified by
                    other other role types in this document
                    should set this role.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_RoleSetup</literal>
                    (<literal>0x10</literal>).  Programs that
                    load user preferences (like desktop
                    backgrounds, audio settings, etc) should set
                    this role.
                </para>
            </listitem>
        </itemizedlist>
      </para>
    </sect2>
  </sect1>
  <sect1 id="load_order">
    <title>Client Load Order</title>
    <para>
      The order in which clients are started on login is often
      important for a proper user experience.  For instance,
      under normal circumstances the window manager needs to be
      loaded before clients with managed windows in order to
      prevent the flickering of window decorations being added to
      already mapped windows.  Also, other intrinsic components
      of the desktop should normally be started before user
      applications.  This section seeks to provide a mechanism
      for controlling the order in which clients are loaded on
      login.  This section does not address situations where the
      user is already logged in and there is an active session
      loaded.
    </para>
    <sect2 id="client_priority">
      <title>Client Priority</title>
      <para>
        Clients that support the DSME may set the
        <varname>_DSME_Priority</varname> property to reflect 
        when they would like to be launched on user login.
        <varname>_DSME_Priority</varname> is a CARD8 property.
        Clients that set this property to low values should be
        started before clients that set this property to higher
        values.  If a client chooses not to set this property,
        then the session manager should assume an implicit
        priority for the client based on the client&apos;s role:  
        </para>
        <informaltable>
            <tgroup cols="2">
              <thead>
                <row>
                  <entry>Client Role</entry> 
                  <entry>Implied Client Priority</entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>
                    <literal>_DSME_RoleWindowManager</literal>
                  </entry>
                  <entry><literal>10</literal></entry>
                </row>
                <row>
                  <entry>
                    <literal>_DSME_RoleSetup</literal>
                  </entry>
                  <entry><literal>20</literal></entry>
                </row>
                <row>
                  <entry>
                    <literal>_DSME_RoleDesktopHandler</literal>
                  </entry>
                  <entry><literal>30</literal></entry>
                </row>
                <row>
                  <entry>
                    <literal>_DSME_RolePanel</literal>
                  </entry>
                  <entry><literal>40</literal></entry>
                </row>
                <row>
                  <entry>
                    <literal>_DSME_RoleDesktopComponent</literal>
                  </entry>
                  <entry><literal>40</literal></entry>
                </row>
                <row>
                  <entry>
                    <literal>_DSME_RoleNormal</literal>
                  </entry>
                  <entry><literal>50</literal></entry>
                </row>
              </tbody>
            </tgroup>
        </informaltable>
        <para>
          In the event that more than one client sets this
          property to the same value the order that these clients
          are loaded is undefined.  However, the desktop session
          manager may choose to look at each client&apos;s role
          in determining which client to load first.
        </para>
    </sect2>
  </sect1>
  <sect1 id="session_saving">
  <title>Session Saving and Logging Out</title>
  <para>
    Often individual application instances in desktop
    environments will have two distinct types of state.  The
    first type of state is application-specific state and the
    other is document-specific state.
  </para>
  <para>
    Application-specific state is information about the number of
    currently opened windows, what documents are open, and other
    information that is important for presenting to the user a
    consistent interface across login sessions.  This type of
    information is important for a seamless user experience, but
    it is not the type of information that users should be able
    to collectively save or discard on a per-application basis.
  </para>
  <para>
    When a user is done using the computer, if that user chooses
    to save the active session, then the application-specific
    state of all currently running application instances should
    be transparently saved for the user.  On the other hand, if
    the user chooses not to save the current session on log out,
    then the application-specific state of all currently running
    application instances should be discarded and when the user
    logs in again the most recently saved session and all its
    associated application-specific state should be loaded.
  </para>  
  <para>
    While application-specific state should be handled
    transparently for the user, document-specific state may
    involve the user.  Document-specific state is the actual open
    documents themselves.  It is much more tangible to the user
    than application-specific state because many users are
    accustomed to directly controlling what goes into their
    documents.  This control includes, for instance, what gets
    typed into the documents, but more importantly for this
    section, when the documents are saved.
  </para>
  <para>
    When the user is done using the computer and attempts to log
    out, all open and unsaved documents may be optionally saved
    or discarded on a per-document basis based on individual
    decisions from the user.  This process may happen regardless
    of whether the user chose to save the active session or not.
  </para>
  <sect2 id="saveyourself_semantics">
    <title>
      <command>SaveYourself</command> Message Semantics
    </title>
    <para>
      When desktop session managers send the
      <command>SaveYourself</command> message to clients the
      <literal>Local</literal> save type indicates that clients
      must save their application-specific state.  The
      <literal>Global</literal> save type indicates that clients
      must save their document-specific state.  In the event that
      save type is <literal>Both</literal> the clients should
      first save document-specific state and then save
      application-specific state.  
    </para>
    <para>
      When the user logs out, the session manager must send a
      <command>SaveYourself</command> message to all clients. If
      the user chose to save the active session when initiating
      the Logout request, then the save type should be
      <literal>Both</literal>.  Otherwise, the save type should
      be <literal>Global</literal>.
    </para>
     <para>
      While a DSME-compliant client must only save
      application-specific state if it receives a
      <command>SaveYourself</command> message with the
      <literal>Local</literal> or <literal>Both</literal> save
      type, it is possible that non DSME-compliant clients will
      save application-specific state for the
      <literal>Global</literal> save type.  For this reason, the
      session manager should run the
      <command>DiscardCommand</command> commands of all relevent
      clients following any <command>SaveYourself</command>
      message with save type <literal>Global</literal>.  If the
      <command>SaveYourself</command> message was the result of a
      <command>SaveYourselfRequest</command> message with 
      <varname>global</varname> set to <literal>False</literal> 
      then the only relevent client is the client that initiated 
      the <command>SaveYourselfRequest</command> message.  In all
      other cases, the <command>DiscardCommand</command> command
      of every client should be run.
    </para>
    <sect3 id="session_shutdown">
      <title>Session Shutdown</title> 
      <para>
        A client that wishes to terminate the active session
        should set the <varname>_DSME_ShutdownType</varname>
        property with the value of the requested method of
        session termination and then immediately send a
        <command>SaveYourselfRequest</command> with 
        <varname>shutdown</varname> set to 
        <literal>True</literal>.
        <varname>_DSME_ShutdownType</varname> is a CARD8 
        property, which can be set to one of several possible 
        values:
        <itemizedlist>
            <listitem>
                <para>
                    <literal>_DSME_ShutdownTypeDefault</literal>
                    (<literal>0x0</literal>).  The session
                    manager should terminate the active session
                    in an implementation-dependent manner.  The
                    session manager may choose to terminate the
                    active session using a user-configurable
                    setting or by remembering the previously used
                    shutdown type.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_ShutdownTypeLogout</literal>
                    (<literal>0x1</literal>).  The session
                    manager should log out of the active session.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_ShutdownTypeReboot</literal>
                    (<literal>0x2</literal>).  The session
                    manager should reboot the computer.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>_DSME_ShutdownTypeHalt</literal>
                    (<literal>0x4</literal>).  The session
                    manager should halt the computer.
                </para>
            </listitem>
        </itemizedlist>
        When the session manager receives a
        <command>SaveYourselfRequest</command> with 
        <varname>shutdown</varname> set to 
        <literal>True</literal> it should terminate the session 
        in the manner specified by initiating client&apos;s
        <varname>_DSME_ShutdownType</varname> property provided 
        that the session manager supports the shutdown type.  If 
        the initiating client did not set the
        <varname>_DSME_ShutdownType</varname> property, then the
        session manager should assume an implied shutdown type of
        <literal>_DSME_ShutdownTypeLogout</literal> for
        compatibility.  If the client set the shutdown type to
        an unsupported value then the session manager should
        cancel the shutdown request.
      </para>
      <para>
        The session manager should inform its clients what 
        shutdown types it supports with
        <varname>_DSME_AvailableShutdownTypes</varname>,
        which is a CARD8 property whose value is the bitwise
        <command>OR</command> of all supported shutdown types. 
        The session manager should set this property on all
        new clients before sending the clients their 
        <command>RegisterClientReply</command> message.  The
        session manager must not change this property after 
        initially setting it. Clients should assume an implied
        value of <literal>_DSME_ShutdownTypeLogout</literal> if
        the session manager fails to set 
        <varname>_DSME_AvailableShutdownTypes</varname> for 
        compatibility.   
      </para>
      <para>
        When clients send the 
        <command>SaveYourselfRequest</command> message with
        <varname>shutdown</varname> set to 
        <literal>True</literal> the <varname>fast</varname>
        and <varname>interact-style</varname> arguments should
        specify the requested level of user interaction.  
      </para>
      <para>
        If <varname>fast</varname> is set to 
        <literal>False</literal> the session manager may display
        a shutdown dialog asking the user how to proceed.  In
        this case <varname>_DSME_ShutdownType</varname> may serve
        as a suggestion that can be overrided by the user.
      </para>
      <para>
        If <varname>fast</varname> is set to
        <literal>True</literal> the session manager should not
        display a shutdown dialog and instead should immediately
        process the client shutdown request.
      </para>
      <para>
        If <varname>interact-style</varname> is set to
        <literal>None</literal> then when the session manager
        sends the terminating <command>SaveYourself</command>
        message to each of its clients it should instruct clients
        not to interact with the user before saving
        document-specific state by setting
        <varname>interact-style</varname> to
        <literal>None</literal>.  In particular, this means that
        clients should save all open documents automatically
        without asking the user for confirmation and clients
        should ignore any errors resulting from failed save
        attempts.
      </para>
      <para>
        If <varname>interact-style</varname> is set to
        <literal>Errors</literal> then when the session manager
        sends the terminating <command>SaveYourself</command>
        message to each of its clients it should instruct clients
        not to interact with the user before saving
        document-specific state by setting
        <varname>interact-style</varname> to
        <literal>None</literal> or <literal>Errors</literal>.  In
        particular, this means that clients should save all open
        documents automatically without asking the user for
        confirmation.  If the session manager sets
        <varname>interact-style</varname> to
        <literal>None</literal> then clients should ignore any
        errors resulting from failed save attempts.  If the
        session manager sets <varname>interact-style</varname> to
        <literal>Errors</literal> then clients should present
        errors resulting from failed save attempts to the user,
        giving the user the option to cancel the shutdown
        process.
      </para>
      <para>
        If <varname>interact-style</varname> is set to
        <literal>Any</literal> then when the session manager
        sends the terminating <command>SaveYourself</command>
        message to each of its clients it may instruct clients to
        interact with the user before saving document-specific
        state by setting <varname>interact-style</varname> to
        <literal>Any</literal>.  In particular, this means that
        clients should present save-confirmation dialogs before
        saving document-specific state and clients should present
        errors resulting from failed save attempts to the user,
        giving the user the option to cancel the shutdown
        process.  Optionally, the session manager may choose not
        to set <varname>interact-style</varname> to
        <literal>Any</literal> and instead set
        <varname>interact-style</varname> to
        <literal>None</literal> or <literal>Errors</literal>.  If
        the session manager sets
        <varname>interact-style</varname> to
        <literal>None</literal> then clients should ignore any
        errors resulting from failed save attempts.  If the
        session manager sets <varname>interact-style</varname> to
        <literal>Errors</literal> then clients should present
        errors resulting from failed save attempts to the user,
        giving the user the option to cancel the shutdown
        process.
      </para>
    </sect3>
  </sect2>
  </sect1>
  <appendix id="changes">
    <title>Change History</title>
    <formalpara>
      <title>Version 0.7, 3 January 2003, Ray Strode</title>
      <para>       
        <itemizedlist>
          <listitem>
            <para>
              Removed 
              <varname>_DSME_ShutdownInteractMode</varname> and
              clarified the purpose of <varname>fast</varname>
              and <varname>interact-mode</varname> for 
              <command>SaveYourselfRequest</command> and
              <command>SaveYourself</command> messages from 
              discussion with Oswald Buddenhagen.  
            </para>
          </listitem>
        </itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.6, 31 December 2003, Ray Strode</title>    
      <para>
        <itemizedlist>
          <listitem>
            <para>
              Added <varname>_DSME_ShutdownType</varname> from
              suggestion by Mark Finlay.
            </para>
          </listitem>
          <listitem>
            <para>
              Alluded to section 11 of the XSMP for clarification 
              of the nature of the properties from suggestion by 
              Olivier Chapuis.
            </para>
          </listitem>
          <listitem>
            <para>
              Added <literal>_DSME_ShutdownTypeDefault</literal>
              and added &quot;for compatibility&quot; to 
              explanation of implicit shutdown type from 
              suggestion by Oswald Buddenhagen.
            </para>
          </listitem>
          <listitem>
            <para>
              Added <varname>_DSME_ShutdownInteractMode</varname>
              property from suggestion by Oswald Buddenhagen.
            </para>
          </listitem>
          <listitem>
            <para>
              Changed quotations and apostrophes to entities.
              Added more semantic markup.
            </para>
          </listitem>
          <listitem>
            <para>
              Changed <literal>_DSME_Role_DesktopManager</literal>
              to <literal>_DSME_Role_DesktopHandler</literal> to
              prevent confusion from desktop managers like xdm,
              kdm, and gdm.
            </para>
          </listitem>
          <listitem>
            <para>
              Added
              <varname>_DSME_AvailableShutdownTypes</varname> so
              clients can query the session manager for available
              shutdown types.
            </para>
          </listitem>
          <listitem>
            <para>
              Changed prefix to _DSME_ instead of _NET_ to 
              prevent confusion with EWMH spec by suggestion from
              Olivier Chapuis.
            </para>
          </listitem>
          <listitem>
            <para>
              Fixed Typos.
            </para>
          </listitem>
        </itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.5, 28 December 2003, Ray Strode</title>    
      <para>
      Initial Draft.
      </para>
    </formalpara>
  </appendix>
</article>