Description of the Application Group Extension

Implementation for the X11 Sample Server

Kaleb KEITHLEY

FUJITSU Limited.

X Version 11, Release 7.7

Version 1.0

Copyright © 1996 X Consortium

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:

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 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.

Except as contained in this notice, the name of the X Consortium shall not be
used in advertising or otherwise to promote the sale, use or other dealings in
this Software without prior written authorization from the X Consortium.

X Window System is a trademark of The Open Group.

WindowsNT is a trademark of Microsoft, Inc.

Macintosh and Apple are trademarks of Apple Computer, Inc.

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

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Table of Contents

AppGroup Server Public Functions
AppGroup Server Private APIs
Known Problems in this release.

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.

AppGroup Server Public Functions

The AppGroup extension adds seven new functions that are called from elsewhere
in the server. They are: XagExtensionInit, XagDefaultColormap, XagRootVisual,
XagLeader, XagIsControlledRoot, 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 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.

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 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.

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.

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.

XagConnectionInfo returns an abbreviated 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.

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.

AppGroup Server Private APIs

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.

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.

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 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.

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 referenced by the record, and finally frees the record itself.

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 client.

