Communicating with the session manager

SCO OpenServer system users expect to be able to end a session without first terminating applications. When the session is resumed, users expect to see applications exactly where they were at shutdown. The session manager is responsible for gracefully shutting down all applications at the end of a session, then restarting them when a new session begins. Your application should supply the session manager with the information needed to restart it in the state it was in when the user logged out.

Restart information is conveyed to the session manager through the WM_COMMAND property placed on an application's top-level window. Before ending a session, the session manager will send a WM_SAVE_YOURSELF message to applications. When your application receives this message, it must immediately prepare itself for shutdown by placing itself in an appropriate state, then setting the WM_COMMAND property to a command that will restart the application and restore it to as similar a state as possible. No interaction with the user is permitted during this process. When the next session begins, the session manager will restart your application with the specified command. It will also restore the application's geometry and window state (iconified or maximized) if the application does not.

For example, after receiving a WM_SAVE_YOURSELF message, a text editor might save edits made to the file letter since the last user-initiated save in a temporary file named letter.tmp. It could then use XSetCommand(XS) to set WM_COMMAND to something like editor -rt letter.tmp. When the session is resumed, the session manager will restart the editor with this command. The editor has defined the -rt option to read in the indicated temporary file, and perhaps display a message that there are unsaved edits left over from the previous session. Note that the editor could not ask the user whether it should save the unsaved edits, because no interaction with the user is permitted between receiving the WM_SAVE_YOURSELF message and shutdown.

If your application does not communicate with the session manager, the session manager will simply disconnect your application from the server at shutdown. Unsaved data may be lost. When the session is resumed, your application will be restarted with the command with which it was last started, and with the geometry and window state (iconized or maximized) it had at shutdown. Its state at shutdown will not be restored.

The session manager will restore a DOS or UNIX terminal window with the command that opened it. If a character-based application was started inside one of these windows after the window was opened, the application will not be restored. If the application was started as an argument to the scoterm command, it will be restarted with that same argument. The application's state at shutdown will not be restored.

To communicate with the session manager:

1. Use standard Xt intrinsics calls to start your application.

   When you use standard Xt intrinsics calls to start your application, the properties WM_COMMAND and WM_CLIENT_MACHINE are placed on your top-level window, WM_COMMAND is set to your startup command, and WM_CLIENT_MACHINE is set to the name of the machine on which your application is running.

2. Place the atom WM_SAVE_YOURSELF in the WM_PROTOCOLS property on your application's top-level window.

   To do this, include the following in your application's code.

     1 #include <X11/Intrinsic.h>
     2 #include <X11/Protocols.h>
     3 #include <X11/AtomMgr.h>
     4 #include <X11/Xatom.h>
      
   
     5 void
     6 SetupSMProtocols(toplevel)
     7 Widget  toplevel;
     8 {
     9         extern  void    SaveYourselfCB();
      
   
    10         Atom    protocols[1];
    11         Atom    xa_WM_SAVE_YOURSELF;
      
   
    12         xa_WM_SAVE_YOURSELF = XmInternAtom(XtDisplay(toplevel),
    13                                       "WM_SAVE_YOURSELF", FALSE);
    14         protocols[0] = xa_WM_SAVE_YOURSELF;
    15         XmAddWMProtocols(toplevel, protocols, 1);
      
   
    16         XmAddWMProtocolCallback(toplevel, xa_WM_SAVE_YOURSELF,
    17                                 SaveYourselfCB, NULL);
    18 }
   

   
   lines 12-15

   Include the WM_SAVE_YOURSELF atom in the WM_PROTOCOLS property on your application's top level window.

   
   lines 16-17

   Set up the callback to respond to the session manager's shutdown notification.

   
   

3. Prepare for shutdown when notified.

   The SetupSMProtocols(toplevel) routine defined in the previous listing sets up the callback with which your application responds to WM_SAVE_YOURSELF. Include the following in your application's code to define the callback routine.

     1 void
     2 SaveYourselfCB(toplevel, client_data, call_data)
     3 Widget          toplevel;
     4 XtPointer       client_data;
     5 XtPointer       call_data;
     6 {
     7   char            *cmd_argv[1];
      
   
     8   cmd_argv[0] = GetBinaryFullPathName();
      
   
     9   XSetCommand(XtDisplay(toplevel), XtWindow(toplevel), cmd_argv, 1);
    10 }
   

   
   lines 2-5

   toplevel is your application's top level widget. client_data is callback client data. call_data is callback data. The latter two are not used in this example.

   
   line 8

   You should substitute the full pathname of your binary for GetBinaryFullPathName(). Include any command line options or special geometry information needed for the restart command.

   
   line 9

   Sets the WM_COMMAND property.

   Because the session manager will be waiting for a PropertyNotify from the property WM_COMMAND as a confirmation that your application has saved its state, it is important that WM_COMMAND is updated even if its contents are correct. After updating WM_COMMAND, your application must wait to be shut down by the session manager. If your application receives a mouse or keyboard event after responding to WM_SAVE_YOURSELF, the shutdown has been canceled and your application may resume operation.