Chip 2001 August - Disc 2/chip_20018102_hu.iso/linux/X-4.1.0/doc/appgroup.txt

Text File | 2001-06-27 | 8.9 KB | 397 lines

       Description of the Application Group Extension
      Implementation for the X11 Sample Server

             Kaleb S. KEITHLEY
            X Consortium

















































AppGroup Extension Definitio- 1 -           October, 1996
























Copyright (C) 1996 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.


















AppGroup Extension Definitio- 2 -           October, 1996








The following document explains the server side of the
Application Group Extension.

WindowsNT is a trademark of Microsoft, Inc.  Macintosh and
Apple are trademarks of Apple Computer, Inc.  X Window Sys-
tem is a trademark of X Consortium, Inc.

To understand this document and the accompanying source
code, you should know the C language, should be familiar
with X server internals, and should also have a general
knowledge of the X Window System.

1.  AppGroup Server Public Functions

The AppGroup extension adds seven new functions that are
called from elsewhere in the server. They are: XagExtension-
Init, XagDefaultColormap, XagRootVisual, XagLeader, XagIs-
ControlledRoot, XagConnectionInfo, XagCallClientStateChange.

XagExtensionInit is the extension initialization function
called from InitExtension in mi/miinitext.c. Note that an
new resource type, RT_APPGROUP, is created, specifying the
destructor function XagAppGroupFree.

XagDefaultColormap returns the colormap ID that was speci-
fied in the creation of the AppGroup. Any time CopyFromPar-
ent is specified for a top-level window's colormap, i.e. in
a CreateWindow or ChangeWindowAttributes request, this func-
tion is called to see if there is an AppGroup specific col-
ormap to use. If there is one, its ID is returned, otherwise
None is returned.

XagRootVisual returns the visual ID that was specified in
the creation of the Appgroup. Like XagDefaultColormap, when
CopyFromParent is specified for a top-level window's visual
in a CreateWindow request, this function is called to see if
there is an AppGroup specific visual to use. If there is
one, its ID is returned, otherwise 0 (zero) is returned.

XagLeader returns the ClientPtr of the client that is the
AppGroup Leader. Normally when an application maps or con-
figures a top-level window a MapRequest or ConfigureRequest
event is delivered to the client, e.g. a window manager,
that has selected SubstructureRedirect on the root window.
However, when the application is part of an AppGroup, the
MapRequest and ConfigureRequest events are delivered to the
AppGroup Leader instead.

XagIsControlledRoot returns a boolean: True if the window is
a top-level window of a client in an AppGroup, False other-
wise.  In a combined server, i.e. one that provides both UI
and printing, the application may create and map windows on
the "printing" screens; thus it becomes necessary to dis-
criminate between the AppGroup's root window and other root



AppGroup Extension Definitio- 3 -           October, 1996








windows. If an AppGroup member creates and maps a [top-
level] window then the window's parent [the root window] is
tested to determine whether to send MapRequest or Configur-
eRequest events to the AppGroup Leader to to some other
client.

In the trivial case XagIsControlledRoot returns True if the
parent window has no parent itself, i.e. it is a root win-
dow. In the case where the application is embedded, indi-
cated by the singleScreen attribute being True, the parent's
drawable ID is compared to the AppGroup's root window ID,
and if it is the same, True is returned.  If neither case is
true, then False is returned.

XagConnectionInfo returns an abreviated version of the con-
nection setup information. When an embedded AppGroup is cre-
ated the server returns only the information about the [UI]
screen that the application is embedded within in the con-
nection setup in order to prevent the application from cre-
ating windows on other screens; thus attempting to guarantee
that any window that should be embedded can be reparented
into the AppGroup Leader's window hierarchy.

XagCallClientStateChange is called to invoke the extension's
client state change callback additional times as necessary
-- currently only once, after the auth data becomes avail-
able between ClientStateInitial and ClientStateConnected.
Client state change callbacks were introduced in the Record
extension, which specifies when the callbacks are invoked.
Unfortunately the points at which they are called are not
necessarily the best as far as the AppGroup Extension is
concerned. Adding an additional state and calling all the
callbacks works too, however this seemed unnecessary
overkill.

2.  AppGroup Server Private APIs

The AppGroup extension adds the following functions which
are private to the extension: ProcXagDispatch and SProcX-
agDispatch, ProcXagQueryVersion and SProcXagQueryVersion,
ProcXagCreate and SProcXagCreate, ProcXagDestroy and SProcX-
agDestroy, ProcGetAttr and SProcGetAttr, ProcXagQuery and
SProcXagQuery, ProcXagCreateAssoc and SProcXagCreateAssoc,
ProcXagDestroyAssoc and SProcXagDestroyAssoc, XagResetProc,
and XagAppGroupFree.

The ProcXagDispatch, SProcXagDispatch, and XagResetProc
functions should be familiar to anyone familiar with X
server internals and I won't elaborate on them here. Simi-
larly the wrapper functions: SProcXagQueryVersion, SProcX-
agCreate, SProcXagDestroy, SProcXagGetAttr, SProcXagQuery,
SProcXagCreateAssoc, and SProcXagDestroyAssoc, as wrappers
which handle swapping integer data into the host's byte
order will not be explained in any detail.



AppGroup Extension Definitio- 4 -           October, 1996








ProcXagQueryVersion returns the major and minor versions of
the AppGroup extension supported by the server.

ProcXagCreate creates an AppGroup. A new record in a linked
list of AppGroups is allocated and initialized. The
attributes from the request are validated and copied to the
AppGroup record. If necessary an abbreviated version of the
connection setup information is compiled and also stored in
the AppGroup record. The first time an AppGroup is created a
client-state-change callback is registered and a reference
count is incremented.

ProcXagDestroy destroys an AppGroup an AppGroup by calling
FreeResource specifying the AppGroup ID. This will result in
the destructor function XagAppGroupFree being called. The
reference count is decremented and when it reaches zero the
client-state-change callback is deleted.

ProcXagGetAttr returns the AppGroup Attributes to the
requesting client.

ProcXagQuery returns the AppGroup ID of an arbitrary
resource to the requesting client.

ProcXagCreateAssoc creates an association between an X win-
dow ID and system-specific data. In native X this function-
ality is unnecessary but for various personal computers,
e.g. Macintosh, OS/2, and MS-Windows it is necessary to
associate an X window ID with the system's native window
identifier so that when the AppGroup Leader issues a Repar-
entWindow request the personal computer X server can lookup
the system-specific window ID and make the necessary func-
tion call(s) with it.

ProcXagDestroyAssoc destroys the association created with
ProcXagCreateAssoc.

XagResetProc removes the client-state-change callback, sets
the reference count to zero, and frees all the AppGroup
records in the linked list by calling XagAppGroupFree.

XagAppGroupFree calls CloseDownClient for each client in an
AppGroup if the AppGroup has a leader, unlinks the AppGroup
record from the linked list, frees allocated memory refer-
enced by the record, and finally frees the record itself.

3.  Known Problems in this release.

In a combined UI/Print server the connection setup returned
to an embedded application will not have information about
the print screens.

The LBX proxy caches connection setup information and will
return incorrect connection setup information to an embedded



AppGroup Extension Definitio- 5 -           October, 1996








client.
























































AppGroup Extension Definitio- 6 -           October, 1996