                 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 (c) 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

   [1]AppGroup Server Public Functions

   [2]AppGroup Server Private APIs

   [3]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.

References

   Visible links
   1. file:///tmp/xmlto.IoYcRw/appgroup.proc#AppGroup_Server_Public_Functions
   2. file:///tmp/xmlto.IoYcRw/appgroup.proc#AppGroup_Server_Private_APIs
   3. file:///tmp/xmlto.IoYcRw/appgroup.proc#Known_Problems_in_this_release
