








                [1mX Session Management Library[0m

                        [1mVersion 1.0[0m

                   [1mX Consortium Standard[0m

                 [1mX Version 11, Release 6.4[0m


                         [4mRalph[24m [4mMor[0m
                        X Consortium



           Copyright (C) 1993, 1994 X Consortium







Permission  is hereby granted, free of charge, to any person
obtaining a copy of this software and associated  documenta-
tion files (the ``Software''), to deal in the Software with-
out restriction, including without limitation the rights  to
use,  copy,  modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to
whom the Software is furnished to do so, subject to the fol-
lowing conditions:

The above copyright notice and this permission notice  shall
be  included  in  all  copies or substantial portions of the
Software.

THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF  ANY
KIND,  EXPRESS  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR-
POSE  AND  NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR-
TIUM BE LIABLE FOR ANY CLAIM, DAMAGES  OR  OTHER  LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR  THE  USE
OR OTHER DEALINGS IN THE SOFTWARE.

Except  as  contained in this notice, the name of the X Con-
sortium shall not be used in  advertising  or  otherwise  to
promote  the  sale,  use  or other dealings in this Software
without prior written authorization from the X Consortium.















X Window System is a trademark of X Consortium, Inc.



































































































































[1m1.  Overview of Session Management[0m

The purpose of the X Session Management Protocol  (XSMP)  is
to provide a uniform mechanism for users to save and restore
their sessions.  A [4msession[24m is a group of  clients,  each  of
which  has a particular state.  The session is controlled by
a network service called the [4msession[24m [4mmanager[24m.   The  session
manager  issues  commands  to  its  clients on behalf of the
user.  These commands may cause clients to save their  state
or  to  terminate.  It is expected that the client will save
its state in such a way that the client can be restarted  at
a  later  time  and  resume its operation as if it had never
been terminated.  A client's state might include information
about  the file currently being edited, the current position
of the insertion point within the file, or the start  of  an
uncommitted  transaction.   The  means  by which clients are
restarted is unspecified by this protocol.

For purposes of this protocol, a [4mclient[24m of the session  man-
ager  is  defined as a connection to the session manager.  A
client is typically, though not necessarily, a process  run-
ning an application program connected to an X display.  How-
ever, a client may be connected to more than one  X  display
or not be connected to any X displays at all.

[1m2.  The Session Management Library[0m

The  Session  Management  Library (SMlib) is a low-level "C"
language interface to XSMP.   It  is  expected  that  higher
level toolkits, such as Xt, will hide many of the details of
session management  from  clients.   Higher  level  toolkits
might  also be developed for session managers to use, but no
such effort is currently under way.

SMlib has two parts to it:

+o    One set of functions for clients that want to  be  part
     of a session

+o    One set of functions for session managers to call

Some applications will use both sets of functions and act as
[4mnested[24m [4msession[24m [4mmanagers[24m.  That is, they will be both a  ses-
sion manager and a client of another session.  An example is
a mail program that could start a text  editor  for  editing
the  text  of a mail message.  The mail program is part of a
regular session and, at the same time, is also acting  as  a
session manager to the editor.

Clients  initialize by connecting to the session manager and
obtaining a [4mclient-ID[24m that uniquely identifies them  in  the
session.  The session manager maintains a list of properties
for each client in the session.  These  properties  describe
the client's environment and, most importantly, describe how



                            - 1 -





[1mX Session Management Library                X11, Release 6.4[0m


the client can be restarted (via an Clients are expected  to
save  their state in such a way as to allow multiple instan-
tiations of themselves to be managed independently.  For ex-
ample, clients may use their client-ID as part of a filename
in which to store the state for a particular  instantiation.
The  client-ID  should  be  saved as part of the so that the
client will retain the same ID after it is restarted.

Once the client initializes itself with the session manager,
it  must  be  ready  to respond to messages from the session
manager.  For example, it might be asked to save  its  state
or  to  terminate.   In  the case of a shutdown, the session
manager might give each client a chance to interact with the
user and cancel the shutdown.

[1m3.  Understanding SMlib's Dependence on ICE[0m

The  X  Session Management Protocol is layered on top of the
Inter-Client Exchange (ICE) Protocol.  The ICE  protocol  is
designed  to  multiplex several protocols over a single con-
nection.  As a result, working with SMlib requires a  little
knowledge of how the ICE library works.

The  ICE  library  utilizes  callbacks  to process messages.
When a client detects that there is data to read on  an  ICE
connection, it should call the function.  will read the mes-
sage header and look at the major opcode in order to  deter-
mine  which  protocol the message was intended for.  The ap-
propriate protocol library will then be triggered to  unpack
the message and hand it off to the client via a callback.

The  main  point to be aware of is that an application using
SMlib must have some code that detects when there is data to
read  on  an ICE connection.  This can be done via a call on
the file descriptor for the ICE connection, but  more  typi-
cally,  will be used to register a callback that will invoke
each time there is data to read on the ICE connection.

To further complicate things, knowing which file descriptors
to  call on requires an understanding of how ICE connections
are created.  On the client side, a call must be made to  in
order to open a connection with a session manager.  will in-
ternally make a call into which will, in turn, determine  if
an ICE connection already exists between the client and ses-
sion manager.  Most likely, a connection  will  not  already
exist  and  a  new ICE connection will be created.  The main
point to be aware of is that, on the client side, it is  not
obvious  when  ICE connections get created or destroyed, be-
cause connections are shared when possible.   To  deal  with
this,  the  ICE  library lets the application register watch
procedures that will be invoked each time an ICE  connection
is  opened  or closed.  These watch procedures could be used
to add or remove ICE file descriptors from the list  of  de-
scriptors to call on.



                            - 2 -





[1mX Session Management Library                X11, Release 6.4[0m


On  the session manager side, things work a bit differently.
The session manager has complete control over  the  creation
of  ICE  connections.  The session manager has to first call
in order to start listening for  connections  from  clients.
Once  a  connection attempt is detected, must be called, and
the session manager can simply add the new ICE file descrip-
tor to the list of descriptors to call on.

For  further information on the library functions related to
ICE connections, see the [4mInter-Client[24m [4mExchange[24m [4mLibrary[24m stan-
dard.

[1m4.  Header Files and Library Name[0m

Applications  (both session managers and clients) should in-
clude the header file This header file defines  all  of  the
SMlib data structures and function prototypes.  includes the
header file which defines all of the SMlib constants.

Because SMlib is dependent on ICE, applications should  link
against SMlib and ICElib by using

[1m5.  Session Management Client (Smc) Functions[0m

This section discusses how Session Management clients:

+o    Connect to the Session Manager

+o    Close the connection

+o    Modify callbacks

+o    Set, delete, and retrieve Session Manager properties

+o    Interact with the user

+o    Request a ``Save Yourself''

+o    Request a ``Save Yourself Phase 2''

+o    Complete a ``Save Yourself''

+o    Use Smc informational functions

+o    Handle Errors

[1m5.1.  Connecting to the Session Manager[0m

To open a connection with a session manager, use
__
||  SmcConn     SmcOpenConnection([4mnetwork_ids_list[24m,     [4mcontext[24m,
[4mxsmp_major_rev[24m, [4mxsmp_minor_rev[24m,
                    [4mmask[24m,      [4mcallbacks[24m,       [4mprevious_id[24m,
[4mclient_id_ret[24m, [4merror_length[24m, [4merror_string_ret[24m)



                            - 3 -





[1mX Session Management Library                X11, Release 6.4[0m


    char *[4mnetwork_ids_list[24m;
    SmPointer [4mcontext[24m;
    int [4mxsmp_major_rev[24m;
    int [4mxsmp_minor_rev[24m;
    unsigned long [4mmask[24m;
    SmcCallbacks *[4mcallbacks[24m;
    char *[4mprevious_id[24m;
    char **[4mclient_id_ret[24m;
    int [4merror_length[24m;
    char *[4merror_string_ret[24m;

[4mnetwork_ids_list[0m
          Specifies  the  network  ID(s) of the session man-
          ager.

[4mcontext[24m   A pointer to an opaque object or  NULL.   Used  to
          determine  if an ICE connection can be shared (see
          below).

[4mxsmp_major_rev[0m
          The highest major version of the XSMP the applica-
          tion supports.

[4mxsmp_minor_rev[0m
          The highest minor version of the XSMP the applica-
          tion supports (for the specified xsmp_major_rev).

[4mmask[24m      A mask indicating which callbacks to register.

[4mcallbacks[24m The callbacks to register.   These  callbacks  are
          used  to respond to messages from the session man-
          ager.

[4mprevious_id[0m
          The client ID from the previous session.

[4mclient_id_ret[0m
          The client ID for the current session is returned.

[4merror_length[0m
          Length of the error_string_ret argument passed in.

[4merror_string_ret[0m
          Returns a null-terminated error message,  if  any.
          The  error_string_ret argument points to user sup-
          plied memory.  No more than error_length bytes are
          used.
||__

The  network_ids_list  argument  is a null-terminated string
containing a list of network IDs for  the  session  manager,
separated by commas.  If network_ids_list is NULL, the value
of the environment variable will be used.  Each  network  ID
has the following format:



                            - 4 -





[1mX Session Management Library                X11, Release 6.4[0m


lw(0.25i)  lw(2.5i)  lw(1i).        tcp/<hostname>:<portnum-
ber>   or        decnet/<hostname>::<objname>  or        lo-
cal/<hostname>:<path>


An  attempt  will  be  made to use the first network ID.  If
that fails, an attempt will be made using the second network
ID, and so on.

After  the  connection  is established, registers the client
with the session manager.  If the client is being  restarted
from  a  previous session, previous_id should contain a null
terminated string representing the client ID from the previ-
ous  session.   If  the client is first joining the session,
previous_id should be set to NULL.  If previous_id is speci-
fied but is determined to be invalid by the session manager,
SMlib will re-register the client with  previous_id  set  to
NULL.

If succeeds, it returns an opaque connection pointer of type
and the client_id_ret argument contains the client ID to  be
used  for  this  session.  The client_id_ret should be freed
with a call to when no longer needed.  On  failure,  returns
NULL,  and  the  reason  for  failure  is  returned  in  er-
ror_string_ret.

Note that SMlib uses the ICE protocol to establish a connec-
tion with the session manager.  If an ICE connection already
exists between the client and session manager, it  might  be
possible  for the same ICE connection to be used for session
management.

The context argument indicates how willing the client is  to
share  the  ICE connection with other protocols.  If context
is NULL, then the caller is always willing to share the con-
nection.   If  context  is  not NULL, then the caller is not
willing to use a previously opened ICE connection that has a
different non-NULL context associated with it.

As  previously discussed (section 3, ``Understanding SMlib's
Dependence on ICE''), the client will have to keep track  of
when ICE connections are created or destroyed (using and and
will have to call each time a shows that there  is  data  to
read on an ICE connection.  For further information, see the
[4mInter-Client[24m [4mExchange[24m [4mLibrary[24m standard.

The callbacks argument contains a set of callbacks  used  to
respond to session manager events.  The mask argument speci-
fies which callbacks are set.  All of the  callbacks  speci-
fied in this version of SMlib are mandatory.  The mask argu-
ment is necessary in order to maintain backwards compatibil-
ity in future versions of the library.





                            - 5 -





[1mX Session Management Library                X11, Release 6.4[0m


The  following  values may be ORed together to obtain a mask
value:


For each callback, the client  can  register  a  pointer  to
client  data.  When SMlib invokes the callback, it will pass
the client data pointer.

__
||  typedef struct {

     struct   {             SmcSaveYourselfProc    callback;
          SmPointer client_data;      } save_yourself;

     struct  {            SmcDieProc callback;           Sm-
Pointer client_data;      } die;

     struct   {             SmcSaveCompleteProc    callback;
          SmPointer client_data;      } save_complete;

     struct  {            SmcShutdownCancelledProc callback;
          SmPointer client_data;      } shutdown_cancelled;

} SmcCallbacks;
||__


[1m5.1.1.  The Save Yourself Callback[0m

The Save Yourself callback is of type
__
||  typedef void (*SmcSaveYourselfProc)();

void  SaveYourselfProc([4msmc_conn[24m,   [4mclient_data[24m,   [4msave_type[24m,
[4mshutdown[24m, [4minteract_style[24m, [4mfast[24m)
    SmcConn [4msmc_conn[24m;
    SmPointer [4mclient_data[24m;
    int [4msave_type[24m;
    Bool [4mshutdown[24m;
    int [4minteract_style[24m;
    Bool [4mfast[24m;

[4msmc_conn[24m  The session management connection object.

[4mclient_data[0m
          Client data specified when the callback was regis-
          tered.

[4msave_type[24m Specifies the type of information that  should  be
          saved.

[4mshutdown[24m  Specifies if a shutdown is taking place.





                            - 6 -





[1mX Session Management Library                X11, Release 6.4[0m


[4minteract_style[0m
          The type of interaction allowed with the user.

[4mfast[24m      If  the client should save its state as quickly as
          possible.
||__

The session manager sends a ``Save Yourself'' message  to  a
client either to checkpoint it or just before termination so
that it can save its state.  The client responds  with  zero
or  more calls to to update the properties indicating how to
restart the client.  When all the properties have been  set,
the client calls

If  interact_style  is the client must not interact with the
user while saving state.  If interact_style  is  the  client
may  interact  with  the  user  only  if  an error condition
arises.  If interact_style is then the client  may  interact
with  the user for any purpose.  Because only one client can
interact with the user at a time, the client must  call  and
wait  for  an ``Interact'' message from the session manager.
When the client is done interacting with the user, it  calls
The  client  may  only call after it receives a ``Save Your-
self'' message and before it calls

If save_type is the client must update the properties to re-
flect  its  current  state.   Specifically,  it  should save
enough information to restore the state as seen by the  user
of  this  client.  It should not affect the state as seen by
other users.  If save_type is the user wants the  client  to
commit  all  of  its  data to permanent, globally accessible
storage.  If save_type is the client should do both of these
(it should first commit the data to permanent storage before
updating its properties).

Some examples are as follows:


+o    If a word processor were sent a ``Save Yourself''  with
     a  type  of  it  could create a temporary file that in-
     cluded the current contents of the file,  the  location
     of the cursor, and other aspects of the current editing
     session.  It would  then  update  its  SmRestartCommand
     property with enough information to find this temporary
     file.

+o    If a word processor were sent a ``Save Yourself''  with
     a  type  of  it  would simply save the currently edited
     file.

+o    If a word processor were sent a ``Save Yourself''  with
     a  type  of  it  would  first save the currently edited
     file.  It would then create a temporary file  with  in-
     formation  such  as  the current position of the cursor



                            - 7 -





[1mX Session Management Library                X11, Release 6.4[0m


     and what file is being edited.  Finally, it  would  up-
     date its SmRestartCommand property with enough informa-
     tion to find the temporary file.

The shutdown argument specifies whether the system is  being
shut  down.   The  interaction  is  different  depending  on
whether or not shutdown is set.  If not shutting  down,  the
client  should  save  its  state  and wait for a ``Save Com-
plete'' message.  If shutting down,  the  client  must  save
state  and then prevent interaction until it receives either
a ``Die'' or a ``Shutdown Cancelled.''

The fast argument specifies that the client should save  its
state  as  quickly as possible.  For example, if the session
manager knows that power is about to fail, it would set fast
to

[1m5.1.2.  The Die Callback[0m

The Die callback is of type
__
||  typedef void (*SmcDieProc)();

void DieProc([4msmc_conn[24m, [4mclient_data[24m)
    SmcConn [4msmc_conn[24m;
    SmPointer [4mclient_data[24m;

[4msmc_conn[24m  The session management connection object.

[4mclient_data[0m
          Client data specified when the callback was regis-
          tered.
||__

The session manager sends a ``Die'' message to a client when
it  wants it to die.  The client should respond by calling A
session manager that behaves properly  will  send  a  ``Save
Yourself'' message before the ``Die'' message.

[1m5.1.3.  The Save Complete Callback[0m

The Save Complete callback is of type
__
||  typedef void (*SmcSaveCompleteProc)();

void SaveCompleteProc([4msmc_conn[24m, [4mclient_data[24m)
    SmcConn [4msmc_conn[24m;
    SmPointer [4mclient_data[24m;

[4msmc_conn[24m  The session management connection object.

[4mclient_data[0m
          Client data specified when the callback was regis-
          tered.



                            - 8 -





[1mX Session Management Library                X11, Release 6.4[0m


||__

When the session manager is done with a checkpoint, it  will
send  each  of the clients a ``Save Complete'' message.  The
client is then free to change its state.

[1m5.1.4.  The Shutdown Cancelled Callback[0m

The Shutdown Cancelled callback is of type
__
||  typedef void (*SmcShutdownCancelledProc)();

void ShutdownCancelledProc([4msmc_conn[24m, [4mclient_data[24m)
    SmcConn [4msmc_conn[24m;
    SmPointer [4mclient_data[24m;

[4msmc_conn[24m  The session management connection object.

[4mclient_data[0m
          Client data specified when the callback was regis-
          tered.
||__

The  session  manager sends a ``Shutdown Cancelled'' message
when the user cancelled the shutdown during  an  interaction
(see  section  5.5,  ``Interacting  With  the  User'').  The
client can now continue as if the shutdown  had  never  hap-
pened.   If  the  client  has  not called yet, it can either
abort the save and then call with the success  argument  set
to  or  it can continue with the save and then call with the
success argument set to reflect the outcome of the save.

[1m5.2.  Closing the Connection[0m

To close a connection with a session manager, use

__
||  SmcCloseStatus  SmcCloseConnection([4msmc_conn[24m,   [4mcount[24m,   [4mrea-[0m
[4mson_msgs[24m)
    SmcConn [4msmc_conn[24m;
    int [4mcount[24m;
    char **[4mreason_msgs[24m;

[4msmc_conn[24m  The session management connection object.

[4mcount[24m     The number of reason messages.

[4mreason_msgs[0m
          The reasons for closing the connection.
||__

The  reason_msgs argument will most likely be NULL if resig-
nation is expected by the client.  Otherwise, it contains  a
list  of  null-terminated Compound Text strings representing



                            - 9 -





[1mX Session Management Library                X11, Release 6.4[0m


the reason for termination.  The session manager should dis-
play these reason messages to the user.

Note that SMlib used the ICE protocol to establish a connec-
tion with the session manager, and various  protocols  other
than session management may be active on the ICE connection.
When is called, the ICE connection will be  closed  only  if
all  protocols  have been shutdown on the connection.  Check
the ICElib standard for and to learn how to set up  a  call-
back  to be invoked each time an ICE connection is opened or
closed.  Typically this callback adds/removes the  ICE  file
descriptor  from  the  list of active descriptors to call on
(or calls or

returns one of the following values:

+o    - the ICE connection was closed at this time, the watch
     procedures were invoked, and the connection was freed.

+o    -  an  IO  error had occurred on the connection, but is
     being called within a nested The watch procedures  have
     been  invoked  at this time, but the connection will be
     freed as soon  as  possible  (when  the  nesting  level
     reaches zero and returns a status of

+o    -  the  connection was not closed at this time, because
     it is being used by other active protocols.

[1m5.3.  Modifying Callbacks[0m

To modify callbacks set up in use
__
||  void SmcModifyCallbacks([4msmc_conn[24m, [4mmask[24m, [4mcallbacks[24m)
    SmcConn [4msmc_conn[24m;
    unsigned long [4mmask[24m;
    SmcCallbacks *[4mcallbacks[24m;

[4msmc_conn[24m  The session management connection object.

[4mmask[24m      A mask indicating which callbacks to modify.

[4mcallbacks[24m The new callbacks.
||__

When specifying a value for the mask argument, the following
values may be ORed together:


[1m5.4.   Setting,  Deleting, and Retrieving Session Management[0m
[1mProperties[0m







                           - 10 -





[1mX Session Management Library                X11, Release 6.4[0m


To set session management properties for this client, use
__
||  void SmcSetProperties([4msmc_conn[24m, [4mnum_props[24m, [4mprops[24m)
    SmcConn [4msmc_conn[24m;
    int [4mnum_props[24m;
    SmProp **[4mprops[24m;

[4msmc_conn[24m  The session management connection object.

[4mnum_props[24m The number of properties.

[4mprops[24m     The list of properties to set.
||__

The  properties are specified as an array of property point-
ers.  Previously set property values may be over-written us-
ing  the function.  Note that the session manager is not ex-
pected to  restore  property  values  when  the  session  is
restarted.   Because  of this, clients should not try to use
the session manager as a database  for  storing  application
specific state.

For  a  description of session management properties and the
structure, see section 7, ``Session Management Properties.''


To delete properties previously set by the client, use
__
||  void SmcDeleteProperties([4msmc_conn[24m, [4mnum_props[24m, [4mprop_names[24m)
    SmcConn [4msmc_conn[24m;
    int [4mnum_props[24m;
    char **[4mprop_names[24m;

[4msmc_conn[24m  The session management connection object.

[4mnum_props[24m The number of properties.

[4mprop_names[0m
          The list of properties to delete.
||__


To get properties previously stored by the client, use
__
||  Status      SmcGetProperties([4msmc_conn[24m,      [4mprop_reply_proc[24m,
[4mclient_data[24m)
    SmcConn [4msmc_conn[24m;
    SmcPropReplyProc [4mprop_reply_proc[24m;
    SmPointer [4mclient_data[24m;

[4msmc_conn[24m  The session management connection object.

[4mprop_reply_proc[0m
          The  callback  to  be  invoked when the properties



                           - 11 -





[1mX Session Management Library                X11, Release 6.4[0m


          reply comes back.

[4mclient_data[0m
          This pointer to client data will be passed to  the
          callback.
||__

The return value of is zero for failure and a positive value
for success.

Note that the library does not block  until  the  properties
reply  comes  back.   Rather,  a callback of type is invoked
when the data is ready.
__
||  typedef void (*SmcPropReplyProc)();

void PropReplyProc([4msmc_conn[24m, [4mclient_data[24m, [4mnum_props[24m, [4mprops[24m)
    SmcConn [4msmc_conn[24m;
    SmPointer [4mclient_data[24m;
    int [4mnum_props[24m;
    SmProp **[4mprops[24m;

[4msmc_conn[24m  The session management connection object.

[4mclient_data[0m
          Client data specified when the callback was regis-
          tered.

[4mnum_props[24m The number of properties returned.

[4mprops[24m     The list of properties returned.
||__

To  free  each  property,  use  (see  section  8,  ``Freeing
Data'').  To free the actual array of pointers, use

[1m5.5.  Interacting With the User[0m

After receiving a ``Save Yourself'' message with  an  inter-
act_style  of  or the client may choose to interact with the
user.  Because only one client can interact with the user at
a  time,  the  client must call and wait for an ``Interact''
message from the session manager.
__
||  Status  SmcInteractRequest([4msmc_conn[24m,   [4mdialog_type[24m,   [4minter-[0m
[4mact_proc[24m, [4mclient_data[24m)
    SmcConn [4msmc_conn[24m;
    int [4mdialog_type[24m;
    SmcInteractProc [4minteract_proc[24m;
    SmPointer [4mclient_data[24m;

[4msmc_conn[24m  The session management connection object.





                           - 12 -





[1mX Session Management Library                X11, Release 6.4[0m


[4mdialog_type[0m
          The type of dialog the client wishes to present to
          the user.

[4minteract_proc[0m
          The callback to be invoked when  the  ``Interact''
          message arrives from the session manager.

[4mclient_data[0m
          This  pointer to client data will be passed to the
          callback when the ``Interact'' message arrives.
||__

The return value of is zero for failure and a positive value
for success.

The  dialog_type  argument  specifies either indicating that
the client wants to start an error dialog, or  meaning  that
the client wishes to start a nonerror dialog.

Note  that  if  a shutdown is in progress, the user may have
the option of cancelling the shutdown.  If the  shutdown  is
cancelled, the clients that have not interacted yet with the
user will receive a ``Shutdown Cancelled''  message  instead
of the ``Interact'' message.

The  callback  will be invoked when the ``Interact'' message
arrives from the session manager.
__
||  typedef void (*SmcInteractProc)();

void InteractProc([4msmc_conn[24m, [4mclient_data[24m)
    SmcConn [4msmc_conn[24m;
    SmPointer [4mclient_data[24m;

[4msmc_conn[24m  The session management connection object.

[4mclient_data[0m
          Client data specified when the callback was regis-
          tered.
||__


After  interacting with the user (in response to an ``Inter-
act'' message), you should call
__
||  void SmcInteractDone([4msmc_conn[24m, [4mcancel_shutdown[24m)
    SmcConn [4msmc_conn[24m;
    Bool [4mcancel_shutdown[24m;

[4msmc_conn[24m  The session management connection object.

[4mcancel_shutdown[0m
          If indicates  that  the  user  requests  that  the



                           - 13 -





[1mX Session Management Library                X11, Release 6.4[0m


          entire shutdown be cancelled.
||__

The  cancel_shutdown argument may only be if the correspond-
ing ``Save Yourself'' specified for shutdown and or for  the
interact_style.

[1m5.6.  Requesting a Save Yourself[0m

To request a checkpoint from the session manager, use
__
||  void  SmcRequestSaveYourself([4msmc_conn[24m,  [4msave_type[24m, [4mshutdown[24m,
[4minteract_style[24m, [4mfast[24m, [4mglobal[24m)
    SmcConn [4msmc_conn[24m;
    int [4msave_type[24m;
    Bool [4mshutdown[24m;
    int [4minteract_style[24m;
    Bool [4mfast[24m;
    Bool [4mglobal[24m;

[4msmc_conn[24m  The session management connection object.

[4msave_type[24m Specifies the type of information that  should  be
          saved.

[4mshutdown[24m  Specifies if a shutdown is taking place.

[4minteract_style[0m
          The type of interaction allowed with the user.

[4mfast[24m      If  the client should save its state as quickly as
          possible.

[4mglobal[24m    Controls who gets the ``Save Yourself.''
||__

The save_type, shutdown, interact_style, and fast  arguments
are  discussed  in  more detail in section 5.1.1, ``The Save
Yourself Callback.''

If global is set to then  the  resulting  ``Save  Yourself''
should  be sent to all clients in the session.  For example,
a vendor of a Uninterruptible Power Supply (UPS)  might  in-
clude  a  Session  Management  client that would monitor the
status of the UPS and generate a fast shutdown if the  power
is about to be lost.

If  global  is set to then the ``Save Yourself'' should only
be sent to the client that requested it.

[1m5.7.  Requesting a Save Yourself Phase 2[0m

In response to a ``Save Yourself, the client may request  to
be informed when all the other clients are quiescent so that



                           - 14 -





[1mX Session Management Library                X11, Release 6.4[0m


it can save their state.  To do so, use
__
||  Status   SmcRequestSaveYourselfPhase2([4msmc_conn[24m,   [4msave_your-[0m
[4mself_phase2_proc[24m, [4mclient_data[24m)
    SmcConn [4msmc_conn[24m;
    SmcSaveYourselfPhase2Proc [4msave_yourself_phase2_proc[24m;
    SmPointer [4mclient_data[24m;

[4msmc_conn[24m  The session management connection object.

[4msave_yourself_phase2_proc[0m
          The  callback  to be invoked when the ``Save Your-
          self Phase 2'' message arrives  from  the  session
          manager.

[4mclient_data[0m
          This  pointer to client data will be passed to the
          callback when the ``Save Yourself Phase  2''  mes-
          sage arrives.
||__

The return value of is zero for failure and a positive value
for success.

This request is needed by clients that manage other  clients
(for  example,  window  managers, workspace managers, and so
on).  The manager must make sure that  all  of  the  clients
that  are  being  managed are in an idle state so that their
state can be saved.

[1m5.8.  Completing a Save Yourself[0m

After saving state in response to a ``Save  Yourself''  mes-
sage, you should call
__
||  void SmcSaveYourselfDone([4msmc_conn[24m, [4msuccess[24m)
    SmcConn [4msmc_conn[24m;
    Bool [4msuccess[24m;

[4msmc_conn[24m  The session management connection object.

[4msuccess[24m   If  the  ``Save Yourself'' operation was completed
          successfully.
||__

Before calling the client must have set each required  prop-
erty at least once since the client registered with the ses-
sion manager.

[1m5.9.  Using Smc Informational Functions[0m







                           - 15 -





[1mX Session Management Library                X11, Release 6.4[0m

__
||  int SmcProtocolVersion([4msmc_conn[24m)
||__    SmcConn [4msmc_conn[24m;

returns the major version of the session management protocol
associated with this session.


__
||  int SmcProtocolRevision([4msmc_conn[24m)
||__    SmcConn [4msmc_conn[24m;

returns the minor version of the session management protocol
associated with this session.


__
||  char *SmcVendor([4msmc_conn[24m)
||__    SmcConn [4msmc_conn[24m;

returns a string that provides some  identification  of  the
owner  of  the  session manager.  The string should be freed
with a call to


__
||  char *SmcRelease([4msmc_conn[24m)
||__    SmcConn [4msmc_conn[24m;

returns a string that provides the  release  number  of  the
session manager.  The string should be freed with a call to


__
||  char *SmcClientID([4msmc_conn[24m)
||__    SmcConn [4msmc_conn[24m;

returns  a  null-terminated string for the client ID associ-
ated with this connection.  This information  was  also  re-
turned  in  (it  is provided here for convenience).  Call on
this pointer when the client ID is no longer needed.


__
||  IceConn SmcGetIceConnection([4msmc_conn[24m)
||__    SmcConn [4msmc_conn[24m;

returns the ICE connection object associated with this  ses-
sion  management  connection object.  The ICE connection ob-
ject can be used to get some  additional  information  about
the connection.  Some of the more useful functions which can
be used on the IceConn are and For further information,  see
the [4mInter-Client[24m [4mExchange[24m [4mLibrary[24m standard.





                           - 16 -





[1mX Session Management Library                X11, Release 6.4[0m


[1m5.10.  Error Handling[0m

If the client receives an unexpected protocol error from the
session manager, an error handler is invoked  by  SMlib.   A
default  error  handler  exists that simply prints the error
message to and exits if the severity of the error is  fatal.
The  client  can  change  this  error handler by calling the
function.
__
||  SmcErrorHandler SmcSetErrorHandler([4mhandler[24m)
    SmcErrorHandler [4mhandler[24m;

[4mhandler[24m   The error handler.  You should pass  NULL  to  re-
          store the default handler.
||__

returns the previous error handler.

The has the following type:
__
||  typedef void (*SmcErrorHandler)();

void  ErrorHandler([4msmc_conn[24m,  [4mswap[24m,  [4moffending_minor_opcode[24m,
[4moffending_sequence_num[24m, [4merror_class[24m, [4mseverity[24m, [4mvalues[24m)
    SmcConn [4msmc_conn[24m;
    Bool [4mswap[24m;
    int [4moffending_minor_opcode[24m;
    unsigned long [4moffending_sequence_num[24m;
    int [4merror_class[24m;
    int [4mseverity[24m;
    IcePointer [4mvalues[24m;

[4msmc_conn[24m  The session management connection object.

[4mswap[24m      A flag that indicates if the specified values need
          byte swapping.

[4moffending_minor_opcode[0m
          The minor opcode of the offending message.

[4moffending_sequence_num[0m
          The sequence number of the offending message.

[4merror_class[0m
          The error class of the offending message.

[4mseverity[24m  or

[4mvalues[24m    Any  additional error values specific to the minor
          opcode and class.
||__

Note that this error handler is invoked for protocol related
errors.   To  install an error handler to be invoked when an



                           - 17 -





[1mX Session Management Library                X11, Release 6.4[0m


IO error occurs, use For further information, see the [4mInter-[0m
[4mClient[24m [4mExchange[24m [4mLibrary[24m standard.

[1m6.  Session Management Server (Sms) Functions[0m

This section discusses how Session Management servers:

+o    Initialize the library

+o    Register the client

+o    Send a ``Save Yourself'' message

+o    Send a ``Save Yourself Phase 2'' message

+o    Send an ``Interact'' message

+o    Send a ``Save Complete'' message

+o    Send a ``Die'' message

+o    Cancel a shutdown

+o    Return properties

+o    Ping a client

+o    Clean up after a client disconnects

+o    Use Sms informational functions

+o    Handle errors

[1m6.1.  Initializing the Library[0m

is  the first SMlib function that should be called by a ses-
sion manager.  It provides  information  about  the  session
manager  and  registers a callback that will be invoked each
time a new client connects to the session manager.
__
||  Status SmsInitialize([4mvendor[24m, [4mrelease[24m, [4mnew_client_proc[24m,  [4mman-[0m
[4mager_data[24m, [4mhost_based_auth_proc[24m,
                    [4merror_length[24m, [4merror_string_ret[24m)
    char *[4mvendor[24m;
    char *[4mrelease[24m;
    SmsNewClientProc [4mnew_client_proc[24m;
    SmPointer [4mmanager_data[24m;
    IceHostBasedAuthProc [4mhost_based_auth_proc[24m;
    int [4merror_length[24m;
    char *[4merror_string_ret[24m;

[4mvendor[24m    A string specifying the session manager vendor.





                           - 18 -





[1mX Session Management Library                X11, Release 6.4[0m


[4mrelease[24m   A  string  specifying  the session manager release
          number.

[4mnew_client_proc[0m
          Callback to be invoked each time a new client con-
          nects to the session manager.

[4mmanager_data[0m
          When the callback is invoked, this pointer to man-
          ager data will be passed.

[4mhost_based_auth_proc[0m
          Host based authentication callback.

[4merror_length[0m
          Length of the error_string_ret argument passed in.

[4merror_string_ret[0m
          Returns a null-terminated error message,  if  any.
          The  error_string_ret points to user supplied mem-
          ory.  No more than error_length bytes are used.
||__

After the function is called,  the  session  manager  should
call  the  function  to  listen for new connections.  After-
wards, each time a  client  connects,  the  session  manager
should call

See  section  9, ``Authentication of Clients,'' for more de-
tails on authentication (including  host  based  authentica-
tion).   Also see the [4mInter-Client[24m [4mExchange[24m [4mLibrary[24m standard
for further details on listening for and accepting ICE  con-
nections.

Each  time a new client connects to the session manager, the
callback is invoked.  The  session  manager  obtains  a  new
opaque  connection  object that it should use for all future
interaction with the client.  At this time, the session man-
ager must also register a set of callbacks to respond to the
different messages that the client might send.
__
||  typedef Status (*SmsNewClientProc)();

Status NewClientProc([4msms_conn[24m, [4mmanager_data[24m, [4mmask_ret[24m, [4mcall-[0m
[4mbacks_ret[24m, [4mfailure_reason_ret[24m)
    SmsConn [4msms_conn[24m;
    SmPointer [4mmanager_data[24m;
    unsigned long *[4mmask_ret[24m;
    SmsCallbacks *[4mcallbacks_ret[24m;
    char **[4mfailure_reason_ret[24m;

[4msms_conn[24m  A new opaque connection object.





                           - 19 -





[1mX Session Management Library                X11, Release 6.4[0m


[4mmanager_data[0m
          Manager  data specified when the callback was reg-
          istered.

[4mmask_ret[24m  On return, indicates which callbacks were  set  by
          the session manager.

[4mcallbacks_ret[0m
          On  return,  contains  the callbacks registered by
          the session manager.

[4mfailure_reason_ret[0m
          Failure reason returned.
||__

If a failure occurs, the should return a zero status as well
as  allocate  and  return  a  failure reason string in fail-
ure_reason_ret.  SMlib will be responsible for freeing  this
memory.

The  session manager must register a set of callbacks to re-
spond to client events.   The  mask_ret  argument  specifies
which  callbacks are set.  All of the callbacks specified in
this version of SMlib are mandatory.  The mask_ret  argument
is necessary in order to maintain backwards compatibility in
future versions of the library.

The following values may be ORed together to obtain  a  mask
value:


For  each  callback,  the  session  manager  can  register a
pointer to manager data specific  to  that  callback.   This
pointer will be passed to the callback when it is invoked by
SMlib.
__
||
typedef struct {      struct {            SmsRegisterClient-
Proc callback;           SmPointer manager_data;      } reg-
ister_client;

     struct  {            SmsInteractRequestProc   callback;
          SmPointer manager_data;      } interact_request;

     struct    {             SmsInteractDoneProc   callback;
          SmPointer manager_data;      } interact_done;

     struct {           SmsSaveYourselfRequestProc callback;
          SmPointer  manager_data;       } save_yourself_re-
quest;

     struct   {             SmsSaveYourselfPhase2RequestProc
callback;               SmPointer    manager_data;         }
save_yourself_phase2_request;



                           - 20 -





[1mX Session Management Library                X11, Release 6.4[0m


     struct  {            SmsSaveYourselfDoneProc  callback;
          SmPointer manager_data;      } save_yourself_done;

     struct   {            SmsCloseConnectionProc  callback;
          SmPointer manager_data;      } close_connection;

     struct   {             SmsSetPropertiesProc   callback;
          SmPointer manager_data;      } set_properties;

     struct  {            SmsDeletePropertiesProc  callback;
          SmPointer manager_data;      } delete_properties;

     struct   {             SmsGetPropertiesProc   callback;
          SmPointer manager_data;      } get_properties;

} SmsCallbacks;
||__


[1m6.1.1.  The Register Client Callback[0m

The Register Client callback is the first callback that will
be invoked after the client connects to the session manager.
Its type is
__
||  typedef Status (*SmsRegisterClientProc();

Status   RegisterClientProc([4msms_conn[24m,  [4mmanager_data[24m,  [4mprevi-[0m
[4mous_id[24m)
    SmsConn [4msms_conn[24m;
    SmPointer [4mmanager_data[24m;
    char *[4mprevious_id[24m;

[4msms_conn[24m  The session management connection object.

[4mmanager_data[0m
          Manager data specified when the callback was  reg-
          istered.

[4mprevious_id[0m
          The client ID from the previous session.
||__

Before  any further interaction takes place with the client,
the client must be registered with the session manager.

If the client is being restarted from  a  previous  session,
previous_id will contain a null-terminated string represent-
ing the client ID from the previous session.   Call  on  the
previous_id  pointer  when  it  is no longer needed.  If the
client is first joining the  session,  previous_id  will  be
NULL.





                           - 21 -





[1mX Session Management Library                X11, Release 6.4[0m


If  previous_id  is  invalid, the session manager should not
register the client at this time.  This callback should  re-
turn  a status of zero, which will cause an error message to
be sent to the client.  The client should  re-register  with
previous_id set to NULL.

Otherwise,  the  session  manager should register the client
with a unique client ID by calling the function (to be  dis-
cussed  shortly), and the callback should return a status of
one.

[1m6.1.2.  The Interact Request Callback[0m

The Interact Request callback is of type
__
||  typedef void (*SmsInteractRequestProc)();

void   InteractRequestProc([4msms_conn[24m,   [4mmanager_data[24m,    [4mdia-[0m
[4mlog_type[24m)
    SmsConn [4msms_conn[24m;
    SmPointer [4mmanager_data[24m;
    int [4mdialog_type[24m;

[4msms_conn[24m  The session management connection object.

[4mmanager_data[0m
          Manager  data specified when the callback was reg-
          istered.

[4mdialog_type[0m
          The type of dialog the client wishes to present to
          the user.
||__

When  a  client receives a ``Save Yourself'' message with an
interact_style of or the client may choose to interact  with
the  user.   Because  only  one client can interact with the
user at a time, the client must request to interact with the
user.   The  session  manager  should  keep  a  queue of all
clients wishing to interact.  It should send an ``Interact''
message  to  one client at a time and wait for an ``Interact
Done'' message before continuing with the next client.

The dialog_type argument specifies  either  indicating  that
the  client  wants to start an error dialog, or meaning that
the client wishes to start a nonerror dialog.

If a shutdown is in progress, the user may have  the  option
of  cancelling  the  shutdown.  If the shutdown is cancelled
(specified in the ``Interact Done''  message),  the  session
manager should send a ``Shutdown Cancelled'' message to each
client that requested to interact.





                           - 22 -





[1mX Session Management Library                X11, Release 6.4[0m


[1m6.1.3.  The Interact Done Callback[0m

When the client is done interacting with the user, the call-
back will be invoked.
__
||  typedef void (*SmsInteractDoneProc)();

void  InteractDoneProc([4msms_conn[24m,  [4mmanager_data[24m, [4mcancel_shut-[0m
[4mdown[24m)
    SmsConn [4msms_conn[24m;
    SmPointer [4mmanager_data[24m;
    Bool [4mcancel_shutdown[24m;

[4msms_conn[24m  The session management connection object.

[4mmanager_data[0m
          Manager data specified when the callback was  reg-
          istered.

[4mcancel_shutdown[0m
          Specifies  if  the  user  requests that the entire
          shutdown be cancelled.
||__

Note that the shutdown can be cancelled only if  the  corre-
sponding ``Save Yourself'' specified for shutdown and or for
the interact_style.

[1m6.1.4.  The Save Yourself Request Callback[0m

The Save Yourself Request callback is of type
__
||  typedef void (*SmsSaveYourselfRequestProc)();

void     SaveYourselfRequestProc([4msms_conn[24m,     [4mmanager_data[24m,
[4msave_type[24m, [4mshutdown[24m, [4minteract_style[24m, [4mfast[24m, [4mglobal[24m)
    SmsConn [4msms_conn[24m;
    SmPointer [4mmanager_data[24m;
    int [4msave_type[24m;
    Bool [4mshutdown[24m;
    int [4minteract_style[24m;
    Bool [4mfast[24m;
    Bool [4mglobal[24m;

[4msms_conn[24m  The session management connection object.

[4mmanager_data[0m
          Manager  data specified when the callback was reg-
          istered.

[4msave_type[24m Specifies the type of information that  should  be
          saved.





                           - 23 -





[1mX Session Management Library                X11, Release 6.4[0m


[4mshutdown[24m  Specifies if a shutdown is taking place.

[4minteract_style[0m
          The type of interaction allowed with the user.

[4mfast[24m      If  the client should save its state as quickly as
          possible.

[4mglobal[24m    Controls who gets the ``Save Yourself.''
||__

The Save Yourself Request prompts  the  session  manager  to
initiate  a  checkpoint or shutdown.  For information on the
save_type, shutdown, interact_style, and fast arguments, see
section 6.3, ``Sending a Save Yourself Message.''

If  global  is  set  to then the resulting ``Save Yourself''
should be sent to all applications.  If  global  is  set  to
then the ``Save Yourself'' should only be sent to the client
that requested it.

[1m6.1.5.  The Save Yourself Phase 2 Request Callback[0m

The Save Yourself Phase 2 Request callback is of type
__
||  typedef void (*SmsSaveYourselfPhase2RequestProc)();

void     SmsSaveYourselfPhase2RequestProc([4msms_conn[24m,     [4mman-[0m
[4mager_data[24m)
    SmsConn [4msms_conn[24m;
    SmPointer [4mmanager_data[24m;

[4msms_conn[24m  The session management connection object.

[4mmanager_data[0m
          Manager  data specified when the callback was reg-
          istered.
||__

This request is sent by clients that  manage  other  clients
(for  example,  window  managers, workspace managers, and so
on).  Such managers must make sure that all of  the  clients
that  are  being  managed are in an idle state so that their
state can be saved.

[1m6.1.6.  The Save Yourself Done Callback[0m

When the client is done saving its state in  response  to  a
``Save Yourself'' message, the will be invoked.
__
||  typedef void (*SmsSaveYourselfDoneProc)();

void SaveYourselfDoneProc([4msms_conn[24m, [4mmanager_data[24m, [4msuccess[24m)
    SmsConn [4msms_conn[24m;



                           - 24 -





[1mX Session Management Library                X11, Release 6.4[0m


    SmPointer [4mmanager_data[24m;
    Bool [4msuccess[24m;

[4msms_conn[24m  The session management connection object.

[4mmanager_data[0m
          Manager  data specified when the callback was reg-
          istered.

[4msuccess[24m   If the Save Yourself operation was completed  suc-
          cessfully.
||__

Before  the ``Save Yourself Done'' was sent, the client must
have set each required property at least once since it  reg-
istered with the session manager.

[1m6.1.7.  The Connection Closed Callback[0m

If  the  client  properly  terminates (that is, it calls the
callback is invoked.
__
||  typedef void (*SmsCloseConnectionProc)();

void CloseConnectionProc([4msms_conn[24m, [4mmanager_data[24m, [4mcount[24m, [4mrea-[0m
[4mson_msgs[24m)
    SmsConn [4msms_conn[24m;
    SmPointer [4mmanager_data[24m;
    int [4mcount[24m;
    char **[4mreason_msgs[24m;

[4msms_conn[24m  The session management connection object.

[4mmanager_data[0m
          Manager  data specified when the callback was reg-
          istered.

[4mcount[24m     The number of reason messages.

[4mreason_msgs[0m
          The reasons for closing the connection.
||__

The reason_msgs argument will most likely be  NULL  and  the
count  argument  zero  (0) if resignation is expected by the
user.  Otherwise, it contains a list of null-terminated Com-
pound  Text strings representing the reason for termination.
The session manager should display these reason messages  to
the user.

Call  to free the reason messages.  For further information,
see section 8, ``Freeing Data.''





                           - 25 -





[1mX Session Management Library                X11, Release 6.4[0m


[1m6.1.8.  The Set Properties Callback[0m

When the client  sets  session  management  properties,  the
callback will be invoked.
__
||  typedef void (*SmsSetPropertiesProc)();

void  SetPropertiesProc([4msms_conn[24m,  [4mmanager_data[24m,  [4mnum_props[24m,
[4mprops[24m)
    SmsConn [4msms_conn[24m;
    SmPointer [4mmanager_data[24m;
    int [4mnum_props[24m;
    SmProp **[4mprops[24m;

[4msmc_conn[24m  The session management connection object.

[4mmanager_data[0m
          Manager data specified when the callback was  reg-
          istered.

[4mnum_props[24m The number of properties.

[4mprops[24m     The list of properties to set.
||__

The  properties are specified as an array of property point-
ers.  For a description of session management properties and
the  structure,  see section 7, ``Session Management Proper-
ties.''

Previously set property values may  be  over-written.   Some
properties  have  predefined semantics.  The session manager
is required to store nonpredefined properties.

To free each property, use For further information, see sec-
tion  8, ``Freeing Data.''  You should free the actual array
of pointers with a call to

[1m6.1.9.  The Delete Properties Callback[0m

When the client deletes session management  properties,  the
callback will be invoked.
__
||  typedef void (*SmsDeletePropertiesProc)();

void DeletePropertiesProc([4msms_conn[24m, [4mmanager_data[24m, [4mnum_props[24m,
[4mprop_names[24m)
    SmsConn [4msms_conn[24m;
    SmPointer [4mmanager_data[24m;
    int [4mnum_props[24m;
    char **[4mprop_names[24m;

[4msmc_conn[24m  The session management connection object.




                           - 26 -





[1mX Session Management Library                X11, Release 6.4[0m


[4mmanager_data[0m
          Manager data specified when the callback was  reg-
          istered.

[4mnum_props[24m The number of properties.

[4mprop_names[0m
          The list of properties to delete.
||__

The  properties are specified as an array of strings.  For a
description of session management properties and the  struc-
ture, see section 7, ``Session Management Properties.''

[1m6.1.10.  The Get Properties Callback[0m

The  callback  is  invoked when the client wants to retrieve
properties it set.
__
||  typedef void (*SmsGetPropertiesProc)();

void GetPropertiesProc([4msms_conn[24m, [4mmanager_data[24m)
    SmsConn [4msms_conn[24m;
    SmPointer [4mmanager_data[24m;

[4msmc_conn[24m  The session management connection object.

[4mmanager_data[0m
          Manager data specified when the callback was  reg-
          istered.
||__

The  session  manager  should  respond by calling All of the
properties set for this client should be returned.

[1m6.2.  Registering the Client[0m

To register a client (in response to a callback), use
__
||  Status SmsRegisterClientReply([4msms_conn[24m, [4mclient_id[24m)
    SmsConn [4msms_conn[24m;
    char *[4mclient_id[24m;

[4msms_conn[24m  The session management connection object.

[4mclient_id[24m A null-terminated  string  representing  a  unique
          client ID.
||__

The return value of is zero for failure and a positive value
for success.  Failure will occur if SMlib can  not  allocate
memory to hold a copy of the client ID for it's own internal
needs.




                           - 27 -





[1mX Session Management Library                X11, Release 6.4[0m


If a non-NULL previous_id was specified when the client reg-
istered  itself,  client_id  should  be  identical to previ-
ous_id.

Otherwise, client_id should be a unique ID freshly generated
by  the  session  manager.  In addition, the session manager
should send a ``Save Yourself'' message with type  =  Local,
shutdown  =  False,  interact-style = None, and fast = False
immediately after registering the client.

Note that once a client ID has been assigned to the  client,
the  client  keeps  this  ID indefinitely.  If the client is
terminated and restarted, it will be reassigned the same ID.
It  is  desirable  to be able to pass client IDs around from
machine to machine, from user to user, and from session man-
ager to session manager, while retaining the identity of the
client.  This, combined with the indefinite  persistence  of
client  IDs,  means  that  client  IDs  need  to be globally
unique.

You should call the function to generate a  globally  unique
client ID.
__
||  char *SmsGenerateClientID([4msms_conn[24m)
    SmsConn [4msms_conn[24m;

[4msms_conn[24m  The session management connection object.
||__

NULL  will  be  returned  if  the ID could not be generated.
Otherwise, the return value of the function  is  the  client
ID.   It  should  be  freed  with  a  call to when no longer
needed.

[1m6.3.  Sending a Save Yourself Message[0m

To send a ``Save Yourself'' to a client, use
__
||  void SmsSaveYourself([4msms_conn[24m, [4msave_type[24m,  [4mshutdown[24m,  [4minter-[0m
[4mact_style[24m, [4mfast[24m)
    SmsConn [4msms_conn[24m;
    int [4msave_type[24m;
    Bool [4mshutdown[24m;
    int [4minteract_style[24m;
    Bool [4mfast[24m;

[4msms_conn[24m  The session management connection object.

[4msave_type[24m Specifies  the  type of information that should be
          saved.

[4mshutdown[24m  Specifies if a shutdown is taking place.





                           - 28 -





[1mX Session Management Library                X11, Release 6.4[0m


[4minteract_style[0m
          The type of interaction allowed with the user.

[4mfast[24m      If the client should save its state as quickly  as
          possible.
||__

The  session  manager sends a ``Save Yourself'' message to a
client either to checkpoint it or just before termination so
that  it  can save its state.  The client responds with zero
or more ``Set Properties'' messages to update the properties
indicating  how to restart the client.  When all the proper-
ties have been set,  the  client  sends  a  ``Save  Yourself
Done'' message.

If  interact_style  is the client must not interact with the
user while saving state.  If interact_style  is  the  client
may  interact  with  the  user  only  if  an error condition
arises.  If interact_style is then the client  may  interact
with  the  user  for  any  purpose.  The client must send an
``Interact Request'' message and wait  for  an  ``Interact''
message from the session manager before it can interact with
the user.  When the client  is  done  interacting  with  the
user,  it  should  send  an  ``Interact Done'' message.  The
``Interact Request'' message can be sent any  time  after  a
``Save Yourself'' and before a ``Save Yourself Done.''

If save_type is the client must update the properties to re-
flect its  current  state.   Specifically,  it  should  save
enough  information to restore the state as seen by the user
of this client.  It should not affect the state as  seen  by
other  users.   If save_type is the user wants the client to
commit all of its data  to  permanent,  globally  accessible
storage.  If save_type is the client should do both of these
(it should first commit the data to permanent storage before
updating its properties).

The shutdown argument specifies whether the session is being
shut  down.   The  interaction  is  different  depending  on
whether  or not shutdown is set.  If not shutting down, then
the client can save and resume normal operation.   If  shut-
ting down, the client must save and then must prevent inter-
action until it receives either a ``Die''  or  a  ``Shutdown
Cancelled,''  because  anything the user does after the save
will be lost.

The fast argument specifies that the client should save  its
state  as  quickly as possible.  For example, if the session
manager knows that power is about to  fail,  it  should  set
fast to







                           - 29 -





[1mX Session Management Library                X11, Release 6.4[0m


[1m6.4.  Sending a Save Yourself Phase 2 Message[0m

In  order  to  send a ``Save Yourself Phase 2'' message to a
client, use
__
||  void SmsSaveYourselfPhase2([4msms_conn[24m)
    SmsConn [4msms_conn[24m;

[4msms_conn[24m  The session management connection object.
||__

The session manager sends this message to a client that  has
previously sent a ``Save Yourself Phase 2 Request'' message.
This message informs the client that all other  clients  are
in  a fixed state and this client can save state that is as-
sociated with other clients.

[1m6.5.  Sending an Interact Message[0m

To send an ``Interact'' message to a client, use
__
||  void SmsInteract([4msms_conn[24m)
    SmsConn [4msms_conn[24m;

[4msms_conn[24m  The session management connection object.
||__

The ``Interact'' message grants the client the privilege  of
interacting  with  the user.  When the client is done inter-
acting with the user, it must send an ``Interact Done'' mes-
sage to the session manager.

[1m6.6.  Sending a Save Complete Message[0m

To send a ``Save Complete'' message to a client, use
__
||  void SmsSaveComplete([4msms_conn[24m)
    SmsConn [4msms_conn[24m;

[4msms_conn[24m  The session management connection object.
||__

The  session manager sends this message when it is done with
a checkpoint.  The client is then free to change its state.

[1m6.7.  Sending a Die Message[0m

To send a ``Die'' message to a client, use
__
||  void SmsDie([4msms_conn[24m)
    SmsConn [4msms_conn[24m;

[4msms_conn[24m  The session management connection object.




                           - 30 -





[1mX Session Management Library                X11, Release 6.4[0m


||__

Before the session manager terminates, it should wait for  a
``Connection  Closed'' message from each client that it sent
a ``Die'' message to, timing out appropriately.

[1m6.8.  Cancelling a Shutdown[0m

To cancel a shutdown, use
__
||  void SmsShutdownCancelled([4msms_conn[24m)
    SmsConn [4msms_conn[24m;

[4msms_conn[24m  The session management connection object.
||__

The client can now continue as if  the  shutdown  had  never
happened.   If  the  client  has  not sent a ``Save Yourself
Done'' message yet, it can either abort the save and send  a
``Save  Yourself  Done'' with the success argument set to or
it can continue with the save and  send  a  ``Save  Yourself
Done''  with the success argument set to reflect the outcome
of the save.

[1m6.9.  Returning Properties[0m

In response to a ``Get  Properties''  message,  the  session
manager should call
__
||  void SmsReturnProperties([4msms_conn[24m, [4mnum_props[24m, [4mprops[24m)
    SmsConn [4msms_conn[24m;
    int [4mnum_props[24m;
    SmProp **[4mprops[24m;

[4msms_conn[24m  The session management connection object.

[4mnum_props[24m The number of properties.

[4mprops[24m     The list of properties to return to the client.
||__

The  properties  are returned as an array of property point-
ers.  For a description of session management properties and
the  structure,  see section 7, ``Session Management Proper-
ties.''

[1m6.10.  Pinging a Client[0m

To check that a client is still alive, you  should  use  the
function  provided  by  the  ICE library.  To do so, the ICE
connection must be obtained using  the  (see  section  6.12,
``Using Sms Informational Functions'').





                           - 31 -





[1mX Session Management Library                X11, Release 6.4[0m

__
||  void IcePing([4mice_conn[24m, [4mping_reply_proc[24m, [4mclient_data[24m)
    IceConn [4mice_conn[24m;
    IcePingReplyProc [4mping_reply_proc[24m;
    IcePointer [4mclient_data[24m;

[4mice_conn[24m  A valid ICE connection object.

[4mping_reply_proc[0m
          The  callback  to  invoke  when the Ping reply ar-
          rives.

[4mclient_data[0m
          This pointer will be passed to the callback.
||__

When the Ping reply is ready (if ever), the callback will be
invoked.  A session manager should have some sort of timeout
period, after which it assumes the client  has  unexpectedly
died.

__
||  typedef void (*IcePingReplyProc)();

void PingReplyProc([4mice_conn[24m, [4mclient_data[24m)
    IceConn [4mice_conn[24m;
    IcePointer [4mclient_data[24m;

[4mice_conn[24m  The ICE connection object.

[4mclient_data[0m
          The client data specified in the call to
||__


[1m6.11.  Cleaning Up After a Client Disconnects[0m

When  the  session  manager receives a ``Connection Closed''
message or otherwise detects that  the  client  aborted  the
connection,  it should call the function in order to free up
the connection object.
__
||  void SmsCleanUp([4msms_conn[24m)
    SmsConn [4msms_conn[24m;

[4msms_conn[24m  The session management connection object.
||__


[1m6.12.  Using Sms Informational Functions[0m

__
||  int SmsProtocolVersion([4msms_conn[24m)
    SmsConn [4msms_conn[24m;




                           - 32 -





[1mX Session Management Library                X11, Release 6.4[0m


||__

returns the major version of the session management protocol
associated with this session.


__
||  int SmsProtocolRevision([4msms_conn[24m)
    SmsConn [4msms_conn[24m;
||__

returns the minor version of the session management protocol
associated with this session.


__
||  char *SmsClientID([4msms_conn[24m)
    SmsConn [4msms_conn[24m;
||__

returns a null-terminated string for the client  ID  associ-
ated  with this connection.  You should call on this pointer
when the client ID is no longer needed.


To obtain the host name of a client, use This host name will
be needed to restart the client.
__
||  char *SmsClientHostName([4msms_conn[24m)
||__    SmsConn [4msms_conn[24m;

The  string returned is of the form [4mprotocol[24m/[4mhostname[24m, where
[4mprotocol[24m is one of {tcp, decnet, local}.  You should call on
the string returned when it is no longer needed.


__
||  IceConn SmsGetIceConnection([4msms_conn[24m)
||__    SmsConn [4msms_conn[24m;

returns  the ICE connection object associated with this ses-
sion management connection object.  The ICE  connection  ob-
ject  can  be  used to get some additional information about
the connection.  Some of the more useful functions which can
be  used on the IceConn are and For further information, see
the [4mInter-Client[24m [4mExchange[24m [4mLibrary[24m standard.

[1m6.13.  Error Handling[0m

If the session manager receives an unexpected protocol error
from  a client, an error handler is invoked by SMlib.  A de-
fault error handler exists which  simply  prints  the  error
message  (it does not exit).  The session manager can change




                           - 33 -





[1mX Session Management Library                X11, Release 6.4[0m


this error handler by calling
__
||  SmsErrorHandler SmsSetErrorHandler([4mhandler[24m)
    SmsErrorHandler [4mhandler[24m;

[4mhandler[24m   The error handler.  You should pass  NULL  to  re-
          store the default handler.
||__

returns  the  previous error handler.  The has the following
type:
__
||  typedef void (*SmsErrorHandler)();

void  ErrorHandler([4msms_conn[24m,  [4mswap[24m,  [4moffending_minor_opcode[24m,
[4moffending_sequence_num[24m, [4merror_class[24m, [4mseverity[24m, [4mvalues[24m)
    SmsConn [4msms_conn[24m;
    Bool [4mswap[24m;
    int [4moffending_minor_opcode[24m;
    unsigned long [4moffending_sequence_num[24m;
    int [4merror_class[24m;
    int [4mseverity[24m;
    IcePointer [4mvalues[24m;

[4msms_conn[24m  The session management connection object.

[4mswap[24m      A  flag  which  indicates  if the specified values
          need byte swapping.

[4moffending_minor_opcode[0m
          The minor opcode of the offending message.

[4moffending_sequence_num[0m
          The sequence number of the offending message.

[4merror_class[0m
          The error class of the offending message.

[4mseverity[24m  or

[4mvalues[24m    Any additional error values specific to the  minor
          opcode and class.
||__

Note that this error handler is invoked for protocol related
errors.  To install an error handler to be invoked  when  an
IO error occurs, use For further information, see the [4mInter-[0m
[4mClient[24m [4mExchange[24m [4mLibrary[24m standard.

[1m7.  Session Management Properties[0m

Each property is defined by the structure:





                           - 34 -





[1mX Session Management Library                X11, Release 6.4[0m


typedef struct {      char *name;         /* name  of  prop-
erty  */       char  *type;         /*  type  of property */
     int num_vals;   /* number of values */      SmPropValue
*vals;  /* the list of values */ } SmProp;

typedef  struct  {      int length;         /* the length of
the value */      SmPointer value;    /* the value */ }  Sm-
PropValue;

The  X  Session Management Protocol defines a list of prede-
fined properties, several of which are required to be set by
the  client.   The  following table specifies the predefined
properties and indicates  which  ones  are  required.   Each
property has a type associated with it.

A  type  of  SmCARD8 indicates that there is a single 1-byte
value.  A type of SmARRAY8 indicates that there is a  single
array  of  bytes.   A  type of SmLISTofARRAY8 indicates that
there is a list of array of bytes.


l l l c .  _
[1mName Type POSIX Type     Required[0m
_
SmCloneCommand OS-specific    SmLISTofARRAY8 Yes  SmCurrent-
Directory  OS-specific    SmARRAY8  No         SmDiscardCom-
mand    OS-specific    SmLISTofARRAY8 No* SmEnvironment  OS-
specific    SmLISTofARRAY8 No         SmProcessID    OS-spe-
cific    SmARRAY8  No SmProgram OS-specific    SmARRAY8  Yes
SmRestartCommand    OS-specific    SmLISTofARRAY8 Yes  SmRe-
signCommand     OS-specific    SmLISTofARRAY8 No  SmRestart-
StyleHint  SmCARD8   SmCARD8   No    SmShutdownCommand   OS-
specific    SmLISTofARRAY8 No      SmUserID  SmARRAY8  SmAR-
RAY8  Yes
_


*  Required if any state is stored in an external repository
(for example, state file).

+o    SmCloneCommand

     This is like the SmRestartCommand, except it restarts a
     copy  of  the application.  The only difference is that
     the application does not supply its client ID at regis-
     ter time.  On POSIX systems, this should be of type Sm-
     LISTofARRAY8.

+o    SmCurrentDirectory

     On POSIX-based systems, this specifies the value of the
     current  directory  that  needs  to  be set up prior to
     starting the SmProgram and should of type SmARRAY8.




                           - 35 -





[1mX Session Management Library                X11, Release 6.4[0m


+o    SmDiscardCommand

     The discard command contains a command that when deliv-
     ered  to the host that the client is running on (deter-
     mined from the connection), will cause  it  to  discard
     any  information about the current state.  If this com-
     mand is not specified, the Session Manager will  assume
     that  all  of  the client's state is encoded in the Sm-
     RestartCommand.  On POSIX systems, the type  should  be
     SmLISTofARRAY8.

+o    SmEnvironment

     On  POSIX  based systems, this will be of type SmLISTo-
     fARRAY8, where the ARRAY8s alternate  between  environ-
     ment variable name and environment variable value.

+o    SmProcessID

     This   specifies  an  OS-specific  identifier  for  the
     process.  On POSIX systems, this should contain the re-
     turn value of turned into a Latin-1 (decimal) string.

+o    SmProgram

     This  is  the  name of the program that is running.  On
     POSIX systems, this should be first parameter passed to
     and should be of type SmARRAY8.

+o    SmRestartCommand

     The  restart  command contains a command that, when de-
     livered to the host that the client is running on  (de-
     termined from the connection), will cause the client to
     restart in its current state.  On POSIX-based  systems,
     this  is  of  type SmLISTofARRAY8, and each of the ele-
     ments in the array represents an element in the  array.
     This  restart  command  should  ensure  that the client
     restarts with the specified client-ID.

+o    SmResignCommand

     A client that sets the SmRestartStyleHint to  SmRestar-
     tAnway uses this property to specify a command that un-
     does the effect of the client  and  removes  any  saved
     state.   As an example, consider a user that runs which
     registers with the  Session  Manager,  sets  SmRestart-
     StyleHint  to SmRestartAnyway, and then terminates.  To
     allow the Session Manager (at the  user's  request)  to
     undo this, would register a SmResignCommand that undoes
     the effects of the

+o    SmRestartStyleHint




                           - 36 -





[1mX Session Management Library                X11, Release 6.4[0m


     If the RestartStyleHint property is  present,  it  will
     contain the style of restarting the client prefers.  If
     this style is not specified, SmRestartIfRunning is  as-
     sumed.  The possible values are as follows:

     l n.  _
     [1mName Value[0m
     [1m_[0m
     SmRestartIfRunning  0  SmRestartAnyway     1  SmRestar-
     tImmediately     2 SmRestartNever 3
     _


     The SmRestartIfRunning style is used in the usual case.
     The  client  should be restarted in the next session if
     it was running at the end of the current session.

     The SmRestartAnyway style is used to tell  the  Session
     Manager that the application should be restarted in the
     next session even if it exits before the  current  ses-
     sion  is  terminated.   It should be noted that this is
     only a hint and the Session  Manager  will  follow  the
     policies specified by its users in determining what ap-
     plications to restart.

     A client that uses SmRestartAnyway should also set  the
     SmResignCommand  and  SmShutdownCommand  properties  to
     commands that undo the state of the client after it ex-
     its.

     The SmRestartImmediately style is like SmRestartAnyway,
     but, in addition, the client is meant to  run  continu-
     ously.  If the client exits, the Session Manager should
     try to restart it in the current session.

     SmRestartNever style specifies that the client does not
     wish to be restarted in the next session.

+o    SmShutdownCommand

     This  command  is executed at shutdown time to clean up
     after a client that is no longer running  but  retained
     its  state  by  setting SmRestartStyleHint to SmRestar-
     tAnyway.  The client must not remove any saved state as
     the  client  is still part of the session.  As an exam-
     ple, consider a client that turns on a camera at  start
     up time.  This client then exits.  At session shutdown,
     the user wants the  camera  turned  off.   This  client
     would set the SmRestartStyleHint to SmRestartAnyway and
     would register a SmShutdownCommand that would turn  off
     the camera.

+o    SmUserID




                           - 37 -





[1mX Session Management Library                X11, Release 6.4[0m


     Specifies  the  user  ID.  On POSIX-based systems, this
     will contain the user's name  (the  pw_name  member  of
     struct

[1m8.  Freeing Data[0m

To free an individual property, use
__
||  void SmFreeProperty([4mprop[24m)
    SmProp *[4mprop[24m;

[4mprop[24m      The property to free.
||__


To free the reason strings from the callback, use
__
||  void SmFreeReasons([4mcount[24m, [4mreasons[24m)
    int [4mcount[24m;
    char **[4mreasons[24m;

[4mcount[24m     The number of reason strings.

[4mreasons[24m   The list of reason strings to free.
||__


[1m9.  Authentication of Clients[0m

As  stated  earlier, the session management protocol is lay-
ered on top of ICE.  Authentication occurs at two levels  in
the ICE protocol:

+o    The first is when an ICE connection is opened.

+o    The  second  is  when a Protocol Setup occurs on an ICE
     connection.

The authentication methods that are available are  implemen-
tation-dependent  (that is., dependent on the ICElib and SM-
lib implementations in use).  For further  information,  see
the [4mInter-Client[24m [4mExchange[24m [4mLibrary[24m standard.

[1m10.  Working in a Multi-Threaded Environment[0m

To  declare  that multiple threads in an application will be
using SMlib (or any other library layered on top of ICElib),
you  should  call  For  further  information, see the [4mInter-[0m
[4mClient[24m [4mExchange[24m [4mLibrary[24m standard.

[1m11.  Acknowledgements[0m

Thanks to the following people for  their  participation  in
the  X Session Management design: Jordan Brown, Ellis Cohen,



                           - 38 -





[1mX Session Management Library                X11, Release 6.4[0m


Donna  Converse,  Stephen  Gildea,  Vania  Joloboff,  Stuart
Marks, Bob Scheifler, Ralph Swick, and Mike Wexler.























































                           - 39 -


