1<?xml version="1.0" encoding="UTF-8" ?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" 4[ 5<!ENTITY % defs SYSTEM "defs.ent"> %defs; 6]> 7 8 9<!-- lifted from troff+ms+XMan by doclifter --> 10<book id="xsmp"> 11 12<bookinfo> 13 <title>X Session Management Protocol</title> 14 <subtitle>X Consortium Standard</subtitle> 15 <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo> 16 <releaseinfo>Version 1.0</releaseinfo> 17 <authorgroup> 18 <author> 19 <firstname>Mike</firstname><surname>Wexler</surname> 20 <affiliation><orgname>Kubota Pacific Computer, Inc</orgname></affiliation> 21 </author> 22 </authorgroup> 23 <copyright> 24 <year>1992</year><year>1993</year><year>1994</year><year>2002</year> 25 <holder>The Open Group</holder> 26 </copyright> 27 28 <legalnotice> 29 <para> 30Permission is hereby granted, free of charge, to any person 31obtaining a copy of this software and associated documentation files 32(the “Software”), to deal in the Software without 33restriction, including without limitation the rights to use, copy, 34modify, merge, publish, distribute, sublicense, and/or sell copies of 35the Software, and to permit persons to whom the Software is furnished 36to do so, subject to the following conditions: 37 </para> 38 39 <para> 40The above copyright notice and this permission notice shall be 41included in all copies or substantial portions of the Software. 42 </para> 43 44 <para> 45THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY 46OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 47WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 48NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY 49CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 50TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 51SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 52 </para> 53 54 <para> 55Except as contained in this notice, the name of the X Consortium 56shall not be used in advertising or otherwise to promote the sale, use 57or other dealings in this Software without prior written authorization 58from the X Consortium. 59 </para> 60 61 <para> 62X Window System is a trademark of The Open Group. 63 </para> 64 </legalnotice> 65 66 <abstract> 67 <para> 68This document specifies a protocol that facilitates the management of 69groups of client applications by a session manager. The session 70manager can cause clients to save their state, to shut down, and to be 71restarted into a previously saved state. This protocol is layered on 72top of the X.Org <acronym>ICE</acronym> protocol. 73 </para> 74 </abstract> 75 76</bookinfo> 77 78<chapter id='Acknowledgments'> 79 <title>Acknowledgments</title> 80 81 <para> 82First I would like to thank the entire <acronym>ICCCM</acronym> and Intrinsics 83working groups for the comments and suggestions. I would like to make special 84thanks to the following people (in alphabetical order), Jordan Brown, 85Ellis Cohen, Donna Converse, Vania Joloboff, Stuart Marks, Ralph Mor 86and Bob Scheifler. 87 </para> 88</chapter> 89 90<chapter id='Definitions_and_Goals'> 91 <title>Definitions and Goals</title> 92 93 <para> 94The purpose of the X Session Management Protocol (<acronym>XSMP</acronym>) is 95to provide a uniform mechanism for users to save and restore their sessions. 96A <firstterm>session</firstterm> is a group of clients, each 97of which has a particular state. The session is controlled by a 98network service called the <firstterm>session manager</firstterm>. 99The session manager issues commands to its 100clients on behalf of the user. These commands may cause clients to 101save their state or to terminate. It is expected that the client will 102save its state in such a way that the client can be restarted at a 103later time and resume its operation as if it had never been 104terminated. A client's state might include information about the file 105currently being edited, the current position of the insertion point 106within the file, or the start of an uncommitted transaction. The 107means by which clients are restarted is unspecified by this 108protocol. 109 </para> 110 111 <para> 112For purposes of this protocol, a <firstterm>client</firstterm> 113of the session manager is defined as a connection to the session 114manager. A client is typically, though not necessarily, a process 115running an application program connected to an X Window System 116display. However, a client may be connected to more than one X 117display or not be connected to any X displays at all. 118 </para> 119 120 <para> 121This protocol is layered on top of the X Consortium's <acronym>ICE</acronym> protocol and 122relies on the <acronym>ICE</acronym> protocol to handle connection management and authentication. 123 </para> 124 125</chapter> 126 127<chapter id='Overview_of_the_Protocol'> 128 <title>Overview of the Protocol</title> 129 130 <para> 131Clients use XSMP to register themselves with the session manager (SM). 132When a client starts up, it should connect to the SM. The client 133should remain connected for as long as it runs. A client may resign 134from the session by issuing the proper protocol messages before 135disconnecting. Termination of the connection without notice will be 136taken as an indication that the client died unexpectedly. 137 </para> 138 139 <para> 140Clients are expected to save their state in such a way as to allow 141multiple instantiations of themselves to be managed independently. A 142unique value called a <firstterm>client-ID</firstterm> is 143provided by the protocol for the purpose of disambiguating multiple 144instantiations of clients. Clients may use this ID, for example, as 145part of a filename in which to store the state for a particular 146instantiation. The client-ID should be saved as part of the command 147used to restart this client 148(the <property>RestartCommand</property>) so that the client 149will retain the same ID after it is restarted. Certain small pieces 150of state might also be stored in the RestartCommand. For example, an 151X11 client might place a '-twoWindow' option in its RestartCommand to 152indicate that it should start up in two window mode when it is 153restarted. 154 </para> 155 156 <para> 157The client finds the network address of the SM in a system-dependent 158way. On <acronym>POSIX</acronym> systems an environment 159variable called <envar>SESSION_MANAGER</envar> 160will contain a list of network IDs. Each id will contain the 161transport name followed by a slash and the (transport-specific) 162address. A TCP/IP address would look like this: 163 <informalexample><para> 164 <literal>tcp/</literal><replaceable>hostname</replaceable><literal>:</literal><replaceable>portnumber</replaceable> 165 </para></informalexample> 166where the hostname is a fully qualified domain name. 167A Unix Domain address looks like this: 168 <informalexample><para> 169 <literal>local/</literal><replaceable>hostname</replaceable><literal>:</literal><replaceable>path</replaceable> 170 </para></informalexample> 171A DECnet address would look like this: 172 <informalexample><para> 173 <literal>decnet/</literal><replaceable>nodename</replaceable><literal>::</literal><replaceable>objname</replaceable> 174 </para></informalexample> 175 </para> 176 177 <para> 178If multiple network IDs are specified, they should be separated by commas. 179 </para> 180 181 <note><title>Rationale</title> 182 <para> 183There was much discussion over whether the XSMP protocol should use X 184as the transport protocol or whether it should use its own independent 185transport. It was decided that it would use an independent protocol 186for several reasons. First, the Session Manager should be able to 187manage programs that do not maintain an X connection. Second, the X 188protocol is not appropriate to use as a general-purpose transport 189protocol. Third, a session might span multiple displays. 190 </para> 191 192 <para> 193The protocol is connection based, because there is no other way for 194the SM to determine reliably when clients terminate. 195 </para> 196 197 <para> 198It should be noted that this protocol introduces another single point 199of failure into the system. Although it is possible for clients to 200continue running after the SM has exited, this will probably not be 201the case in normal practice. Normally the program that starts the SM 202will consider the session to be terminated when the SM exits (either 203normally or abnormally). 204 </para> 205 206 <para> 207To get around this would require some sort of rendezvous server that 208would also introduce a single point of failure. In the absence of a 209generally available rendezvous server, XSMP is kept simple in the 210hopes of making simple reliable SMs. 211 </para> 212 </note> 213 214 <para> 215Some clients may wish to manage the programs they start. For example, 216a mail program could start a text editor for editing the text of a 217mail message. A client that does this is a session manager itself; it 218should supply the clients it starts with the appropriate connection 219information (i.e., the <envar>SESSION_MANAGER</envar> environment variable) 220that specifies a connection to itself instead of to the top level session 221manager. 222 </para> 223 224 <para> 225Each client has associated with it a list of properties. A property 226set by one client is not visible to any other client. These 227properties are used for the client to inform the SM of the client's 228current state. When a client initially connects to the SM, there are 229no properties set. 230 </para> 231</chapter> 232 233<chapter id='Data_Types'> 234 <title>Data Types</title> 235 236 <para> 237XSMP messages contain several types of data. Both the SM and the 238client always send messages in their native byte order. Thus, both 239sides may need to byte-swap the messages received. The need to do 240byte-swapping is determined at run-time by the <acronym>ICE</acronym> protocol. 241 </para> 242 243 <para> 244If an invalid value is specified for a field of any of the enumerated 245types, a <errorname>BadValue</errorname> error message must be sent by 246the receiver of the message to the sender of the message. 247 </para> 248 249<informaltable frame='topbot'> 250 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 251 <colspec colname='c1' colwidth='1.0*'/> 252 <colspec colname='c2' colwidth='3.0*'/> 253 <thead> 254 <row rowsep='1'> 255 <entry>Type Name</entry> 256 <entry>Description</entry> 257 </row> 258 </thead> 259 <tbody> 260 <row> 261 <entry>BOOL</entry> 262 <entry><para><constant>False</constant> or <constant>True</constant></para></entry> 263 </row> 264 <row> 265 <entry>INTERACT_STYLE</entry> 266 <entry><function>None</function> <function>Errors</function> or <function>Any</function></entry> 267 </row> 268 <row> 269 <entry>DIALOG_TYPE</entry> 270 <entry><function>Error</function> or <function>Normal</function></entry> 271 </row> 272 <row> 273 <entry>SAVE_TYPE</entry> 274 <entry><function>Global</function> <function>Local</function> or <function>Both</function></entry> 275 </row> 276 <row> 277 <entry>CARD8</entry> 278 <entry>a one-byte unsigned integer</entry> 279 </row> 280 <row> 281 <entry>CARD16</entry> 282 <entry>a two-byte unsigned integer</entry> 283 </row> 284 <row> 285 <entry>CARD32</entry> 286 <entry>a four-byte unsigned integer</entry> 287 </row> 288 <row> 289 <entry>ARRAY8</entry> 290 <entry>a sequence of CARD8s</entry> 291 </row> 292 <row> 293 <entry>LISTofARRAY8</entry> 294 <entry>a sequence of ARRAY8s</entry> 295 </row> 296 <row> 297 <entry>PROPERTY</entry> 298 <entry>a property name (an ARRAY8), a type name, and a value of that type</entry> 299 </row> 300 <row> 301 <entry>LISTofPROPERTY</entry> 302 <entry>a counted collection of ­PROPERTYs.</entry> 303 </row> 304 </tbody> 305 </tgroup> 306</informaltable> 307 308</chapter> 309 310<chapter id='Protocol_Setup_and_Message_Format'> 311 <title>Protocol Setup and Message Format</title> 312 313 <para> 314To start the XSMP protocol, the client sends the server an 315<acronym>ICE</acronym> <function>ProtocolSetup</function> message. All XSMP messages are 316in the standard <acronym>ICE</acronym> message format. The message's major opcode is 317assigned to XSMP by <acronym>ICE</acronym> at run-time. The different parties (client 318and SM) may be assigned different major opcodes for XSMP. Once 319assigned, all XSMP messages issued by this party will use the same 320major opcode. The message's minor opcode specifies which protocol 321message this message contains. 322 </para> 323</chapter> 324 325<chapter id='Client_Identification_String'> 326 <title>Client Identification String</title> 327 <para> 328A client ID is a string of XPCS characters encoded in ISO Latin 1 (ISO 3298859-1). No null characters are allowed in this string. The client 330ID string is used in the <function>Register­Client</function> 331and <function>Register­ClientReply</function> messages. 332 </para> 333 334 <para> 335Client IDs consist of the pieces described below. The ID is formed by 336concatenating the pieces in sequence, without separator characters. 337All pieces are padded on the left with '<literal>0</literal>' 338characters so as to fill the specified length. Decimal numbers are 339encoded using the characters '<literal>0</literal>' through 340'<literal>9</literal>', and hexadecimal numbers using the characters 341'<literal>0</literal>' through '<literal>9</literal>' and 342'<literal>A</literal>' through '<literal>F</literal>'. 343 </para> 344 345 <itemizedlist mark='bullet'> 346 <listitem><para> 347Version. This is currently the character '<literal>1</literal>'. 348 </para></listitem> 349 <listitem> 350 <para>Address type and address. The address type will be one of 351<literallayout remap='DS'> 352 '<literal>1</literal>' a 4-byte IPv4 address encoded as 8 hexadecimal digits 353 '<literal>2</literal>' a 6-byte DECNET address encoded as 12 hexadecimal digits 354 '<literal>6</literal>' a 16-byte IPv6 address encoded as 32 hexadecimal digits 355</literallayout> 356 </para> 357 358 <para> 359The address is the one of the network addresses of the machine where 360the session manager (not the client) is running. For example, the IP 361address 198.112.45.11 would be encoded as the string 362"<literal>QC6702D0B</literal>". 363 </para> 364 </listitem> 365 <listitem><para> 366 Time stamp. A 13-digit decimal number specifying 367 the number of milliseconds since 00:00:00 UTC, January 1, 1970. 368 </para></listitem> 369 <listitem> 370 <para> 371 Process-ID type and process-ID. The process-ID type will be one of 372<literallayout remap='DS'> 373 '<literal>1</literal>' a <acronym>POSIX</acronym> process-ID encoded as a 10-digit decimal number. 374</literallayout> 375 </para> 376 <para> 377The process-ID is the process-ID of the session manager, not of a client. 378 </para> 379 </listitem> 380 <listitem> 381 <para> 382Sequence number. This is a four-digit decimal number. It is 383incremented every time the session manager creates an ID. After 384reaching "Q9999" it wraps to "Q0000". 385 </para> 386 <note><title>Rationale</title> 387 <para> 388Once a client ID has been assigned to the client, the client keeps 389this ID indefinitely. If the client is terminated and restarted, it 390will be reassigned the same ID. It is desirable to be able to pass 391client IDs around from machine to machine, from user to user, and from 392session manager to session manager, while retaining the identity of 393the client. This, combined with the indefinite persistence of client 394IDs, means that client IDs need to be globally unique. The 395construction specified above will ensure that any client ID created by 396any user, session manager, and machine will be different from any other. 397 </para> 398 </note> 399 </listitem> 400 </itemizedlist> 401</chapter> 402 403<chapter id='Protocol'> 404 <title>Protocol</title> 405 <para> 406The protocol consists of a sequence of messages as described below. 407Each message type is specified by an <acronym>ICE</acronym> minor opcode. A given 408message type is sent either from a client to the session manager or 409from the session manager to a client; the appropriate direction is 410listed with each message's description. For each message type, the 411set of valid responses and possible error messages are listed. The 412<acronym>ICE</acronym> severity is given in parentheses following each error class. 413 </para> 414 415 <synopsis> 416<function>RegisterClient</function> [Client → SM] 417 418 <parameter>previous-ID</parameter>: ARRAY8 419 420 Valid Responses: <function>RegisterClientReply</function> 421 422 Possible Errors: <errorname>BadValue</errorname> (<symbol role='Pn'>CanContinue</symbol>) 423 </synopsis> 424 425 <para> 426The client must send this message to the SM to register the client's 427existence. If a client is being restarted from a previous session, 428the <parameter>previous-ID</parameter> field must contain the client 429ID from the previous session. For new clients, 430<parameter>previous-ID</parameter> should be of zero length. 431 </para> 432 433 <para> 434If <parameter>previous-ID</parameter> is not valid, 435the SM will send a <errorname>BadValue</errorname> 436error message to the client. At this point the SM reverts to the 437register state and waits for another <function>RegisterClient</function> 438The client should then send a <function>RegisterClient</function> with a 439null <parameter>previous-ID</parameter> field. 440 </para> 441 442 <synopsis> 443<function>RegisterClientReply</function> [Client ← SM] 444 445 <parameter>client-ID</parameter>: <type>ARRAY8</type> 446 </synopsis> 447 448 <para> 449The <parameter>client-ID</parameter> specifies a unique identification 450for this client. If the client had specified an ID in the 451<parameter>previous-ID</parameter> field of the 452<function>RegisterClient</function> message, 453<parameter>client-ID</parameter> will be identical to the previously 454specified ID. If <parameter>previous-ID</parameter> was null, 455<parameter>client-ID</parameter> will be a unique ID freshly generated 456by the SM. The <parameter>client-ID</parameter> format is specified in 457<link linkend='Client_Identification_String'>section 6</link>. 458 </para> 459 460 <para> 461If the client didn't supply a <parameter>previous-ID</parameter> field to 462the <function>Register­Client</function> message, the SM must send 463a <function>SaveYourself</function> message with type = Local, 464shutdown = False, interact-style = None, and fast = False immediately 465after the <function>RegisterClientReply</function> The client should 466respond to this like any other <function>Save­Yourself</function> 467message. 468 </para> 469 470 <synopsis> 471<function>SaveYourself</function> [Client ← SM] 472 473 <parameter>type</parameter>: <type>SAVE_TYPE</type> 474 <parameter>shutdown</parameter>: <type>BOOL</type> 475 <parameter>interact-style</parameter>: <type>INTERACT_STYLE</type> 476 <parameter>fast</parameter>: <type>BOOL</type> 477 478 Valid Responses: 479 <function>SetProperties</function> 480 <function>DeleteProperties</function> 481 <function>GetProperties</function> 482 <function>SaveYourselfDone</function> 483 <function>SaveYourselfPhase2Request</function> 484 <function>InteractRequest</function> 485 </synopsis> 486 487 <para> 488The SM sends this message to a client to ask it to save its state. 489The client writes a state file, if necessary, and, if necessary, 490uses <function>SetProperties</function> to inform the SM of how to 491restart it and how to discard the saved state. During this process it 492can, if allowed by <parameter>interact-style</parameter>, request permission 493to interact with 494the user by sending an <function>InteractRequest</function> message. 495After the state has been saved, or if it cannot be successfully saved, 496and the properties are appropriately set, the client sends 497a <function>SaveYourselfDone</function> message. If the client wants 498to save additional information after all the other clients have 499finished changing their own state, the client should 500send <function>SaveYourselfPhase2Request</function> instead 501of <function>SaveYourselfDone</function> The client must then freeze 502interaction with the user and wait until it receives 503a <function>SaveComplete</function> <function>Die</function> or 504a <function>ShutdownCancelled</function> message. 505 </para> 506 507 <para> 508If <parameter>interact-style</parameter> is <function>None</function> the 509client must not interact with the user while saving state. If the 510<parameter>interact-style</parameter> 511is <function>Errors</function> the client may interact with the user 512only if an error condition arises. If <parameter>interact-style</parameter> 513is <function>Any</function> then the client may interact with the user 514for any purpose. This is done by sending 515an <function>Interact­Request</function> message. The SM will 516send an <function>Interact</function> message to each client that sent 517an <function>Interact­Request</function> The client must postpone 518all interaction until it gets the <function>Interact</function> 519message. When the client is done interacting it should send the SM 520an <function>Interact­Done</function> message. 521The <function>Interact­Request</function> message can be sent any 522time after a <function>Save­Yourself</function> and before 523a <function>Save­Yourself­Done</function> 524 </para> 525 526 <para> 527Unusual circumstances may dictate multiple interactions. The client 528may initiate as many <function>Interact­Request</function> 529- <function>Interact</function> - <function>InteractDone</function> 530sequences as it needs before it sends <function>SaveYourselfDone</function> 531 </para> 532 533 <para> 534When a client receives <function>Save­Yourself</function> and has 535not yet responded <function>Save­Yourself­Done</function> to a 536previous <function>Save­Yourself</function> it must send 537a <function>Save­Yourself­Done</function> and may then begin 538responding as appropriate to the newly received 539<function>Save­Yourself</function> 540</para> 541 542 <para> 543The <parameter>type</parameter> field specifies the type of information that 544should be saved: <function>Global</function> <function>Local</function> 545or <function>Both</function> The <function>Local</function> type 546indicates that the application must update the properties to reflect 547its current state, send 548a <function>Save­Yourself­Done</function> and continue. 549Specifically it should save enough information to restore the state as 550seen by the user of this client. It should not affect the state as 551seen by other users. The <function>Global</function> type indicates 552that the user wants the client to commit all of its data to permanent, 553globally-accessible storage. <function>Both</function> indicates that 554the client should do both of these. If <function>Both</function> is 555specified, the client should first commit the data to permanent 556storage before updating its SM properties. 557 </para> 558 559 <note><title>Examples</title> 560 <para> 561If a word processor was sent a <function>SaveYourself</function> with 562a type of <function>Local</function> it could create a temporary file 563that included the current contents of the file, the location of the 564cursor, and other aspects of the current editing session. It would 565then update its <function>Restart­Command</function> property with 566enough information to find the temporary file, and 567its <function>Discard­Command</function> with enough information 568to remove it. 569 </para> 570 571 <para> 572If a word processor was sent a <function>SaveYourself</function> with 573a type of <function>Global</function> it would simply save the 574currently edited file. 575 </para> 576 577 <para> 578If a word processor was sent a <function>SaveYourself</function> with 579a type of <function>Both</function> it would first save the currently 580edited file. It would then create a temporary file with information 581such as the current position of the cursor and what file is being 582edited. It would then update 583its <function>Restart­Command</function> property with enough 584information to find the temporary file, and 585its <function>Discard­Command</function> with enough information 586to remove it. 587 </para> 588 589 <para> 590Once the SM has send <function>SaveYourself</function> to a client, it 591can't send another <function>SaveYourself</function> to that client until 592the client either responds with a <function>SaveYourselfDone</function> or 593the SM sends a <function>ShutdownCancelled</function> 594 </para> 595 </note> 596 597 <note><title>Advice to Implementors</title> 598 <para> 599If the client stores local any state in a file or similar "external" 600storage, it must create a distinct copy in response to 601each <function>SaveYourself</function> message. 602It <emphasis remap='I'>must not</emphasis> simply refer to a previous 603copy, because the SM may discard that previous saved state using 604a <function>DiscardCommand</function> without knowing that it is 605needed for the new checkpoint. 606 </para> 607 </note> 608 609 <para> 610The <parameter>shutdown</parameter> field specifies whether the system is 611being shut down. 612 </para> 613 614 <note><title>Rationale</title> 615 <para> 616The interaction may be different depending on whether or not shutdown is set. 617 </para> 618 </note> 619 620 <para> 621The client must save and then must prevent interaction until it 622receives a <function>SaveComplete</function> <function>Die</function> 623or a <function>Shutdown­Cancelled</function> because anything the 624user does after the save will be lost. 625 </para> 626 627 <para> 628The <parameter>fast</parameter> field specifies whether or not the client 629should save its state as quickly as possible. For example, if the SM knows 630that power is about to fail, it should set the <parameter>fast</parameter> 631field to <constant>True</constant>. 632 </para> 633 634 <synopsis> 635<function>SaveYourselfPhase2</function> [Client → SM] 636 637 Valid Responses: 638 <function>SetProperties</function> 639 <function>DeleteProperties</function> 640 <function>GetProperties</function> 641 <function>SaveYourselfDone</function> 642 <function>InteractRequest</function> 643 </synopsis> 644 645 <para> 646The SM sends this message to a client that has previously sent 647a <function>SaveYourselfPhase2Request</function> message. This 648message informs the client that all other clients are in a fixed state 649and this client can save state that is associated with other clients. 650 </para> 651 652 <note><title>Rationale</title> 653 <para> 654Clients that manager other clients (window managers, workspace 655managers, etc) need to know when all clients they are managing are 656idle, so that the manager can save state related to each of the 657clients without being concerned with that state changing. 658 </para> 659 </note> 660 <para> 661The client writes a state file, if necessary, and, if necessary, 662uses <function>SetProperties</function> to inform the SM of how to 663restart it and how to discard the saved state. During this process it 664can request permission to interact with the user by sending 665an <function>InteractRequest</function> message. This should only be 666done if an error occurs that requires user interaction to resolve. 667After the state has been saved, or if it cannot be successfully saved, 668and the properties are appropriately set, the client sends 669a <function>SaveYourselfDone</function> message. 670 </para> 671 672 <synopsis> 673<function>SaveYourselfRequest</function> [Client → SM] 674 675 <parameter>type</parameter>: <type>SAVE_TYPE</type> 676 <parameter>shutdown</parameter>: <type>BOOL</type> 677 <parameter>interact-style</parameter>: <type>INTERACT_STYLE</type> 678 <parameter>fast</parameter>: <type>BOOL</type> 679 <parameter>global</parameter>: <type>BOOL</type> 680 681 Valid Responses: <function>SaveYourself</function> 682 </synopsis> 683 684 <para> 685An application sends this to the SM to request a checkpoint. When the 686SM receives this request it may generate a <function>SaveYourself</function> 687message in response and it may leave the fields intact. 688 </para> 689 690 <note><title>Example</title> <para> 691A vendor of a <acronym>UPS</acronym> (Uninterruptible Power Supply) 692might include an SM client that would monitor the status of 693the <acronym>UPS</acronym> and generate a fast shutdown if the power 694is about to be lost. 695 </para></note> 696 697 <para> 698If <parameter>global</parameter> is set to <constant>True</constant> then the 699resulting <function>SaveYourself</function> should be sent to all 700applications. If <parameter>global</parameter> is set to 701<constant>False</constant> then the 702resulting <function>SaveYourself</function> should be sent to the 703application that sent the <function>Save­Yourself­Request</function> 704 </para> 705 706 <synopsis> 707<function>InteractRequest</function> [Client → SM] 708 709 <parameter>dialog-type</parameter>: <type>DIALOG_TYPE</type> 710 711 Valid Responses: <function>Interact</function> <function>ShutdownCancelled</function> 712 713 Possible Errors: <errorname>BadState</errorname> (<symbol role='Pn'>CanContinue</symbol>) 714 </synopsis> 715 716 <para> 717During a checkpoint or session-save operation, only one client at a 718time might be granted the privilege of interacting with the user. 719The <function>InteractRequest</function> message causes the SM to emit 720an <function>Interact</function> message at some later time if the 721shutdown is not cancelled by another client first. 722 </para> 723 724 <para> 725The <parameter>dialog-type</parameter> field specifies either 726<function>Errors</function> indicating that the client wants to start an 727error dialog or <function>Normal</function> meaning the client wishes 728to start a non-error dialog. 729 </para> 730 731 <synopsis> 732<function>Interact</function> [Client ← SM] 733 734 Valid Responses: <function>InteractDone</function> 735 </synopsis> 736 737 <para> 738This message grants the client the privilege of interacting with the 739user. When the client is done interacting with the user it must send 740an <function>InteractDone</function> message to the SM unless a 741shutdown cancel is received. 742 </para> 743 <note><title>Advice to Implementors</title> 744 <para>If a client receives a ShutdownCancelled 745after receiving an <function>Interact</function> message, but before 746sending a <function>InteractDone</function> the client should abort 747the interaction and send a <function>SaveYourselfDone</function> 748 </para></note> 749 750 <synopsis> 751<function>InteractDone</function> [Client → SM] 752 753 <parameter>cancel-shutdown</parameter>: <type>BOOL</type> 754 755 Valid Responses: <function>ShutdownCancelled</function> 756 </synopsis> 757 758 <para> 759This message is used by a client to notify the SM that it is done interacting. 760 </para> 761 762 <para> 763Setting the <parameter>cancel-shutdown</parameter> field to <constant>True</constant> 764indicates that the user has requested that the entire shutdown be 765cancelled. <parameter>Cancel-shutdown</parameter> may only be <constant>True</constant> if 766the corresponding <function>SaveYourself</function> message 767specified <constant>True</constant> for the shutdown field 768and <function>Any</function> or <function>Errors</function> for the 769<parameter>interact-style</parameter> field. Otherwise, 770<parameter>cancel-shutdown</parameter> must be <constant>False</constant>. 771 </para> 772 773 <synopsis> 774<function>SaveYourselfDone</function> [Client → SM] 775 776 <parameter>success</parameter>: <type>BOOL</type> 777 778 Valid Responses: 779 <function>SaveComplete</function> 780 <function>Die</function> 781 <function>ShutdownCancelled</function> 782 783 </synopsis> 784 785 <para> 786This message is sent by a client to indicate that all of the 787properties representing its state have been updated. After 788sending <function>SaveYourselfDone</function> the client must wait for 789a <function>SaveComplete</function> <function>ShutdownCancelled</function> 790or <function>Die</function> message before changing its state. If 791the <function>SaveYourself</function> operation was successful, then 792the client should set the <parameter>success</parameter> field to 793<constant>True</constant> otherwise the client should set it to 794<constant>False</constant>. 795 </para> 796 797 <note><title>Example</title> 798 <para> 799If a client tries to save its state and runs out of disk space, it 800should return <constant>False</constant> in the <parameter>success</parameter> 801field of the <function>SaveYourselfDone</function> message. 802 </para> 803 </note> 804 805 <synopsis> 806<function>SaveYourselfPhase2Request</function> [Client → SM] 807 808 Valid Responses: 809 <function>ShutdownCancelled</function> 810 <function>SaveYourselfPhase2</function> 811 812 </synopsis> 813 814 <para> 815This message is sent by a client to indicate that it needs to be informed 816when all the other clients are quiescent, so it can continue its state. 817 </para> 818 819 <synopsis> 820<function>Die</function> [Client ← SM] 821 822 Valid Responses: <function>ConnectionClosed</function> 823 </synopsis> 824 825 <para> 826When the SM wants a client to die it sends a <function>Die</function> 827message. Before the client dies it responds by sending 828a <function>ConnectionClosed</function> message and may then close its 829connection to the SM at any time. 830 </para> 831 832 <synopsis> 833<function>SaveComplete</function> [Client → SM] 834 835 Valid Responses: 836 </synopsis> 837 838 <para> 839When the SM is done with a checkpoint, it will send each of the 840clients a <function>SaveComplete</function> message. The client is 841then free to change its state. 842 </para> 843 844 <synopsis> 845<function>ShutdownCancelled</function> [Client ← SM] 846 </synopsis> 847 848 <para> 849The shutdown currently in process has been aborted. The client can 850now continue as if the shutdown had never happened. If the client has 851not sent <function>SaveYourselfDone</function> yet, the client can 852either abort the save and send <function>SaveYourselfDone</function> 853with the success field set to <constant>False</constant> or it can 854continue with the save and send a <function>SaveYourselfDone</function> 855with the success field set to reflect the outcome of the save. 856 </para> 857 858 <synopsis> 859<function>ConnectionClosed</function> [Client → SM] 860 861 <parameter>reason</parameter>: <type>LISTofARRAY8</type> 862 </synopsis> 863 864 <para> 865Specifies that the client has decided to terminate. It should be 866immediately followed by closing the connection. 867 </para> 868 869 <para> 870The <parameter>reason</parameter> field specifies why the client is resigning 871from the session. It is encoded as an array of Compound Text strings. If the 872resignation is expected by the user, there will typically be zero 873ARRAY8s here. But if the client encountered an unexpected fatal 874error, the error message (which might otherwise be printed on stderr 875on a <acronym>POSIX</acronym> system) should be forwarded to the SM here, one ARRAY8 per 876line of the message. It is the responsibility of the SM to display 877this reason to the user. 878 </para> 879 880 <para> 881After sending this message, the client must not send any additional 882XSMP messages to the SM. 883 </para> 884 <note><title>Advice to Implementors</title><para> 885If additional messages are received, they should be discarded. 886 </para></note> 887 <note><title>Rationale</title><para> 888The reason for sending the <function>ConnectionClosed</function> 889message before actually closing the connections is that some transport 890protocols will not provide immediate notification of connection 891closure. 892 </para></note> 893 894 <synopsis> 895<function>SetProperties</function> [Client → SM] 896 897 <parameter>properties</parameter>: <type>LISTofPROPERTY</type> 898 </synopsis> 899 900 <para> 901Sets the specified <parameter>properties</parameter> to the specified values. 902Existing 903properties not specified in the <function>Set­Properties</function> 904message are unaffected. Some properties have predefined semantics. 905See <link linkend='Predefined_Properties'>section 11, 906“Predefined Properties.”</link> 907 </para> 908 909 <para> 910The protocol specification recommends that property names used for 911properties not defined by the standard should begin with an 912underscore. To prevent conflicts among organizations, additional 913prefixes should be chosen (for example, _KPC_FAST_SAVE_OPTION). The 914organizational prefixes should be registered with the X Registry. The 915XSMP reserves all property names not beginning with an underscore for 916future use. 917 </para> 918 919 <synopsis> 920<function>DeleteProperties</function> [Client → SM] 921 922 <parameter>property-names</parameter>: <type>LISTofARRAY8</type> 923 </synopsis> 924 925 <para>Removes the named properties.</para> 926 927 <synopsis> 928<function>GetProperties</function> [Client → SM] 929 930 Valid Responses: <function>GetPropertiesReply</function> 931 </synopsis> 932 933 <para> 934Requests that the SM respond with the values of all the properties for 935this client. 936 </para> 937 938 <synopsis> 939<function>GetPropertiesReply</function> [Client ← SM] 940 941 <parameter>values</parameter>: <type>LISTofPROPERTY</type> 942 </synopsis> 943 944 <para> 945This message is sent in reply to a <function>GetProperties</function> 946message and includes the <parameter>values</parameter> of all the properties. 947 </para> 948</chapter> 949 950<chapter id='Errors'> 951 <title>Errors</title> 952 953 <para> 954When the receiver of a message detects an error condition, the 955receiver sends an <acronym>ICE</acronym> error message to the sender. There are only two 956types of errors that are used by the XSMP: 957<errorname>BadValue</errorname> and <errorname>BadState</errorname> 958These are both defined in the <acronym>ICE</acronym> protocol. 959 </para> 960 961 <para> 962Any message received out-of-sequence will generate 963a <errorname>BadState</errorname> error message. 964 </para> 965</chapter> 966 967<chapter id='State_Diagrams'> 968 <title>State Diagrams</title> 969 <para> 970These state diagrams are designed to cover all actions of both the 971client and the SM. 972 </para> 973 974 <sect1 id='Client_State_Diagram'> 975<title>Client State Diagram</title> 976 977<!-- <literallayout remap='DS'> --> 978<literallayout> 979<emphasis remap='I'>start:</emphasis> 980 <acronym>ICE</acronym> protocol setup complete → <emphasis remap='C'>register</emphasis></literallayout> 981 982<literallayout> 983<emphasis remap='I'>register:</emphasis> 984 send <emphasis remap='B'>RegisterClient</emphasis> → <emphasis remap='C'>collect-id</emphasis></literallayout> 985 986<literallayout remap='DS'> 987<emphasis remap='I'>collect-id:</emphasis> 988 receive <emphasis remap='B'>RegisterClientReply</emphasis> → <emphasis remap='C'>idle</emphasis></literallayout> 989 990<literallayout remap='DS'> 991<emphasis remap='I'>shutdown-cancelled:</emphasis> 992 send <emphasis remap='B'>SaveYourselfDone</emphasis> → <emphasis remap='C'>idle</emphasis></literallayout> 993 994<literallayout remap='DS'> 995<emphasis remap='I'>idle:</emphasis> [Undoes any freeze of interaction with user.] 996 receive <emphasis remap='B'>Die</emphasis> → <emphasis remap='C'>die</emphasis> 997 receive <emphasis remap='B'>SaveYourself</emphasis> → <emphasis remap='C'>freeze-interaction</emphasis> 998 send <emphasis remap='B'>GetProperties</emphasis> → <emphasis remap='C'>idle</emphasis> 999 receive <emphasis remap='B'>GetPropertiesReply</emphasis> → <emphasis remap='C'>idle</emphasis> 1000 send <emphasis remap='B'>SetProperties</emphasis> → <emphasis remap='C'>idle</emphasis> 1001 send <emphasis remap='B'>DeleteProperties</emphasis> → <emphasis remap='C'>idle</emphasis> 1002 send <emphasis remap='B'>ConnectionClosed</emphasis> → <emphasis remap='C'>connection-closed</emphasis> 1003 send <emphasis remap='B'>SaveYourselfRequest</emphasis> → <emphasis remap='C'>idle</emphasis> 1004</literallayout> <!-- remap='DE' --> 1005 1006<literallayout remap='DS'> 1007<emphasis remap='I'>die:</emphasis> 1008 send <emphasis remap='B'>ConnectionClosed</emphasis> → <emphasis remap='C'>connection-closed</emphasis></literallayout> 1009 1010<literallayout remap='DS'> 1011<emphasis remap='I'>freeze-interaction:</emphasis> 1012 freeze interaction with user → <emphasis remap='C'>save-yourself</emphasis></literallayout> 1013 1014<literallayout remap='DS'> 1015<emphasis remap='I'>save-yourself:</emphasis> 1016 receive <emphasis remap='B'>ShutdownCancelled</emphasis> → <emphasis remap='C'>shutdown-cancelled</emphasis> 1017 send <emphasis remap='B'>SetProperties</emphasis> → <emphasis remap='C'>save-yourself</emphasis> 1018 send <emphasis remap='B'>DeleteProperties</emphasis> → <emphasis remap='C'>save-yourself</emphasis> 1019 send <emphasis remap='B'>GetProperties</emphasis> → <emphasis remap='C'>save-yourself</emphasis> 1020 receive <emphasis remap='B'>GetPropertiesReply</emphasis> → <emphasis remap='C'>save-yourself</emphasis> 1021 send <emphasis remap='B'>InteractRequest</emphasis> → <emphasis remap='C'>interact-request</emphasis> 1022 send <emphasis remap='B'>SaveYourselfPhase2Request</emphasis> → waiting-for-phase2 1023 1024<emphasis remap='I'>save-yourself:</emphasis> 1025 if shutdown mode: 1026 send <emphasis remap='B'>SaveYourselfDone</emphasis> → <emphasis remap='C'>save-yourself-done</emphasis> 1027 otherwise: 1028 send <emphasis remap='B'>SaveYourselfDone</emphasis> → <emphasis remap='C'>idle</emphasis></literallayout> 1029 1030<literallayout remap='DS'> 1031<emphasis remap='I'>waiting-for-phase2:</emphasis> 1032 receive <emphasis remap='B'>ShutdownCancelled</emphasis> → <emphasis remap='C'>shutdown-cancelled</emphasis> 1033 receive <emphasis remap='B'>SaveYourselfPhase2</emphasis> → <emphasis remap='C'>phase2</emphasis></literallayout> 1034 1035<literallayout remap='DS'> 1036<emphasis remap='I'>phase2:</emphasis> 1037 receive <emphasis remap='B'>ShutdownCancelled</emphasis> → <emphasis remap='C'>shutdown-cancelled</emphasis> 1038 send <emphasis remap='B'>SetProperties</emphasis> → <emphasis remap='C'>save-yourself</emphasis> 1039 send <emphasis remap='B'>DeleteProperties</emphasis> → <emphasis remap='C'>save-yourself</emphasis> 1040 send <emphasis remap='B'>GetProperties</emphasis> → <emphasis remap='C'>save-yourself</emphasis> 1041 receive <emphasis remap='B'>GetPropertiesReply</emphasis> → <emphasis remap='C'>save-yourself</emphasis> 1042 send <emphasis remap='B'>InteractRequest</emphasis> → <emphasis remap='C'>interact-request</emphasis> (errors only) 1043 if shutdown mode: 1044 send <emphasis remap='B'>SaveYourselfDone</emphasis> → <emphasis remap='C'>save-yourself-done</emphasis> 1045 otherwise: 1046 send <emphasis remap='B'>SaveYourselfDone</emphasis> → <emphasis remap='C'>idle</emphasis></literallayout> 1047 1048<literallayout remap='DS'> 1049<emphasis remap='I'>interact-request:</emphasis> 1050 receive <emphasis remap='B'>Interact</emphasis> → <emphasis remap='C'>interact</emphasis> 1051 receive <emphasis remap='B'>ShutdownCancelled</emphasis> → <emphasis remap='C'>shutdown-cancelled</emphasis></literallayout> 1052 1053<literallayout remap='DS'> 1054<emphasis remap='I'>interact:</emphasis> 1055 send <emphasis remap='B'>InteractDone</emphasis> → <emphasis remap='C'>save-yourself</emphasis> 1056 receive <emphasis remap='B'>ShutdownCancelled</emphasis> → <emphasis remap='C'>shutdown-cancelled</emphasis></literallayout> 1057 1058<literallayout remap='DS'> 1059<emphasis remap='I'>save-yourself-done:</emphasis> (changing state is forbidden) 1060 receive <emphasis remap='B'>SaveComplete</emphasis> → <emphasis remap='C'>idle</emphasis> 1061 receive <emphasis remap='B'>Die</emphasis> → <emphasis remap='C'>die</emphasis> 1062 receive <emphasis remap='B'>ShutdownCancelled</emphasis> → <emphasis remap='C'>idle</emphasis></literallayout> 1063 1064<literallayout remap='DS'> 1065<emphasis remap='I'>connection-closed:</emphasis> 1066 client stops participating in session </literallayout> 1067</sect1> 1068 1069<sect1 id='Session_Manager_State_Diagram'> 1070<title>Session Manager State Diagram</title> 1071 1072<literallayout remap='DS'> 1073<emphasis remap='I'>start:</emphasis> 1074 receive <emphasis remap='B'>ProtocolSetup</emphasis> → <emphasis remap='C'>protocol-setup</emphasis></literallayout> 1075 1076<literallayout remap='DS'> 1077<emphasis remap='I'>protocol-setup:</emphasis> 1078 send <emphasis remap='B'>ProtocolSetupReply</emphasis> → <emphasis remap='C'>register</emphasis></literallayout> 1079 1080<literallayout remap='DS'> 1081<emphasis remap='I'>register:</emphasis> 1082 receive <emphasis remap='B'>RegisterClient</emphasis> → <emphasis remap='C'>acknowledge-register</emphasis> 1083</literallayout> 1084 1085<literallayout remap='DS'> 1086<emphasis remap='I'>acknowledge-register:</emphasis> 1087 send <emphasis remap='B'>RegisterClientReply</emphasis> → <emphasis remap='C'>idle</emphasis> 1088</literallayout> 1089 1090<literallayout remap='DS'> 1091<emphasis remap='I'>idle:</emphasis> 1092 receive <emphasis remap='B'>SetProperties</emphasis> → <emphasis remap='C'>idle</emphasis> 1093 receive <emphasis remap='B'>DeleteProperties</emphasis> → <emphasis remap='C'>idle</emphasis> 1094 receive <emphasis remap='B'>ConnectionClosed</emphasis> → <emphasis remap='C'>start</emphasis> 1095 receive <emphasis remap='B'>GetProperties</emphasis> → <emphasis remap='C'>get-properties</emphasis> 1096 receive <emphasis remap='B'>SaveYourselfRequest</emphasis> → <emphasis remap='C'>save-yourself</emphasis> 1097 send <emphasis remap='B'>SaveYourself</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1098</literallayout> 1099 1100<literallayout remap='DS'> 1101<emphasis remap='I'>save-yourself:</emphasis> 1102 send <emphasis remap='B'>SaveYourself</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1103</literallayout> 1104 1105<literallayout remap='DS'> 1106<emphasis remap='I'>get-properties:</emphasis> 1107 send <emphasis remap='B'>GetPropertiesReply</emphasis> → <emphasis remap='C'>idle</emphasis> 1108</literallayout> 1109 1110<literallayout remap='DS'> 1111<emphasis remap='I'>saving-get-properties:</emphasis> 1112 send <emphasis remap='B'>GetPropertiesReply</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1113</literallayout> 1114 1115<literallayout remap='DS'> 1116<emphasis remap='I'>saving-yourself:</emphasis> 1117 receive <emphasis remap='B'>InteractRequest</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1118 send <emphasis remap='B'>Interact</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1119 send <emphasis remap='B'>ShutdownCancelled</emphasis> → <emphasis remap='C'>idle</emphasis> 1120 receive <emphasis remap='B'>InteractDone</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1121 receive <emphasis remap='B'>SetProperties</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1122 receive <emphasis remap='B'>DeleteProperties</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1123 receive <emphasis remap='B'>GetProperties</emphasis> → <emphasis remap='C'>saving-get-properties</emphasis> 1124 receive <emphasis remap='B'>SaveYourselfPhase2Request</emphasis> → <emphasis remap='C'>start-phase2</emphasis> 1125 receive <emphasis remap='B'>SaveYourselfDone</emphasis> → <emphasis remap='C'>save-yourself-done</emphasis> 1126</literallayout> 1127 1128<literallayout remap='DS'> 1129<emphasis remap='I'>start-phase2:</emphasis> 1130 If all clients have sent either SaveYourselfPhase2Request or SaveYourselfDone: 1131 send <emphasis remap='B'>SaveYourselfPhase2</emphasis> → <emphasis remap='C'>phase2</emphasis> 1132 else 1133 → <emphasis remap='C'>saving-yourself</emphasis> 1134</literallayout> 1135 1136<literallayout remap='DS'> 1137<emphasis remap='I'>phase2:</emphasis> 1138 receive <emphasis remap='B'>InteractRequest</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1139 send <emphasis remap='B'>Interact</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1140 send <emphasis remap='B'>ShutdownCancelled</emphasis> → <emphasis remap='C'>idle</emphasis> 1141 receive <emphasis remap='B'>InteractDone</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1142 receive <emphasis remap='B'>SetProperties</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1143 receive <emphasis remap='B'>DeleteProperties</emphasis> → <emphasis remap='C'>saving-yourself</emphasis> 1144 receive <emphasis remap='B'>GetProperties</emphasis> → <emphasis remap='C'>saving-get-properties</emphasis> 1145 receive <emphasis remap='B'>SaveYourselfDone</emphasis> → <emphasis remap='C'>save-yourself-done</emphasis> 1146</literallayout> 1147 1148<literallayout remap='DS'> 1149<emphasis remap='I'>save-yourself-done:</emphasis> 1150 If all clients are saved: 1151 If shutting down: 1152 send <emphasis remap='B'>Die</emphasis> → <emphasis remap='C'>die</emphasis> 1153 otherwise 1154 send <emphasis remap='B'>SaveComplete</emphasis> → <emphasis remap='C'>idle</emphasis> 1155 1156 If some clients are not saved: 1157 → <emphasis remap='C'>saving-yourself</emphasis> 1158</literallayout> 1159 1160<literallayout remap='DS'> 1161<emphasis remap='I'>die:</emphasis> 1162 SM stops accepting connections 1163</literallayout> 1164 </sect1> 1165</chapter> 1166 1167<chapter id='Protocol_Encoding'> 1168 <title>Protocol Encoding</title> 1169 <sect1 id='Types'> 1170<title>Types</title> 1171 1172<informaltable frame='none'> 1173 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1174 <?dbfo keep-together="always" ?> 1175 <colspec colname='c1' colwidth='1.0*'/> 1176 <colspec colname='c2' colwidth='10.0*'/> 1177 <thead> 1178 <row> 1179 <entry namest='c1' nameend='c2'><emphasis role="bold">BOOL</emphasis></entry> 1180 </row> 1181 </thead> 1182 <tbody> 1183 <row> 1184 <entry>0</entry> 1185 <entry>False</entry> 1186 </row> 1187 <row> 1188 <entry>1</entry> 1189 <entry>True</entry> 1190 </row> 1191 </tbody> 1192 </tgroup> 1193 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1194 <?dbfo keep-together="always" ?> 1195 <colspec colname='c1' colwidth='1.0*'/> 1196 <colspec colname='c2' colwidth='10.0*'/> 1197 <thead> 1198 <row> 1199 <entry namest='c1' nameend='c2'><emphasis role="bold">INTERACT_STYLE</emphasis></entry> 1200 </row> 1201 </thead> 1202 <tbody> 1203 <row> 1204 <entry>0</entry> 1205 <entry>None</entry> 1206 </row> 1207 <row> 1208 <entry>1</entry> 1209 <entry>Errors</entry> 1210 </row> 1211 <row> 1212 <entry>2</entry> 1213 <entry>Any</entry> 1214 </row> 1215 </tbody> 1216 </tgroup> 1217 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1218 <?dbfo keep-together="always" ?> 1219 <colspec colname='c1' colwidth='1.0*'/> 1220 <colspec colname='c2' colwidth='10.0*'/> 1221 <thead> 1222 <row> 1223 <entry namest='c1' nameend='c2'><emphasis role="bold">DIALOG_TYPE</emphasis></entry> 1224 </row> 1225 </thead> 1226 <tbody> 1227 <row> 1228 <entry>0</entry> 1229 <entry>Error</entry> 1230 </row> 1231 <row> 1232 <entry>1</entry> 1233 <entry>Normal</entry> 1234 </row> 1235 </tbody> 1236 </tgroup> 1237 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1238 <?dbfo keep-together="always" ?> 1239 <colspec colname='c1' colwidth='1.0*'/> 1240 <colspec colname='c2' colwidth='10.0*'/> 1241 <thead> 1242 <row> 1243 <entry namest='c1' nameend='c2'><emphasis role="bold">SAVE_TYPE</emphasis></entry> 1244 </row> 1245 </thead> 1246 <tbody> 1247 <row> 1248 <entry>0</entry> 1249 <entry>Global</entry> 1250 </row> 1251 <row> 1252 <entry>1</entry> 1253 <entry>Local</entry> 1254 </row> 1255 <row> 1256 <entry>2</entry> 1257 <entry>Both</entry> 1258 </row> 1259 </tbody> 1260 </tgroup> 1261 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1262 <?dbfo keep-together="always" ?> 1263 <colspec colname='c1' colwidth='1.0*'/> 1264 <colspec colname='c2' colwidth='5.0*'/> 1265 <colspec colname='c3' colwidth='5.0*'/> 1266 <thead> 1267 <row> 1268 <entry namest='c1' nameend='c2'><emphasis role="bold">ARRAY8</emphasis></entry> 1269 </row> 1270 </thead> 1271 <tbody> 1272 <row> 1273 <entry>4</entry> 1274 <entry>CARD32</entry> 1275 <entry>length</entry> 1276 </row> 1277 <row> 1278 <entry>n</entry> 1279 <entry>ListofCARD8, the array</entry> 1280 <entry>p = pad (4 + n, 8)</entry> 1281 </row> 1282 <row> 1283 <entry>2</entry> 1284 <entry>Both</entry> 1285 </row> 1286 </tbody> 1287 </tgroup> 1288 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1289 <?dbfo keep-together="always" ?> 1290 <colspec colname='c1' colwidth='1.0*'/> 1291 <colspec colname='c2' colwidth='5.0*'/> 1292 <colspec colname='c3' colwidth='5.0*'/> 1293 <thead> 1294 <row> 1295 <entry namest='c1' nameend='c2'><emphasis role="bold">LISTofARRAY8</emphasis></entry> 1296 </row> 1297 </thead> 1298 <tbody> 1299 <row> 1300 <entry>4</entry> 1301 <entry>CARD32</entry> 1302 <entry>count</entry> 1303 </row> 1304 <row> 1305 <entry>4</entry> 1306 <entry></entry> 1307 <entry>unused</entry> 1308 </row> 1309 <row> 1310 <entry>a</entry> 1311 <entry>ARRAY8</entry> 1312 <entry>first array</entry> 1313 </row> 1314 <row> 1315 <entry>b</entry> 1316 <entry>ARRAY8</entry> 1317 <entry>second array</entry> 1318 </row> 1319 <row> 1320 <entry>.</entry> 1321 <entry></entry> 1322 <entry></entry> 1323 </row> 1324 <row> 1325 <entry>.</entry> 1326 <entry></entry> 1327 <entry></entry> 1328 </row> 1329 <row> 1330 <entry>.</entry> 1331 <entry></entry> 1332 <entry></entry> 1333 </row> 1334 <row> 1335 <entry>q</entry> 1336 <entry>ARRAY8</entry> 1337 <entry>last array</entry> 1338 </row> 1339 </tbody> 1340 </tgroup> 1341 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1342 <?dbfo keep-together="always" ?> 1343 <colspec colname='c1' colwidth='1.0*'/> 1344 <colspec colname='c2' colwidth='5.0*'/> 1345 <colspec colname='c3' colwidth='5.0*'/> 1346 <thead> 1347 <row> 1348 <entry namest='c1' nameend='c2'><emphasis role="bold">PROPERTY</emphasis></entry> 1349 </row> 1350 </thead> 1351 <tbody> 1352 <row> 1353 <entry>a</entry> 1354 <entry>ARRAY8</entry> 1355 <entry>name</entry> 1356 </row> 1357 <row> 1358 <entry>b</entry> 1359 <entry>ARRAY8</entry> 1360 <entry>type (XPCS encoded in Latin-1, case sensitive)</entry> 1361 </row> 1362 <row> 1363 <entry>c</entry> 1364 <entry>LISTofARRAY8</entry> 1365 <entry>values</entry> 1366 </row> 1367 </tbody> 1368 </tgroup> 1369 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1370 <?dbfo keep-together="always" ?> 1371 <colspec colname='c1' colwidth='1.0*'/> 1372 <colspec colname='c2' colwidth='5.0*'/> 1373 <colspec colname='32' colwidth='5.0*'/> 1374 <thead> 1375 <row> 1376 <entry namest='c1' nameend='c2'><emphasis role="bold">LISTofPROPERTY</emphasis></entry> 1377 </row> 1378 </thead> 1379 <tbody> 1380 <row> 1381 <entry>4</entry> 1382 <entry>CARD32</entry> 1383 <entry>count</entry> 1384 </row> 1385 <row> 1386 <entry>4</entry> 1387 <entry></entry> 1388 <entry>unused</entry> 1389 </row> 1390 <row> 1391 <entry>a</entry> 1392 <entry>PROPERTY</entry> 1393 <entry>first property</entry> 1394 </row> 1395 <row> 1396 <entry>b</entry> 1397 <entry>PROPERTY</entry> 1398 <entry>second property</entry> 1399 </row> 1400 <row> 1401 <entry>.</entry> 1402 <entry></entry> 1403 <entry></entry> 1404 </row> 1405 <row> 1406 <entry>.</entry> 1407 <entry></entry> 1408 <entry></entry> 1409 </row> 1410 <row> 1411 <entry>.</entry> 1412 <entry></entry> 1413 <entry></entry> 1414 </row> 1415 <row> 1416 <entry>q</entry> 1417 <entry>PROPERTY</entry> 1418 <entry>last property</entry> 1419 </row> 1420 </tbody> 1421 </tgroup> 1422</informaltable> 1423 1424 </sect1> 1425 1426 <sect1 id='Messages'> 1427<title>Messages</title> 1428 <para> 1429XSMP is a sub-protocol of <acronym>ICE</acronym>. The major opcode is 1430assigned at run-time by <acronym>ICE</acronym> and is represented here 1431by '<literal>?</literal>'. 1432 </para> 1433 1434 <para> 1435To start the XSMP protocol, the client sends the server an 1436<acronym>ICE</acronym> <function>ProtocolSetup</function> message. 1437The protocol-name field should be specified as "<literal>XSMP</literal>", 1438the major version of the protocol is 1, the minor version is 0. These 1439values may change if the protocol is revised. The minor version 1440number will be incremented if the change is compatible, otherwise the 1441major version number will be incremented. 1442 </para> 1443 1444 <para> 1445In <function>ProtocolReply</function> message sent by the session 1446manager, the XSMP protocol defines the vendor parameter as product 1447identification of the session manager, and defines the release 1448parameter as the software release identification of the session 1449manager. The session manager should supply this information in the 1450<acronym>ICE</acronym> <function>ProtocolReply</function> message. 1451 </para> 1452 1453<informaltable frame='none'> 1454 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1455 <?dbfo keep-together="always" ?> 1456 <colspec colname='c1' colwidth='1.0*'/> 1457 <colspec colname='c2' colwidth='5.0*'/> 1458 <colspec colname='c3' colwidth='5.0*'/> 1459 <thead> 1460 <row> 1461 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>RegisterClient</function></emphasis></entry> 1462 </row> 1463 </thead> 1464 <tbody> 1465 <row> 1466 <entry>1</entry> 1467 <entry>?</entry> 1468 <entry>XSMP</entry> 1469 </row> 1470 <row> 1471 <entry>1</entry> 1472 <entry>1</entry> 1473 <entry>opcode</entry> 1474 </row> 1475 <row> 1476 <entry>2</entry> 1477 <entry></entry> 1478 <entry>unused</entry> 1479 </row> 1480 <row> 1481 <entry>4</entry> 1482 <entry>a/8</entry> 1483 <entry>length of remaining data in 8-byte units</entry> 1484 </row> 1485 <row> 1486 <entry>a</entry> 1487 <entry>ARRAY8</entry> 1488 <entry>previous-ID</entry> 1489 </row> 1490 </tbody> 1491 </tgroup> 1492 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1493 <?dbfo keep-together="always" ?> 1494 <colspec colname='c1' colwidth='1.0*'/> 1495 <colspec colname='c2' colwidth='5.0*'/> 1496 <colspec colname='c3' colwidth='5.0*'/> 1497 <thead> 1498 <row> 1499 <entry namest='c1' nameend='c3'><emphasis role="bold"><function>RegisterClientReply</function></emphasis></entry> 1500 </row> 1501 </thead> 1502 <tbody> 1503 <row> 1504 <entry>1</entry> 1505 <entry>?</entry> 1506 <entry>XSMP</entry> 1507 </row> 1508 <row> 1509 <entry>1</entry> 1510 <entry>2</entry> 1511 <entry>opcode</entry> 1512 </row> 1513 <row> 1514 <entry>2</entry> 1515 <entry></entry> 1516 <entry>unused</entry> 1517 </row> 1518 <row> 1519 <entry>4</entry> 1520 <entry>a/8</entry> 1521 <entry>length of remaining data in 8-byte units</entry> 1522 </row> 1523 <row> 1524 <entry>a</entry> 1525 <entry>ARRAY8</entry> 1526 <entry>client-ID</entry> 1527 </row> 1528 </tbody> 1529 </tgroup> 1530 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1531 <?dbfo keep-together="always" ?> 1532 <colspec colname='c1' colwidth='1.0*'/> 1533 <colspec colname='c2' colwidth='5.0*'/> 1534 <colspec colname='c3' colwidth='5.0*'/> 1535 <thead> 1536 <row> 1537 <entry namest='c1' nameend='c3'><emphasis role="bold"><function>SaveYourself</function></emphasis></entry> 1538 </row> 1539 </thead> 1540 <tbody> 1541 <row> 1542 <entry>1</entry> 1543 <entry>?</entry> 1544 <entry>XSMP</entry> 1545 </row> 1546 <row> 1547 <entry>1</entry> 1548 <entry>3</entry> 1549 <entry>opcode</entry> 1550 </row> 1551 <row> 1552 <entry>2</entry> 1553 <entry></entry> 1554 <entry>unused</entry> 1555 </row> 1556 <row> 1557 <entry>4</entry> 1558 <entry>1</entry> 1559 <entry>length of remaining data in 8-byte units</entry> 1560 </row> 1561 <row> 1562 <entry>1</entry> 1563 <entry>SAVE_TYPE</entry> 1564 <entry>type</entry> 1565 </row> 1566 <row> 1567 <entry>1</entry> 1568 <entry>BOOL</entry> 1569 <entry>shutdown</entry> 1570 </row> 1571 <row> 1572 <entry>1</entry> 1573 <entry>INTERACT_STYLE</entry> 1574 <entry>interact-style</entry> 1575 </row> 1576 <row> 1577 <entry>1</entry> 1578 <entry>BOOL</entry> 1579 <entry>fast</entry> 1580 </row> 1581 <row> 1582 <entry>4</entry> 1583 <entry></entry> 1584 <entry>unused</entry> 1585 </row> 1586 </tbody> 1587 </tgroup> 1588 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1589 <?dbfo keep-together="always" ?> 1590 <colspec colname='c1' colwidth='1.0*'/> 1591 <colspec colname='c2' colwidth='5.0*'/> 1592 <colspec colname='c3' colwidth='5.0*'/> 1593 <thead> 1594 <row> 1595 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>SaveYourselfRequest</function></emphasis></entry> 1596 </row> 1597 </thead> 1598 <tbody> 1599 <row> 1600 <entry>1</entry> 1601 <entry>?</entry> 1602 <entry>XSMP</entry> 1603 </row> 1604 <row> 1605 <entry>1</entry> 1606 <entry>4</entry> 1607 <entry>opcode</entry> 1608 </row> 1609 <row> 1610 <entry>2</entry> 1611 <entry></entry> 1612 <entry>unused</entry> 1613 </row> 1614 <row> 1615 <entry>4</entry> 1616 <entry>1</entry> 1617 <entry>length of remainning data in 8-byte units</entry> 1618 </row> 1619 <row> 1620 <entry>1</entry> 1621 <entry>SAVE_TYPE</entry> 1622 <entry>type</entry> 1623 </row> 1624 <row> 1625 <entry>1</entry> 1626 <entry>BOOL</entry> 1627 <entry>shutdown</entry> 1628 </row> 1629 <row> 1630 <entry>1</entry> 1631 <entry>INTERACT_STYLE</entry> 1632 <entry>interact-style</entry> 1633 </row> 1634 <row> 1635 <entry>1</entry> 1636 <entry>BOOL</entry> 1637 <entry>fast</entry> 1638 </row> 1639 <row> 1640 <entry>3</entry> 1641 <entry></entry> 1642 <entry>unused</entry> 1643 </row> 1644 </tbody> 1645 </tgroup> 1646 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1647 <?dbfo keep-together="always" ?> 1648 <colspec colname='c1' colwidth='1.0*'/> 1649 <colspec colname='c2' colwidth='5.0*'/> 1650 <colspec colname='c3' colwidth='5.0*'/> 1651 <thead> 1652 <row> 1653 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>InteractRequest</function></emphasis></entry> 1654 </row> 1655 </thead> 1656 <tbody> 1657 <row> 1658 <entry>1</entry> 1659 <entry>?</entry> 1660 <entry>XSMP</entry> 1661 </row> 1662 <row> 1663 <entry>1</entry> 1664 <entry>5</entry> 1665 <entry>opcode</entry> 1666 </row> 1667 <row> 1668 <entry>1</entry> 1669 <entry>DIALOG_TYPE</entry> 1670 <entry>dialog type</entry> 1671 </row> 1672 <row> 1673 <entry>1</entry> 1674 <entry></entry> 1675 <entry>unused</entry> 1676 </row> 1677 <row> 1678 <entry>4</entry> 1679 <entry>0</entry> 1680 <entry>length of remaining data in 8-byte units</entry> 1681 </row> 1682 </tbody> 1683 </tgroup> 1684 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1685 <?dbfo keep-together="always" ?> 1686 <colspec colname='c1' colwidth='1.0*'/> 1687 <colspec colname='c2' colwidth='5.0*'/> 1688 <colspec colname='c3' colwidth='5.0*'/> 1689 <thead> 1690 <row> 1691 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>Interact</function></emphasis></entry> 1692 </row> 1693 </thead> 1694 <tbody> 1695 <row> 1696 <entry>1</entry> 1697 <entry>?</entry> 1698 <entry>XSMP</entry> 1699 </row> 1700 <row> 1701 <entry>1</entry> 1702 <entry>6</entry> 1703 <entry>opcode</entry> 1704 </row> 1705 <row> 1706 <entry>2</entry> 1707 <entry></entry> 1708 <entry>unused</entry> 1709 </row> 1710 <row> 1711 <entry>4</entry> 1712 <entry>0</entry> 1713 <entry>length of remaining data in 8-byte units</entry> 1714 </row> 1715 </tbody> 1716 </tgroup> 1717 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1718 <?dbfo keep-together="always" ?> 1719 <colspec colname='c1' colwidth='1.0*'/> 1720 <colspec colname='c2' colwidth='5.0*'/> 1721 <colspec colname='c3' colwidth='5.0*'/> 1722 <thead> 1723 <row> 1724 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>InteractDone</function></emphasis></entry> 1725 </row> 1726 </thead> 1727 <tbody> 1728 <row> 1729 <entry>1</entry> 1730 <entry>?</entry> 1731 <entry>XSMP</entry> 1732 </row> 1733 <row> 1734 <entry>1</entry> 1735 <entry>7</entry> 1736 <entry>opcode</entry> 1737 </row> 1738 <row> 1739 <entry>1</entry> 1740 <entry>BOOL</entry> 1741 <entry>cancel-shutdown</entry> 1742 </row> 1743 <row> 1744 <entry>1</entry> 1745 <entry></entry> 1746 <entry>unused</entry> 1747 </row> 1748 </tbody> 1749 </tgroup> 1750 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1751 <?dbfo keep-together="always" ?> 1752 <colspec colname='c1' colwidth='1.0*'/> 1753 <colspec colname='c2' colwidth='5.0*'/> 1754 <colspec colname='c3' colwidth='5.0*'/> 1755 <thead> 1756 <row> 1757 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>InteractDone</function></emphasis></entry> 1758 </row> 1759 </thead> 1760 <tbody> 1761 <row> 1762 <entry>1</entry> 1763 <entry>?</entry> 1764 <entry>XSMP</entry> 1765 </row> 1766 <row> 1767 <entry>1</entry> 1768 <entry>7</entry> 1769 <entry>opcode</entry> 1770 </row> 1771 <row> 1772 <entry>1</entry> 1773 <entry>BOOL</entry> 1774 <entry>cancel-shutdown</entry> 1775 </row> 1776 <row> 1777 <entry>1</entry> 1778 <entry></entry> 1779 <entry>unused</entry> 1780 </row> 1781 <row> 1782 <entry>4</entry> 1783 <entry>0</entry> 1784 <entry>length of remaining data in 8-byte units</entry> 1785 </row> 1786 </tbody> 1787 </tgroup> 1788 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1789 <?dbfo keep-together="always" ?> 1790 <colspec colname='c1' colwidth='1.0*'/> 1791 <colspec colname='c2' colwidth='5.0*'/> 1792 <colspec colname='c3' colwidth='5.0*'/> 1793 <thead> 1794 <row> 1795 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>SaveYourselfDone</function></emphasis></entry> 1796 </row> 1797 </thead> 1798 <tbody> 1799 <row> 1800 <entry>1</entry> 1801 <entry>?</entry> 1802 <entry>XSMP</entry> 1803 </row> 1804 <row> 1805 <entry>1</entry> 1806 <entry>8</entry> 1807 <entry>opcode</entry> 1808 </row> 1809 <row> 1810 <entry>1</entry> 1811 <entry>BOOL</entry> 1812 <entry>success</entry> 1813 </row> 1814 <row> 1815 <entry>1</entry> 1816 <entry></entry> 1817 <entry>unused</entry> 1818 </row> 1819 <row> 1820 <entry>4</entry> 1821 <entry>0</entry> 1822 <entry>length of remaining data in 8-byte units</entry> 1823 </row> 1824 </tbody> 1825 </tgroup> 1826 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1827 <?dbfo keep-together="always" ?> 1828 <colspec colname='c1' colwidth='1.0*'/> 1829 <colspec colname='c2' colwidth='5.0*'/> 1830 <colspec colname='c3' colwidth='5.0*'/> 1831 <thead> 1832 <row> 1833 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>Die</function></emphasis></entry> 1834 </row> 1835 </thead> 1836 <tbody> 1837 <row> 1838 <entry>1</entry> 1839 <entry>?</entry> 1840 <entry>XSMP</entry> 1841 </row> 1842 <row> 1843 <entry>1</entry> 1844 <entry>9</entry> 1845 <entry>opcode</entry> 1846 </row> 1847 <row> 1848 <entry>1</entry> 1849 <entry></entry> 1850 <entry>unused</entry> 1851 </row> 1852 <row> 1853 <entry>4</entry> 1854 <entry>0</entry> 1855 <entry>length of remaining data in 8-byte units</entry> 1856 </row> 1857 </tbody> 1858 </tgroup> 1859 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1860 <?dbfo keep-together="always" ?> 1861 <colspec colname='c1' colwidth='1.0*'/> 1862 <colspec colname='c2' colwidth='5.0*'/> 1863 <colspec colname='c3' colwidth='5.0*'/> 1864 <thead> 1865 <row> 1866 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>ShutdownCancelled</function></emphasis></entry> 1867 </row> 1868 </thead> 1869 <tbody> 1870 <row> 1871 <entry>1</entry> 1872 <entry>?</entry> 1873 <entry>XSMP</entry> 1874 </row> 1875 <row> 1876 <entry>1</entry> 1877 <entry>10</entry> 1878 <entry>opcode</entry> 1879 </row> 1880 <row> 1881 <entry>2</entry> 1882 <entry></entry> 1883 <entry>unused</entry> 1884 </row> 1885 <row> 1886 <entry>4</entry> 1887 <entry>0</entry> 1888 <entry>length of remaining data in 8-byte units</entry> 1889 </row> 1890 </tbody> 1891 </tgroup> 1892 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1893 <?dbfo keep-together="always" ?> 1894 <colspec colname='c1' colwidth='1.0*'/> 1895 <colspec colname='c2' colwidth='5.0*'/> 1896 <colspec colname='c3' colwidth='5.0*'/> 1897 <thead> 1898 <row> 1899 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>ConnectionClosed</function></emphasis></entry> 1900 </row> 1901 </thead> 1902 <tbody> 1903 <row> 1904 <entry>1</entry> 1905 <entry>?</entry> 1906 <entry>XSMP</entry> 1907 </row> 1908 <row> 1909 <entry>1</entry> 1910 <entry>11</entry> 1911 <entry>opcode</entry> 1912 </row> 1913 <row> 1914 <entry>2</entry> 1915 <entry></entry> 1916 <entry>unused</entry> 1917 </row> 1918 <row> 1919 <entry>4</entry> 1920 <entry>a/8</entry> 1921 <entry>length of remaining data in 8-byte units</entry> 1922 </row> 1923 <row> 1924 <entry>a</entry> 1925 <entry>LISTofARRAY8</entry> 1926 <entry>reason</entry> 1927 </row> 1928 </tbody> 1929 </tgroup> 1930 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1931 <?dbfo keep-together="always" ?> 1932 <colspec colname='c1' colwidth='1.0*'/> 1933 <colspec colname='c2' colwidth='5.0*'/> 1934 <colspec colname='c3' colwidth='5.0*'/> 1935 <thead> 1936 <row> 1937 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>SetProperties</function></emphasis></entry> 1938 </row> 1939 </thead> 1940 <tbody> 1941 <row> 1942 <entry>1</entry> 1943 <entry>?</entry> 1944 <entry>XSMP</entry> 1945 </row> 1946 <row> 1947 <entry>1</entry> 1948 <entry>12</entry> 1949 <entry>opcode</entry> 1950 </row> 1951 <row> 1952 <entry>2</entry> 1953 <entry></entry> 1954 <entry>unused</entry> 1955 </row> 1956 <row> 1957 <entry>4</entry> 1958 <entry>a/8</entry> 1959 <entry>length of remaining data in 8-byte units</entry> 1960 </row> 1961 <row> 1962 <entry>a</entry> 1963 <entry>LISTofPROPERTY</entry> 1964 <entry>properties</entry> 1965 </row> 1966 </tbody> 1967 </tgroup> 1968 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 1969 <?dbfo keep-together="always" ?> 1970 <colspec colname='c1' colwidth='1.0*'/> 1971 <colspec colname='c2' colwidth='5.0*'/> 1972 <colspec colname='c3' colwidth='5.0*'/> 1973 <thead> 1974 <row> 1975 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>DeleteProperties</function></emphasis></entry> 1976 </row> 1977 </thead> 1978 <tbody> 1979 <row> 1980 <entry>1</entry> 1981 <entry>?</entry> 1982 <entry>XSMP</entry> 1983 </row> 1984 <row> 1985 <entry>1</entry> 1986 <entry>13</entry> 1987 <entry>opcode</entry> 1988 </row> 1989 <row> 1990 <entry>2</entry> 1991 <entry></entry> 1992 <entry>unused</entry> 1993 </row> 1994 <row> 1995 <entry>4</entry> 1996 <entry>a/8</entry> 1997 <entry>length of remaining data in 8-byte units</entry> 1998 </row> 1999 <row> 2000 <entry>a</entry> 2001 <entry>LISTofPROPERTY</entry> 2002 <entry>properties</entry> 2003 </row> 2004 </tbody> 2005 </tgroup> 2006 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 2007 <?dbfo keep-together="always" ?> 2008 <colspec colname='c1' colwidth='1.0*'/> 2009 <colspec colname='c2' colwidth='5.0*'/> 2010 <colspec colname='c3' colwidth='5.0*'/> 2011 <thead> 2012 <row> 2013 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>GetProperties</function></emphasis></entry> 2014 </row> 2015 </thead> 2016 <tbody> 2017 <row> 2018 <entry>1</entry> 2019 <entry>?</entry> 2020 <entry>XSMP</entry> 2021 </row> 2022 <row> 2023 <entry>1</entry> 2024 <entry>14</entry> 2025 <entry>opcode</entry> 2026 </row> 2027 <row> 2028 <entry>2</entry> 2029 <entry></entry> 2030 <entry>unused</entry> 2031 </row> 2032 <row> 2033 <entry>4</entry> 2034 <entry>0</entry> 2035 <entry>length of remaining data in 8-byte units</entry> 2036 </row> 2037 </tbody> 2038 </tgroup> 2039 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 2040 <?dbfo keep-together="always" ?> 2041 <colspec colname='c1' colwidth='1.0*'/> 2042 <colspec colname='c2' colwidth='5.0*'/> 2043 <colspec colname='c3' colwidth='5.0*'/> 2044 <thead> 2045 <row> 2046 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>GetPropertiesReply</function></emphasis></entry> 2047 </row> 2048 </thead> 2049 <tbody> 2050 <row> 2051 <entry>1</entry> 2052 <entry>?</entry> 2053 <entry>XSMP</entry> 2054 </row> 2055 <row> 2056 <entry>1</entry> 2057 <entry>15</entry> 2058 <entry>opcode</entry> 2059 </row> 2060 <row> 2061 <entry>2</entry> 2062 <entry></entry> 2063 <entry>unused</entry> 2064 </row> 2065 <row> 2066 <entry>4</entry> 2067 <entry>a/8</entry> 2068 <entry>length of remaining data in 8-byte units</entry> 2069 </row> 2070 <row> 2071 <entry>a</entry> 2072 <entry>LISTofPROPERTY</entry> 2073 <entry>properties</entry> 2074 </row> 2075 </tbody> 2076 </tgroup> 2077 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 2078 <?dbfo keep-together="always" ?> 2079 <colspec colname='c1' colwidth='1.0*'/> 2080 <colspec colname='c2' colwidth='5.0*'/> 2081 <colspec colname='c3' colwidth='5.0*'/> 2082 <thead> 2083 <row> 2084 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>SaveYourselfPhase2Request</function></emphasis></entry> 2085 </row> 2086 </thead> 2087 <tbody> 2088 <row> 2089 <entry>1</entry> 2090 <entry>?</entry> 2091 <entry>XSMP</entry> 2092 </row> 2093 <row> 2094 <entry>1</entry> 2095 <entry>16</entry> 2096 <entry>opcode</entry> 2097 </row> 2098 <row> 2099 <entry>2</entry> 2100 <entry></entry> 2101 <entry>unused</entry> 2102 </row> 2103 <row> 2104 <entry>4</entry> 2105 <entry>0</entry> 2106 <entry>length of remaining data in 8-byte units</entry> 2107 </row> 2108 </tbody> 2109 </tgroup> 2110 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 2111 <?dbfo keep-together="always" ?> 2112 <colspec colname='c1' colwidth='1.0*'/> 2113 <colspec colname='c2' colwidth='5.0*'/> 2114 <colspec colname='c3' colwidth='5.0*'/> 2115 <thead> 2116 <row> 2117 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>SaveYourselfPhase2</function></emphasis></entry> 2118 </row> 2119 </thead> 2120 <tbody> 2121 <row> 2122 <entry>1</entry> 2123 <entry>?</entry> 2124 <entry>XSMP</entry> 2125 </row> 2126 <row> 2127 <entry>1</entry> 2128 <entry>17</entry> 2129 <entry>opcode</entry> 2130 </row> 2131 <row> 2132 <entry>2</entry> 2133 <entry></entry> 2134 <entry>unused</entry> 2135 </row> 2136 <row> 2137 <entry>4</entry> 2138 <entry>0</entry> 2139 <entry>length of remaining data in 8-byte units</entry> 2140 </row> 2141 </tbody> 2142 </tgroup> 2143 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 2144 <?dbfo keep-together="always" ?> 2145 <colspec colname='c1' colwidth='1.0*'/> 2146 <colspec colname='c2' colwidth='5.0*'/> 2147 <colspec colname='c3' colwidth='5.0*'/> 2148 <thead> 2149 <row> 2150 <entry namest="c1" nameend="c3"><emphasis role="bold"><function>SaveComplete</function></emphasis></entry> 2151 </row> 2152 </thead> 2153 <tbody> 2154 <row> 2155 <entry>1</entry> 2156 <entry>?</entry> 2157 <entry>XSMP</entry> 2158 </row> 2159 <row> 2160 <entry>1</entry> 2161 <entry>18</entry> 2162 <entry>opcode</entry> 2163 </row> 2164 <row> 2165 <entry>2</entry> 2166 <entry></entry> 2167 <entry>unused</entry> 2168 </row> 2169 <row> 2170 <entry>4</entry> 2171 <entry>0</entry> 2172 <entry>length of remaining data in 8-byte units</entry> 2173 </row> 2174 </tbody> 2175 </tgroup> 2176</informaltable> 2177 2178 </sect1> 2179</chapter> 2180 2181<chapter id='Predefined_Properties'> 2182 <title>Predefined Properties</title> 2183 <para> 2184All property values are stored in a LISTofARRAY8. If the type of the 2185property is CARD8, the value is stored as a LISTofARRAY8 with one 2186ARRAY8 that is one byte long. That single byte contains the CARD8. 2187If the type of the property is ARRAY8, the value is stored in the 2188first element of a single element LISTofARRAY8. 2189 </para> 2190 2191 <para> 2192The required properties must be set each time a client connects with 2193the SM. The properties must be set after the client 2194sends <function>RegisterClient</function> and before the client 2195sends <function>SaveYourselfDone</function> Otherwise, the behavior of 2196the session manager is not defined. 2197 </para> 2198 2199 <para> 2200Clients may set, get, and delete nonstandard properties. The lifetime 2201of stored properties does not extend into subsequent sessions. 2202 </para> 2203 2204<informaltable frame='topbot'> 2205 <tgroup cols='4' align='left' colsep='0' rowsep='0'> 2206 <colspec colname='c1' colwidth='2.0*' /> 2207 <colspec colname='c2' colwidth='2.0*' /> 2208 <colspec colname='c3' colwidth='2.0*' /> 2209 <colspec colname='c4' colwidth='1.0*' /> 2210 <thead> 2211 <row rowsep='1'> 2212 <entry>Name</entry> 2213 <entry>Type</entry> 2214 <entry>Posix Type</entry> 2215 <entry>Required?</entry> 2216 </row> 2217 </thead> 2218 <tbody> 2219 <row> 2220 <entry>CloneCommand</entry> 2221 <entry>OS-specific</entry> 2222 <entry>LISTofARRAY8</entry> 2223 <entry>Yes</entry> 2224 </row> 2225 <row> 2226 <entry>CurrentDirectory</entry> 2227 <entry>OS-specific</entry> 2228 <entry>ARRAY8</entry> 2229 <entry>No</entry> 2230 </row> 2231 <row> 2232 <entry>DiscardCommand</entry> 2233 <entry>OS-specific</entry> 2234 <entry>LISTofARRAY8</entry> 2235 <entry>No*</entry> 2236 </row> 2237 <row> 2238 <entry>Environment</entry> 2239 <entry>OS-specific</entry> 2240 <entry>LISTofARRAY8</entry> 2241 <entry>No</entry> 2242 </row> 2243 <row> 2244 <entry>ProcessID</entry> 2245 <entry>OS-specific</entry> 2246 <entry>ARRAY8</entry> 2247 <entry>No</entry> 2248 </row> 2249 <row> 2250 <entry>Program</entry> 2251 <entry>OS-specific</entry> 2252 <entry>ARRAY8</entry> 2253 <entry>Yes</entry> 2254 </row> 2255 <row> 2256 <entry>RestartCommand</entry> 2257 <entry>OS-specific</entry> 2258 <entry>LISTofARRAY8</entry> 2259 <entry>Yes</entry> 2260 </row> 2261 <row> 2262 <entry>ResignCommand</entry> 2263 <entry>OS-specific</entry> 2264 <entry>LISTofARRAY8</entry> 2265 <entry>No</entry> 2266 </row> 2267 <row> 2268 <entry>RestartStyleHint</entry> 2269 <entry>CARD8</entry> 2270 <entry>CARD8</entry> 2271 <entry>No</entry> 2272 </row> 2273 <row> 2274 <entry>ShutdownCommand</entry> 2275 <entry>OS-specific</entry> 2276 <entry>LISTofARRAY8</entry> 2277 <entry>No</entry> 2278 </row> 2279 <row> 2280 <entry>UserID</entry> 2281 <entry>ARRAY8</entry> 2282 <entry>ARRAY8</entry> 2283 <entry>Yes</entry> 2284 </row> 2285 </tbody> 2286 </tgroup> 2287</informaltable> 2288 2289 <para> 2290* Required if any state is stored in an external repository (e.g., state file). 2291 </para> 2292 2293 <variablelist remap='IP'> 2294 <varlistentry> 2295 <term>CloneCommand</term> 2296 <listitem> <para> 2297This is like the <function>RestartCommand</function> except it 2298restarts a copy of the application. The only difference is that the 2299application doesn't supply its client id at register time. On <acronym>POSIX</acronym> 2300systems the type should be a LISTofARRAY8. 2301 </para></listitem> 2302 </varlistentry> 2303 <varlistentry> 2304 <term>CurrentDirectory</term> 2305 <listitem><para> 2306On <acronym>POSIX</acronym>-based systems specifies the value of the current directory that 2307needs to be set up prior to starting the program and should be of type ARRAY8. 2308 </para></listitem> 2309 </varlistentry> 2310 <varlistentry> 2311 <term>DiscardCommand</term> 2312 <listitem><para> 2313The discard command contains a command that when delivered to the host 2314that the client is running on (determined from the connection), will 2315cause it to discard any information about the current state. If this 2316command is not specified, the SM will assume that all of the client's 2317state is encoded in the <function>Restart­Command</function> On 2318<acronym>POSIX</acronym> systems the type should be LISTofARRAY8. 2319 </para></listitem> 2320 </varlistentry> 2321 <varlistentry> 2322 <term>Environment</term> 2323 <listitem><para> 2324On <acronym>POSIX</acronym> based systems, this will be of type LISTofARRAY8 where the 2325ARRAY8s alternate between environment variable name and environment 2326variable value. 2327 </para></listitem> 2328 </varlistentry> 2329 <varlistentry> 2330 <term>ProcessID</term> 2331 <listitem><para> 2332This specifies an OS-specific identifier for the process. On <acronym>POSIX</acronym> 2333systems this should of type ARRAY8 and contain the return value of 2334getpid() turned into a Latin-1 (decimal) string. 2335 </para></listitem> 2336 </varlistentry> 2337 <varlistentry> 2338 <term>Program</term> 2339 <listitem><para> 2340The name of the program that is running. On <acronym>POSIX</acronym> systems this should 2341be the first parameter passed to execve and should be of type ARRAY8. 2342 </para></listitem> 2343 </varlistentry> 2344 <varlistentry> 2345 <term>RestartCommand</term> 2346 <listitem><para> 2347The restart command contains a command that when delivered to the host 2348that the client is running on (determined from the connection), will 2349cause the client to restart in its current state. On <acronym>POSIX</acronym>-based 2350systems this is of type LISTofARRAY8 and each of the elements in the 2351array represents an element in the argv array. This restart command 2352should ensure that the client restarts with the specified 2353client-ID. 2354 </para></listitem> 2355 </varlistentry> 2356 <varlistentry> 2357 <term>ResignCommand</term> 2358 <listitem> 2359 <para> 2360A client that sets the <function>RestartStyleHint</function> 2361to <function>RestartAnyway</function> uses this property to specify a 2362command that undoes the effect of the client and removes any saved 2363state. 2364 </para> 2365 <note><title>Example</title><para> 2366A user runs xmodmap. xmodmap registers with the SM, 2367sets <function>Restart­Style­Hint</function> 2368to <function>Restart­Anyway</function> and then terminates. In 2369order to allow the SM (at the user's request) to undo this, xmodmap 2370would register a <function>Resign­Command</function> that undoes 2371the effects of the xmodmap. 2372 </para></note> 2373 </listitem> 2374 </varlistentry> 2375 <varlistentry> 2376 <term>RestartStyleHint</term> 2377 <listitem> 2378 <para> 2379If the RestartStyleHint property is present, it will contain the style 2380of restarting the client prefers. If this flag isn't 2381specified, <function>RestartIfRunning</function> is assumed. The 2382possible values are as follows: 2383 </para> 2384 2385<informaltable frame='topbot'> 2386 <?dbfo keep-together="always" ?> 2387 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 2388 <colspec colname='c1' colwidth='1.0*'/> 2389 <colspec colname='c2' colwidth='2.5*'/> 2390 <thead> 2391 <row rowsep='1'> 2392 <entry>Name</entry> 2393 <entry>Value</entry> 2394 </row> 2395 </thead> 2396 <tbody> 2397 <row> 2398 <entry>RestartIfRunning</entry> 2399 <entry>0</entry> 2400 </row> 2401 <row> 2402 <entry>RestartAnyway</entry> 2403 <entry>1</entry> 2404 </row> 2405 <row> 2406 <entry>RestartImmediately</entry> 2407 <entry>2</entry> 2408 </row> 2409 <row> 2410 <entry>RestartNever</entry> 2411 <entry>3</entry> 2412 </row> 2413 </tbody> 2414 </tgroup> 2415</informaltable> 2416 2417 <para> 2418The <function>RestartIfRunning</function> style is used in the usual 2419case. The client should be restarted in the next session if it is 2420connected to the session manager at the end of the current session. 2421 </para> 2422 2423 <para> 2424The <function>RestartAnyway</function> style is used to tell the SM 2425that the application should be restarted in the next session even if 2426it exits before the current session is terminated. It should be noted 2427that this is only a hint and the SM will follow the policies specified 2428by its users in determining what applications to restart. 2429 </para> 2430 2431 <note><title>Rationale</title><para> 2432This can be specified by a client which supports (as MS-Windows 2433clients do) a means for the user to indicate while exiting that 2434restarting is desired. It can also be used for clients that spawn 2435other clients and then go away, but which want to be restarted. 2436 </para></note> 2437 2438 <para> 2439A client that uses <function>RestartAnyway</function> should also set 2440the <function>ResignCommand</function> and <function>ShutdownCommand</function> 2441properties to commands that undo the state of the client after it exits. 2442 </para> 2443 2444 <para> 2445The <function>RestartImmediately</function> style is 2446like <function>RestartAnyway</function> but in addition, the client is 2447meant to run continuously. If the client exits, the SM should try to 2448restart it in the current session. 2449 </para> 2450 2451 <note><title>Advice to Implementors</title><para> 2452It would be wise to sanity-check the frequency which 2453which <function>RestartImmediately</function> clients are restarted, 2454to avoid a sick client being restarted continuously. 2455 </para></note> 2456 2457 <para> 2458The <function>RestartNever</function> style specifies that the client 2459does not wish to be restarted in the next session. 2460 </para> 2461 2462 <note><title>Advice to Implementors</title> <para> 2463This should be used rarely, if at all. It will cause the client to be 2464silently left out of sessions when they are restarted and will 2465probably be confusing to users. 2466 </para></note> <!-- remap='NE' --> 2467 <!-- .RE --> 2468 </listitem> 2469 </varlistentry> 2470 <varlistentry> 2471 <term>ShutdownCommand</term> 2472 <listitem> 2473 <para> 2474This command is executed at shutdown time to clean up after a client 2475that is no longer running but retained its state by 2476setting <function>RestartStyleHint</function> 2477to <function>RestartAnyway</function> The command must not remove any 2478saved state as the client is still part of the session. 2479 </para> 2480 <note><title>Example</title><para> 2481A client is run at start up time that turns on a camera. This client 2482then exits. At session shutdown, the user wants the camera turned 2483off. This client would set the <function>Restart­Style­Hint</function> 2484to <function>Restart­Anyway</function> and would register a 2485<function>Shutdown­Command</function> that would turn off the camera. 2486 </para></note> 2487 </listitem> 2488 </varlistentry> 2489 <varlistentry> 2490 <term>UserID</term> 2491 <listitem><para> 2492Specifies the user's ID. On <acronym>POSIX</acronym>-based systems 2493this will contain the the user's name (the <structfield>pw_name</structfield> 2494field of <structname>struct passwd</structname>). 2495 </para></listitem> 2496 </varlistentry> 2497 </variablelist> 2498</chapter> 2499</book> 2500