SMlib.xml revision 3c15da26
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> 30Permission is hereby granted, free of charge, to any person obtaining 31a copy of this software and associated documentation files (the 32“Software”), to deal in the Software without restriction, 33including without limitation the rights to use, copy, modify, merge, 34publish, distribute, sublicense, and/or sell copies of the Software, 35and to permit persons to whom the Software is furnished to do so, 36subject to the following conditions: 37 </para> 38 39 <para> 40The above copyright notice and this permission notice shall be 41included in all copies or substantial portions of the Software. 42 </para> 43 44 <para> 45THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF 46ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 47WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE 48AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR 49ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 50CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 51WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 52 </para> 53 54 <para> 55Except as contained in this notice, the name of the X Consortium shall 56not be used in advertising or otherwise to promote the sale, use or 57other dealings in this Software without prior written authorization 58from the X Consortium. 59 </para> 60 61 <para> 62X Window System is a trademark of The Open Group. 63 </para> 64 </legalnotice> 65 66</bookinfo> 67 68<chapter id='Overview_of_Session_Management'> 69 <title>Overview of Session Management</title> 70 71 <abstract> 72 <para> 73The purpose of the X Session Management Protocol (<acronym>XSMP</acronym>) 74is to provide a uniform mechanism for users to save and restore their 75sessions. A <firstterm>session</firstterm> is a group of clients, 76each of which has a particular state. The session is controlled by a 77network service called the <firstterm>session manager</firstterm>. 78The session manager issues commands to its clients on behalf of the 79user. These commands may cause clients to save their state or to 80terminate. It is expected that the client will save its state in such 81a way that the client can be restarted at a later time and resume its 82operation as if it had never been terminated. A client's state might 83include information about the file currently being edited, the current 84position of the insertion point within the file, or the start of an 85uncommitted transaction. The means by which clients are restarted is 86unspecified by this protocol. 87 </para> 88 89 <para> 90For purposes of this protocol, a <firstterm>client</firstterm> of the 91session manager is defined as a connection to the session manager. A 92client is typically, though not necessarily, a process running an 93application program connected to an X display. However, a client may 94be connected to more than one X display or not be connected to any X 95displays 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> 104The Session Management Library (<abbrev>SMlib</abbrev>) is a low-level 105"C" language interface to XSMP. It is expected that higher level 106toolkits, such as Xt, will hide many of the details of session 107management from clients. Higher level toolkits might also be developed 108for 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> 121Some applications will use both sets of functions and act as 122<firstterm>nested session managers</firstterm>. That is, they will be 123both a session manager and a client of another session. An example is 124a mail program that could start a text editor for editing the text of 125a mail message. The mail program is part of a regular session and, at 126the same time, is also acting as a session manager to the editor. 127 </para> 128 129 <para> 130Clients initialize by connecting to the session manager and obtaining 131a <firstterm>client-ID</firstterm> that uniquely identifies them in 132the session. The session manager maintains a list of properties for 133each client in the session. These properties describe the client's 134environment and, most importantly, describe how the client can be 135restarted (via an <property>SmRestartCommand</property>). Clients are 136expected to save their state in such a way as to allow multiple 137instantiations of themselves to be managed independently. For 138example, clients may use their client-ID as part of a filename in 139which to store the state for a particular instantiation. The 140client-ID should be saved as part of the <property>SmRestartCommand</property> 141so that the client will retain the same ID after it is restarted. 142 </para> 143 144 <para> 145Once the client initializes itself with the session manager, it must 146be ready to respond to messages from the session manager. For 147example, it might be asked to save its state or to terminate. In the 148case of a shutdown, the session manager might give each client a 149chance 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> 157The X Session Management Protocol is layered on top of the 158Inter-Client Exchange (<acronym>ICE</acronym>) Protocol. The ICE 159protocol is designed to multiplex several protocols over a single 160connection. As a result, working with SMlib requires a little 161knowledge of how the ICE library works. 162 </para> 163 164 <para> 165The ICE library utilizes callbacks to process messages. When a client 166detects that there is data to read on an ICE connection, it should 167call 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 169and look at the major opcode in order to determine which protocol the 170message was intended for. The appropriate protocol library will then 171be triggered to unpack the message and hand it off to the client via a 172callback. 173 </para> 174 175 <para> 176The main point to be aware of is that an application using SMlib must 177have some code that detects when there is data to read on an ICE 178connection. This can be done via a <function>select</function> call 179on the file descriptor for the ICE connection, but more 180typically, <function>XtAppAddInput</function> will be used to register 181a callback that will invoke <olink targetdoc='ICElib' targetptr='IceProcessMessages'><function>IceProcessMessages</function></olink> 182each time there is data to read on the ICE connection. 183 </para> 184 185 <para> 186To further complicate things, knowing which file descriptors to 187call <function>select</function> on requires an understanding of how 188ICE connections are created. On the client side, a call must be made 189to <xref linkend='SmcOpenConnection' xrefstyle='select: title'/> in order to open a connection 190with a session manager. <xref linkend='SmcOpenConnection' xrefstyle='select: title'/> will 191internally makea call into <olink targetdoc='ICElib' targetptr='IceOpenConnection'><function>IceOpenConnection</function></olink> 192which will, in turn, determine if an ICE connection already exists 193between the client and session manager. Most likely, a connection 194will not already exist and a new ICE connection will be created. The 195main point to be aware of is that, on the client side, it is not 196obvious when ICE connections get created or destroyed, because 197connections are shared when possible. To deal with this, the ICE 198library lets the application register watch procedures that will be 199invoked each time an ICE connection is opened or closed. These watch 200procedures could be used to add or remove ICE file descriptors from 201the list of descriptors to call <function>select</function> on. 202 </para> 203 204 <para> 205On the session manager side, things work a bit differently. The 206session manager has complete control over the creation of ICE 207connections. The session manager has to first 208call <olink targetdoc='ICElib' targetptr='IceListenForConnections'><function>IceListenForConnections</function></olink> in order to start 209listening for connections from clients. Once a connection attempt is 210detected, <olink targetdoc='ICElib' targetptr='IceAcceptConnection'><function>IceAcceptConnection</function></olink> must be called, and 211the session manager can simply add the new ICE file descriptor to the 212list of descriptors to call <function>select</function> on. 213 214 </para> 215 216 <para> 217For further information on the library functions related to ICE connections, 218see the <citetitle pubwork='article'>Inter-Client Exchange Library</citetitle> 219standard. 220 </para> 221</chapter> 222 223<chapter id='Header_Files_and_Library_Name'> 224<title>Header Files and Library Name</title> 225 226 <para> 227Applications (both session managers and clients) should include the 228header file <<filename class='headerfile'>X11/SM/SMlib.h</filename>>. 229This header file defines all of the SMlib data structures and function 230prototypes. <filename class='headerfile'>SMlib.h</filename> includes the 231header file <<filename class='headerfile'>X11/SM/SM.h</filename>>, 232which defines all of the SMlib constants. 233 </para> 234 235 <para> 236Because SMlib is dependent on ICE, applications should link against 237SMlib 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 “Save Yourself”</para></listitem> 254 <listitem><para>Request a “Save Yourself Phase 2”</para></listitem> 255 <listitem><para>Complete a “Save Yourself”</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> 265To open a connection with a session manager, 266use <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> 293A pointer to an opaque object or <constant>NULL</constant>. Used to determine 294if 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> 301The 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> 307The highest minor version of the XSMP the application supports (for 308the 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> 318The callbacks to register. These callbacks are used to respond to 319messages 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> 337Returns a null-terminated error message, if any. 338The <parameter>error_string_ret</parameter> argument points to user supplied 339memory. No more than <parameter>error_length</parameter> bytes are used. 340 </para></listitem> 341 </varlistentry> 342 </variablelist> 343 344 <para> 345The <parameter>network_ids_list</parameter> argument is a 346null-terminated string containing a list of network IDs for the session 347manager, separated by commas. If <parameter>network_ids_list</parameter> 348is <constant>NULL</constant>, the value of 349the <envar>SESSION_MANAGER</envar> environment variable will be used. 350Each 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><hostname></parameter><literal>:</literal><parameter><portnumber></parameter></entry> 360 <entry>or</entry> 361 </row> 362 <row> 363 <entry><literal>decnet/</literal><parameter><hostname></parameter><literal>::</literal><parameter><objname></parameter></entry> 364 <entry>or</entry> 365 </row> 366 <row> 367 <entry><literal>local/</literal><parameter><hostname></parameter><literal>:</literal><parameter><path></parameter></entry> 368 <entry></entry> 369 </row> 370 </tbody> 371 </tgroup> 372</informaltable> 373 </para> 374 375 <para> 376An attempt will be made to use the first network ID. If that fails, 377an attempt will be made using the second network ID, and so on. 378 </para> 379 380 <para> 381After the connection is established, <xref linkend='SmcOpenConnection' xrefstyle='select: title'/> 382registers the client with the session manager. If the client is being 383restarted from a previous session, <parameter>previous_id</parameter> 384should contain a null terminated string representing the client ID from the 385previous session. If the client is first joining the session, 386<parameter>previous_id</parameter> should be set to <constant>NULL</constant>. 387If <parameter>previous_id</parameter> is specified but is determined 388to be invalid by the session manager, SMlib will re-register the 389client with <parameter>previous_id</parameter> set to <constant>NULL</constant>. 390 </para> 391 392 <para> 393If <xref linkend='SmcOpenConnection' xrefstyle='select: title'/> succeeds, it returns an 394opaque connection pointer of type <function>SmcConn</function> and the 395<parameter>client_id_ret</parameter> argument contains the client ID to be 396used for this session. The <parameter>client_id_ret</parameter> should be 397freed with a call to <function>free</function> when no longer needed. On 398failure, <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> 404Note that SMlib uses the ICE protocol to establish a connection with 405the session manager. If an ICE connection already exists between the 406client and session manager, it might be possible for the same ICE 407connection to be used for session management. 408 </para> 409 410 <para id='context_sharing'> 411The context argument indicates how willing the client is to share the 412ICE connection with other protocols. If context is <constant>NULL</constant>, 413then 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 415opened ICE connection that has a different non-<constant>NULL</constant> 416context associated with it. 417 </para> 418 419 <para> 420As previously discussed 421(<link linkend='Understanding_SMlibs_Dependence_on_ICE'>section 3, 422“Understanding SMlib's Dependence on ICE”</link>), the 423client will have to keep track of when ICE connections are created or 424destroyed (using <olink targetdoc='ICElib' targetptr='IceAddConnectionWatch'><function>IceAddConnectionWatch</function></olink> 425and <olink targetdoc='ICElib' targetptr='IceRemoveConnectionWatch'><function>IceRemoveConnectionWatch</function></olink> and will have to 426call <olink targetdoc='ICElib' targetptr='IceProcessMessages'><function>IceProcessMessages</function></olink> each time 427a <function>select</function> shows that there is data to read on an 428ICE connection. For further information, see the 429<citetitle pubwork='article'>Inter-Client Exchange Library</citetitle> 430standard. 431 </para> 432 433 <para> 434The callbacks argument contains a set of callbacks used to respond to 435session manager events. The mask argument specifies which callbacks 436are set. All of the callbacks specified in this version of SMlib are 437mandatory. The mask argument is necessary in order to maintain 438backwards compatibility in future versions of the library. 439 </para> 440 441 <para> 442The 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> 454For each callback, the client can register a pointer to client data. 455When SMlib invokes the callback, it will pass the client data pointer. 456 </para> 457 458<!-- .ne 4 IGNORED --> 459 460<synopsis> 461typedef 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> 490The 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> 533The session manager sends a “Save Yourself” message to a 534client either to checkpoint it or just before termination so that it 535can save its state. The client responds with zero or more calls 536to <xref linkend='SmcSetProperties' xrefstyle='select: title'/> to update the properties 537indicating how to restart the client. When all the properties have 538been set, the client calls <xref linkend='SmcSaveYourselfDone' xrefstyle='select: title'/> 539 </para> 540 541 <para> 542If <parameter>interact_style</parameter> is 543<constant>SmInteractStyleNone</constant> the 544client must not interact with the user while saving state. 545If <parameter>interact_style</parameter> is 546<constant>SmInteractStyleErrors</constant> the 547client may interact with the user only if an error condition arises. 548If <parameter>interact_style</parameter> is 549<constant>SmInteractStyleAny</constant> then the 550client may interact with the user for any purpose. Because only one 551client can interact with the user at a time, the client must 552call <xref linkend='SmcInteractRequest' xrefstyle='select: title'/> and wait for an 553“Interact” message from the session manager. When the 554client is done interacting with the user, it 555calls <xref linkend='SmcInteractDone' xrefstyle='select: title'/> The client may only 556call <xref linkend='SmcInteractRequest' xrefstyle='select: title'/> after it receives a 557“Save Yourself” message and before it 558calls <xref linkend='SmcSaveYourselfDone' xrefstyle='select: title'/> 559 </para> 560 561 <para> 562If <parameter>save_type</parameter> is <constant>SmSaveLocal</constant> the 563client must update the properties to reflect its current state. Specifically, 564it should save enough information to restore the state as seen by the 565user of this client. It should not affect the state as seen by other users. 566If <parameter>save_type</parameter> is <constant>SmSaveGlobal</constant> 567the user wants the client to commit all of its data to permanent, globally 568accessible storage. 569If <parameter>save_type</parameter> is <constant>SmSaveBoth</constant> 570the client should do both of these (it should first commit the data to 571permanent storage before updating its properties). 572 </para> 573 574 <para> 575Some examples are as follows: 576 577 <itemizedlist mark='bullet'> 578 <listitem><para> 579If a word processor were sent a “Save Yourself” with a 580type of <constant>SmSaveLocal</constant> it could create a temporary 581file that included the current contents of the file, the location of 582the cursor, and other aspects of the current editing session. It 583would then update its <property>SmRestartCommand</property> property with 584enough information to find this temporary file. 585 </para></listitem> 586 <listitem><para> 587If a word processor were sent a “Save Yourself” with a 588type of <constant>SmSaveGlobal</constant> it would simply save the 589currently edited file. 590 </para></listitem> 591 <listitem><para> 592If a word processor were sent a “Save Yourself” with a 593type of <constant>SmSaveBoth</constant> it would first save the 594currently edited file. It would then create a temporary file with 595information such as the current position of the cursor and what file 596is being edited. Finally, it would update its 597<property>SmRestartCommand</property> property with enough information 598to find the temporary file. 599 </para></listitem> 600 </itemizedlist> 601 </para> 602 603 <para> 604The <parameter>shutdown</parameter> argument specifies whether the 605system is being shut down. 606The interaction is different depending on whether or not shutdown is 607set. If not shutting down, the client should save its state and wait 608for a “Save Complete” message. If shutting down, the 609client must save state and then prevent interaction until it receives 610either a “Die” or a “Shutdown Cancelled.” 611 </para> 612 613 <para> 614The <parameter>fast</parameter> argument specifies that the client 615should save its state as quickly as possible. For example, if the 616session manager knows that power is about to fail, it would 617set <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> 625The 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> 649The session manager sends a “Die” message to a client when 650it wants it to die. The client should respond by calling 651<xref linkend='SmcCloseConnection' xrefstyle='select: title'/>. A session manager that 652behaves properly will send a “Save Yourself” message 653before the “Die” message. 654 </para> 655 </sect2> 656 657 <sect2 id='The_Save_Complete_Callback'> 658<title>The Save Complete Callback</title> 659 660 <para> 661The 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> 689The 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> 713The session manager sends a “Shutdown Cancelled” message 714when the user cancelled the shutdown during an interaction 715(see <link linkend='Interacting_With_the_User'>section 5.5, 716“Interacting With the User”</link>). The client can now 717continue as if the shutdown had never happened. If the client has not 718called <xref linkend='SmcSaveYourselfDone' xrefstyle='select: title'/> yet, it can either 719abort the save and then call <xref linkend='SmcSaveYourselfDone' xrefstyle='select: title'/> 720with the success argument set to <constant>False</constant> or it can 721continue with the save and then call <xref linkend='SmcSaveYourselfDone' xrefstyle='select: title'/> 722with the <parameter>success</parameter> argument set to reflect the outcome 723of the save. 724 </para> 725 </sect2> 726 </sect1> 727 728 <sect1 id='Closing_the_Connection'> 729<title>Closing the Connection</title> 730 731 <para> 732To close a connection with a session manager, 733use <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> 760The <parameter>reason_msgs</parameter> argument will most likely be 761<constant>NULL</constant> if resignation is expected by the client. 762Otherwise, it contains a list of null-terminated Compound Text strings 763representing the reason for termination. The session manager should 764display these reason messages to the user. 765 </para> 766 767 <para> 768Note that SMlib used the ICE protocol to establish a connection with 769the session manager, and various protocols other than session 770management may be active on the ICE connection. 771When <xref linkend='SmcCloseConnection' xrefstyle='select: title'/> is called, the ICE 772connection will be closed only if all protocols have been shutdown on 773the connection. Check the ICElib standard 774for <olink targetdoc='ICElib' targetptr='IceAddConnectionWatch'><function>IceAddConnectionWatch</function></olink> 775and <olink targetdoc='ICElib' targetptr='IceRemoveConnectionWatch'><function>IceRemoveConnectionWatch</function></olink> to learn how to set 776up a callback to be invoked each time an ICE connection is opened or 777closed. Typically this callback adds/removes the ICE file descriptor 778from 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 790this 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 794connection, but <xref linkend='SmcCloseConnection' xrefstyle='select: title'/> is being 795called within a nested <olink targetdoc='ICElib' targetptr='IceProcessMessages'><function>IceProcessMessages</function></olink> The 796watch procedures have been invoked at this time, but the connection 797will be freed as soon as possible (when the nesting level reaches zero 798and <olink targetdoc='ICElib' targetptr='IceProcessMessages'><function>IceProcessMessages</function></olink> returns a status 799of <function>IceProcessMessagesConnectionClosed</function> 800 </para> </listitem> 801 <listitem><para> 802<constant>SmcConnectionInUse</constant> - the connection was not closed at 803this 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> 814To modify callbacks set up in <xref linkend='SmcOpenConnection' xrefstyle='select: title'/> 815use <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> 842When specifying a value for the <parameter>mask</parameter> argument, 843the 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> 858To set session management properties for this client, 859use <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> 888The properties are specified as an array of property pointers. 889Previously set property values may be over-written using 890the <xref linkend='SmcSetProperties' xrefstyle='select: title'/> function. Note that the 891session manager is not expected to restore property values when the 892session is restarted. Because of this, clients should not try to use 893the session manager as a database for storing application specific state. 894 </para> 895 896 <para> 897For a description of session management properties and 898the <structname>SmProp</structname> structure, 899see <link linkend='Session_Management_Properties'>section 7, 900“Session Management Properties.”</link> 901 </para> 902 903 904 <para> 905To delete properties previously set by the client, 906use <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> 933To get properties previously stored by the client, 934use <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> 962The return value of <xref linkend='SmcGetProperties' xrefstyle='select: title'/> is zero for 963failure and a positive value for success. 964 </para> 965 966 <para> 967Note that the library does not block until the properties reply comes 968back. Rather, a callback of type <xref linkend='SmcPropReplyProc' xrefstyle='select: title'/> 969is 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> 1002To free each property, use <xref linkend='SmFreeProperty' xrefstyle='select: title'/> 1003(see <link linkend='Freeing_Data'>section 8, “Freeing 1004Data”</link>). To free the actual array of pointers, 1005use <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> 1013After receiving a “Save Yourself” message with an 1014<parameter>interact_style</parameter> of 1015<constant>SmInteractStyleErrors</constant> 1016or <constant>SmInteractStyleAny</constant> the client may choose to 1017interact with the user. Because only one client can interact with the 1018user at a time, the client must call <xref linkend='SmcInteractRequest' xrefstyle='select: title'/> 1019and wait for an “Interact” 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 “Interact” message arrives from the session manager.</para></listitem> 1044 </varlistentry> 1045 <varlistentry> 1046 <term><parameter>client_data</parameter></term> 1047 <listitem><para> 1048This pointer to client data will be passed to 1049the <xref linkend='SmcInteractProc' xrefstyle='select: title'/> callback when the 1050“Interact” message arrives. 1051 </para></listitem> 1052 </varlistentry> 1053</variablelist> 1054 1055 <para> 1056The return value of <xref linkend='SmcInteractRequest' xrefstyle='select: title'/> is zero 1057for failure and a positive value for success. 1058 </para> 1059 1060 <para> 1061The <parameter>dialog_type</parameter> argument specifies 1062either <constant>SmDialogError</constant> indicating that the client 1063wants to start an error dialog, or <constant>SmDialogNormal</constant> 1064meaning that the client wishes to start a nonerror dialog. 1065 </para> 1066 1067 <para> 1068Note that if a shutdown is in progress, the user may have the option 1069of cancelling the shutdown. If the shutdown is cancelled, the clients 1070that have not interacted yet with the user will receive a 1071“Shutdown Cancelled” message instead of the 1072“Interact” message. 1073 </para> 1074 1075 <para> 1076The <xref linkend='SmcInteractProc' xrefstyle='select: title'/> callback will be invoked when 1077the “Interact” 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> 1100After interacting with the user (in response to an “Interact” 1101message), 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> 1123The <parameter>cancel_shutdown</parameter> argument may only be 1124<constant>True</constant> if the corresponding “Save Yourself” 1125specified <constant>True</constant> for shutdown 1126and <constant>SmInteractStyleErrors</constant> 1127or <constant>SmInteractStyleAny</constant> for 1128the <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> 1136To request a checkpoint from the session manager, 1137use <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 “Save Yourself.”</para></listitem> 1177 </varlistentry> 1178</variablelist> 1179 1180 <para> 1181The <parameter>save_type</parameter>, <parameter>shutdown</parameter>, 1182<parameter>interact_style</parameter>, and <parameter>fast</parameter> 1183arguments are discussed in more detail in 1184<link linkend='The_Save_Yourself_Callback'>section 5.1.1, 1185“The Save Yourself Callback.”</link> 1186 </para> 1187 1188 <para> 1189If <parameter>global</parameter> is set to <constant>True</constant> then 1190the resulting “Save Yourself” should be sent to all clients in the 1191session. For example, a vendor of a Uninterruptible Power Supply 1192(<acronym>UPS</acronym>) might include a Session Management client 1193that would monitor the status of the UPS and generate a fast shutdown 1194if the power is about to be lost. 1195 </para> 1196 1197 <para> 1198If global is set to <constant>False</constant> then the “Save 1199Yourself” 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> 1207In response to a “Save Yourself”, the client may request to be 1208informed when all the other clients are quiescent so that it can save their 1209state. 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 “Save Yourself Phase 2” 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 “Save Yourself Phase 2” message arrives.</para></listitem> 1233 </varlistentry> 1234</variablelist> 1235 1236 <para> 1237The return value of <xref linkend='SmcRequestSaveYourselfPhase2' xrefstyle='select: title'/> 1238is zero for failure and a positive value for success. 1239 </para> 1240 1241 <para> 1242This request is needed by clients that manage other clients (for 1243example, window managers, workspace managers, and so on). The manager 1244must make sure that all of the clients that are being managed are in 1245an 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> 1253After saving state in response to a “Save Yourself” 1254message, 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 “Save Yourself” operation was completed successfully.</para></listitem> 1273 </varlistentry> 1274</variablelist> 1275 1276 <para> 1277Before calling <xref linkend='SmcSaveYourselfDone' xrefstyle='select: title'/> the client 1278must have set each required property at least once since the client 1279registered 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 1295the 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 1308the 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 1320identification of the owner of the session manager. The string should 1321be 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 1333release number of the session manager. The string should be freed 1334with 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 1346the client ID associated with this connection. This information was 1347also returned in <xref linkend='SmcOpenConnection' xrefstyle='select: title'/> (it is 1348provided here for convenience). Call <function>free</function> on 1349this 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 1361object associated with this session management connection object. The 1362ICE connection object can be used to get some additional information 1363about the connection. Some of the more useful functions which can be 1364used 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>, 1368and <olink targetdoc='ICElib' targetptr='IcePing'><function>IcePing</function></olink>. For further information, see 1369the <citetitle pubwork='article'>Inter-Client Exchange Library</citetitle> 1370standard. 1371 </para> 1372 </sect1> 1373 1374 <sect1 id='Error_Handling'> 1375<title>Error Handling</title> 1376 1377 <para> 1378If the client receives an unexpected protocol error from the session 1379manager, an error handler is invoked by SMlib. A default error 1380handler exists that simply prints the error message 1381to <varname>stderr</varname> and exits if the severity of the error 1382is fatal. The client can change this error handler by calling 1383the <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> 1394The error handler. You should pass <constant>NULL</constant> to 1395restore 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> 1404The <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> 1455Note that this error handler is invoked for protocol related errors. 1456To 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 1458the <citetitle pubwork='article'>Inter-Client Exchange Library</citetitle> 1459standard. 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> 1468This 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 “Save Yourself” message</para></listitem> 1474 <listitem><para>Send a “Save Yourself Phase 2” message</para></listitem> 1475 <listitem><para>Send an “Interact” message</para></listitem> 1476 <listitem><para>Send a “Save Complete” message</para></listitem> 1477 <listitem><para>Send a “Die” 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 1492should be called by a session manager. It provides information about 1493the session manager and registers a callback that will be invoked each 1494time 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> 1540Returns a null-terminated error message, if any. 1541The <parameter>error_string_ret</parameter> points to user supplied memory. 1542No more than <parameter>error_length</parameter> bytes are used. 1543 </para></listitem> 1544 </varlistentry> 1545</variablelist> 1546 1547 <para> 1548After the <xref linkend='SmsInitialize' xrefstyle='select: title'/> function is called, the 1549session manager should call the <olink targetdoc='ICElib' targetptr='IceListenForConnections'><function>IceListenForConnections</function></olink> 1550function to listen for new connections. Afterwards, each time a 1551client connects, the session manager should 1552call <olink targetdoc='ICElib' targetptr='IceAcceptConnection'><function>IceAcceptConnection</function></olink> 1553 </para> 1554 1555 <para> 1556See <link linkend='Authentication_of_Clients'>section 9, 1557“Authentication of Clients,”</link> for more details on 1558authentication (including host based authentication). Also see 1559the <citetitle pubwork='article'>Inter-Client Exchange 1560Library</citetitle> standard for further details on listening for and 1561accepting ICE connections. 1562 </para> 1563 1564 <para> 1565Each time a new client connects to the session manager, 1566the <xref linkend='SmsNewClientProc' xrefstyle='select: title'/> callback is invoked. The 1567session manager obtains a new opaque connection object that it should 1568use for all future interaction with the client. At this time, the 1569session manager must also register a set of callbacks to respond to 1570the 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> 1608If a failure occurs, the <xref linkend='SmsNewClientProc' xrefstyle='select: title'/> should 1609return a zero status as well as allocate and return a failure reason 1610string in <parameter>failure_reason_ret</parameter>. 1611SMlib will be responsible for freeing this memory. 1612 </para> 1613 1614 <para> 1615The session manager must register a set of callbacks to respond to 1616client events. The <parameter>mask_ret</parameter> argument specifies 1617which callbacks are set. All of the callbacks specified in this version of 1618SMlib are mandatory. The <parameter>mask_ret</parameter> argument is 1619necessary in order to maintain backwards compatibility in future versions 1620of the library. 1621 </para> 1622 1623 <para> 1624The 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> 1641For each callback, the session manager can register a pointer to 1642manager data specific to that callback. This pointer will be passed 1643to the callback when it is invoked by SMlib. 1644 </para> 1645 1646<synopsis> 1647typedef 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> 1705The Register Client callback is the first callback that will be 1706invoked after the client connects to the session manager. Its type 1707is <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> 1735Before any further interaction takes place with the client, the client 1736must be registered with the session manager. 1737 </para> 1738 1739 <para> 1740If the client is being restarted from a previous session, 1741<parameter>previous_id</parameter> will contain a null-terminated string 1742representing the client ID from the previous session. 1743Call <function>free</function> on the <parameter>previous_id</parameter> 1744pointer when it is no longer needed. If the client is first joining the 1745session, <parameter>previous_id</parameter> will be <constant>NULL</constant>. 1746 </para> 1747 1748 <para> 1749If <parameter>previous_id</parameter> is invalid, the session manager should 1750not register the client at this time. This callback should return a status 1751of zero, which will cause an error message to be sent to the client. The 1752client should re-register with previous_id set to <constant>NULL</constant>. 1753 </para> 1754 1755 <para> 1756Otherwise, the session manager should register the client with a unique 1757client ID by calling the <xref linkend='SmsRegisterClientReply' xrefstyle='select: title'/> 1758function (to be discussed shortly), and the 1759<xref linkend='SmsRegisterClientProc' xrefstyle='select: title'/> callback should return a 1760status of one. 1761 </para> 1762 </sect2> 1763 1764 <sect2 id='The_Interact_Request_Callback'> 1765<title>The Interact Request Callback</title> 1766 1767 <para> 1768The Interact Request callback is of 1769type <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> 1797When a client receives a “Save Yourself” message with an 1798<parameter>interact_style</parameter> of 1799<constant>SmInteractStyleErrors</constant> 1800or <constant>SmInteractStyleAny</constant> the client may choose to 1801interact with the user. Because only one client can interact with the 1802user at a time, the client must request to interact with the user. 1803The session manager should keep a queue of all clients wishing to 1804interact. It should send an “Interact” message to one 1805client at a time and wait for an “Interact Done” message 1806before continuing with the next client. 1807 </para> 1808 1809 <para> 1810The <parameter>dialog_type</parameter> argument specifies 1811either <constant>SmDialogError</constant> indicating that the client 1812wants to start an error dialog, or <constant>SmDialogNormal</constant> 1813meaning that the client wishes to start a nonerror dialog. 1814 </para> 1815 1816 <para> 1817If a shutdown is in progress, the user may have the option of 1818cancelling the shutdown. If the shutdown is cancelled (specified in 1819the “Interact Done” message), the session manager should 1820send a “Shutdown Cancelled” message to each client that 1821requested to interact. 1822 </para> 1823 </sect2> 1824 1825 <sect2 id='The_Interact_Done_Callback'> 1826<title>The Interact Done Callback</title> 1827 1828 <para> 1829When the client is done interacting with the user, 1830the <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> 1858Note that the shutdown can be cancelled only if the corresponding 1859“Save Yourself” specified <constant>True</constant> for 1860shutdown and <constant>SmInteractStyleErrors</constant> 1861or <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> 1871The Save Yourself Request callback is of 1872type <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 “Save Yourself.”</para></listitem> 1916 </varlistentry> 1917</variablelist> 1918 1919 <para> 1920The Save Yourself Request prompts the session manager to initiate a 1921checkpoint or shutdown. For information on the 1922<parameter>save_type</parameter>, <parameter>shutdown</parameter>, 1923<parameter>interact_style</parameter>, and <parameter>fast</parameter> 1924arguments, see <link linkend='Sending_a_Save_Yourself_Message'>section 6.3, 1925“Sending a Save Yourself Message.”</link> 1926 </para> 1927 1928 <para> 1929If <parameter>global</parameter> is set to <constant>True</constant> then the 1930resulting “Save Yourself” should be sent to all applications. 1931If <parameter>global</parameter> is set to <constant>False</constant> then the 1932“Save Yourself” 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> 1940The Save Yourself Phase 2 Request callback is of 1941type <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> 1964This request is sent by clients that manage other clients (for 1965example, window managers, workspace managers, and so on). Such 1966managers must make sure that all of the clients that are being managed 1967are 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> 1975When the client is done saving its state in response to a 1976“Save Yourself” message, 1977the <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> 2005Before the “Save Yourself Done” was sent, the client must 2006have set each required property at least once since it registered with 2007the session manager. 2008 </para> 2009 </sect2> 2010 2011 <sect2 id='The_Connection_Closed_Callback'> 2012<title>The Connection Closed Callback</title> 2013 2014 <para> 2015If the client properly terminates (that is, it 2016calls <xref linkend='SmcCloseConnection' xrefstyle='select: title'/>, 2017the <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> 2050The <parameter>reason_msgs</parameter> argument will most likely 2051be <constant>NULL</constant> and the <parameter>count</parameter> 2052argument zero (0) if resignation is expected by the user. Otherwise, 2053it contains a list of null-terminated Compound Text strings 2054representing the reason for termination. The session manager should 2055display these reason messages to the user. 2056 </para> 2057 2058 <para> 2059Call <xref linkend='SmFreeReasons' xrefstyle='select: title'/> to free the reason messages. 2060For further information, see 2061<link linkend='Freeing_Data'>section 8, “Freeing Data”</link> 2062 </para> 2063 </sect2> 2064 2065 <sect2 id='The_Set_Properties_Callback'> 2066<title>The Set Properties Callback</title> 2067 2068 <para> 2069When the client sets session management properties, 2070the <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> 2103The properties are specified as an array of property pointers. For a 2104description of session management properties and 2105the <structname>SmProp</structname> structure, 2106see <link linkend='Session_Management_Properties'>section 7, 2107“Session Management Properties.”</link> 2108 </para> 2109 2110 <para> 2111Previously set property values may be over-written. Some properties 2112have predefined semantics. The session manager is required to store 2113nonpredefined properties. 2114 </para> 2115 2116 <para> 2117To free each property, use <xref linkend='SmFreeProperty' xrefstyle='select: title'/>. 2118For further information, see <link linkend='Freeing_Data'>section 8, 2119“Freeing Data”</link> You should free the actual array of 2120pointers 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> 2128When the client deletes session management properties, 2129the <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> 2162The properties are specified as an array of strings. For a 2163description of session management properties and 2164the <structname>SmProp</structname> structure, 2165see <link linkend='Session_Management_Properties'>section 7, 2166“Session Management Properties.”</link> 2167 </para> 2168 </sect2> 2169 2170 <sect2 id='The_Get_Properties_Callback'> 2171<title>The Get Properties Callback</title> 2172 2173 <para> 2174The <xref linkend='SmsGetPropertiesProc' xrefstyle='select: title'/> callback is invoked when 2175the 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> 2198The session manager should respond by 2199calling <xref linkend='SmsReturnProperties' xrefstyle='select: title'/>. 2200All 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> 2209To register a client (in response to 2210a <xref linkend='SmsRegisterClientProc' xrefstyle='select: title'/> callback), 2211use <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> 2234The return value of <xref linkend='SmsRegisterClientReply' xrefstyle='select: title'/> is 2235zero for failure and a positive value for success. Failure will occur 2236if SMlib can not allocate memory to hold a copy of the client ID for 2237it's own internal needs. 2238 </para> 2239 2240 <para> 2241If a non-<constant>NULL</constant> <parameter>previous_id</parameter> was 2242specified when the client registered itself, <parameter>client_id</parameter> 2243should be identical to <parameter>previous_id</parameter>. 2244 </para> 2245 2246 <para> 2247Otherwise, <parameter>client_id</parameter> should be a unique ID freshly 2248generated by the session manager. In addition, the session manager should 2249send a “Save Yourself” message with 2250<parameter>type</parameter> = <constant>Local</constant>, 2251<parameter>shutdown</parameter> = <constant>False</constant>, 2252<parameter>interact-style</parameter> = <constant>None</constant>, 2253and <parameter>fast</parameter> = <constant>False</constant> 2254immediately after registering the client. 2255 </para> 2256 2257 <para> 2258Note that once a client ID has been assigned to the client, the client 2259keeps this ID indefinitely. If the client is terminated and 2260restarted, it will be reassigned the same ID. It is desirable to be 2261able to pass client IDs around from machine to machine, from user to 2262user, and from session manager to session manager, while retaining the 2263identity of the client. This, combined with the indefinite 2264persistence of client IDs, means that client IDs need to be globally 2265unique. 2266 </para> 2267 2268 <para> 2269You should call the <xref linkend='SmsGenerateClientID' xrefstyle='select: title'/> function 2270to 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. 2290Otherwise, the return value of the function is the client ID. 2291It should be freed with a call to <function>free</function> when 2292no 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> 2300To send a “Save Yourself” to a client, 2301use <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> 2340The session manager sends a “Save Yourself” message to a 2341client either to checkpoint it or just before termination so that it 2342can save its state. The client responds with zero or more “Set 2343Properties” messages to update the properties indicating how to 2344restart the client. When all the properties have been set, the client 2345sends a “Save Yourself Done” message. 2346 </para> 2347 2348 <para> 2349If <parameter>interact_style</parameter> 2350is <constant>SmInteractStyleNone</constant> the 2351client must not interact with the user while saving state. 2352If <parameter>interact_style</parameter> 2353is <constant>SmInteractStyleErrors</constant> the 2354client may interact with the user only if an error condition arises. 2355If <parameter>interact_style</parameter> 2356is <constant>SmInteractStyleAny</constant> then the 2357client may interact with the user for any purpose. The client must 2358send an “Interact Request” message and wait for an 2359“Interact” message from the session manager before it can 2360interact with the user. When the client is done interacting with the 2361user, it should send an “Interact Done” message. The 2362“Interact Request” message can be sent any time after a 2363“Save Yourself” and before a “Save Yourself 2364Done.” 2365 </para> 2366 2367 <para> 2368If <parameter>save_type</parameter> is <constant>SmSaveLocal</constant> 2369the client must update the properties to reflect its current state. 2370Specifically, it should save enough information to restore the state as 2371seen by the user of this client. It should not affect the state as seen 2372by other users. 2373If <parameter>save_type</parameter> is <constant>SmSaveGlobal</constant> 2374the user wants the client to commit all of its data to permanent, globally 2375accessible storage. 2376If <parameter>save_type</parameter> is <constant>SmSaveBoth</constant> 2377the client should do both of these (it should first commit the data to 2378permanent storage before updating its properties). 2379 </para> 2380 2381 <para> 2382The <parameter>shutdown</parameter> argument specifies whether the session 2383is being shut down. The interaction is different depending on whether or not 2384shutdown is set. If not shutting down, then the client can save and 2385resume normal operation. If shutting down, the client must save and 2386then must prevent interaction until it receives either a 2387“Die” or a “Shutdown Cancelled,” because 2388anything the user does after the save will be lost. 2389 </para> 2390 2391 <para> 2392The <parameter>fast</parameter> argument specifies that the client should 2393save its state as quickly as possible. For example, if the session manager 2394knows that power is about to fail, it should set <parameter>fast</parameter> 2395to <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> 2403In order to send a “Save Yourself Phase 2” message to a 2404client, 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> 2422The session manager sends this message to a client that has previously 2423sent a “Save Yourself Phase 2 Request” message. This 2424message informs the client that all other clients are in a fixed state 2425and 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> 2433To send an “Interact” message to a client, 2434use <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> 2452The “Interact” message grants the client the privilege of 2453interacting with the user. When the client is done interacting with 2454the user, it must send an “Interact Done” message to the 2455session 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> 2463To send a “Save Complete” message to a client, 2464use <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> 2482The session manager sends this message when it is done with a 2483checkpoint. 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> 2491To send a “Die” message to a client, 2492use <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> 2510Before the session manager terminates, it should wait for a 2511“Connection Closed” message from each client that it sent 2512a “Die” 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> 2520To 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> 2538The client can now continue as if the shutdown had never happened. If 2539the client has not sent a “Save Yourself Done” message 2540yet, it can either abort the save and send a “Save Yourself 2541Done” with the success argument set to <constant>False</constant> 2542or it can continue with the save and send a “Save Yourself Done” 2543with the <parameter>success</parameter> argument set to reflect the outcome 2544of the save. 2545 </para> 2546 </sect1> 2547<!-- aaaaaaaaaaaaaaaaa --> 2548 2549 <sect1 id='Returning_Properties'> 2550<title>Returning Properties</title> 2551 2552 <para> 2553In response to a “Get Properties” message, the session 2554manager 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> 2582The properties are returned as an array of property pointers. For a 2583description of session management properties and 2584the <structname>SmProp</structname> structure, 2585see <link linkend='Session_Management_Properties'>section 7, 2586“Session Management Properties.”</link> 2587 </para> 2588 </sect1> 2589 2590 <sect1 id='Pinging_a_Client'> 2591<title>Pinging a Client</title> 2592 2593 <para> 2594To check that a client is still alive, you should use 2595the <olink targetdoc='ICElib' targetptr='IcePing'><function>IcePing</function></olink> function provided by the ICE library. 2596To do so, the ICE connection must be obtained using 2597the <xref linkend='SmsGetIceConnection' xrefstyle='select: title'/> 2598(see <link linkend='Using_Sms_Informational_Functions'>section 6.12, 2599“Using Sms Informational Functions”</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> 2629When the Ping reply is ready (if ever), 2630the <xref linkend='IcePingReplyProc' xrefstyle='select: title'/> callback will be invoked. A 2631session manager should have some sort of timeout period, after which 2632it 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> 2660When the session manager receives a “Connection Closed” 2661message or otherwise detects that the client aborted the connection, 2662it should call the <xref linkend='SmsCleanUp' xrefstyle='select: title'/> function in order 2663to 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 2694the 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 2706the 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 2718the client ID associated with this connection. You should 2719call <function>free</function> on this pointer when the client ID is 2720no longer needed. 2721 </para> 2722 2723 2724 <para> 2725To obtain the host name of a client, 2726use <xref linkend='SmsClientHostName' xrefstyle='select: title'/>. 2727This 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> 2738The string returned is of the form 2739<parameter>protocol</parameter><literal>/</literal><parameter>hostname</parameter>, 2740where <parameter>protocol</parameter> is one of 2741{<literal>tcp</literal>, <literal>decnet</literal>, <literal>local</literal>}. 2742You should call <function>free</function> on the string returned when 2743it 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 2755object associated with this session management connection object. The 2756ICE connection object can be used to get some additional information 2757about the connection. Some of the more useful functions which can be 2758used on the IceConn are <function>IceConnectionNumber</function> 2759and <function>IceLastSequenceNumber</function>. 2760For further information, see the 2761<citetitle pubwork='article'>Inter-Client Exchange Library</citetitle> 2762standard. 2763 </para> 2764 </sect1> 2765 2766 <sect1 id='Error_Handling_2'> 2767<title>Error Handling</title> 2768 2769 <para> 2770If the session manager receives an unexpected protocol error from a 2771client, an error handler is invoked by SMlib. A default error handler 2772exists which simply prints the error message (it does not exit). The 2773session manager can change this error handler by 2774calling <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> 2785The error handler. You should pass <constant>NULL</constant> 2786to restore the default handler. 2787 </para> 2788 2789 <para> 2790<xref linkend='SmsSetErrorHandler' xrefstyle='select: title'/> returns the previous error handler. 2791The <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> 2843Note that this error handler is invoked for protocol related errors. 2844To install an error handler to be invoked when an IO error occurs, 2845use <olink targetdoc='ICElib' targetptr='IceSetIOErrorHandler'><function>IceSetIOErrorHandler</function></olink>. 2846For further information, see the 2847<citetitle pubwork='article'>Inter-Client Exchange Library</citetitle> 2848standard. 2849 </para> 2850 </sect1> 2851</chapter> 2852 2853<chapter id='Session_Management_Properties'> 2854 <title>Session Management Properties</title> 2855 2856 <para> 2857Each property is defined by the <structname>SmProp</structname> structure: 2858 2859<synopsis> 2860typedef 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 2867typedef struct { 2868 int length; /* the length of the value */ 2869 SmPointer value; /* the value */ 2870} SmPropValue; 2871</synopsis> 2872 </para> 2873 2874 <para> 2875The X Session Management Protocol defines a list of predefined 2876properties, several of which are required to be set by the client. 2877The following table specifies the predefined properties and indicates 2878which ones are required. Each property has a type associated with it. 2879 </para> 2880 2881 <para> 2882A type of <type>SmCARD8</type> indicates that there is a single 1-byte value. 2883A type of <type>SmARRAY8</type> indicates that there is a single array of bytes. 2884A type of <type>SmLISTofARRAY8</type> indicates that there is a list of array of 2885bytes. 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 2975example, state file). 2976 </para> 2977 2978 <itemizedlist mark='bullet'> 2979 <listitem><para><property>SmCloneCommand</property></para> 2980 <para> 2981This is like the <property>SmRestartCommand</property>, except it restarts a 2982copy of the application. The only difference is that the application does not 2983supply its client ID at register time. On <acronym>POSIX</acronym> systems, 2984this should be of type <type>SmLISTofARRAY8</type>. 2985 </para></listitem> 2986 <listitem><para><property>SmCurrentDirectory</property></para> 2987 <para> 2988On <acronym>POSIX</acronym>-based systems, this specifies the value of the 2989current 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> 2994The discard command contains a command that when delivered to the host 2995that the client is running on (determined from the connection), will 2996cause it to discard any information about the current state. If this 2997command is not specified, the Session Manager will assume that all of 2998the client's state is encoded in the <property>SmRestartCommand</property>. 2999On <acronym>POSIX</acronym> systems, the type should be 3000<type>SmLISTofARRAY8</type>. 3001 </para></listitem> 3002 <listitem><para><property>SmEnvironment</property></para> 3003 <para> 3004On <acronym>POSIX</acronym> based systems, this will be of type 3005<type>SmLISTofARRAY8</type>, where the <type>ARRAY8</type>s alternate between 3006environment variable name and environment variable value. 3007 </para></listitem> 3008 <listitem><para><property>SmProcessID</property></para> 3009 <para> 3010This specifies an OS-specific identifier for the process. 3011On <acronym>POSIX</acronym> systems, this should contain the return value 3012of <function>getpid</function> turned into a Latin-1 (decimal) string. 3013 </para></listitem> 3014 <listitem><para><property>SmProgram</property></para> 3015 <para> 3016This is the name of the program that is running. On <acronym>POSIX</acronym> 3017systems, this should be first parameter passed to <function>execve</function> 3018and should be of type <type>SmARRAY8</type>. 3019 </para></listitem> 3020 <listitem><para><property>SmRestartCommand</property></para> 3021 <para> 3022The restart command contains a command that, when delivered to the 3023host that the client is running on (determined from the connection), 3024will cause the client to restart in its current state. 3025On <acronym>POSIX</acronym>-based systems, this is of 3026type <type>SmLISTofARRAY8</type>, and each of the elements in 3027the array represents an element in the <varname>argv</varname> 3028array. This restart command should ensure that the client restarts 3029with the specified client-ID. 3030 </para></listitem> 3031 <listitem><para><property>SmResignCommand</property></para> 3032 <para> 3033A client that sets the <property>SmRestartStyleHint</property> 3034to <constant>SmRestartAnyway</constant> uses this property to specify a 3035command that undoes the effect of the client and removes any saved state. 3036As an example, consider a user that runs <command>xmodmap</command> which 3037registers with the Session Manager, 3038sets <property>SmRestartStyleHint</property> 3039to <constant>SmRestartAnyway</constant>, and then 3040terminates. To allow the Session Manager (at the user's request) to 3041undo this, <command>xmodmap</command> would register a 3042<property>SmResignCommand</property> that undoes the effects of 3043the <command>xmodmap</command>. 3044 </para></listitem> 3045 <listitem><para><property>SmRestartStyleHint</property></para> 3046 <para> 3047If the <property>SmRestartStyleHint</property> is present, it will contain the 3048style of restarting the client prefers. If this style is not specified, 3049<constant>SmRestartIfRunning</constant> is assumed. 3050The 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> 3086The <constant>SmRestartIfRunning</constant> style is used in the usual case. 3087The client should be restarted in the next session if it was running at 3088the end of the current session. 3089 </para> 3090 3091 <para> 3092The <constant>SmRestartAnyway</constant> style is used to tell the Session 3093Manager that the application should be restarted in the next session even if 3094it exits before the current session is terminated. It should be noted that 3095this is only a hint and the Session Manager will follow the policies 3096specified by its users in determining what applications to restart. 3097 </para> 3098 3099 <para> 3100A client that uses <constant>SmRestartAnyway</constant> should also set the 3101<property>SmResignCommand</property> and <property>SmShutdownCommand</property> 3102properties to commands that undo the state of the client after it exits. 3103 </para> 3104 3105 <para> 3106The 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 3111wish to be restarted in the next session. 3112 </para> 3113 </listitem> 3114 <listitem><para><property>SmShutdownCommand</property></para> 3115 <para> 3116This command is executed at shutdown time to clean up after a client 3117that 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 3120state as the client is still part of the session. As an 3121example, consider a client that turns on a camera at start up time. 3122This client then exits. At session shutdown, the user wants the 3123camera turned off. This client would set the 3124<property>SmRestartStyleHint</property> to 3125<constant>SmRestartAnyway</constant> and would register 3126a <property>SmShutdownCommand</property> that would turn off the camera. 3127 </para></listitem> 3128 <listitem><para><property>SmUserID</property></para> 3129 <para> 3130Specifies the user ID. On <acronym>POSIX</acronym>-based systems, this will 3131contain 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> 3141To 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> 3159To free the reason strings from 3160the <xref linkend='SmsCloseConnectionProc' xrefstyle='select: title'/> callback, 3161use <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> 3188As stated earlier, the session management protocol is layered on top 3189of 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> 3198The authentication methods that are available are 3199implementation-dependent (that is., dependent on the ICElib and SMlib 3200implementations in use). For further information, see the 3201<citetitle pubwork='article'>Inter-Client Exchange Library</citetitle> 3202standard. 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> 3210To declare that multiple threads in an application will be using SMlib 3211(or any other library layered on top of ICElib), you should 3212call <function>IceInitThreads</function>. 3213For further information, see the 3214<citetitle pubwork='article'>Inter-Client Exchange Library</citetitle> 3215standard. 3216 </para> 3217</chapter> 3218 3219<chapter id='Acknowledgements'> 3220 <title>Acknowledgements</title> 3221 3222 <para> 3223Thanks to the following people for their participation in the 3224X Session Management design: Jordan Brown, Ellis Cohen, Donna Converse, 3225Stephen Gildea, Vania Joloboff, Stuart Marks, Bob Scheifler, Ralph Swick, 3226and Mike Wexler. 3227 </para> 3228 3229</chapter> 3230</book> 3231