








                XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy

                        VVeerrssiioonn 11..00

                   XX CCoonnssoorrttiiuumm SSttaannddaarrdd

                 XX VVeerrssiioonn 1111,, RReelleeaassee 66..44

                         _R_a_l_p_h _M_o_r
                        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.














































































11..  OOvveerrvviieeww ooff SSeessssiioonn MMaannaaggeemmeenntt

The purpose of the X Session Management Protocol  (XSMP)  is
to provide a uniform mechanism for users to save and restore
their sessions.  A _s_e_s_s_i_o_n is a group of  clients,  each  of
which  has a particular state.  The session is controlled by
a network service called the _s_e_s_s_i_o_n _m_a_n_a_g_e_r.   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 _c_l_i_e_n_t 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.

22..  TThhee SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy

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
_n_e_s_t_e_d _s_e_s_s_i_o_n _m_a_n_a_g_e_r_s.  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 _c_l_i_e_n_t_-_I_D 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 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


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
example,  clients may use their client-ID as part of a file-
name in which to store the state for a particular instantia-
tion.   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.

33..  UUnnddeerrssttaannddiinngg SSMMlliibb''ss DDeeppeennddeennccee oonn IICCEE

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
appropriate protocol  library  will  then  be  triggered  to
unpack the message and hand it off to the client via a call-
back.

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
internally  make  a call into which will, in turn, determine
if an ICE connection already exists between the  client  and
session 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,
because  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



                            - 2 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


descriptors to call on.

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 _I_n_t_e_r_-_C_l_i_e_n_t _E_x_c_h_a_n_g_e _L_i_b_r_a_r_y stan-
dard.

44..  HHeeaaddeerr FFiilleess aanndd LLiibbrraarryy NNaammee

Applications (both  session  managers  and  clients)  should
include  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

55..  SSeessssiioonn MMaannaaggeemmeenntt CClliieenntt ((SSmmcc)) FFuunnccttiioonnss

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

55..11..  CCoonnnneeccttiinngg ttoo tthhee SSeessssiioonn MMaannaaggeerr

To open a connection with a session manager, use
__
||  SmcConn     SmcOpenConnection(_n_e_t_w_o_r_k___i_d_s___l_i_s_t,     _c_o_n_t_e_x_t,
_x_s_m_p___m_a_j_o_r___r_e_v, _x_s_m_p___m_i_n_o_r___r_e_v,



                            - 3 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


                    _m_a_s_k,       _c_a_l_l_b_a_c_k_s,      _p_r_e_v_i_o_u_s___i_d,
_c_l_i_e_n_t___i_d___r_e_t, _e_r_r_o_r___l_e_n_g_t_h, _e_r_r_o_r___s_t_r_i_n_g___r_e_t)
    char *_n_e_t_w_o_r_k___i_d_s___l_i_s_t;
    SmPointer _c_o_n_t_e_x_t;
    int _x_s_m_p___m_a_j_o_r___r_e_v;
    int _x_s_m_p___m_i_n_o_r___r_e_v;
    unsigned long _m_a_s_k;
    SmcCallbacks *_c_a_l_l_b_a_c_k_s;
    char *_p_r_e_v_i_o_u_s___i_d;
    char **_c_l_i_e_n_t___i_d___r_e_t;
    int _e_r_r_o_r___l_e_n_g_t_h;
    char *_e_r_r_o_r___s_t_r_i_n_g___r_e_t;

_n_e_t_w_o_r_k___i_d_s___l_i_s_t
          Specifies the network ID(s) of  the  session  man-
          ager.

_c_o_n_t_e_x_t   A  pointer  to  an opaque object or NULL.  Used to
          determine if an ICE connection can be shared  (see
          below).

_x_s_m_p___m_a_j_o_r___r_e_v
          The highest major version of the XSMP the applica-
          tion supports.

_x_s_m_p___m_i_n_o_r___r_e_v
          The highest minor version of the XSMP the applica-
          tion  supports (for the specified xsmp_major_rev).

_m_a_s_k      A mask indicating which callbacks to register.

_c_a_l_l_b_a_c_k_s The callbacks to register.   These  callbacks  are
          used  to respond to messages from the session man-
          ager.

_p_r_e_v_i_o_u_s___i_d
          The client ID from the previous session.

_c_l_i_e_n_t___i_d___r_e_t
          The client ID for the current session is returned.

_e_r_r_o_r___l_e_n_g_t_h
          Length of the error_string_ret argument passed in.

_e_r_r_o_r___s_t_r_i_n_g___r_e_t
          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



                            - 4 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


of the environment variable will be used.  Each  network  ID
has the following format:

lw(0.25i)                  lw(2.5i)                  lw(1i).
     tcp/<hostname>:<portnumber>   or
     decnet/<hostname>::<objname>  or
     local/<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
error_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
_I_n_t_e_r_-_C_l_i_e_n_t _E_x_c_h_a_n_g_e _L_i_b_r_a_r_y 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



                            - 5 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


argument is necessary in order to maintain backwards compat-
ibility in future versions of the library.

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;
          SmPointer client_data;      } die;

     struct    {             SmcSaveCompleteProc   callback;
          SmPointer client_data;      } save_complete;

     struct {            SmcShutdownCancelledProc  callback;
          SmPointer client_data;      } shutdown_cancelled;

} SmcCallbacks;
||__


55..11..11..  TThhee SSaavvee YYoouurrsseellff CCaallllbbaacckk

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

void   SaveYourselfProc(_s_m_c___c_o_n_n,   _c_l_i_e_n_t___d_a_t_a,  _s_a_v_e___t_y_p_e,
_s_h_u_t_d_o_w_n, _i_n_t_e_r_a_c_t___s_t_y_l_e, _f_a_s_t)
    SmcConn _s_m_c___c_o_n_n;
    SmPointer _c_l_i_e_n_t___d_a_t_a;
    int _s_a_v_e___t_y_p_e;
    Bool _s_h_u_t_d_o_w_n;
    int _i_n_t_e_r_a_c_t___s_t_y_l_e;
    Bool _f_a_s_t;

_s_m_c___c_o_n_n  The session management connection object.

_c_l_i_e_n_t___d_a_t_a
          Client data specified when the callback was regis-
          tered.

_s_a_v_e___t_y_p_e Specifies  the  type of information that should be
          saved.




                            - 6 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


_s_h_u_t_d_o_w_n  Specifies if a shutdown is taking place.

_i_n_t_e_r_a_c_t___s_t_y_l_e
          The type of interaction allowed with the user.

_f_a_s_t      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
reflect 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
     included 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



                            - 7 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


     file.   It  would  then  create  a  temporary file with
     information such as the current position of the  cursor
     and  what  file  is  being  edited.   Finally, it would
     update its SmRestartCommand property with enough infor-
     mation 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

55..11..22..  TThhee DDiiee CCaallllbbaacckk

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

void DieProc(_s_m_c___c_o_n_n, _c_l_i_e_n_t___d_a_t_a)
    SmcConn _s_m_c___c_o_n_n;
    SmPointer _c_l_i_e_n_t___d_a_t_a;

_s_m_c___c_o_n_n  The session management connection object.

_c_l_i_e_n_t___d_a_t_a
          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.

55..11..33..  TThhee SSaavvee CCoommpplleettee CCaallllbbaacckk

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

void SaveCompleteProc(_s_m_c___c_o_n_n, _c_l_i_e_n_t___d_a_t_a)
    SmcConn _s_m_c___c_o_n_n;
    SmPointer _c_l_i_e_n_t___d_a_t_a;

_s_m_c___c_o_n_n  The session management connection object.





                            - 8 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


_c_l_i_e_n_t___d_a_t_a
          Client data specified when the callback was regis-
          tered.
||__

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.

55..11..44..  TThhee SShhuuttddoowwnn CCaanncceelllleedd CCaallllbbaacckk

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

void ShutdownCancelledProc(_s_m_c___c_o_n_n, _c_l_i_e_n_t___d_a_t_a)
    SmcConn _s_m_c___c_o_n_n;
    SmPointer _c_l_i_e_n_t___d_a_t_a;

_s_m_c___c_o_n_n  The session management connection object.

_c_l_i_e_n_t___d_a_t_a
          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.

55..22..  CClloossiinngg tthhee CCoonnnneeccttiioonn

To close a connection with a session manager, use

__
||  SmcCloseStatus      SmcCloseConnection(_s_m_c___c_o_n_n,      _c_o_u_n_t,
_r_e_a_s_o_n___m_s_g_s)
    SmcConn _s_m_c___c_o_n_n;
    int _c_o_u_n_t;
    char **_r_e_a_s_o_n___m_s_g_s;

_s_m_c___c_o_n_n  The session management connection object.

_c_o_u_n_t     The number of reason messages.

_r_e_a_s_o_n___m_s_g_s
          The reasons for closing the connection.





                            - 9 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


||__

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
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.

55..33..  MMooddiiffyyiinngg CCaallllbbaacckkss

To modify callbacks set up in use
__
||  void SmcModifyCallbacks(_s_m_c___c_o_n_n, _m_a_s_k, _c_a_l_l_b_a_c_k_s)
    SmcConn _s_m_c___c_o_n_n;
    unsigned long _m_a_s_k;
    SmcCallbacks *_c_a_l_l_b_a_c_k_s;

_s_m_c___c_o_n_n  The session management connection object.

_m_a_s_k      A mask indicating which callbacks to modify.

_c_a_l_l_b_a_c_k_s The new callbacks.
||__

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






                           - 10 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


55..44..   SSeettttiinngg,,  DDeelleettiinngg,, aanndd RReettrriieevviinngg SSeessssiioonn MMaannaaggeemmeenntt
PPrrooppeerrttiieess

To set session management properties for this client, use
__
||  void SmcSetProperties(_s_m_c___c_o_n_n, _n_u_m___p_r_o_p_s, _p_r_o_p_s)
    SmcConn _s_m_c___c_o_n_n;
    int _n_u_m___p_r_o_p_s;
    SmProp **_p_r_o_p_s;

_s_m_c___c_o_n_n  The session management connection object.

_n_u_m___p_r_o_p_s The number of properties.

_p_r_o_p_s     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
using  the  function.   Note that the session manager is not
expected 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(_s_m_c___c_o_n_n, _n_u_m___p_r_o_p_s, _p_r_o_p___n_a_m_e_s)
    SmcConn _s_m_c___c_o_n_n;
    int _n_u_m___p_r_o_p_s;
    char **_p_r_o_p___n_a_m_e_s;

_s_m_c___c_o_n_n  The session management connection object.

_n_u_m___p_r_o_p_s The number of properties.

_p_r_o_p___n_a_m_e_s
          The list of properties to delete.
||__


To get properties previously stored by the client, use
__
||  Status      SmcGetProperties(_s_m_c___c_o_n_n,      _p_r_o_p___r_e_p_l_y___p_r_o_c,
_c_l_i_e_n_t___d_a_t_a)
    SmcConn _s_m_c___c_o_n_n;
    SmcPropReplyProc _p_r_o_p___r_e_p_l_y___p_r_o_c;
    SmPointer _c_l_i_e_n_t___d_a_t_a;





                           - 11 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


_s_m_c___c_o_n_n  The session management connection object.

_p_r_o_p___r_e_p_l_y___p_r_o_c
          The callback to be  invoked  when  the  properties
          reply comes back.

_c_l_i_e_n_t___d_a_t_a
          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(_s_m_c___c_o_n_n, _c_l_i_e_n_t___d_a_t_a, _n_u_m___p_r_o_p_s, _p_r_o_p_s)
    SmcConn _s_m_c___c_o_n_n;
    SmPointer _c_l_i_e_n_t___d_a_t_a;
    int _n_u_m___p_r_o_p_s;
    SmProp **_p_r_o_p_s;

_s_m_c___c_o_n_n  The session management connection object.

_c_l_i_e_n_t___d_a_t_a
          Client data specified when the callback was regis-
          tered.

_n_u_m___p_r_o_p_s The number of properties returned.

_p_r_o_p_s     The list of properties returned.
||__

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

55..55..  IInntteerraaccttiinngg WWiitthh tthhee UUsseerr

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(_s_m_c___c_o_n_n,       _d_i_a_l_o_g___t_y_p_e,
_i_n_t_e_r_a_c_t___p_r_o_c, _c_l_i_e_n_t___d_a_t_a)
    SmcConn _s_m_c___c_o_n_n;
    int _d_i_a_l_o_g___t_y_p_e;
    SmcInteractProc _i_n_t_e_r_a_c_t___p_r_o_c;
    SmPointer _c_l_i_e_n_t___d_a_t_a;



                           - 12 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


_s_m_c___c_o_n_n  The session management connection object.

_d_i_a_l_o_g___t_y_p_e
          The type of dialog the client wishes to present to
          the user.

_i_n_t_e_r_a_c_t___p_r_o_c
          The  callback  to be invoked when the ``Interact''
          message arrives from the session manager.

_c_l_i_e_n_t___d_a_t_a
          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(_s_m_c___c_o_n_n, _c_l_i_e_n_t___d_a_t_a)
    SmcConn _s_m_c___c_o_n_n;
    SmPointer _c_l_i_e_n_t___d_a_t_a;

_s_m_c___c_o_n_n  The session management connection object.

_c_l_i_e_n_t___d_a_t_a
          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(_s_m_c___c_o_n_n, _c_a_n_c_e_l___s_h_u_t_d_o_w_n)
    SmcConn _s_m_c___c_o_n_n;
    Bool _c_a_n_c_e_l___s_h_u_t_d_o_w_n;

_s_m_c___c_o_n_n  The session management connection object.




                           - 13 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


_c_a_n_c_e_l___s_h_u_t_d_o_w_n
          If  indicates  that  the  user  requests  that the
          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.

55..66..  RReeqquueessttiinngg aa SSaavvee YYoouurrsseellff

To request a checkpoint from the session manager, use
__
||  void SmcRequestSaveYourself(_s_m_c___c_o_n_n,  _s_a_v_e___t_y_p_e,  _s_h_u_t_d_o_w_n,
_i_n_t_e_r_a_c_t___s_t_y_l_e, _f_a_s_t, _g_l_o_b_a_l)
    SmcConn _s_m_c___c_o_n_n;
    int _s_a_v_e___t_y_p_e;
    Bool _s_h_u_t_d_o_w_n;
    int _i_n_t_e_r_a_c_t___s_t_y_l_e;
    Bool _f_a_s_t;
    Bool _g_l_o_b_a_l;

_s_m_c___c_o_n_n  The session management connection object.

_s_a_v_e___t_y_p_e Specifies  the  type of information that should be
          saved.

_s_h_u_t_d_o_w_n  Specifies if a shutdown is taking place.

_i_n_t_e_r_a_c_t___s_t_y_l_e
          The type of interaction allowed with the user.

_f_a_s_t      If the client should save its state as quickly  as
          possible.

_g_l_o_b_a_l    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
include 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.






                           - 14 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


55..77..  RReeqquueessttiinngg aa SSaavvee YYoouurrsseellff PPhhaassee 22

In  response to a ``Save Yourself, the client may request to
be informed when all the other clients are quiescent so that
it can save their state.  To do so, use
__
||  Status                SmcRequestSaveYourselfPhase2(_s_m_c___c_o_n_n,
_s_a_v_e___y_o_u_r_s_e_l_f___p_h_a_s_e_2___p_r_o_c, _c_l_i_e_n_t___d_a_t_a)
    SmcConn _s_m_c___c_o_n_n;
    SmcSaveYourselfPhase2Proc _s_a_v_e___y_o_u_r_s_e_l_f___p_h_a_s_e_2___p_r_o_c;
    SmPointer _c_l_i_e_n_t___d_a_t_a;

_s_m_c___c_o_n_n  The session management connection object.

_s_a_v_e___y_o_u_r_s_e_l_f___p_h_a_s_e_2___p_r_o_c
          The callback to be invoked when the  ``Save  Your-
          self  Phase  2''  message arrives from the session
          manager.

_c_l_i_e_n_t___d_a_t_a
          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.

55..88..  CCoommpplleettiinngg aa SSaavvee YYoouurrsseellff

After  saving  state in response to a ``Save Yourself'' mes-
sage, you should call
__
||  void SmcSaveYourselfDone(_s_m_c___c_o_n_n, _s_u_c_c_e_s_s)
    SmcConn _s_m_c___c_o_n_n;
    Bool _s_u_c_c_e_s_s;

_s_m_c___c_o_n_n  The session management connection object.

_s_u_c_c_e_s_s   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.





                           - 15 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


55..99..  UUssiinngg SSmmcc IInnffoorrmmaattiioonnaall FFuunnccttiioonnss

__
||  int SmcProtocolVersion(_s_m_c___c_o_n_n)
||__    SmcConn _s_m_c___c_o_n_n;

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


__
||  int SmcProtocolRevision(_s_m_c___c_o_n_n)
||__    SmcConn _s_m_c___c_o_n_n;

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


__
||  char *SmcVendor(_s_m_c___c_o_n_n)
||__    SmcConn _s_m_c___c_o_n_n;

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(_s_m_c___c_o_n_n)
||__    SmcConn _s_m_c___c_o_n_n;

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


__
||  char *SmcClientID(_s_m_c___c_o_n_n)
||__    SmcConn _s_m_c___c_o_n_n;

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


__
||  IceConn SmcGetIceConnection(_s_m_c___c_o_n_n)
||__    SmcConn _s_m_c___c_o_n_n;

returns  the ICE connection object associated with this ses-
sion  management  connection  object.   The  ICE  connection
object  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



                           - 16 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


the _I_n_t_e_r_-_C_l_i_e_n_t _E_x_c_h_a_n_g_e _L_i_b_r_a_r_y standard.

55..1100..  EErrrroorr HHaannddlliinngg

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(_h_a_n_d_l_e_r)
    SmcErrorHandler _h_a_n_d_l_e_r;

_h_a_n_d_l_e_r   The  error  handler.   You  should  pass  NULL  to
          restore the default handler.
||__

returns the previous error handler.

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

void  ErrorHandler(_s_m_c___c_o_n_n,  _s_w_a_p,  _o_f_f_e_n_d_i_n_g___m_i_n_o_r___o_p_c_o_d_e,
_o_f_f_e_n_d_i_n_g___s_e_q_u_e_n_c_e___n_u_m, _e_r_r_o_r___c_l_a_s_s, _s_e_v_e_r_i_t_y, _v_a_l_u_e_s)
    SmcConn _s_m_c___c_o_n_n;
    Bool _s_w_a_p;
    int _o_f_f_e_n_d_i_n_g___m_i_n_o_r___o_p_c_o_d_e;
    unsigned long _o_f_f_e_n_d_i_n_g___s_e_q_u_e_n_c_e___n_u_m;
    int _e_r_r_o_r___c_l_a_s_s;
    int _s_e_v_e_r_i_t_y;
    IcePointer _v_a_l_u_e_s;

_s_m_c___c_o_n_n  The session management connection object.

_s_w_a_p      A flag that indicates if the specified values need
          byte swapping.

_o_f_f_e_n_d_i_n_g___m_i_n_o_r___o_p_c_o_d_e
          The minor opcode of the offending message.

_o_f_f_e_n_d_i_n_g___s_e_q_u_e_n_c_e___n_u_m
          The sequence number of the offending message.

_e_r_r_o_r___c_l_a_s_s
          The error class of the offending message.

_s_e_v_e_r_i_t_y  or

_v_a_l_u_e_s    Any additional error values specific to the  minor
          opcode and class.





                           - 17 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


||__

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 _I_n_t_e_r_-
_C_l_i_e_n_t _E_x_c_h_a_n_g_e _L_i_b_r_a_r_y standard.

66..  SSeessssiioonn MMaannaaggeemmeenntt SSeerrvveerr ((SSmmss)) FFuunnccttiioonnss

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

66..11..  IInniittiiaalliizziinngg tthhee LLiibbrraarryy

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(_v_e_n_d_o_r,   _r_e_l_e_a_s_e,   _n_e_w___c_l_i_e_n_t___p_r_o_c,
_m_a_n_a_g_e_r___d_a_t_a, _h_o_s_t___b_a_s_e_d___a_u_t_h___p_r_o_c,
                    _e_r_r_o_r___l_e_n_g_t_h, _e_r_r_o_r___s_t_r_i_n_g___r_e_t)
    char *_v_e_n_d_o_r;
    char *_r_e_l_e_a_s_e;
    SmsNewClientProc _n_e_w___c_l_i_e_n_t___p_r_o_c;
    SmPointer _m_a_n_a_g_e_r___d_a_t_a;
    IceHostBasedAuthProc _h_o_s_t___b_a_s_e_d___a_u_t_h___p_r_o_c;
    int _e_r_r_o_r___l_e_n_g_t_h;
    char *_e_r_r_o_r___s_t_r_i_n_g___r_e_t;



                           - 18 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


_v_e_n_d_o_r    A string specifying the session manager vendor.

_r_e_l_e_a_s_e   A string specifying the  session  manager  release
          number.

_n_e_w___c_l_i_e_n_t___p_r_o_c
          Callback to be invoked each time a new client con-
          nects to the session manager.

_m_a_n_a_g_e_r___d_a_t_a
          When the callback is invoked, this pointer to man-
          ager data will be passed.

_h_o_s_t___b_a_s_e_d___a_u_t_h___p_r_o_c
          Host based authentication callback.

_e_r_r_o_r___l_e_n_g_t_h
          Length of the error_string_ret argument passed in.

_e_r_r_o_r___s_t_r_i_n_g___r_e_t
          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
details on authentication (including host based  authentica-
tion).   Also see the _I_n_t_e_r_-_C_l_i_e_n_t _E_x_c_h_a_n_g_e _L_i_b_r_a_r_y 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(_s_m_s___c_o_n_n,   _m_a_n_a_g_e_r___d_a_t_a,   _m_a_s_k___r_e_t,
_c_a_l_l_b_a_c_k_s___r_e_t, _f_a_i_l_u_r_e___r_e_a_s_o_n___r_e_t)
    SmsConn _s_m_s___c_o_n_n;
    SmPointer _m_a_n_a_g_e_r___d_a_t_a;
    unsigned long *_m_a_s_k___r_e_t;
    SmsCallbacks *_c_a_l_l_b_a_c_k_s___r_e_t;
    char **_f_a_i_l_u_r_e___r_e_a_s_o_n___r_e_t;





                           - 19 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


_s_m_s___c_o_n_n  A new opaque connection object.

_m_a_n_a_g_e_r___d_a_t_a
          Manager  data specified when the callback was reg-
          istered.

_m_a_s_k___r_e_t  On return, indicates which callbacks were  set  by
          the session manager.

_c_a_l_l_b_a_c_k_s___r_e_t
          On  return,  contains  the callbacks registered by
          the session manager.

_f_a_i_l_u_r_e___r_e_a_s_o_n___r_e_t
          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
respond 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_request;

     struct   {             SmsSaveYourselfPhase2RequestProc



                           - 20 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


callback;               SmPointer    manager_data;         }
save_yourself_phase2_request;

     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;
||__


66..11..11..  TThhee RReeggiisstteerr CClliieenntt CCaallllbbaacckk

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(_s_m_s___c_o_n_n,       _m_a_n_a_g_e_r___d_a_t_a,
_p_r_e_v_i_o_u_s___i_d)
    SmsConn _s_m_s___c_o_n_n;
    SmPointer _m_a_n_a_g_e_r___d_a_t_a;
    char *_p_r_e_v_i_o_u_s___i_d;

_s_m_s___c_o_n_n  The session management connection object.

_m_a_n_a_g_e_r___d_a_t_a
          Manager  data specified when the callback was reg-
          istered.

_p_r_e_v_i_o_u_s___i_d
          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



                           - 21 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


NULL.

If previous_id is invalid, the session  manager  should  not
register  the  client  at  this  time.  This callback should
return 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.

66..11..22..  TThhee IInntteerraacctt RReeqquueesstt CCaallllbbaacckk

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

void       InteractRequestProc(_s_m_s___c_o_n_n,       _m_a_n_a_g_e_r___d_a_t_a,
_d_i_a_l_o_g___t_y_p_e)
    SmsConn _s_m_s___c_o_n_n;
    SmPointer _m_a_n_a_g_e_r___d_a_t_a;
    int _d_i_a_l_o_g___t_y_p_e;

_s_m_s___c_o_n_n  The session management connection object.

_m_a_n_a_g_e_r___d_a_t_a
          Manager data specified when the callback was  reg-
          istered.

_d_i_a_l_o_g___t_y_p_e
          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 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


66..11..33..  TThhee IInntteerraacctt DDoonnee CCaallllbbaacckk

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

void        InteractDoneProc(_s_m_s___c_o_n_n,         _m_a_n_a_g_e_r___d_a_t_a,
_c_a_n_c_e_l___s_h_u_t_d_o_w_n)
    SmsConn _s_m_s___c_o_n_n;
    SmPointer _m_a_n_a_g_e_r___d_a_t_a;
    Bool _c_a_n_c_e_l___s_h_u_t_d_o_w_n;

_s_m_s___c_o_n_n  The session management connection object.

_m_a_n_a_g_e_r___d_a_t_a
          Manager  data specified when the callback was reg-
          istered.

_c_a_n_c_e_l___s_h_u_t_d_o_w_n
          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.

66..11..44..  TThhee SSaavvee YYoouurrsseellff RReeqquueesstt CCaallllbbaacckk

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

void     SaveYourselfRequestProc(_s_m_s___c_o_n_n,     _m_a_n_a_g_e_r___d_a_t_a,
_s_a_v_e___t_y_p_e, _s_h_u_t_d_o_w_n, _i_n_t_e_r_a_c_t___s_t_y_l_e, _f_a_s_t, _g_l_o_b_a_l)
    SmsConn _s_m_s___c_o_n_n;
    SmPointer _m_a_n_a_g_e_r___d_a_t_a;
    int _s_a_v_e___t_y_p_e;
    Bool _s_h_u_t_d_o_w_n;
    int _i_n_t_e_r_a_c_t___s_t_y_l_e;
    Bool _f_a_s_t;
    Bool _g_l_o_b_a_l;

_s_m_s___c_o_n_n  The session management connection object.

_m_a_n_a_g_e_r___d_a_t_a
          Manager data specified when the callback was  reg-
          istered.

_s_a_v_e___t_y_p_e Specifies  the  type of information that should be
          saved.





                           - 23 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


_s_h_u_t_d_o_w_n  Specifies if a shutdown is taking place.

_i_n_t_e_r_a_c_t___s_t_y_l_e
          The type of interaction allowed with the user.

_f_a_s_t      If the client should save its state as quickly  as
          possible.

_g_l_o_b_a_l    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.

66..11..55..  TThhee SSaavvee YYoouurrsseellff PPhhaassee 22 RReeqquueesstt CCaallllbbaacckk

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

void              SmsSaveYourselfPhase2RequestProc(_s_m_s___c_o_n_n,
_m_a_n_a_g_e_r___d_a_t_a)
    SmsConn _s_m_s___c_o_n_n;
    SmPointer _m_a_n_a_g_e_r___d_a_t_a;

_s_m_s___c_o_n_n  The session management connection object.

_m_a_n_a_g_e_r___d_a_t_a
          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.

66..11..66..  TThhee SSaavvee YYoouurrsseellff DDoonnee CCaallllbbaacckk

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

void SaveYourselfDoneProc(_s_m_s___c_o_n_n, _m_a_n_a_g_e_r___d_a_t_a, _s_u_c_c_e_s_s)
    SmsConn _s_m_s___c_o_n_n;



                           - 24 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


    SmPointer _m_a_n_a_g_e_r___d_a_t_a;
    Bool _s_u_c_c_e_s_s;

_s_m_s___c_o_n_n  The session management connection object.

_m_a_n_a_g_e_r___d_a_t_a
          Manager  data specified when the callback was reg-
          istered.

_s_u_c_c_e_s_s   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.

66..11..77..  TThhee CCoonnnneeccttiioonn CClloosseedd CCaallllbbaacckk

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

void  CloseConnectionProc(_s_m_s___c_o_n_n,   _m_a_n_a_g_e_r___d_a_t_a,   _c_o_u_n_t,
_r_e_a_s_o_n___m_s_g_s)
    SmsConn _s_m_s___c_o_n_n;
    SmPointer _m_a_n_a_g_e_r___d_a_t_a;
    int _c_o_u_n_t;
    char **_r_e_a_s_o_n___m_s_g_s;

_s_m_s___c_o_n_n  The session management connection object.

_m_a_n_a_g_e_r___d_a_t_a
          Manager  data specified when the callback was reg-
          istered.

_c_o_u_n_t     The number of reason messages.

_r_e_a_s_o_n___m_s_g_s
          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 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


66..11..88..  TThhee SSeett PPrrooppeerrttiieess CCaallllbbaacckk

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

void  SetPropertiesProc(_s_m_s___c_o_n_n,  _m_a_n_a_g_e_r___d_a_t_a,  _n_u_m___p_r_o_p_s,
_p_r_o_p_s)
    SmsConn _s_m_s___c_o_n_n;
    SmPointer _m_a_n_a_g_e_r___d_a_t_a;
    int _n_u_m___p_r_o_p_s;
    SmProp **_p_r_o_p_s;

_s_m_c___c_o_n_n  The session management connection object.

_m_a_n_a_g_e_r___d_a_t_a
          Manager data specified when the callback was  reg-
          istered.

_n_u_m___p_r_o_p_s The number of properties.

_p_r_o_p_s     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

66..11..99..  TThhee DDeelleettee PPrrooppeerrttiieess CCaallllbbaacckk

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

void DeletePropertiesProc(_s_m_s___c_o_n_n, _m_a_n_a_g_e_r___d_a_t_a, _n_u_m___p_r_o_p_s,
_p_r_o_p___n_a_m_e_s)
    SmsConn _s_m_s___c_o_n_n;
    SmPointer _m_a_n_a_g_e_r___d_a_t_a;
    int _n_u_m___p_r_o_p_s;
    char **_p_r_o_p___n_a_m_e_s;

_s_m_c___c_o_n_n  The session management connection object.




                           - 26 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


_m_a_n_a_g_e_r___d_a_t_a
          Manager data specified when the callback was  reg-
          istered.

_n_u_m___p_r_o_p_s The number of properties.

_p_r_o_p___n_a_m_e_s
          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.''

66..11..1100..  TThhee GGeett PPrrooppeerrttiieess CCaallllbbaacckk

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

void GetPropertiesProc(_s_m_s___c_o_n_n, _m_a_n_a_g_e_r___d_a_t_a)
    SmsConn _s_m_s___c_o_n_n;
    SmPointer _m_a_n_a_g_e_r___d_a_t_a;

_s_m_c___c_o_n_n  The session management connection object.

_m_a_n_a_g_e_r___d_a_t_a
          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.

66..22..  RReeggiisstteerriinngg tthhee CClliieenntt

To register a client (in response to a callback), use
__
||  Status SmsRegisterClientReply(_s_m_s___c_o_n_n, _c_l_i_e_n_t___i_d)
    SmsConn _s_m_s___c_o_n_n;
    char *_c_l_i_e_n_t___i_d;

_s_m_s___c_o_n_n  The session management connection object.

_c_l_i_e_n_t___i_d 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 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


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(_s_m_s___c_o_n_n)
    SmsConn _s_m_s___c_o_n_n;

_s_m_s___c_o_n_n  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.

66..33..  SSeennddiinngg aa SSaavvee YYoouurrsseellff MMeessssaaggee

To send a ``Save Yourself'' to a client, use
__
||  void    SmsSaveYourself(_s_m_s___c_o_n_n,    _s_a_v_e___t_y_p_e,    _s_h_u_t_d_o_w_n,
_i_n_t_e_r_a_c_t___s_t_y_l_e, _f_a_s_t)
    SmsConn _s_m_s___c_o_n_n;
    int _s_a_v_e___t_y_p_e;
    Bool _s_h_u_t_d_o_w_n;
    int _i_n_t_e_r_a_c_t___s_t_y_l_e;
    Bool _f_a_s_t;

_s_m_s___c_o_n_n  The session management connection object.

_s_a_v_e___t_y_p_e Specifies  the  type of information that should be
          saved.

_s_h_u_t_d_o_w_n  Specifies if a shutdown is taking place.





                           - 28 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


_i_n_t_e_r_a_c_t___s_t_y_l_e
          The type of interaction allowed with the user.

_f_a_s_t      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
reflect 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 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


66..44..  SSeennddiinngg aa SSaavvee YYoouurrsseellff PPhhaassee 22 MMeessssaaggee

In  order  to  send a ``Save Yourself Phase 2'' message to a
client, use
__
||  void SmsSaveYourselfPhase2(_s_m_s___c_o_n_n)
    SmsConn _s_m_s___c_o_n_n;

_s_m_s___c_o_n_n  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
associated with other clients.

66..55..  SSeennddiinngg aann IInntteerraacctt MMeessssaaggee

To send an ``Interact'' message to a client, use
__
||  void SmsInteract(_s_m_s___c_o_n_n)
    SmsConn _s_m_s___c_o_n_n;

_s_m_s___c_o_n_n  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.

66..66..  SSeennddiinngg aa SSaavvee CCoommpplleettee MMeessssaaggee

To send a ``Save Complete'' message to a client, use
__
||  void SmsSaveComplete(_s_m_s___c_o_n_n)
    SmsConn _s_m_s___c_o_n_n;

_s_m_s___c_o_n_n  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.

66..77..  SSeennddiinngg aa DDiiee MMeessssaaggee

To send a ``Die'' message to a client, use
__
||  void SmsDie(_s_m_s___c_o_n_n)
    SmsConn _s_m_s___c_o_n_n;

_s_m_s___c_o_n_n  The session management connection object.




                           - 30 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


||__

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.

66..88..  CCaanncceelllliinngg aa SShhuuttddoowwnn

To cancel a shutdown, use
__
||  void SmsShutdownCancelled(_s_m_s___c_o_n_n)
    SmsConn _s_m_s___c_o_n_n;

_s_m_s___c_o_n_n  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.

66..99..  RReettuurrnniinngg PPrrooppeerrttiieess

In  response  to  a  ``Get Properties'' message, the session
manager should call
__
||  void SmsReturnProperties(_s_m_s___c_o_n_n, _n_u_m___p_r_o_p_s, _p_r_o_p_s)
    SmsConn _s_m_s___c_o_n_n;
    int _n_u_m___p_r_o_p_s;
    SmProp **_p_r_o_p_s;

_s_m_s___c_o_n_n  The session management connection object.

_n_u_m___p_r_o_p_s The number of properties.

_p_r_o_p_s     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.''

66..1100..  PPiinnggiinngg aa CClliieenntt

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 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44

__
||  void IcePing(_i_c_e___c_o_n_n, _p_i_n_g___r_e_p_l_y___p_r_o_c, _c_l_i_e_n_t___d_a_t_a)
    IceConn _i_c_e___c_o_n_n;
    IcePingReplyProc _p_i_n_g___r_e_p_l_y___p_r_o_c;
    IcePointer _c_l_i_e_n_t___d_a_t_a;

_i_c_e___c_o_n_n  A valid ICE connection object.

_p_i_n_g___r_e_p_l_y___p_r_o_c
          The  callback  to  invoke  when  the  Ping   reply
          arrives.

_c_l_i_e_n_t___d_a_t_a
          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(_i_c_e___c_o_n_n, _c_l_i_e_n_t___d_a_t_a)
    IceConn _i_c_e___c_o_n_n;
    IcePointer _c_l_i_e_n_t___d_a_t_a;

_i_c_e___c_o_n_n  The ICE connection object.

_c_l_i_e_n_t___d_a_t_a
          The client data specified in the call to
||__


66..1111..  CClleeaanniinngg UUpp AAfftteerr aa CClliieenntt DDiissccoonnnneeccttss

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(_s_m_s___c_o_n_n)
    SmsConn _s_m_s___c_o_n_n;

_s_m_s___c_o_n_n  The session management connection object.
||__


66..1122..  UUssiinngg SSmmss IInnffoorrmmaattiioonnaall FFuunnccttiioonnss

__
||  int SmsProtocolVersion(_s_m_s___c_o_n_n)
    SmsConn _s_m_s___c_o_n_n;




                           - 32 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


||__

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


__
||  int SmsProtocolRevision(_s_m_s___c_o_n_n)
    SmsConn _s_m_s___c_o_n_n;
||__

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


__
||  char *SmsClientID(_s_m_s___c_o_n_n)
    SmsConn _s_m_s___c_o_n_n;
||__

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(_s_m_s___c_o_n_n)
||__    SmsConn _s_m_s___c_o_n_n;

The string returned is of the form _p_r_o_t_o_c_o_l/_h_o_s_t_n_a_m_e,  where
_p_r_o_t_o_c_o_l is one of {tcp, decnet, local}.  You should call on
the string returned when it is no longer needed.


__
||  IceConn SmsGetIceConnection(_s_m_s___c_o_n_n)
||__    SmsConn _s_m_s___c_o_n_n;

returns the ICE connection object associated with this  ses-
sion  management  connection  object.   The  ICE  connection
object 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 _I_n_t_e_r_-_C_l_i_e_n_t _E_x_c_h_a_n_g_e _L_i_b_r_a_r_y standard.

66..1133..  EErrrroorr HHaannddlliinngg

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




                           - 33 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


this error handler by calling
__
||  SmsErrorHandler SmsSetErrorHandler(_h_a_n_d_l_e_r)
    SmsErrorHandler _h_a_n_d_l_e_r;

_h_a_n_d_l_e_r   The  error  handler.   You  should  pass  NULL  to
          restore the default handler.
||__

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

void  ErrorHandler(_s_m_s___c_o_n_n,  _s_w_a_p,  _o_f_f_e_n_d_i_n_g___m_i_n_o_r___o_p_c_o_d_e,
_o_f_f_e_n_d_i_n_g___s_e_q_u_e_n_c_e___n_u_m, _e_r_r_o_r___c_l_a_s_s, _s_e_v_e_r_i_t_y, _v_a_l_u_e_s)
    SmsConn _s_m_s___c_o_n_n;
    Bool _s_w_a_p;
    int _o_f_f_e_n_d_i_n_g___m_i_n_o_r___o_p_c_o_d_e;
    unsigned long _o_f_f_e_n_d_i_n_g___s_e_q_u_e_n_c_e___n_u_m;
    int _e_r_r_o_r___c_l_a_s_s;
    int _s_e_v_e_r_i_t_y;
    IcePointer _v_a_l_u_e_s;

_s_m_s___c_o_n_n  The session management connection object.

_s_w_a_p      A flag which indicates  if  the  specified  values
          need byte swapping.

_o_f_f_e_n_d_i_n_g___m_i_n_o_r___o_p_c_o_d_e
          The minor opcode of the offending message.

_o_f_f_e_n_d_i_n_g___s_e_q_u_e_n_c_e___n_u_m
          The sequence number of the offending message.

_e_r_r_o_r___c_l_a_s_s
          The error class of the offending message.

_s_e_v_e_r_i_t_y  or

_v_a_l_u_e_s    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 _I_n_t_e_r_-
_C_l_i_e_n_t _E_x_c_h_a_n_g_e _L_i_b_r_a_r_y standard.

77..  SSeessssiioonn MMaannaaggeemmeenntt PPrrooppeerrttiieess

Each property is defined by the structure:





                           - 34 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


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 */ }
SmPropValue;

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 .  _
NNaammee TTyyppee PPOOSSIIXX TTyyppee     RReeqquuiirreedd
_
SmCloneCommand OS-specific    SmLISTofARRAY8 Yes
SmCurrentDirectory  OS-specific    SmARRAY8  No
SmDiscardCommand    OS-specific    SmLISTofARRAY8 No*
SmEnvironment  OS-specific    SmLISTofARRAY8 No
SmProcessID    OS-specific    SmARRAY8  No
SmProgram OS-specific    SmARRAY8  Yes
SmRestartCommand    OS-specific    SmLISTofARRAY8 Yes
SmResignCommand     OS-specific    SmLISTofARRAY8 No
SmRestartStyleHint  SmCARD8   SmCARD8   No
SmShutdownCommand   OS-specific    SmLISTofARRAY8 No
SmUserID  SmARRAY8  SmARRAY8  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
     SmLISTofARRAY8.

+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 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


+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
     SmRestartCommand.  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 pro-
     cess.  On POSIX systems, this should contain the return
     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
     delivered to the host that the  client  is  running  on
     (determined from the connection), will cause the client
     to restart in its current state.  On  POSIX-based  sys-
     tems,  this  is of type SmLISTofARRAY8, and each of the
     elements 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
     undoes 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 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


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

     l n.  _
     NNaammee VVaalluuee
     __
     SmRestartIfRunning  0             SmRestartAnyway     1
     SmRestartImmediately     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
     applications 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
     exits.

     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 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


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

88..  FFrreeeeiinngg DDaattaa

To free an individual property, use
__
||  void SmFreeProperty(_p_r_o_p)
    SmProp *_p_r_o_p;

_p_r_o_p      The property to free.
||__


To free the reason strings from the callback, use
__
||  void SmFreeReasons(_c_o_u_n_t, _r_e_a_s_o_n_s)
    int _c_o_u_n_t;
    char **_r_e_a_s_o_n_s;

_c_o_u_n_t     The number of reason strings.

_r_e_a_s_o_n_s   The list of reason strings to free.
||__


99..  AAuutthheennttiiccaattiioonn ooff CClliieennttss

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
SMlib implementations in use).  For further information, see
the _I_n_t_e_r_-_C_l_i_e_n_t _E_x_c_h_a_n_g_e _L_i_b_r_a_r_y standard.

1100..  WWoorrkkiinngg iinn aa MMuullttii--TThhrreeaaddeedd EEnnvviirroonnmmeenntt

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 _I_n_t_e_r_-
_C_l_i_e_n_t _E_x_c_h_a_n_g_e _L_i_b_r_a_r_y standard.

1111..  AAcckknnoowwlleeddggeemmeennttss

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



                           - 38 -





XX SSeessssiioonn MMaannaaggeemmeenntt LLiibbrraarryy                XX1111,, RReelleeaassee 66..44


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























































                           - 39 -


