189 lines
8.6 KiB
Plaintext
189 lines
8.6 KiB
Plaintext
.\" $Xorg: appgroup.ms,v 1.3 2000/08/17 19:42:41 cpqbld Exp $
|
|
.EF 'AppGroup Extension Definition'- % -'October, 1996'
|
|
.OF 'AppGroup Extension Definition'- % -'October, 1996'
|
|
.EH '''
|
|
.OH '''
|
|
.TL
|
|
Description of the Application Group Extension
|
|
Implementation for the X11 Sample Server
|
|
.AU
|
|
Kaleb S. KEITHLEY
|
|
.AI
|
|
X Consortium
|
|
.LP
|
|
.bp
|
|
\&
|
|
.sp 15
|
|
Copyright \(co 1996 X Consortium
|
|
.LP
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
of this software and associated documentation files (the ``Software''), to deal
|
|
in the Software without 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 following conditions:
|
|
.LP
|
|
The above copyright notice and this permission notice shall be included in
|
|
all copies or substantial portions of the Software.
|
|
.LP
|
|
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 PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
X CONSORTIUM 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.
|
|
.bp
|
|
.LP
|
|
The following document explains the server side of the Application
|
|
Group Extension.
|
|
.LP
|
|
WindowsNT is a trademark of Microsoft, Inc. Macintosh and Apple
|
|
are trademarks of Apple Computer, Inc. X Window System is a
|
|
trademark of X Consortium, Inc.
|
|
.LP
|
|
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.
|
|
.NH 1
|
|
AppGroup Server Public Functions
|
|
.LP
|
|
The AppGroup extension adds seven new functions that are called
|
|
from elsewhere in the server. They are: XagExtensionInit,
|
|
XagDefaultColormap, XagRootVisual, XagLeader, XagIsControlledRoot,
|
|
XagConnectionInfo, XagCallClientStateChange.
|
|
.LP
|
|
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.
|
|
.LP
|
|
XagDefaultColormap returns the colormap ID that was specified in
|
|
the creation of the AppGroup. Any time CopyFromParent is specified
|
|
for a top-level window's colormap, i.e. in a CreateWindow or
|
|
ChangeWindowAttributes request, this function is called to see
|
|
if there is an AppGroup specific colormap to use. If there is
|
|
one, its ID is returned, otherwise None is returned.
|
|
.LP
|
|
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.
|
|
.LP
|
|
XagLeader returns the ClientPtr of the client that is the AppGroup
|
|
Leader. Normally when an application maps or configures 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.
|
|
.LP
|
|
XagIsControlledRoot returns a boolean: True if the window is a
|
|
top-level window of a client in an AppGroup, False otherwise.
|
|
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 discriminate between the
|
|
AppGroup's root window and other root 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 ConfigureRequest events to the AppGroup Leader to
|
|
to some other client.
|
|
.LP
|
|
In the trivial case XagIsControlledRoot returns True if the parent
|
|
window has no parent itself, i.e. it is a root window. In the case
|
|
where the application is embedded, indicated 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.
|
|
.LP
|
|
XagConnectionInfo returns an abreviated version of the connection
|
|
setup information. When an embedded AppGroup is created the server
|
|
returns only the information about the [UI] screen that the
|
|
application is embedded within in the connection setup in order to
|
|
prevent the application from creating 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.
|
|
.LP
|
|
XagCallClientStateChange is called to invoke the extension's client
|
|
state change callback additional times as necessary -- currently
|
|
only once, after the auth data becomes available 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.
|
|
.NH 1
|
|
AppGroup Server Private APIs
|
|
.LP
|
|
The AppGroup extension adds the following functions which are
|
|
private to the extension: ProcXagDispatch and SProcXagDispatch,
|
|
ProcXagQueryVersion and SProcXagQueryVersion, ProcXagCreate and
|
|
SProcXagCreate, ProcXagDestroy and SProcXagDestroy,
|
|
ProcGetAttr and SProcGetAttr, ProcXagQuery and SProcXagQuery,
|
|
ProcXagCreateAssoc and SProcXagCreateAssoc, ProcXagDestroyAssoc
|
|
and SProcXagDestroyAssoc, XagResetProc, and XagAppGroupFree.
|
|
.LP
|
|
The ProcXagDispatch, SProcXagDispatch, and XagResetProc functions
|
|
should be familiar to anyone familiar with X server internals and
|
|
I won't elaborate on them here. Similarly the wrapper functions:
|
|
SProcXagQueryVersion, SProcXagCreate, 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.
|
|
.LP
|
|
ProcXagQueryVersion returns the major and minor versions of the
|
|
AppGroup extension supported by the server.
|
|
.LP
|
|
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.
|
|
.LP
|
|
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.
|
|
.LP
|
|
ProcXagGetAttr returns the AppGroup Attributes to the requesting
|
|
client.
|
|
.LP
|
|
ProcXagQuery returns the AppGroup ID of an arbitrary resource to
|
|
the requesting client.
|
|
.LP
|
|
ProcXagCreateAssoc creates an association between an X window ID
|
|
and system-specific data. In native X this functionality 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 ReparentWindow request the personal
|
|
computer X server can lookup the system-specific window ID and
|
|
make the necessary function call(s) with it.
|
|
.LP
|
|
ProcXagDestroyAssoc destroys the association created with
|
|
ProcXagCreateAssoc.
|
|
.LP
|
|
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.
|
|
.LP
|
|
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 referenced
|
|
by the record, and finally frees the record itself.
|
|
.NH 1
|
|
Known Problems in this release.
|
|
.LP
|
|
In a combined UI/Print server the connection setup returned to an
|
|
embedded application will not have information about the print
|
|
screens.
|
|
.LP
|
|
The LBX proxy caches connection setup information and will return
|
|
incorrect connection setup information to an embedded client.
|