doc/SMlib.xml

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