path: root/specs/SM/xsmp.ms

.\" Use tbl, -ms, and macros.t
.\" $Xorg: xsmp.ms,v 1.3 2000/08/17 19:42:19 cpqbld Exp $
.EH ''''
.OH ''''
.EF ''''
.OF ''''
.ps 10
.nr PS 10
\&
.TL
\s+2\fBX Session Management Protocol\fP\s-2
.sp
X.Org Standard
.sp
X Version 11, Release 6.8
.AU
Mike Wexler
.AI
Kubota Pacific Computer, Inc.
.AB
.LP
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.
.AE
.LP
.bp
\&
.sp 8
.LP
.DS C
X Window System is a trademark of The Open Group.
.sp
Copyright \(co 1992, 1993, 1994, 2002 The Open Group.
.DE
.sp 3
.LP
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:
.LP
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
.LP
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.
.af PN i
.EF ''\\\\n(PN''
.OF ''\\\\n(PN''
.bp 1
.af PN 1
.EH '\fBX Session Management Protocol\fP''\fBX11, Release 6.8\fP'
.OH '\fBX Session Management Protocol\fP''\fBX11, Release 6.8\fP'
.EF ''\fB\\\\n(PN\fP''
.OF ''\fB\\\\n(PN\fP''
.nH 1 "Acknowledgements"
.LP
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.
.nH 1 "Definitions and Goals"
.LP
The purpose of the X Session Management Protocol (XSMP) is to provide a
uniform mechanism for users to save and restore their sessions.  A
\fIsession\fP is a group of clients, each of which has a particular state.
The session is controlled by a network service called the \fIsession
manager\fP\^.  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.
.LP
For purposes of this protocol, a \fIclient\fP 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.
.LP
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.
.LP
.nH 1 "Overview of the Protocol"
.LP
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.
.LP
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 \fIclient-ID\fP 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 \fIRestartCommand\fP\^) 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.
.LP
The client finds the network address of the SM in a system-dependent way.
On POSIX systems an environment variable called SESSION_MANAGER 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:
.ID
	\fCtcp/\fP\fIhostname\fP\^\fC:\fP\^\fIportnumber\fP
.DE
where the hostname is a fully qualified domain name.
A Unix Domain address looks like this:
.ID
	\fClocal/\fP\fIhostname\fP\^\fC:\fP\^\fIpath\fP
.DE
A DECnet address would look like this:
.ID
	\fCdecnet/\fP\fInodename\fP\^\fC::\fP\^\fIobjname\fP
.DE
If multiple network IDs are specified, they should be separated by commas.
.NT Rationale
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.
.LP
The protocol is connection based, because there is no other way for the SM
to determine reliably when clients terminate.
.LP
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).
.LP
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.
.NE
.LP
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 SESSION_MANAGER environment variable) that specifies
a connection to itself instead of to the top level session manager.
.LP
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.
.nH 1 "Data Types"
.LP
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. 
.LP
If an invalid value is specified for a field of any of the enumerated types, a
.PN BadValue
error message must be sent by the receiver of the message to the sender of the
message.
.br
.ne 6
.TS H
l lw(4.5i).
_
.sp 6p
.B
Type Name	Description
.R
.sp 6p
_
.sp 6p
.TH
BOOL	T{
.PN False
or
.PN True
T}
INTERACT_STYLE	T{
.PN None ,
.PN Errors ,
or
.PN Any
T}
DIALOG_TYPE	T{
.PN Error
or
.PN Normal
T}
SAVE_TYPE	T{
.PN Global ,
.PN Local ,
or
.PN Both
T}
CARD8	a one-byte unsigned integer
CARD16	a two-byte unsigned integer
CARD32	a four-byte unsigned integer
ARRAY8	a sequence of CARD8s
LISTofARRAY8	a sequence of ARRAY8s
PROPERTY	a property name (an ARRAY8), a type name, and a value of that type
LISTofPROPERTY	T{
a counted collection of \%PROPERTYs.
T}		
.sp 6p
_
.TE
.nH 1 "Protocol Setup and Message Format"
.LP
To start the XSMP protocol, the client sends the server an ICE
.PN ProtocolSetup
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. 
.nH 1 "Client Identification String"
.LP
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
.PN Register\%Client
and
.PN Register\%ClientReply
messages.
.LP
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 '0' characters
so as to fill the specified length.
Decimal numbers are
encoded using the characters `0' through `9', and
hexadecimal numbers using the characters `0' through `9'
and `A' through `F'.
.IP \(bu 4
Version.  This is currently the character `1'.
.IP \(bu 4
Address type and address.  The address type will be one of
.DS
.ta 0.5i
`1'	a 4-byte IPv4 address encoded as 8 hexadecimal digits
`2'	a 6-byte DECNET address encoded as 12 hexadecimal digits
`6'	a 16-byte IPv6 address encoded as 32 hexadecimal digits
.DE
.IP
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 \*QC6702D0B\*U.
.IP \(bu 4
Time stamp.  A 13-digit decimal number specifying the number of
milliseconds since 00:00:00 UTC, January 1, 1970.
.IP \(bu 4
Process-ID type and process-ID.  The process-ID type will be one of
.DS
.ta 0.5i
`1'	a POSIX process-ID encoded as a 10-digit decimal number.
.DE
.IP
The process-ID is the process-ID of the session manager, not of a client.
.IP \(bu 4
Sequence number.  This is a four-digit decimal number.  It is incremented
every time the session manager creates an ID.  After reaching \*Q9999\*U it
wraps to \*Q0000\*U.
.NT "Rationale"
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.
.NE
.nH 1 "Protocol"
.LP
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.
.LP
.sM
.PN RegisterClient
[Client \(-> SM]
.RS
.LP
\fIprevious-ID\fP\^: ARRAY8
.LP
Valid Responses: 
.PN RegisterClientReply
.LP
Possible Errors:
.PN BadValue
.Pn ( CanContinue )
.RE
.eM
.LP
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 previous-ID field must contain the client ID from the
previous session.
For new clients, previous-ID should be of zero length.
.LP
If previous-ID is not valid, the SM will send a
.PN BadValue
error message to the client.
At this point the SM reverts to the register state and waits for another
.PN RegisterClient .
The client should then send a
.PN RegisterClient
with a null previous-ID field.
.LP
.sM
.PN RegisterClientReply
[Client \(<- SM]
.RS
.LP
\fIclient-ID\fP\^: ARRAY8
.RE
.eM
.LP
The client-ID specifies a unique identification for this client.
If the client had specified an ID in the previous-ID field of the
.PN RegisterClient
message, client-ID will be identical to the previously specified ID.  If
previous-ID was null, client-ID will be a unique ID freshly generated by the
SM.  The client-ID format is specified in section 6.
.LP
If the client didn't supply a previous-ID field to the
.PN Register\%Client
message, the SM must send a
.PN SaveYourself
message with type = Local, shutdown = False, interact-style = None,
and fast = False immediately after the
.PN RegisterClientReply .
The client should respond to this like any other
.PN Save\%Yourself
message.
.LP
.sM
.PN SaveYourself
[Client \(<- SM]
.RS
.LP
\fItype\fP\^: SAVE_TYPE
.br
\fIshutdown\fP\^: BOOL
.br
\fIinteract-style\fP\^: INTERACT_STYLE
.br
\fIfast\fP\^: BOOL
.LP
Valid Responses:
.PN SetProperties ,
.PN DeleteProperties ,
.PN GetProperties ,
.PN SaveYourselfDone ,
.PN SaveYourselfPhase2Request ,
.PN InteractRequest
.RE
.eM
.LP
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 
.PN SetProperties
to inform the SM of
how to restart it and how to discard the saved state.  During
this process it can, if allowed by interact-style, request
permission to interact with the user by sending an
.PN InteractRequest
message.
After the state has been saved, or
if it cannot be successfully saved, and the properties
are appropriately set, the client sends a 
.PN SaveYourselfDone
message. 
If the client wants to save additional information after all the
other clients have finished changing their own state, the client
should send
.PN SaveYourselfPhase2Request
instead of 
.PN SaveYourselfDone .
The client must then
freeze interaction with the user and wait until it
receives a 
.PN SaveComplete ,
.PN Die ,
or a 
.PN ShutdownCancelled
message.
.LP
If interact-style is
.PN None ,
the client must not interact with the
user while saving state.  If the interact-style is 
.PN Errors ,
the client
may interact with the user only if an error condition arises.  If
interact-style is 
.PN Any ,
then the client may interact with the user for
any purpose.
This is done by sending an
.PN Interact\%Request
message.  The SM will send an
.PN Interact
message to
each client that sent an
.PN Interact\%Request .  
The client must postpone all
interaction until it gets the
.PN Interact
message.  When the client is done
interacting it should send the SM an
.PN Interact\%Done
message.  The 
.PN Interact\%Request
message can be sent any time after a
.PN Save\%Yourself
and before a 
.PN Save\%Yourself\%Done .
.LP
Unusual circumstances may dictate multiple interactions.
The client may initiate as many
.PN Interact\%Request
\-
.PN Interact
\-
.PN InteractDone
sequences as it needs before it sends
.PN SaveYourselfDone .
.LP
When a client receives
.PN Save\%Yourself
and has not yet responded
.PN Save\%Yourself\%Done
to a previous
.PN Save\%Yourself ,
it must send a
.PN Save\%Yourself\%Done
and may then begin responding as appropriate
to the newly received 
.PN Save\%Yourself .
.LP
The type field specifies the type of information that should be saved:
.PN Global ,
.PN Local ,
or
.PN Both .
The 
.PN Local
type indicates that the application must update the
properties to reflect its current state, send a
.PN Save\%Yourself\%Done
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
.PN Global
type indicates that the user wants the client to 
commit all of its data to permanent, globally-accessible
storage.
.PN Both
indicates that the client should do both of these.  If
.PN Both
is specified, the client should first commit the data to permanent storage
before updating its SM properties.
.NT Examples
If a word processor was sent a 
.PN SaveYourself
with a type of 
.PN Local ,
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
.PN Restart\%Command
property with enough information to find the temporary file, 
and its 
.PN Discard\%Command 
with enough information to remove it.
.LP
If a word processor was sent a 
.PN SaveYourself
with a type of
.PN Global ,
it would simply save the currently edited file.
.LP
If a word processor was sent a 
.PN SaveYourself
with a type of
.PN Both ,
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
.PN Restart\%Command
property with enough information to find the temporary file, 
and its 
.PN Discard\%Command 
with enough information to remove it.
.LP
Once the SM has send 
.PN SaveYourself
to a client, it can't send another 
.PN SaveYourself 
to that client until the client either
responds with a 
.PN SaveYourselfDone
or the SM sends a 
.PN ShutdownCancelled .
.NE
.NT "Advice to Implementors"
If the client stores local any state in a file or similar
\*Qexternal\*U storage, it must create a distinct
copy in response to each 
.PN SaveYourself 
message.
It \fImust not\fP simply refer to a previous copy, because
the SM may discard that previous saved state using a 
.PN DiscardCommand
without knowing that it is needed for the new checkpoint.
.NE
.LP
The shutdown field specifies whether the system is being shut down.
.NT Rationale
The interaction
may be different depending on whether or not shutdown is set.
.NE
The client must save and then must prevent interaction
until it receives a
.PN SaveComplete ,
.PN Die ,
or a
.PN Shutdown\%Cancelled ,
because anything the user does after the save will be lost.
.LP
The fast 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 fast field to
.PN True .
.LP
.sM
.PN SaveYourselfPhase2
[Client \(<- SM]
.RS
.LP
.LP
Valid Responses:
.PN SetProperties ,
.PN DeleteProperties ,
.PN GetProperties ,
.PN SaveYourselfDone ,
.PN InteractRequest
.RE
.eM
.LP
The SM sends this message to a client that has previously sent a
.PN SaveYourselfPhase2Request
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.
.NT "Rationale"
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.
.NE
The client writes a state file, if necessary, and, if necessary, uses 
.PN SetProperties
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
.PN InteractRequest
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 
.PN SaveYourselfDone
message. 
.LP
.LP
.sM
.PN SaveYourselfRequest
[Client \(-> SM]
.RS
.LP
\fItype\fP\^: SAVE_TYPE
.br
\fIshutdown\fP\^: BOOL
.br
\fIinteract-style\fP\^: INTERACT_STYLE
.br
\fIfast\fP\^: BOOL
.br
\fIglobal\fP\^: BOOL
.LP
Valid Responses:
.PN SaveYourself
.RE
.eM
.LP
An application sends this to the SM to request a checkpoint.
When the SM receives this request it may generate a 
.PN SaveYourself
message in response and it may leave the fields intact.
.NT Example
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.
.NE
.LP
If global is set to 
.PN True ,
then the resulting 
.PN SaveYourself 
should be
sent to all applications.  If global is set to 
.PN False ,
then the resulting
.PN SaveYourself 
should be sent to the application that sent the 
.PN Save\%Yourself\%Request .
.LP
.sM
.PN InteractRequest
[Client \(-> SM]
.RS
.LP
\fIdialog-type\fP\^: DIALOG_TYPE
.LP
Valid Responses:
.PN Interact ,
.PN ShutdownCancelled
.LP
Possible Errors:
.PN BadState
.Pn ( CanContinue )
.RE
.eM
.LP
During a checkpoint or session-save operation,
only one client at a time might be granted the privilege of interacting with
the user.  The
.PN InteractRequest
message causes the SM to emit an
.PN Interact
message at some later time if the shutdown is not cancelled
by another client first.
.LP
The dialog-type field specifies either
.PN Errors ,
indicating that the 
client wants to start an error dialog or
.PN Normal ,
meaning the client 
wishes to start a non-error dialog.
.LP
.sM
.PN Interact
[Client \(<- SM]
.RS
.LP
Valid Responses:
.PN InteractDone
.LP
.RE
.eM
.LP
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 
.PN InteractDone
message to the SM unless a shutdown cancel is received.
.NT "Advice to Implementors"
If a client receives a ShutdownCancelled after receiving an
.PN Interact
message, but before sending a 
.PN InteractDone ,
the client should abort the interaction and send a 
.PN SaveYourselfDone .
.NE
.LP
.sM
.PN InteractDone
[Client \(-> SM]
.RS
.LP
\fIcancel-shutdown\fP\^: BOOL
.br
.LP
Valid Responses:
.PN ShutdownCancelled
.LP
.RE
.eM
.LP
This message is used by a client to notify the SM that it is done interacting.
.LP
Setting the cancel-shutdown field to 
.PN True
indicates that
the user has requested that the entire shutdown be cancelled.
Cancel-shutdown may only be
.PN True
if the corresponding
.PN SaveYourself
message specified
.PN True
for the shutdown field and
.PN Any
or
.PN Errors
for the interact-style field.  Otherwise, cancel-shutdown must be
.PN False .
.LP
.sM
.PN SaveYourselfDone
[Client \(-> SM]
.RS
.LP
\fIsuccess\fP\^: BOOL
.LP
Valid Responses: 
.PN SaveComplete ,
.PN Die ,
.PN ShutdownCancelled
.LP
.RE
.eM
.LP
This message is sent by a client to indicate that all of the properties
representing its state have been updated.
After sending 
.PN SaveYourselfDone 
the client must
wait for a 
.PN SaveComplete ,
.PN ShutdownCancelled ,
or 
.PN Die 
message before changing its state.
If the 
.PN SaveYourself
operation was successful, then the client
should set the success field to
.PN True ;
otherwise the client should set
it to
.PN False .
.NT Example
If a client tries to save its state and runs out of disk space,
it should return 
.PN False
in the success
field of the 
.PN SaveYourselfDone
message.
.NE
.LP
.sM
.PN SaveYourselfPhase2Request
[Client \(-> SM]
.RS
.LP
Valid Responses: 
.PN ShutdownCancelled ,
.PN SaveYourselfPhase2
.LP
.RE
.eM
.LP
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.
.LP
.sM
.PN Die
[Client \(<- SM]
.RS
.LP
Valid Responses:
.PN ConnectionClosed
.RE
.eM
.LP
When the SM wants a client to die it sends a
.PN Die
message.  Before the client dies it responds
by sending a 
.PN ConnectionClosed
message and may then close
its connection to the SM at any time.
.LP
.sM
.PN SaveComplete
[Client \(<- SM]
.RS
.LP
Valid Responses:
.RE
.eM
.LP
When the SM is done with a checkpoint, it will send each of the clients a
.PN SaveComplete
message.  
The client is then free to change its state.
.LP
.sM
.PN ShutdownCancelled
[Client \(<- SM]
.RS
.RE
.eM
.LP
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
.PN SaveYourselfDone
yet, the client can either
abort the save and send 
.PN SaveYourselfDone
with the success field
set to
.PN False ,
or it can continue with the save and send a
.PN SaveYourselfDone
with the success field set to reflect the outcome
of the save.
.LP
.sM
.PN ConnectionClosed
[Client \(-> SM]
.RS
.LP
\fIreason\fP\^: LISTofARRAY8
.RE
.eM
.LP
Specifies that the client has decided to terminate.
It should be immediately followed by closing the connection.
.LP
The reason 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.
.LP
After sending this message, the client must not send any additional XSMP
messages to the SM.
.NT "Advice to Implementors"
If additional messages are received, they should be discarded.
.NE
.NT Rationale
The reason for sending the
.PN ConnectionClosed
message before
actually closing the connections is that some transport protocols will
not provide immediate notification of connection closure.
.NE
.LP
.sM
.PN SetProperties
[Client \(-> SM]
.RS
.LP
\fIproperties\fP: LISTofPROPERTY
.RE
.eM
.LP
Sets the specified properties to the specified values.
Existing properties not specified in the 
.PN Set\%Properties
message are unaffected.
Some properties have predefined semantics.
See section 11, \*QPredefined Properties.\*U
.LP
The protocol specification recommends that property names used 
for properties not defined by the standard should begin with an underscore.
To prevent conflicts among organizations, 
additional prefixes should be chosen 
(for example,  _KPC_FAST_SAVE_OPTION).
The organizational prefixes should be registered with the X Registry.
The XSMP reserves all property names not beginning with an underscore for 
future use.
.LP
.sM
.PN DeleteProperties
[Client \(-> SM]
.RS
.LP
.br
\fIproperty-names\fP: LISTofARRAY8
.RE
.eM
.LP
Removes the named properties.
.LP
.sM
.PN GetProperties
[Client \(-> SM]
.RS
.LP
Valid Responses:
.PN GetPropertiesReply
.RE
.eM
.LP
Requests that the SM respond with the
values of all the properties for this client.
.LP
.sM
.PN GetPropertiesReply
[Client \(<- SM]
.RS
.LP
\fIvalues\fP\^: LISTofPROPERTY
.RE
.eM
.LP
This message is sent in reply to a
.PN GetProperties
message and includes
the values of all the properties.
.nH 1 "Errors"
.LP
When the receiver of a message detects an error condition, 
the receiver sends
an ICE error message to the sender.
There are only two types of errors that are used by the XSMP:
.PN BadValue 
and
.PN BadState .
These are both defined in the ICE protocol.
.LP
Any message received out-of-sequence
will generate a
.PN BadState
error message.
.nH 1 "State Diagrams"
.LP
These state diagrams are designed to cover all actions of both
the client and the SM. 
.nH 2 "Client State Diagram"
.LP
.nf
.DS L 0
\fIstart:\fP
	ICE protocol setup complete \(-> \fCregister\fP
.DE
.sp
.DS L 0
\fIregister:\fP
	send \fBRegisterClient\fP \(-> \fCcollect-id\fP
.DE
.sp
.DS L 0
\fIcollect-id:\fP
	receive \fBRegisterClientReply\fP \(-> \fCidle\fP
.DE
.sp
.DS L 0
\fIshutdown-cancelled:\fP
	send \fBSaveYourselfDone\fP \(-> \fCidle\fP
.DE
.sp
.DS L 0
\fIidle:\fP [Undoes any freeze of interaction with user.] 
	receive \fBDie\fP \(-> \fCdie\fP
	receive \fBSaveYourself\fP \(-> \fCfreeze-interaction\fP
	send \fBGetProperties\fP \(-> \fCidle\fP
	receive \fBGetPropertiesReply\fP \(-> \fCidle\fP
	send \fBSetProperties\fP \(-> \fCidle\fP
	send \fBDeleteProperties\fP \(-> \fCidle\fP
	send \fBConnectionClosed\fP \(-> \fCconnection-closed\fP
	send \fBSaveYourselfRequest\fP \(-> \fCidle\fP
.DE
.sp
.DS L 0
\fIdie:\fP
	send \fBConnectionClosed\fP \(-> \fCconnection-closed\fP
.DE
.sp
.DS L 0
\fIfreeze-interaction:\fP
	freeze interaction with user \(-> \fCsave-yourself\fP
.DE
.sp
.DS L 0
\fIsave-yourself:\fP
	receive \fBShutdownCancelled\fP \(-> \fCshutdown-cancelled\fP
	send \fBSetProperties\fP \(-> \fCsave-yourself\fP
	send \fBDeleteProperties\fP \(-> \fCsave-yourself\fP
	send \fBGetProperties\fP \(-> \fCsave-yourself\fP
	receive \fBGetPropertiesReply\fP \(-> \fCsave-yourself\fP
	send \fBInteractRequest\fP \(-> \fCinteract-request\fP
	send \fBSaveYourselfPhase2Request\fP -> waiting-for-phase2
	if shutdown mode:
		send \fBSaveYourselfDone\fP \(-> \fCsave-yourself-done\fP
	otherwise:
		send \fBSaveYourselfDone\fP \(-> \fCidle\fP
.DE
.sp
.DS L 0
\fIwaiting-for-phase2:\fP
	receive \fBShutdownCancelled\fP \(-> \fCshutdown-cancelled\fP
	receive \fBSaveYourselfPhase2\fP \(-> \fCphase2\fP
.DE
.sp
.DS L 0
\fIphase2:\fP
	receive \fBShutdownCancelled\fP \(-> \fCshutdown-cancelled\fP
	send \fBSetProperties\fP \(-> \fCsave-yourself\fP
	send \fBDeleteProperties\fP \(-> \fCsave-yourself\fP
	send \fBGetProperties\fP \(-> \fCsave-yourself\fP
	receive \fBGetPropertiesReply\fP \(-> \fCsave-yourself\fP
	send \fBInteractRequest\fP \(-> \fCinteract-request\fP (errors only)
	if shutdown mode:
		send \fBSaveYourselfDone\fP \(-> \fCsave-yourself-done\fP
	otherwise:
		send \fBSaveYourselfDone\fP \(-> \fCidle\fP
.DE
.sp
.DS L 0
\fIinteract-request:\fP
	receive \fBInteract\fP \(-> \fCinteract\fP
	receive \fBShutdownCancelled\fP \(-> \fCshutdown-cancelled\fP
.DE
.sp
.DS L 0
\fIinteract:\fP
	send \fBInteractDone\fP \(-> \fCsave-yourself\fP
	receive \fBShutdownCancelled\fP \(-> \fCshutdown-cancelled\fP
.DE
.sp
.DS L 0
\fIsave-yourself-done:\fP (changing state is forbidden)
	receive \fBSaveComplete\fP \(-> \fCidle\fP
	receive \fBDie\fP \(-> \fCdie\fP
	receive \fBShutdownCancelled\fP \(-> \fCidle\fP
.DE
.sp
.DS L 0
\fIconnection-closed:\fP
	client stops participating in session
.DE
.ne 1i
.nH 2 "Session Manager State Diagram"
.LP
.nf
.DS L 0
\fIstart:\fP
	receive \fBProtocolSetup\fP \(-> \fCprotocol-setup\fP
.DE
.sp
.DS L 0
\fIprotocol-setup:\fP
	send \fBProtocolSetupReply\fP \(-> \fCregister\fP
.DE
.sp
.DS L 0
\fIregister:\fP
	receive \fBRegisterClient\fP \(-> \fCacknowledge-register\fP
.DE
.sp
.DS L 0
\fIacknowledge-register:\fP
	send \fBRegisterClientReply\fP \(-> \fCidle\fP
.DE
.sp
.DS L 0
\fIidle:\fP
	receive \fBSetProperties\fP \(-> \fCidle\fP
	receive \fBDeleteProperties\fP \(-> \fCidle\fP
	receive \fBConnectionClosed\fP \(-> \fCstart\fP
	receive \fBGetProperties\fP \(-> \fCget-properties\fP
	receive \fBSaveYourselfRequest\fP \(-> \fCsave-yourself\fP
	send \fBSaveYourself\fP \(-> \fCsaving-yourself\fP
.DE
.sp
.DS L 0
\fIsave-yourself:\fP
	send \fBSaveYourself\fP \(-> \fCsaving-yourself\fP
.DE
.sp
.DS L 0
\fIget-properties:\fP
	send \fBGetPropertiesReply\fP \(-> \fCidle\fP
.DE
.sp
.DS L 0
\fIsaving-get-properties:\fP
	send \fBGetPropertiesReply\fP \(-> \fCsaving-yourself\fP
.DE
.sp
.DS L 0
\fIsaving-yourself:\fP
	receive \fBInteractRequest\fP \(-> \fCsaving-yourself\fP
	send \fBInteract\fP \(-> \fCsaving-yourself\fP
	send \fBShutdownCancelled\fP -> \fCidle\fP
	receive \fBInteractDone\fP \(-> \fCsaving-yourself\fP
	receive \fBSetProperties\fP \(-> \fCsaving-yourself\fP
 	receive \fBDeleteProperties\fP \(-> \fCsaving-yourself\fP
	receive \fBGetProperties\fP \(-> \fCsaving-get-properties\fP
	receive \fBSaveYourselfPhase2Request\fP \(-> \fCstart-phase2\fP
	receive \fBSaveYourselfDone\fP \(-> \fCsave-yourself-done\fP
.DE
.sp
.DS L 0
\fIstart-phase2:\fP	
	If all clients have sent either \fBSaveYourselfPhase2Request\fP or \fBSaveYourselfDone\fP:
		send \fBSaveYourselfPhase2\fP \(-> \fCphase2\fP
	else
		\(-> \fCsaving-yourself\fP
.DE
.sp
.DS L 0
\fIphase2:\fP
	receive \fBInteractRequest\fP \(-> \fCsaving-yourself\fP
	send \fBInteract\fP \(-> \fCsaving-yourself\fP
	send \fBShutdownCancelled\fP -> \fCidle\fP
	receive \fBInteractDone\fP \(-> \fCsaving-yourself\fP
	receive \fBSetProperties\fP \(-> \fCsaving-yourself\fP
 	receive \fBDeleteProperties\fP \(-> \fCsaving-yourself\fP
	receive \fBGetProperties\fP \(-> \fCsaving-get-properties\fP
	receive \fBSaveYourselfDone\fP \(-> \fCsave-yourself-done\fP
.DE
.sp
.DS L 0
\fIsave-yourself-done:\fP
	If all clients are saved:
		If shutting down:
			send \fBDie\fP \(-> \fCdie\fP
		otherwise
			send \fBSaveComplete\fP \(-> \fCidle\fP
.sp
	If some clients are not saved:
	\(-> \fCsaving-yourself\fP
.DE
.sp
.DS L 0
\fIdie:\fP
	SM stops accepting connections
.DE
.nH 1 "Protocol Encoding"
.nH 2 "Types"
.LP
.nf
.ta .2i .5i 2.0i
BOOL
	0	False
	1	True
.sp
INTERACT_STYLE
	0	None
	1	Errors
	2	Any
.sp
DIALOG_TYPE
	0	Error
	1	Normal
.sp
SAVE_TYPE
	0	Global
	1 	Local
	2 	Both
.sp
.ne .75i
ARRAY8
	4	CARD32	length
	n	LISTofCARD8	the array
	p		p = pad (4 + n, 8)
.sp
LISTofARRAY8
	4	CARD32	count
	4		unused
	a	ARRAY8	first array
	b	ARRAY8	second array
	\&.
	\&.
	\&.
	q	ARRAY8	last array
.sp
PROPERTY
	a	ARRAY8	name
	b	ARRAY8	type (XPCS encoded in Latin-1, case sensitive)
	c	LISTofARRAY8	values
.sp
LISTofPROPERTY
	4       CARD32	count
	4       	unused
	a       PROPERTY	first property
	b       PROPERTY	second property
	\&.
	\&.
	\&.
	q	PROPERTY	last property
.nH 2 "Messages"
.LP
XSMP is a sub-protocol of ICE.  The major opcode is assigned at run-time
by ICE and is represented here by `?'.
.LP
To start the XSMP protocol, the client sends the server an ICE
.PN ProtocolSetup
message.  
The protocol-name field should be specified as \*QXSMP\*U, the major
version of the protocol is 1, the minor version is 0.
These values may change if the protocol is revised.  The minor version
number will be incremented if the change is compatible, otherwise the major
version number will be incremented.
.LP
In 
.PN ProtocolReply
message sent by the session manager,
the XSMP protocol defines the vendor parameter as product identification
of the session manager, and defines the release parameter as
the software release identification of the session manager. 
The session manager should supply this information in the
ICE 
.PN ProtocolReply
message.
.LP
.nf
.ta .2i .5i 2.0i 
.ne 3
.PN RegisterClient
	1	?	XSMP
	1	1	opcode
	2		unused
	4	a/8	length of remaining data in 8-byte units
	a	ARRAY8	previous-ID
.ne 6
.sp
.PN RegisterClientReply
	1	?	XSMP
	1	2	opcode
	2		unused
	4	a/8	length of remaining data in 8-byte units
	a	ARRAY8	client-ID
.ne 4
.sp
.PN SaveYourself
	1	?	XSMP
	1	3	opcode
	2		unused
	4	1	length of remaining data in 8-byte units
	1	SAVE_TYPE	type
	1	BOOL	shutdown
	1	INTERACT_STYLE	interact-style
	1	BOOL	fast
	4		unused
.ne 4
.sp
.PN SaveYourselfRequest
	1	?	XSMP
	1	4	opcode
	2		unused
	4	1	length of remaining data in 8-byte units
	1	SAVE_TYPE	type
	1	BOOL	shutdown
	1	INTERACT_STYLE	interact-style
	1	BOOL	fast
	1	BOOL	global
	3		unused
.ne 4
.sp
.PN InteractRequest
	1	?	XSMP
	1	5	opcode
	1	DIALOG_TYPE	dialog type
	1		unused
	4	0	length of remaining data in 8-byte units
.ne 4
.sp
.PN Interact
	1	?	XSMP
	1	6	opcode
	2		unused
	4	0	length of remaining data in 8-byte units
.ne 4
.sp
.PN InteractDone
	1	?	XSMP
	1	7	opcode
	1	BOOL	cancel-shutdown
	1		unused
	4	0	length of remaining data in 8-byte units
.ne 6
.sp
.PN SaveYourselfDone
	1	?	XSMP
	1	8	opcode
	1	BOOL	success
	1		unused
	4	0	length of remaining data in 8-byte units
.ne 4
.sp
.PN Die
	1	?	XSMP
	1	9	opcode
	2		unused
	4	0	length of remaining data in 8-byte units
.ne 4
.sp
.PN ShutdownCancelled
	1	?	XSMP
	1	10	opcode
	2		unused
	4	0	length of remaining data in 8-byte units
.ne 4
.sp
.PN ConnectionClosed
	1	?	XSMP
	1	11	opcode
	2		unused
	4	a/8	length of remaining data in 8-byte units
	a	LISTofARRAY8	reason
.ne 4
.sp
.PN SetProperties
	1	?	XSMP
	1	12	opcode
	2		unused
	4	a/8	length of remaining data in 8-byte units
	a	LISTofPROPERTY	properties
.ne 4
.sp
.PN DeleteProperties
	1	?	XSMP
	1	13	opcode
	2		unused
	4	a/8	length of remaining data in 8-byte units
	a	LISTofARRAY8	properties
.ne 4
.sp
.PN GetProperties
	1	?	XSMP
	1	14	opcode
	2		unused
	4	0	length of remaining data in 8-byte units
.ne 4
.sp
.PN GetPropertiesReply
	1	?	XSMP
	1	15	opcode
	2		unused
	4	a/8	length of remaining data in 8-byte units
	a	LISTofPROPERTY	properties
.ne 4
.sp
.PN SaveYourselfPhase2Request
	1	?	XSMP
	1	16	opcode
	2		unused
	4	0	length of remaining data in 8-byte units
.ne 4
.sp
.PN SaveYourselfPhase2
	1	?	XSMP
	1	17	opcode
	2		unused
	4	0	length of remaining data in 8-byte units

.sp
.PN SaveComplete
	1	?	XSMP
	1	18	opcode
	2		unused
	4	0	length of remaining data in 8-byte units

.nH 1 "Predefined Properties"
.LP
All property values are stored in a LISTofARRAY8.  If the type of the
property is CARD8, the value is stored as a LISTofARRAY8 with one ARRAY8
that is one byte long.  That single byte contains the CARD8.  If the type of
the property is ARRAY8, the value is stored in the first element of a single
element LISTofARRAY8.
.LP
The required properties must be set each time a client
connects with the SM.  The properties must be set after
the client sends
.PN RegisterClient
and before the client sends
.PN SaveYourselfDone .
Otherwise, the behavior of
the session manager is not defined.
.LP
Clients may set, get, and delete nonstandard properties.
The lifetime of stored properties does not extend into 
subsequent sessions.
.br
.ne 6
.TS H
l l l c .
_
.sp 6p
.B
Name	Type	Posix Type	Required?
.R
.sp 6p
_
.sp 6p
.TH
CloneCommand	OS-specific	LISTofARRAY8	Yes
CurrentDirectory	OS-specific	ARRAY8	No
DiscardCommand	OS-specific	LISTofARRAY8	No*
Environment	OS-specific	LISTofARRAY8	No
ProcessID	OS-specific	ARRAY8	No
Program	OS-specific	ARRAY8	Yes
RestartCommand	OS-specific	LISTofARRAY8	Yes
ResignCommand	OS-specific	LISTofARRAY8	No
RestartStyleHint	CARD8	CARD8	No
ShutdownCommand	OS-specific	LISTofARRAY8	No
UserID	ARRAY8	ARRAY8	Yes
.sp 6p
_
.TE
.LP
* Required if any state is stored in an external repository (e.g., state file).
.IP CloneCommand 3
This is like the 
.PN RestartCommand 
except it restarts a copy of the
application.  The only difference is that the application doesn't
supply its client id at register time.  On POSIX systems the type
should be a LISTofARRAY8.
.IP CurrentDirectory 3
On POSIX-based systems specifies the value of the current directory that
needs to be set up prior to starting the program and should be of type
ARRAY8.
.IP DiscardCommand 3
The discard command contains a command that when delivered to the host that 
the client is running on (determined from the connection), will
cause it to discard any information about the current state.  If this command
is not specified, the SM will assume that all of the client's state is encoded
in the 
.PN Restart\%Command .
On POSIX systems the type should be LISTofARRAY8.
.IP Environment 3
On POSIX based systems, this will be of type LISTofARRAY8 where
the ARRAY8s alternate between environment variable name and environment
variable value.  
.IP ProcessID 3
This specifies an OS-specific identifier for the process.  On POSIX
systems this should of type ARRAY8 and contain the return value 
of getpid() turned into a Latin-1 (decimal) string.
.IP Program 3
The name of the program that is running.  On POSIX systems this 
should be the
first parameter passed to execve and should be of type ARRAY8.
.IP RestartCommand 3
The restart command contains a command that when delivered to the
host that the client is running on (determined from the connection),
will cause the client to restart in
its current state.  On POSIX-based systems this is of type LISTofARRAY8
and each of the elements in the array represents an element in
the argv array.
This restart command should ensure that the client restarts with the specified
client-ID.
.IP ResignCommand 3
A client that sets the
.PN RestartStyleHint
to
.PN RestartAnyway
uses this property to specify a command 
that undoes the effect of the client and removes
any saved state.
.NT Example
A user runs xmodmap.  xmodmap registers with the SM, sets 
.PN Restart\%Style\%Hint
to 
.PN Restart\%Anyway ,
and then terminates.  In order to allow the SM (at the
user's request) to undo this, xmodmap would register a
.PN Resign\%Command
that undoes the effects of the xmodmap.
.NE
.IP RestartStyleHint 3
.RS
.LP
If the RestartStyleHint property is present, it will contain the 
style of restarting the client prefers.  If this flag isn't specified,
.PN RestartIfRunning
is assumed.
The possible values are as follows:
.br
.ne 6
.TS H
l n.
_
.sp 6p
.B
Name	Value
.R
.sp 6p
_
.sp 6p
.TH
RestartIfRunning	0
RestartAnyway	1
RestartImmediately	2
RestartNever	3
.sp 6p
_
.TE
.LP
The
.PN RestartIfRunning
style is used in the usual case.  The client should
be restarted in the next session if it is connected to the 
session manager at the end of the current session.
.LP
The
.PN RestartAnyway
style is used to tell the SM that the application
should be restarted in the next session even if it exits before the 
current session is terminated.
It should be noted that this is only a hint and the SM
will follow the policies specified by its users in determining what applications
to restart.
.LP
.NT Rationale
This can be specified by a client which supports (as MS-Windows clients
do) a means for the user to indicate while exiting that
restarting is desired.  It can also be used for clients that
spawn other clients and then go away, but which want to be
restarted.
.NE
.LP
A client that uses
.PN RestartAnyway
should also set the
.PN ResignCommand
and
.PN ShutdownCommand
properties to commands that undo the state of the client
after it exits.
.LP
The
.PN RestartImmediately
style is like
.PN RestartAnyway ,
but in addition, the
client is meant to run continuously.  If the client exits, the
SM should try to restart it in the current session.
.NT "Advice to Implementors"
It would be wise to sanity-check the frequency which which
.PN RestartImmediately
clients are restarted, to avoid a sick
client being restarted continuously.
.NE
The
.PN RestartNever
style specifies that the client 
does not wish to be restarted in the next session.
.NT "Advice To Implementors"
This should be used rarely, if at all.  It will cause the client
to be silently left out of sessions when they are restarted and
will probably be confusing to users.
.NE
.RE
.IP ShutdownCommand
This command is executed at shutdown time to clean up after a client that
is no longer running but retained its state by setting
.PN RestartStyleHint
to 
.PN RestartAnyway .
The command must not remove any saved state as the client is still part of
the session.
.NT Example
A client is run at start up time that turns on a camera.  This client then
exits.  At session shutdown, the user wants the camera turned off.  This client
would set the 
.PN Restart\%Style\%Hint
to 
.PN Restart\%Anyway
and would register a 
.PN Shutdown\%Command
that would turn off the camera.
.NE
.IP UserID 3
Specifies the user's ID.  On POSIX-based systems this
will contain the the user's name (the pw_name field of struct passwd).
.\" Finish up.
.YZ 3