doc/SMlib.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4
   5
   6 <!-- lifted from troff+ms+XMan by doclifter -->
   7 <book id="smlibms">
   8
   9 <bookinfo>
  10    <title>X Session Management Library</title>
  11    <subtitle>X Consortium Standard</subtitle>
  12    <releaseinfo>X Version 11, Release 6.4</releaseinfo>
  13    <authorgroup>
  14       <author>
  15          <firstname>Ralph</firstname><surname>Mor</surname>
  16       </author>
  17    </authorgroup>
  18    <corpname>X Consortium Standard</corpname>
  19    <copyright>
  20      <year>1993</year><year>1994</year>
  21      <holder>X Consortium</holder>
  22    </copyright>
  23    <releaseinfo>Version 1.0</releaseinfo>
  24    <affiliation><orgname>X Consortium</orgname></affiliation>
  25    <productnumber>X Version 11, Release 7</productnumber>
  26
  27    <legalnotice>
  28      <para>
  29 Permission is hereby granted, free of charge, to any person obtaining
  30 a copy of this software and associated documentation files (the
  31 &ldquo;Software&rdquo;), to deal in the Software without restriction,
  32 including without limitation the rights to use, copy, modify, merge,
  33 publish, distribute, sublicense, and/or sell copies of the Software,
  34 and to permit persons to whom the Software is furnished to do so,
  35 subject to the following conditions:
  36      </para>
  37
  38      <para>
  39 The above copyright notice and this permission notice shall be
  40 included in all copies or substantial portions of the Software.
  41      </para>
  42
  43      <para>
  44 THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF
  45 ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  46 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
  47 AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR
  48 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  49 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  50 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  51      </para>
  52
  53      <para>
  54 Except as contained in this notice, the name of the X Consortium shall
  55 not be used in advertising or otherwise to promote the sale, use or
  56 other dealings in this Software without prior written authorization
  57 from the X Consortium.
  58      </para>
  59
  60      <para>
  61 X Window System is a trademark of The Open Group.
  62      </para>
  63    </legalnotice>
  64
  65 </bookinfo>
  66
  67 <chapter id="overview_of_session_management">
  68   <title>Overview of Session Management</title>
  69
  70   <abstract>
  71     <para>
  72 The purpose of the X Session Management Protocol (<acronym>XSMP</acronym>)
  73 is to provide a uniform mechanism for users to save and restore their
  74 sessions.  A <firstterm>session</firstterm> is a group of clients,
  75 each of which has a particular state.  The session is controlled by a
  76 network service called the <firstterm>session manager</firstterm>.
  77 The session manager issues commands to its clients on behalf of the
  78 user.  These commands may cause clients to save their state or to
  79 terminate.  It is expected that the client will save its state in such
  80 a way that the client can be restarted at a later time and resume its
  81 operation as if it had never been terminated.  A client's state might
  82 include information about the file currently being edited, the current
  83 position of the insertion point within the file, or the start of an
  84 uncommitted transaction.  The means by which clients are restarted is
  85 unspecified by this protocol.
  86     </para>
  87
  88     <para>
  89 For purposes of this protocol, a <firstterm>client</firstterm> of the
  90 session manager is defined as a connection to the session manager.  A
  91 client is typically, though not necessarily, a process running an
  92 application program connected to an X display.  However, a client may
  93 be connected to more than one X display or not be connected to any X
  94 displays at all.
  95     </para>
  96   </abstract>
  97 </chapter>
  98
  99 <chapter id='the_session_management_library'>
 100   <title>The Session Management Library</title>
 101   <abstract>
 102     <para>
 103 The Session Management Library (<abbrev>SMlib</abbrev>) is a low-level
 104 "C" language interface to XSMP.  It is expected that higher level
 105 toolkits, such as Xt, will hide many of the details of session
 106 management from clients.  Higher level toolkits might also be developed
 107 for session managers to use, but no such effort is currently under way.
 108     </para>
 109   </abstract>
 110
 111   <para>
 112     SMlib has two parts to it:
 113     <itemizedlist mark='bullet'>
 114       <listitem><para>One set of functions for clients that want to be part of a session</para></listitem>
 115       <listitem><para>One set of functions for session managers to call</para></listitem>
 116     </itemizedlist>
 117   </para>
 118
 119   <para>
 120 Some applications will use both sets of functions and act as
 121 <firstterm>nested session managers</firstterm>.  That is, they will be
 122 both a session manager and a client of another session.  An example is
 123 a mail program that could start a text editor for editing the text of
 124 a mail message.  The mail program is part of a regular session and, at
 125 the same time, is also acting as a session manager to the editor.
 126   </para>
 127
 128   <para>
 129 Clients initialize by connecting to the session manager and obtaining
 130 a <firstterm>client-ID</firstterm> that uniquely identifies them in
 131 the session.  The session manager maintains a list of properties for
 132 each client in the session.  These properties describe the client's
 133 environment and, most importantly, describe how the client can be
 134 restarted (via an <property>SmRestartCommand</property>). Clients are
 135 expected to save their state in such a way as to allow multiple
 136 instantiations of themselves to be managed independently.  For
 137 example, clients may use their client-ID as part of a filename in
 138 which to store the state for a particular instantiation.  The
 139 client-ID should be saved as part of the <property>SmRestartCommand</property>
 140 so that the client will retain the same ID after it is restarted.
 141   </para>
 142
 143   <para>
 144 Once the client initializes itself with the session manager, it must
 145 be ready to respond to messages from the session manager.  For
 146 example, it might be asked to save its state or to terminate.  In the
 147 case of a shutdown, the session manager might give each client a
 148 chance to interact with the user and cancel the shutdown.
 149   </para>
 150 </chapter>
 151
 152 <chapter id='understanding_smlibs_dependence_on_ice'>
 153   <title>Understanding SMlib's Dependence on ICE</title>
 154
 155   <para>
 156 The X Session Management Protocol is layered on top of the
 157 Inter-Client Exchange (<acronym>ICE</acronym>) Protocol.  The ICE
 158 protocol is designed to multiplex several protocols over a single
 159 connection.  As a result, working with SMlib requires a little
 160 knowledge of how the ICE library works.
 161   </para>
 162
 163   <para>
 164 The ICE library utilizes callbacks to process messages.  When a client
 165 detects that there is data to read on an ICE connection, it should
 166 call the <function>IceProcessMessages</function> function.
 167 <function>IceProcessMessages</function> will read the message header
 168 and look at the major opcode in order to determine which protocol the
 169 message was intended for.  The appropriate protocol library will then
 170 be triggered to unpack the message and hand it off to the client via a
 171 callback.
 172   </para>
 173
 174   <para>
 175 The main point to be aware of is that an application using SMlib must
 176 have some code that detects when there is data to read on an ICE
 177 connection.  This can be done via a <function>select</function> call
 178 on the file descriptor for the ICE connection, but more
 179 typically, <function>XtAppAddInput</function> will be used to register
 180 a callback that will invoke <function>IceProcessMessages</function>
 181 each time there is data to read on the ICE connection.
 182   </para>
 183
 184   <para>
 185 To further complicate things, knowing which file descriptors to
 186 call <function>select</function> on requires an understanding of how
 187 ICE connections are created.  On the client side, a call must be made
 188 to <function>SmcOpenConnection</function> in order to open a connection
 189 with a session manager.  <function>SmcOpenConnection</function> will
 190 internally makea call into <function>IceOpenConnection</function>
 191 which will, in turn, determine if an ICE connection already exists
 192 between the client and session manager.  Most likely, a connection
 193 will not already exist and a new ICE connection will be created.  The
 194 main point to be aware of is that, on the client side, it is not
 195 obvious when ICE connections get created or destroyed, because
 196 connections are shared when possible.  To deal with this, the ICE
 197 library lets the application register watch procedures that will be
 198 invoked each time an ICE connection is opened or closed.  These watch
 199 procedures could be used to add or remove ICE file descriptors from
 200 the list of descriptors to call <function>select</function> on.
 201   </para>
 202
 203   <para>
 204 On the session manager side, things work a bit differently.  The
 205 session manager has complete control over the creation of ICE
 206 connections.  The session manager has to first
 207 call <function>IceListenForConnections</function> in order to start
 208 listening for connections from clients.  Once a connection attempt is
 209 detected, <function>IceAcceptConnection</function> must be called, and
 210 the session manager can simply add the new ICE file descriptor to the
 211 list of descriptors to call <function>select</function> on.
 212
 213   </para>
 214
 215   <para>
 216 For further information on the library functions related to ICE connections,
 217 see the <citetitle pubwork='article'>Inter-Client Exchange Library</citetitle>
 218 standard.
 219   </para>
 220 </chapter>
 221
 222 <chapter id='header_files_and_library_name'>
 223 <title>Header Files and Library Name</title>
 224
 225   <para>
 226 Applications (both session managers and clients) should include the
 227 header file &lt;<filename class='headerfile'>X11/SM/SMlib.h</filename>&gt;.
 228 This header file defines all of the SMlib data structures and function
 229 prototypes.  <filename class='headerfile'>SMlib.h</filename> includes the
 230 header file &lt;<filename class='headerfile'>X11/SM/SM.h</filename>&gt;,
 231 which defines all of the SMlib constants.
 232   </para>
 233
 234   <para>
 235 Because SMlib is dependent on ICE, applications should link against
 236 SMlib and ICElib by using
 237 <quote><option>-lSM</option> <option>-lICE</option></quote>.
 238   </para>
 239 </chapter>
 240
 241 <chapter id='session_management_client'>
 242   <title>Session Management Client (<acronym>Smc</acronym>) Functions</title>
 243
 244   <para>
 245     This section discusses how Session Management clients:
 246     <itemizedlist mark='bullet'>
 247       <listitem><para>Connect to the Session Manager</para></listitem>
 248       <listitem><para>Close the connection</para></listitem>
 249       <listitem><para>Modify callbacks</para></listitem>
 250       <listitem><para>Set, delete, and retrieve Session Manager properties</para></listitem>
 251       <listitem><para>Interact with the user</para></listitem>
 252       <listitem><para>Request a &ldquo;Save Yourself&rdquo;</para></listitem>
 253       <listitem><para>Request a &ldquo;Save Yourself Phase 2&rdquo;</para></listitem>
 254       <listitem><para>Complete a &ldquo;Save Yourself&rdquo;</para></listitem>
 255       <listitem><para>Use Smc informational functions</para></listitem>
 256       <listitem><para>Handle Errors</para></listitem>
 257     </itemizedlist>
 258   </para>
 259
 260   <sect1 id='connecting_to_the_session_manager'>
 261     <title>Connecting to the Session Manager</title>
 262
 263     <para>
 264 To open a connection with a session manager,
 265 use <function>SmcOpenConnection</function>
 266     </para>
 267
 268     <funcsynopsis>
 269       <funcprototype>
 270         <funcdef>SmcConn <function>SmcOpenConnection</function></funcdef>
 271         <paramdef>char *<parameter>network_ids_list</parameter></paramdef>
 272         <paramdef>SmPointer <parameter>context</parameter></paramdef>
 273         <paramdef>int <parameter>xsmp_major_rev</parameter></paramdef>
 274         <paramdef>int <parameter>xsmp_minor_rev</parameter></paramdef>
 275         <paramdef>unsigned long <parameter>mask</parameter></paramdef>
 276         <paramdef>SmcCallbacks *<parameter>callbacks</parameter></paramdef>
 277         <paramdef>char *<parameter>previous_id</parameter></paramdef>
 278         <paramdef>char **<parameter>client_id_ret</parameter></paramdef>
 279         <paramdef>int <parameter>error_length</parameter></paramdef>
 280         <paramdef>char *<parameter>error_string_ret</parameter></paramdef>
 281       </funcprototype>
 282     </funcsynopsis>
 283
 284     <variablelist remap='IP'>
 285       <varlistentry>
 286         <term><parameter>network_ids_list</parameter></term>
 287         <listitem><para>Specifies the network ID(s) of the session manager.</para></listitem>
 288       </varlistentry>
 289       <varlistentry>
 290         <term><parameter>context</parameter></term>
 291         <listitem><para>
 292 A pointer to an opaque object or <constant>NULL</constant>.  Used to determine
 293 if an ICE connection can be shared
 294 (see <link linkend='context_sharing'>below</link>).
 295      </para></listitem>
 296       </varlistentry>
 297       <varlistentry>
 298         <term><parameter>xsmp_major_rev</parameter></term>
 299         <listitem><para>
 300 The highest major version of the XSMP the application supports.
 301         </para></listitem>
 302       </varlistentry>
 303       <varlistentry>
 304         <term><parameter>xsmp_minor_rev</parameter></term>
 305         <listitem><para>
 306 The highest minor version of the XSMP the application supports (for
 307 the specified <parameter>xsmp_major_rev</parameter>).
 308         </para></listitem>
 309       </varlistentry>
 310       <varlistentry>
 311         <term><parameter>mask</parameter></term>
 312         <listitem><para>A mask indicating which callbacks to register.</para></listitem>
 313       </varlistentry>
 314       <varlistentry>
 315         <term><parameter>callbacks</parameter></term>
 316         <listitem><para>
 317 The callbacks to register.  These callbacks are used to respond to
 318 messages from the session manager.
 319         </para></listitem>
 320       </varlistentry>
 321       <varlistentry>
 322         <term><parameter>previous_id</parameter></term>
 323         <listitem><para>The client ID from the previous session.</para></listitem>
 324       </varlistentry>
 325       <varlistentry>
 326         <term><parameter>client_id_ret</parameter></term>
 327         <listitem><para>The client ID for the current session is returned.</para></listitem>
 328       </varlistentry>
 329       <varlistentry>
 330         <term><parameter>error_length</parameter></term>
 331         <listitem><para>Length of the <parameter>error_string_ret</parameter> argument passed in.</para></listitem>
 332       </varlistentry>
 333       <varlistentry>
 334         <term><parameter>error_string_ret</parameter></term>
 335         <listitem><para>
 336 Returns a null-terminated error message, if any.
 337 The <parameter>error_string_ret</parameter> argument points to user supplied
 338 memory.  No more than <parameter>error_length</parameter> bytes are used.
 339         </para></listitem>
 340       </varlistentry>
 341     </variablelist>
 342
 343     <para>
 344 The <parameter>network_ids_list</parameter> argument is a
 345 null-terminated string containing a list of network IDs for the session
 346 manager, separated by commas. If <parameter>network_ids_list</parameter>
 347 is <constant>NULL</constant>, the value of
 348 the <envar>SESSION_MANAGER</envar> environment variable will be used.
 349 Each network ID has the following format:
 350
 351 <informaltable pgwide='0' frame='none'>
 352   <tgroup cols='3' align='center'>
 353     <colspec colname='c1'/>
 354     <colspec colname='c2'/>
 355     <colspec colname='c3'/>
 356     <tbody>
 357       <row>
 358         <entry align='left'></entry>
 359         <entry align='left'><literal>tcp/</literal><parameter>&lt;hostname&gt;</parameter><literal>:</literal><parameter>&lt;portnumber&gt;</parameter></entry>
 360         <entry align='left'>or</entry>
 361       </row>
 362       <row>
 363         <entry align='left'></entry>
 364         <entry align='left'><literal>decnet/</literal><parameter>&lt;hostname&gt;</parameter><literal>::</literal><parameter>&lt;objname&gt;</parameter></entry>
 365         <entry align='left'>or</entry>
 366       </row>
 367       <row>
 368         <entry align='left'></entry>
 369         <entry align='left'><literal>local/</literal><parameter>&lt;hostname&gt;</parameter><literal>:</literal><parameter>&lt;path&gt;</parameter></entry>
 370         <entry align='left'></entry>
 371       </row>
 372     </tbody>
 373   </tgroup>
 374 </informaltable>
 375     </para>
 376
 377     <para>
 378 An attempt will be made to use the first network ID.  If that fails,
 379 an attempt will be made using the second network ID, and so on.
 380     </para>
 381
 382     <para>
 383 After the connection is established, <function>SmcOpenConnection</function>
 384 registers the client with the session manager.  If the client is being
 385 restarted from a previous session, <parameter>previous_id</parameter>
 386 should contain a null terminated string representing the client ID from the
 387 previous session.  If the client is first joining the session,
 388 <parameter>previous_id</parameter> should be set to <constant>NULL</constant>.
 389 If <parameter>previous_id</parameter> is specified but is determined
 390 to be invalid by the session manager, SMlib will re-register the
 391 client with <parameter>previous_id</parameter> set to <constant>NULL</constant>.
 392     </para>
 393
 394     <para>
 395 If <function>SmcOpenConnection</function> succeeds, it returns an
 396 opaque connection pointer of type <function>SmcConn</function> and the
 397 <parameter>client_id_ret</parameter> argument contains the client ID to be
 398 used for this session.  The <parameter>client_id_ret</parameter> should be
 399 freed with a call to <function>free</function> when no longer needed.  On
 400 failure, <function>SmcOpenConnection</function> returns
 401 <constant>NULL</constant>, and the reason for failure is returned in
 402 <parameter>error_string_ret</parameter>.
 403     </para>
 404
 405     <para>
 406 Note that SMlib uses the ICE protocol to establish a connection with
 407 the session manager.  If an ICE connection already exists between the
 408 client and session manager, it might be possible for the same ICE
 409 connection to be used for session management.
 410     </para>
 411
 412     <para id='context_sharing'>
 413 The context argument indicates how willing the client is to share the
 414 ICE connection with other protocols.  If context is <constant>NULL</constant>,
 415 then the caller is always willing to share the connection.  If context is not
 416 <constant>NULL</constant>, then the caller is not willing to use a previously
 417 opened ICE connection that has a different non-<constant>NULL</constant>
 418 context associated with it.
 419     </para>
 420
 421     <para>
 422 As previously discussed
 423 (<link linkend='understanding_smlibs_dependence_on_ice'>section 3,
 424 &ldquo;Understanding SMlib's Dependence on ICE&rdquo;</link>), the
 425 client will have to keep track of when ICE connections are created or
 426 destroyed (using <function>IceAddConnectionWatch</function>
 427 and <function>IceRemoveConnectionWatch</function> and will have to
 428 call <function>IceProcessMessages</function> each time
 429 a <function>select</function> shows that there is data to read on an
 430 ICE connection.  For further information, see the
 431 <citetitle pubwork='article'>Inter-Client Exchange Library</citetitle>
 432 standard.
 433     </para>
 434
 435     <para>
 436 The callbacks argument contains a set of callbacks used to respond to
 437 session manager events.  The mask argument specifies which callbacks
 438 are set.  All of the callbacks specified in this version of SMlib are
 439 mandatory.  The mask argument is necessary in order to maintain
 440 backwards compatibility in future versions of the library.
 441     </para>
 442
 443     <para>
 444 The following values may be ORed together to obtain a
 445 <parameter>mask</parameter> value:
 446
 447       <simplelist type='vert'>
 448         <member><constant>SmcSaveYourselfProcMask</constant></member>
 449         <member><constant>SmcDieProcMask</constant></member>
 450         <member><constant>SmcSaveCompleteProcMask</constant></member>
 451         <member><constant>SmcShutdownCancelledProcMask</constant></member>
 452       </simplelist>
 453     </para>
 454
 455     <para>
 456 For each callback, the client can register a pointer to client data.
 457 When SMlib invokes the callback, it will pass the client data pointer.
 458     </para>
 459
 460 <!-- .ne 4  IGNORED -->
 461
 462 <synopsis>
 463 typedef struct {
 464
 465         struct {
 466                 SmcSaveYourselfProc callback;
 467                 SmPointer client_data;
 468         } save_yourself;
 469
 470         struct {
 471                 SmcDieProc callback;
 472                 SmPointer client_data;
 473         } die;
 474
 475         struct {
 476                 SmcSaveCompleteProc callback;
 477                 SmPointer client_data;
 478         } save_complete;
 479
 480         struct {
 481                 SmcShutdownCancelledProc callback;
 482                 SmPointer client_data;
 483         } shutdown_cancelled;
 484
 485 } SmcCallbacks;
 486 </synopsis>
 487
 488     <sect2 id='the_save_yourself_callback'>
 489       <title>The Save Yourself Callback</title>
 490
 491       <para>
 492 The Save Yourself callback is of type <function>SmcSaveYourselfProc</function>
 493       </para>
 494
 495 <funcsynopsis>
 496 <funcprototype>
 497   <funcdef>typedef void (*<function>SaveYourselfProc</function>)</funcdef>
 498     <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
 499     <paramdef>SmcConn <parameter>client_data</parameter></paramdef>
 500     <paramdef>int <parameter>save_type</parameter></paramdef>
 501     <paramdef>Bool <parameter>shutdown</parameter></paramdef>
 502     <paramdef>int <parameter>interact_style</parameter></paramdef>
 503     <paramdef>Bool <parameter>fast</parameter></paramdef>
 504 </funcprototype>
 505 </funcsynopsis>
 506
 507 <variablelist remap='IP'>
 508   <varlistentry>
 509     <term><parameter>smc_conn</parameter></term>
 510     <listitem><para>The session management connection object.</para></listitem>
 511   </varlistentry>
 512   <varlistentry>
 513     <term><parameter>client_data</parameter></term>
 514     <listitem><para>Client data specified when the callback was registered.</para></listitem>
 515   </varlistentry>
 516   <varlistentry>
 517     <term><parameter>save_type</parameter></term>
 518     <listitem><para>Specifies the type of information that should be saved.</para></listitem>
 519   </varlistentry>
 520   <varlistentry>
 521     <term><parameter>shut_down</parameter></term>
 522     <listitem><para>Specifies if a shutdown is taking place.</para></listitem>
 523   </varlistentry>
 524   <varlistentry>
 525     <term><parameter>interact_style</parameter></term>
 526     <listitem><para>The type of interaction allowed with the user.</para></listitem>
 527   </varlistentry>
 528   <varlistentry>
 529     <term><parameter>fast</parameter></term>
 530     <listitem><para>if <symbol>True</symbol>, then client should save its state as quickly as possible.</para></listitem>
 531   </varlistentry>
 532 </variablelist>
 533
 534       <para>
 535 The session manager sends a &ldquo;Save Yourself&rdquo; message to a
 536 client either to checkpoint it or just before termination so that it
 537 can save its state.  The client responds with zero or more calls
 538 to <function>SmcSetProperties</function> to update the properties
 539 indicating how to restart the client.  When all the properties have
 540 been set, the client calls <function>SmcSaveYourselfDone</function>
 541       </para>
 542
 543       <para>
 544 If <parameter>interact_style</parameter> is
 545 <constant>SmInteractStyleNone</constant> the
 546 client must not interact with the user while saving state.
 547 If <parameter>interact_style</parameter> is
 548 <constant>SmInteractStyleErrors</constant> the
 549 client may interact with the user only if an error condition arises.
 550 If <parameter>interact_style</parameter> is
 551 <constant>SmInteractStyleAny</constant> then the
 552 client may interact with the user for any purpose.  Because only one
 553 client can interact with the user at a time, the client must
 554 call <function>SmcInteractRequest</function> and wait for an
 555 &ldquo;Interact&rdquo; message from the session manager.  When the
 556 client is done interacting with the user, it
 557 calls <function>SmcInteractDone</function> The client may only
 558 call <function>SmcInteractRequest</function> after it receives a
 559 &ldquo;Save Yourself&rdquo; message and before it
 560 calls <function>SmcSaveYourselfDone</function>
 561       </para>
 562
 563       <para>
 564 If <parameter>save_type</parameter> is <constant>SmSaveLocal</constant> the
 565 client must update the properties to reflect its current state.  Specifically,
 566 it should save enough information to restore the state as seen by the
 567 user of this client.  It should not affect the state as seen by other users.
 568 If <parameter>save_type</parameter> is <constant>SmSaveGlobal</constant>
 569 the user wants the client to commit all of its data to permanent, globally
 570 accessible storage.
 571 If <parameter>save_type</parameter> is <constant>SmSaveBoth</constant>
 572 the client should do both of these (it should first commit the data to
 573 permanent storage before updating its properties).
 574       </para>
 575
 576       <para>
 577 Some examples are as follows:
 578
 579         <itemizedlist mark='bullet'>
 580           <listitem><para>
 581 If a word processor were sent a &ldquo;Save Yourself&rdquo; with a
 582 type of <constant>SmSaveLocal</constant> it could create a temporary
 583 file that included the current contents of the file, the location of
 584 the cursor, and other aspects of the current editing session.  It
 585 would then update its <property>SmRestartCommand</property> property with
 586 enough information to find this temporary file.
 587           </para></listitem>
 588           <listitem><para>
 589 If a word processor were sent a &ldquo;Save Yourself&rdquo; with a
 590 type of <constant>SmSaveGlobal</constant> it would simply save the
 591 currently edited file.
 592           </para></listitem>
 593           <listitem><para>
 594 If a word processor were sent a &ldquo;Save Yourself&rdquo; with a
 595 type of <constant>SmSaveBoth</constant> it would first save the
 596 currently edited file.  It would then create a temporary file with
 597 information such as the current position of the cursor and what file
 598 is being edited.  Finally, it would update its
 599 <property>SmRestartCommand</property> property with enough information
 600 to find the temporary file.
 601           </para></listitem>
 602         </itemizedlist>
 603       </para>
 604
 605       <para>
 606 The <parameter>shutdown</parameter> argument specifies whether the
 607 system is being shut down.
 608 The interaction is different depending on whether or not shutdown is
 609 set.  If not shutting down, the client should save its state and wait
 610 for a &ldquo;Save Complete&rdquo; message.  If shutting down, the
 611 client must save state and then prevent interaction until it receives
 612 either a &ldquo;Die&rdquo; or a &ldquo;Shutdown Cancelled.&rdquo;
 613       </para>
 614
 615       <para>
 616 The <parameter>fast</parameter> argument specifies that the client
 617 should save its state as quickly as possible.  For example, if the
 618 session manager knows that power is about to fail, it would
 619 set <parameter>fast</parameter> to <constant>True</constant>.
 620       </para>
 621     </sect2>
 622
 623     <sect2 id='the_die_callback'>
 624       <title>The Die Callback</title>
 625
 626       <para>
 627 The Die callback is of type <function>SmcDieProc</function>
 628       </para>
 629
 630 <funcsynopsis>
 631 <funcprototype>
 632   <funcdef>typedef void (*<function>SmcDieProc</function>)</funcdef>
 633     <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
 634     <paramdef>SmcConn <parameter>client_data</parameter></paramdef>
 635 </funcprototype>
 636 </funcsynopsis>
 637
 638 <variablelist remap='IP'>
 639   <varlistentry>
 640     <term><parameter>smc_conn</parameter></term>
 641     <listitem><para>The session management connection object.</para></listitem>
 642   </varlistentry>
 643   <varlistentry>
 644     <term><parameter>client_data</parameter></term>
 645     <listitem><para>Client data specified when the callback was registered.</para></listitem>
 646   </varlistentry>
 647 </variablelist>
 648
 649
 650       <para>
 651 The session manager sends a &ldquo;Die&rdquo; message to a client when
 652 it wants it to die.  The client should respond by calling
 653 <function>SmcCloseConnection</function>.  A session manager that
 654 behaves properly will send a &ldquo;Save Yourself&rdquo; message
 655 before the &ldquo;Die&rdquo; message.
 656       </para>
 657     </sect2>
 658
 659     <sect2 id='the_save_complete_callback'>
 660       <title>The Save Complete Callback</title>
 661
 662       <para>
 663 The Save Complete callback is of type <function>SmcSaveCompleteProc</function>
 664       </para>
 665
 666 <funcsynopsis>
 667    <funcprototype>
 668       <funcdef>typedef void (*<function>SmcSaveCompleteProc</function>)</funcdef>
 669       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
 670       <paramdef>SmPointer <parameter>client_data</parameter></paramdef>
 671   </funcprototype>
 672 </funcsynopsis>
 673
 674 <variablelist remap='IP'>
 675   <varlistentry>
 676     <term><parameter>smc_conn</parameter></term>
 677     <listitem><para>The session management connection object.</para></listitem>
 678   </varlistentry>
 679   <varlistentry>
 680     <term><parameter>client_data</parameter></term>
 681     <listitem><para>Client data specified when the callback was registered.</para></listitem>
 682   </varlistentry>
 683 </variablelist>
 684     </sect2>
 685
 686
 687     <sect2 id='the_shutdown_cancelled_callback'>
 688       <title>The Shutdown Cancelled Callback</title>
 689
 690       <para>
 691 The Shutdown Cancelled callback is of type
 692 <function>SmcShutdownCancelledProc</function>
 693       </para>
 694
 695 <funcsynopsis>
 696    <funcprototype>
 697       <funcdef>typedef void (*<function>SmcShutdownCancelledProc</function>)</funcdef>
 698       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
 699       <paramdef>SmPointer <parameter>client_data</parameter></paramdef>
 700   </funcprototype>
 701 </funcsynopsis>
 702
 703 <variablelist remap='IP'>
 704   <varlistentry>
 705     <term><parameter>smc_conn</parameter></term>
 706     <listitem><para>The session management connection object.</para></listitem>
 707   </varlistentry>
 708   <varlistentry>
 709     <term><parameter>client_data</parameter></term>
 710     <listitem><para>Client data specified when the callback was registered.</para></listitem>
 711   </varlistentry>
 712 </variablelist>
 713
 714       <para>
 715 The session manager sends a &ldquo;Shutdown Cancelled&rdquo; message
 716 when the user cancelled the shutdown during an interaction
 717 (see <link linkend='interacting_with_the_user'>section 5.5,
 718 &ldquo;Interacting With the User&rdquo;</link>).  The client can now
 719 continue as if the shutdown had never happened.  If the client has not
 720 called <function>SmcSaveYourselfDone</function> yet, it can either
 721 abort the save and then call <function>SmcSaveYourselfDone</function>
 722 with the success argument set to <constant>False</constant> or it can
 723 continue with the save and then call <function>SmcSaveYourselfDone</function>
 724 with the <parameter>success</parameter> argument set to reflect the outcome
 725 of the save.
 726       </para>
 727     </sect2>
 728   </sect1>
 729
 730   <sect1 id='closing_the_connection'><title>Closing the Connection</title>
 731
 732     <para>
 733 To close a connection with a session manager,
 734 use <function>SmcCloseConnection</function>
 735     </para>
 736
 737 <funcsynopsis>
 738    <funcprototype>
 739       <funcdef>SmcCloseStatus <function>SmcCloseConnection</function></funcdef>
 740       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
 741       <paramdef>int <parameter>count</parameter></paramdef>
 742       <paramdef>char **<parameter>reason_msgs</parameter></paramdef>
 743   </funcprototype>
 744 </funcsynopsis>
 745 <variablelist remap='IP'>
 746   <varlistentry>
 747     <term><parameter>smc_conn</parameter></term>
 748     <listitem><para>The session management connection object.</para></listitem>
 749   </varlistentry>
 750   <varlistentry>
 751     <term><parameter>count</parameter></term>
 752     <listitem><para>The number of reasons for closing the connection.</para></listitem>
 753   </varlistentry>
 754   <varlistentry>
 755     <term><parameter>reason_msgs</parameter></term>
 756     <listitem><para>The reasons for closing the connection.</para></listitem>
 757   </varlistentry>
 758 </variablelist>
 759
 760     <para>
 761 The <parameter>reason_msgs</parameter> argument will most likely be
 762 <constant>NULL</constant> if resignation is expected by the client.
 763 Otherwise, it contains a list of null-terminated Compound Text strings
 764 representing the reason for termination.  The session manager should
 765 display these reason messages to the user.
 766     </para>
 767
 768     <para>
 769 Note that SMlib used the ICE protocol to establish a connection with
 770 the session manager, and various protocols other than session
 771 management may be active on the ICE connection.
 772 When <function>SmcCloseConnection</function> is called, the ICE
 773 connection will be closed only if all protocols have been shutdown on
 774 the connection.  Check the ICElib standard
 775 for <function>IceAddConnectionWatch</function>
 776 and <function>IceRemoveConnectionWatch</function> to learn how to set
 777 up a callback to be invoked each time an ICE connection is opened or
 778 closed.  Typically this callback adds/removes the ICE file descriptor
 779 from the list of active descriptors to call <function>select</function> on
 780 (or calls <function>XtAppAddInput</function> or
 781 <function>XtRemoveInput</function>).
 782     </para>
 783
 784
 785     <para>
 786 <function>SmcCloseConnection</function> returns one of the following values:
 787
 788       <itemizedlist mark='bullet'>
 789         <listitem><para>
 790 <constant>SmcClosedNow</constant> - the ICE connection was closed at
 791 this time, the watch procedures were invoked, and the connection was freed.
 792         </para></listitem>
 793         <listitem><para>
 794 <constant>SmcClosedASAP</constant> - an IO error had occurred on the
 795 connection, but <function>SmcCloseConnection</function> is being
 796 called within a nested <function>IceProcessMessages</function> The
 797 watch procedures have been invoked at this time, but the connection
 798 will be freed as soon as possible (when the nesting level reaches zero
 799 and <function>IceProcessMessages</function> returns a status
 800 of <function>IceProcessMessagesConnectionClosed</function>
 801         </para> </listitem>
 802         <listitem><para>
 803 <constant>SmcConnectionInUse</constant> - the connection was not closed at
 804 this time, because it is being used by other active protocols.
 805         </para> </listitem>
 806       </itemizedlist>
 807     </para>
 808   </sect1>
 809
 810
 811   <sect1 id='modifying_callbacks'>
 812     <title>Modifying Callbacks</title>
 813
 814     <para>
 815 To modify callbacks set up in <function>SmcOpenConnection</function>
 816 use <function>SmcModifyCallbacks</function>
 817     </para>
 818
 819 <funcsynopsis>
 820    <funcprototype>
 821       <funcdef>void <function>SmcModifyCallbacks</function></funcdef>
 822       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
 823       <paramdef>unsigned long <parameter>mask</parameter></paramdef>
 824       <paramdef>SmcCallbacks *<parameter>callbacks</parameter></paramdef>
 825   </funcprototype>
 826 </funcsynopsis>
 827 <variablelist remap='IP'>
 828   <varlistentry>
 829     <term><parameter>smc_conn</parameter></term>
 830     <listitem><para>The session management connection object.</para></listitem>
 831   </varlistentry>
 832   <varlistentry>
 833     <term><parameter>mask</parameter></term>
 834     <listitem><para>A mask indicating which callbacks to modify.</para></listitem>
 835   </varlistentry>
 836   <varlistentry>
 837     <term><parameter>callbacks</parameter></term>
 838     <listitem><para>The new callbacks.</para></listitem>
 839   </varlistentry>
 840 </variablelist>
 841
 842     <para>
 843 When specifying a value for the <parameter>mask</parameter> argument,
 844 the following values may be ORed together:
 845
 846       <simplelist type='vert'>
 847         <member><constant>SmcSaveYourselfProcMask</constant></member>
 848         <member><constant>SmcDieProcMask</constant></member>
 849         <member><constant>SmcSaveCompleteProcMask</constant></member>
 850         <member><constant>SmcShutdownCancelledProcMask</constant></member>
 851       </simplelist>
 852     </para>
 853   </sect1>
 854
 855   <sect1 id='setting_deleting_and_retrieving_session_management_properties'>
 856     <title>Setting, Deleting, and Retrieving Session Management Properties</title>
 857
 858     <para>
 859 To set session management properties for this client,
 860 use <function>SmcSetProperties</function>
 861     </para>
 862
 863 <funcsynopsis>
 864    <funcprototype>
 865       <funcdef>void <function>SmcSetProperties</function></funcdef>
 866       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
 867       <paramdef>int <parameter>num_props</parameter></paramdef>
 868       <paramdef>SmProp **<parameter>props</parameter></paramdef>
 869   </funcprototype>
 870 </funcsynopsis>
 871
 872 <variablelist remap='IP'>
 873   <varlistentry>
 874     <term><parameter>smc_conn</parameter></term>
 875     <listitem><para>The session management connection object.</para></listitem>
 876   </varlistentry>
 877   <varlistentry>
 878     <term><parameter>num_props</parameter></term>
 879     <listitem><para>The number of properties.</para></listitem>
 880   </varlistentry>
 881   <varlistentry>
 882     <term><parameter>props</parameter></term>
 883     <listitem><para>The list of properties to set.</para></listitem>
 884   </varlistentry>
 885 </variablelist>
 886
 887
 888     <para>
 889 The properties are specified as an array of property pointers.
 890 Previously set property values may be over-written using
 891 the <function>SmcSetProperties</function> function.  Note that the
 892 session manager is not expected to restore property values when the
 893 session is restarted.  Because of this, clients should not try to use
 894 the session manager as a database for storing application specific state.
 895     </para>
 896
 897     <para>
 898 For a description of session management properties and
 899 the <structname>SmProp</structname> structure,
 900 see <link linkend='session_management_properties'>section 7,
 901 &ldquo;Session Management Properties.&rdquo;</link>
 902     </para>
 903
 904
 905     <para>
 906 To delete properties previously set by the client,
 907 use <function>SmcDeleteProperties</function>
 908     </para>
 909
 910 <funcsynopsis>
 911    <funcprototype>
 912       <funcdef>void <function>SmcDeleteProperties</function></funcdef>
 913       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
 914       <paramdef>int <parameter>num_props</parameter></paramdef>
 915       <paramdef>char **<parameter>prop_names</parameter></paramdef>
 916   </funcprototype>
 917 </funcsynopsis>
 918 <variablelist remap='IP'>
 919   <varlistentry>
 920     <term><parameter>smc_conn</parameter></term>
 921     <listitem><para>The session management connection object.</para></listitem>
 922   </varlistentry>
 923   <varlistentry>
 924     <term><parameter>num_props</parameter></term>
 925     <listitem><para>The number of properties.</para></listitem>
 926   </varlistentry>
 927   <varlistentry>
 928     <term><parameter>prop_names</parameter></term>
 929     <listitem><para>The list of properties to set.</para></listitem>
 930   </varlistentry>
 931 </variablelist>
 932
 933     <para>
 934 To get properties previously stored by the client,
 935 use <function>SmcGetProperties</function>
 936     </para>
 937
 938 <funcsynopsis>
 939    <funcprototype>
 940       <funcdef>Status <function>SmcGetProperties</function></funcdef>
 941       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
 942       <paramdef>SmcPropReplyProc <parameter>prop_reply_proc</parameter></paramdef>
 943       <paramdef>SmPointer <parameter>client_data</parameter></paramdef>
 944   </funcprototype>
 945 </funcsynopsis>
 946
 947 <variablelist remap='IP'>
 948   <varlistentry>
 949     <term><parameter>smc_conn</parameter></term>
 950     <listitem><para>The session management connection object.</para></listitem>
 951   </varlistentry>
 952   <varlistentry>
 953     <term><parameter>prop_reply_proc</parameter></term>
 954     <listitem><para>The callback to be invoked when the properties reply comes back.</para></listitem>
 955   </varlistentry>
 956   <varlistentry>
 957     <term><parameter>client_data</parameter></term>
 958     <listitem><para>This pointer to client data will be passed to the <function>SmcPropReplyProc</function> callback.</para></listitem>
 959   </varlistentry>
 960 </variablelist>
 961
 962     <para>
 963 The return value of <function>SmcGetProperties</function> is zero for
 964 failure and a positive value for success.
 965     </para>
 966
 967     <para>
 968 Note that the library does not block until the properties reply comes
 969 back.  Rather, a callback of type <function>SmcPropReplyProc</function>
 970 is invoked when the data is ready.
 971     </para>
 972
 973 <funcsynopsis>
 974    <funcprototype>
 975       <funcdef>typedef void (*<function>SmcPropReplyProc</function>)</funcdef>
 976       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
 977       <paramdef>SmPointer <parameter>client_data</parameter></paramdef>
 978       <paramdef>int <parameter>num_props</parameter></paramdef>
 979       <paramdef>SmProp **<parameter>props</parameter></paramdef>
 980   </funcprototype>
 981 </funcsynopsis>
 982
 983 <variablelist remap='IP'>
 984   <varlistentry>
 985     <term><parameter>smc_conn</parameter></term>
 986     <listitem><para>The session management connection object.</para></listitem>
 987   </varlistentry>
 988   <varlistentry>
 989     <term><parameter>client_data</parameter></term>
 990     <listitem><para>This pointer to client data will be passed to the <function>SmcPropReplyProc</function> callback.</para></listitem>
 991   </varlistentry>
 992   <varlistentry>
 993     <term><parameter>num_props</parameter></term>
 994     <listitem><para>The number of properties returned.</para></listitem>
 995   </varlistentry>
 996   <varlistentry>
 997     <term><parameter>props</parameter></term>
 998     <listitem><para>The list of properties returned.</para></listitem>
 999   </varlistentry>
1000 </variablelist>
1001
1002     <para>
1003 To free each property, use <function>SmFreeProperty</function>
1004 (see <link linkend='freeing_data'>section 8, &ldquo;Freeing
1005 Data&rdquo;</link>).  To free the actual array of pointers,
1006 use <function>free</function>
1007     </para>
1008   </sect1>
1009
1010   <sect1 id='interacting_with_the_user'>
1011     <title>Interacting With the User</title>
1012
1013     <para>
1014 After receiving a &ldquo;Save Yourself&rdquo; message with an
1015 <parameter>interact_style</parameter> of
1016 <constant>SmInteractStyleErrors</constant>
1017 or <constant>SmInteractStyleAny</constant> the client may choose to
1018 interact with the user.  Because only one client can interact with the
1019 user at a time, the client must call <function>SmcInteractRequest</function>
1020 and wait for an &ldquo;Interact&rdquo; message from the session manager.
1021     </para>
1022
1023 <funcsynopsis>
1024    <funcprototype>
1025       <funcdef>Status <function>SmcInteractRequest</function></funcdef>
1026       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1027       <paramdef>int <parameter>dialog_type</parameter></paramdef>
1028       <paramdef>SmcInteractProc <parameter>interact_proc</parameter></paramdef>
1029       <paramdef>SmPointer <parameter>client_data</parameter></paramdef>
1030   </funcprototype>
1031 </funcsynopsis>
1032
1033 <variablelist remap='IP'>
1034   <varlistentry>
1035     <term><parameter>smc_conn</parameter></term>
1036     <listitem><para>The session management connection object.</para></listitem>
1037   </varlistentry>
1038   <varlistentry>
1039     <term><parameter>dialog_type</parameter></term>
1040     <listitem><para>The type of dialog the client wishes to present to the user.</para></listitem>
1041   </varlistentry>
1042   <varlistentry>
1043     <term><parameter>interact_proc</parameter></term>
1044     <listitem><para>The callback to be invoked when the &ldquo;Interact&rdquo; message arrives from the session manager.</para></listitem>
1045   </varlistentry>
1046   <varlistentry>
1047     <term><parameter>client_data</parameter></term>
1048     <listitem><para>
1049 This pointer to client data will be passed to
1050 the <function>SmcInteractProc</function> callback when the
1051 &ldquo;Interact&rdquo; message arrives.
1052     </para></listitem>
1053   </varlistentry>
1054 </variablelist>
1055
1056     <para>
1057 The return value of <function>SmcInteractRequest</function> is zero
1058 for failure and a positive value for success.
1059     </para>
1060
1061     <para>
1062 The <parameter>dialog_type</parameter> argument specifies
1063 either <constant>SmDialogError</constant> indicating that the client
1064 wants to start an error dialog, or <constant>SmDialogNormal</constant>
1065 meaning that the client wishes to start a nonerror dialog.
1066     </para>
1067
1068     <para>
1069 Note that if a shutdown is in progress, the user may have the option
1070 of cancelling the shutdown.  If the shutdown is cancelled, the clients
1071 that have not interacted yet with the user will receive a
1072 &ldquo;Shutdown Cancelled&rdquo; message instead of the
1073 &ldquo;Interact&rdquo; message.
1074     </para>
1075
1076     <para>
1077 The <function>SmcInteractProc</function> callback will be invoked when
1078 the &ldquo;Interact&rdquo; message arrives from the session manager.
1079     </para>
1080
1081 <funcsynopsis>
1082    <funcprototype>
1083       <funcdef>typedef void (*<function>SmcInteractProc</function>)</funcdef>
1084       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1085       <paramdef>SmPointer <parameter>client_data</parameter></paramdef>
1086   </funcprototype>
1087 </funcsynopsis>
1088
1089 <variablelist remap='IP'>
1090   <varlistentry>
1091     <term><parameter>smc_conn</parameter></term>
1092     <listitem><para>The session management connection object.</para></listitem>
1093   </varlistentry>
1094   <varlistentry>
1095     <term><parameter>client_data</parameter></term>
1096     <listitem><para>Client data specified when the callback was registered.</para></listitem>
1097   </varlistentry>
1098 </variablelist>
1099
1100     <para>
1101 After interacting with the user (in response to an &ldquo;Interact&rdquo;
1102 message), you should call <function>SmcInteractDone</function>
1103     </para>
1104
1105 <funcsynopsis>
1106    <funcprototype>
1107       <funcdef>void <function>SmcInteractDone</function></funcdef>
1108       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1109       <paramdef>Bool <parameter>cancel_shutdown</parameter></paramdef>
1110   </funcprototype>
1111 </funcsynopsis>
1112
1113 <variablelist remap='IP'>
1114   <varlistentry>
1115     <term><parameter>smc_conn</parameter></term>
1116     <listitem><para>The session management connection object.</para></listitem>
1117   </varlistentry>
1118   <varlistentry>
1119     <term><parameter>cancel_shutdown</parameter></term>
1120     <listitem><para>If <constant>True</constant>, indicates that the user requests that the entire shutdown be cancelled.</para></listitem>
1121   </varlistentry>
1122 </variablelist>
1123     <para>
1124 The <parameter>cancel_shutdown</parameter> argument may only be
1125 <constant>True</constant> if the corresponding &ldquo;Save Yourself&rdquo;
1126 specified <constant>True</constant> for shutdown
1127 and <constant>SmInteractStyleErrors</constant>
1128 or <constant>SmInteractStyleAny</constant> for
1129 the <parameter>interact_style</parameter>.
1130     </para>
1131   </sect1>
1132
1133   <sect1 id='requesting_a_save_yourself'>
1134     <title>Requesting a Save Yourself</title>
1135
1136     <para>
1137 To request a checkpoint from the session manager,
1138 use <function>SmcRequestSaveYourself</function>
1139     </para>
1140
1141 <funcsynopsis>
1142    <funcprototype>
1143       <funcdef>void <function>SmcRequestSaveYourself</function></funcdef>
1144       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1145       <paramdef>int <parameter>save_type</parameter></paramdef>
1146       <paramdef>Bool <parameter>shutdown</parameter></paramdef>
1147       <paramdef>int <parameter>interact_style</parameter></paramdef>
1148       <paramdef>Bool <parameter>fast</parameter></paramdef>
1149       <paramdef>Bool <parameter>global</parameter></paramdef>
1150   </funcprototype>
1151 </funcsynopsis>
1152
1153
1154 <variablelist remap='IP'>
1155   <varlistentry>
1156     <term><parameter>smc_conn</parameter></term>
1157     <listitem><para>The session management connection object.</para></listitem>
1158   </varlistentry>
1159   <varlistentry>
1160     <term><parameter>save_type</parameter></term>
1161     <listitem><para>Specifies the type of information that should be saved.</para></listitem>
1162   </varlistentry>
1163   <varlistentry>
1164     <term><parameter>shutdown</parameter></term>
1165     <listitem><para>Specifies if a shutdown is taking place.</para></listitem>
1166   </varlistentry>
1167   <varlistentry>
1168     <term><parameter>interact_style</parameter></term>
1169     <listitem><para>The type of interaction allowed with the user.</para></listitem>
1170   </varlistentry>
1171   <varlistentry>
1172     <term><parameter>fast</parameter></term>
1173     <listitem><para>If <constant>True</constant> the client should save its state as quickly as possible.</para></listitem>
1174   </varlistentry>
1175   <varlistentry>
1176     <term><parameter>global</parameter></term>
1177     <listitem><para>Controls who gets the &ldquo;Save Yourself.&rdquo;</para></listitem>
1178   </varlistentry>
1179 </variablelist>
1180
1181     <para>
1182 The <parameter>save_type</parameter>, <parameter>shutdown</parameter>,
1183 <parameter>interact_style</parameter>, and <parameter>fast</parameter>
1184 arguments are discussed in more detail in
1185 <link linkend='the_save_yourself_callback'>section 5.1.1,
1186 &ldquo;The Save Yourself Callback.&rdquo;</link>
1187     </para>
1188
1189     <para>
1190 If <parameter>global</parameter> is set to <constant>True</constant> then
1191 the resulting &ldquo;Save Yourself&rdquo; should be sent to all clients in the
1192 session.  For example, a vendor of a Uninterruptible Power Supply
1193 (<acronym>UPS</acronym>) might include a Session Management client
1194 that would monitor the status of the UPS and generate a fast shutdown
1195 if the power is about to be lost.
1196     </para>
1197
1198     <para>
1199 If global is set to <constant>False</constant> then the &ldquo;Save
1200 Yourself&rdquo; should only be sent to the client that requested it.
1201     </para>
1202   </sect1>
1203
1204   <sect1 id='requesting_a_save_yourself_phase_2'>
1205     <title>Requesting a Save Yourself Phase 2</title>
1206
1207     <para>
1208 In response to a &ldquo;Save Yourself&rdquo;, the client may request to be
1209 informed when all the other clients are quiescent so that it can save their
1210 state.  To do so, use <function>SmcRequestSaveYourselfPhase2</function>
1211     </para>
1212
1213 <funcsynopsis>
1214    <funcprototype>
1215       <funcdef>Status <function>SmcRequestSaveYourselfPhase2</function></funcdef>
1216       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1217       <paramdef>SmcSaveYourselfPhase2Proc <parameter>save_yourself_phase2_proc</parameter></paramdef>
1218       <paramdef>SmPointer <parameter>client_data</parameter></paramdef>
1219   </funcprototype>
1220 </funcsynopsis>
1221
1222 <variablelist remap='IP'>
1223   <varlistentry>
1224     <term><parameter>smc_conn</parameter></term>
1225     <listitem><para>The session management connection object.</para></listitem>
1226   </varlistentry>
1227   <varlistentry>
1228     <term><parameter>save_type_phase2_proc</parameter></term>
1229     <listitem><para>The callback to be invoked when the &ldquo;Save Yourself Phase 2&rdquo; message arrives from the session manager.</para></listitem>
1230   </varlistentry>
1231   <varlistentry>
1232     <term><parameter>client_data</parameter></term>
1233     <listitem><para>This pointer to client data will be passed to the <function>SmcSaveYourselfPhase2Proc</function> callback when the &ldquo;Save Yourself Phase 2&rdquo; message arrives.</para></listitem>
1234   </varlistentry>
1235 </variablelist>
1236
1237     <para>
1238 The return value of <function>SmcRequestSaveYourselfPhase2</function>
1239 is zero for failure and a positive value for success.
1240     </para>
1241
1242     <para>
1243 This request is needed by clients that manage other clients (for
1244 example, window managers, workspace managers, and so on).  The manager
1245 must make sure that all of the clients that are being managed are in
1246 an idle state so that their state can be saved.
1247     </para>
1248   </sect1>
1249
1250   <sect1 id='completing_a_save_yourself'>
1251     <title>Completing a Save Yourself</title>
1252
1253     <para>
1254 After saving state in response to a &ldquo;Save Yourself&rdquo;
1255 message, you should call <function>SmcSaveYourselfDone</function>
1256     </para>
1257
1258 <funcsynopsis>
1259    <funcprototype>
1260       <funcdef>void <function>SmcSaveYourselfDone</function></funcdef>
1261       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1262       <paramdef>Bool <parameter>success</parameter></paramdef>
1263   </funcprototype>
1264 </funcsynopsis>
1265
1266 <variablelist remap='IP'>
1267   <varlistentry>
1268     <term><parameter>smc_conn</parameter></term>
1269     <listitem><para>The session management connection object.</para></listitem>
1270   </varlistentry>
1271   <varlistentry>
1272     <term><parameter>success</parameter></term>
1273     <listitem><para>If <constant>True</constant> the &ldquo;Save Yourself&rdquo; operation was completed successfully.</para></listitem>
1274   </varlistentry>
1275 </variablelist>
1276
1277     <para>
1278 Before calling <function>SmcSaveYourselfDone</function> the client
1279 must have set each required property at least once since the client
1280 registered with the session manager.
1281     </para>
1282   </sect1>
1283
1284   <sect1 id='using_smc_informational_functions'>
1285     <title>Using Smc Informational Functions</title>
1286
1287 <funcsynopsis>
1288    <funcprototype>
1289       <funcdef>int <function>SmcProtocolVersion</function></funcdef>
1290       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1291   </funcprototype>
1292 </funcsynopsis>
1293
1294     <para>
1295 <function>SmcProtocolVersion</function> returns the major version of
1296 the session management protocol associated with this session.
1297     </para>
1298
1299
1300 <funcsynopsis>
1301    <funcprototype>
1302       <funcdef>int <function>SmcProtocolRevision</function></funcdef>
1303       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1304   </funcprototype>
1305 </funcsynopsis>
1306
1307     <para>
1308 <function>SmcProtocolRevision</function> returns the minor version of
1309 the session management protocol associated with this session.
1310     </para>
1311
1312 <funcsynopsis>
1313    <funcprototype>
1314       <funcdef>char *<function>SmcVendor</function></funcdef>
1315       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1316   </funcprototype>
1317 </funcsynopsis>
1318
1319     <para>
1320 <function>SmcVendor</function> returns a string that provides some
1321 identification of the owner of the session manager.  The string should
1322 be freed with a call to <function>free</function>
1323     </para>
1324
1325 <funcsynopsis>
1326    <funcprototype>
1327       <funcdef>char *<function>SmcRelease</function></funcdef>
1328       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1329   </funcprototype>
1330 </funcsynopsis>
1331
1332     <para>
1333 <function>SmcRelease</function> returns a string that provides the
1334 release number of the session manager.  The string should be freed
1335 with a call to <function>free</function>
1336     </para>
1337
1338 <funcsynopsis>
1339    <funcprototype>
1340       <funcdef>char *<function>SmcClientID</function></funcdef>
1341       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1342   </funcprototype>
1343 </funcsynopsis>
1344
1345     <para>
1346 <function>SmcClientID</function> returns a null-terminated string for
1347 the client ID associated with this connection.  This information was
1348 also returned in <function>SmcOpenConnection</function> (it is
1349 provided here for convenience).  Call <function>free</function> on
1350 this pointer when the client ID is no longer needed.
1351     </para>
1352
1353 <funcsynopsis>
1354    <funcprototype>
1355       <funcdef>IceConn <function>SmcGetIceConnection</function></funcdef>
1356       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1357   </funcprototype>
1358 </funcsynopsis>
1359
1360     <para>
1361 <function>SmcGetIceConnection</function> returns the ICE connection
1362 object associated with this session management connection object.  The
1363 ICE connection object can be used to get some additional information
1364 about the connection.  Some of the more useful functions which can be
1365 used on the IceConn are <function>IceConnectionNumber</function>,
1366 <function>IceConnectionString</function>,
1367 <function>IceLastSentSequenceNumber</function>,
1368 <function>IceLastReceivedSequenceNumber</function>,
1369 and <function>IcePing</function>. For further information, see
1370 the <citetitle pubwork='article'>Inter-Client Exchange Library</citetitle>
1371 standard.
1372     </para>
1373   </sect1>
1374
1375   <sect1 id='error_handling'>
1376     <title>Error Handling</title>
1377
1378     <para>
1379 If the client receives an unexpected protocol error from the session
1380 manager, an error handler is invoked by SMlib.  A default error
1381 handler exists that simply prints the error message
1382 to <varname>stderr</varname> and exits if the severity of the error
1383 is fatal.  The client can change this error handler by calling
1384 the <function>SmcSetErrorHandler</function> function.
1385     </para>
1386
1387 <funcsynopsis>
1388   <funcprototype>
1389       <funcdef>SmcErrorHandler <function>SmcSetErrorHandler</function></funcdef>
1390       <paramdef>SmcErrorHandler <parameter>handler</parameter></paramdef>
1391   </funcprototype>
1392 </funcsynopsis>
1393
1394     <para>
1395 The error handler.  You should pass <constant>NULL</constant> to
1396 restore the default handler.
1397     </para>
1398
1399
1400     <para>
1401 <function>SmcSetErrorHandler</function> returns the previous error handler.
1402     </para>
1403
1404     <para>
1405 The <function>SmcErrorHandler</function> has the following type:
1406     </para>
1407
1408 <funcsynopsis>
1409    <funcprototype>
1410       <funcdef>typedef void (*<function>SmcErrorHandler</function>)</funcdef>
1411       <paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
1412       <paramdef>Bool <parameter>swap</parameter></paramdef>
1413       <paramdef>int <parameter>offending_minor_opcode</parameter></paramdef>
1414       <paramdef>unsigned long <parameter>offending_sequence_num</parameter></paramdef>
1415       <paramdef>int <parameter>error_class</parameter></paramdef>
1416       <paramdef>int <parameter>severity</parameter></paramdef>
1417       <paramdef>IcePointer <parameter>values</parameter></paramdef>
1418   </funcprototype>
1419 </funcsynopsis>
1420
1421 <variablelist remap='IP'>
1422   <varlistentry>
1423     <term><parameter>smc_conn</parameter></term>
1424     <listitem><para>The session management connection object.</para></listitem>
1425   </varlistentry>
1426   <varlistentry>
1427      <term><parameter>swap</parameter></term>
1428      <listitem><para>A flag that indicates if the specified values need byte swapping.</para></listitem>
1429   </varlistentry>
1430   <varlistentry>
1431      <term><parameter>offending_minor_opcode</parameter></term>
1432      <listitem><para>The minor opcode of the offending message.</para></listitem>
1433   </varlistentry>
1434   <varlistentry>
1435      <term><parameter>offending_sequence_num</parameter></term>
1436      <listitem><para>The sequence number of the offending message.</para></listitem>
1437   </varlistentry>
1438   <varlistentry>
1439      <term><parameter>error_class</parameter></term>
1440      <listitem><para>The error class of the offending message.</para></listitem>
1441   </varlistentry>
1442   <varlistentry>
1443      <term><parameter>severity</parameter></term>
1444      <listitem><para><constant>IceCanContinue</constant>,
1445          <constant>IceFatalToProtocol</constant>, or
1446          <constant>IceFatalToConnection</constant>
1447      </para></listitem>
1448   </varlistentry>
1449   <varlistentry>
1450      <term><parameter>values</parameter></term>
1451      <listitem><para>Any additional error values specific to the minor opcode and class.</para></listitem>
1452   </varlistentry>
1453 </variablelist>
1454
1455     <para>
1456 Note that this error handler is invoked for protocol related errors.
1457 To install an error handler to be invoked when an IO error occurs, use
1458 <function>IceSetIOErrorHandler</function> For further information, see
1459 the <citetitle pubwork='article'>Inter-Client Exchange Library</citetitle>
1460 standard.
1461     </para>
1462   </sect1>
1463 </chapter>
1464
1465 <chapter id='session_management_server'>
1466   <title>Session Management Server (<acronym>Sms</acronym>) Functions</title>
1467
1468   <para>
1469 This section discusses how Session Management servers:
1470
1471     <itemizedlist mark='bullet'>
1472       <listitem><para>Initialize the library</para></listitem>
1473       <listitem><para>Register the client</para></listitem>
1474       <listitem><para>Send a &ldquo;Save Yourself&rdquo; message</para></listitem>
1475       <listitem><para>Send a &ldquo;Save Yourself Phase 2&rdquo; message</para></listitem>
1476       <listitem><para>Send an &ldquo;Interact&rdquo; message</para></listitem>
1477       <listitem><para>Send a &ldquo;Save Complete&rdquo; message</para></listitem>
1478       <listitem><para>Send a &ldquo;Die&rdquo; message</para></listitem>
1479       <listitem><para>Cancel a shutdown</para></listitem>
1480       <listitem><para>Return properties</para></listitem>
1481       <listitem><para>Ping a client</para></listitem>
1482       <listitem><para>Clean up after a client disconnects</para></listitem>
1483       <listitem><para>Use Sms informational functions</para></listitem>
1484       <listitem><para>Handle errors</para></listitem>
1485     </itemizedlist>
1486   </para>
1487
1488   <sect1 id='initializing_the_library'>
1489     <title>Initializing the Library</title>
1490
1491     <para>
1492 <function>SmsInitialize</function> is the first SMlib function that
1493 should be called by a session manager.  It provides information about
1494 the session manager and registers a callback that will be invoked each
1495 time a new client connects to the session manager.
1496     </para>
1497
1498 <funcsynopsis>
1499    <funcprototype>
1500       <funcdef>Status <function>SmsInitialize</function></funcdef>
1501       <paramdef>char *<parameter>vendor</parameter></paramdef>
1502       <paramdef>char *<parameter>release</parameter></paramdef>
1503       <paramdef>SmsNewClientProc <parameter>new_client_proc</parameter></paramdef>
1504       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
1505       <paramdef>IceHostBasedAuthProc <parameter>host_based_auth_proc</parameter></paramdef>
1506       <paramdef>int <parameter>error_length</parameter></paramdef>
1507       <paramdef>char *<parameter>error_string_ret</parameter></paramdef>
1508   </funcprototype>
1509 </funcsynopsis>
1510
1511
1512
1513 <variablelist remap='IP'>
1514   <varlistentry>
1515     <term><parameter>vendor</parameter></term>
1516     <listitem><para>A string specifying the session manager vendor.</para></listitem>
1517   </varlistentry>
1518   <varlistentry>
1519     <term><parameter>release</parameter></term>
1520     <listitem><para>A string specifying the session manager release number.</para></listitem>
1521   </varlistentry>
1522   <varlistentry>
1523     <term><parameter>new_client_proc</parameter></term>
1524     <listitem><para>Callback to be invoked each time a new client connects to the session manager.</para></listitem>
1525   </varlistentry>
1526   <varlistentry>
1527     <term><parameter>manager_data</parameter></term>
1528     <listitem><para>When the <function>SmsNewClientProc</function> callback is invoked, this pointer to manager data will be passed.</para></listitem>
1529   </varlistentry>
1530   <varlistentry>
1531     <term><parameter>host_based_auth_proc</parameter></term>
1532     <listitem><para>Host based authentication callback.</para></listitem>
1533   </varlistentry>
1534   <varlistentry>
1535     <term><parameter>error_length</parameter></term>
1536     <listitem><para>Length of the <parameter>error_string_ret</parameter> argument passed in.</para></listitem>
1537   </varlistentry>
1538   <varlistentry>
1539     <term><parameter>error_string_ret</parameter></term>
1540     <listitem><para>
1541 Returns a null-terminated error message, if any.
1542 The <parameter>error_string_ret</parameter> points to user supplied memory.
1543 No more than <parameter>error_length</parameter> bytes are used.
1544     </para></listitem>
1545   </varlistentry>
1546 </variablelist>
1547
1548     <para>
1549 After the <function>SmsInitialize</function> function is called, the
1550 session manager should call the <function>IceListenForConnections</function>
1551 function to listen for new connections.  Afterwards, each time a
1552 client connects, the session manager should
1553 call <function>IceAcceptConnection</function>
1554     </para>
1555
1556     <para>
1557 See <link linkend='authentication_of_clients'>section 9,
1558 &ldquo;Authentication of Clients,&rdquo;</link> for more details on
1559 authentication (including host based authentication).  Also see
1560 the <citetitle pubwork='article'>Inter-Client Exchange
1561 Library</citetitle> standard for further details on listening for and
1562 accepting ICE connections.
1563     </para>
1564
1565     <para>
1566 Each time a new client connects to the session manager,
1567 the <function>SmsNewClientProc</function> callback is invoked.  The
1568 session manager obtains a new opaque connection object that it should
1569 use for all future interaction with the client.  At this time, the
1570 session manager must also register a set of callbacks to respond to
1571 the different messages that the client might send.
1572     </para>
1573
1574 <funcsynopsis>
1575    <funcprototype>
1576       <funcdef>typedef Status (*<function>SmsNewClientProc</function>)</funcdef>
1577       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
1578       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
1579       <paramdef>unsigned long *<parameter>mask_ret</parameter></paramdef>
1580       <paramdef>SmsCallbacks *<parameter>callbacks_ret</parameter></paramdef>
1581       <paramdef>char **<parameter>failure_reason_ret</parameter></paramdef>
1582   </funcprototype>
1583 </funcsynopsis>
1584
1585 <variablelist remap='IP'>
1586   <varlistentry>
1587     <term><parameter>sms_conn</parameter></term>
1588     <listitem><para>A new opaque connection object.</para></listitem>
1589   </varlistentry>
1590   <varlistentry>
1591     <term><parameter>manager_data</parameter></term>
1592     <listitem><para>Manager data specified when the callback was registered.</para></listitem>
1593   </varlistentry>
1594   <varlistentry>
1595     <term><parameter>mask_ret</parameter></term>
1596     <listitem><para>On return, indicates which callbacks were set by the session manager.</para></listitem>
1597   </varlistentry>
1598   <varlistentry>
1599     <term><parameter>callbacks_ret</parameter></term>
1600     <listitem><para>On return, contains the callbacks registered by the session manager.</para></listitem>
1601   </varlistentry>
1602   <varlistentry>
1603     <term><parameter>failure_reason_ret</parameter></term>
1604     <listitem><para>Failure reason returned.</para></listitem>
1605   </varlistentry>
1606 </variablelist>
1607
1608     <para>
1609 If a failure occurs, the <function>SmsNewClientProc</function> should
1610 return a zero status as well as allocate and return a failure reason
1611 string in <parameter>failure_reason_ret</parameter>.
1612 SMlib will be responsible for freeing this memory.
1613     </para>
1614
1615     <para>
1616 The session manager must register a set of callbacks to respond to
1617 client events.  The <parameter>mask_ret</parameter> argument specifies
1618 which callbacks are set.  All of the callbacks specified in this version of
1619 SMlib are mandatory.  The <parameter>mask_ret</parameter> argument is
1620 necessary in order to maintain backwards compatibility in future versions
1621 of the library.
1622     </para>
1623
1624     <para>
1625 The following values may be ORed together to obtain a mask value:
1626
1627       <simplelist type='vert'>
1628         <member><constant>SmsRegisterClientProcMask</constant></member>
1629         <member><constant>SmsInteractRequestProcMask</constant></member>
1630         <member><constant>SmsInteractDoneProcMask</constant></member>
1631         <member><constant>SmsSaveYourselfRequestProcMask</constant></member>
1632         <member><constant>SmsSaveYourselfP2RequestProcMask</constant></member>
1633         <member><constant>SmsSaveYourselfDoneProcMask</constant></member>
1634         <member><constant>SmsCloseConnectionProcMask</constant></member>
1635         <member><constant>SmsSetPropertiesProcMask</constant></member>
1636         <member><constant>SmsDeletePropertiesProcMask</constant></member>
1637         <member><constant>SmsGetPropertiesProcMask</constant></member>
1638       </simplelist>
1639     </para>
1640
1641     <para>
1642 For each callback, the session manager can register a pointer to
1643 manager data specific to that callback.  This pointer will be passed
1644 to the callback when it is invoked by SMlib.
1645     </para>
1646
1647 <synopsis>
1648 typedef struct {
1649         struct {
1650                 SmsRegisterClientProc callback;
1651                 SmPointer manager_data;
1652         } register_client;
1653
1654         struct {
1655                 SmsInteractRequestProc callback;
1656                 SmPointer manager_data;
1657         } interact_request;
1658
1659         struct {
1660                 SmsInteractDoneProc callback;
1661                 SmPointer manager_data;
1662         } interact_done;
1663
1664         struct {
1665                 SmsSaveYourselfRequestProc callback;
1666                 SmPointer manager_data;
1667         } save_yourself_request;
1668
1669         struct {
1670                 SmsSaveYourselfPhase2RequestProc callback;
1671                 SmPointer manager_data;
1672         } save_yourself_phase2_request;
1673
1674         struct {
1675                 SmsSaveYourselfDoneProc callback;
1676                 SmPointer manager_data;
1677         } save_yourself_done;
1678
1679         struct {
1680                 SmsCloseConnectionProc callback;
1681                 SmPointer manager_data;
1682         } close_connection;
1683
1684         struct {
1685                 SmsSetPropertiesProc callback;
1686                 SmPointer manager_data;
1687         } set_properties;
1688
1689         struct {
1690                 SmsDeletePropertiesProc callback;
1691                 SmPointer manager_data;
1692         } delete_properties;
1693
1694         struct {
1695                 SmsGetPropertiesProc callback;
1696                 SmPointer manager_data;
1697         } get_properties;
1698
1699 } SmsCallbacks;
1700 </synopsis>
1701
1702     <sect2 id='the_register_client_callback'>
1703       <title>The Register Client Callback</title>
1704
1705       <para>
1706 The Register Client callback is the first callback that will be
1707 invoked after the client connects to the session manager.  Its type
1708 is <function>SmsRegisterClientProc</function>
1709       </para>
1710
1711 <funcsynopsis>
1712    <funcprototype>
1713       <funcdef>typedef Status (*<function>SmsRegisterClientProc</function>)</funcdef>
1714       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
1715       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
1716       <paramdef>char *<parameter>previous_id</parameter></paramdef>
1717   </funcprototype>
1718 </funcsynopsis>
1719
1720 <variablelist remap='IP'>
1721   <varlistentry>
1722     <term><parameter>sms_conn</parameter></term>
1723     <listitem><para>The session management connection object.</para></listitem>
1724   </varlistentry>
1725   <varlistentry>
1726     <term><parameter>manager_data</parameter></term>
1727     <listitem><para>Manager data specified when the callback was registered.</para></listitem>
1728   </varlistentry>
1729   <varlistentry>
1730     <term><parameter>previous_id</parameter></term>
1731     <listitem><para>The client ID from the previous session.</para></listitem>
1732   </varlistentry>
1733 </variablelist>
1734
1735       <para>
1736 Before any further interaction takes place with the client, the client
1737 must be registered with the session manager.
1738       </para>
1739
1740       <para>
1741 If the client is being restarted from a previous session,
1742 <parameter>previous_id</parameter> will contain a null-terminated string
1743 representing the client ID from the previous session.
1744 Call <function>free</function> on the <parameter>previous_id</parameter>
1745 pointer when it is no longer needed.  If the client is first joining the
1746 session, <parameter>previous_id</parameter> will be <constant>NULL</constant>.
1747       </para>
1748
1749       <para>
1750 If <parameter>previous_id</parameter> is invalid, the session manager should
1751 not register the client at this time.  This callback should return a status
1752 of zero, which will cause an error message to be sent to the client.  The
1753 client should re-register with previous_id set to <constant>NULL</constant>.
1754       </para>
1755
1756       <para>
1757 Otherwise, the session manager should register the client with a unique
1758 client ID by calling the <function>SmsRegisterClientReply</function>
1759 function (to be discussed shortly), and the
1760 <function>SmsRegisterClientProc</function> callback should return a
1761 status of one.
1762       </para>
1763     </sect2>
1764
1765     <sect2 id='the_interact_request_callback'>
1766       <title>The Interact Request Callback</title>
1767
1768       <para>
1769 The Interact Request callback is of
1770 type <function>SmsInteractRequestProc</function>
1771       </para>
1772
1773 <funcsynopsis>
1774    <funcprototype>
1775       <funcdef>typedef void (*<function>SmsInteractRequestProc</function>)</funcdef>
1776       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
1777       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
1778       <paramdef>int <parameter>dialog_type</parameter></paramdef>
1779   </funcprototype>
1780 </funcsynopsis>
1781
1782 <variablelist remap='IP'>
1783   <varlistentry>
1784     <term><parameter>sms_conn</parameter></term>
1785     <listitem><para>The session management connection object.</para></listitem>
1786   </varlistentry>
1787   <varlistentry>
1788     <term><parameter>manager_data</parameter></term>
1789     <listitem><para>Manager data specified when the callback was registered.</para></listitem>
1790   </varlistentry>
1791   <varlistentry>
1792     <term><parameter>dialog_type</parameter></term>
1793     <listitem><para>The type of dialog the client wishes to present to the user.</para></listitem>
1794   </varlistentry>
1795 </variablelist>
1796
1797       <para>
1798 When a client receives a &ldquo;Save Yourself&rdquo; message with an
1799 <parameter>interact_style</parameter> of
1800 <constant>SmInteractStyleErrors</constant>
1801 or <constant>SmInteractStyleAny</constant> the client may choose to
1802 interact with the user.  Because only one client can interact with the
1803 user at a time, the client must request to interact with the user.
1804 The session manager should keep a queue of all clients wishing to
1805 interact.  It should send an &ldquo;Interact&rdquo; message to one
1806 client at a time and wait for an &ldquo;Interact Done&rdquo; message
1807 before continuing with the next client.
1808       </para>
1809
1810       <para>
1811 The <parameter>dialog_type</parameter> argument specifies
1812 either <constant>SmDialogError</constant> indicating that the client
1813 wants to start an error dialog, or <constant>SmDialogNormal</constant>
1814 meaning that the client wishes to start a nonerror dialog.
1815       </para>
1816
1817       <para>
1818 If a shutdown is in progress, the user may have the option of
1819 cancelling the shutdown.  If the shutdown is cancelled (specified in
1820 the &ldquo;Interact Done&rdquo; message), the session manager should
1821 send a &ldquo;Shutdown Cancelled&rdquo; message to each client that
1822 requested to interact.
1823       </para>
1824     </sect2>
1825
1826     <sect2 id='the_interact_done_callback'>
1827       <title>The Interact Done Callback</title>
1828
1829       <para>
1830 When the client is done interacting with the user,
1831 the <function>SmsInteractDoneProc</function> callback will be invoked.
1832       </para>
1833
1834 <funcsynopsis>
1835    <funcprototype>
1836       <funcdef>typedef void (*<function>SmsInteractDoneProc</function>)</funcdef>
1837       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
1838       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
1839       <paramdef>Bool <parameter>cancel_shutdown</parameter></paramdef>
1840   </funcprototype>
1841 </funcsynopsis>
1842
1843 <variablelist remap='IP'>
1844   <varlistentry>
1845     <term><parameter>sms_conn</parameter></term>
1846     <listitem><para>The session management connection object.</para></listitem>
1847   </varlistentry>
1848   <varlistentry>
1849     <term><parameter>manager_data</parameter></term>
1850     <listitem><para>Manager data specified when the callback was registered.</para></listitem>
1851   </varlistentry>
1852   <varlistentry>
1853     <term><parameter>cancel_shutdown</parameter></term>
1854     <listitem><para>Specifies if the user requests that the entire shutdown be cancelled.</para></listitem>
1855   </varlistentry>
1856 </variablelist>
1857
1858       <para>
1859 Note that the shutdown can be cancelled only if the corresponding
1860 &ldquo;Save Yourself&rdquo; specified <constant>True</constant> for
1861 shutdown and <constant>SmInteractStyleErrors</constant>
1862 or <constant>SmInteractStyleAny</constant> for the
1863 <parameter>interact_style</parameter>.
1864       </para>
1865     </sect2>
1866
1867
1868     <sect2 id='the_save_yourself_request_callback'>
1869       <title>The Save Yourself Request Callback</title>
1870
1871       <para>
1872 The Save Yourself Request callback is of
1873 type <function>SmsSaveYourselfRequestProc</function>
1874       </para>
1875
1876 <funcsynopsis>
1877    <funcprototype>
1878       <funcdef>typedef void (*<function>SaveYourselfRequestProc</function>)</funcdef>
1879       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
1880       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
1881       <paramdef>int <parameter>save_type</parameter></paramdef>
1882       <paramdef>Bool <parameter>shutdown</parameter></paramdef>
1883       <paramdef>int <parameter>interact_style</parameter></paramdef>
1884       <paramdef>Bool <parameter>fast</parameter></paramdef>
1885       <paramdef>Bool <parameter>global</parameter></paramdef>
1886   </funcprototype>
1887 </funcsynopsis>
1888
1889 <variablelist remap='IP'>
1890   <varlistentry>
1891     <term><parameter>sms_conn</parameter></term>
1892     <listitem><para>The session management connection object.</para></listitem>
1893   </varlistentry>
1894   <varlistentry>
1895     <term><parameter>manager_data</parameter></term>
1896     <listitem><para>Manager data specified when the callback was registered.</para></listitem>
1897   </varlistentry>
1898   <varlistentry>
1899     <term><parameter>save_type</parameter></term>
1900     <listitem><para>Specifies the type of information that should be saved.</para></listitem>
1901   </varlistentry>
1902   <varlistentry>
1903     <term><parameter>shutdown</parameter></term>
1904     <listitem><para>Specifies if a shutdown is taking place.</para></listitem>
1905   </varlistentry>
1906   <varlistentry>
1907     <term><parameter>interact_style</parameter></term>
1908     <listitem><para>The type of interaction allowed with the user.</para></listitem>
1909   </varlistentry>
1910   <varlistentry>
1911     <term><parameter>fast</parameter></term>
1912     <listitem><para>If <constant>True</constant> the client should save its state as quickly as possible.</para></listitem>
1913   </varlistentry>
1914   <varlistentry>
1915     <term><parameter>global</parameter></term>
1916     <listitem><para>Controls who gets the &ldquo;Save Yourself.&rdquo;</para></listitem>
1917   </varlistentry>
1918 </variablelist>
1919
1920       <para>
1921 The Save Yourself Request prompts the session manager to initiate a
1922 checkpoint or shutdown.  For information on the
1923 <parameter>save_type</parameter>, <parameter>shutdown</parameter>,
1924 <parameter>interact_style</parameter>, and <parameter>fast</parameter>
1925 arguments, see <link linkend='sending_a_save_yourself_message'>section 6.3,
1926 &ldquo;Sending a Save Yourself Message.&rdquo;</link>
1927       </para>
1928
1929       <para>
1930 If <parameter>global</parameter> is set to <constant>True</constant> then the
1931 resulting &ldquo;Save Yourself&rdquo; should be sent to all applications.
1932 If <parameter>global</parameter> is set to <constant>False</constant> then the
1933 &ldquo;Save Yourself&rdquo; should only be sent to the client that requested it.
1934       </para>
1935     </sect2>
1936
1937     <sect2 id='the_save_yourself_phase_2_request_callback'>
1938       <title>The Save Yourself Phase 2 Request Callback</title>
1939
1940       <para>
1941 The Save Yourself Phase 2 Request callback is of
1942 type <function>SmsSaveYourselfPhase2RequestProc</function>
1943       </para>
1944
1945 <funcsynopsis>
1946    <funcprototype>
1947       <funcdef>typedef void (*<function>SmsSaveYourselfPhase2RequestProc</function>)</funcdef>
1948       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
1949       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
1950   </funcprototype>
1951 </funcsynopsis>
1952
1953 <variablelist remap='IP'>
1954   <varlistentry>
1955     <term><parameter>sms_conn</parameter></term>
1956     <listitem><para>The session management connection object.</para></listitem>
1957   </varlistentry>
1958   <varlistentry>
1959     <term><parameter>manager_data</parameter></term>
1960     <listitem><para>Manager data specified when the callback was registered.</para></listitem>
1961   </varlistentry>
1962 </variablelist>
1963
1964       <para>
1965 This request is sent by clients that manage other clients (for
1966 example, window managers, workspace managers, and so on).  Such
1967 managers must make sure that all of the clients that are being managed
1968 are in an idle state so that their state can be saved.
1969       </para>
1970     </sect2>
1971
1972     <sect2 id='the_save_yourself_done_callback'>
1973       <title>The Save Yourself Done Callback</title>
1974
1975       <para>
1976 When the client is done saving its state in response to a
1977 &ldquo;Save Yourself&rdquo; message,
1978 the <function>SmsSaveYourselfDoneProc</function> will be invoked.
1979       </para>
1980
1981 <funcsynopsis>
1982    <funcprototype>
1983       <funcdef>typedef void (*<function>SaveYourselfDoneProc</function>)</funcdef>
1984       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
1985       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
1986       <paramdef>Bool <parameter>success</parameter></paramdef>
1987   </funcprototype>
1988 </funcsynopsis>
1989
1990 <variablelist remap='IP'>
1991   <varlistentry>
1992     <term><parameter>sms_conn</parameter></term>
1993     <listitem><para>The session management connection object.</para></listitem>
1994   </varlistentry>
1995   <varlistentry>
1996     <term><parameter>manager_data</parameter></term>
1997     <listitem><para>Manager data specified when the callback was registered.</para></listitem>
1998   </varlistentry>
1999   <varlistentry>
2000     <term><parameter>success</parameter></term>
2001     <listitem><para>If <constant>True</constant> the Save Yourself operation was completed successfully.</para></listitem>
2002   </varlistentry>
2003 </variablelist>
2004
2005       <para>
2006 Before the &ldquo;Save Yourself Done&rdquo; was sent, the client must
2007 have set each required property at least once since it registered with
2008 the session manager.
2009       </para>
2010     </sect2>
2011
2012     <sect2 id='the_connection_closed_callback'>
2013       <title>The Connection Closed Callback</title>
2014
2015       <para>
2016 If the client properly terminates (that is, it
2017 calls <function>SmcCloseConnection</function>,
2018 the <function>SmsCloseConnectionProc</function> callback is invoked.
2019       </para>
2020
2021 <funcsynopsis>
2022    <funcprototype>
2023       <funcdef>typedef void (*<function>SmsCloseConnectionProc</function>)</funcdef>
2024       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2025       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
2026       <paramdef>int <parameter>count</parameter></paramdef>
2027       <paramdef>char **<parameter>reason_msgs</parameter></paramdef>
2028   </funcprototype>
2029 </funcsynopsis>
2030
2031 <variablelist remap='IP'>
2032   <varlistentry>
2033     <term><parameter>sms_conn</parameter></term>
2034     <listitem><para>The session management connection object.</para></listitem>
2035   </varlistentry>
2036 <varlistentry>
2037   <term><parameter>manager_data</parameter></term>
2038   <listitem><para>Manager data specified when the callback was registered.</para></listitem>
2039   </varlistentry>
2040   <varlistentry>
2041     <term><parameter>count</parameter></term>
2042     <listitem><para>The number of reason messages.</para></listitem>
2043   </varlistentry>
2044   <varlistentry>
2045     <term><parameter>reason_msgs</parameter></term>
2046     <listitem><para>The reasons for closing the connection.</para></listitem>
2047   </varlistentry>
2048 </variablelist>
2049
2050       <para>
2051 The <parameter>reason_msgs</parameter> argument will most likely
2052 be <constant>NULL</constant> and the <parameter>count</parameter>
2053 argument zero (0) if resignation is expected by the user.  Otherwise,
2054 it contains a list of null-terminated Compound Text strings
2055 representing the reason for termination.  The session manager should
2056 display these reason messages to the user.
2057       </para>
2058
2059       <para>
2060 Call <function>SmFreeReasons</function> to free the reason messages.
2061 For further information, see
2062 <link linkend='freeing_data'>section 8, &ldquo;Freeing Data&rdquo;</link>
2063       </para>
2064     </sect2>
2065
2066     <sect2 id='the_set_properties_callback'>
2067       <title>The Set Properties Callback</title>
2068
2069       <para>
2070 When the client sets session management properties,
2071 the <function>SmsSetPropertiesProc</function> callback will be invoked.
2072       </para>
2073
2074 <funcsynopsis>
2075    <funcprototype>
2076       <funcdef>typedef void (*<function>SmsSetPropertiesProc</function>)</funcdef>
2077       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2078       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
2079       <paramdef>int <parameter>num_props</parameter></paramdef>
2080       <paramdef>SmProp **<parameter>props</parameter></paramdef>
2081   </funcprototype>
2082 </funcsynopsis>
2083
2084 <variablelist remap='IP'>
2085   <varlistentry>
2086     <term><parameter>sms_conn</parameter></term>
2087     <listitem><para>The session management connection object.</para></listitem>
2088   </varlistentry>
2089   <varlistentry>
2090     <term><parameter>manager_data</parameter></term>
2091     <listitem><para>Manager data specified when the callback was registered.</para></listitem>
2092   </varlistentry>
2093   <varlistentry>
2094     <term><parameter>num_props</parameter></term>
2095     <listitem><para>The number of properties.</para></listitem>
2096   </varlistentry>
2097   <varlistentry>
2098     <term><parameter>props</parameter></term>
2099     <listitem><para>The list of properties to set.</para></listitem>
2100   </varlistentry>
2101 </variablelist>
2102
2103       <para>
2104 The properties are specified as an array of property pointers.  For a
2105 description of session management properties and
2106 the <structname>SmProp</structname> structure,
2107 see <link linkend='session_management_properties'>section 7,
2108 &ldquo;Session Management Properties.&rdquo;</link>
2109       </para>
2110
2111       <para>
2112 Previously set property values may be over-written.  Some properties
2113 have predefined semantics.  The session manager is required to store
2114 nonpredefined properties.
2115       </para>
2116
2117       <para>
2118 To free each property, use <function>SmFreeProperty</function>.
2119 For further information, see <link linkend='freeing_data'>section 8,
2120 &ldquo;Freeing Data&rdquo;</link> You should free the actual array of
2121 pointers with a call to <function>free</function>
2122       </para>
2123     </sect2>
2124
2125     <sect2 id='the_delete_properties_callback'>
2126       <title>The Delete Properties Callback</title>
2127
2128       <para>
2129 When the client deletes session management properties,
2130 the <function>SmsDeletePropertiesProc</function> callback will be invoked.
2131       </para>
2132
2133 <funcsynopsis>
2134    <funcprototype>
2135       <funcdef>typedef void (*<function>SmsDeletePropertiesProc</function>)</funcdef>
2136       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2137       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
2138       <paramdef>int <parameter>num_props</parameter></paramdef>
2139       <paramdef>char **<parameter>prop_names</parameter></paramdef>
2140   </funcprototype>
2141 </funcsynopsis>
2142
2143 <variablelist remap='IP'>
2144   <varlistentry>
2145     <term><parameter>sms_conn</parameter></term>
2146     <listitem><para>The session management connection object.</para></listitem>
2147   </varlistentry>
2148   <varlistentry>
2149     <term><parameter>manager_data</parameter></term>
2150     <listitem><para>Manager data specified when the callback was registered.</para></listitem>
2151   </varlistentry>
2152   <varlistentry>
2153     <term><parameter>num_props</parameter></term>
2154     <listitem><para>The number of properties.</para></listitem>
2155   </varlistentry>
2156   <varlistentry>
2157     <term><parameter>prop_names</parameter></term>
2158     <listitem><para>The list of properties to delete.</para></listitem>
2159   </varlistentry>
2160 </variablelist>
2161
2162       <para>
2163 The properties are specified as an array of strings.  For a
2164 description of session management properties and
2165 the <structname>SmProp</structname> structure,
2166 see <link linkend='session_management_properties'>section 7,
2167 &ldquo;Session Management Properties.&rdquo;</link>
2168       </para>
2169     </sect2>
2170
2171     <sect2 id='the_get_properties_callback'>
2172       <title>The Get Properties Callback</title>
2173
2174       <para>
2175 The <function>SmsGetPropertiesProc</function> callback is invoked when
2176 the client wants to retrieve properties it set.
2177       </para>
2178
2179 <funcsynopsis>
2180    <funcprototype>
2181       <funcdef>typedef void (*<function>SmsGetPropertiesProc</function>)</funcdef>
2182       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2183       <paramdef>SmPointer <parameter>manager_data</parameter></paramdef>
2184   </funcprototype>
2185 </funcsynopsis>
2186
2187 <variablelist remap='IP'>
2188   <varlistentry>
2189     <term><parameter>sms_conn</parameter></term>
2190     <listitem><para>The session management connection object.</para></listitem>
2191   </varlistentry>
2192   <varlistentry>
2193     <term><parameter>manager_data</parameter></term>
2194     <listitem><para>Manager data specified when the callback was registered.</para></listitem>
2195   </varlistentry>
2196 </variablelist>
2197
2198       <para>
2199 The session manager should respond by
2200 calling <function>SmsReturnProperties</function>.
2201 All of the properties set for this client should be returned.
2202       </para>
2203     </sect2>
2204   </sect1>
2205
2206   <sect1 id='registering_the_client'>
2207     <title>Registering the Client</title>
2208
2209     <para>
2210 To register a client (in response to
2211 a <function>SmsRegisterClientProc</function> callback),
2212 use <function>SmsRegisterClientReply</function>.
2213     </para>
2214
2215 <funcsynopsis>
2216    <funcprototype>
2217       <funcdef>Status <function>SmsRegisterClientReply</function></funcdef>
2218       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2219       <paramdef>char *<parameter>client_id</parameter></paramdef>
2220   </funcprototype>
2221 </funcsynopsis>
2222
2223 <variablelist remap='IP'>
2224   <varlistentry>
2225     <term><parameter>sms_conn</parameter></term>
2226     <listitem><para>The session management connection object.</para></listitem>
2227   </varlistentry>
2228   <varlistentry>
2229     <term><parameter>client_id</parameter></term>
2230     <listitem><para>A null-terminated string representing a unique client ID.</para></listitem>
2231   </varlistentry>
2232 </variablelist>
2233
2234     <para>
2235 The return value of <function>SmsRegisterClientReply</function> is
2236 zero for failure and a positive value for success.  Failure will occur
2237 if SMlib can not allocate memory to hold a copy of the client ID for
2238 it's own internal needs.
2239     </para>
2240
2241     <para>
2242 If a non-<constant>NULL</constant> <parameter>previous_id</parameter> was
2243 specified when the client registered itself, <parameter>client_id</parameter>
2244 should be identical to <parameter>previous_id</parameter>.
2245     </para>
2246
2247     <para>
2248 Otherwise, <parameter>client_id</parameter> should be a unique ID freshly
2249 generated by the session manager.  In addition, the session manager should
2250 send a &ldquo;Save Yourself&rdquo; message with
2251 <parameter>type</parameter> = <constant>Local</constant>,
2252 <parameter>shutdown</parameter> = <constant>False</constant>,
2253 <parameter>interact-style</parameter> = <constant>None</constant>,
2254 and <parameter>fast</parameter> = <constant>False</constant>
2255 immediately after registering the client.
2256     </para>
2257
2258     <para>
2259 Note that once a client ID has been assigned to the client, the client
2260 keeps this ID indefinitely.  If the client is terminated and
2261 restarted, it will be reassigned the same ID.  It is desirable to be
2262 able to pass client IDs around from machine to machine, from user to
2263 user, and from session manager to session manager, while retaining the
2264 identity of the client.  This, combined with the indefinite
2265 persistence of client IDs, means that client IDs need to be globally
2266 unique.
2267     </para>
2268
2269     <para>
2270 You should call the <function>SmsGenerateClientID</function> function
2271 to generate a globally unique client ID.
2272     </para>
2273
2274 <funcsynopsis>
2275    <funcprototype>
2276       <funcdef>char *<function>SmsGenerateClientID</function></funcdef>
2277       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2278   </funcprototype>
2279 </funcsynopsis>
2280
2281 <variablelist remap='IP'>
2282   <varlistentry>
2283     <term><parameter>sms_conn</parameter></term>
2284     <listitem><para>The session management connection object.</para></listitem>
2285   </varlistentry>
2286 </variablelist>
2287
2288
2289     <para>
2290 <constant>NULL</constant> will be returned if the ID could not be generated.
2291 Otherwise, the return value of the function is the client ID.
2292 It should be freed with a call to <function>free</function> when
2293 no longer needed.
2294     </para>
2295   </sect1>
2296
2297   <sect1 id='sending_a_save_yourself_message'>
2298     <title>Sending a Save Yourself Message</title>
2299
2300     <para>
2301 To send a &ldquo;Save Yourself&rdquo; to a client,
2302 use <function>SmsSaveYourself</function>.
2303     </para>
2304
2305 <funcsynopsis>
2306    <funcprototype>
2307       <funcdef>void <function>SmsSaveYourself</function></funcdef>
2308       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2309       <paramdef>int <parameter>save_type</parameter></paramdef>
2310       <paramdef>Bool <parameter>shutdown</parameter></paramdef>
2311       <paramdef>int <parameter>interact_style</parameter></paramdef>
2312       <paramdef>Bool <parameter>fast</parameter></paramdef>
2313   </funcprototype>
2314 </funcsynopsis>
2315
2316 <variablelist remap='IP'>
2317   <varlistentry>
2318     <term><parameter>sms_conn</parameter></term>
2319     <listitem><para>The session management connection object.</para></listitem>
2320   </varlistentry>
2321   <varlistentry>
2322     <term><parameter>save_type</parameter></term>
2323     <listitem><para>Specifies the type of information that should be saved.</para></listitem>
2324   </varlistentry>
2325   <varlistentry>
2326     <term><parameter>shutdown</parameter></term>
2327     <listitem><para>Specifies if a shutdown is taking place.</para></listitem>
2328   </varlistentry>
2329   <varlistentry>
2330     <term><parameter>interact_style</parameter></term>
2331     <listitem><para>The type of interaction allowed with the user.</para></listitem>
2332   </varlistentry>
2333   <varlistentry>
2334     <term><parameter>fast</parameter></term>
2335     <listitem><para>If <constant>True</constant> the client should save its state as quickly as possible.</para></listitem>
2336   </varlistentry>
2337 </variablelist>
2338
2339
2340     <para>
2341 The session manager sends a &ldquo;Save Yourself&rdquo; message to a
2342 client either to checkpoint it or just before termination so that it
2343 can save its state.  The client responds with zero or more &ldquo;Set
2344 Properties&rdquo; messages to update the properties indicating how to
2345 restart the client.  When all the properties have been set, the client
2346 sends a &ldquo;Save Yourself Done&rdquo; message.
2347     </para>
2348
2349     <para>
2350 If <parameter>interact_style</parameter>
2351 is <constant>SmInteractStyleNone</constant> the
2352 client must not interact with the user while saving state.
2353 If <parameter>interact_style</parameter>
2354 is <constant>SmInteractStyleErrors</constant> the
2355 client may interact with the user only if an error condition arises.
2356 If <parameter>interact_style</parameter>
2357 is <constant>SmInteractStyleAny</constant> then the
2358 client may interact with the user for any purpose.  The client must
2359 send an &ldquo;Interact Request&rdquo; message and wait for an
2360 &ldquo;Interact&rdquo; message from the session manager before it can
2361 interact with the user.  When the client is done interacting with the
2362 user, it should send an &ldquo;Interact Done&rdquo; message.  The
2363 &ldquo;Interact Request&rdquo; message can be sent any time after a
2364 &ldquo;Save Yourself&rdquo; and before a &ldquo;Save Yourself
2365 Done.&rdquo;
2366     </para>
2367
2368     <para>
2369 If <parameter>save_type</parameter> is <constant>SmSaveLocal</constant>
2370 the client must update the properties to reflect its current state.
2371 Specifically, it should save enough information to restore the state as
2372 seen by the user of this client.  It should not affect the state as seen
2373 by other users.
2374 If <parameter>save_type</parameter> is <constant>SmSaveGlobal</constant>
2375 the user wants the client to commit all of its data to permanent, globally
2376 accessible storage.
2377 If <parameter>save_type</parameter> is <constant>SmSaveBoth</constant>
2378 the client should do both of these (it should first commit the data to
2379 permanent storage before updating its properties).
2380     </para>
2381
2382     <para>
2383 The <parameter>shutdown</parameter> argument specifies whether the session
2384 is being shut down.  The interaction is different depending on whether or not
2385 shutdown is set.  If not shutting down, then the client can save and
2386 resume normal operation.  If shutting down, the client must save and
2387 then must prevent interaction until it receives either a
2388 &ldquo;Die&rdquo; or a &ldquo;Shutdown Cancelled,&rdquo; because
2389 anything the user does after the save will be lost.
2390     </para>
2391
2392     <para>
2393 The <parameter>fast</parameter> argument specifies that the client should
2394 save its state as quickly as possible.  For example, if the session manager
2395 knows that power is about to fail, it should set <parameter>fast</parameter>
2396 to <constant>True</constant>.
2397     </para>
2398   </sect1>
2399
2400   <sect1 id='sending_a_save_yourself_phase_2_message'>
2401     <title>Sending a Save Yourself Phase 2 Message</title>
2402
2403     <para>
2404 In order to send a &ldquo;Save Yourself Phase 2&rdquo; message to a
2405 client, use <function>SmsSaveYourselfPhase2</function>
2406     </para>
2407
2408 <funcsynopsis>
2409    <funcprototype>
2410       <funcdef>void <function>SmsSaveYourselfPhase2</function></funcdef>
2411       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2412   </funcprototype>
2413 </funcsynopsis>
2414
2415 <variablelist remap='IP'>
2416   <varlistentry>
2417     <term><parameter>sms_conn</parameter></term>
2418     <listitem><para>The session management connection object.</para></listitem>
2419   </varlistentry>
2420 </variablelist>
2421
2422     <para>
2423 The session manager sends this message to a client that has previously
2424 sent a &ldquo;Save Yourself Phase 2 Request&rdquo; message.  This
2425 message informs the client that all other clients are in a fixed state
2426 and this client can save state that is associated with other clients.
2427     </para>
2428   </sect1>
2429
2430   <sect1 id='sending_an_interact_message'>
2431     <title>Sending an Interact Message</title>
2432
2433     <para>
2434 To send an &ldquo;Interact&rdquo; message to a client,
2435 use <function>SmsInteract</function>.
2436     </para>
2437
2438 <funcsynopsis>
2439    <funcprototype>
2440       <funcdef>void <function>SmsInteract</function></funcdef>
2441       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2442   </funcprototype>
2443 </funcsynopsis>
2444
2445 <variablelist remap='IP'>
2446   <varlistentry>
2447     <term><parameter>sms_conn</parameter></term>
2448     <listitem><para>The session management connection object.</para></listitem>
2449   </varlistentry>
2450 </variablelist>
2451
2452     <para>
2453 The &ldquo;Interact&rdquo; message grants the client the privilege of
2454 interacting with the user.  When the client is done interacting with
2455 the user, it must send an &ldquo;Interact Done&rdquo; message to the
2456 session manager.
2457     </para>
2458   </sect1>
2459
2460   <sect1 id='sending_a_save_complete_message'>
2461     <title>Sending a Save Complete Message</title>
2462
2463     <para>
2464 To send a &ldquo;Save Complete&rdquo; message to a client,
2465 use <function>SmsSaveComplete</function>.
2466     </para>
2467
2468 <funcsynopsis>
2469    <funcprototype>
2470       <funcdef>void <function>SmsSaveComplete</function></funcdef>
2471       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2472   </funcprototype>
2473 </funcsynopsis>
2474
2475 <variablelist remap='IP'>
2476   <varlistentry>
2477     <term><parameter>sms_conn</parameter></term>
2478     <listitem><para>The session management connection object.</para></listitem>
2479   </varlistentry>
2480 </variablelist>
2481
2482     <para>
2483 The session manager sends this message when it is done with a
2484 checkpoint.  The client is then free to change its state.
2485     </para>
2486   </sect1>
2487
2488   <sect1 id='sending_a_die_message'>
2489     <title>Sending a Die Message</title>
2490
2491     <para>
2492 To send a &ldquo;Die&rdquo; message to a client,
2493 use <function>SmsDie</function>.
2494     </para>
2495
2496 <funcsynopsis>
2497    <funcprototype>
2498       <funcdef>void <function>SmsDie</function></funcdef>
2499       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2500   </funcprototype>
2501 </funcsynopsis>
2502
2503 <variablelist remap='IP'>
2504   <varlistentry>
2505     <term><parameter>sms_conn</parameter></term>
2506     <listitem><para>The session management connection object.</para></listitem>
2507   </varlistentry>
2508 </variablelist>
2509
2510     <para>
2511 Before the session manager terminates, it should wait for a
2512 &ldquo;Connection Closed&rdquo; message from each client that it sent
2513 a &ldquo;Die&rdquo; message to, timing out appropriately.
2514     </para>
2515   </sect1>
2516
2517   <sect1 id='cancelling_a_shutdown'>
2518     <title>Cancelling a Shutdown</title>
2519
2520     <para>
2521 To cancel a shutdown, use <function>SmsShutdownCancelled</function>.
2522     </para>
2523
2524 <funcsynopsis>
2525    <funcprototype>
2526       <funcdef>void <function>SmsShutdownCancelled</function></funcdef>
2527       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2528   </funcprototype>
2529 </funcsynopsis>
2530
2531 <variablelist remap='IP'>
2532   <varlistentry>
2533     <term><parameter>sms_conn</parameter></term>
2534     <listitem><para>The session management connection object.</para></listitem>
2535   </varlistentry>
2536 </variablelist>
2537
2538     <para>
2539 The client can now continue as if the shutdown had never happened.  If
2540 the client has not sent a &ldquo;Save Yourself Done&rdquo; message
2541 yet, it can either abort the save and send a &ldquo;Save Yourself
2542 Done&rdquo; with the success argument set to <constant>False</constant>
2543 or it can continue with the save and send a &ldquo;Save Yourself Done&rdquo;
2544 with the <parameter>success</parameter> argument set to reflect the outcome
2545 of the save.
2546     </para>
2547   </sect1>
2548 <!-- aaaaaaaaaaaaaaaaa -->
2549
2550   <sect1 id='returning_properties'>
2551     <title>Returning Properties</title>
2552
2553     <para>
2554 In response to a &ldquo;Get Properties&rdquo; message, the session
2555 manager should call <function>SmsReturnProperties</function>.
2556     </para>
2557
2558 <funcsynopsis>
2559    <funcprototype>
2560       <funcdef>void <function>SmsReturnProperties</function></funcdef>
2561       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2562       <paramdef>int <parameter>num_props</parameter></paramdef>
2563       <paramdef>SmProp **<parameter>props</parameter></paramdef>
2564   </funcprototype>
2565 </funcsynopsis>
2566
2567 <variablelist remap='IP'>
2568   <varlistentry>
2569     <term><parameter>sms_conn</parameter></term>
2570     <listitem><para>The session management connection object.</para></listitem>
2571   </varlistentry>
2572   <varlistentry>
2573     <term><parameter>num_props</parameter></term>
2574     <listitem><para>The number of properties.</para></listitem>
2575   </varlistentry>
2576   <varlistentry>
2577     <term><parameter>props</parameter></term>
2578     <listitem><para>The list of properties to return to the client.</para></listitem>
2579   </varlistentry>
2580 </variablelist>
2581
2582     <para>
2583 The properties are returned as an array of property pointers.  For a
2584 description of session management properties and
2585 the <structname>SmProp</structname> structure,
2586 see <link linkend='session_management_properties'>section 7,
2587 &ldquo;Session Management Properties.&rdquo;</link>
2588     </para>
2589   </sect1>
2590
2591   <sect1 id='pinging_a_client'>
2592     <title>Pinging a Client</title>
2593
2594     <para>
2595 To check that a client is still alive, you should use
2596 the <function>IcePing</function> function provided by the ICE library.
2597 To do so, the ICE connection must be obtained using
2598 the <function>SmsGetIceConnection</function>
2599 (see <link linkend='using_sms_informational_functions'>section 6.12,
2600 &ldquo;Using Sms Informational Functions&rdquo;</link>).
2601     </para>
2602
2603
2604 <funcsynopsis>
2605    <funcprototype>
2606       <funcdef>void <function>IcePing</function></funcdef>
2607       <paramdef>IceConn <parameter>ice_conn</parameter></paramdef>
2608       <paramdef>IcePingReplyProc <parameter>ping_reply_proc</parameter></paramdef>
2609       <paramdef>IcePointer <parameter>client_data</parameter></paramdef>
2610   </funcprototype>
2611 </funcsynopsis>
2612
2613 <variablelist remap='IP'>
2614   <varlistentry>
2615     <term><parameter>ice_conn</parameter></term>
2616     <listitem><para>A valid ICE connection object.</para></listitem>
2617   </varlistentry>
2618   <varlistentry>
2619     <term><parameter>ping_reply_proc</parameter></term>
2620     <listitem><para>The callback to invoke when the Ping reply arrives.</para></listitem>
2621   </varlistentry>
2622   <varlistentry>
2623     <term><parameter>client_data</parameter></term>
2624     <listitem><para>This pointer will be passed to the <function>IcePingReplyProc</function> callback.</para></listitem>
2625   </varlistentry>
2626 </variablelist>
2627
2628
2629     <para>
2630 When the Ping reply is ready (if ever),
2631 the <function>IcePingReplyProc</function> callback will be invoked.  A
2632 session manager should have some sort of timeout period, after which
2633 it assumes the client has unexpectedly died.
2634     </para>
2635
2636 <funcsynopsis>
2637    <funcprototype>
2638       <funcdef>typedef void (*<function>IcePingReplyProc</function>)</funcdef>
2639       <paramdef>IceConn <parameter>ice_conn</parameter></paramdef>
2640       <paramdef>IcePointer <parameter>client_data</parameter></paramdef>
2641   </funcprototype>
2642 </funcsynopsis>
2643
2644 <variablelist remap='IP'>
2645   <varlistentry>
2646     <term><parameter>ice_conn</parameter></term>
2647     <listitem><para>A valid ICE connection object.</para></listitem>
2648   </varlistentry>
2649   <varlistentry>
2650     <term><parameter>client_data</parameter></term>
2651     <listitem><para>The client data specified in the call to <function>IcePing</function></para></listitem>
2652   </varlistentry>
2653 </variablelist>
2654
2655   </sect1>
2656
2657   <sect1 id='cleaning_up_after_a_client_disconnects'>
2658     <title>Cleaning Up After a Client Disconnects</title>
2659
2660     <para>
2661 When the session manager receives a &ldquo;Connection Closed&rdquo;
2662 message or otherwise detects that the client aborted the connection,
2663 it should call the <function>SmsCleanUp</function> function in order
2664 to free up the connection object.
2665     </para>
2666
2667 <funcsynopsis>
2668    <funcprototype>
2669       <funcdef>void <function>SmsCleanUp</function></funcdef>
2670       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2671   </funcprototype>
2672 </funcsynopsis>
2673
2674 <variablelist remap='IP'>
2675   <varlistentry>
2676     <term><parameter>sms_conn</parameter></term>
2677     <listitem><para>The session management connection object.</para></listitem>
2678   </varlistentry>
2679 </variablelist>
2680
2681   </sect1>
2682
2683   <sect1 id='using_sms_informational_functions'>
2684     <title>Using Sms Informational Functions</title>
2685
2686 <funcsynopsis>
2687    <funcprototype>
2688       <funcdef>int <function>SmsProtocolVersion</function></funcdef>
2689       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2690   </funcprototype>
2691 </funcsynopsis>
2692
2693     <para>
2694 <function>SmsProtocolVersion</function> returns the major version of
2695 the session management protocol associated with this session.
2696     </para>
2697
2698 <funcsynopsis>
2699    <funcprototype>
2700       <funcdef>int <function>SmsProtocolRevision</function></funcdef>
2701       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2702   </funcprototype>
2703 </funcsynopsis>
2704
2705     <para>
2706 <function>SmsProtocolRevision</function> returns the minor version of
2707 the session management protocol associated with this session.
2708     </para>
2709
2710 <funcsynopsis>
2711    <funcprototype>
2712       <funcdef>char *<function>SmsClientID</function></funcdef>
2713       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2714   </funcprototype>
2715 </funcsynopsis>
2716
2717     <para>
2718 <function>SmsClientID</function> returns a null-terminated string for
2719 the client ID associated with this connection.  You should
2720 call <function>free</function> on this pointer when the client ID is
2721 no longer needed.
2722     </para>
2723
2724
2725     <para>
2726 To obtain the host name of a client,
2727 use <function>SmsClientHostName</function>.
2728 This host name will be needed to restart the client.
2729     </para>
2730
2731 <funcsynopsis>
2732    <funcprototype>
2733       <funcdef>char *<function>SmsClientHostName</function></funcdef>
2734       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2735   </funcprototype>
2736 </funcsynopsis>
2737
2738     <para>
2739 The string returned is of the form
2740 <parameter>protocol</parameter><literal>/</literal><parameter>hostname</parameter>,
2741 where <parameter>protocol</parameter> is one of
2742 {<literal>tcp</literal>, <literal>decnet</literal>, <literal>local</literal>}.
2743 You should call <function>free</function> on the string returned when
2744 it is no longer needed.
2745     </para>
2746
2747 <funcsynopsis>
2748    <funcprototype>
2749       <funcdef>IceConn <function>SmsGetIceConnection</function></funcdef>
2750       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2751   </funcprototype>
2752 </funcsynopsis>
2753
2754     <para>
2755 <function>SmsGetIceConnection</function> returns the ICE connection
2756 object associated with this session management connection object.  The
2757 ICE connection object can be used to get some additional information
2758 about the connection.  Some of the more useful functions which can be
2759 used on the IceConn are <function>IceConnectionNumber</function>
2760 and <function>IceLastSequenceNumber</function>.
2761 For further information, see the
2762 <citetitle pubwork='article'>Inter-Client Exchange Library</citetitle>
2763 standard.
2764     </para>
2765   </sect1>
2766
2767   <sect1 id='error_handling2'>
2768     <title>Error Handling</title>
2769
2770     <para>
2771 If the session manager receives an unexpected protocol error from a
2772 client, an error handler is invoked by SMlib.  A default error handler
2773 exists which simply prints the error message (it does not exit).  The
2774 session manager can change this error handler by
2775 calling <function>SmsSetErrorHandler</function>.
2776     </para>
2777
2778 <funcsynopsis>
2779    <funcprototype>
2780       <funcdef>SmsErrorHandler <function>SmsSetErrorHandler</function></funcdef>
2781       <paramdef>SmsErrorHandler <parameter>handler</parameter></paramdef>
2782   </funcprototype>
2783 </funcsynopsis>
2784
2785     <para>
2786 The error handler.  You should pass <constant>NULL</constant>
2787 to restore the default handler.
2788     </para>
2789
2790     <para>
2791 <function>SmsSetErrorHandler</function> returns the previous error handler.
2792 The <function>SmsErrorHandler</function> has the following type:
2793     </para>
2794
2795 <funcsynopsis>
2796    <funcprototype>
2797       <funcdef>typedef void (*<function>SmsErrorHandler</function>)</funcdef>
2798       <paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
2799       <paramdef>Bool <parameter>swap</parameter></paramdef>
2800       <paramdef>int <parameter>offending_minor_opcode</parameter></paramdef>
2801       <paramdef>unsigned long <parameter>offending_sequence_num</parameter></paramdef>
2802       <paramdef>int <parameter>error_class</parameter></paramdef>
2803       <paramdef>int <parameter>severity</parameter></paramdef>
2804       <paramdef>IcePointer <parameter>values</parameter></paramdef>
2805   </funcprototype>
2806 </funcsynopsis>
2807
2808 <variablelist remap='IP'>
2809   <varlistentry>
2810     <term><parameter>sms_conn</parameter></term>
2811     <listitem><para>The session management connection object.</para></listitem>
2812   </varlistentry>
2813   <varlistentry>
2814     <term><parameter>swap</parameter></term>
2815     <listitem><para>A flag which indicates if the specified values need byte swapping.</para></listitem>
2816   </varlistentry>
2817   <varlistentry>
2818     <term><parameter>offending_minor_opcode</parameter></term>
2819     <listitem><para>The minor opcode of the offending message.</para></listitem>
2820   </varlistentry>
2821   <varlistentry>
2822     <term><parameter>offending_sequence_num</parameter></term>
2823     <listitem><para>The sequence number of the offending message.</para></listitem>
2824   </varlistentry>
2825   <varlistentry>
2826     <term><parameter>error_class</parameter></term>
2827     <listitem><para>The error class of the offending message.</para></listitem>
2828   </varlistentry>
2829   <varlistentry>
2830     <term><parameter>severity</parameter></term>
2831     <listitem><para>
2832         <constant>IceCanContinue</constant>,
2833         <constant>IceFatalToProtocol</constant>, or
2834         <constant>IceFatalToConnection</constant>
2835     </para></listitem>
2836   </varlistentry>
2837   <varlistentry>
2838     <term><parameter>values</parameter></term>
2839     <listitem><para>Any additional error values specific to the minor opcode and class.</para></listitem>
2840   </varlistentry>
2841 </variablelist>
2842
2843     <para>
2844 Note that this error handler is invoked for protocol related errors.
2845 To install an error handler to be invoked when an IO error occurs,
2846 use <function>IceSetIOErrorHandler</function>.
2847 For further information, see the
2848 <citetitle pubwork='article'>Inter-Client Exchange Library</citetitle>
2849 standard.
2850     </para>
2851   </sect1>
2852 </chapter>
2853
2854 <chapter id='session_management_properties'>
2855   <title>Session Management Properties</title>
2856
2857   <para>
2858 Each property is defined by the <structname>SmProp</structname> structure:
2859
2860 <synopsis>
2861 typedef struct {
2862         char *name;     /* name of property */
2863         char *type;     /* type of property */
2864         int num_vals;   /* number of values */
2865         SmPropValue *vals;      /* the list of values */
2866 } SmProp;
2867
2868 typedef struct {
2869         int length;     /* the length of the value */
2870         SmPointer value;        /* the value */
2871 } SmPropValue;
2872 </synopsis>
2873   </para>
2874
2875   <para>
2876 The X Session Management Protocol defines a list of predefined
2877 properties, several of which are required to be set by the client.
2878 The following table specifies the predefined properties and indicates
2879 which ones are required.  Each property has a type associated with it.
2880   </para>
2881
2882   <para>
2883 A type of <type>SmCARD8</type> indicates that there is a single 1-byte value.
2884 A type of <type>SmARRAY8</type> indicates that there is a single array of bytes.
2885 A type of <type>SmLISTofARRAY8</type> indicates that there is a list of array of
2886 bytes.
2887   </para>
2888
2889 <informaltable pgwide='0' frame='none'>
2890   <tgroup cols='4' align='center'>
2891     <colspec colname='c1'/>
2892     <colspec colname='c2'/>
2893     <colspec colname='c3'/>
2894     <colspec colname='c4'/>
2895     <thead>
2896       <row>
2897         <entry align='left'>Name</entry>
2898         <entry align='left'>Type</entry>
2899         <entry align='left'><acronym>POSIX</acronym> Type</entry>
2900         <entry align='center'>Required</entry>
2901       </row>
2902     </thead>
2903     <tbody>
2904       <row>
2905         <entry align='left'><property>SmCloneCommand</property></entry>
2906         <entry align='left'>OS-specific</entry>
2907         <entry align='left'><type>SmLISTofARRAY8</type></entry>
2908         <entry align='center'>Yes</entry>
2909       </row>
2910       <row>
2911         <entry align='left'><property>SmCurrentDirectory</property></entry>
2912         <entry align='left'>OS-specific</entry>
2913         <entry align='left'><type>SmARRAY8</type></entry>
2914         <entry align='center'>No</entry>
2915       </row>
2916       <row>
2917         <entry align='left'><property>SmDiscardCommand</property></entry>
2918         <entry align='left'>OS-specific</entry>
2919         <entry align='left'><type>SmLISTofARRAY8</type></entry>
2920         <entry align='center'>No*</entry>
2921       </row>
2922       <row>
2923         <entry align='left'><property>SmEnvironment</property></entry>
2924         <entry align='left'>OS-specific</entry>
2925         <entry align='left'><type>SmLISTofARRAY8</type></entry>
2926         <entry align='center'>No</entry>
2927       </row>
2928       <row>
2929         <entry align='left'><property>SmProcessID</property></entry>
2930         <entry align='left'>OS-specific</entry>
2931         <entry align='left'><type>SmARRAY8</type></entry>
2932         <entry align='center'>No</entry>
2933       </row>
2934       <row>
2935         <entry align='left'><property>SmProgram</property></entry>
2936         <entry align='left'>OS-specific</entry>
2937         <entry align='left'><type>SmARRAY8</type></entry>
2938         <entry align='center'>Yes</entry>
2939       </row>
2940       <row>
2941         <entry align='left'><property>SmRestartCommand</property></entry>
2942         <entry align='left'>OS-specific</entry>
2943         <entry align='left'><type>SmLISTofARRAY8</type></entry>
2944         <entry align='center'>Yes</entry>
2945       </row>
2946       <row>
2947         <entry align='left'><property>SmResignCommand</property></entry>
2948         <entry align='left'>OS-specific</entry>
2949         <entry align='left'><type>SmLISTofARRAY8</type></entry>
2950         <entry align='center'>No</entry>
2951       </row>
2952       <row>
2953         <entry align='left'><property>SmRestartStyleHint</property></entry>
2954         <entry align='left'><type>SmCARD8</type></entry>
2955         <entry align='left'><type>SmCARD8</type></entry>
2956         <entry align='center'>No</entry>
2957       </row>
2958       <row>
2959         <entry align='left'><property>SmShutdownCommand</property></entry>
2960         <entry align='left'>OS-specific</entry>
2961         <entry align='left'><type>SmLISTofARRAY8</type></entry>
2962         <entry align='center'>No</entry>
2963       </row>
2964       <row>
2965         <entry align='left'><property>SmUserID</property></entry>
2966         <entry align='left'><type>SmARRAY8</type></entry>
2967         <entry align='left'><type>SmARRAY8</type></entry>
2968         <entry align='center'>Yes</entry>
2969       </row>
2970     </tbody>
2971   </tgroup>
2972 </informaltable>
2973
2974   <para>
2975 * Required if any state is stored in an external repository (for
2976 example, state file).
2977   </para>
2978
2979   <itemizedlist mark='bullet'>
2980     <listitem><para><property>SmCloneCommand</property></para>
2981       <para>
2982 This is like the <property>SmRestartCommand</property>, except it restarts a
2983 copy of the application.  The only difference is that the application does not
2984 supply its client ID at register time.  On <acronym>POSIX</acronym> systems,
2985 this should be of type <type>SmLISTofARRAY8</type>.
2986     </para></listitem>
2987     <listitem><para><property>SmCurrentDirectory</property></para>
2988       <para>
2989 On <acronym>POSIX</acronym>-based systems, this specifies the value of the
2990 current directory that needs to be set up prior to starting the
2991 <property>SmProgram</property> and should of type <type>SmARRAY8</type>.
2992     </para></listitem>
2993     <listitem><para><property>SmDiscardCommand</property></para>
2994       <para>
2995 The discard command contains a command that when delivered to the host
2996 that the client is running on (determined from the connection), will
2997 cause it to discard any information about the current state.  If this
2998 command is not specified, the Session Manager will assume that all of
2999 the client's state is encoded in the <property>SmRestartCommand</property>.
3000 On <acronym>POSIX</acronym> systems, the type should be
3001 <type>SmLISTofARRAY8</type>.
3002     </para></listitem>
3003     <listitem><para><property>SmEnvironment</property></para>
3004       <para>
3005 On <acronym>POSIX</acronym> based systems, this will be of type
3006 <type>SmLISTofARRAY8</type>, where the <type>ARRAY8</type>s alternate between
3007 environment variable name and environment variable value.
3008     </para></listitem>
3009     <listitem><para><property>SmProcessID</property></para>
3010       <para>
3011 This specifies an OS-specific identifier for the process.
3012 On <acronym>POSIX</acronym> systems, this should contain the return value
3013 of <function>getpid</function> turned into a Latin-1 (decimal) string.
3014     </para></listitem>
3015     <listitem><para><property>SmProgram</property></para>
3016       <para>
3017 This is the name of the program that is running.  On <acronym>POSIX</acronym>
3018 systems, this should be first parameter passed to <function>execve</function>
3019 and should be of type <type>SmARRAY8</type>.
3020     </para></listitem>
3021     <listitem><para><property>SmRestartCommand</property></para>
3022       <para>
3023 The restart command contains a command that, when delivered to the
3024 host that the client is running on (determined from the connection),
3025 will cause the client to restart in its current state.
3026 On <acronym>POSIX</acronym>-based systems, this is of
3027 type <type>SmLISTofARRAY8</type>, and each of the elements in
3028 the array represents an element in the <varname>argv</varname>
3029 array.  This restart command should ensure that the client restarts
3030 with the specified client-ID.
3031     </para></listitem>
3032     <listitem><para><property>SmResignCommand</property></para>
3033       <para>
3034 A client that sets the <property>SmRestartStyleHint</property>
3035 to <constant>SmRestartAnyway</constant> uses this property to specify a
3036 command that undoes the effect of the client and removes any saved state.
3037 As an example, consider a user that runs <command>xmodmap</command> which
3038 registers with the Session Manager,
3039 sets <property>SmRestartStyleHint</property>
3040 to <constant>SmRestartAnyway</constant>, and then
3041 terminates.  To allow the Session Manager (at the user's request) to
3042 undo this, <command>xmodmap</command> would register a
3043 <property>SmResignCommand</property> that undoes the effects of
3044 the <command>xmodmap</command>.
3045     </para></listitem>
3046     <listitem><para><property>SmRestartStyleHint</property></para>
3047       <para>
3048 If the <property>SmRestartStyleHint</property> is present, it will contain the
3049 style of restarting the client prefers.  If this style is not specified,
3050 <constant>SmRestartIfRunning</constant> is assumed.
3051 The possible values are as follows:
3052
3053 <informaltable pgwide='0' frame='none'>
3054   <tgroup cols='2' align='center'>
3055     <colspec colname='c1'/>
3056     <colspec colname='c2'/>
3057     <thead>
3058       <row>
3059         <entry align='left'>Name</entry>
3060         <entry align='right'>Value</entry>
3061       </row>
3062     </thead>
3063     <tbody>
3064       <row>
3065         <entry align='left'><constant>SmRestartIfRunning</constant></entry>
3066         <entry align='right'>0</entry>
3067       </row>
3068       <row>
3069         <entry align='left'><constant>SmRestartAnyway</constant></entry>
3070         <entry align='right'>1</entry>
3071       </row>
3072       <row>
3073         <entry align='left'><constant>SmRestartImmediately</constant></entry>
3074         <entry align='right'>2</entry>
3075       </row>
3076       <row>
3077         <entry align='left'><constant>SmRestartNever</constant></entry>
3078         <entry align='right'>3</entry>
3079       </row>
3080     </tbody>
3081   </tgroup>
3082 </informaltable>
3083       </para>
3084
3085       <para>
3086 The <constant>SmRestartIfRunning</constant> style is used in the usual case.
3087 The client should be restarted in the next session if it was running at
3088 the end of the current session.
3089       </para>
3090
3091       <para>
3092 The <constant>SmRestartAnyway</constant> style is used to tell the Session
3093 Manager that the application should be restarted in the next session even if
3094 it exits before the current session is terminated.  It should be noted that
3095 this is only a hint and the Session Manager will follow the policies
3096 specified by its users in determining what applications to restart.
3097       </para>
3098
3099       <para>
3100 A client that uses <constant>SmRestartAnyway</constant> should also set the
3101 <property>SmResignCommand</property> and <property>SmShutdownCommand</property>
3102 properties to commands that undo the state of the client after it exits.
3103       </para>
3104
3105       <para>
3106 The SmRestartImmediately style is like SmRestartAnyway, but, in addition, the client is meant to run continuously.  If the client exits, the Session Manager should try to restart it in the current session.
3107       </para>
3108
3109       <para>
3110 <constant>SmRestartNever</constant> style specifies that the client does not
3111 wish to be restarted in the next session.
3112       </para>
3113     </listitem>
3114     <listitem><para><property>SmShutdownCommand</property></para>
3115       <para>
3116 This command is executed at shutdown time to clean up after a client
3117 that is no longer running but retained its state by setting
3118 <property>SmRestartStyleHint</property> to
3119 <constant>SmRestartAnyway</constant>.  The client must not remove any saved
3120 state as the client is still part of the session.  As an
3121 example, consider a client that turns on a camera at start up time.
3122 This client then exits.  At session shutdown, the user wants the
3123 camera turned off.  This client would set the
3124 <property>SmRestartStyleHint</property> to
3125 <constant>SmRestartAnyway</constant> and would register
3126 a <property>SmShutdownCommand</property> that would turn off the camera.
3127     </para></listitem>
3128     <listitem><para><property>SmUserID</property></para>
3129       <para>
3130 Specifies the user ID.  On <acronym>POSIX</acronym>-based systems, this will
3131 contain the user's name (the <structfield>pw_name</structfield> member of
3132 <structname>struct passwd</structname>).
3133     </para></listitem>
3134   </itemizedlist>
3135 </chapter>
3136
3137 <chapter id='freeing_data'>
3138   <title>Freeing Data</title>
3139
3140   <para>
3141 To free an individual property, use <function>SmFreeProperty</function>
3142   </para>
3143
3144 <funcsynopsis>
3145    <funcprototype>
3146       <funcdef>void <function>SmFreeProperty</function></funcdef>
3147       <paramdef>SmProp *<parameter>prop</parameter></paramdef>
3148   </funcprototype>
3149 </funcsynopsis>
3150
3151 <variablelist remap='IP'>
3152   <varlistentry>
3153     <term><parameter>prop</parameter></term>
3154     <listitem><para>The property to free.</para></listitem>
3155   </varlistentry>
3156 </variablelist>
3157
3158   <para>
3159 To free the reason strings from
3160 the <function>SmsCloseConnectionProc</function> callback,
3161 use <function>SmFreeReasons</function>
3162   </para>
3163
3164 <funcsynopsis>
3165    <funcprototype>
3166       <funcdef>void <function>SmFreeReasons</function></funcdef>
3167       <paramdef>int <parameter>count</parameter></paramdef>
3168       <paramdef>char **<parameter>reasons</parameter></paramdef>
3169   </funcprototype>
3170 </funcsynopsis>
3171
3172 <variablelist remap='IP'>
3173   <varlistentry>
3174     <term><parameter>count</parameter></term>
3175     <listitem><para>The number of reason strings.</para></listitem>
3176   </varlistentry>
3177   <varlistentry>
3178     <term><parameter>reasons</parameter></term>
3179     <listitem><para>The list of reason strings to free.</para></listitem>
3180   </varlistentry>
3181 </variablelist>
3182 </chapter>
3183
3184 <chapter id='authentication_of_clients'>
3185   <title>Authentication of Clients</title>
3186
3187   <para>
3188 As stated earlier, the session management protocol is layered on top
3189 of ICE.  Authentication occurs at two levels in the ICE protocol:
3190
3191 <itemizedlist mark='bullet'>
3192     <listitem><para>The first is when an ICE connection is opened.</para></listitem>
3193     <listitem><para>The second is when a Protocol Setup occurs on an ICE connection.</para></listitem>
3194 </itemizedlist>
3195   </para>
3196
3197   <para>
3198 The authentication methods that are available are
3199 implementation-dependent (that is., dependent on the ICElib and SMlib
3200 implementations in use).  For further information, see the
3201 <citetitle pubwork='article'>Inter-Client Exchange Library</citetitle>
3202 standard.
3203   </para>
3204 </chapter>
3205
3206 <chapter id='working_in_a_multithreaded_environment'>
3207   <title>Working in a Multi-Threaded Environment</title>
3208
3209   <para>
3210 To declare that multiple threads in an application will be using SMlib
3211 (or any other library layered on top of ICElib), you should
3212 call <function>IceInitThreads</function>.
3213 For further information, see the
3214 <citetitle pubwork='article'>Inter-Client Exchange Library</citetitle>
3215 standard.
3216   </para>
3217 </chapter>
3218
3219 <chapter id='acknowledgements'>
3220   <title>Acknowledgements</title>
3221
3222   <para>
3223 Thanks to the following people for their participation in the
3224 X Session Management design: Jordan Brown, Ellis Cohen, Donna Converse,
3225 Stephen Gildea, Vania Joloboff, Stuart Marks, Bob Scheifler, Ralph Swick,
3226 and Mike Wexler.
3227   </para>
3228
3229 </chapter>
3230 </book>