159 lines
7.0 KiB
Plaintext
159 lines
7.0 KiB
Plaintext
<!-- $XConsortium: ch04.sgm /main/5 1996/09/08 19:36:34 rws $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
<Chapter Id="PG.smgr.div.1">
|
|
<Title Id="PG.smgr.mkr.1">Integrating with Session Manager</Title>
|
|
<Para>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.</Para>
|
|
<InformalTable Id="PG.smgr.itbl.1" Frame="All">
|
|
<TGroup Cols="1">
|
|
<ColSpec Colname="1" Colwidth="4.0 in">
|
|
<TBody>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'How Session Manager Saves Sessions and Applications27'--><XRef Role="JumpText" Linkend="PG.smgr.mkr.2"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'How to Program the Application for Session Management28'--><XRef Role="JumpText" Linkend="PG.smgr.mkr.3"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'How Session Manager Restores a Session30'--><XRef Role="JumpText" Linkend="PG.smgr.mkr.4"></Para></Entry>
|
|
</Row>
|
|
</TBody>
|
|
</TGroup>
|
|
</InformalTable>
|
|
<Sect1 Id="PG.smgr.div.2">
|
|
<Title Id="PG.smgr.mkr.2">How Session Manager Saves Sessions and Applications</Title>
|
|
<Para>When you exit a session or when you save a Home session, Session Manager:</Para>
|
|
<OrderedList>
|
|
<ListItem>
|
|
<Para>Saves the selected resource settings and X server settings</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Allows each application to save its state and waits for the save to be
|
|
completed</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Obtains the command line required to restart the application</Para>
|
|
</ListItem>
|
|
</OrderedList>
|
|
</Sect1>
|
|
<Sect1 Id="PG.smgr.div.3">
|
|
<Title Id="PG.smgr.mkr.3">How to Program the Application for Session Management</Title>
|
|
<Sect2 Id="PG.smgr.div.4">
|
|
<Title>Setting the Program Environment</Title>
|
|
<Para>This section describes the programming steps necessary for an application to
|
|
be saved as part of the integration process.</Para>
|
|
<Para>Follow these steps to set the program environment:</Para>
|
|
<OrderedList>
|
|
<ListItem>
|
|
<Para>Include the following header files:</Para>
|
|
<ItemizedList Remap="Bullet2">
|
|
<ListItem>
|
|
<Para><Filename>Xm/Xm.h</Filename></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Filename>Xm/Protocols.h</Filename></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Filename>Dt/Session.h</Filename></Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Link with <Command>libXm</Command> and <Command>libDtSvc</Command>.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Initialize the toolkit and create a top-level widget.</Para>
|
|
</ListItem>
|
|
</OrderedList>
|
|
<Sect3 Id="PG.smgr.div.5">
|
|
<Title>Setting the WM_SAVE_YOURSELF Atom</Title>
|
|
<Para>Use the Motif <Filename>XmAddWMProtocol()</Filename> function to set the <Filename>WM_SAVE_YOURSELF</Filename>
|
|
atom on the <ComputerOutput>WM_PROTOCOLS</ComputerOutput> property for the top-level window of your
|
|
application, as shown in the following example.</Para>
|
|
<ProgramListing>Atom XaWmSaveYourself;
|
|
|
|
Display *dsp;
|
|
|
|
|
|
|
|
dsp = XtDisplay(toplevel);
|
|
|
|
XaWmSaveYourself =
|
|
|
|
XmInternAtom(dsp, ”WM_SAVE_YOURSELF”, False);
|
|
|
|
XmAddWMProtocols(toplevel, &XaWmSaveYourself, 1);</ProgramListing>
|
|
<Note>
|
|
<Para>Do not set the <ComputerOutput>WM_SAVE_YOURSELF</ComputerOutput> atom for more than one window.</Para>
|
|
</Note>
|
|
</Sect3>
|
|
<Sect3 Id="PG.smgr.div.6">
|
|
<Title>Prepare to Receive the WM_SAVE_YOURSELF Message</Title>
|
|
<Para>Use the Motif <Filename>XmAddWMProtocolCallback()</Filename> function to establish a callback
|
|
procedure to be called when the application receives a <Filename>WM_SAVE_YOURSELF</Filename>
|
|
client message:</Para>
|
|
<ProgramListing>XmAddWMProtocolCallback(toplevel, XaWmSaveYourself,
|
|
SaveYourselfProc,
|
|
toplevel);</ProgramListing>
|
|
</Sect3>
|
|
<Sect3 Id="PG.smgr.div.7">
|
|
<Title>Processing the WM_SAVE_YOURSELF Message</Title>
|
|
<Para>When Session Manager sends a <Filename>WM_SAVE_YOURSELF</Filename> client message to this
|
|
sample application's top-level window, the <Filename>SaveYourselfProc()</Filename> 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.</Para>
|
|
<Para>Session Manager provides the <Filename>DtSessionSavePath()</Filename> function as a way to
|
|
return a full path name and a base file name to use for saving the application's
|
|
state.</Para>
|
|
</Sect3>
|
|
<Sect3 Id="PG.smgr.div.8">
|
|
<Title>Setting the WM_COMMAND Property</Title>
|
|
<Para>After the application has finished processing the <Filename>WM_SAVE_YOURSELF</Filename>
|
|
message, either by saving its state or ignoring the message, the application
|
|
must set the <Filename>WM_COMMAND</Filename> property on its top-level window to tell Session
|
|
Manager that the save operation is complete.</Para>
|
|
<Para>Use the Xlib <Filename>XsetCommand()</Filename> function to set the <Filename>WM_COMMAND</Filename> property on the
|
|
application's top-level window. Setting this property lets Session Manager
|
|
know that the application has finished processing the <Filename>WM_SAVE_YOURSELF</Filename>
|
|
message and gives Session Manager the command line it needs to restart the
|
|
application.</Para>
|
|
<Para><Filename>XsetCommand()</Filename> accepts an array of command-line arguments. If the
|
|
application uses the <Filename>DtSessionSavePath()</Filename> function as part of the save
|
|
process, <Filename>XsetCommand()</Filename> needs an additional command-line argument: <Command>‐session</Command> <Symbol Role="Variable">basename</Symbol>, where <Symbol Role="Variable">basename</Symbol> is the base file name returned by
|
|
<Filename>DtSessionSavePath()</Filename>.</Para>
|
|
</Sect3>
|
|
</Sect2>
|
|
</Sect1>
|
|
<Sect1 Id="PG.smgr.div.9">
|
|
<Title Id="PG.smgr.mkr.4">How Session Manager Restores a Session</Title>
|
|
<Para>Session Manager restores a session by:</Para>
|
|
<OrderedList>
|
|
<ListItem>
|
|
<Para>Restoring the resource database and server settings</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Restarting applications using the saved command lines</Para>
|
|
</ListItem>
|
|
</OrderedList>
|
|
<Para>If the application used <Filename>DtSessionSavePath()</Filename> to find a path for its saved
|
|
state, the application can pass the base file name from the <Filename>-session</Filename> argument
|
|
to the <Filename>DtSessionRestorePath()</Filename> function to find the full path name of its
|
|
saved-state file.</Para>
|
|
</Sect1>
|
|
</Chapter>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->
|