specs: convert protocol appgroup.ms from xorg-docs to DocBook XML

Signed-off-by: Gaetan Nadon <memsize@videotron.ca>

2 files changed, 249 insertions, 0 deletions

diff --git a/specs/Makefile.am b/specs/Makefile.am
index d46c391..af88d05 100644
--- a/specs/Makefile.am
+++ b/specs/Makefile.am
@@ -23,6 +23,7 @@
 
 if ENABLE_SPECS
 doc_sources =		\
+	appgroup.xml	\
 	dbe.xml		\
 	dpms.xml	\
 	security.xml	\
diff --git a/specs/appgroup.xml b/specs/appgroup.xml
new file mode 100644
index 0000000..eebf843
--- /dev/null
+++ b/specs/appgroup.xml
@@ -0,0 +1,248 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+
+<book id="appgroup">
+
+<bookinfo>
+   <title>Description of the Application Group Extension</title>
+   <subtitle>Implementation for the X11 Sample Server</subtitle>
+   <releaseinfo>Version 1.0</releaseinfo>
+   <authorgroup>
+      <author>
+         <firstname>Kaleb </firstname><surname>KEITHLEY</surname>
+         <affiliation><orgname>FUJITSU Limited.</orgname></affiliation>
+         <email>blah@blah.com</email>
+      </author>
+   </authorgroup>
+   <corpname>X Consortium Standard</corpname>
+   <copyright><year>1996</year><holder>X Consortium</holder></copyright>
+   <affiliation><orgname>X Consortium</orgname></affiliation>
+   <productnumber>X Version 11, Release 7</productnumber>
+
+<abstract>
+<para>
+The following document explains the server side of the Application
+Group Extension.
+</para>
+</abstract>
+
+<legalnotice>
+
+
+<para>
+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:
+</para>
+
+<para>
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+The following document explains the server side of the Application
+Group Extension.
+</para>
+
+<para>
+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.
+</para>
+</legalnotice>
+</bookinfo>
+
+<chapter>
+<title>TITLE</title>
+<para>
+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.
+</para>
+
+<sect1 id="AppGroup_Server_Public_Functions">
+<title>AppGroup Server Public Functions</title>
+<para>
+The AppGroup extension adds seven new functions that are called
+from elsewhere in the server. They are: XagExtensionInit,
+XagDefaultColormap, XagRootVisual, XagLeader, XagIsControlledRoot,
+XagConnectionInfo, XagCallClientStateChange.
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+</sect1>
+
+<sect1 id="AppGroup_Server_Private_APIs">
+<title>AppGroup Server Private APIs</title>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+ProcXagQueryVersion returns the major and minor versions of the
+AppGroup extension supported by the server.
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+ProcXagGetAttr returns the AppGroup Attributes to the requesting
+client.
+</para>
+<para>
+ProcXagQuery returns the AppGroup ID of an arbitrary resource to
+the requesting client.
+</para>
+<para>
+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.
+</para>
+<para>
+ProcXagDestroyAssoc destroys the association created with
+ProcXagCreateAssoc.
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+</sect1>
+
+<sect1 id="Known_Problems_in_this_release_">
+<title>Known Problems in this release.</title>
+<para>
+In a combined UI/Print server the connection setup returned to an
+embedded application will not have information about the print
+screens.
+</para>
+<para>
+The LBX proxy caches connection setup information and will return
+incorrect connection setup information to an embedded client.
+</para>
+</sect1>
+</chapter>
+</book>