diff options
| author | Alan Coopersmith <alan.coopersmith@oracle.com> | 2010-10-22 08:21:27 -0700 |
|---|---|---|
| committer | Alan Coopersmith <alan.coopersmith@oracle.com> | 2010-10-22 08:21:27 -0700 |
| commit | 29e2ac62cb6a152499d1b3f9fe871b1252f3c22f (patch) | |
| tree | 0e5ce77933f6793ae754ed782773074441ed44b3 /doc/xsmp.xml | |
| parent | c83363e83a937ba2ddd99e732bfde5f8d39bd648 (diff) | |
xsmp.xml: Line wrapping & other whitespace cleanup
Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>
Diffstat (limited to 'doc/xsmp.xml')
| -rw-r--r-- | doc/xsmp.xml | 1396 |
1 files changed, 1009 insertions, 387 deletions
diff --git a/doc/xsmp.xml b/doc/xsmp.xml index 04623da..3449aac 100644 --- a/doc/xsmp.xml +++ b/doc/xsmp.xml @@ -24,88 +24,225 @@ <affiliation><orgname>X Consortium</orgname></affiliation> <productnumber>X Version 11, Release 7</productnumber> -<legalnotice> -<para>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:</para> - -<para>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:</para> - -<para>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</para> - -<para>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.</para> - -<para>Except as contained in this notice, the name of the X Consortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium.</para> - -<para>X Window System is a trademark of The Open Group.</para> -</legalnotice> - -<abstract> -<para>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.</para> -</abstract> + <legalnotice> + <para> +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: + </para> + + <para> +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + </para> + + <para> +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. + </para> + + <para> +Except as contained in this notice, the name of the X Consortium +shall not be used in advertising or otherwise to promote the sale, use +or other dealings in this Software without prior written authorization +from the X Consortium. + </para> + + <para> +X Window System is a trademark of The Open Group. + </para> + </legalnotice> + + <abstract> + <para> +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. + </para> + </abstract> </bookinfo> <chapter id="acknowledgments"> -<title>Acknowledgments</title> - -<para>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.</para> + <title>Acknowledgments</title> + + <para> +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. + </para> </chapter> <chapter id="definitions_and_goals"> -<title>Definitions and Goals</title> - -<para>The purpose of the X Session Management Protocol (XSMP) is to provide a uniform mechanism for users to save and restore their sessions. A <emphasis remap='I'>session</emphasis> is a group of clients, each of which has a particular state. The session is controlled by a network service called the <emphasis remap='I'>session manager</emphasis>. 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.</para> - -<para>For purposes of this protocol, a <emphasis remap='I'>client</emphasis> 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.</para> - -<para>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.</para> + <title>Definitions and Goals</title> + + <para> +The purpose of the X Session Management Protocol (XSMP) is to provide +a uniform mechanism for users to save and restore their sessions. +A <emphasis remap='I'>session</emphasis> is a group of clients, each +of which has a particular state. The session is controlled by a +network service called the <emphasis remap='I'>session +manager</emphasis>. 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. + </para> + + <para> +For purposes of this protocol, a <emphasis remap='I'>client</emphasis> +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. + </para> + + <para> +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. + </para> </chapter> <chapter id="overview_of_the_protocol"> -<title>Overview of the Protocol</title> - -<para>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.</para> - -<para>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 <emphasis remap='I'>client-ID</emphasis> 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 <emphasis remap='I'>RestartCommand</emphasis>) 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.</para> - -<para>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: + <title>Overview of the Protocol</title> + + <para> +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. + </para> + + <para> +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 <emphasis remap='I'>client-ID</emphasis> 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 <emphasis remap='I'>RestartCommand</emphasis>) 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. + </para> + + <para> +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: <literallayout remap='DS'> <emphasis remap='C'>tcp/</emphasis><emphasis remap='I'>hostname</emphasis><emphasis remap='C'>:</emphasis><emphasis remap='I'>portnumber</emphasis> -</literallayout></para> - -<para>where the hostname is a fully qualified domain name. +</literallayout> +where the hostname is a fully qualified domain name. A Unix Domain address looks like this: <literallayout remap='DS'> <emphasis remap='C'>local/</emphasis><emphasis remap='I'>hostname</emphasis><emphasis remap='C'>:</emphasis><emphasis remap='I'>path</emphasis> -</literallayout></para> - -<para>A DECnet address would look like this: +</literallayout> +A DECnet address would look like this: <literallayout remap='DS'> <emphasis remap='C'>decnet/</emphasis><emphasis remap='I'>nodename</emphasis><emphasis remap='C'>::</emphasis><emphasis remap='I'>objname</emphasis> -</literallayout></para> - -<para>If multiple network IDs are specified, they should be separated by commas.</para> - -<note remap='NT'> <para>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.</para> - -<para>The protocol is connection based, because there is no other way for the SM to determine reliably when clients terminate.</para> - -<para>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).</para> - -<para>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. -</para></note> - -<para>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.</para> - -<para>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.</para> +</literallayout> + </para> + + <para> +If multiple network IDs are specified, they should be separated by commas. + </para> + + <note remap='NT'> + <para> +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. + </para> + + <para> +The protocol is connection based, because there is no other way for +the SM to determine reliably when clients terminate. + </para> + + <para> +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). + </para> + + <para> +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. + </para> + </note> + + <para> +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. + </para> + + <para> +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. + </para> </chapter> <chapter id="data_types"> -<title>Data Types</title> + <title>Data Types</title> -<para>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.</para> + <para> +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. + </para> -<para>If an invalid value is specified for a field of any of the enumerated types, a <function>BadValue</function> error message must be sent by the receiver of the message to the sender of the message.</para> + <para> +If an invalid value is specified for a field of any of the enumerated +types, a <function>BadValue</function> error message must be sent by +the receiver of the message to the sender of the message. + </para> <informaltable pgwide='0' frame='none'> <tgroup cols='2' align='center'> @@ -169,270 +306,613 @@ A Unix Domain address looks like this: </chapter> <chapter id="protocol_setup_and_message_format"> -<title>Protocol Setup and Message Format</title> - -<para>To start the XSMP protocol, the client sends the server an ICE <function>ProtocolSetup</function> 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.</para> + <title>Protocol Setup and Message Format</title> + + <para> +To start the XSMP protocol, the client sends the server an +ICE <function>ProtocolSetup</function> 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. + </para> </chapter> <chapter id="client_identification_string"> -<title>Client Identification String</title> -<para>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 <function>Register­Client</function> and <function>Register­ClientReply</function> messages.</para> - -<para>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'.</para> - -<itemizedlist mark='bullet'> + <title>Client Identification String</title> + <para> +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 <function>Register­Client</function> +and <function>Register­ClientReply</function> messages. + </para> + + <para> +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'. + </para> + + <itemizedlist mark='bullet'> <listitem><para>Version. This is currently the character '1'.</para></listitem> - <listitem><para>Address type and address. The address type will be one of + <listitem> + <para>Address type and address. The address type will be one of <literallayout remap='DS'> '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 </literallayout> -</para> - -<para>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".</para> - </listitem> - <listitem><para>Time stamp. A 13-digit decimal number specifying the number of milliseconds since 00:00:00 UTC, January 1, 1970.</para></listitem> - <listitem><para>Process-ID type and process-ID. The process-ID type will be one of + </para> + + <para> +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". + </para> + </listitem> + <listitem><para> + Time stamp. A 13-digit decimal number specifying + the number of milliseconds since 00:00:00 UTC, January 1, 1970. + </para></listitem> + <listitem> + <para> + Process-ID type and process-ID. The process-ID type will be one of <literallayout remap='DS'> '1' a POSIX process-ID encoded as a 10-digit decimal number. -</literallayout> </para> -<para>The process-ID is the process-ID of the session manager, not of a client.</para></listitem> - <listitem><para>Sequence number. This is a four-digit decimal number. It is incremented every time the session manager creates an ID. After reaching "Q9999" it wraps to "Q0000".</para> -<note remap='NT'> -<para>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. </para> -</note> - </listitem> -</itemizedlist> +</literallayout> + </para> + <para> +The process-ID is the process-ID of the session manager, not of a client. + </para> + </listitem> + <listitem> + <para> +Sequence number. This is a four-digit decimal number. It is +incremented every time the session manager creates an ID. After +reaching "Q9999" it wraps to "Q0000". + </para> + <note remap='NT'> + <para> +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. + </para> + </note> + </listitem> + </itemizedlist> </chapter> <chapter id="protocol"> -<title>Protocol</title> -<para>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.</para> - -<para><function>RegisterClient</function> [Client -> SM]</para> - -<para><emphasis remap='I'>previous-ID</emphasis>: ARRAY8</para> - -<para>Valid Responses: <function>RegisterClientReply</function></para> - -<para>Possible Errors: <function>BadValue</function> (<symbol role='Pn'>CanContinue</symbol>)</para> - -<para>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.</para> - -<para>If previous-ID is not valid, the SM will send a <function>BadValue</function> error message to the client. At this point the SM reverts to the register state and waits for another <function>RegisterClient</function> The client should then send a <function>RegisterClient</function> with a null previous-ID field.</para> - -<para><function>RegisterClientReply</function> [Client >- SM]</para> - -<para><emphasis remap='I'>client-ID</emphasis>: ARRAY8</para> - -<para>The client-ID specifies a unique identification for this client. If the client had specified an ID in the previous-ID field of the <function>RegisterClient</function> 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.</para> - -<para>If the client didn't supply a previous-ID field to the <function>Register­Client</function> message, the SM must send a <function>SaveYourself</function> message with type = Local, shutdown = False, interact-style = None, and fast = False immediately after the <function>RegisterClientReply</function> The client should respond to this like any other <function>Save­Yourself</function> message.</para> - -<para><function>SaveYourself</function> [Client >- SM]</para> - -<para><emphasis remap='I'>type</emphasis>: SAVE_TYPE</para> -<para><emphasis remap='I'>shutdown</emphasis>: BOOL</para> -<para><emphasis remap='I'>interact-style</emphasis>: INTERACT_STYLE</para> -<para><emphasis remap='I'>fast</emphasis>: BOOL</para> - -<para>Valid Responses: -<function>SetProperties</function> -<function>DeleteProperties</function> -<function>GetProperties</function> -<function>SaveYourselfDone</function> -<function>SaveYourselfPhase2Request</function> -<function>InteractRequest</function></para> - -<para>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 <function>SetProperties</function> 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 <function>InteractRequest</function> message. After the state has been saved, or if it cannot be successfully saved, and the properties are appropriately set, the client sends a <function>SaveYourselfDone</function> message. If the client wants to save additional information after all the other clients have finished changing their own state, the client should send <function>SaveYourselfPhase2Request</function> instead of <function>SaveYourselfDone</function> The client must then freeze interaction with the user and wait until it receives a <function>SaveComplete</function> <function>Die</function> or a <function>ShutdownCancelled</function> message.</para> - -<para>If interact-style is <function>None</function> the client must not interact with the user while saving state. If the interact-style is <function>Errors</function> the client may interact with the user only if an error condition arises. If interact-style is <function>Any</function> then the client may interact with the user for any purpose. This is done by sending an <function>Interact­Request</function> message. The SM will send an <function>Interact</function> message to each client that sent an <function>Interact­Request</function> The client must postpone all interaction until it gets the <function>Interact</function> message. When the client is done interacting it should send the SM an <function>Interact­Done</function> message. The <function>Interact­Request</function> message can be sent any time after a <function>Save­Yourself</function> and before a <function>Save­Yourself­Done</function></para> - -<para>Unusual circumstances may dictate multiple interactions. The client may initiate as many <function>Interact­Request</function> - <function>Interact</function> - <function>InteractDone</function> sequences as it needs before it sends <function>SaveYourselfDone</function></para> - -<para>When a client receives <function>Save­Yourself</function> and has not yet responded <function>Save­Yourself­Done</function> to a previous <function>Save­Yourself</function> it must send a <function>Save­Yourself­Done</function> and may then begin responding as appropriate to the newly received <function>Save­Yourself</function></para> - -<para>The type field specifies the type of information that should be saved: <function>Global</function> <function>Local</function> or <function>Both</function> The <function>Local</function> type indicates that the application must update the properties to reflect its current state, send a <function>Save­Yourself­Done</function> 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 <function>Global</function> type indicates that the user wants the client to commit all of its data to permanent, globally-accessible storage. <function>Both</function> indicates that the client should do both of these. If <function>Both</function> is specified, the client should first commit the data to permanent storage before updating its SM properties.</para> - -<note remap='NT'> -<para>If a word processor was sent a <function>SaveYourself</function> with a type of <function>Local</function> 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 <function>Restart­Command</function> property with enough information to find the temporary file, and its <function>Discard­Command</function> with enough information to remove it.</para> - -<para>If a word processor was sent a <function>SaveYourself</function> with a type of <function>Global</function> it would simply save the currently edited file.</para> - -<para>If a word processor was sent a <function>SaveYourself</function> with a type of <function>Both</function> 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 <function>Restart­Command</function> property with enough information to find the temporary file, and its <function>Discard­Command</function> with enough information to remove it.</para> - -<para>Once the SM has send <function>SaveYourself</function> to a client, it can't send another <function>SaveYourself</function> to that client until the client either responds with a <function>SaveYourselfDone</function> or the SM sends a <function>ShutdownCancelled</function> </para> -</note> - -<note remap='NT'> -<para>If the client stores local any state in a file or similar "Qexternal" storage, it must create a distinct copy in response to each <function>SaveYourself</function> message. It <emphasis remap='I'>must not</emphasis> simply refer to a previous copy, because the SM may discard that previous saved state using a <function>DiscardCommand</function> without knowing that it is needed for the new checkpoint. </para> -</note> - -<para>The shutdown field specifies whether the system is being shut down.</para> -<note remap='NT'> -<para>The interaction may be different depending on whether or not shutdown is set. </para> -</note> -<para>The client must save and then must prevent interaction until it receives a <function>SaveComplete</function> <function>Die</function> or a <function>Shutdown­Cancelled</function> because anything the user does after the save will be lost.</para> - -<para>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 <function>True</function></para> - -<para><function>SaveYourselfPhase2</function> [Client -> SM]</para> - -<para>Valid Responses: -<function>SetProperties</function> -<function>DeleteProperties</function> -<function>GetProperties</function> -<function>SaveYourselfDone</function> -<function>InteractRequest</function></para> - -<para>The SM sends this message to a client that has previously sent a <function>SaveYourselfPhase2Request</function> 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.</para> - -<note remap='NT'> -<para>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. </para> -</note> -<para>The client writes a state file, if necessary, and, if necessary, uses <function>SetProperties</function> 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 <function>InteractRequest</function> 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 <function>SaveYourselfDone</function> message.</para> - -<para><function>SaveYourselfRequest</function> [Client -> SM]</para> - -<para><emphasis remap='I'>type</emphasis>: SAVE_TYPE</para> -<para><emphasis remap='I'>shutdown</emphasis>: BOOL</para> -<para><emphasis remap='I'>interact-style</emphasis>: INTERACT_STYLE</para> -<para><emphasis remap='I'>fast</emphasis>: BOOL</para> -<para><emphasis remap='I'>global</emphasis>: BOOL</para> - -<para>Valid Responses: <function>SaveYourself</function></para> - -<para>An application sends this to the SM to request a checkpoint. When the SM receives this request it may generate a <function>SaveYourself</function> message in response and it may leave the fields intact.</para> - -<note remap='NT'> <para>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. </para></note> - -<para>If global is set to <function>True</function> then the resulting <function>SaveYourself</function> should be sent to all applications. If global is set to <function>False</function> then the resulting <function>SaveYourself</function> should be sent to the application that sent the <function>Save­Yourself­Request</function></para> - -<para><function>InteractRequest</function> [Client -> SM]</para> - -<para><emphasis remap='I'>dialog-type</emphasis>: DIALOG_TYPE</para> - -<para>Valid Responses: <function>Interact</function> <function>ShutdownCancelled</function></para> - -<para>Possible Errors: <function>BadState</function> (<symbol role='Pn'>CanContinue</symbol>)</para> - -<para>During a checkpoint or session-save operation, only one client at a time might be granted the privilege of interacting with the user. The <function>InteractRequest</function> message causes the SM to emit an <function>Interact</function> message at some later time if the shutdown is not cancelled by another client first.</para> - -<para>The dialog-type field specifies either <function>Errors</function> indicating that the client wants to start an error dialog or <function>Normal</function> meaning the client wishes to start a non-error dialog.</para> - -<para><function>Interact</function> [Client >- SM]</para> - -<para>Valid Responses: <function>InteractDone</function></para> - -<para>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 <function>InteractDone</function> message to the SM unless a shutdown cancel is received.</para> -<note remap='NT'> <para>If a client receives a ShutdownCancelled after receiving an <function>Interact</function> message, but before sending a <function>InteractDone</function> the client should abort the interaction and send a <function>SaveYourselfDone</function> </para></note> - -<para><function>InteractDone</function> [Client -> SM]</para> - -<para><emphasis remap='I'>cancel-shutdown</emphasis>: BOOL</para> - -<para>Valid Responses: <function>ShutdownCancelled</function></para> - -<para>This message is used by a client to notify the SM that it is done interacting.</para> - -<para>Setting the cancel-shutdown field to <function>True</function> indicates that the user has requested that the entire shutdown be cancelled. Cancel-shutdown may only be <function>True</function> if the corresponding <function>SaveYourself</function> message specified <function>True</function> for the shutdown field and <function>Any</function> or <function>Errors</function> for the interact-style field. Otherwise, cancel-shutdown must be <function>False</function></para> - -<para><function>SaveYourselfDone</function> [Client -> SM]</para> - -<para><emphasis remap='I'>success</emphasis>: BOOL</para> - -<para>Valid Responses: -<function>SaveComplete</function> -<function>Die</function> -<function>ShutdownCancelled</function></para> - -<para>This message is sent by a client to indicate that all of the properties representing its state have been updated. After sending <function>SaveYourselfDone</function> the client must wait for a <function>SaveComplete</function> <function>ShutdownCancelled</function> or <function>Die</function> message before changing its state. If the <function>SaveYourself</function> operation was successful, then the client should set the success field to <function>True</function> otherwise the client should set it to <function>False</function></para> - -<note remap='NT'> -<para>If a client tries to save its state and runs out of disk space, it should return <function>False</function> in the success field of the <function>SaveYourselfDone</function> message. </para> -</note> - -<para><function>SaveYourselfPhase2Request</function> [Client -> SM]</para> - -<para>Valid Responses: -<function>ShutdownCancelled</function> -<function>SaveYourselfPhase2</function></para> - -<para>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.</para> - -<para><function>Die</function> [Client >- SM]</para> - -<para>Valid Responses: <function>ConnectionClosed</function></para> - -<para>When the SM wants a client to die it sends a <function>Die</function> message. Before the client dies it responds by sending a <function>ConnectionClosed</function> message and may then close its connection to the SM at any time.</para> - -<para><function>SaveComplete</function> [Client -> SM]</para> - -<para>Valid Responses:</para> - -<para>When the SM is done with a checkpoint, it will send each of the clients a <function>SaveComplete</function> message. The client is then free to change its state.</para> - -<para><function>ShutdownCancelled</function> [Client >- SM]</para> - -<para>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 <function>SaveYourselfDone</function> yet, the client can either abort the save and send <function>SaveYourselfDone</function> with the success field set to <function>False</function> or it can continue with the save and send a <function>SaveYourselfDone</function> with the success field set to reflect the outcome of the save.</para> - -<para><function>ConnectionClosed</function> [Client -> SM]</para> - -<para><emphasis remap='I'>reason</emphasis>: LISTofARRAY8</para> - -<para>Specifies that the client has decided to terminate. It should be immediately followed by closing the connection.</para> - -<para>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.</para> - -<para>After sending this message, the client must not send any additional XSMP messages to the SM.</para> -<note remap='NT'> <para>If additional messages are received, they should be discarded. </para></note> -<note remap='NT'> -<para>The reason for sending the <function>ConnectionClosed</function> message before actually closing the connections is that some transport protocols will not provide immediate notification of connection closure. </para></note> - -<para><function>SetProperties</function> [Client -> SM]</para> - -<para><emphasis remap='I'>properties</emphasis>: LISTofPROPERTY</para> - -<para>Sets the specified properties to the specified values. Existing properties not specified in the <function>Set­Properties</function> message are unaffected. Some properties have predefined semantics. See section 11, "Predefined Properties."</para> - -<para>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.</para> - -<para><function>DeleteProperties</function> [Client -> SM]</para> - -<para><emphasis remap='I'>property-names</emphasis>: LISTofARRAY8</para> - -<para>Removes the named properties.</para> - -<para><function>GetProperties</function> [Client -> SM]</para> - -<para>Valid Responses: <function>GetPropertiesReply</function></para> - -<para>Requests that the SM respond with the values of all the properties for this client.</para> - -<para><function>GetPropertiesReply</function> [Client <- SM]</para> - -<para><emphasis remap='I'>values</emphasis>: LISTofPROPERTY</para> + <title>Protocol</title> + <para> +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. + </para> + + <para><function>RegisterClient</function> [Client -> SM]</para> + + <para><emphasis remap='I'>previous-ID</emphasis>: ARRAY8</para> + + <para>Valid Responses: <function>RegisterClientReply</function></para> + + <para>Possible Errors: <function>BadValue</function> (<symbol role='Pn'>CanContinue</symbol>)</para> + + <para> +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. + </para> + + <para> +If previous-ID is not valid, the SM will send a <function>BadValue</function> +error message to the client. At this point the SM reverts to the +register state and waits for another <function>RegisterClient</function> +The client should then send a <function>RegisterClient</function> with a +null previous-ID field. + </para> + + <para><function>RegisterClientReply</function> [Client >- SM]</para> + + <para><emphasis remap='I'>client-ID</emphasis>: ARRAY8</para> + + <para> +The client-ID specifies a unique identification for this client. If +the client had specified an ID in the previous-ID field of +the <function>RegisterClient</function> 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. + </para> + + <para> +If the client didn't supply a previous-ID field to +the <function>Register­Client</function> message, the SM must send +a <function>SaveYourself</function> message with type = Local, +shutdown = False, interact-style = None, and fast = False immediately +after the <function>RegisterClientReply</function> The client should +respond to this like any other <function>Save­Yourself</function> +message. + </para> + + <para><function>SaveYourself</function> [Client >- SM]</para> + + <para><emphasis remap='I'>type</emphasis>: SAVE_TYPE</para> + <para><emphasis remap='I'>shutdown</emphasis>: BOOL</para> + <para><emphasis remap='I'>interact-style</emphasis>: INTERACT_STYLE</para> + <para><emphasis remap='I'>fast</emphasis>: BOOL</para> + + <para>Valid Responses: + <function>SetProperties</function> + <function>DeleteProperties</function> + <function>GetProperties</function> + <function>SaveYourselfDone</function> + <function>SaveYourselfPhase2Request</function> + <function>InteractRequest</function></para> + + <para> +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 <function>SetProperties</function> 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 <function>InteractRequest</function> message. +After the state has been saved, or if it cannot be successfully saved, +and the properties are appropriately set, the client sends +a <function>SaveYourselfDone</function> message. If the client wants +to save additional information after all the other clients have +finished changing their own state, the client should +send <function>SaveYourselfPhase2Request</function> instead +of <function>SaveYourselfDone</function> The client must then freeze +interaction with the user and wait until it receives +a <function>SaveComplete</function> <function>Die</function> or +a <function>ShutdownCancelled</function> message. + </para> + + <para> +If interact-style is <function>None</function> the client must not +interact with the user while saving state. If the interact-style +is <function>Errors</function> the client may interact with the user +only if an error condition arises. If interact-style +is <function>Any</function> then the client may interact with the user +for any purpose. This is done by sending +an <function>Interact­Request</function> message. The SM will +send an <function>Interact</function> message to each client that sent +an <function>Interact­Request</function> The client must postpone +all interaction until it gets the <function>Interact</function> +message. When the client is done interacting it should send the SM +an <function>Interact­Done</function> message. +The <function>Interact­Request</function> message can be sent any +time after a <function>Save­Yourself</function> and before +a <function>Save­Yourself­Done</function> + </para> + + <para> +Unusual circumstances may dictate multiple interactions. The client +may initiate as many <function>Interact­Request</function> +- <function>Interact</function> - <function>InteractDone</function> +sequences as it needs before it sends <function>SaveYourselfDone</function> + </para> + + <para> +When a client receives <function>Save­Yourself</function> and has +not yet responded <function>Save­Yourself­Done</function> to a +previous <function>Save­Yourself</function> it must send +a <function>Save­Yourself­Done</function> and may then begin +responding as appropriate to the newly received +<function>Save­Yourself</function> +</para> -<para>This message is sent in reply to a <function>GetProperties</function> message and includes the values of all the properties.</para> + <para> +The type field specifies the type of information that should be +saved: <function>Global</function> <function>Local</function> +or <function>Both</function> The <function>Local</function> type +indicates that the application must update the properties to reflect +its current state, send +a <function>Save­Yourself­Done</function> 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 <function>Global</function> type indicates +that the user wants the client to commit all of its data to permanent, +globally-accessible storage. <function>Both</function> indicates that +the client should do both of these. If <function>Both</function> is +specified, the client should first commit the data to permanent +storage before updating its SM properties. + </para> + + <note remap='NT'> + <para> +If a word processor was sent a <function>SaveYourself</function> with +a type of <function>Local</function> 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 <function>Restart­Command</function> property with +enough information to find the temporary file, and +its <function>Discard­Command</function> with enough information +to remove it. + </para> + + <para> +If a word processor was sent a <function>SaveYourself</function> with +a type of <function>Global</function> it would simply save the +currently edited file. + </para> + + <para> +If a word processor was sent a <function>SaveYourself</function> with +a type of <function>Both</function> 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 <function>Restart­Command</function> property with enough +information to find the temporary file, and +its <function>Discard­Command</function> with enough information +to remove it. + </para> + + <para> +Once the SM has send <function>SaveYourself</function> to a client, it can't send another <function>SaveYourself</function> to that client until the client either responds with a <function>SaveYourselfDone</function> or the SM sends a <function>ShutdownCancelled</function> + </para> + </note> + + <note remap='NT'> + <para> +If the client stores local any state in a file or similar "Qexternal" +storage, it must create a distinct copy in response to +each <function>SaveYourself</function> message. +It <emphasis remap='I'>must not</emphasis> simply refer to a previous +copy, because the SM may discard that previous saved state using +a <function>DiscardCommand</function> without knowing that it is +needed for the new checkpoint. + </para> + </note> + + <para> +The shutdown field specifies whether the system is being shut down. + </para> + + <note remap='NT'> + <para> +The interaction may be different depending on whether or not shutdown is set. + </para> + </note> + + <para> +The client must save and then must prevent interaction until it +receives a <function>SaveComplete</function> <function>Die</function> +or a <function>Shutdown­Cancelled</function> because anything the +user does after the save will be lost. + </para> + + <para> +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 <function>True</function> + </para> + + <para><function>SaveYourselfPhase2</function> [Client -> SM]</para> + + <para>Valid Responses: + <function>SetProperties</function> + <function>DeleteProperties</function> + <function>GetProperties</function> + <function>SaveYourselfDone</function> + <function>InteractRequest</function></para> + + <para> +The SM sends this message to a client that has previously sent +a <function>SaveYourselfPhase2Request</function> 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. + </para> + + <note remap='NT'> + <para> +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. + </para> + </note> + <para> +The client writes a state file, if necessary, and, if necessary, +uses <function>SetProperties</function> 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 <function>InteractRequest</function> 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 <function>SaveYourselfDone</function> message. + </para> + + <para><function>SaveYourselfRequest</function> [Client -> SM]</para> + + <para><emphasis remap='I'>type</emphasis>: SAVE_TYPE</para> + <para><emphasis remap='I'>shutdown</emphasis>: BOOL</para> + <para><emphasis remap='I'>interact-style</emphasis>: INTERACT_STYLE</para> + <para><emphasis remap='I'>fast</emphasis>: BOOL</para> + <para><emphasis remap='I'>global</emphasis>: BOOL</para> + + <para>Valid Responses: <function>SaveYourself</function></para> + + <para> +An application sends this to the SM to request a checkpoint. When the +SM receives this request it may generate a <function>SaveYourself</function> +message in response and it may leave the fields intact. + </para> + + <note remap='NT'> <para> +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. + </para></note> + + <para> +If global is set to <function>True</function> then the +resulting <function>SaveYourself</function> should be sent to all +applications. If global is set to <function>False</function> then the +resulting <function>SaveYourself</function> should be sent to the +application that sent the <function>Save­Yourself­Request</function> + </para> + + <para><function>InteractRequest</function> [Client -> SM]</para> + + <para><emphasis remap='I'>dialog-type</emphasis>: DIALOG_TYPE</para> + + <para>Valid Responses: <function>Interact</function> <function>ShutdownCancelled</function></para> + + <para>Possible Errors: <function>BadState</function> (<symbol role='Pn'>CanContinue</symbol>)</para> + + <para> +During a checkpoint or session-save operation, only one client at a +time might be granted the privilege of interacting with the user. +The <function>InteractRequest</function> message causes the SM to emit +an <function>Interact</function> message at some later time if the +shutdown is not cancelled by another client first. + </para> + + <para> +The dialog-type field specifies either <function>Errors</function> +indicating that the client wants to start an error dialog +or <function>Normal</function> meaning the client wishes to start a +non-error dialog. + </para> + + <para><function>Interact</function> [Client >- SM]</para> + + <para>Valid Responses: <function>InteractDone</function></para> + + <para> +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 <function>InteractDone</function> message to the SM unless a +shutdown cancel is received. + </para> + <note remap='NT'> <para> If a client receives a ShutdownCancelled +after receiving an <function>Interact</function> message, but before +sending a <function>InteractDone</function> the client should abort +the interaction and send a <function>SaveYourselfDone</function> + </para></note> + + <para><function>InteractDone</function> [Client -> SM]</para> + + <para><emphasis remap='I'>cancel-shutdown</emphasis>: BOOL</para> + + <para>Valid Responses: <function>ShutdownCancelled</function></para> + + <para> +This message is used by a client to notify the SM that it is done interacting. + </para> + + <para> +Setting the cancel-shutdown field to <function>True</function> +indicates that the user has requested that the entire shutdown be +cancelled. Cancel-shutdown may only be <function>True</function> if +the corresponding <function>SaveYourself</function> message +specified <function>True</function> for the shutdown field +and <function>Any</function> or <function>Errors</function> for the +interact-style field. Otherwise, cancel-shutdown must +be <function>False</function> + </para> + + <para><function>SaveYourselfDone</function> [Client -> SM]</para> + + <para><emphasis remap='I'>success</emphasis>: BOOL</para> + + <para>Valid Responses: + <function>SaveComplete</function> + <function>Die</function> + <function>ShutdownCancelled</function> + </para> + + <para> +This message is sent by a client to indicate that all of the +properties representing its state have been updated. After +sending <function>SaveYourselfDone</function> the client must wait for +a <function>SaveComplete</function> <function>ShutdownCancelled</function> +or <function>Die</function> message before changing its state. If +the <function>SaveYourself</function> operation was successful, then +the client should set the success field to <function>True</function> +otherwise the client should set it to <function>False</function> + </para> + + <note remap='NT'> + <para> +If a client tries to save its state and runs out of disk space, it +should return <function>False</function> in the success field of +the <function>SaveYourselfDone</function> message. + </para> + </note> + + <para><function>SaveYourselfPhase2Request</function> [Client -> SM]</para> + + <para>Valid Responses: + <function>ShutdownCancelled</function> + <function>SaveYourselfPhase2</function> + </para> + + <para> +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. + </para> + + <para><function>Die</function> [Client >- SM]</para> + + <para>Valid Responses: <function>ConnectionClosed</function></para> + + <para> +When the SM wants a client to die it sends a <function>Die</function> +message. Before the client dies it responds by sending +a <function>ConnectionClosed</function> message and may then close its +connection to the SM at any time. + </para> + + <para><function>SaveComplete</function> [Client -> SM]</para> + + <para>Valid Responses:</para> + + <para> +When the SM is done with a checkpoint, it will send each of the +clients a <function>SaveComplete</function> message. The client is +then free to change its state. + </para> + + <para><function>ShutdownCancelled</function> [Client >- SM]</para> + + <para> +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 <function>SaveYourselfDone</function> yet, the client can +either abort the save and send <function>SaveYourselfDone</function> +with the success field set to <function>False</function> or it can +continue with the save and send a <function>SaveYourselfDone</function> +with the success field set to reflect the outcome of the save. + </para> + + <para><function>ConnectionClosed</function> [Client -> SM]</para> + + <para><emphasis remap='I'>reason</emphasis>: LISTofARRAY8</para> + + <para> +Specifies that the client has decided to terminate. It should be +immediately followed by closing the connection. + </para> + + <para> +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. + </para> + + <para> +After sending this message, the client must not send any additional +XSMP messages to the SM. + </para> + <note remap='NT'><para> +If additional messages are received, they should be discarded. + </para></note> + <note remap='NT'><para> +The reason for sending the <function>ConnectionClosed</function> +message before actually closing the connections is that some transport +protocols will not provide immediate notification of connection +closure. + </para></note> + + <para><function>SetProperties</function> [Client -> SM]</para> + + <para><emphasis remap='I'>properties</emphasis>: LISTofPROPERTY</para> + + <para> +Sets the specified properties to the specified values. Existing +properties not specified in the <function>Set­Properties</function> +message are unaffected. Some properties have predefined semantics. +See section 11, "Predefined Properties." + </para> + + <para> +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. + </para> + + <para><function>DeleteProperties</function> [Client -> SM]</para> + + <para><emphasis remap='I'>property-names</emphasis>: LISTofARRAY8</para> + + <para>Removes the named properties.</para> + + <para><function>GetProperties</function> [Client -> SM]</para> + + <para>Valid Responses: <function>GetPropertiesReply</function></para> + + <para> +Requests that the SM respond with the values of all the properties for +this client. + </para> + + <para><function>GetPropertiesReply</function> [Client <- SM]</para> + + <para><emphasis remap='I'>values</emphasis>: LISTofPROPERTY</para> + + <para> +This message is sent in reply to a <function>GetProperties</function> +message and includes the values of all the properties. + </para> </chapter> <chapter id="errors"> -<title>Errors</title> - -<para>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: <function>BadValue</function> and <function>BadState</function> -These are both defined in the ICE protocol.</para> - -<para>Any message received out-of-sequence will generate a <function>BadState</function> -error message.</para> + <title>Errors</title> + + <para> +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: +<function>BadValue</function> and <function>BadState</function> +These are both defined in the ICE protocol. + </para> + + <para> +Any message received out-of-sequence will generate +a <function>BadState</function> error message. + </para> </chapter> <chapter id="state_diagrams"> -<title>State Diagrams</title> -<para>These state diagrams are designed to cover all actions of both the client and the SM.</para> + <title>State Diagrams</title> + <para> +These state diagrams are designed to cover all actions of both the +client and the SM. + </para> -<sect1 id='client_state_diagram'> -<title>Client State Diagram</title> + <sect1 id='client_state_diagram'> + <title>Client State Diagram</title> <!-- <literallayout remap='DS'> --> <literallayout> @@ -621,13 +1101,13 @@ error message.</para> <emphasis remap='I'>die:</emphasis> SM stops accepting connections </literallayout> -</sect1> + </sect1> </chapter> <chapter id='protocol_encoding'> -<title>Protocol Encoding</title> -<sect1 id="types"> -<title>Types</title> + <title>Protocol Encoding</title> + <sect1 id="types"> + <title>Types</title> <informaltable pgwide='0' frame='all'> <tgroup cols='2' align='center'> @@ -894,15 +1374,33 @@ error message.</para> </tgroup> </informaltable> -</sect1> - -<sect1 id='messages'> -<title>Messages</title> -<para>XSMP is a sub-protocol of ICE. The major opcode is assigned at run-time by ICE and is represented here by '?'.</para> - -<para>To start the XSMP protocol, the client sends the server an ICE <function>ProtocolSetup</function> 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.</para> - -<para>In <function>ProtocolReply</function> 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 <function>ProtocolReply</function> message.</para> + </sect1> + + <sect1 id='messages'> + <title>Messages</title> + <para> +XSMP is a sub-protocol of ICE. The major opcode is assigned at +run-time by ICE and is represented here by '?'. + </para> + + <para> +To start the XSMP protocol, the client sends the server an +ICE <function>ProtocolSetup</function> 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. + </para> + + <para> +In <function>ProtocolReply</function> 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 <function>ProtocolReply</function> message. + </para> <informaltable pgwide='0' frame='all'> <tgroup cols='3' align='center'> @@ -1665,16 +2163,31 @@ error message.</para> </tgroup> </informaltable> -</sect1> + </sect1> </chapter> <chapter id='predefined_properties'> -<title>Predefined Properties</title> -<para>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.</para> - -<para>The required properties must be set each time a client connects with the SM. The properties must be set after the client sends <function>RegisterClient</function> and before the client sends <function>SaveYourselfDone</function> Otherwise, the behavior of the session manager is not defined.</para> - -<para>Clients may set, get, and delete nonstandard properties. The lifetime of stored properties does not extend into subsequent sessions.</para> + <title>Predefined Properties</title> + <para> +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. + </para> + + <para> +The required properties must be set each time a client connects with +the SM. The properties must be set after the client +sends <function>RegisterClient</function> and before the client +sends <function>SaveYourselfDone</function> Otherwise, the behavior of +the session manager is not defined. + </para> + + <para> +Clients may set, get, and delete nonstandard properties. The lifetime +of stored properties does not extend into subsequent sessions. + </para> <informaltable pgwide='0' frame='none'> <tgroup cols='4' align='center'> @@ -1761,46 +2274,101 @@ error message.</para> </tgroup> </informaltable> -<para>* Required if any state is stored in an external repository (e.g., state file).</para> - -<variablelist remap='IP'> - <varlistentry> - <term>CloneCommand</term> - <listitem> <para>This is like the <function>RestartCommand</function> 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.</para></listitem> - </varlistentry> - <varlistentry> - <term>CurrentDirectory</term> - <listitem><para>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.</para></listitem> - </varlistentry> - <varlistentry> - <term>DiscardCommand</term> - <listitem><para>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 <function>Restart­Command</function> On POSIX systems the type should be LISTofARRAY8.</para></listitem> - </varlistentry> - <varlistentry> - <term>Environment</term> - <listitem><para>On POSIX based systems, this will be of type LISTofARRAY8 where the ARRAY8s alternate between environment variable name and environment variable value.</para></listitem> - </varlistentry> - <varlistentry> - <term>ProcessID</term> - <listitem><para>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.</para></listitem> - </varlistentry> - <varlistentry> - <term>Program</term> - <listitem><para>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.</para></listitem> - </varlistentry> - <varlistentry> - <term>RestartCommand</term> - <listitem><para>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.</para></listitem> - </varlistentry> - <varlistentry> - <term>ResignCommand</term> - <listitem><para>A client that sets the <function>RestartStyleHint</function> to <function>RestartAnyway</function> uses this property to specify a command that undoes the effect of the client and removes any saved state.</para> - <note remap='NT'><para>A user runs xmodmap. xmodmap registers with the SM, sets <function>Restart­Style­Hint</function> to <function>Restart­Anyway</function> and then terminates. In order to allow the SM (at the user's request) to undo this, xmodmap would register a <function>Resign­Command</function> that undoes the effects of the xmodmap. </para></note> - </listitem> - </varlistentry> - <varlistentry> - <term>RestartStyleHint</term> - <listitem> <para>If the RestartStyleHint property is present, it will contain the style of restarting the client prefers. If this flag isn't specified, <function>RestartIfRunning</function> is assumed. The possible values are as follows:</para> + <para> +* Required if any state is stored in an external repository (e.g., state file). + </para> + + <variablelist remap='IP'> + <varlistentry> + <term>CloneCommand</term> + <listitem> <para> +This is like the <function>RestartCommand</function> 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. + </para></listitem> + </varlistentry> + <varlistentry> + <term>CurrentDirectory</term> + <listitem><para> +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. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DiscardCommand</term> + <listitem><para> +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 <function>Restart­Command</function> On +POSIX systems the type should be LISTofARRAY8. + </para></listitem> + </varlistentry> + <varlistentry> + <term>Environment</term> + <listitem><para> +On POSIX based systems, this will be of type LISTofARRAY8 where the +ARRAY8s alternate between environment variable name and environment +variable value. + </para></listitem> + </varlistentry> + <varlistentry> + <term>ProcessID</term> + <listitem><para> +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. + </para></listitem> + </varlistentry> + <varlistentry> + <term>Program</term> + <listitem><para> +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. + </para></listitem> + </varlistentry> + <varlistentry> + <term>RestartCommand</term> + <listitem><para> +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. + </para></listitem> + </varlistentry> + <varlistentry> + <term>ResignCommand</term> + <listitem> + <para> +A client that sets the <function>RestartStyleHint</function> +to <function>RestartAnyway</function> uses this property to specify a +command that undoes the effect of the client and removes any saved +state. + </para> + <note remap='NT'><para> +A user runs xmodmap. xmodmap registers with the SM, +sets <function>Restart­Style­Hint</function> +to <function>Restart­Anyway</function> and then terminates. In +order to allow the SM (at the user's request) to undo this, xmodmap +would register a <function>Resign­Command</function> that undoes +the effects of the xmodmap. + </para></note> + </listitem> + </varlistentry> + <varlistentry> + <term>RestartStyleHint</term> + <listitem> + <para> +If the RestartStyleHint property is present, it will contain the style +of restarting the client prefers. If this flag isn't +specified, <function>RestartIfRunning</function> is assumed. The +possible values are as follows: + </para> <informaltable pgwide='0' frame='none'> <tgroup cols='2' align='center'> @@ -1837,31 +2405,85 @@ error message.</para> </tgroup> </informaltable> -<para>The <function>RestartIfRunning</function> 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.</para> - -<para>The <function>RestartAnyway</function> 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.</para> - - <note remap='NT'><para>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.</para></note> - -<para>A client that uses <function>RestartAnyway</function> should also set the <function>ResignCommand</function> and <function>ShutdownCommand</function> properties to commands that undo the state of the client after it exits.</para> - -<para>The <function>RestartImmediately</function> style is like <function>RestartAnyway</function> 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.</para> -<note remap='NT'><para>It would be wise to sanity-check the frequency which which <function>RestartImmediately</function> clients are restarted, to avoid a sick client being restarted continuously.</para></note> -<para>The <function>RestartNever</function> style specifies that the client does not wish to be restarted in the next session.</para> -<note remap='NT'> <para>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.</para></note> <!-- remap='NE' --> -<!-- .RE --> - </listitem> - </varlistentry> - <varlistentry> - <term>ShutdownCommand</term> - <listitem><para>This command is executed at shutdown time to clean up after a client that is no longer running but retained its state by setting <function>RestartStyleHint</function> to <function>RestartAnyway</function> The command must not remove any saved state as the client is still part of the session.</para> -<note remap='NT'><para>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 <function>Restart­Style­Hint</function> to <function>Restart­Anyway</function> and would register a <function>Shutdown­Command</function> that would turn off the camera.</para></note> - </listitem> - </varlistentry> - <varlistentry> - <term>UserID</term> - <listitem><para>Specifies the user's ID. On POSIX-based systems this will contain the the user's name (the pw_name field of struct passwd).</para></listitem> - </varlistentry> -</variablelist> + <para> +The <function>RestartIfRunning</function> 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. + </para> + + <para> +The <function>RestartAnyway</function> 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. + </para> + + <note remap='NT'><para> +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. + </para></note> + + <para> +A client that uses <function>RestartAnyway</function> should also set +the <function>ResignCommand</function> and <function>ShutdownCommand</function> +properties to commands that undo the state of the client after it exits. + </para> + + <para> +The <function>RestartImmediately</function> style is +like <function>RestartAnyway</function> 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. + </para> + + <note remap='NT'><para> +It would be wise to sanity-check the frequency which +which <function>RestartImmediately</function> clients are restarted, +to avoid a sick client being restarted continuously. + </para></note> + + <para> +The <function>RestartNever</function> style specifies that the client +does not wish to be restarted in the next session. + </para> + + <note remap='NT'> <para> +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. + </para></note> <!-- remap='NE' --> + <!-- .RE --> + </listitem> + </varlistentry> + <varlistentry> + <term>ShutdownCommand</term> + <listitem> + <para> +This command is executed at shutdown time to clean up after a client +that is no longer running but retained its state by +setting <function>RestartStyleHint</function> +to <function>RestartAnyway</function> The command must not remove any +saved state as the client is still part of the session. + </para> + <note remap='NT'><para> +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 <function>Restart­Style­Hint</function> +to <function>Restart­Anyway</function> and would register a +<function>Shutdown­Command</function> that would turn off the camera. + </para></note> + </listitem> + </varlistentry> + <varlistentry> + <term>UserID</term> + <listitem><para> +Specifies the user's ID. On POSIX-based systems this will contain the +the user's name (the pw_name field of struct passwd). + </para></listitem> + </varlistentry> + </variablelist> </chapter> </book> |