C. Obsolete Session Manager Conventions

This appendix contains obsolete conventions for session management using X properties and messages. The conventions described here are deprecated, and are described only for historical interest. For further information on session management, see X Session Management Protocol.

C.1. Properties

The client communicates with the session manager by placing two properties (WM_COMMAND and WM_CLIENT_MACHINE) on its top-level window. If the client has a group of top-level windows, these properties should be placed on the group leader window.

The window manager is responsible for placing a WM_STATE property on each top-level client window for use by session managers and other clients that need to be able to identify top-level client windows and their state.

C.1.1. WM_COMMAND Property

The WM_COMMAND property represents the command used to start or restart the client. By updating this property, clients should ensure that it always reflects a command that will restart them in their current state. The content and type of the property depends on the operating system of the machine running the client. On POSIX-conformant systems using ISO Latin-1 characters for their command lines, the property should:

Be of type STRING
Contain a list of null-terminated strings
Be initialized from argv
Other systems will need to set appropriate conventions for the type and contents of WM_COMMAND properties. Window and session managers should not assume that STRING is the type of WM_COMMAND or that they will be able to understand or display its contents.

Note that WM_COMMAND strings are null-terminated and differ from the general conventions that STRING properties are null-separated. This inconsistency is necessary for backwards compatibility.

A client with multiple top-level windows should ensure that exactly one of them has a WM_COMMAND with nonzero length. Zero-length WM_COMMAND properties can be used to reply to WM_SAVE_YOURSELF messages on other top-level windows but will otherwise be ignored.

C.1.2. WM_CLIENT_MACHINE Property

This property is described in section 4.1.2.9.

C.2. Termination

Because they communicate by means of unreliable network connections, clients must be prepared for their connection to the server to be terminated at any time without warning. They cannot depend on getting notification that termination is imminent or on being able to use the server to negotiate with the user about their fate. For example, clients cannot depend on being able to put up a dialog box.

Similarly, clients may terminate at any time without notice to the session manager. When a client terminates itself rather than being terminated by the session manager, it is viewed as having resigned from the session in question, and it will not be revived if the session is revived.

C.3. Client Responses to Session Manager Actions

Clients may need to respond to session manager actions in two ways:

Saving their internal state
Deleting a window

C.3.1. Saving Client State

Clients that want to be warned when the session manager feels that they should save their internal state (for example, when termination impends) should include the atom WM_SAVE_YOURSELF in the WM_PROTOCOLS property on their top-level windows to participate in the WM_SAVE_YOURSELF protocol. They will receive a ClientMessage event as described in section 4.2.8 with the atom WM_SAVE_YOURSELF in its data[0] field.

Clients that receive WM_SAVE_YOURSELF should place themselves in a state from which they can be restarted and should update WM_COMMAND to be a command that will restart them in this state. The session manager will be waiting for a PropertyNotify event on WM_COMMAND as a confirmation that the client has saved its state. Therefore, WM_COMMAND should be updated (perhaps with a zero-length append) even if its contents are correct. No interactions with the user are permitted during this process.

Once it has received this confirmation, the session manager will feel free to terminate the client if that is what the user asked for. Otherwise, if the user asked for the session to be put to sleep, the session manager will ensure that the client does not receive any mouse or keyboard events.

After receiving a WM_SAVE_YOURSELF, saving its state, and updating WM_COMMAND, the client should not change its state (in the sense of doing anything that would require a change to WM_COMMAND) until it receives a mouse or keyboard event. Once it does so, it can assume that the danger is over. The session manager will ensure that these events do not reach clients until the danger is over or until the clients have been killed.

Irrespective of how they are arranged in window groups, clients with multiple top-level windows should ensure the following:

Only one of their top-level windows has a nonzero-length WM_COMMAND property.
They respond to a WM_SAVE_YOURSELF message by:
- First, updating the nonzero-length WM_COMMAND property, if necessary
- Second, updating the WM_COMMAND property on the window for which they received the WM_SAVE_YOURSELF message if it was not updated in the first step

Receiving WM_SAVE_YOURSELF on a window is, conceptually, a command to save the entire client state.¹⁶

C.3.2. Window Deletion

Windows are deleted using the WM_DELETE_WINDOW protocol, which is described in section 4.2.8.1.

C.4. Summary of Session Manager Property Types

The session manager properties are listed in the following table:


Name	Type	Format	See Section

WM_CLIENT_MACHINE	TEXT		4.1.2.9
WM_COMMAND	TEXT		C.1.1
WM_STATE	WM_STATE	32	4.1.3.1

Christophe Tronche, ch@tronche.com