home *** CD-ROM | disk | FTP | other *** search
/ Chip 2001 August - Disc 2 / chip_20018102_hu.iso / linux / X-4.1.0 / doc / xsmp.txt < prev    next >
Text File  |  2001-06-27  |  45KB  |  1,915 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.            X Session Management Protocol
  12.  
  13.            X Consortium Standard
  14.  
  15.          X Version 11, Release 6.4
  16.  
  17.             Mike Wexler
  18.            Kubota Pacific Computer, Inc.
  19.  
  20.  
  21.               ABSTRACT
  22.  
  23.  
  24.  
  25.      This document specifies a protocol that facili-
  26.      tates the management of groups of client applica-
  27.      tions by a session manager.  The session manager
  28.      can cause clients to save their state, to shut
  29.      down, and to be restarted into a previously saved
  30.      state.  This protocol is layered on top of the X
  31.      Consortium's ICE protocol.
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.     X Window System is a trademark of X Consortium, Inc.
  85.  
  86.     Copyright (C) 1992, 1993, 1994 X Consortium
  87.  
  88.  
  89.  
  90.  
  91.  
  92. Permission is hereby granted, free of charge, to any person
  93. obtaining a copy of this software and associated documenta-
  94. tion files (the ``Software''), to deal in the Software with-
  95. out restriction, including without limitation the rights to
  96. use, copy, modify, merge, publish, distribute, sublicense,
  97. and/or sell copies of the Software, and to permit persons to
  98. whom the Software is furnished to do so, subject to the fol-
  99. lowing conditions:
  100.  
  101. The above copyright notice and this permission notice shall
  102. be included in all copies or substantial portions of the
  103. Software.
  104.  
  105. THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY
  106. KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  107. WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR-
  108. POSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR-
  109. TIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  110. WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  111. FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
  112. OR OTHER DEALINGS IN THE SOFTWARE.
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                  ii
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. 1.  Acknowledgements
  140.  
  141. First I would like to thank the entire ICCCM and Intrinsics
  142. working groups for the comments and suggestions. I would
  143. like to make special thanks to the following people (in
  144. alphabetical order), Jordan Brown, Ellis Cohen, Donna Con-
  145. verse, Vania Joloboff, Stuart Marks, Ralph Mor and Bob
  146. Scheifler.
  147.  
  148. 2.  Definitions and Goals
  149.  
  150. The purpose of the X Session Management Protocol (XSMP) is
  151. to provide a uniform mechanism for users to save and restore
  152. their sessions.  A session is a group of clients, each of
  153. which has a particular state.  The session is controlled by
  154. a network service called the session manager.  The session
  155. manager issues commands to its clients on behalf of the
  156. user.  These commands may cause clients to save their state
  157. or to terminate.  It is expected that the client will save
  158. its state in such a way that the client can be restarted at
  159. a later time and resume its operation as if it had never
  160. been terminated.  A client's state might include information
  161. about the file currently being edited, the current position
  162. of the insertion point within the file, or the start of an
  163. uncommitted transaction.  The means by which clients are
  164. restarted is unspecified by this protocol.
  165.  
  166. For purposes of this protocol, a client of the session man-
  167. ager is defined as a connection to the session manager.  A
  168. client is typically, though not necessarily, a process run-
  169. ning an application program connected to an X Window System
  170. display.  However, a client may be connected to more than
  171. one X display or not be connected to any X displays at all.
  172.  
  173. This protocol is layered on top of the X Consortium's ICE
  174. protocol and relies on the ICE protocol to handle connection
  175. management and authentication.
  176.  
  177.  
  178. 3.  Overview of the Protocol
  179.  
  180. Clients use XSMP to register themselves with the session
  181. manager (SM).  When a client starts up, it should connect to
  182. the SM.  The client should remain connected for as long as
  183. it runs.  A client may resign from the session by issuing
  184. the proper protocol messages before disconnecting.  Termina-
  185. tion of the connection without notice will be taken as an
  186. indication that the client died unexpectedly.
  187.  
  188. Clients are expected to save their state in such a way as to
  189. allow multiple instantiations of themselves to be managed
  190. independently.    A unique value called a client-ID is pro-
  191. vided by the protocol for the purpose of disambiguating mul-
  192. tiple instantiations of clients.  Clients may use this ID,
  193.  
  194.  
  195.  
  196.                   1
  197.  
  198.  
  199.  
  200.  
  201.  
  202. X Session Management Protocol            X11, Release 6.4
  203.  
  204.  
  205. for example, as part of a filename in which to store the
  206. state for a particular instantiation.  The client-ID should
  207. be saved as part of the command used to restart this client
  208. (the RestartCommand) so that the client will retain the same
  209. ID after it is restarted.  Certain small pieces of state
  210. might also be stored in the RestartCommand.   For example,
  211. an X11 client might place a `-twoWindow' option in its
  212. RestartCommand to indicate that it should start up in two
  213. window mode when it is restarted.
  214.  
  215. The client finds the network address of the SM in a system-
  216. dependent way.    On POSIX systems an environment variable
  217. called SESSION_MANAGER will contain a list of network IDs.
  218. Each id will contain the transport name followed by a slash
  219. and the (transport-specific) address.  A TCP/IP address
  220. would look like this:
  221.  
  222.       tcp/hostname:portnumber
  223.  
  224. where the hostname is a fully qualified domain name.  A Unix
  225. Domain address looks like this:
  226.  
  227.       local/hostname:path
  228.  
  229. A DECnet address would look like this:
  230.  
  231.       decnet/nodename::objname
  232.  
  233. If multiple network IDs are specified, they should be sepa-
  234. rated by commas.
  235.  
  236.              Rationale
  237.  
  238.      There was much discussion over whether the XSMP
  239.      protocol should use X as the transport protocol or
  240.      whether it should use its own independent trans-
  241.      port.  It was decided that it would use an inde-
  242.      pendent protocol for several reasons.  First, the
  243.      Session Manager should be able to manage programs
  244.      that do not maintain an X connection.  Second, the
  245.      X protocol is not appropriate to use as a general-
  246.      purpose transport protocol.  Third, a session
  247.      might span multiple displays.
  248.  
  249.      The protocol is connection based, because there is
  250.      no other way for the SM to determine reliably when
  251.      clients terminate.
  252.  
  253.      It should be noted that this protocol introduces
  254.      another single point of failure into the system.
  255.      Although it is possible for clients to continue
  256.      running after the SM has exited, this will proba-
  257.      bly not be the case in normal practice.  Normally
  258.      the program that starts the SM will consider the
  259.  
  260.  
  261.  
  262.                   2
  263.  
  264.  
  265.  
  266.  
  267.  
  268. X Session Management Protocol            X11, Release 6.4
  269.  
  270.  
  271.      session to be terminated when the SM exits (either
  272.      normally or abnormally).
  273.  
  274.      To get around this would require some sort of ren-
  275.      dezvous server that would also introduce a single
  276.      point of failure.    In the absence of a generally
  277.      available rendezvous server, XSMP is kept simple
  278.      in the hopes of making simple reliable SMs.
  279.  
  280.  
  281. Some clients may wish to manage the programs they start.
  282. For example, a mail program could start a text editor for
  283. editing the text of a mail message.  A client that does this
  284. is a session manager itself; it should supply the clients it
  285. starts with the appropriate connection information (i.e.,
  286. the SESSION_MANAGER environment variable) that specifies a
  287. connection to itself instead of to the top level session
  288. manager.
  289.  
  290. Each client has associated with it a list of properties.  A
  291. property set by one client is not visible to any other
  292. client.  These properties are used for the client to inform
  293. the SM of the client's current state.  When a client ini-
  294. tially connects to the SM, there are no properties set.
  295.  
  296. 4.  Data Types
  297.  
  298. XSMP messages contain several types of data.  Both the SM
  299. and the client always send messages in their native byte
  300. order.    Thus, both sides may need to byte-swap the messages
  301. received.  The need to do byte-swapping is determined at
  302. run-time by the ICE protocol.
  303.  
  304. If an invalid value is specified for a field of any of the
  305. enumerated types, a BadValue error message must be sent by
  306. the receiver of the message to the sender of the message.
  307.  
  308. ------------------------------------------------------------------------------------
  309. Type Name     Description
  310. ------------------------------------------------------------------------------------
  311. BOOL         False or True
  312. INTERACT_STYLE     None, Errors, or Any
  313. DIALOG_TYPE     Error or Normal
  314. SAVE_TYPE     Global, Local, or Both
  315. CARD8         a one-byte unsigned integer
  316. CARD16         a two-byte unsigned integer
  317. CARD32         a four-byte unsigned integer
  318. ARRAY8         a sequence of CARD8s
  319. LISTofARRAY8     a sequence of ARRAY8s
  320. PROPERTY     a property name (an ARRAY8), a type name, and a value of that type
  321. LISTofPROPERTY     a counted collection of PROPERTYs.
  322. ------------------------------------------------------------------------------------
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                   3
  329.  
  330.  
  331.  
  332.  
  333.  
  334. X Session Management Protocol            X11, Release 6.4
  335.  
  336.  
  337. 5.  Protocol Setup and Message Format
  338.  
  339. To start the XSMP protocol, the client sends the server an
  340. ICE ProtocolSetup message.  All XSMP messages are in the
  341. standard ICE message format.  The message's major opcode is
  342. assigned to XSMP by ICE at run-time.  The different parties
  343. (client and SM) may be assigned different major opcodes for
  344. XSMP.  Once assigned, all XSMP messages issued by this party
  345. will use the same major opcode.  The message's minor opcode
  346. specifies which protocol message this message contains.
  347.  
  348. 6.  Client Identification String
  349.  
  350. A client ID is a string of XPCS characters encoded in ISO
  351. Latin 1 (ISO 8859-1).  No null characters are allowed in
  352. this string.  The client ID string is used in the Register-
  353. Client and RegisterClientReply messages.
  354.  
  355. Client IDs consist of the pieces described below.  The ID is
  356. formed by concatenating the pieces in sequence, without sep-
  357. arator characters.  All pieces are padded on the left with
  358. '0' characters so as to fill the specified length.  Decimal
  359. numbers are encoded using the characters `0' through `9',
  360. and hexadecimal numbers using the characters `0' through `9'
  361. and `A' through `F'.
  362.  
  363. o   Version.  This is currently the character `1'.
  364.  
  365. o   Address type and address.  The address type will be one
  366.     of
  367.  
  368.      `1'  a 4-byte IP address encoded as 8 hexadecimal digits
  369.      `2'  a 6-byte DECNET address encoded as 12 hexadecimal digits
  370.  
  371.  
  372.     The address is the one of the network addresses of the
  373.     machine where the session manager (not the client) is
  374.     running.  For example, the IP address 198.112.45.11
  375.     would be encoded as the string "C6702D0B".
  376.  
  377. o   Time stamp.  A 13-digit decimal number specifying the
  378.     number of milliseconds since 00:00:00 UTC, January 1,
  379.     1970.
  380.  
  381. o   Process-ID type and process-ID.  The process-ID type
  382.     will be one of
  383.  
  384.      `1'  a POSIX process-ID encoded as a 10-digit decimal number.
  385.  
  386.  
  387.     The process-ID is the process-ID of the session manager,
  388.     not of a client.
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                   4
  395.  
  396.  
  397.  
  398.  
  399.  
  400. X Session Management Protocol            X11, Release 6.4
  401.  
  402.  
  403. o   Sequence number.  This is a four-digit decimal number.
  404.     It is incremented every time the session manager creates
  405.     an ID.  After reaching "9999" it wraps to "0000".
  406.  
  407.                Rationale
  408.  
  409.      Once a client ID has been assigned to the
  410.      client, the client keeps this ID indefinitely.
  411.      If the client is terminated and restarted, it
  412.      will be reassigned the same ID.  It is desir-
  413.      able to be able to pass client IDs around from
  414.      machine to machine, from user to user, and
  415.      from session manager to session manager, while
  416.      retaining the identity of the client.    This,
  417.      combined with the indefinite persistence of
  418.      client IDs, means that client IDs need to be
  419.      globally unique.  The construction specified
  420.      above will ensure that any client ID created
  421.      by any user, session manager, and machine will
  422.      be different from any other.
  423.  
  424.  
  425. 7.  Protocol
  426.  
  427. The protocol consists of a sequence of messages as described
  428. below.    Each message type is specified by an ICE minor
  429. opcode.  A given message type is sent either from a client
  430. to the session manager or from the session manager to a
  431. client; the appropriate direction is listed with each mes-
  432. sage's description.  For each message type, the set of valid
  433. responses and possible error messages are listed.  The ICE
  434. severity is given in parentheses following each error class.
  435.  
  436. __
  437. |    RegisterClient [Client -> SM]
  438.  
  439.      previous-ID: ARRAY8
  440.  
  441.      Valid Responses: RegisterClientReply
  442.  
  443. |__      Possible Errors: BadValue (CanContinue)
  444.  
  445.  
  446. The client must send this message to the SM to register the
  447. client's existence.  If a client is being restarted from a
  448. previous session, the previous-ID field must contain the
  449. client ID from the previous session.  For new clients, pre-
  450. vious-ID should be of zero length.
  451.  
  452. If previous-ID is not valid, the SM will send a BadValue
  453. error message to the client.  At this point the SM reverts
  454. to the register state and waits for another RegisterClient.
  455. The client should then send a RegisterClient with a null
  456. previous-ID field.
  457.  
  458.  
  459.  
  460.                   5
  461.  
  462.  
  463.  
  464.  
  465.  
  466. X Session Management Protocol            X11, Release 6.4
  467.  
  468. __
  469. |    RegisterClientReply [Client <- SM]
  470.  
  471. |__      client-ID: ARRAY8
  472.  
  473.  
  474. The client-ID specifies a unique identification for this
  475. client.  If the client had specified an ID in the previous-
  476. ID field of the RegisterClient message, client-ID will be
  477. identical to the previously specified ID.  If previous-ID
  478. was null, client-ID will be a unique ID freshly generated by
  479. the SM.  The client-ID format is specified in section 6.
  480.  
  481. If the client didn't supply a previous-ID field to the
  482. RegisterClient message, the SM must send a SaveYourself mes-
  483. sage with type = Local, shutdown = False, interact-style =
  484. None, and fast = False immediately after the
  485. RegisterClientReply.  The client should respond to this like
  486. any other SaveYourself message.
  487.  
  488. __
  489. |    SaveYourself [Client <- SM]
  490.  
  491.      type: SAVE_TYPE
  492.      shutdown: BOOL
  493.      interact-style: INTERACT_STYLE
  494.      fast: BOOL
  495.  
  496.      Valid Responses: SetProperties, DeleteProperties,
  497.      GetProperties, SaveYourselfDone,
  498. |__      SaveYourselfPhase2Request, InteractRequest
  499.  
  500.  
  501. The SM sends this message to a client to ask it to save its
  502. state.    The client writes a state file, if necessary, and,
  503. if necessary, uses SetProperties to inform the SM of how to
  504. restart it and how to discard the saved state.    During this
  505. process it can, if allowed by interact-style, request per-
  506. mission to interact with the user by sending an InteractRe-
  507. quest message.    After the state has been saved, or if it
  508. cannot be successfully saved, and the properties are appro-
  509. priately set, the client sends a SaveYourselfDone message.
  510. If the client wants to save additional information after all
  511. the other clients have finished changing their own state,
  512. the client should send SaveYourselfPhase2Request instead of
  513. SaveYourselfDone.  The client must then freeze interaction
  514. with the user and wait until it receives a SaveComplete,
  515. Die, or a ShutdownCancelled message.
  516.  
  517. If interact-style is None, the client must not interact with
  518. the user while saving state.  If the interact-style is
  519. Errors, the client may interact with the user only if an
  520. error condition arises.  If interact-style is Any, then the
  521. client may interact with the user for any purpose.  This is
  522. done by sending an InteractRequest message.  The SM will
  523.  
  524.  
  525.  
  526.                   6
  527.  
  528.  
  529.  
  530.  
  531.  
  532. X Session Management Protocol            X11, Release 6.4
  533.  
  534.  
  535. send an Interact message to each client that sent an
  536. InteractRequest.  The client must postpone all interaction
  537. until it gets the Interact message.  When the client is done
  538. interacting it should send the SM an InteractDone message.
  539. The InteractRequest message can be sent any time after a
  540. SaveYourself and before a SaveYourselfDone.
  541.  
  542. Unusual circumstances may dictate multiple interactions.
  543. The client may initiate as many InteractRequest - Interact -
  544. InteractDone sequences as it needs before it sends
  545. SaveYourselfDone.
  546.  
  547. When a client receives SaveYourself and has not yet
  548. responded SaveYourselfDone to a previous SaveYourself, it
  549. must send a SaveYourselfDone and may then begin responding
  550. as appropriate to the newly received SaveYourself.
  551.  
  552. The type field specifies the type of information that should
  553. be saved: Global, Local, or Both.  The Local type indicates
  554. that the application must update the properties to reflect
  555. its current state, send a SaveYourselfDone and continue.
  556. Specifically it should save enough information to restore
  557. the state as seen by the user of this client.  It should not
  558. affect the state as seen by other users.  The Global type
  559. indicates that the user wants the client to commit all of
  560. its data to permanent, globally-accessible storage.  Both
  561. indicates that the client should do both of these.  If Both
  562. is specified, the client should first commit the data to
  563. permanent storage before updating its SM properties.
  564.  
  565.               Examples
  566.  
  567.      If a word processor was sent a SaveYourself with a
  568.      type of Local, it could create a temporary file
  569.      that included the current contents of the file,
  570.      the location of the cursor, and other aspects of
  571.      the current editing session.  It would then update
  572.      its RestartCommand property with enough informa-
  573.      tion to find the temporary file, and its Discard-
  574.      Command with enough information to remove it.
  575.  
  576.      If a word processor was sent a SaveYourself with a
  577.      type of Global, it would simply save the currently
  578.      edited file.
  579.  
  580.      If a word processor was sent a SaveYourself with a
  581.      type of Both, it would first save the currently
  582.      edited file.  It would then create a temporary
  583.      file with information such as the current position
  584.      of the cursor and what file is being edited.  It
  585.      would then update its RestartCommand property with
  586.      enough information to find the temporary file, and
  587.      its DiscardCommand with enough information to
  588.      remove it.
  589.  
  590.  
  591.  
  592.                   7
  593.  
  594.  
  595.  
  596.  
  597.  
  598. X Session Management Protocol            X11, Release 6.4
  599.  
  600.  
  601.      Once the SM has send SaveYourself to a client, it
  602.      can't send another SaveYourself to that client
  603.      until the client either responds with a SaveYour-
  604.      selfDone or the SM sends a ShutdownCancelled.
  605.  
  606.  
  607.            Advice to Implementors
  608.  
  609.      If the client stores local any state in a file or
  610.      similar "external" storage, it must create a dis-
  611.      tinct copy in response to each SaveYourself mes-
  612.      sage.  It must not simply refer to a previous
  613.      copy, because the SM may discard that previous
  614.      saved state using a DiscardCommand without knowing
  615.      that it is needed for the new checkpoint.
  616.  
  617.  
  618. The shutdown field specifies whether the system is being
  619. shut down.
  620.  
  621.              Rationale
  622.  
  623.      The interaction may be different depending on
  624.      whether or not shutdown is set.
  625.  
  626. The client must save and then must prevent interaction until
  627. it receives a SaveComplete, Die, or a ShutdownCancelled,
  628. because anything the user does after the save will be lost.
  629.  
  630. The fast field specifies whether or not the client should
  631. save its state as quickly as possible.    For example, if the
  632. SM knows that power is about to fail, it should set the fast
  633. field to True.
  634.  
  635. __
  636. |    SaveYourselfPhase2 [Client <- SM]
  637.  
  638.  
  639.      Valid Responses: SetProperties, DeleteProperties,
  640. |__      GetProperties, SaveYourselfDone, InteractRequest
  641.  
  642.  
  643. The SM sends this message to a client that has previously
  644. sent a SaveYourselfPhase2Request message.  This message
  645. informs the client that all other clients are in a fixed
  646. state and this client can save state that is associated with
  647. other clients.
  648.  
  649.              Rationale
  650.  
  651.      Clients that manager other clients (window man-
  652.      agers, workspace managers, etc) need to know when
  653.      all clients they are managing are idle, so that
  654.      the manager can save state related to each of the
  655.  
  656.  
  657.  
  658.                   8
  659.  
  660.  
  661.  
  662.  
  663.  
  664. X Session Management Protocol            X11, Release 6.4
  665.  
  666.  
  667.      clients without being concerned with that state
  668.      changing.
  669.  
  670. The client writes a state file, if necessary, and, if neces-
  671. sary, uses SetProperties to inform the SM of how to restart
  672. it and how to discard the saved state.    During this process
  673. it can request permission to interact with the user by send-
  674. ing an InteractRequest message.  This should only be done if
  675. an error occurs that requires user interaction to resolve.
  676. After the state has been saved, or if it cannot be success-
  677. fully saved, and the properties are appropriately set, the
  678. client sends a SaveYourselfDone message.
  679.  
  680.  
  681. __
  682. |    SaveYourselfRequest [Client -> SM]
  683.  
  684.      type: SAVE_TYPE
  685.      shutdown: BOOL
  686.      interact-style: INTERACT_STYLE
  687.      fast: BOOL
  688.      global: BOOL
  689.  
  690. |__      Valid Responses: SaveYourself
  691.  
  692.  
  693. An application sends this to the SM to request a checkpoint.
  694. When the SM receives this request it may generate a SaveY-
  695. ourself message in response and it may leave the fields
  696. intact.
  697.  
  698.               Example
  699.  
  700.      A vendor of a UPS (Uninterruptible Power Supply)
  701.      might include an SM client that would monitor the
  702.      status of the UPS and generate a fast shutdown if
  703.      the power is about to be lost.
  704.  
  705.  
  706. If global is set to True, then the resulting SaveYourself
  707. should be sent to all applications.  If global is set to
  708. False, then the resulting SaveYourself should be sent to the
  709. application that sent the SaveYourselfRequest.
  710.  
  711. __
  712. |    InteractRequest [Client -> SM]
  713.  
  714.      dialog-type: DIALOG_TYPE
  715.  
  716.      Valid Responses: Interact, ShutdownCancelled
  717.  
  718. |__      Possible Errors: BadState (CanContinue)
  719.  
  720.  
  721.  
  722.  
  723.  
  724.                   9
  725.  
  726.  
  727.  
  728.  
  729.  
  730. X Session Management Protocol            X11, Release 6.4
  731.  
  732.  
  733. During a checkpoint or session-save operation, only one
  734. client at a time might be granted the privilege of interact-
  735. ing with the user.  The InteractRequest message causes the
  736. SM to emit an Interact message at some later time if the
  737. shutdown is not cancelled by another client first.
  738.  
  739. The dialog-type field specifies either Errors, indicating
  740. that the client wants to start an error dialog or Normal,
  741. meaning the client wishes to start a non-error dialog.
  742.  
  743. __
  744. |    Interact [Client <- SM]
  745.  
  746.      Valid Responses: InteractDone
  747. |__
  748.  
  749.  
  750. This message grants the client the privilege of interacting
  751. with the user.    When the client is done interacting with the
  752. user it must send an InteractDone message to the SM unless a
  753. shutdown cancel is received.
  754.  
  755.            Advice to Implementors
  756.  
  757.      If a client receives a ShutdownCancelled after
  758.      receiving an Interact message, but before sending
  759.      a InteractDone, the client should abort the inter-
  760.      action and send a SaveYourselfDone.
  761.  
  762.  
  763. __
  764. |    InteractDone [Client -> SM]
  765.  
  766.      cancel-shutdown: BOOL
  767.  
  768.      Valid Responses: ShutdownCancelled
  769. |__
  770.  
  771.  
  772. This message is used by a client to notify the SM that it is
  773. done interacting.
  774.  
  775. Setting the cancel-shutdown field to True indicates that the
  776. user has requested that the entire shutdown be cancelled.
  777. Cancel-shutdown may only be True if the corresponding SaveY-
  778. ourself message specified True for the shutdown field and
  779. Any or Errors for the interact-style field.  Otherwise, can-
  780. cel-shutdown must be False.
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.                  10
  791.  
  792.  
  793.  
  794.  
  795.  
  796. X Session Management Protocol            X11, Release 6.4
  797.  
  798. __
  799. |    SaveYourselfDone [Client -> SM]
  800.  
  801.      success: BOOL
  802.  
  803.      Valid Responses: SaveComplete, Die, ShutdownCancelled
  804. |__
  805.  
  806.  
  807. This message is sent by a client to indicate that all of the
  808. properties representing its state have been updated.  After
  809. sending SaveYourselfDone the client must wait for a
  810. SaveComplete, ShutdownCancelled, or Die message before
  811. changing its state.  If the SaveYourself operation was suc-
  812. cessful, then the client should set the success field to
  813. True; otherwise the client should set it to False.
  814.  
  815.               Example
  816.  
  817.      If a client tries to save its state and runs out
  818.      of disk space, it should return False in the suc-
  819.      cess field of the SaveYourselfDone message.
  820.  
  821.  
  822. __
  823. |    SaveYourselfPhase2Request [Client -> SM]
  824.  
  825.      Valid Responses: ShutdownCancelled, SaveYourselfPhase2
  826. |__
  827.  
  828.  
  829. This message is sent by a client to indicate that it needs
  830. to be informed when all the other clients are quiescent, so
  831. it can continue its state.
  832.  
  833. __
  834. |    Die [Client <- SM]
  835.  
  836. |__      Valid Responses: ConnectionClosed
  837.  
  838.  
  839. When the SM wants a client to die it sends a Die message.
  840. Before the client dies it responds by sending a Connection-
  841. Closed message and may then close its connection to the SM
  842. at any time.
  843.  
  844. __
  845. |    SaveComplete [Client <- SM]
  846.  
  847. |__      Valid Responses:
  848.  
  849.  
  850. When the SM is done with a checkpoint, it will send each of
  851. the clients a SaveComplete message.  The client is then free
  852. to change its state.
  853.  
  854.  
  855.  
  856.                  11
  857.  
  858.  
  859.  
  860.  
  861.  
  862. X Session Management Protocol            X11, Release 6.4
  863.  
  864. __
  865. |__  ShutdownCancelled [Client <- SM]
  866.  
  867.  
  868. The shutdown currently in process has been aborted.  The
  869. client can now continue as if the shutdown had never hap-
  870. pened.    If the client has not sent SaveYourselfDone yet, the
  871. client can either abort the save and send SaveYourselfDone
  872. with the success field set to False, or it can continue with
  873. the save and send a SaveYourselfDone with the success field
  874. set to reflect the outcome of the save.
  875.  
  876. __
  877. |    ConnectionClosed [Client -> SM]
  878.  
  879. |__      reason: LISTofARRAY8
  880.  
  881.  
  882. Specifies that the client has decided to terminate.  It
  883. should be immediately followed by closing the connection.
  884.  
  885. The reason field specifies why the client is resigning from
  886. the session.  It is encoded as an array of Compound Text
  887. strings.  If the resignation is expected by the user, there
  888. will typically be zero ARRAY8s here.  But if the client
  889. encountered an unexpected fatal error, the error message
  890. (which might otherwise be printed on stderr on a POSIX sys-
  891. tem) should be forwarded to the SM here, one ARRAY8 per line
  892. of the message.  It is the responsibility of the SM to dis-
  893. play this reason to the user.
  894.  
  895. After sending this message, the client must not send any
  896. additional XSMP messages to the SM.
  897.  
  898.            Advice to Implementors
  899.  
  900.      If additional messages are received, they should
  901.      be discarded.
  902.  
  903.  
  904.              Rationale
  905.  
  906.      The reason for sending the ConnectionClosed mes-
  907.      sage before actually closing the connections is
  908.      that some transport protocols will not provide
  909.      immediate notification of connection closure.
  910.  
  911.  
  912. __
  913. |    SetProperties [Client -> SM]
  914.  
  915. |__      properties: LISTofPROPERTY
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.                  12
  923.  
  924.  
  925.  
  926.  
  927.  
  928. X Session Management Protocol            X11, Release 6.4
  929.  
  930.  
  931. Sets the specified properties to the specified values.
  932. Existing properties not specified in the SetProperties mes-
  933. sage are unaffected.  Some properties have predefined seman-
  934. tics.  See section 11, "Predefined Properties."
  935.  
  936. The protocol specification recommends that property names
  937. used for properties not defined by the standard should begin
  938. with an underscore.  To prevent conflicts among organiza-
  939. tions, additional prefixes should be chosen (for example,
  940. _KPC_FAST_SAVE_OPTION).  The organizational prefixes should
  941. be registered with the X Registry.  The XSMP reserves all
  942. property names not beginning with an underscore for future
  943. use.
  944.  
  945. __
  946. |    DeleteProperties [Client -> SM]
  947.  
  948. |__      property-names: LISTofARRAY8
  949.  
  950.  
  951. Removes the named properties.
  952.  
  953. __
  954. |    GetProperties [Client -> SM]
  955.  
  956. |__      Valid Responses: GetPropertiesReply
  957.  
  958.  
  959. Requests that the SM respond with the values of all the
  960. properties for this client.
  961.  
  962. __
  963. |    GetPropertiesReply [Client <- SM]
  964.  
  965. |__      values: LISTofPROPERTY
  966.  
  967.  
  968. This message is sent in reply to a GetProperties message and
  969. includes the values of all the properties.
  970.  
  971. 8.  Errors
  972.  
  973. When the receiver of a message detects an error condition,
  974. the receiver sends an ICE error message to the sender.
  975. There are only two types of errors that are used by the
  976. XSMP: BadValue and BadState.  These are both defined in the
  977. ICE protocol.
  978.  
  979. Any message received out-of-sequence will generate a Bad-
  980. State error message.
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.                  13
  989.  
  990.  
  991.  
  992.  
  993.  
  994. X Session Management Protocol            X11, Release 6.4
  995.  
  996.  
  997. 9.  State Diagrams
  998.  
  999. These state diagrams are designed to cover all actions of
  1000. both the client and the SM.
  1001.  
  1002. 9.1.  Client State Diagram
  1003.  
  1004.  
  1005. start:
  1006.      ICE protocol setup complete -> register
  1007.  
  1008.  
  1009.  
  1010. register:
  1011.      send RegisterClient -> collect-id
  1012.  
  1013.  
  1014.  
  1015. collect-id:
  1016.      receive RegisterClientReply -> idle
  1017.  
  1018.  
  1019.  
  1020. shutdown-cancelled:
  1021.      send SaveYourselfDone -> idle
  1022.  
  1023.  
  1024.  
  1025. idle: [Undoes any freeze of interaction with user.]
  1026.      receive Die -> die
  1027.      receive SaveYourself -> freeze-interaction
  1028.      send GetProperties -> idle
  1029.      receive GetPropertiesReply -> idle
  1030.      send SetProperties -> idle
  1031.      send DeleteProperties -> idle
  1032.      send ConnectionClosed -> connection-closed
  1033.      send SaveYourselfRequest -> idle
  1034.  
  1035.  
  1036.  
  1037. die:
  1038.      send ConnectionClosed -> connection-closed
  1039.  
  1040.  
  1041.  
  1042. freeze-interaction:
  1043.      freeze interaction with user -> save-yourself
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.                  14
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060. X Session Management Protocol            X11, Release 6.4
  1061.  
  1062.  
  1063. save-yourself:
  1064.      receive ShutdownCancelled -> shutdown-cancelled
  1065.      send SetProperties -> save-yourself
  1066.      send DeleteProperties -> save-yourself
  1067.      send GetProperties -> save-yourself
  1068.      receive GetPropertiesReply -> save-yourself
  1069.      send InteractRequest -> interact-request
  1070.      send SaveYourselfPhase2Request -> waiting-for-phase2
  1071.      if shutdown mode:
  1072.       send SaveYourselfDone -> save-yourself-done
  1073.      otherwise:
  1074.       send SaveYourselfDone -> idle
  1075.  
  1076.  
  1077.  
  1078. waiting-for-phase2:
  1079.      receive ShutdownCancelled -> shutdown-cancelled
  1080.      receive SaveYourselfPhase2 -> phase2
  1081.  
  1082.  
  1083.  
  1084. phase2:
  1085.      receive ShutdownCancelled -> shutdown-cancelled
  1086.      send SetProperties -> save-yourself
  1087.      send DeleteProperties -> save-yourself
  1088.      send GetProperties -> save-yourself
  1089.      receive GetPropertiesReply -> save-yourself
  1090.      send InteractRequest -> interact-request (errors only)
  1091.      if shutdown mode:
  1092.       send SaveYourselfDone -> save-yourself-done
  1093.      otherwise:
  1094.       send SaveYourselfDone -> idle
  1095.  
  1096.  
  1097.  
  1098. interact-request:
  1099.      receive Interact -> interact
  1100.      receive ShutdownCancelled -> shutdown-cancelled
  1101.  
  1102.  
  1103.  
  1104. interact:
  1105.      send InteractDone -> save-yourself
  1106.      receive ShutdownCancelled -> shutdown-cancelled
  1107.  
  1108.  
  1109.  
  1110. save-yourself-done: (changing state is forbidden)
  1111.      receive SaveComplete -> idle
  1112.      receive Die -> die
  1113.      receive ShutdownCancelled -> idle
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.                  15
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126. X Session Management Protocol            X11, Release 6.4
  1127.  
  1128.  
  1129. connection-closed:
  1130.      client stops participating in session
  1131.  
  1132.  
  1133. 9.2.  Session Manager State Diagram
  1134.  
  1135.  
  1136. start:
  1137.      receive ProtocolSetup -> protocol-setup
  1138.  
  1139.  
  1140.  
  1141. protocol-setup:
  1142.      send ProtocolSetupReply -> register
  1143.  
  1144.  
  1145.  
  1146. register:
  1147.      receive RegisterClient -> acknowledge-register
  1148.  
  1149.  
  1150.  
  1151. acknowledge-register:
  1152.      send RegisterClientReply -> idle
  1153.  
  1154.  
  1155.  
  1156. idle:
  1157.      receive SetProperties -> idle
  1158.      receive DeleteProperties -> idle
  1159.      receive ConnectionClosed -> start
  1160.      receive GetProperties -> get-properties
  1161.      receive SaveYourselfRequest -> save-yourself
  1162.      send SaveYourself -> saving-yourself
  1163.  
  1164.  
  1165.  
  1166. save-yourself:
  1167.      send SaveYourself -> saving-yourself
  1168.  
  1169.  
  1170.  
  1171. get-properties:
  1172.      send GetPropertiesReply -> idle
  1173.  
  1174.  
  1175.  
  1176. saving-get-properties:
  1177.      send GetPropertiesReply -> saving-yourself
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.                  16
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192. X Session Management Protocol            X11, Release 6.4
  1193.  
  1194.  
  1195. saving-yourself:
  1196.      receive InteractRequest -> saving-yourself
  1197.      send Interact -> saving-yourself
  1198.      send ShutdownCancelled -> idle
  1199.      receive InteractDone -> saving-yourself
  1200.      receive SetProperties -> saving-yourself
  1201.      receive DeleteProperties -> saving-yourself
  1202.      receive GetProperties -> saving-get-properties
  1203.      receive SaveYourselfPhase2Request -> start-phase2
  1204.      receive SaveYourselfDone -> save-yourself-done
  1205.  
  1206.  
  1207.  
  1208. start-phase2:
  1209.      If all clients have sent either SaveYourselfPhase2Request or SaveYourselfDone:
  1210.       send SaveYourselfPhase2 -> phase2
  1211.      else
  1212.       -> saving-yourself
  1213.  
  1214.  
  1215.  
  1216. phase2:
  1217.      receive InteractRequest -> saving-yourself
  1218.      send Interact -> saving-yourself
  1219.      send ShutdownCancelled -> idle
  1220.      receive InteractDone -> saving-yourself
  1221.      receive SetProperties -> saving-yourself
  1222.      receive DeleteProperties -> saving-yourself
  1223.      receive GetProperties -> saving-get-properties
  1224.      receive SaveYourselfDone -> save-yourself-done
  1225.  
  1226.  
  1227.  
  1228. save-yourself-done:
  1229.      If all clients are saved:
  1230.       If shutting down:
  1231.            send Die -> die
  1232.       otherwise
  1233.            send SaveComplete -> idle
  1234.  
  1235.      If some clients are not saved:
  1236.      -> saving-yourself
  1237.  
  1238.  
  1239.  
  1240. die:
  1241.      SM stops accepting connections
  1242.  
  1243.  
  1244. 10.  Protocol Encoding
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.                  17
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258. X Session Management Protocol            X11, Release 6.4
  1259.  
  1260.  
  1261. 10.1.  Types
  1262.  
  1263. BOOL
  1264.   0  False
  1265.   1  True
  1266.  
  1267. INTERACT_STYLE
  1268.   0  None
  1269.   1  Errors
  1270.   2  Any
  1271.  
  1272. DIALOG_TYPE
  1273.   0  Error
  1274.   1  Normal
  1275.  
  1276. SAVE_TYPE
  1277.   0  Global
  1278.   1  Local
  1279.   2  Both
  1280.  
  1281. ARRAY8
  1282.   4  CARD32        length
  1283.   n  LISTofCARD8    the array
  1284.   p            p = pad (4 + n, 8)
  1285.  
  1286. LISTofARRAY8
  1287.   4  CARD32        count
  1288.   4            unused
  1289.   a  ARRAY8        first array
  1290.   b  ARRAY8        second array
  1291.   .
  1292.   .
  1293.   .
  1294.   q  ARRAY8        last array
  1295.  
  1296. PROPERTY
  1297.   a  ARRAY8        name
  1298.   b  ARRAY8        type (XPCS encoded in Latin-1, case sensitive)
  1299.   c  LISTofARRAY8   values
  1300.  
  1301. LISTofPROPERTY
  1302.   4      CARD32    count
  1303.   4            unused
  1304.   a      PROPERTY  first property
  1305.   b      PROPERTY  second property
  1306.   .
  1307.   .
  1308.   .
  1309.   q  PROPERTY        last property
  1310.  
  1311. 10.2.  Messages
  1312.  
  1313. XSMP is a sub-protocol of ICE.    The major opcode is assigned
  1314. at run-time by ICE and is represented here by `?'.
  1315.  
  1316.  
  1317.  
  1318.                  18
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324. X Session Management Protocol            X11, Release 6.4
  1325.  
  1326.  
  1327. To start the XSMP protocol, the client sends the server an
  1328. ICE ProtocolSetup message.  The protocol-name field should
  1329. be specified as "XSMP", the major version of the protocol is
  1330. 1, the minor version is 0.  These values may change if the
  1331. protocol is revised.  The minor version number will be
  1332. incremented if the change is compatible, otherwise the major
  1333. version number will be incremented.
  1334.  
  1335. In ProtocolReply message sent by the session manager, the
  1336. XSMP protocol defines the vendor parameter as product iden-
  1337. tification of the session manager, and defines the release
  1338. parameter as the software release identification of the ses-
  1339. sion manager.  The session manager should supply this infor-
  1340. mation in the ICE ProtocolReply message.
  1341.  
  1342. RegisterClient
  1343.   1  ?            XSMP
  1344.   1  1            opcode
  1345.   2            unused
  1346.   4  a/8        length of remaining data in 8-byte units
  1347.   a  ARRAY8        previous-ID
  1348.  
  1349. RegisterClientReply
  1350.   1  ?            XSMP
  1351.   1  2            opcode
  1352.   2            unused
  1353.   4  a/8        length of remaining data in 8-byte units
  1354.   a  ARRAY8        client-ID
  1355.  
  1356. SaveYourself
  1357.   1  ?            XSMP
  1358.   1  3            opcode
  1359.   2            unused
  1360.   4  1            length of remaining data in 8-byte units
  1361.   1  SAVE_TYPE        type
  1362.   1  BOOL        shutdown
  1363.   1  INTERACT_STYLE interact-style
  1364.   1  BOOL        fast
  1365.   4            unused
  1366.  
  1367. SaveYourselfRequest
  1368.   1  ?            XSMP
  1369.   1  4            opcode
  1370.   2            unused
  1371.   4  1            length of remaining data in 8-byte units
  1372.   1  SAVE_TYPE        type
  1373.   1  BOOL        shutdown
  1374.   1  INTERACT_STYLE interact-style
  1375.   1  BOOL        fast
  1376.   1  BOOL        global
  1377.   3            unused
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.                  19
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390. X Session Management Protocol            X11, Release 6.4
  1391.  
  1392.  
  1393. InteractRequest
  1394.   1  ?            XSMP
  1395.   1  5            opcode
  1396.   1  DIALOG_TYPE    dialog type
  1397.   1            unused
  1398.   4  0            length of remaining data in 8-byte units
  1399.  
  1400. Interact
  1401.   1  ?            XSMP
  1402.   1  6            opcode
  1403.   2            unused
  1404.   4  0            length of remaining data in 8-byte units
  1405.  
  1406. InteractDone
  1407.   1  ?            XSMP
  1408.   1  7            opcode
  1409.   1  BOOL        cancel-shutdown
  1410.   1            unused
  1411.   4  0            length of remaining data in 8-byte units
  1412.  
  1413. SaveYourselfDone
  1414.   1  ?            XSMP
  1415.   1  8            opcode
  1416.   1  BOOL        success
  1417.   1            unused
  1418.   4  0            length of remaining data in 8-byte units
  1419.  
  1420. Die
  1421.   1  ?            XSMP
  1422.   1  9            opcode
  1423.   2            unused
  1424.   4  0            length of remaining data in 8-byte units
  1425.  
  1426. ShutdownCancelled
  1427.   1  ?            XSMP
  1428.   1  10         opcode
  1429.   2            unused
  1430.   4  0            length of remaining data in 8-byte units
  1431.  
  1432. ConnectionClosed
  1433.   1  ?            XSMP
  1434.   1  11         opcode
  1435.   2            unused
  1436.   4  a/8        length of remaining data in 8-byte units
  1437.   a  LISTofARRAY8   reason
  1438.  
  1439. SetProperties
  1440.   1  ?            XSMP
  1441.   1  12         opcode
  1442.   2            unused
  1443.   4  a/8        length of remaining data in 8-byte units
  1444.   a  LISTofPROPERTY properties
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.                  20
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456. X Session Management Protocol            X11, Release 6.4
  1457.  
  1458.  
  1459. DeleteProperties
  1460.   1  ?            XSMP
  1461.   1  13         opcode
  1462.   2            unused
  1463.   4  a/8        length of remaining data in 8-byte units
  1464.   a  LISTofARRAY8   properties
  1465.  
  1466. GetProperties
  1467.   1  ?            XSMP
  1468.   1  14         opcode
  1469.   2            unused
  1470.   4  0            length of remaining data in 8-byte units
  1471.  
  1472. GetPropertiesReply
  1473.   1  ?            XSMP
  1474.   1  15         opcode
  1475.   2            unused
  1476.   4  a/8        length of remaining data in 8-byte units
  1477.   a  LISTofPROPERTY properties
  1478.  
  1479. SaveYourselfPhase2Request
  1480.   1  ?            XSMP
  1481.   1  16         opcode
  1482.   2            unused
  1483.   4  0            length of remaining data in 8-byte units
  1484.  
  1485. SaveYourselfPhase2
  1486.   1  ?            XSMP
  1487.   1  17         opcode
  1488.   2            unused
  1489.   4  0            length of remaining data in 8-byte units
  1490.  
  1491.  
  1492. SaveComplete
  1493.   1  ?            XSMP
  1494.   1  18         opcode
  1495.   2            unused
  1496.   4  0            length of remaining data in 8-byte units
  1497.  
  1498.  
  1499. 11.  Predefined Properties
  1500.  
  1501. All property values are stored in a LISTofARRAY8.  If the
  1502. type of the property is CARD8, the value is stored as a
  1503. LISTofARRAY8 with one ARRAY8 that is one byte long.  That
  1504. single byte contains the CARD8.  If the type of the property
  1505. is ARRAY8, the value is stored in the first element of a
  1506. single element LISTofARRAY8.
  1507.  
  1508. The required properties must be set each time a client con-
  1509. nects with the SM.  The properties must be set after the
  1510. client sends RegisterClient and before the client sends
  1511. SaveYourselfDone.  Otherwise, the behavior of the session
  1512. manager is not defined.
  1513.  
  1514.  
  1515.  
  1516.                  21
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522. X Session Management Protocol            X11, Release 6.4
  1523.  
  1524.  
  1525. Clients may set, get, and delete nonstandard properties.
  1526. The lifetime of stored properties does not extend into sub-
  1527. sequent sessions.
  1528.  
  1529. ----------------------------------------------------------
  1530. Name           Type      Posix Type    Required?
  1531. ----------------------------------------------------------
  1532. CloneCommand       OS-specific     LISTofARRAY8       Yes
  1533. CurrentDirectory   OS-specific     ARRAY8        No
  1534. DiscardCommand       OS-specific     LISTofARRAY8       No*
  1535. Environment       OS-specific     LISTofARRAY8       No
  1536. ProcessID       OS-specific     ARRAY8        No
  1537. Program        OS-specific     ARRAY8        Yes
  1538. RestartCommand       OS-specific     LISTofARRAY8       Yes
  1539. ResignCommand       OS-specific     LISTofARRAY8       No
  1540. RestartStyleHint   CARD8     CARD8           No
  1541. ShutdownCommand    OS-specific     LISTofARRAY8       No
  1542. UserID           ARRAY8     ARRAY8        Yes
  1543. ----------------------------------------------------------
  1544.  
  1545.  
  1546. * Required if any state is stored in an external repository
  1547. (e.g., state file).
  1548.  
  1549. CloneCommand
  1550.    This is like the RestartCommand except it restarts a copy
  1551.    of the application.    The only difference is that the
  1552.    application doesn't supply its client id at register
  1553.    time.  On POSIX systems the type should be a LISTofAR-
  1554.    RAY8.
  1555.  
  1556. CurrentDirectory
  1557.    On POSIX-based systems specifies the value of the current
  1558.    directory that needs to be set up prior to starting the
  1559.    program and should be of type ARRAY8.
  1560.  
  1561. DiscardCommand
  1562.    The discard command contains a command that when deliv-
  1563.    ered to the host that the client is running on (deter-
  1564.    mined from the connection), will cause it to discard any
  1565.    information about the current state.  If this command is
  1566.    not specified, the SM will assume that all of the
  1567.    client's state is encoded in the RestartCommand.  On
  1568.    POSIX systems the type should be LISTofARRAY8.
  1569.  
  1570. Environment
  1571.    On POSIX based systems, this will be of type LISTofARRAY8
  1572.    where the ARRAY8s alternate between environment variable
  1573.    name and environment variable value.
  1574.  
  1575. ProcessID
  1576.    This specifies an OS-specific identifier for the process.
  1577.    On POSIX systems this should of type ARRAY8 and contain
  1578.    the return value of getpid() turned into a Latin-1
  1579.  
  1580.  
  1581.  
  1582.                  22
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588. X Session Management Protocol            X11, Release 6.4
  1589.  
  1590.  
  1591.    (decimal) string.
  1592.  
  1593. Program
  1594.    The name of the program that is running.  On POSIX sys-
  1595.    tems this should be the first parameter passed to execve
  1596.    and should be of type ARRAY8.
  1597.  
  1598. RestartCommand
  1599.    The restart command contains a command that when deliv-
  1600.    ered to the host that the client is running on (deter-
  1601.    mined from the connection), will cause the client to
  1602.    restart in its current state.  On POSIX-based systems
  1603.    this is of type LISTofARRAY8 and each of the elements in
  1604.    the array represents an element in the argv array.  This
  1605.    restart command should ensure that the client restarts
  1606.    with the specified client-ID.
  1607.  
  1608. ResignCommand
  1609.    A client that sets the RestartStyleHint to RestartAnyway
  1610.    uses this property to specify a command that undoes the
  1611.    effect of the client and removes any saved state.
  1612.  
  1613.                 Example
  1614.  
  1615.     A user runs xmodmap.  xmodmap registers with
  1616.     the SM, sets RestartStyleHint to RestartAnyway,
  1617.     and then terminates.  In order to allow the SM
  1618.     (at the user's request) to undo this, xmodmap
  1619.     would register a ResignCommand that undoes the
  1620.     effects of the xmodmap.
  1621.  
  1622.  
  1623. RestartStyleHint
  1624.  
  1625.    If the RestartStyleHint property is present, it will con-
  1626.    tain the style of restarting the client prefers.  If this
  1627.    flag isn't specified, RestartIfRunning is assumed.  The
  1628.    possible values are as follows:
  1629.  
  1630.    ---------------------------
  1631.    Name         Value
  1632.    ---------------------------
  1633.    RestartIfRunning      0
  1634.    RestartAnyway      1
  1635.    RestartImmediately      2
  1636.    RestartNever       3
  1637.    ---------------------------
  1638.  
  1639.  
  1640.    The RestartIfRunning style is used in the usual case.
  1641.    The client should be restarted in the next session if it
  1642.    is connected to the session manager at the end of the
  1643.    current session.
  1644.  
  1645.  
  1646.  
  1647.  
  1648.                  23
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654. X Session Management Protocol            X11, Release 6.4
  1655.  
  1656.  
  1657.    The RestartAnyway style is used to tell the SM that the
  1658.    application should be restarted in the next session even
  1659.    if it exits before the current session is terminated.  It
  1660.    should be noted that this is only a hint and the SM will
  1661.    follow the policies specified by its users in determining
  1662.    what applications to restart.
  1663.  
  1664.  
  1665.                Rationale
  1666.  
  1667.     This can be specified by a client which sup-
  1668.     ports (as MS-Windows clients do) a means for
  1669.     the user to indicate while exiting that
  1670.     restarting is desired.    It can also be used for
  1671.     clients that spawn other clients and then go
  1672.     away, but which want to be restarted.
  1673.  
  1674.  
  1675.    A client that uses RestartAnyway should also set the
  1676.    ResignCommand and ShutdownCommand properties to commands
  1677.    that undo the state of the client after it exits.
  1678.  
  1679.    The RestartImmediately style is like RestartAnyway, but
  1680.    in addition, the client is meant to run continuously.  If
  1681.    the client exits, the SM should try to restart it in the
  1682.    current session.
  1683.  
  1684.             Advice to Implementors
  1685.  
  1686.     It would be wise to sanity-check the frequency
  1687.     which which RestartImmediately clients are
  1688.     restarted, to avoid a sick client being
  1689.     restarted continuously.
  1690.  
  1691.    The RestartNever style specifies that the client does not
  1692.    wish to be restarted in the next session.
  1693.  
  1694.             Advice To Implementors
  1695.  
  1696.     This should be used rarely, if at all.    It will
  1697.     cause the client to be silently left out of
  1698.     sessions when they are restarted and will prob-
  1699.     ably be confusing to users.
  1700.  
  1701.  
  1702. ShutdownCommand
  1703.    This command is executed at shutdown time to clean up
  1704.    after a client that is no longer running but retained its
  1705.    state by setting RestartStyleHint to RestartAnyway.    The
  1706.    command must not remove any saved state as the client is
  1707.    still part of the session.
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.                  24
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720. X Session Management Protocol            X11, Release 6.4
  1721.  
  1722.  
  1723.                 Example
  1724.  
  1725.     A client is run at start up time that turns on
  1726.     a camera.  This client then exits.  At session
  1727.     shutdown, the user wants the camera turned off.
  1728.     This client would set the RestartStyleHint to
  1729.     RestartAnyway and would register a Shutdown-
  1730.     Command that would turn off the camera.
  1731.  
  1732.  
  1733. UserID
  1734.    Specifies the user's ID.  On POSIX-based systems this
  1735.    will contain the the user's name (the pw_name field of
  1736.    struct passwd).
  1737.  
  1738.  
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.                  25
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786. X Session Management Protocol            X11, Release 6.4
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799.  
  1800.  
  1801.  
  1802.  
  1803.  
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.                  26
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852. X Session Management Protocol            X11, Release 6.4
  1853.  
  1854.  
  1855.                Table of Contents
  1856.  
  1857.  
  1858.    1. Acknowledgements . . . . . . . . . . . . . . . . .   1
  1859.    2. Definitions and Goals  . . . . . . . . . . . . . .   1
  1860.    3. Overview of the Protocol . . . . . . . . . . . . .   1
  1861.    4. Data Types . . . . . . . . . . . . . . . . . . . .   3
  1862.    5. Protocol Setup and Message Format  . . . . . . . .   4
  1863.    6. Client Identification String . . . . . . . . . . .   4
  1864.    7. Protocol . . . . . . . . . . . . . . . . . . . . .   5
  1865.    8. Errors . . . . . . . . . . . . . . . . . . . . . .  13
  1866.    9. State Diagrams . . . . . . . . . . . . . . . . . .  14
  1867.    9.1. Client State Diagram . . . . . . . . . . . . . .  14
  1868.    9.2. Session Manager State Diagram  . . . . . . . . .  16
  1869.    10. Protocol Encoding . . . . . . . . . . . . . . . .  17
  1870.    10.1. Types . . . . . . . . . . . . . . . . . . . . .  18
  1871.    10.2. Messages  . . . . . . . . . . . . . . . . . . .  18
  1872.    11. Predefined Properties . . . . . . . . . . . . . .  21
  1873.  
  1874.  
  1875.  
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.                  iii
  1913.  
  1914.  
  1915.