XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll XX..OOrrgg SSttaannddaarrdd XX VVeerrssiioonn 1111,, RReelleeaassee 77 lliibbSSMM 11..11..11 Mike Wexler Kubota Pacific Computer, Inc. _A_B_S_T_R_A_C_T This document specifies a protocol that facili‐ tates the management of groups of client applica‐ tions 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. X Window System is a trademark of The Open Group. Copyright © 1992, 1993, 1994, 2002 The Open Group. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documenta‐ tion files (the ‘‘Software’’), to deal in the Software with‐ out 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 fol‐ lowing conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 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 PUR‐ POSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSOR‐ TIUM 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. ii _1_. _A_c_k_n_o_w_l_e_d_g_e_m_e_n_t_s 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 Con‐ verse, Vania Joloboff, Stuart Marks, Ralph Mor and Bob Scheifler. _2_. _D_e_f_i_n_i_t_i_o_n_s _a_n_d _G_o_a_l_s The purpose of the X Session Management Protocol (XSMP) is to provide a uniform mechanism for users to save and restore their sessions. A _s_e_s_s_i_o_n is a group of clients, each of which has a particular state. The session is controlled by a network service called the _s_e_s_s_i_o_n _m_a_n_a_g_e_r. 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 _c_l_i_e_n_t of the session man‐ ager is defined as a connection to the session manager. A client is typically, though not necessarily, a process run‐ ning 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. _3_. _O_v_e_r_v_i_e_w _o_f _t_h_e _P_r_o_t_o_c_o_l 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. Termina‐ tion 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 _c_l_i_e_n_t_‐_I_D is pro‐ vided by the protocol for the purpose of disambiguating mul‐ tiple instantiations of clients. Clients may use this ID, 11 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 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 _R_e_s_t_a_r_t_C_o_m_m_a_n_d) 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: tcp/_h_o_s_t_n_a_m_e:_p_o_r_t_n_u_m_b_e_r where the hostname is a fully qualified domain name. A Unix Domain address looks like this: local/_h_o_s_t_n_a_m_e:_p_a_t_h A DECnet address would look like this: decnet/_n_o_d_e_n_a_m_e::_o_b_j_n_a_m_e If multiple network IDs are specified, they should be sepa‐ rated by commas. 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 trans‐ port. It was decided that it would use an inde‐ pendent 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. The protocol is connection based, because there is no other way for the SM to determine reliably when clients terminate. 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 22 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 terminated when the SM exits (either normally or abnor‐ mally). To get around this would require some sort of ren‐ dezvous 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. 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 ini‐ tially connects to the SM, there are no properties set. _4_. _D_a_t_a _T_y_p_e_s 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 _B_a_d_V_a_l_u_e error message must be sent by the receiver of the message to the sender of the message. ──────────────────────────────────────────────────────────────────────────────────── _T_y_p_e _N_a_m_e _D_e_s_c_r_i_p_t_i_o_n ──────────────────────────────────────────────────────────────────────────────────── BOOL _F_a_l_s_e or _T_r_u_e INTERACT_STYLE _N_o_n_e, _E_r_r_o_r_s, or _A_n_y DIALOG_TYPE _E_r_r_o_r or _N_o_r_m_a_l SAVE_TYPE _G_l_o_b_a_l, _L_o_c_a_l, or _B_o_t_h 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 a counted collection of PROPERTYs. ──────────────────────────────────────────────────────────────────────────────────── 33 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 _5_. _P_r_o_t_o_c_o_l _S_e_t_u_p _a_n_d _M_e_s_s_a_g_e _F_o_r_m_a_t To start the XSMP protocol, the client sends the server an ICE _P_r_o_t_o_c_o_l_S_e_t_u_p 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. _6_. _C_l_i_e_n_t _I_d_e_n_t_i_f_i_c_a_t_i_o_n _S_t_r_i_n_g 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 _R_e_g_i_s_t_e_r_‐ _C_l_i_e_n_t and _R_e_g_i_s_t_e_r_C_l_i_e_n_t_R_e_p_l_y messages. Client IDs consist of the pieces described below. The ID is formed by concatenating the pieces in sequence, without sep‐ arator 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’. · Version. This is currently the character ‘1’. · Address type and address. The address type will be one of ‘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 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 "C6702D0B". · Time stamp. A 13‐digit decimal number specifying the number of milliseconds since 00:00:00 UTC, January 1, 1970. · Process‐ID type and process‐ID. The process‐ID type will be one of ‘1’ a POSIX process‐ID encoded as a 10‐digit decimal number. The process‐ID is the process‐ID of the session manager, not of a client. 44 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 · Sequence number. This is a four‐digit decimal number. It is incremented every time the session manager creates an ID. After reaching "9999" it wraps to "0000". 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 desir‐ able 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. _7_. _P_r_o_t_o_c_o_l 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 mes‐ sage’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. __ ││ _R_e_g_i_s_t_e_r_C_l_i_e_n_t [Client → SM] _p_r_e_v_i_o_u_s_‐_I_D: ARRAY8 Valid Responses: _R_e_g_i_s_t_e_r_C_l_i_e_n_t_R_e_p_l_y ││__ Possible Errors: _B_a_d_V_a_l_u_e (_C_a_n_C_o_n_t_i_n_u_e) 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, pre‐ vious‐ID should be of zero length. If previous‐ID is not valid, the SM will send a _B_a_d_V_a_l_u_e error message to the client. At this point the SM reverts to the register state and waits for another _R_e_g_i_s_t_e_r_C_l_i_e_n_t. The client should then send a _R_e_g_i_s_t_e_r_C_l_i_e_n_t with a null previous‐ID field. 55 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 __ ││ _R_e_g_i_s_t_e_r_C_l_i_e_n_t_R_e_p_l_y [Client ← SM] ││__ _c_l_i_e_n_t_‐_I_D: 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 _R_e_g_i_s_t_e_r_C_l_i_e_n_t 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 _R_e_g_i_s_t_e_r_C_l_i_e_n_t message, the SM must send a _S_a_v_e_Y_o_u_r_s_e_l_f mes‐ sage with type = Local, shutdown = False, interact‐style = None, and fast = False immediately after the _R_e_g_i_s_t_e_r_C_l_i_e_n_‐ _t_R_e_p_l_y. The client should respond to this like any other _S_a_v_e_Y_o_u_r_s_e_l_f message. __ ││ _S_a_v_e_Y_o_u_r_s_e_l_f [Client ← SM] _t_y_p_e: SAVE_TYPE _s_h_u_t_d_o_w_n: BOOL _i_n_t_e_r_a_c_t_‐_s_t_y_l_e: INTERACT_STYLE _f_a_s_t: BOOL Valid Responses: _S_e_t_P_r_o_p_e_r_t_i_e_s, _D_e_l_e_t_e_P_r_o_p_e_r_t_i_e_s, _G_e_t_‐ _P_r_o_p_e_r_t_i_e_s, _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e, _S_a_v_e_Y_o_u_r_s_e_l_f_P_h_a_s_e_2_R_e_‐ ││__ _q_u_e_s_t, _I_n_t_e_r_a_c_t_R_e_q_u_e_s_t 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 _S_e_t_P_r_o_p_e_r_t_i_e_s 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 per‐ mission to interact with the user by sending an _I_n_t_e_r_a_c_t_R_e_‐ _q_u_e_s_t message. After the state has been saved, or if it cannot be successfully saved, and the properties are appro‐ priately set, the client sends a _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e message. If the client wants to save additional information after all the other clients have finished changing their own state, the client should send _S_a_v_e_Y_o_u_r_s_e_l_f_P_h_a_s_e_2_R_e_q_u_e_s_t instead of _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e. The client must then freeze interaction with the user and wait until it receives a _S_a_v_e_C_o_m_p_l_e_t_e, _D_i_e, or a _S_h_u_t_d_o_w_n_C_a_n_c_e_l_l_e_d message. If interact‐style is _N_o_n_e, the client must not interact with the user while saving state. If the interact‐style is _E_r_r_o_r_s, the client may interact with the user only if an error condition arises. If interact‐style is _A_n_y, then the client may interact with the user for any purpose. This is 66 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 done by sending an _I_n_t_e_r_a_c_t_R_e_q_u_e_s_t message. The SM will send an _I_n_t_e_r_a_c_t message to each client that sent an _I_n_t_e_r_a_c_t_R_e_q_u_e_s_t. The client must postpone all interaction until it gets the _I_n_t_e_r_a_c_t message. When the client is done interacting it should send the SM an _I_n_t_e_r_a_c_t_D_o_n_e message. The _I_n_t_e_r_a_c_t_R_e_q_u_e_s_t message can be sent any time after a _S_a_v_e_Y_o_u_r_s_e_l_f and before a _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e. Unusual circumstances may dictate multiple interactions. The client may initiate as many _I_n_t_e_r_a_c_t_R_e_q_u_e_s_t − _I_n_t_e_r_a_c_t − _I_n_t_e_r_a_c_t_D_o_n_e sequences as it needs before it sends _S_a_v_e_Y_o_u_r_‐ _s_e_l_f_D_o_n_e. When a client receives _S_a_v_e_Y_o_u_r_s_e_l_f and has not yet responded _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e to a previous _S_a_v_e_Y_o_u_r_s_e_l_f, it must send a _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e and may then begin responding as appropriate to the newly received _S_a_v_e_Y_o_u_r_s_e_l_f. The type field specifies the type of information that should be saved: _G_l_o_b_a_l, _L_o_c_a_l, or _B_o_t_h. The _L_o_c_a_l type indicates that the application must update the properties to reflect its current state, send a _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e 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 _G_l_o_b_a_l type indicates that the user wants the client to commit all of its data to permanent, globally‐accessible storage. _B_o_t_h indicates that the client should do both of these. If _B_o_t_h is specified, the client should first commit the data to permanent storage before updating its SM properties. Examples If a word processor was sent a _S_a_v_e_Y_o_u_r_s_e_l_f with a type of _L_o_c_a_l, 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 _R_e_s_t_a_r_t_C_o_m_m_a_n_d property with enough informa‐ tion to find the temporary file, and its _D_i_s_c_a_r_d_‐ _C_o_m_m_a_n_d with enough information to remove it. If a word processor was sent a _S_a_v_e_Y_o_u_r_s_e_l_f with a type of _G_l_o_b_a_l, it would simply save the currently edited file. If a word processor was sent a _S_a_v_e_Y_o_u_r_s_e_l_f with a type of _B_o_t_h, 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 _R_e_s_t_a_r_t_C_o_m_m_a_n_d property with enough information to find the temporary file, and its _D_i_s_c_a_r_d_C_o_m_m_a_n_d with enough information to remove it. 77 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 Once the SM has send _S_a_v_e_Y_o_u_r_s_e_l_f to a client, it can’t send another _S_a_v_e_Y_o_u_r_s_e_l_f to that client until the client either responds with a _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e or the SM sends a _S_h_u_t_d_o_w_n_C_a_n_c_e_l_l_e_d. Advice to Implementors If the client stores local any state in a file or simi‐ lar "external" storage, it must create a distinct copy in response to each _S_a_v_e_Y_o_u_r_s_e_l_f message. It _m_u_s_t _n_o_t simply refer to a previous copy, because the SM may discard that previous saved state using a _D_i_s_c_a_r_d_C_o_m_‐ _m_a_n_d without knowing that it is needed for the new checkpoint. The shutdown field specifies whether the system is being shut down. Rationale The interaction may be different depending on whether or not shutdown is set. The client must save and then must prevent interaction until it receives a _S_a_v_e_C_o_m_p_l_e_t_e, _D_i_e, or a _S_h_u_t_d_o_w_n_C_a_n_c_e_l_l_e_d, 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 _T_r_u_e. __ ││ _S_a_v_e_Y_o_u_r_s_e_l_f_P_h_a_s_e_2 [Client ← SM] Valid Responses: _S_e_t_P_r_o_p_e_r_t_i_e_s, _D_e_l_e_t_e_P_r_o_p_e_r_t_i_e_s, _G_e_t_‐ ││__ _P_r_o_p_e_r_t_i_e_s, _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e, _I_n_t_e_r_a_c_t_R_e_q_u_e_s_t The SM sends this message to a client that has previously sent a _S_a_v_e_Y_o_u_r_s_e_l_f_P_h_a_s_e_2_R_e_q_u_e_s_t 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. Rationale Clients that manager other clients (window man‐ agers, 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 88 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 clients without being concerned with that state changing. The client writes a state file, if necessary, and, if neces‐ sary, uses _S_e_t_P_r_o_p_e_r_t_i_e_s 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 send‐ ing an _I_n_t_e_r_a_c_t_R_e_q_u_e_s_t 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 success‐ fully saved, and the properties are appropriately set, the client sends a _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e message. __ ││ _S_a_v_e_Y_o_u_r_s_e_l_f_R_e_q_u_e_s_t [Client → SM] _t_y_p_e: SAVE_TYPE _s_h_u_t_d_o_w_n: BOOL _i_n_t_e_r_a_c_t_‐_s_t_y_l_e: INTERACT_STYLE _f_a_s_t: BOOL _g_l_o_b_a_l: BOOL ││__ Valid Responses: _S_a_v_e_Y_o_u_r_s_e_l_f An application sends this to the SM to request a checkpoint. When the SM receives this request it may generate a _S_a_v_e_Y_‐ _o_u_r_s_e_l_f message in response and it may leave the fields intact. 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. If global is set to _T_r_u_e, then the resulting _S_a_v_e_Y_o_u_r_s_e_l_f should be sent to all applications. If global is set to _F_a_l_s_e, then the resulting _S_a_v_e_Y_o_u_r_s_e_l_f should be sent to the application that sent the _S_a_v_e_Y_o_u_r_s_e_l_f_R_e_q_u_e_s_t. __ ││ _I_n_t_e_r_a_c_t_R_e_q_u_e_s_t [Client → SM] _d_i_a_l_o_g_‐_t_y_p_e: DIALOG_TYPE Valid Responses: _I_n_t_e_r_a_c_t, _S_h_u_t_d_o_w_n_C_a_n_c_e_l_l_e_d ││__ Possible Errors: _B_a_d_S_t_a_t_e (_C_a_n_C_o_n_t_i_n_u_e) 99 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 During a checkpoint or session‐save operation, only one client at a time might be granted the privilege of interact‐ ing with the user. The _I_n_t_e_r_a_c_t_R_e_q_u_e_s_t message causes the SM to emit an _I_n_t_e_r_a_c_t message at some later time if the shutdown is not cancelled by another client first. The dialog‐type field specifies either _E_r_r_o_r_s, indicating that the client wants to start an error dialog or _N_o_r_m_a_l, meaning the client wishes to start a non‐error dialog. __ ││ _I_n_t_e_r_a_c_t [Client ← SM] Valid Responses: _I_n_t_e_r_a_c_t_D_o_n_e ││__ 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 _I_n_t_e_r_a_c_t_D_o_n_e message to the SM unless a shutdown cancel is received. Advice to Implementors If a client receives a ShutdownCancelled after receiving an _I_n_t_e_r_a_c_t message, but before sending a _I_n_t_e_r_a_c_t_D_o_n_e, the client should abort the inter‐ action and send a _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e. __ ││ _I_n_t_e_r_a_c_t_D_o_n_e [Client → SM] _c_a_n_c_e_l_‐_s_h_u_t_d_o_w_n: BOOL Valid Responses: _S_h_u_t_d_o_w_n_C_a_n_c_e_l_l_e_d ││__ This message is used by a client to notify the SM that it is done interacting. Setting the cancel‐shutdown field to _T_r_u_e indicates that the user has requested that the entire shutdown be cancelled. Cancel‐shutdown may only be _T_r_u_e if the corresponding _S_a_v_e_Y_‐ _o_u_r_s_e_l_f message specified _T_r_u_e for the shutdown field and _A_n_y or _E_r_r_o_r_s for the interact‐style field. Otherwise, can‐ cel‐shutdown must be _F_a_l_s_e. 1100 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 __ ││ _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e [Client → SM] _s_u_c_c_e_s_s: BOOL Valid Responses: _S_a_v_e_C_o_m_p_l_e_t_e, _D_i_e, _S_h_u_t_d_o_w_n_C_a_n_c_e_l_l_e_d ││__ This message is sent by a client to indicate that all of the properties representing its state have been updated. After sending _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e the client must wait for a _S_a_v_e_C_o_m_‐ _p_l_e_t_e, _S_h_u_t_d_o_w_n_C_a_n_c_e_l_l_e_d, or _D_i_e message before changing its state. If the _S_a_v_e_Y_o_u_r_s_e_l_f operation was successful, then the client should set the success field to _T_r_u_e; otherwise the client should set it to _F_a_l_s_e. Example If a client tries to save its state and runs out of disk space, it should return _F_a_l_s_e in the suc‐ cess field of the _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e message. __ ││ _S_a_v_e_Y_o_u_r_s_e_l_f_P_h_a_s_e_2_R_e_q_u_e_s_t [Client → SM] Valid Responses: _S_h_u_t_d_o_w_n_C_a_n_c_e_l_l_e_d, _S_a_v_e_Y_o_u_r_s_e_l_f_P_h_a_s_e_2 ││__ 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. __ ││ _D_i_e [Client ← SM] ││__ Valid Responses: _C_o_n_n_e_c_t_i_o_n_C_l_o_s_e_d When the SM wants a client to die it sends a _D_i_e message. Before the client dies it responds by sending a _C_o_n_n_e_c_t_i_o_n_‐ _C_l_o_s_e_d message and may then close its connection to the SM at any time. __ ││ _S_a_v_e_C_o_m_p_l_e_t_e [Client ← SM] ││__ Valid Responses: When the SM is done with a checkpoint, it will send each of the clients a _S_a_v_e_C_o_m_p_l_e_t_e message. The client is then free 1111 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 to change its state. __ ││││__ _S_h_u_t_d_o_w_n_C_a_n_c_e_l_l_e_d [Client ← SM] The shutdown currently in process has been aborted. The client can now continue as if the shutdown had never hap‐ pened. If the client has not sent _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e yet, the client can either abort the save and send _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e with the success field set to _F_a_l_s_e, or it can continue with the save and send a _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e with the success field set to reflect the outcome of the save. __ ││ _C_o_n_n_e_c_t_i_o_n_C_l_o_s_e_d [Client → SM] ││__ _r_e_a_s_o_n: 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 sys‐ tem) should be forwarded to the SM here, one ARRAY8 per line of the message. It is the responsibility of the SM to dis‐ play this reason to the user. After sending this message, the client must not send any additional XSMP messages to the SM. Advice to Implementors If additional messages are received, they should be discarded. Rationale The reason for sending the _C_o_n_n_e_c_t_i_o_n_C_l_o_s_e_d mes‐ sage before actually closing the connections is that some transport protocols will not provide immediate notification of connection closure. 1122 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 __ ││ _S_e_t_P_r_o_p_e_r_t_i_e_s [Client → SM] ││__ _p_r_o_p_e_r_t_i_e_s: LISTofPROPERTY Sets the specified properties to the specified values. Existing properties not specified in the _S_e_t_P_r_o_p_e_r_t_i_e_s mes‐ sage are unaffected. Some properties have predefined seman‐ tics. 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 organiza‐ tions, 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. __ ││ _D_e_l_e_t_e_P_r_o_p_e_r_t_i_e_s [Client → SM] ││__ _p_r_o_p_e_r_t_y_‐_n_a_m_e_s: LISTofARRAY8 Removes the named properties. __ ││ _G_e_t_P_r_o_p_e_r_t_i_e_s [Client → SM] ││__ Valid Responses: _G_e_t_P_r_o_p_e_r_t_i_e_s_R_e_p_l_y Requests that the SM respond with the values of all the properties for this client. __ ││ _G_e_t_P_r_o_p_e_r_t_i_e_s_R_e_p_l_y [Client ← SM] ││__ _v_a_l_u_e_s: LISTofPROPERTY This message is sent in reply to a _G_e_t_P_r_o_p_e_r_t_i_e_s message and includes the values of all the properties. _8_. _E_r_r_o_r_s 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: _B_a_d_V_a_l_u_e and _B_a_d_S_t_a_t_e. These are both defined in the ICE protocol. 1133 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 Any message received out‐of‐sequence will generate a _B_a_d_‐ _S_t_a_t_e error message. _9_. _S_t_a_t_e _D_i_a_g_r_a_m_s These state diagrams are designed to cover all actions of both the client and the SM. _9_._1_. _C_l_i_e_n_t _S_t_a_t_e _D_i_a_g_r_a_m _s_t_a_r_t_: ICE protocol setup complete → register _r_e_g_i_s_t_e_r_: send RReeggiisstteerrCClliieenntt → collect‐id _c_o_l_l_e_c_t_‐_i_d_: receive RReeggiisstteerrCClliieennttRReeppllyy → idle _s_h_u_t_d_o_w_n_‐_c_a_n_c_e_l_l_e_d_: send SSaavveeYYoouurrsseellffDDoonnee → idle _i_d_l_e_: [Undoes any freeze of interaction with user.] receive DDiiee → die receive SSaavveeYYoouurrsseellff → freeze‐interaction send GGeettPPrrooppeerrttiieess → idle receive GGeettPPrrooppeerrttiieessRReeppllyy → idle send SSeettPPrrooppeerrttiieess → idle send DDeelleetteePPrrooppeerrttiieess → idle send CCoonnnneeccttiioonnCClloosseedd → connection‐closed send SSaavveeYYoouurrsseellffRReeqquueesstt → idle _d_i_e_: send CCoonnnneeccttiioonnCClloosseedd → connection‐closed _f_r_e_e_z_e_‐_i_n_t_e_r_a_c_t_i_o_n_: freeze interaction with user → save‐yourself 1144 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 _s_a_v_e_‐_y_o_u_r_s_e_l_f_: receive SShhuuttddoowwnnCCaanncceelllleedd → shutdown‐cancelled send SSeettPPrrooppeerrttiieess → save‐yourself send DDeelleetteePPrrooppeerrttiieess → save‐yourself send GGeettPPrrooppeerrttiieess → save‐yourself receive GGeettPPrrooppeerrttiieessRReeppllyy → save‐yourself send IInntteerraaccttRReeqquueesstt → interact‐request send SSaavveeYYoouurrsseellffPPhhaassee22RReeqquueesstt ‐> waiting‐for‐phase2 if shutdown mode: send SSaavveeYYoouurrsseellffDDoonnee → save‐yourself‐done otherwise: send SSaavveeYYoouurrsseellffDDoonnee → idle _w_a_i_t_i_n_g_‐_f_o_r_‐_p_h_a_s_e_2_: receive SShhuuttddoowwnnCCaanncceelllleedd → shutdown‐cancelled receive SSaavveeYYoouurrsseellffPPhhaassee22 → phase2 _p_h_a_s_e_2_: receive SShhuuttddoowwnnCCaanncceelllleedd → shutdown‐cancelled send SSeettPPrrooppeerrttiieess → save‐yourself send DDeelleetteePPrrooppeerrttiieess → save‐yourself send GGeettPPrrooppeerrttiieess → save‐yourself receive GGeettPPrrooppeerrttiieessRReeppllyy → save‐yourself send IInntteerraaccttRReeqquueesstt → interact‐request (errors only) if shutdown mode: send SSaavveeYYoouurrsseellffDDoonnee → save‐yourself‐done otherwise: send SSaavveeYYoouurrsseellffDDoonnee → idle _i_n_t_e_r_a_c_t_‐_r_e_q_u_e_s_t_: receive IInntteerraacctt → interact receive SShhuuttddoowwnnCCaanncceelllleedd → shutdown‐cancelled _i_n_t_e_r_a_c_t_: send IInntteerraaccttDDoonnee → save‐yourself receive SShhuuttddoowwnnCCaanncceelllleedd → shutdown‐cancelled _s_a_v_e_‐_y_o_u_r_s_e_l_f_‐_d_o_n_e_: (changing state is forbidden) receive SSaavveeCCoommpplleettee → idle receive DDiiee → die receive SShhuuttddoowwnnCCaanncceelllleedd → idle 1155 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 _c_o_n_n_e_c_t_i_o_n_‐_c_l_o_s_e_d_: client stops participating in session _9_._2_. _S_e_s_s_i_o_n _M_a_n_a_g_e_r _S_t_a_t_e _D_i_a_g_r_a_m _s_t_a_r_t_: receive PPrroottooccoollSSeettuupp → protocol‐setup _p_r_o_t_o_c_o_l_‐_s_e_t_u_p_: send PPrroottooccoollSSeettuuppRReeppllyy → register _r_e_g_i_s_t_e_r_: receive RReeggiisstteerrCClliieenntt → acknowledge‐register _a_c_k_n_o_w_l_e_d_g_e_‐_r_e_g_i_s_t_e_r_: send RReeggiisstteerrCClliieennttRReeppllyy → idle _i_d_l_e_: receive SSeettPPrrooppeerrttiieess → idle receive DDeelleetteePPrrooppeerrttiieess → idle receive CCoonnnneeccttiioonnCClloosseedd → start receive GGeettPPrrooppeerrttiieess → get‐properties receive SSaavveeYYoouurrsseellffRReeqquueesstt → save‐yourself send SSaavveeYYoouurrsseellff → saving‐yourself _s_a_v_e_‐_y_o_u_r_s_e_l_f_: send SSaavveeYYoouurrsseellff → saving‐yourself _g_e_t_‐_p_r_o_p_e_r_t_i_e_s_: send GGeettPPrrooppeerrttiieessRReeppllyy → idle _s_a_v_i_n_g_‐_g_e_t_‐_p_r_o_p_e_r_t_i_e_s_: send GGeettPPrrooppeerrttiieessRReeppllyy → saving‐yourself 1166 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 _s_a_v_i_n_g_‐_y_o_u_r_s_e_l_f_: receive IInntteerraaccttRReeqquueesstt → saving‐yourself send IInntteerraacctt → saving‐yourself send SShhuuttddoowwnnCCaanncceelllleedd ‐> idle receive IInntteerraaccttDDoonnee → saving‐yourself receive SSeettPPrrooppeerrttiieess → saving‐yourself receive DDeelleetteePPrrooppeerrttiieess → saving‐yourself receive GGeettPPrrooppeerrttiieess → saving‐get‐properties receive SSaavveeYYoouurrsseellffPPhhaassee22RReeqquueesstt → start‐phase2 receive SSaavveeYYoouurrsseellffDDoonnee → save‐yourself‐done _s_t_a_r_t_‐_p_h_a_s_e_2_: If all clients have sent either SSaavveeYYoouurrsseellffPPhhaassee22RReeqquueesstt or SSaavveeYYoouurrsseellffDDoonnee: send SSaavveeYYoouurrsseellffPPhhaassee22 → phase2 else → saving‐yourself _p_h_a_s_e_2_: receive IInntteerraaccttRReeqquueesstt → saving‐yourself send IInntteerraacctt → saving‐yourself send SShhuuttddoowwnnCCaanncceelllleedd ‐> idle receive IInntteerraaccttDDoonnee → saving‐yourself receive SSeettPPrrooppeerrttiieess → saving‐yourself receive DDeelleetteePPrrooppeerrttiieess → saving‐yourself receive GGeettPPrrooppeerrttiieess → saving‐get‐properties receive SSaavveeYYoouurrsseellffDDoonnee → save‐yourself‐done _s_a_v_e_‐_y_o_u_r_s_e_l_f_‐_d_o_n_e_: If all clients are saved: If shutting down: send DDiiee → die otherwise send SSaavveeCCoommpplleettee → idle If some clients are not saved: → saving‐yourself _d_i_e_: SM stops accepting connections _1_0_. _P_r_o_t_o_c_o_l _E_n_c_o_d_i_n_g 1177 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 _1_0_._1_. _T_y_p_e_s BOOL 0 False 1 True INTERACT_STYLE 0 None 1 Errors 2 Any DIALOG_TYPE 0 Error 1 Normal SAVE_TYPE 0 Global 1 Local 2 Both ARRAY8 4 CARD32 length n LISTofCARD8 the array p p = pad (4 + n, 8) LISTofARRAY8 4 CARD32 count 4 unused a ARRAY8 first array b ARRAY8 second array . . . q ARRAY8 last array PROPERTY a ARRAY8 name b ARRAY8 type (XPCS encoded in Latin‐1, case sensitive) c LISTofARRAY8 values LISTofPROPERTY 4 CARD32 count 4 unused a PROPERTY first property b PROPERTY second property . . . q PROPERTY last property _1_0_._2_. _M_e_s_s_a_g_e_s XSMP is a sub‐protocol of ICE. The major opcode is assigned at run‐time by ICE and is represented here by ‘?’. 1188 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 To start the XSMP protocol, the client sends the server an ICE _P_r_o_t_o_c_o_l_S_e_t_u_p message. The protocol‐name field should be specified as "XSMP", 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. In _P_r_o_t_o_c_o_l_R_e_p_l_y message sent by the session manager, the XSMP protocol defines the vendor parameter as product iden‐ tification of the session manager, and defines the release parameter as the software release identification of the ses‐ sion manager. The session manager should supply this infor‐ mation in the ICE _P_r_o_t_o_c_o_l_R_e_p_l_y message. _R_e_g_i_s_t_e_r_C_l_i_e_n_t 1 ? XSMP 1 1 opcode 2 unused 4 a/8 length of remaining data in 8‐byte units a ARRAY8 previous‐ID _R_e_g_i_s_t_e_r_C_l_i_e_n_t_R_e_p_l_y 1 ? XSMP 1 2 opcode 2 unused 4 a/8 length of remaining data in 8‐byte units a ARRAY8 client‐ID _S_a_v_e_Y_o_u_r_s_e_l_f 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 _S_a_v_e_Y_o_u_r_s_e_l_f_R_e_q_u_e_s_t 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 1199 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 _I_n_t_e_r_a_c_t_R_e_q_u_e_s_t 1 ? XSMP 1 5 opcode 1 DIALOG_TYPE dialog type 1 unused 4 0 length of remaining data in 8‐byte units _I_n_t_e_r_a_c_t 1 ? XSMP 1 6 opcode 2 unused 4 0 length of remaining data in 8‐byte units _I_n_t_e_r_a_c_t_D_o_n_e 1 ? XSMP 1 7 opcode 1 BOOL cancel‐shutdown 1 unused 4 0 length of remaining data in 8‐byte units _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e 1 ? XSMP 1 8 opcode 1 BOOL success 1 unused 4 0 length of remaining data in 8‐byte units _D_i_e 1 ? XSMP 1 9 opcode 2 unused 4 0 length of remaining data in 8‐byte units _S_h_u_t_d_o_w_n_C_a_n_c_e_l_l_e_d 1 ? XSMP 1 10 opcode 2 unused 4 0 length of remaining data in 8‐byte units _C_o_n_n_e_c_t_i_o_n_C_l_o_s_e_d 1 ? XSMP 1 11 opcode 2 unused 4 a/8 length of remaining data in 8‐byte units a LISTofARRAY8 reason _S_e_t_P_r_o_p_e_r_t_i_e_s 1 ? XSMP 1 12 opcode 2 unused 4 a/8 length of remaining data in 8‐byte units a LISTofPROPERTY properties 2200 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 _D_e_l_e_t_e_P_r_o_p_e_r_t_i_e_s 1 ? XSMP 1 13 opcode 2 unused 4 a/8 length of remaining data in 8‐byte units a LISTofARRAY8 properties _G_e_t_P_r_o_p_e_r_t_i_e_s 1 ? XSMP 1 14 opcode 2 unused 4 0 length of remaining data in 8‐byte units _G_e_t_P_r_o_p_e_r_t_i_e_s_R_e_p_l_y 1 ? XSMP 1 15 opcode 2 unused 4 a/8 length of remaining data in 8‐byte units a LISTofPROPERTY properties _S_a_v_e_Y_o_u_r_s_e_l_f_P_h_a_s_e_2_R_e_q_u_e_s_t 1 ? XSMP 1 16 opcode 2 unused 4 0 length of remaining data in 8‐byte units _S_a_v_e_Y_o_u_r_s_e_l_f_P_h_a_s_e_2 1 ? XSMP 1 17 opcode 2 unused 4 0 length of remaining data in 8‐byte units _S_a_v_e_C_o_m_p_l_e_t_e 1 ? XSMP 1 18 opcode 2 unused 4 0 length of remaining data in 8‐byte units _1_1_. _P_r_e_d_e_f_i_n_e_d _P_r_o_p_e_r_t_i_e_s 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 con‐ nects with the SM. The properties must be set after the client sends _R_e_g_i_s_t_e_r_C_l_i_e_n_t and before the client sends _S_a_v_e_Y_o_u_r_s_e_l_f_D_o_n_e. Otherwise, the behavior of the session manager is not defined. 2211 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 Clients may set, get, and delete nonstandard properties. The lifetime of stored properties does not extend into sub‐ sequent sessions. ────────────────────────────────────────────────────────── _N_a_m_e _T_y_p_e _P_o_s_i_x _T_y_p_e _R_e_q_u_i_r_e_d_? ────────────────────────────────────────────────────────── 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 ────────────────────────────────────────────────────────── * Required if any state is stored in an external repository (e.g., state file). CloneCommand This is like the _R_e_s_t_a_r_t_C_o_m_m_a_n_d 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 LISTofAR‐ RAY8. CurrentDirectory 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. DiscardCommand The discard command contains a command that when deliv‐ ered to the host that the client is running on (deter‐ mined 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 _R_e_s_t_a_r_t_C_o_m_m_a_n_d. On POSIX systems the type should be LISTofARRAY8. Environment On POSIX based systems, this will be of type LISTofARRAY8 where the ARRAY8s alternate between environment variable name and environment variable value. ProcessID 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 2222 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 (decimal) string. Program The name of the program that is running. On POSIX sys‐ tems this should be the first parameter passed to execve and should be of type ARRAY8. RestartCommand The restart command contains a command that when deliv‐ ered to the host that the client is running on (deter‐ mined 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. ResignCommand A client that sets the _R_e_s_t_a_r_t_S_t_y_l_e_H_i_n_t to _R_e_s_t_a_r_t_A_n_y_w_a_y uses this property to specify a command that undoes the effect of the client and removes any saved state. Example A user runs xmodmap. xmodmap registers with the SM, sets _R_e_s_t_a_r_t_S_t_y_l_e_H_i_n_t to _R_e_s_t_a_r_t_A_n_y_w_a_y, and then terminates. In order to allow the SM (at the user’s request) to undo this, xmodmap would register a _R_e_s_i_g_n_C_o_m_m_a_n_d that undoes the effects of the xmodmap. RestartStyleHint If the RestartStyleHint property is present, it will con‐ tain the style of restarting the client prefers. If this flag isn’t specified, _R_e_s_t_a_r_t_I_f_R_u_n_n_i_n_g is assumed. The possible values are as follows: ─────────────────────────── _N_a_m_e _V_a_l_u_e ─────────────────────────── RestartIfRunning 0 RestartAnyway 1 RestartImmediately 2 RestartNever 3 ─────────────────────────── The _R_e_s_t_a_r_t_I_f_R_u_n_n_i_n_g 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. 2233 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 The _R_e_s_t_a_r_t_A_n_y_w_a_y 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. Rationale This can be specified by a client which sup‐ ports (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. A client that uses _R_e_s_t_a_r_t_A_n_y_w_a_y should also set the _R_e_s_i_g_n_C_o_m_m_a_n_d and _S_h_u_t_d_o_w_n_C_o_m_m_a_n_d properties to commands that undo the state of the client after it exits. The _R_e_s_t_a_r_t_I_m_m_e_d_i_a_t_e_l_y style is like _R_e_s_t_a_r_t_A_n_y_w_a_y, 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. Advice to Implementors It would be wise to sanity‐check the frequency which which _R_e_s_t_a_r_t_I_m_m_e_d_i_a_t_e_l_y clients are restarted, to avoid a sick client being restarted continuously. The _R_e_s_t_a_r_t_N_e_v_e_r style specifies that the client does not wish to be restarted in the next session. 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 prob‐ ably be confusing to users. 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 _R_e_s_t_a_r_t_S_t_y_l_e_H_i_n_t to _R_e_s_t_a_r_t_A_n_y_w_a_y. The command must not remove any saved state as the client is still part of the session. 2244 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 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 _R_e_s_t_a_r_t_S_t_y_l_e_H_i_n_t to _R_e_s_t_a_r_t_A_n_y_w_a_y and would register a _S_h_u_t_d_o_w_n_C_o_m_m_a_n_d that would turn off the camera. UserID Specifies the user’s ID. On POSIX‐based systems this will contain the the user’s name (the pw_name field of struct passwd). 2255 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 2266 XX SSeessssiioonn MMaannaaggeemmeenntt PPrroottooccooll lliibbSSMM 11..11..11 TTaabbllee ooff CCoonntteennttss 1. Acknowledgements ................................... 1 2. Definitions and Goals .............................. 1 3. Overview of the Protocol ........................... 1 4. Data Types ......................................... 3 5. Protocol Setup and Message Format .................. 4 6. Client Identification String ....................... 4 7. Protocol ........................................... 5 8. Errors ............................................. 13 9. State Diagrams ..................................... 14 9.1. Client State Diagram ............................. 14 9.2. Session Manager State Diagram .................... 16 10. Protocol Encoding ................................. 17 10.1. Types ........................................... 18 10.2. Messages ........................................ 18 11. Predefined Properties ............................. 21 iii