"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"

[

 %defs;

]>

<book id="xsmp">

<bookinfo>

   <title>X Session Management Protocol</title>

   <subtitle>X Consortium Standard</subtitle>

   <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>

   <releaseinfo>Version 1.0</releaseinfo>

   <authorgroup>

      <author>

         <firstname>Mike</firstname><surname>Wexler</surname>

         <affiliation><orgname>Kubota Pacific Computer, Inc</orgname></affiliation>

      </author>

   </authorgroup>

   <copyright>

     <year>1992</year><year>1993</year><year>1994</year><year>2002</year>

     <holder>The Open Group</holder>

   </copyright>

   <legalnotice>

     <para>

Permission is hereby granted, free of charge, to any person

obtaining a copy of this software and associated documentation files

(the “Software”), to deal in the Software without

restriction, including without limitation the rights to use, copy,

modify, merge, publish, distribute, sublicense, and/or sell copies of

the Software, and to permit persons to whom the Software is furnished

to do so, subject to the following conditions:

     </para>

     <para>

The above copyright notice and this permission notice shall be

included in all copies or substantial portions of the Software.

     </para>

     <para>

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY

OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE

WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY

CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,

TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

     </para>

     <para>

Except as contained in this notice, the name of the X Consortium

shall not be used in advertising or otherwise to promote the sale, use

or other dealings in this Software without prior written authorization

from the X Consortium.

     </para>

     <para>

X Window System is a trademark of The Open Group.

     </para>

   </legalnotice>

   <abstract>

     <para>

This document specifies a protocol that facilitates the management of

groups of client applications by a session manager.  The session

manager can cause clients to save their state, to shut down, and to be

restarted into a previously saved state.  This protocol is layered on

top of the X.Org ICE protocol.

     </para>

   </abstract>

</bookinfo>

<chapter id='Acknowledgments'>

  <title>Acknowledgments</title>

  <para>

First I would like to thank the entire ICCCM and Intrinsics

working groups for the comments and suggestions. I would like to make special

thanks to the following people (in alphabetical order), Jordan Brown,

Ellis Cohen, Donna Converse, Vania Joloboff, Stuart Marks, Ralph Mor

and Bob Scheifler.

  </para>

</chapter>

<chapter id='Definitions_and_Goals'>

  <title>Definitions and Goals</title>

  <para>

The purpose of the X Session Management Protocol (XSMP) is

to provide a uniform mechanism for users to save and restore their sessions.

A <firstterm>session</firstterm> is a group of clients, each

of which has a particular state.  The session is controlled by a

network service called the <firstterm>session manager</firstterm>.

The session manager issues commands to its

clients on behalf of the user.  These commands may cause clients to

save their state or to terminate.  It is expected that the client will

save its state in such a way that the client can be restarted at a

later time and resume its operation as if it had never been

terminated.  A client's state might include information about the file

currently being edited, the current position of the insertion point

within the file, or the start of an uncommitted transaction.  The

means by which clients are restarted is unspecified by this

protocol.

  </para>

  <para>

For purposes of this protocol, a <firstterm>client</firstterm>

of the session manager is defined as a connection to the session

manager.  A client is typically, though not necessarily, a process

running an application program connected to an X Window System

display.  However, a client may be connected to more than one X

display or not be connected to any X displays at all.

  </para>

  <para>

This protocol is layered on top of the X Consortium's ICE protocol and

relies on the ICE protocol to handle connection management and authentication.

  </para>

</chapter>

<chapter id='Overview_of_the_Protocol'>

  <title>Overview of the Protocol</title>

  <para>

Clients use XSMP to register themselves with the session manager (SM).

When a client starts up, it should connect to the SM.  The client

should remain connected for as long as it runs.  A client may resign

from the session by issuing the proper protocol messages before

disconnecting.  Termination of the connection without notice will be

taken as an indication that the client died unexpectedly.

  </para>

  <para>

Clients are expected to save their state in such a way as to allow

multiple instantiations of themselves to be managed independently.  A

unique value called a <firstterm>client-ID</firstterm> is

provided by the protocol for the purpose of disambiguating multiple

instantiations of clients.  Clients may use this ID, for example, as

part of a filename in which to store the state for a particular

instantiation.  The client-ID should be saved as part of the command

used to restart this client

(the <property>RestartCommand</property>) so that the client

will retain the same ID after it is restarted.  Certain small pieces

of state might also be stored in the RestartCommand.  For example, an

X11 client might place a '-twoWindow' option in its RestartCommand to

indicate that it should start up in two window mode when it is

restarted.

  </para>

  <para>

The client finds the network address of the SM in a system-dependent

way.  On POSIX systems an environment

variable called <envar>SESSION_MANAGER</envar>

will contain a list of network IDs.  Each id will contain the

transport name followed by a slash and the (transport-specific)

address.  A TCP/IP address would look like this:

    <informalexample><para>

      <literal>tcp/</literal><replaceable>hostname</replaceable><literal>:</literal><replaceable>portnumber</replaceable>

    </para></informalexample>

where the hostname is a fully qualified domain name.

A Unix Domain address looks like this:

    <informalexample><para>

	<literal>local/</literal><replaceable>hostname</replaceable><literal>:</literal><replaceable>path</replaceable>

    </para></informalexample>

A DECnet address would look like this:

    <informalexample><para>

	<literal>decnet/</literal><replaceable>nodename</replaceable><literal>::</literal><replaceable>objname</replaceable>

    </para></informalexample>

  </para>

  <para>

If multiple network IDs are specified, they should be separated by commas.

  </para>

  <note><title>Rationale</title>

    <para>

There was much discussion over whether the XSMP protocol should use X

as the transport protocol or whether it should use its own independent

transport.  It was decided that it would use an independent protocol

for several reasons.  First, the Session Manager should be able to

manage programs that do not maintain an X connection.  Second, the X

protocol is not appropriate to use as a general-purpose transport

protocol.  Third, a session might span multiple displays.

    </para>

    <para>

The protocol is connection based, because there is no other way for

the SM to determine reliably when clients terminate.

    </para>

    <para>

It should be noted that this protocol introduces another single point

of failure into the system.  Although it is possible for clients to

continue running after the SM has exited, this will probably not be

the case in normal practice.  Normally the program that starts the SM

will consider the session to be terminated when the SM exits (either

normally or abnormally).

    </para>

    <para>

To get around this would require some sort of rendezvous server that

would also introduce a single point of failure.  In the absence of a

generally available rendezvous server, XSMP is kept simple in the

hopes of making simple reliable SMs.

    </para>

  </note>

  <para>

Some clients may wish to manage the programs they start.  For example,

a mail program could start a text editor for editing the text of a

mail message.  A client that does this is a session manager itself; it

should supply the clients it starts with the appropriate connection

information (i.e., the <envar>SESSION_MANAGER</envar> environment variable)

that specifies a connection to itself instead of to the top level session

manager.

  </para>

  <para>

Each client has associated with it a list of properties.  A property

set by one client is not visible to any other client.  These

properties are used for the client to inform the SM of the client's

current state.  When a client initially connects to the SM, there are

no properties set.

  </para>

</chapter>

<chapter id='Data_Types'>

  <title>Data Types</title>

  <para>

XSMP messages contain several types of data.  Both the SM and the

client always send messages in their native byte order.  Thus, both

sides may need to byte-swap the messages received.  The need to do

byte-swapping is determined at run-time by the ICE protocol.

  </para>

  <para>

If an invalid value is specified for a field of any of the enumerated

types, a <errorname>BadValue</errorname> error message must be sent by

the receiver of the message to the sender of the message.

  </para>

<informaltable frame='topbot'>

  <tgroup cols='2' align='left' colsep='0' rowsep='0'>

    <colspec colname='c1' colwidth='1.0*'/>

    <colspec colname='c2' colwidth='3.0*'/>

      <row rowsep='1'>

        <entry>Type Name</entry>

        <entry>Description</entry>

      </row>

      <row>

        <entry>BOOL</entry>

        <entry><para><constant>False</constant> or <constant>True</constant></para></entry>

      </row>

      <row>

        <entry>INTERACT_STYLE</entry>

        <entry><function>None</function> <function>Errors</function> or <function>Any</function></entry>

      </row>

      <row>

        <entry>DIALOG_TYPE</entry>

        <entry><function>Error</function> or <function>Normal</function></entry>

      </row>

      <row>

        <entry>SAVE_TYPE</entry>

        <entry><function>Global</function> <function>Local</function> or <function>Both</function></entry>

      </row>

      <row>

        <entry>CARD8</entry>

        <entry>a one-byte unsigned integer</entry>

      </row>

      <row>

        <entry>CARD16</entry>

        <entry>a two-byte unsigned integer</entry>

      </row>

      <row>

        <entry>CARD32</entry>

        <entry>a four-byte unsigned integer</entry>

      </row>

      <row>

        <entry>ARRAY8</entry>

        <entry>a sequence of CARD8s</entry>

      </row>

      <row>

        <entry>LISTofARRAY8</entry>

        <entry>a sequence of ARRAY8s</entry>

      </row>

      <row>

        <entry>PROPERTY</entry>

        <entry>a property name (an ARRAY8), a type name, and a value of that type</entry>

      </row>

      <row>

        <entry>LISTofPROPERTY</entry>

        <entry>a counted collection of ­PROPERTYs.</entry>

      </row>

  </tgroup>

</informaltable>

</chapter>

<chapter id='Protocol_Setup_and_Message_Format'>

  <title>Protocol Setup and Message Format</title>

  <para>

To start the XSMP protocol, the client sends the server an

ICE <function>ProtocolSetup</function> message.  All XSMP messages are

in the standard ICE message format.  The message's major opcode is

assigned to XSMP by ICE at run-time.  The different parties (client

and SM) may be assigned different major opcodes for XSMP.  Once

assigned, all XSMP messages issued by this party will use the same

major opcode.  The message's minor opcode specifies which protocol

message this message contains.

  </para>

</chapter>

<chapter id='Client_Identification_String'>

  <title>Client Identification String</title>

  <para>

A client ID is a string of XPCS characters encoded in ISO Latin 1 (ISO

8859-1).  No null characters are allowed in this string.  The client

ID string is used in the <function>Register­Client</function>

and <function>Register­ClientReply</function> messages.

  </para>

  <para>

Client IDs consist of the pieces described below.  The ID is formed by

concatenating the pieces in sequence, without separator characters.

All pieces are padded on the left with '<literal>0</literal>'

characters so as to fill the specified length.  Decimal numbers are

encoded using the characters '<literal>0</literal>' through

'<literal>9</literal>', and hexadecimal numbers using the characters

'<literal>0</literal>' through '<literal>9</literal>' and

'<literal>A</literal>' through '<literal>F</literal>'.

  </para>

  <itemizedlist mark='bullet'>

     <listitem><para>

Version.  This is currently the character '<literal>1</literal>'.

     </para></listitem>

     <listitem>

       <para>Address type and address.  The address type will be one of

<literallayout remap='DS'>

     '<literal>1</literal>'     a 4-byte IPv4 address encoded as 8 hexadecimal digits

     '<literal>2</literal>'     a 6-byte DECNET address encoded as 12 hexadecimal digits

     '<literal>6</literal>'     a 16-byte IPv6 address encoded as 32 hexadecimal digits

</literallayout>

       </para>

       <para>

The address is the one of the network addresses of the machine where

the session manager (not the client) is running.  For example, the IP

address 198.112.45.11 would be encoded as the string

"<literal>QC6702D0B</literal>".

       </para>

     </listitem>

     <listitem><para>

	 Time stamp.  A 13-digit decimal number specifying

	 the number of milliseconds since 00:00:00 UTC, January 1, 1970.

     </para></listitem>

     <listitem>

       <para>

	Process-ID type and process-ID.  The process-ID type will be one of

<literallayout remap='DS'>

     '<literal>1</literal>'	a POSIX process-ID encoded as a 10-digit decimal number.

</literallayout>

       </para>

       <para>

The process-ID is the process-ID of the session manager, not of a client.

       </para>

     </listitem>

     <listitem>

       <para>

Sequence number.  This is a four-digit decimal number.  It is

incremented every time the session manager creates an ID.  After

reaching "Q9999" it wraps to "Q0000".

       </para>

       <note><title>Rationale</title>

	 <para>

Once a client ID has been assigned to the client, the client keeps

this ID indefinitely.  If the client is terminated and restarted, it

will be reassigned the same ID.  It is desirable to be able to pass

client IDs around from machine to machine, from user to user, and from

session manager to session manager, while retaining the identity of

the client.  This, combined with the indefinite persistence of client

IDs, means that client IDs need to be globally unique.  The

construction specified above will ensure that any client ID created by

any user, session manager, and machine will be different from any other.

	 </para>

       </note>

     </listitem>

  </itemizedlist>

</chapter>

<chapter id='Protocol'>

  <title>Protocol</title>

  <para>

The protocol consists of a sequence of messages as described below.

Each message type is specified by an ICE minor opcode.  A given

message type is sent either from a client to the session manager or

from the session manager to a client; the appropriate direction is

listed with each message's description.  For each message type, the

set of valid responses and possible error messages are listed.  The

ICE severity is given in parentheses following each error class.

  </para>

  <synopsis>

<function>RegisterClient</function> [Client → SM]

  <parameter>previous-ID</parameter>: ARRAY8

  Valid Responses: <function>RegisterClientReply</function>

  Possible Errors: <errorname>BadValue</errorname> (<symbol role='Pn'>CanContinue</symbol>)

  </synopsis>

  <para>

The client must send this message to the SM to register the client's

existence.  If a client is being restarted from a previous session,

the <parameter>previous-ID</parameter> field must contain the client

ID from the previous session.  For new clients,

<parameter>previous-ID</parameter> should be of zero length.

  </para>

  <para>

If <parameter>previous-ID</parameter> is not valid,

the SM will send a <errorname>BadValue</errorname>

error message to the client.  At this point the SM reverts to the

register state and waits for another <function>RegisterClient</function>

The client should then send a <function>RegisterClient</function> with a

null <parameter>previous-ID</parameter> field.

  </para>

  <synopsis>

<function>RegisterClientReply</function> [Client ← SM]

  <parameter>client-ID</parameter>: <type>ARRAY8</type>

  </synopsis>

  <para>

The <parameter>client-ID</parameter> specifies a unique identification

for this client.  If the client had specified an ID in the

<parameter>previous-ID</parameter> field of the

<function>RegisterClient</function> message,

<parameter>client-ID</parameter> will be identical to the previously

specified ID.  If <parameter>previous-ID</parameter> was null,

<parameter>client-ID</parameter> will be a unique ID freshly generated

by the SM.  The <parameter>client-ID</parameter> format is specified in

<link linkend='Client_Identification_String'>section 6</link>.

  </para>

  <para>

If the client didn't supply a <parameter>previous-ID</parameter> field to

the <function>Register­Client</function> message, the SM must send

a <function>SaveYourself</function> message with type = Local,

shutdown = False, interact-style = None, and fast = False immediately

after the <function>RegisterClientReply</function> The client should

respond to this like any other <function>Save­Yourself</function>

message.

  </para>

  <synopsis>

<function>SaveYourself</function> [Client ← SM]

  <parameter>type</parameter>: <type>SAVE_TYPE</type>

  <parameter>shutdown</parameter>: <type>BOOL</type>

  <parameter>interact-style</parameter>: <type>INTERACT_STYLE</type>

  <parameter>fast</parameter>: <type>BOOL</type>

  Valid Responses:

    <function>SetProperties</function>

    <function>DeleteProperties</function>

    <function>GetProperties</function>

    <function>SaveYourselfDone</function>

    <function>SaveYourselfPhase2Request</function>

    <function>InteractRequest</function>

  </synopsis>

  <para>

The SM sends this message to a client to ask it to save its state.

The client writes a state file, if necessary, and, if necessary,

uses <function>SetProperties</function> to inform the SM of how to

restart it and how to discard the saved state.  During this process it

can, if allowed by <parameter>interact-style</parameter>, request permission

to interact with

the user by sending an <function>InteractRequest</function> message.

After the state has been saved, or if it cannot be successfully saved,

and the properties are appropriately set, the client sends

a <function>SaveYourselfDone</function> message.  If the client wants

to save additional information after all the other clients have

finished changing their own state, the client should

send <function>SaveYourselfPhase2Request</function> instead

of <function>SaveYourselfDone</function> The client must then freeze

interaction with the user and wait until it receives

a <function>SaveComplete</function> <function>Die</function> or

a <function>ShutdownCancelled</function> message.

  </para>

  <para>

If <parameter>interact-style</parameter> is <function>None</function> the

client must not interact with the user while saving state.  If the

<parameter>interact-style</parameter>

is <function>Errors</function> the client may interact with the user

only if an error condition arises.  If <parameter>interact-style</parameter>

is <function>Any</function> then the client may interact with the user

for any purpose.  This is done by sending

an <function>Interact­Request</function> message.  The SM will

send an <function>Interact</function> message to each client that sent

an <function>Interact­Request</function> The client must postpone

all interaction until it gets the <function>Interact</function>

message.  When the client is done interacting it should send the SM

an <function>Interact­Done</function> message.

The <function>Interact­Request</function> message can be sent any

time after a <function>Save­Yourself</function> and before

a <function>Save­Yourself­Done</function>

  </para>

  <para>

Unusual circumstances may dictate multiple interactions.  The client

may initiate as many <function>Interact­Request</function>

- <function>Interact</function> - <function>InteractDone</function>

sequences as it needs before it sends <function>SaveYourselfDone</function>

  </para>

  <para>

When a client receives <function>Save­Yourself</function> and has

not yet responded <function>Save­Yourself­Done</function> to a

previous <function>Save­Yourself</function> it must send

a <function>Save­Yourself­Done</function> and may then begin

responding as appropriate to the newly received

<function>Save­Yourself</function>

</para>

  <para>

The <parameter>type</parameter> field specifies the type of information that

should be saved: <function>Global</function> <function>Local</function>

or <function>Both</function> The <function>Local</function> type

indicates that the application must update the properties to reflect

its current state, send

a <function>Save­Yourself­Done</function> and continue.

Specifically it should save enough information to restore the state as

seen by the user of this client.  It should not affect the state as

seen by other users.  The <function>Global</function> type indicates

that the user wants the client to commit all of its data to permanent,

globally-accessible storage.  <function>Both</function> indicates that

the client should do both of these.  If <function>Both</function> is

specified, the client should first commit the data to permanent

storage before updating its SM properties.

  </para>

  <note><title>Examples</title>

    <para>

If a word processor was sent a <function>SaveYourself</function> with

a type of <function>Local</function> it could create a temporary file

that included the current contents of the file, the location of the

cursor, and other aspects of the current editing session.  It would

then update its <function>Restart­Command</function> property with

enough information to find the temporary file, and

its <function>Discard­Command</function> with enough information

to remove it.

    </para>

    <para>

If a word processor was sent a <function>SaveYourself</function> with

a type of <function>Global</function> it would simply save the

currently edited file.

    </para>

    <para>

If a word processor was sent a <function>SaveYourself</function> with

a type of <function>Both</function> it would first save the currently

edited file.  It would then create a temporary file with information

such as the current position of the cursor and what file is being

edited.  It would then update

its <function>Restart­Command</function> property with enough

information to find the temporary file, and

its <function>Discard­Command</function> with enough information

to remove it.

    </para>

    <para>

Once the SM has send <function>SaveYourself</function> to a client, it

can't send another <function>SaveYourself</function> to that client until

the client either responds with a <function>SaveYourselfDone</function> or

the SM sends a <function>ShutdownCancelled</function>

    </para>

  </note>

  <note><title>Advice to Implementors</title>

    <para>

If the client stores local any state in a file or similar "external"

storage, it must create a distinct copy in response to

each <function>SaveYourself</function> message.

It <emphasis remap='I'>must not</emphasis> simply refer to a previous

copy, because the SM may discard that previous saved state using

a <function>DiscardCommand</function> without knowing that it is

needed for the new checkpoint.

    </para>

  </note>

  <para>

The <parameter>shutdown</parameter> field specifies whether the system is

being shut down.

  </para>

  <note><title>Rationale</title>

    <para>

The interaction may be different depending on whether or not shutdown is set.

    </para>

  </note>

  <para>

The client must save and then must prevent interaction until it

receives a <function>SaveComplete</function> <function>Die</function>

or a <function>Shutdown­Cancelled</function> because anything the

user does after the save will be lost.

  </para>

  <para>

The <parameter>fast</parameter> field specifies whether or not the client

should save its state as quickly as possible.  For example, if the SM knows

that power is about to fail, it should set the <parameter>fast</parameter>

field to <constant>True</constant>.

  </para>

  <synopsis>

<function>SaveYourselfPhase2</function> [Client → SM]

  Valid Responses:

    <function>SetProperties</function>

    <function>DeleteProperties</function>

    <function>GetProperties</function>

    <function>SaveYourselfDone</function>

    <function>InteractRequest</function>

  </synopsis>

  <para>

The SM sends this message to a client that has previously sent

a <function>SaveYourselfPhase2Request</function> message.  This

message informs the client that all other clients are in a fixed state

and this client can save state that is associated with other clients.

  </para>

  <note><title>Rationale</title>

    <para>

Clients that manager other clients (window managers, workspace

managers, etc) need to know when all clients they are managing are

idle, so that the manager can save state related to each of the

clients without being concerned with that state changing.

    </para>

  </note>

  <para>

The client writes a state file, if necessary, and, if necessary,

uses <function>SetProperties</function> to inform the SM of how to

restart it and how to discard the saved state.  During this process it

can request permission to interact with the user by sending

an <function>InteractRequest</function> message.  This should only be

done if an error occurs that requires user interaction to resolve.

After the state has been saved, or if it cannot be successfully saved,

and the properties are appropriately set, the client sends

a <function>SaveYourselfDone</function> message.

  </para>

  <synopsis>

<function>SaveYourselfRequest</function> [Client → SM]

  <parameter>type</parameter>: <type>SAVE_TYPE</type>

  <parameter>shutdown</parameter>: <type>BOOL</type>

  <parameter>interact-style</parameter>: <type>INTERACT_STYLE</type>

  <parameter>fast</parameter>: <type>BOOL</type>

  <parameter>global</parameter>: <type>BOOL</type>

  Valid Responses: <function>SaveYourself</function>

  </synopsis>

  <para>

An application sends this to the SM to request a checkpoint.  When the

SM receives this request it may generate a <function>SaveYourself</function>

message in response and it may leave the fields intact.

  </para>

  <note><title>Example</title> <para>

A vendor of a UPS (Uninterruptible Power Supply)

might include an SM client that would monitor the status of

the UPS and generate a fast shutdown if the power

is about to be lost.

  </para></note>

  <para>

If <parameter>global</parameter> is set to <constant>True</constant> then the

resulting <function>SaveYourself</function> should be sent to all

applications.  If <parameter>global</parameter> is set to

<constant>False</constant> then the

resulting <function>SaveYourself</function> should be sent to the

application that sent the <function>Save­Yourself­Request</function>

  </para>

  <synopsis>

<function>InteractRequest</function> [Client → SM]

  <parameter>dialog-type</parameter>: <type>DIALOG_TYPE</type>

  Valid Responses: <function>Interact</function> <function>ShutdownCancelled</function>

  Possible Errors: <errorname>BadState</errorname> (<symbol role='Pn'>CanContinue</symbol>)

  </synopsis>

  <para>

During a checkpoint or session-save operation, only one client at a

time might be granted the privilege of interacting with the user.

The <function>InteractRequest</function> message causes the SM to emit

an <function>Interact</function> message at some later time if the

shutdown is not cancelled by another client first.

  </para>

  <para>

The <parameter>dialog-type</parameter> field specifies either

<function>Errors</function> indicating that the client wants to start an

error dialog or <function>Normal</function> meaning the client wishes

to start a non-error dialog.

  </para>

  <synopsis>

<function>Interact</function> [Client ← SM]

  Valid Responses: <function>InteractDone</function>

  </synopsis>

  <para>

This message grants the client the privilege of interacting with the

user.  When the client is done interacting with the user it must send

an <function>InteractDone</function> message to the SM unless a

shutdown cancel is received.

  </para>

  <note><title>Advice to Implementors</title>

    <para>If a client receives a ShutdownCancelled

after receiving an <function>Interact</function> message, but before

sending a <function>InteractDone</function> the client should abort

the interaction and send a <function>SaveYourselfDone</function>

  </para></note>

  <synopsis>

<function>InteractDone</function> [Client → SM]

  <parameter>cancel-shutdown</parameter>: <type>BOOL</type>

  Valid Responses: <function>ShutdownCancelled</function>

  </synopsis>

  <para>

This message is used by a client to notify the SM that it is done interacting.

  </para>

  <para>

Setting the <parameter>cancel-shutdown</parameter> field to <constant>True</constant>

indicates that the user has requested that the entire shutdown be

cancelled.  <parameter>Cancel-shutdown</parameter> may only be <constant>True</constant> if

the corresponding <function>SaveYourself</function> message

specified <constant>True</constant> for the shutdown field

and <function>Any</function> or <function>Errors</function> for the

<parameter>interact-style</parameter> field.  Otherwise,

<parameter>cancel-shutdown</parameter> must be <constant>False</constant>.

  </para>

  <synopsis>

<function>SaveYourselfDone</function> [Client → SM]

  <parameter>success</parameter>: <type>BOOL</type>

  Valid Responses:

    <function>SaveComplete</function>

    <function>Die</function>

    <function>ShutdownCancelled</function>

  </synopsis>

  <para>

This message is sent by a client to indicate that all of the

properties representing its state have been updated.  After

sending <function>SaveYourselfDone</function> the client must wait for

a <function>SaveComplete</function> <function>ShutdownCancelled</function>

or <function>Die</function> message before changing its state.  If

the <function>SaveYourself</function> operation was successful, then

the client should set the <parameter>success</parameter> field to

<constant>True</constant> otherwise the client should set it to

<constant>False</constant>.

  </para>

  <note><title>Example</title>

    <para>

If a client tries to save its state and runs out of disk space, it

should return <constant>False</constant> in the <parameter>success</parameter>

field of the <function>SaveYourselfDone</function> message.

    </para>

  </note>

  <synopsis>

<function>SaveYourselfPhase2Request</function> [Client → SM]

  Valid Responses:

    <function>ShutdownCancelled</function>

    <function>SaveYourselfPhase2</function>

  </synopsis>

  <para>

This message is sent by a client to indicate that it needs to be informed

when all the other clients are quiescent, so it can continue its state.

  </para>

  <synopsis>

<function>Die</function> [Client ← SM]

  Valid Responses: <function>ConnectionClosed</function>

  </synopsis>

  <para>

When the SM wants a client to die it sends a <function>Die</function>

message.  Before the client dies it responds by sending

a <function>ConnectionClosed</function> message and may then close its

connection to the SM at any time.

  </para>

  <synopsis>

<function>SaveComplete</function> [Client → SM]

  Valid Responses:

  </synopsis>

  <para>

When the SM is done with a checkpoint, it will send each of the

clients a <function>SaveComplete</function> message.  The client is

then free to change its state.

  </para>

  <synopsis>

<function>ShutdownCancelled</function> [Client ← SM]

  </synopsis>

  <para>

The shutdown currently in process has been aborted.  The client can

now continue as if the shutdown had never happened.  If the client has

not sent <function>SaveYourselfDone</function> yet, the client can

either abort the save and send <function>SaveYourselfDone</function>

with the success field set to <constant>False</constant> or it can

continue with the save and send a <function>SaveYourselfDone</function>

with the success field set to reflect the outcome of the save.

  </para>

  <synopsis>

<function>ConnectionClosed</function> [Client → SM]

  <parameter>reason</parameter>: <type>LISTofARRAY8</type>

  </synopsis>

  <para>

Specifies that the client has decided to terminate.  It should be

immediately followed by closing the connection.

  </para>

  <para>

The <parameter>reason</parameter> field specifies why the client is resigning

from the session.  It is encoded as an array of Compound Text strings.  If the

resignation is expected by the user, there will typically be zero

ARRAY8s here.  But if the client encountered an unexpected fatal

error, the error message (which might otherwise be printed on stderr

on a POSIX system) should be forwarded to the SM here, one ARRAY8 per

line of the message.  It is the responsibility of the SM to display

this reason to the user.

  </para>