# Integrating with Session Manager

Session Manager saves information about the Desktop environment and the applications running when the user logs out (of the current session) or when the user saves the environment (in a home session). For an application to be saved as part of the current session or the home session and then restarted as part of the next session, it must participate in the X Inter-Client Communication Conventions Manual (ICCCM) 1.1 Session Management Protocol. This chapter outlines how Session Manager saves and restores sessions and details the steps necessary for an application to participate in session management.

PG.smgr.mkr.2
PG.smgr.mkr.3
PG.smgr.mkr.4

## How Session Manager Saves Sessions and Applications

When you exit a session or when you save a Home session, Session Manager:

1. Saves the selected resource settings and X server settings

2. Allows each application to save its state and waits for the save to be completed

3. Obtains the command line required to restart the application

## How to Program the Application for Session Management

### Setting the Program Environment

This section describes the programming steps necessary for an application to be saved as part of the integration process.

Follow these steps to set the program environment:

1. Include the following header files:

   - `Xm/Xm.h`

   - `Xm/Protocols.h`

   - `Dt/Session.h`

2. Link with `libXm` and `libDtSvc`.

3. Initialize the toolkit and create a top-level widget.

#### Setting the WM_SAVE_YOURSELF Atom

Use the Motif `XmAddWMProtocol()` function to set the `WM_SAVE_YOURSELF` atom on the `WM_PROTOCOLS` property for the top-level window of your application, as shown in the following example.

    Atom XaWmSaveYourself;

    Display *dsp;

    dsp = XtDisplay(toplevel);

    XaWmSaveYourself =

    XmInternAtom(dsp, ”WM_SAVE_YOURSELF”, False);

    XmAddWMProtocols(toplevel, &XaWmSaveYourself, 1);

Do not set the `WM_SAVE_YOURSELF` atom for more than one window.

#### Prepare to Receive the WM_SAVE_YOURSELF Message

Use the Motif `XmAddWMProtocolCallback()` function to establish a callback procedure to be called when the application receives a `WM_SAVE_YOURSELF` client message:

    XmAddWMProtocolCallback(toplevel, XaWmSaveYourself,
    SaveYourselfProc,
       toplevel);

#### Processing the WM_SAVE_YOURSELF Message

When Session Manager sends a `WM_SAVE_YOURSELF` client message to this sample application's top-level window, the `SaveYourselfProc()` callback procedure is called. Use thecallback to save the application's state. The application can save its state by any means you want, but cannot interact with the user during the save.

Session Manager provides the `DtSessionSavePath()` function as a way to return a full path name and a base file name to use for saving the application's state.

#### Setting the WM_COMMAND Property

After the application has finished processing the `WM_SAVE_YOURSELF` message, either by saving its state or ignoring the message, the application must set the `WM_COMMAND` property on its top-level window to tell Session Manager that the save operation is complete.

Use the Xlib `XsetCommand()` function to set the `WM_COMMAND` property on the application's top-level window. Setting this property lets Session Manager know that the application has finished processing the `WM_SAVE_YOURSELF` message and gives Session Manager the command line it needs to restart the application.

`XsetCommand()` accepts an array of command-line arguments. If the application uses the `DtSessionSavePath()` function as part of the save process, `XsetCommand()` needs an additional command-line argument: `‐session` basename, where basename is the base file name returned by `DtSessionSavePath()`.

## How Session Manager Restores a Session

Session Manager restores a session by:

1. Restoring the resource database and server settings

2. Restarting applications using the saved command lines

If the application used `DtSessionSavePath()` to find a path for its saved state, the application can pass the base file name from the `-session` argument to the `DtSessionRestorePath()` function to find the full path name of its saved-state file.