DocsTable of Contents
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.
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.
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 depend 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.
This property is described in WM_CLIENT_MACHINE Property.
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.
Clients may need to respond to session manager actions in two ways:
Saving their internal state
Deleting a window
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
ClientMessage Events
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. [11]
Windows are deleted using the WM_DELETE_WINDOW protocol, which is described in Window Deletion.
The session manager properties are listed in the following table:
| Name | Type | Format | See Section |
|---|---|---|---|
| WM_CLIENT_MACHINE | TEXT | WM_CLIENT_MACHINE Property | |
| WM_COMMAND | TEXT | WM_COMMAND Property | |
| WM_STATE | WM_STATE | 32 | WM_STATE Property |
[11] This convention has changed since earlier drafts because of the introduction of the protocol in the next section. In the public review draft, there was ambiguity as to whether WM_SAVE_YOURSELF was a checkpoint or a shutdown facility. It is now unambiguously a checkpoint facility; if a shutdown facility is judged to be necessary, a separate WM_PROTOCOLS protocol will be developed and registered with the X Consortium.