X Session Management Protocol

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.

The purpose of the X Session Management Protocol (XSMP) is to provide a uniform mechanism for users to save and restore their sessions. A session is a group of clients, each of which has a particular state. The session is controlled by a network service called the session manager. 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.

For purposes of this protocol, a client 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.

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.

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.

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 client-ID 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 RestartCommand) 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.

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:

where the hostname is a fully qualified domain name. A Unix Domain address looks like this:

A DECnet address would look like this:

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

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.

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.

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.

If an invalid value is specified for a field of any of the enumerated types, a BadValue error message must be sent by the receiver of the message to the sender of the message.

To start the XSMP protocol, the client sends the server an ICE 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.

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 Register­Client and Register­ClientReply messages.

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'.

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.

RegisterClient [Client → SM]

  previous-ID: ARRAY8

  Valid Responses: RegisterClientReply

  Possible Errors: BadValue (CanContinue)
  

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.

If previous-ID is not valid, the SM will send a BadValue error message to the client. At this point the SM reverts to the register state and waits for another RegisterClient The client should then send a RegisterClient with a null previous-ID field.

RegisterClientReply [Client ← SM]

  client-ID: ARRAY8
  

The client-ID specifies a unique identification for this client. If the client had specified an ID in the previous-ID field of the 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.

If the client didn't supply a previous-ID field to the Register­Client message, the SM must send a SaveYourself message with type = Local, shutdown = False, interact-style = None, and fast = False immediately after the RegisterClientReply The client should respond to this like any other Save­Yourself message.

SaveYourself [Client ← SM]

  type: SAVE_TYPE
  shutdown: BOOL
  interact-style: INTERACT_STYLE
  fast: BOOL

  Valid Responses:
    SetProperties
    DeleteProperties
    GetProperties
    SaveYourselfDone
    SaveYourselfPhase2Request
    InteractRequest
  

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 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 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 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 SaveYourselfPhase2Request instead of SaveYourselfDone The client must then freeze interaction with the user and wait until it receives a SaveComplete Die or a ShutdownCancelled message.

If interact-style is None the client must not interact with the user while saving state. If the interact-style is Errors the client may interact with the user only if an error condition arises. If interact-style is Any then the client may interact with the user for any purpose. This is done by sending an Interact­Request message. The SM will send an Interact message to each client that sent an Interact­Request The client must postpone all interaction until it gets the Interact message. When the client is done interacting it should send the SM an Interact­Done message. The Interact­Request message can be sent any time after a Save­Yourself and before a Save­Yourself­Done

Unusual circumstances may dictate multiple interactions. The client may initiate as many Interact­Request - Interact - InteractDone sequences as it needs before it sends SaveYourselfDone

When a client receives Save­Yourself and has not yet responded Save­Yourself­Done to a previous Save­Yourself it must send a Save­Yourself­Done and may then begin responding as appropriate to the newly received Save­Yourself

The type field specifies the type of information that should be saved: Global Local or Both The Local type indicates that the application must update the properties to reflect its current state, send a 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 Global type indicates that the user wants the client to commit all of its data to permanent, globally-accessible storage. Both indicates that the client should do both of these. If Both is specified, the client should first commit the data to permanent storage before updating its SM properties.

The shutdown field specifies whether the system is being shut down.

The client must save and then must prevent interaction until it receives a SaveComplete Die or a Shutdown­Cancelled because anything the user does after the save will be lost.

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 True.

SaveYourselfPhase2 [Client → SM]

  Valid Responses:
    SetProperties
    DeleteProperties
    GetProperties
    SaveYourselfDone
    InteractRequest
  

The SM sends this message to a client that has previously sent a 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.

The client writes a state file, if necessary, and, if necessary, uses 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 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 SaveYourselfDone message.

SaveYourselfRequest [Client → SM]

  type: SAVE_TYPE
  shutdown: BOOL
  interact-style: INTERACT_STYLE
  fast: BOOL
  global: BOOL

  Valid Responses: SaveYourself
  

An application sends this to the SM to request a checkpoint. When the SM receives this request it may generate a SaveYourself message in response and it may leave the fields intact.

If global is set to True then the resulting SaveYourself should be sent to all applications. If global is set to False then the resulting SaveYourself should be sent to the application that sent the Save­Yourself­Request

InteractRequest [Client → SM]

  dialog-type: DIALOG_TYPE

  Valid Responses: Interact ShutdownCancelled

  Possible Errors: BadState (CanContinue)
  

During a checkpoint or session-save operation, only one client at a time might be granted the privilege of interacting with the user. The InteractRequest message causes the SM to emit an Interact message at some later time if the shutdown is not cancelled by another client first.

The dialog-type field specifies either Errors indicating that the client wants to start an error dialog or Normal meaning the client wishes to start a non-error dialog.

Interact [Client ← SM]

  Valid Responses: InteractDone
  

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 InteractDone message to the SM unless a shutdown cancel is received.

InteractDone [Client → SM]

  cancel-shutdown: BOOL

  Valid Responses: ShutdownCancelled
  

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

Setting the cancel-shutdown field to True indicates that the user has requested that the entire shutdown be cancelled. Cancel-shutdown may only be True if the corresponding SaveYourself message specified True for the shutdown field and Any or Errors for the interact-style field. Otherwise, cancel-shutdown must be False.

SaveYourselfDone [Client → SM]

  success: BOOL

  Valid Responses:
    SaveComplete
    Die
    ShutdownCancelled

  

This message is sent by a client to indicate that all of the properties representing its state have been updated. After sending SaveYourselfDone the client must wait for a SaveComplete ShutdownCancelled or Die message before changing its state. If the SaveYourself operation was successful, then the client should set the success field to True otherwise the client should set it to False.

SaveYourselfPhase2Request [Client → SM]

  Valid Responses:
    ShutdownCancelled
    SaveYourselfPhase2

  

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.

Die [Client ← SM]

  Valid Responses: ConnectionClosed
  

When the SM wants a client to die it sends a Die message. Before the client dies it responds by sending a ConnectionClosed message and may then close its connection to the SM at any time.

SaveComplete [Client → SM]

  Valid Responses:
  

When the SM is done with a checkpoint, it will send each of the clients a SaveComplete message. The client is then free to change its state.

ShutdownCancelled [Client ← SM]
  

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 SaveYourselfDone yet, the client can either abort the save and send SaveYourselfDone with the success field set to False or it can continue with the save and send a SaveYourselfDone with the success field set to reflect the outcome of the save.

ConnectionClosed [Client → SM]

  reason: LISTofARRAY8
  

Specifies that the client has decided to terminate. It should be immediately followed by closing the connection.

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.

After sending this message, the client must not send any additional XSMP messages to the SM.

SetProperties [Client → SM]

  properties: LISTofPROPERTY
  

Sets the specified properties to the specified values. Existing properties not specified in the Set­Properties message are unaffected. Some properties have predefined semantics. See section 11, “Predefined Properties.”

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.

DeleteProperties [Client → SM]

  property-names: LISTofARRAY8
  

Removes the named properties.

GetProperties [Client → SM]

  Valid Responses: GetPropertiesReply
  

Requests that the SM respond with the values of all the properties for this client.

GetPropertiesReply [Client ← SM]

  values: LISTofPROPERTY
  

This message is sent in reply to a GetProperties message and includes the values of all the properties.

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: BadValue and BadState These are both defined in the ICE protocol.

Any message received out-of-sequence will generate a BadState error message.

These state diagrams are designed to cover all actions of both the client and the SM.

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.

The required properties must be set each time a client connects with the SM. The properties must be set after the client sends RegisterClient and before the client sends SaveYourselfDone Otherwise, the behavior of the session manager is not defined.

Clients may set, get, and delete nonstandard properties. The lifetime of stored properties does not extend into subsequent sessions.

* Required if any state is stored in an external repository (e.g., state file).