specs: convert ICE doc/specs from xorg-docs module to DocBook XML

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

1 files changed, 4588 insertions, 0 deletions

diff --git a/doc/ICElib.xml b/doc/ICElib.xml
new file mode 100644
index 0000000..27f3f0d
--- /dev/null
+++ b/doc/ICElib.xml
@@ -0,0 +1,4588 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+
+
+<book id="icelib">
+
+<bookinfo>
+   <title>Inter-Client Exchange Library</title>
+   <subtitle>X Consortium Standard</subtitle>
+   <releaseinfo>X Version 11, Release 6.4</releaseinfo>
+   <authorgroup>
+     <author>
+       <firstname>Ralph</firstname><surname>Mor</surname>
+       <affiliation><orgname>X Consortium</orgname></affiliation>
+     </author>
+   </authorgroup>
+   <corpname>X Consortium Standard</corpname>
+   <copyright><year>1993</year><holder>X Consortium</holder></copyright>
+   <copyright><year>1994</year><holder>X Consortium</holder></copyright>
+   <copyright><year>1996</year><holder>X Consortium</holder></copyright>
+   <revhistory><revision><revnumber>1.0</revnumber><date></date></revision></revhistory>
+
+<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>
+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.
+</para>
+
+</legalnotice>
+</bookinfo>
+
+<chapter id='overview_of_ice'>
+<title>Overview of ICE</title>
+
+<para>
+There are numerous possible inter-client protocols, with many similarities
+and common needs - authentication, version negotiation, byte
+order negotiation, and so on.
+The Inter-Client Exchange (ICE) protocol is intended to provide a framework
+for building such protocols, allowing them to make use of common negotiation
+mechanisms and to be multiplexed over a single transport connection.
+</para>
+</chapter>
+
+<chapter id='the_ice_library__c_language_interface_to'>
+<title>The ICE Library - C Language Interface to ICE</title>
+
+<para>
+A client that wishes to utilize ICE must first register the protocols it
+understands with the ICE library.  Each protocol is dynamically assigned
+a major opcode ranging from 1-255 (two clients can use different
+major opcodes for the same protocol).  The next step for the client is either
+to open a connection with another client or to wait for connections made
+by other clients.  Authentication may be required.  A client can both
+initiate connections with other clients and be
+waiting for clients to connect to itself (a nested session manager is an
+example).  Once an ICE connection is established between the two clients, one
+of the clients needs to initiate a
+<function>ProtocolSetup</function>
+in order to
+"activate" a given protocol.  Once the other client accepts the
+<function>ProtocolSetup</function>
+(once again, authentication may be required), the
+two clients are ready to start passing messages specific to that protocol to
+each other.  Multiple protocols may be active on a single ICE connection.
+Clients are responsible for notifying the ICE library when a protocol is no
+longer active on an ICE connection, although ICE does not define how each
+subprotocol triggers a protocol shutdown.
+</para>
+
+<para>
+The ICE library utilizes callbacks to process incoming messages.  Using
+callbacks allows
+<function>ProtocolSetup</function>
+messages and authentication to happen
+behind the scenes.  An additional benefit is that messages never need
+to be buffered up by the library when the client blocks waiting for a
+particular message.
+</para>
+</chapter>
+
+<chapter id='intended_audience'>
+<title>Intended Audience</title>
+
+<para>This document is intended primarily for implementors of protocol libraries
+layered on top of ICE.  Typically, applications that wish to utilize ICE
+will make calls into individual protocol libraries rather than directly
+make calls into the ICE library.  However, some applications will have to
+make some initial calls into the ICE library in order to accept ICE
+connections (for example, a session manager accepting connections from
+clients).  But in general, protocol libraries should be designed to hide
+the inner details of ICE from applications.</para>
+</chapter>
+
+<chapter id='header_files_and_library_name'>
+<title>Header Files and Library Name</title>
+
+
+<para>The header file
+&lt;<symbol role='Pn'>X11/ICE/ICElib.h</symbol>&gt;
+defines all of the ICElib data structures and function prototypes.
+<function>ICElib.h</function>
+includes the header file
+&lt;<symbol role='Pn'>X11/ICE/ICE.h</symbol>&gt;,
+which defines all of the ICElib constants.
+Protocol libraries that need to read and write messages should include
+the header file
+&lt;<symbol role='Pn'>X11/ICE/ICEmsg.h</symbol>&gt;.</para>
+
+<para>Applications should link against ICElib using -lICE.</para>
+</chapter>
+
+<chapter id='note_on_prefixes'>
+<title>Note on Prefixes</title>
+
+
+<para>The following name prefixes are used in the library to distinguish between
+a client that initiates a
+<function>ProtocolSetup</function>
+and a client that
+responds with a
+<function>ProtocolReply</function></para>
+
+<itemizedlist>
+  <listitem>
+<para><function>IcePo</function>
+- Ice Protocol Originator</para>
+  </listitem>
+  <listitem>
+<para><function>IcePa</function>
+- Ice Protocol Acceptor</para>
+  </listitem>
+</itemizedlist>
+</chapter>
+
+<chapter id='protocol_registration'>
+<title>Protocol Registration</title>
+
+<para>
+In order for two clients to exchange messages for a given protocol, each
+side must register the protocol with the ICE library.  The purpose of
+registration is for each side to obtain a major opcode for the protocol
+and to provide callbacks for processing messages and handling authentication.
+There are two separate registration functions:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+One to handle the side that does a
+<function>ProtocolSetup</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+One to handle the side that responds with a
+<function>ProtocolReply</function>
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para>
+It is recommended that protocol registration occur before the two clients
+establish an ICE connection.  If protocol registration occurs after an
+ICE connection is created, there can be a brief interval of time in which a
+<function>ProtocolSetup</function>
+is received, but the protocol is not registered.
+If it is not possible to register a protocol before the creation of an
+ICE connection, proper precautions should be taken to avoid the above race
+condition.
+</para>
+
+
+<para>
+The <function>IceRegisterForProtocolSetup</function>
+function should be called for the client that initiates a
+<function>ProtocolSetup</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>IceRegisterForProtocolSetup</function></funcdef>
+    <paramdef>char<parameter> *protocol_name</parameter></paramdef>
+    <paramdef>char<parameter> *vendor</parameter></paramdef>
+    <paramdef>char<parameter> *release</parameter></paramdef>
+    <paramdef>int<parameter> *version_count</parameter></paramdef>
+    <paramdef>int<parameter> *version_count</parameter></paramdef>
+    <paramdef>IcePoVersionRec<parameter> *version_recs</parameter></paramdef>
+    <paramdef>int<parameter> auth_names</parameter></paramdef>
+    <paramdef>char<parameter> **auth_names</parameter></paramdef>
+    <paramdef>IcePoAuthProc<parameter> *auth_procs</parameter></paramdef>
+    <paramdef>IceIOErrorProc<parameter> *io_error_proc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>protocol_name</emphasis></term>
+    <listitem>
+      <para>
+A string specifying the name of the protocol to register.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>vendor</emphasis></term>
+    <listitem>
+      <para>A vendor string with semantics specified by the protocol.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>release</emphasis></term>
+    <listitem>
+      <para>A release string with semantics specified by the protocol.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>version_count</emphasis></term>
+    <listitem>
+      <para>The number of different versions of the protocol supported.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>version_recs</emphasis></term>
+    <listitem>
+      <para>List of versions and associated callbacks.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>auth_count</emphasis></term>
+    <listitem>
+      <para>The number of authentication methods supported.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>auth_names</emphasis></term>
+    <listitem>
+      <para>The list of authentication methods supported.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>auth_procs</emphasis></term>
+    <listitem>
+      <para>
+The list of authentication callbacks, one for each authentication method.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>io_error_proc</emphasis></term>
+    <listitem>
+      <para>IO error handler, or NULL.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+<function>IceRegisterForProtocolSetup</function> returns the major
+opcode reserved or -1 if an error occurred.  In order to actually activate
+the protocol, the <function>IceProtocolSetup</function>
+function needs to be called with this major opcode.  Once the protocol is
+activated, all messages for the protocol should be sent using this major
+opcode.
+</para>
+
+<para>
+A protocol library may support multiple versions of the same protocol.
+The version_recs argument specifies a list of supported versions of the
+protocol, which are prioritized in decreasing order of preference.
+Each version record consists of a major and minor version of the protocol
+as well as a callback to be used for processing incoming messages.
+</para>
+
+
+<literallayout remap='Ds'>
+typedef struct {
+	int major_version;
+	int minor_version;
+	IcePoProcessMsgProc process_msg_proc;
+} IcePoVersionRec;
+</literallayout>
+
+<para>The
+<function>IcePoProcessMsgProc</function>
+callback is responsible for processing the set of messages that can be
+received by the client that initiated the
+<function>ProtocolSetup</function>
+For further information,
+see
+<link linkend="callbacks_for_processing_messages">
+<xref linkend="callbacks_for_processing_messages"></xref></link>.</para>
+
+<para>Authentication may be required before the protocol can become active.
+The protocol library must register the authentication methods that it
+supports with the ICE library.
+The auth_names and auth_procs arguments are a list of authentication names
+and callbacks that are  prioritized in decreasing order of preference.
+For information on the
+<function>IcePoAuthProc</function>
+callback, see
+<link linkend="authentication_methods">
+<xref linkend="authentication_methods"></xref></link>
+</para>
+
+<para>The
+<function>IceIOErrorProc</function>
+callback is invoked if the ICE connection unexpectedly breaks.
+You should pass NULL for io_error_proc if not interested in being notified.
+For further information,
+<link linkend="error_handling">
+<xref linkend="error_handling"></xref></link>
+</para>
+
+
+<para>The
+<function>IceRegisterForProtocolReply</function>
+function should be called for the client that responds to a
+<function>ProtocolSetup</function>
+with a
+<function>ProtocolReply</function></para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Bool <function>IceRegisterForProtocolReply</function></funcdef>
+    <paramdef>char<parameter> *host_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>protocol_name</emphasis></term>
+    <listitem><para>A string specifying the name of the protocol to register.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>vendor</emphasis></term>
+  <listitem>
+<para>A vendor string with semantics specified by the protocol.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>release</emphasis></term>
+  <listitem>
+<para>A release string with semantics specified by the protocol.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>version_count</emphasis></term>
+  <listitem>
+<para>The number of different versions of the protocol supported.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>version_recs</emphasis></term>
+  <listitem>
+<para>List of versions and associated callbacks.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>auth_count</emphasis></term>
+  <listitem>
+<para>The number of authentication methods supported.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>auth_names</emphasis></term>
+  <listitem>
+<para>The list of authentication methods supported.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>auth_procs</emphasis></term>
+  <listitem>
+<para>The list of authentication callbacks, one for each authentication method.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>host_based_auth_proc</emphasis></term>
+  <listitem>
+<para>Host based authentication callback.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>protocol_setup_proc</emphasis></term>
+  <listitem>
+<para>A callback to be invoked when authentication has succeeded for a
+<function>ProtocolSetup</function>
+but before the
+<function>ProtocolReply</function>
+is sent.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>protocol_activate_proc</emphasis></term>
+  <listitem>
+<para>A callback to be invoked after the
+<function>ProtocolReply</function>
+is sent.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>io_error_proc</emphasis></term>
+  <listitem>
+<para>IO error handler, or NULL.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para><function>IceRegisterForProtocolReply</function>
+returns the major opcode reserved or -1 if an error occurred.  The major
+opcode should be used in all subsequent messages sent for this protocol.</para>
+
+<para>A protocol library may support multiple versions of the same protocol.
+The version_recs argument specifies a list of supported versions of the protocol,
+which are prioritized in decreasing order of preference.
+Each version record consists of a major and minor version of the protocol
+as well as a callback to be used for processing incoming messages.</para>
+
+
+<literallayout remap='Ds'>
+typedef struct {
+	int major_version;
+	int minor_version;
+	IcePaProcessMsgProc process_msg_proc;
+} IcePaVersionRec;
+</literallayout>
+
+
+<para>The
+<function>IcePaProcessMsgProc</function>
+callback is responsible for processing the set of messages that can be
+received by the client that accepted the
+<function>ProtocolSetup</function>
+For further information,
+see
+<link linkend="callbacks_for_processing_messages">
+<xref linkend="callbacks_for_processing_messages"></xref></link>
+</para>
+
+<para>Authentication may be required before the protocol can become active.
+The protocol library must register the authentication methods that it
+supports with the ICE library.
+The auth_names and auth_procs arguments are a list of authentication names
+and callbacks that are prioritized in decreasing order of preference.
+For information on the
+<function>IcePaAuthProc</function>,
+See
+<link linkend="authentication_methods">
+<xref linkend="authentication_methods"></xref></link>
+
+</para>
+
+<para>If authentication fails and the client attempting to initiate
+the
+<function>ProtocolSetup</function>
+has not required authentication, the
+<function>IceHostBasedAuthProc</function>
+callback is invoked with the host name of the originating client.
+If the callback returns
+<function>True</function>
+the
+<function>ProtocolSetup</function>
+will succeed, even though the original
+authentication failed.
+Note that authentication can effectively be disabled by registering an
+<function>IceHostBasedAuthProc</function>
+which always returns
+<function>True</function>
+If no host based
+authentication is allowed, you should pass NULL for host_based_auth_proc.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Bool <function>HostBasedAuthProc</function></funcdef>
+    <paramdef>char<parameter> *host_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>protocol_name</emphasis></term>
+    <listitem><para>The host name of the client that sent the <function>ProtocolSetup</function></para></listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>The host_name argument is a string of the form <emphasis remap='I'>protocol</emphasis>/<emphasis remap='I'>hostname</emphasis>,
+where <emphasis remap='I'>protocol</emphasis> is one of {tcp, decnet, local}.</para>
+
+<para>Because
+<function>ProtocolSetup</function>
+messages and authentication happen behind the scenes
+via callbacks, the protocol library needs some way of being notified when the
+<function>ProtocolSetup</function>
+has completed.
+This occurs in two phases.
+In the first phase, the
+<function>IceProtocolSetupProc</function>
+callback is invoked after authentication has
+successfully completed but before the ICE library sends a
+<function>ProtocolReply</function>
+Any resources required for this protocol should be allocated at this time.
+If the
+<function>IceProtocolSetupProc</function>
+returns a successful status, the ICE library will
+send the
+<function>ProtocolReply</function>
+and then invoke the
+<function>IceProtocolActivateProc</function>
+callback.  Otherwise, an error will be sent to the
+other client in response to the
+<function>ProtocolSetup</function></para>
+
+<para>The
+<function>IceProtocolActivateProc</function>
+is an optional callback and should be registered only if the protocol
+library intends to generate a message immediately following the
+<function>ProtocolReply</function>
+You should pass NULL for protocol_activate_proc if not interested
+in this callback.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>ProtocolSetupProc</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> major_version</parameter></paramdef>
+    <paramdef>int<parameter> minor_version</parameter></paramdef>
+    <paramdef>char<parameter> *vendor</parameter></paramdef>
+    <paramdef>char<parameter> *release</parameter></paramdef>
+    <paramdef>IcePointer<parameter> *client_data_ret</parameter></paramdef>
+    <paramdef>char<parameter> **failure_reason_ret</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>protocol_name</emphasis></term>
+    <listitem>
+<para>The ICE connection object.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>major_version</emphasis></term>
+  <listitem>
+<para>The major version of the protocol.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>minor_version</emphasis></term>
+  <listitem>
+<para>The minor version of the protocol.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>vendor</emphasis></term>
+  <listitem>
+<para>The vendor string registered by the protocol originator.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>release</emphasis></term>
+  <listitem>
+<para>The release string registered by the protocol originator.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>client_data_ret</emphasis></term>
+  <listitem>
+<para>Client data to be set by callback.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>failure_reason_ret</emphasis></term>
+  <listitem>
+<para>Failure reason returned.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>The pointer stored in the client_data_ret argument will be passed
+to the
+<function>IcePaProcessMsgProc</function>
+callback whenever a message has arrived for this protocol on the
+ICE connection.</para>
+
+<para>The vendor and release strings should be freed with
+<function>free</function>
+when they are no longer needed.</para>
+
+<para>If a failure occurs, the
+<function>IceProtocolSetupProc</function>
+should return a zero status as well as allocate and return a failure
+reason string in failure_reason_ret.
+The ICE library will be responsible for freeing this memory.</para>
+
+<para>The
+<function>IceProtocolActivateProc</function>
+callback is defined as follows:</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>ProtocolActivateProc</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem><para>The ICE connection object.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>client_data</emphasis></term>
+    <listitem>
+    <para>
+The client data set in the <function>IceProtocolSetupProc</function> callback.
+    </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>The
+<function>IceIOErrorProc</function>
+callback is invoked if the ICE connection unexpectedly breaks.
+You should pass NULL for io_error_proc if not interested in being notified.
+For further information,
+see
+<link linkend="error_handling">
+<xref linkend="error_handling"></xref></link>
+</para>
+
+<sect1 id='callbacks_for_processing_messages'>
+<title>Callbacks for Processing Messages</title>
+
+<para>When an application detects that there is new data to read on an ICE
+connection (via
+<function>select</function>
+it calls the
+<function>IceProcessMessages</function>
+function
+<link linkend="processing_messages">
+<xref linkend="processing_messages"></xref></link>.
+
+When
+<function>IceProcessMessages</function>
+reads an ICE message header with a major opcode other than
+zero (reserved for the ICE protocol), it needs to call a function that will
+read the rest of the message, unpack it, and process it accordingly.</para>
+
+<para>If the message arrives at the client that initiated the
+<function>ProtocolSetup</function>
+the
+<function>IcePoProcessMsgProc</function>
+callback is invoked.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>PoProcessMsgProc</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
+    <paramdef>int<parameter> opcode</parameter></paramdef>
+    <paramdef>unsigned long<parameter> length</parameter></paramdef>
+    <paramdef>Bool<parameter> swap</parameter></paramdef>
+    <paramdef>IceReplyWaitInfo<parameter> *reply_wait</parameter></paramdef>
+    <paramdef>Bool<parameter> *reply_ready_ret</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem><para>The ICE connection object.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>client_data</emphasis></term>
+  <listitem>
+<para>Client data associated with this protocol on the ICE connection.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>opcode</emphasis></term>
+  <listitem>
+<para>The minor opcode of the message.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>length</emphasis></term>
+  <listitem>
+<para>The length (in 8-byte units) of the message beyond the ICE header.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>swap</emphasis></term>
+  <listitem>
+<para>A flag that indicates if byte swapping is necessary.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>reply_wait</emphasis></term>
+  <listitem>
+<para>Indicates if the invoking client is waiting for a reply.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>reply_ready_ret</emphasis></term>
+  <listitem>
+<para>If set to
+<function>True</function>
+a reply is ready.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>If the message arrives at the client that accepted the
+<function>ProtocolSetup</function>
+the
+<function>IcePaProcessMsgProc</function>
+callback is invoked.</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>IcePaProcessMsgProc</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
+    <paramdef>int<parameter> opcode</parameter></paramdef>
+    <paramdef>unsigned long<parameter> length</parameter></paramdef>
+    <paramdef>Bool<parameter> swap</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem><para>The ICE connection object.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>client_data</emphasis></term>
+  <listitem>
+<para>Client data associated with this protocol on the ICE connection.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>opcode</emphasis></term>
+  <listitem>
+<para>The minor opcode of the message.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>length</emphasis></term>
+  <listitem>
+<para>The length (in 8-byte units) of the message beyond the ICE header.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>swap</emphasis></term>
+  <listitem>
+<para>A flag that indicates if byte swapping is necessary.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>In order to read the message, both of these callbacks should use the
+macros defined for this purpose (see
+<link linkend="reading_ice_messages">
+<xref linkend="reading_ice_messages"></xref></link>.).
+Note that byte swapping may be necessary.
+As a convenience, the length field in the ICE header will be swapped by ICElib
+if necessary.</para>
+
+<para>In both of these callbacks, the client_data argument is a pointer to client
+data that was registered at
+<function>ProtocolSetup</function>
+time.
+In the case of
+<function>IcePoProcessMsgProc</function>
+the client data was set in the call to
+<function>IceProtocolSetup</function>
+In the case of
+<function>IcePaProcessMsgProc</function>
+the client data was set in the
+<function>IceProtocolSetupProc</function>
+callback.</para>
+
+<para>The
+<function>IcePoProcessMsgProc</function>
+callback needs to check the reply_wait argument.
+If reply_wait is NULL ,
+the ICE library expects the function to
+pass the message to the client via a callback.
+For example, if this is a Session Management "Save Yourself" message,
+this function should notify the client of the "Save Yourself" via a callback.
+The details of how such a callback would be defined
+are implementation-dependent.</para>
+
+<para>However, if reply_wait is not NULL ,
+then the client is waiting for
+a reply or an error for a message it previously sent.
+The reply_wait is of type
+<function>IceReplyWaitInfo</function></para>
+
+
+<literallayout remap='Ds'>
+typedef struct {
+	unsigned long sequence_of_request;
+	int major_opcode_of_request;
+	int minor_opcode_of_request;
+	IcePointer reply;
+} IceReplyWaitInfo;
+</literallayout>
+
+<para><function>IceReplyWaitInfo</function>
+contains the major/minor opcodes and sequence number of
+the message for which a reply is being awaited.
+It also contains a pointer to the reply message to be filled in
+(the protocol library should cast this
+<function>IcePointer</function>
+to the appropriate reply type).
+In most cases, the reply will have some fixed-size part, and the client waiting
+for the reply will have provided a pointer to a structure to hold
+this fixed-size data.  If there is variable-length data, it would be
+expected that the
+<function>IcePoProcessMsgProc</function>
+callback will have to allocate additional
+memory and store pointer(s) to that memory in the fixed-size
+structure.  If the entire data is variable length (for example., a single
+variable-length string), then the client waiting for the reply would probably
+just pass a pointer to fixed-size space to hold a pointer, and the
+<function>IcePoProcessMsgProc</function>
+callback would allocate the storage and store the pointer.
+It is the responsibility of the client receiving the reply to
+free any memory allocated on its behalf.</para>
+
+<para>If reply_wait is not NULL and
+<function>IcePoProcessMsgProc</function>
+has a reply or error to return in response to this reply_wait
+(that is, no callback was generated), then the reply_ready_ret argument
+should be set to
+<function>True</function>
+Note that an error should only be returned
+if it corresponds to the reply being waited for.  Otherwise, the
+<function>IcePoProcessMsgProc</function>
+should either handle the error internally or invoke an error handler
+for its library.</para>
+
+<para>If reply_wait is NULL,
+then care must be taken not to store any value in reply_ready_ret,
+because this pointer may also be NULL.</para>
+
+<para>The
+<function>IcePaProcessMsgProc</function>
+callback, on the other hand, should always pass
+the message to the client via a callback.  For example, if this is a Session
+Management "Interact Request" message, this function should notify the
+client of the "Interact Request" via a callback.</para>
+
+<para>The reason the
+<function>IcePaProcessMsgProc</function>
+callback does not have a reply_wait, like
+<function>IcePoProcessMsgProc</function>
+does, is because a process that is acting as
+a server should never block for a reply (infinite blocking can
+occur if the connecting client does not act properly, denying access
+to other clients).</para>
+</sect1>
+
+<sect1 id='authentication_methods'>
+<title>Authentication Methods</title>
+
+<para>As already stated, a protocol library must register the authentication
+methods that it supports with the ICE library.  For each authentication
+method, there are two callbacks that may be registered:</para>
+<itemizedlist>
+  <listitem>
+    <para>
+One to handle the side that initiates a <function>ProtocolSetup</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+One to handle the side that accepts or rejects this request
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para><function>IcePoAuthProc</function>
+is the callback invoked for the client that initiated the
+<function>ProtocolSetup</function>
+This callback must be able to respond
+to the initial "Authentication Required" message or subsequent
+"Authentication Next Phase" messages sent by the other client.</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IcePoAuthStatus <function>IcePoAuthStatus </function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
+    <paramdef>int<parameter> opcode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem><para>The ICE connection object.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>auth_state_ptr</emphasis></term>
+  <listitem>
+<para>A pointer to state for use by the authentication callback procedure.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>clean_up</emphasis></term>
+  <listitem>
+<para>If
+<function>True</function>
+authentication is over, and the function
+should clean up any state it was maintaining.  The
+last 6 arguments should be ignored.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>swap</emphasis></term>
+  <listitem>
+<para>If
+<function>True</function>
+the auth_data may have to be byte swapped
+(depending on its contents).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>auth_datalen</emphasis></term>
+  <listitem>
+<para>The length (in bytes) of the authenticator data.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>auth_data</emphasis></term>
+  <listitem>
+<para>The data from the authenticator.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>reply_datalen_ret</emphasis></term>
+  <listitem>
+<para>The length (in bytes) of the reply data returned.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>reply_data_ret</emphasis></term>
+  <listitem>
+<para>The reply data returned.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>error_string_ret</emphasis></term>
+  <listitem>
+<para>If the authentication procedure encounters an error during
+authentication, it should allocate and return
+an error string.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>Authentication may require several phases, depending on the authentication
+method.  As a result, the
+<function>IcePoAuthProc</function>
+may be called more than once when authenticating a client, and
+some state will have to be maintained between each invocation.
+At the start of each
+<function>ProtocolSetup</function>
+*auth_state_ptr is NULL,
+and the function should initialize its state and set
+this pointer.  In subsequent invocations of the callback, the pointer
+should be used to get at any state previously stored by the callback.</para>
+
+<para>If needed, the network ID of the client accepting the
+<function>ProtocolSetup</function>
+can be obtained by calling the
+<function>IceConnectionString</function>
+function.</para>
+
+<para>ICElib will be responsible for freeing the reply_data_ret and
+error_string_ret pointers with
+<function>free</function></para>
+
+<para>The auth_data pointer may point to a volatile block of memory.
+If the data must be kept beyond this invocation of the callback, be sure
+to make a copy of it.</para>
+
+<para>The
+<function>IcePoAuthProc</function>
+should return one of four values:</para>
+<itemizedlist>
+  <listitem>
+<para><function>IcePoAuthHaveReply</function>
+- a reply is available.</para>
+  </listitem>
+  <listitem>
+<para><function>IcePoAuthRejected</function>
+- authentication rejected.</para>
+  </listitem>
+  <listitem>
+<para><function>IcePoAuthFailed</function>
+- authentication failed.</para>
+  </listitem>
+  <listitem>
+<para><function>IcePoAuthDoneCleanup</function>
+- done cleaning up.</para>
+  </listitem>
+</itemizedlist>
+
+<para><function>IcePaAuthProc</function>
+is the callback invoked for the client that received the
+<function>ProtocolSetup</function></para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IcePoAuthStatus <function>PoAuthStatus </function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>IcePointer<parameter> *auth_state_ptr</parameter></paramdef>
+    <paramdef>Bool<parameter> swap</parameter></paramdef>
+    <paramdef>int<parameter> auth_datalen</parameter></paramdef>
+    <paramdef>IcePointer<parameter> auth_data</parameter></paramdef>
+    <paramdef>int<parameter> *reply_datalen_ret</parameter></paramdef>
+    <paramdef>IcePointer<parameter> *reply_data_ret</parameter></paramdef>
+    <paramdef>char<parameter> **error_string_ret</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem><para>The ICE connection object.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>auth_state_ptr</emphasis></term>
+    <listitem>
+<para>A pointer to state for use by the authentication callback procedure.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>swap</emphasis></term>
+    <listitem>
+<para>If
+<function>True</function>
+auth_data may have to be byte swapped
+(depending on its contents).</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>auth_datalen</emphasis></term>
+    <listitem>
+<para>The length (in bytes) of the protocol originator authentication data.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>auth_data</emphasis></term>
+    <listitem>
+<para>The authentication data from the protocol originator.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>reply_datalen_ret</emphasis></term>
+    <listitem>
+<para>The length of the authentication data returned.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>reply_data_ret</emphasis></term>
+    <listitem>
+<para>The authentication data returned.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>error_string_ret</emphasis></term>
+    <listitem>
+<para>If authentication is rejected or fails, an error
+string is returned.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>Authentication may require several phases, depending on the authentication
+method.  As a result, the
+<function>IcePaAuthProc</function>
+may be called more than once when authenticating a client, and
+some state will have to be maintained between each invocation.
+At the start of each
+<function>ProtocolSetup</function>
+auth_datalen is zero,
+*auth_state_ptr is NULL,
+and the function should initialize its state and set
+this pointer.  In subsequent invocations of the callback, the pointer
+should be used to get at any state previously stored by the callback.</para>
+
+<para>If needed, the network ID of the client accepting the
+<function>ProtocolSetup</function>
+can be obtained by calling the
+<function>IceConnectionString</function>
+function.</para>
+
+<para>The auth_data pointer may point to a volatile block of memory.
+If the data must be kept beyond this invocation of the callback, be sure
+to make a copy of it.</para>
+
+<para>ICElib will be responsible for transmitting and freeing the reply_data_ret and
+error_string_ret pointers with
+<function>free</function></para>
+
+<para>
+The <function>IcePaAuthProc</function> should return one of four values:
+</para>
+
+
+<itemizedlist>
+  <listitem>
+    <para>
+<function>IcePaAuthContinue</function> - continue (or start) authentication.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>IcePaAuthAccepted</function> - authentication accepted.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>IcePaAuthRejected</function> - authentication rejected.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>IcePaAuthFailed</function> - authentication failed.
+    </para>
+  </listitem>
+</itemizedlist>
+</sect1>
+
+</chapter>
+
+<chapter id='ice_connections'>
+<title>ICE Connections</title>
+
+<para>
+In order for two clients to establish an ICE connection, one client has to be
+waiting for connections, and the other client has to initiate the connection.
+Most clients will initiate connections, so we discuss that first.
+</para>
+
+<sect1 id='opening_an_ice_connection'>
+<title>Opening an ICE Connection</title>
+
+
+<para>
+To open an ICE connection with another client (that is, waiting
+for connections), use <function>IceOpenConnection</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IceConn <function>IceOpenConnection</function></funcdef>
+    <paramdef>char<parameter> *network_ids_list</parameter></paramdef>
+    <paramdef>IcePointer<parameter> context</parameter></paramdef>
+    <paramdef>Bool<parameter> must_authenticate</parameter></paramdef>
+    <paramdef>int<parameter> major_opcode_check</parameter></paramdef>
+    <paramdef>int<parameter> error_length</parameter></paramdef>
+    <paramdef>char<parameter> *error_string_ret</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>network_ids_list</emphasis></term>
+    <listitem>
+      <para>
+Specifies the network ID(s) of the other client.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>context</emphasis></term>
+    <listitem>
+      <para>
+A pointer to an opaque object or NULL.  Used to determine if an
+ICE connection can be shared (see below).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>must_authenticate</emphasis></term>
+    <listitem>
+      <para>
+If <function>True</function> the other client may not bypass authentication.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>major_opcode_check</emphasis></term>
+    <listitem>
+      <para>
+Used to force a new ICE connection to be created (see below).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>error_length</emphasis></term>
+    <listitem>
+      <para>Length of the error_string_ret argument passed in.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>error_string_ret</emphasis></term>
+    <listitem>
+      <para>
+Returns a null-terminated error message, if any.  The error_string_ret
+argument points to user supplied memory.  No more than error_length bytes
+are used.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+<function>IceOpenConnection</function>
+returns an opaque ICE connection object if it succeeds;
+otherwise, it returns NULL.
+</para>
+
+<para>
+The network_ids_list argument contains a list of network IDs separated
+by commas.  An attempt will be made to use the first network ID.  If
+that fails, an attempt will be made using the second network ID, and so on.
+Each network ID has the following format:
+</para>
+
+<informaltable pgwide='0' frame='none'>
+  <tgroup cols='3' align='center'>
+    <colspec colname='c1'/>
+    <colspec colname='c2'/>
+    <colspec colname='c3'/>
+    <tbody>
+      <row>
+        <entry align='left'></entry>
+        <entry align='left'>tcp/&lt;hostname&gt;:&lt;portnumber&gt;</entry>
+        <entry align='left'>or</entry>
+      </row>
+      <row>
+        <entry align='left'></entry>
+        <entry align='left'>decnet/&lt;hostname&gt;::&lt;objname&gt;</entry>
+        <entry align='left'>or</entry>
+      </row>
+      <row>
+        <entry align='left'></entry>
+        <entry align='left'>local/&lt;hostname&gt;:&lt;path&gt;</entry>
+        <entry align='left'></entry>
+      </row>
+    </tbody>
+  </tgroup>
+</informaltable>
+
+
+<para>Most protocol libraries will have some sort of open function that should
+internally make a call into
+<function>IceOpenConnection</function>
+When
+<function>IceOpenConnection</function>
+is called, it may be possible to use a previously opened ICE connection (if
+the target client is the same).  However, there are cases in which shared
+ICE connections are not desired.</para>
+
+<para>The context argument is used to determine if an ICE connection can
+be shared.
+If context is NULL,
+then the caller is always willing to share the connection.
+If context is not NULL,
+then the caller is not willing to use a previously opened ICE connection
+that has a different non-NULL context associated with it.</para>
+
+<para>In addition, if major_opcode_check contains a nonzero major opcode value,
+a previously created ICE connection will be used only if the major opcode
+is not active on the connection.  This can be used to force multiple ICE
+connections between two clients for the same protocol.</para>
+
+<para>Any authentication requirements are handled internally by the ICE library.
+The method by which the authentication data is obtained
+is implementation-dependent.
+  <footnote remap='FS'>
+<para>The X Consortium's ICElib implementation uses an .ICEauthority file (see
+Appendix A).
+  </para></footnote> </para>
+
+<para>After
+<function>IceOpenConnection</function>
+is called, the client is ready to send a
+<function>ProtocolSetup</function>
+(provided that
+<function>IceRegisterForProtocolSetup</function>
+was called) or receive a
+<function>ProtocolSetup</function>
+(provided that
+<function>IceRegisterForProtocolReply</function>
+was called).</para>
+</sect1>
+
+<sect1 id='listening_for_ice_connections'>
+<title>Listening for ICE Connections</title>
+
+<para>Clients wishing to accept ICE connections must first call
+<function>IceListenForConnections</function>
+or
+<function>IceListenForWellKnownConnections</function>
+so that they can listen for connections.  A list of opaque "listen" objects are
+returned, one for each type of transport method that is available
+(for example, Unix Domain, TCP, DECnet, and so on).</para>
+
+<para>Normally clients will let ICElib allocate an available name in each
+transport and return listen objects.  Such a client will then use
+<function>IceComposeNetworkIdList</function>
+to extract the chosen names and make them
+available to other clients for opening the connection.  In certain
+cases it may be necessary for a client to listen for connections
+on pre-arranged transport object names.  Such a client may use
+<function>IceListenForWellKnownConnections</function>
+to specify the names for the listen objects.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>IceListenForConnections</function></funcdef>
+    <paramdef>int<parameter> *count_ret</parameter></paramdef>
+    <paramdef>IceListenObj<parameter> **listen_objs_ret</parameter></paramdef>
+    <paramdef>int<parameter> error_length</parameter></paramdef>
+    <paramdef>char<parameter> *error_string_ret</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>count_ret</emphasis></term>
+    <listitem><para>Returns the number of listen objects created.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>listen_objs_ret</emphasis></term>
+    <listitem><para>Returns a list of pointers to opaque listen objects.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>error_length</emphasis></term>
+  <listitem>
+<para>The length of the error_string_ret argument passed in.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>error_string_ret</emphasis></term>
+  <listitem>
+<para>Returns a null-terminated error message, if any.
+The error_string_ret points to user supplied memory.
+No more than error_length bytes are used.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>The return value of
+<function>IceListenForConnections</function>
+is zero for failure and a positive value for success.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>IceListenForWellKnownConnections</function></funcdef>
+    <paramdef>char<parameter> *port_id</parameter></paramdef>
+    <paramdef>int<parameter> *count_ret</parameter></paramdef>
+    <paramdef>IceListenObj<parameter> **listen_objs_ret</parameter></paramdef>
+    <paramdef>int<parameter> error_length</parameter></paramdef>
+    <paramdef>char<parameter> *error_string_ret</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>port_id</emphasis></term>
+    <listitem>
+      <para>
+Specifies the port identification for the address(es) to be opened.  The
+value must not contain the slash ("/"> or comma (".") character; thse are
+reserved for future use.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>count_ret</emphasis></term>
+    <listitem>
+      <para>Returns the number of listen objects created.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>listen_objs_ret</emphasis></term>
+    <listitem>
+      <para>
+Returns a list of pointers to opaque listen objects.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>listen_objs_ret</emphasis></term>
+    <listitem>
+      <para>
+Returns a list of pointers to opaque listen objects.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>error_length</emphasis></term>
+    <listitem>
+      <para>
+The length of the error_string_ret argument passed in.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>error_string_ret</emphasis></term>
+    <listitem>
+      <para>
+Returns a null-terminated error message, if any.  The error_string_ret
+points to user supplied memory.  No more than error_length bytes are used.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<function>IceListenForWellKnownConnections</function> constructs a list
+of network IDs by prepending each known transport to port_id and then
+attempts to create listen objects for the result.  Port_id is the portnumber,
+objname, or path portion of the ICE network ID. If a listen object for
+a particular network ID cannot be created the network ID is ignored.
+If no listen objects are created
+<function>IceListenForWellKnownConnections</function>
+returns failure.
+</para>
+
+<para>
+The return value of <function>IceListenForWellKnownConnections</function>
+is zero for failure and a positive value for success.
+</para>
+
+<para>
+To close and free the listen objects, use
+<function>IceFreeListenObjs</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>IceFreeListenObjs</function></funcdef>
+    <paramdef>int<parameter> count</parameter></paramdef>
+    <paramdef>IceListenObj<parameter> *listen_objs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>count</emphasis></term>
+    <listitem>
+      <para>The number of listen objects.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>listen_objs</emphasis></term>
+    <listitem>
+      <para>The listen objects.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+To detect a new connection on a listen object, use
+<function>select</function> on the descriptor associated with
+the listen object.
+</para>
+
+<para>
+To obtain the descriptor, use
+<function>IceGetListenConnectionNumber</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>IceGetListenConnectionNumber</function></funcdef>
+    <paramdef>IceListenObj<parameter> *listen_objs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term><emphasis remap='I'>listen_obj</emphasis></term>
+    <listitem>
+      <para>The listen objects.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+To obtain the network ID string associated with a listen object, use
+<function>IceGetListenConnectionString</function>
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>char <function>IceGetListenConnectionString</function></funcdef>
+    <paramdef>IceListenObj<parameter> listen_obj</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>listen_obj</emphasis></term>
+    <listitem>
+      <para>The listen objects.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>A network ID has the following format:</para>
+
+<informaltable pgwide='0' frame='none'>
+  <tgroup cols='3' align='center'>
+    <colspec colname='c1'/>
+    <colspec colname='c2'/>
+    <colspec colname='c3'/>
+    <tbody>
+      <row>
+        <entry align='left'></entry>
+        <entry align='left'>tcp/&lt;hostname&gt;:&lt;portnumber&gt;</entry>
+        <entry align='left'>or</entry>
+      </row>
+      <row>
+        <entry align='left'></entry>
+        <entry align='left'>decnet/&lt;hostname&gt;::&lt;objname&gt;</entry>
+        <entry align='left'>or</entry>
+      </row>
+      <row>
+        <entry align='left'></entry>
+        <entry align='left'>local/&lt;hostname&gt;:&lt;path&gt;</entry>
+        <entry align='left'></entry>
+      </row>
+    </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+To compose a string containing a list of network IDs separated by commas
+(the format recognized by <function>IceOpenConnection</function>
+use <function>IceComposeNetworkIdList</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>char <function>IceComposeNetworkIdList</function></funcdef>
+    <paramdef>int<parameter> count</parameter></paramdef>
+    <paramdef>IceListenObj<parameter> *listen_objs</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>count</emphasis></term>
+    <listitem>
+      <para>The number of listen objects.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>listen_objs</emphasis></term>
+    <listitem>
+      <para>The listen objects.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id='host_based_authentication_for_ice_connec'>
+<title>Host Based Authentication for ICE Connections</title>
+
+<para>
+If authentication fails when a client attempts to open an
+ICE connection and the initiating client has not required authentication,
+a host based authentication procedure may be invoked to provide
+a last chance for the client to connect.  Each listen object has such a
+callback associated with it, and this callback is set using the
+<function>IceSetHostBasedAuthProc</function>
+function.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>IceSetHostBasedAuthProc</function></funcdef>
+    <paramdef>IceListenObj<parameter> listen_obj</parameter></paramdef>
+    <paramdef>IceHostBasedAuthProc<parameter> host_based_auth_proc</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>IceListenObj</emphasis></term>
+    <listitem>
+      <para>The listen object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>host_based_auth_proc</emphasis></term>
+    <listitem>
+      <para>The host based authentication procedure.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+By default, each listen object has no host based authentication procedure
+associated with it.  Passing NULL for host_based_auth_proc turns off
+host based authentication if it was previously set.
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Bool <function>HostBasedAuthProc</function></funcdef>
+    <paramdef>char<parameter> *host_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>host_name</emphasis></term>
+    <listitem>
+      <para>
+The host name of the client that tried to open an ICE connection.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+The host_name argument is a string in the form
+<emphasis remap='I'>protocol</emphasis>/
+<emphasis remap='I'>hostname</emphasis>,
+where <emphasis remap='I'>protocol</emphasis> is one of
+{tcp, decnet, local}.
+</para>
+
+<para>
+If <function>IceHostBasedAuthProc</function> returns
+<function>True</function>
+access will be granted, even though the original authentication failed.
+Note that authentication can effectively be disabled by registering an
+<function>IceHostBasedAuthProc</function>
+which always returns <function>True</function>
+</para>
+
+<para>
+Host based authentication is also allowed at
+<function>ProtocolSetup</function> time.
+The callback is specified in the
+<function>IceRegisterForProtocolReply</function>
+function (see
+<link linkend="protocol_registration">
+<xref linkend="protocol_registration"></xref></link>).
+</para>
+</sect1>
+
+<sect1 id='accepting_ice_connections'>
+<title>Accepting ICE Connections</title>
+
+
+<para>
+After a connection attempt is detected on a listen object returned by
+<function>IceListenForConnections</function>
+you should call <function>IceAcceptConnection</function>
+This returns a new opaque ICE connection object.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IceConn <function>IceAcceptConnection</function></funcdef>
+    <paramdef>IceListenObj<parameter> listen_obj</parameter></paramdef>
+    <paramdef>IceAcceptStatus<parameter> *status_ret</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term><emphasis remap='I'>listen_obj</emphasis></term>
+  <listitem>
+<para>The listen object on which a new connection was detected.</para>
+  </listitem>
+  </varlistentry>
+  </variablelist>
+  <variablelist remap='IP'>
+  <varlistentry>
+  <term><emphasis remap='I'>status_ret</emphasis></term>
+  <listitem>
+<para>Return status information.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>The status_ret argument is set to one of the following values:</para>
+<itemizedlist>
+  <listitem>
+<para><function>IceAcceptSuccess</function>
+- the accept operation succeeded,
+and the function returns a new connection object.</para>
+  </listitem>
+  <listitem>
+<para><function>IceAcceptFailure</function>
+- the accept operation failed, and the function returns NULL.</para>
+  </listitem>
+  <listitem>
+<para><function>IceAcceptBadMalloc</function>
+- a memory allocation failed, and the function returns NULL.</para>
+  </listitem>
+</itemizedlist>
+
+<para>In general, to detect new connections, you should call
+<function>select</function>
+on the file descriptors associated with the listen objects.
+When a new connection is detected, the
+<function>IceAcceptConnection</function>
+function should be called.
+<function>IceAcceptConnection</function>
+may return a new ICE connection that is in a pending state.  This is because
+before the connection can become valid, authentication may be necessary.
+Because the ICE library cannot block and wait for the connection to
+become valid (infinite blocking can occur if the connecting client
+does not act properly), the application must wait for the connection status
+to become valid.</para>
+
+<para>The following pseudo-code demonstrates how connections are accepted:</para>
+
+<literallayout class="monospaced">
+new_ice_conn = IceAcceptConnection (listen_obj, &amp;accept_status);
+if (accept_status != IceAcceptSuccess)
+{
+     close the file descriptor and return
+}
+
+status = IceConnectionStatus (new_ice_conn);
+time_start = time_now;
+
+while (status == IceConnectPending)
+{
+     select() on {new_ice_conn, all open connections}
+
+     for (each ice_conn in the list of open connections)
+          if (data ready on ice_conn)
+          {
+               status = IceProcessMessages (ice_conn, NULL, NULL);
+               if (status == IceProcessMessagesIOError)
+                    IceCloseConnection(ice_conn);
+          }
+     if data ready on new_ice_conn
+     {
+          /*
+          * IceProcessMessages is called until the connection
+          * is non-pending.  Doing so handles the connection
+          * setup request and any authentication requirements.
+          */
+
+          IceProcessMessages ( new_ice_conn, NULL, NULL);
+          status = IceConnectionStatus (new_ice_conn);
+     }
+     else
+     {
+          if (time_now - time_start &gt; MAX_WAIT_TIME)
+               status = IceConnectRejected;
+     }
+}
+
+if (status == IceConnectAccepted)
+{
+     Add new_ice_conn to the list of open connections
+}
+else
+{
+     IceCloseConnection
+     new_ice_conn
+}
+</literallayout>
+
+<para>After
+<function>IceAcceptConnection</function>
+is called and the connection has been
+validated, the client is ready to receive a
+<function>ProtocolSetup</function>
+(provided
+that
+<function>IceRegisterForProtocolReply</function>
+was called) or send a
+<function>ProtocolSetup</function>
+(provided that
+<function>IceRegisterForProtocolSetup</function>
+was called).</para>
+</sect1>
+
+<sect1 id='closing_ice_connections'>
+<title>Closing ICE Connections</title>
+
+<para>To close an ICE connection created with
+<function>IceOpenConnection</function>
+or
+<function>IceAcceptConnection</function>
+use
+<function>IceCloseConnection</function></para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IceCloseStatus <function>IceCloseConnection</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term><emphasis remap='I'>ice_conn</emphasis></term>
+  <listitem>
+  <para>The ICE connection to close.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>To actually close an ICE connection, the following conditions
+must be met:</para>
+
+<itemizedlist>
+  <listitem>
+<para>The <emphasis remap='I'>open reference count</emphasis> must have reached zero on this ICE connection.
+When
+<function>IceOpenConnection</function>
+is called, it tries to use a previously opened
+ICE connection.  If it is able to use an existing connection, it increments
+the open reference count on the connection by one.
+So, to close an ICE connection, each call to
+<function>IceOpenConnection</function>
+must be matched with a call to
+<function>IceCloseConnection</function>
+The connection can be closed only
+on the last call to
+<function>IceCloseConnection</function></para>
+  </listitem>
+  <listitem>
+<para>The <emphasis remap='I'>active protocol count</emphasis> must have reached zero.  Each time a
+<function>ProtocolSetup</function>
+succeeds on the connection, the active protocol count
+is incremented by one.  When the client no longer expects to use the
+protocol on the connection, the
+<function>IceProtocolShutdown</function>
+function should be called, which decrements the active protocol count
+by one (see
+<link linkend="protocol_setup_and_shutdown">
+<xref linkend="protocol_setup_and_shutdown"></xref></link>).
+</para>
+  </listitem>
+  <listitem>
+<para>If shutdown negotiation is enabled on the connection, the client on the other
+side of the ICE connection must agree to have the connection closed.</para>
+
+<para><function>IceCloseConnection</function>
+returns one of the following values:</para>
+  </listitem>
+  <listitem>
+<para><function>IceClosedNow</function>
+- the ICE connection was closed at this time.  The watch procedures were
+invoked and the connection was freed.</para>
+  </listitem>
+  <listitem>
+<para><function>IceClosedASAP</function>
+- an IO error had occurred on the connection, but
+<function>IceCloseConnection</function>
+is being called within a nested
+<function>IceProcessMessages</function>
+The watch procedures have been invoked at this time, but the connection
+will be freed as soon as possible (when the nesting level reaches zero and
+<function>IceProcessMessages</function>
+returns a status of
+<function>IceProcessMessagesConnectionClosed</function></para>
+  </listitem>
+  <listitem>
+<para><function>IceConnectionInUse</function>
+- the connection was not closed at this time, because it is being used by
+other active protocols.</para>
+  </listitem>
+  <listitem>
+<para><function>IceStartedShutdownNegotiation</function>
+- the connection was not closed at this time and shutdown negotiation started
+with the client on the other side of the ICE connection.  When the connection
+is actually closed,
+<function>IceProcessMessages</function>
+will return a status of
+<function>IceProcessMessagesConnectionClosed</function></para>
+  </listitem>
+</itemizedlist>
+
+<para>When it is known that the client on the other side of the ICE connection
+has terminated the connection without initiating shutdown negotiation, the
+<function>IceSetShutdownNegotiation</function>
+function should be called to turn off shutdown negotiation.  This will prevent
+<function>IceCloseConnection</function>
+from writing to a broken connection.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>IceSetShutdownNegotiation</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>Bool<parameter> negotiate</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term><emphasis remap='I'>ice_conn</emphasis></term>
+  <listitem>
+  <para>A valid ICE connection object.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>negotiate</emphasis></term>
+  <listitem>
+<para>If
+<function>False</function>
+shutdown negotiating will be turned off.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>To check the shutdown negotiation status of an ICE connection, use
+<function>IceCheckShutdownNegotiation</function></para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Bool <function>IceCheckShutdownNegotiation</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term><emphasis remap='I'>ice_conn</emphasis></term>
+  <listitem>
+  <para>A valid ICE connection object.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para><function>IceCheckShutdownNegotiation</function>
+returns
+<function>True</function>
+if shutdown negotiation will take place on the connection;
+otherwise, it returns
+<function>False</function>
+Negotiation is on by default for a connection.  It
+can only be changed with the
+<function>IceSetShutdownNegotiation</function>
+function.</para>
+</sect1>
+
+<sect1 id='connection_watch_procedures'>
+<title>Connection Watch Procedures</title>
+
+<para>To add a watch procedure that will be called
+each time ICElib opens a new connection via
+<function>IceOpenConnection</function>
+or
+<function>IceAcceptConnection</function>
+or closes a connection via
+<function>IceCloseConnection</function>
+use
+<function>IceAddConnectionWatch</function></para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>IceAddConnectionWatch</function></funcdef>
+    <paramdef>IceWatchProc<parameter> watch_proc</parameter></paramdef>
+    <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>watch_proc</emphasis></term>
+    <listitem>
+      <para>
+The watch procedure to invoke when ICElib opens or closes a connection.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>client_data</emphasis></term>
+    <listitem>
+      <para>This pointer will be passed to the watch procedure.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+The return value of <function>IceAddConnectionWatch</function>
+is zero for failure, and a positive value for success.
+</para>
+
+<para>
+Note that several calls to <function>IceOpenConnection</function>
+might share the same ICE connection.  In such a case, the watch procedure
+is only invoked when the connection is first created (after authentication
+succeeds).  Similarly, because connections might be shared, the
+watch procedure is called only if <function>IceCloseConnection</function>
+actually closes the connection (right before the IceConn is freed).
+</para>
+
+<para>
+The watch procedures are very useful for applications that
+need to add a file descriptor to a select mask when a new connection
+is created and remove the file descriptor when the connection is destroyed.
+Because connections are shared, knowing when to add and remove the file
+descriptor from the select mask would be difficult without the watch
+procedures.
+</para>
+
+<para>
+Multiple watch procedures may be registered with the ICE library.
+No assumptions should be made about their order of invocation.
+</para>
+
+<para>
+If one or more ICE connections were already created by the ICE library at the
+time the watch procedure is registered, the watch procedure will instantly
+be invoked for each of these ICE connections (with the opening argument
+set to <function>True</function>
+</para>
+
+<para>
+The watch procedure is of type <function>IceWatchProc</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>WatchProc</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
+    <paramdef>Bool<parameter> opening</parameter></paramdef>
+    <paramdef>IcePointer<parameter> *watch_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>
+The opened or closed ICE connection.  Call
+<function>IceConnectionNumber</function>
+to get the file descriptor associated with this connection.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>client_data</emphasis></term>
+    <listitem>
+      <para>
+Client data specified in the call to
+<function>IceAddConnectionWatch</function>
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>opening</emphasis></term>
+    <listitem>
+      <para>
+If <function>True</function> the connection is being opened.  If
+<function>False</function> the connection is being closed.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>watch_data</emphasis></term>
+    <listitem>
+      <para>Can be used to save a pointer to client data.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+If opening is <function>True</function> the client should set the
+*watch_data pointer to any data it may need to save until the connection
+is closed and the watch procedure is invoked again with opening set to
+<function>False</function>
+</para>
+
+<para>
+To remove a watch procedure, use
+<function>IceRemoveConnectionWatch</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>IceRemoveConnectionWatch</function></funcdef>
+    <paramdef>IceWatchProc<parameter> watch_proc</parameter></paramdef>
+    <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>watch_proc</emphasis></term>
+    <listitem>
+      <para>
+The watch procedure that was passed to
+<function>IceAddConnectionWatch</function>
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>client_data</emphasis></term>
+    <listitem>
+      <para>
+The client_data pointer that was passed to
+<function>IceAddConnectionWatch</function>
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+</sect1>
+</chapter>
+
+<chapter id='protocol_setup_and_shutdown'>
+<title>Protocol Setup and Shutdown</title>
+
+<para>
+To activate a protocol on a given ICE connection, use
+<function>IceProtocolSetup</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IceProtocolSetupStatus <function>IceProtocolSetup</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> my_opcode</parameter></paramdef>
+    <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
+    <paramdef>Bool<parameter> must_authenticate</parameter></paramdef>
+    <paramdef>int<parameter> *major_version_ret</parameter></paramdef>
+    <paramdef>int<parameter> *minor_version_ret</parameter></paramdef>
+    <paramdef>char<parameter> **vendor_ret</parameter></paramdef>
+    <paramdef>char<parameter> **release_ret</parameter></paramdef>
+    <paramdef>int<parameter> error_length</parameter></paramdef>
+    <paramdef>char<parameter> *error_string_ret</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>my_opcode</emphasis></term>
+    <listitem>
+      <para>
+The major opcode of the protocol to be set up, as returned by
+<function>IceRegisterForProtocolSetup</function>
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>client_data</emphasis></term>
+    <listitem>
+      <para>
+The client data stored in this pointer will be passed to the
+<function>IcePoProcessMsgProc</function> callback.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>must_authenticate</emphasis></term>
+    <listitem>
+      <para>
+If <function>True</function> the other client may
+not bypass authentication.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>major_version_ret</emphasis></term>
+    <listitem>
+      <para>The major version of the protocol to be used is returned.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>minor_version_ret</emphasis></term>
+    <listitem>
+      <para>The minor version of the protocol to be used is returned.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>vendor_ret</emphasis></term>
+    <listitem>
+      <para>The vendor string specified by the protocol acceptor.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>release_ret</emphasis></term>
+    <listitem>
+      <para>The release string specified by the protocol acceptor.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>error_length</emphasis></term>
+    <listitem>
+      <para>
+Specifies the length of the error_string_ret argument passed in.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>error_string_ret</emphasis></term>
+    <listitem>
+      <para>
+Returns a null-terminated error message, if any.
+The error_string_ret argument points to user supplied memory.
+No more than error_length bytes are used.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+The vendor_ret and release_ret strings should be freed with
+<function>free</function> when no longer needed.
+</para>
+
+<para>
+<function>IceProtocolSetup</function> returns one of the following values:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+<function>IceProtocolSetupSuccess</function> - the major_version_ret,
+minor_version_ret, vendor_ret, release_ret are set.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>IceProtocolSetupFailure</function> or
+<function>IceProtocolSetupIOError</function>
+- check error_string_ret for failure reason.  The major_version_ret,
+minor_version_ret, vendor_ret, release_ret are not set.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>IceProtocolAlreadyActive</function>
+- this protocol is already active on this connection.
+The major_version_ret, minor_version_ret, vendor_ret, release_ret
+are not set.
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para>
+To notify the ICE library when a given protocol will no longer be used
+on an ICE connection, use <function>IceProtocolShutdown</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>IceProtocolShutdown</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> major_opcode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>major_opcode</emphasis></term>
+    <listitem>
+      <para>The major opcode of the protocol to shut down.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+The return value of <function>IceProtocolShutdown</function>
+is zero for failure and a positive value for success.
+</para>
+
+<para>
+Failure will occur if the major opcode was never registered OR the protocol
+of the major opcode was never activated on the connection.  By activated,
+we mean that a <function>ProtocolSetup</function> succeeded on the connection.
+Note that ICE does not define how each sub-protocol triggers a
+protocol shutdown.
+</para>
+</chapter>
+
+<chapter id='processing_messages'>
+<title>Processing Messages</title>
+
+
+<para>To process incoming messages on an ICE connection, use
+<function>IceProcessMessages</function></para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IceProcessMessagesStatus <function>IceProcessMessages</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>IceReplyWaitInfo<parameter> *reply_wait</parameter></paramdef>
+    <paramdef>Bool<parameter> *reply_ready_ret</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>reply_wait</emphasis></term>
+    <listitem>
+      <para>Indicates if a reply is being waited for.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>reply_ready_ret</emphasis></term>
+    <listitem>
+      <para>
+If set to <function>True</function> on return, a reply is ready.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<function>IceProcessMessages</function> is used in two ways:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+In the first, a client may generate a message and block by calling
+<function>IceProcessMessages</function> repeatedly until it gets its reply.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+In the second, a client calls <function>IceProcessMessages</function>
+with reply_wait set to NULL in response to <function>select</function>
+showing that there is data to read on the ICE connection.
+The ICE library may process zero or more complete messages.
+Note that messages that are not blocked for are always processed by
+invoking callbacks.
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para>
+<function>IceReplyWaitInfo</function> contains the major/minor opcodes
+and sequence number of the message for which a reply is being awaited.
+It also contains a pointer to the reply message to be filled in (the
+protocol library should cast this <function>IcePointer</function>
+to the appropriate reply type).  In most
+cases, the reply will have some fixed-size part, and the client waiting
+for the reply will have provided a pointer to a structure to hold
+this fixed-size data.  If there is variable-length data, it would be
+expected that the
+<function>IcePoProcessMsgProc</function>
+callback will have to allocate additional
+memory and store pointer(s) to that memory in the fixed-size
+structure.  If the entire data is variable length (for example, a single
+variable-length string), then the client waiting for the reply would probably
+just pass a pointer to fixed-size space to hold a pointer, and the
+<function>IcePoProcessMsgProc</function>
+callback would allocate the storage and store the pointer.
+It is the responsibility of the client receiving the reply to
+free up any memory allocated on its behalf.
+</para>
+
+<literallayout class="monospaced">
+typedef struct {
+     unsigned long sequence_of_request;
+     int major_opcode_of_request;
+     int minor_opcode_of_request;
+     IcePointer reply;
+} IceReplyWaitInfo;
+</literallayout>
+
+<para>
+If reply_wait is not NULL and
+<function>IceProcessMessages</function>
+has a reply or error to return in response to this reply_wait
+(that is, no callback was generated), then the reply_ready_ret argument
+will be set to <function>True</function>
+</para>
+
+<para>
+If reply_wait is NULL, then the caller may also pass NULL for
+reply_ready_ret and be guaranteed that no value will be stored in
+this pointer.
+</para>
+
+<para>
+<function>IceProcessMessages</function> returns one of the following values:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+<function>IceProcessMessagesSuccess</function> - no error occurred.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>IceProcessMessagesIOError</function> - an IO error occurred,
+and the caller must explicitly close the connection by calling
+<function>IceCloseConnection</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>IceProcessMessagesConnectionClosed</function>
+- the ICE connection has been closed (closing of the connection was deferred
+because of shutdown negotiation, or because the
+<function>IceProcessMessages</function>
+nesting level was not zero).  Do not attempt
+to access the ICE connection at this point, since it has been freed.
+    </para>
+  </listitem>
+</itemizedlist>
+
+</chapter>
+
+<chapter id='ping'>
+<title>Ping</title>
+
+<para>
+To send a "Ping" message to the client on the other side of the
+ICE connection, use <function>IcePing</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>IcePing</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>IcePingReplyProc<parameter> ping_reply_proc</parameter></paramdef>
+    <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>ping_reply_proc</emphasis></term>
+    <listitem>
+      <para>The callback to invoke when the Ping reply arrives.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>client_data</emphasis></term>
+    <listitem>
+      <para>
+This pointer will be passed to the <function>IcePingReplyProc</function>
+callback.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para><function>IcePing</function>
+returns zero for failure and a positive value for success.</para>
+
+<para>When
+<function>IceProcessMessages</function>
+processes the Ping reply, it will invoke the
+<function>IcePingReplyProc</function>
+callback.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>PingReplyProc</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+  <term><emphasis remap='I'>ice_conn</emphasis></term>
+  <listitem>
+<para>A valid ICE connection object.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='I'>client_data</emphasis></term>
+  <listitem>
+<para>The client data specified in the call to
+<function>IcePing</function></para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+</chapter>
+
+<chapter id='using_icelib_informational_functions'>
+<title>Using ICElib Informational Functions</title>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IceConnectStatus <function>IceConnectionStatus</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para><function>IceConnectionStatus</function>
+returns the status of an ICE connection.  The possible return values are:</para>
+
+<itemizedlist>
+  <listitem>
+<para><function>IceConnectPending</function>
+- the connection is not valid yet (that is, authentication is taking place).
+This is only relevant to connections created by
+<function>IceAcceptConnection</function></para>
+  </listitem>
+  <listitem>
+<para><function>IceConnectAccepted</function>
+- the connection has been accepted.
+This is only relevant to connections created by
+<function>IceAcceptConnection</function></para>
+  </listitem>
+  <listitem>
+<para><function>IceConnectRejected</function>
+- the connection had been rejected  (that is, authentication failed).
+This is only relevant to connections created by
+<function>IceAcceptConnection</function></para>
+  </listitem>
+  <listitem>
+<para><function>IceConnectIOError</function>
+- an IO error has occurred on the connection.</para>
+  </listitem>
+</itemizedlist>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>char <function> *IceVendor</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para><function>IceVendor</function>
+returns the ICE library vendor identification
+for the other side of the connection.
+The string should be freed with a call to
+<function>free</function>
+when no longer needed.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>char <function> *IceRelease</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para><function>IceRelease</function>
+returns the release identification of the ICE library
+on the other side of the connection.
+The string should be freed with a call to
+<function>free</function>
+when no longer needed.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function> IceProtocolVersion</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para><function>IceProtocolVersion</function>
+returns the major version of the ICE protocol on this connection.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function> IceProtocolRevision</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<para><function>IceProtocolRevision</function>
+returns the minor version of the ICE protocol on this connection.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function> IceConnectionNumber</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<para><function>IceConnectionNumber</function>
+returns the file descriptor of this ICE connection.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>char <function> *IceConnectionString</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para><function>IceConnectionString</function>
+returns the network ID of the client that
+accepted this connection.  The string should be freed with a call to
+<function>free</function>
+when no longer needed.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>unsigned long <function> IceLastSentSequenceNumber</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<para><function>IceLastSentSequenceNumber</function>
+returns the sequence number of the last message sent on this ICE connection.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>unsigned long <function> IceLastReceivedSequenceNumber</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para><function>IceLastReceivedSequenceNumber</function>
+returns the sequence number of the last message received on this
+ICE connection.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Bool <function> IceSwapping</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+
+<para><function>IceSwapping</function>
+returns
+<function>True</function>
+if byte swapping is necessary when reading messages on the ICE connection.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IcePointer <function> IceGetContext</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<para><function>IceGetContext</function>
+returns the context associated with a connection created by
+<function>IceOpenConnection</function></para>
+</chapter>
+
+<chapter id='ice_messages'>
+<title>ICE Messages</title>
+
+<para>
+All ICE messages have a standard 8-byte header.  The ICElib macros that
+read and write messages rely on the following naming convention for message
+headers:
+</para>
+
+<literallayout class='monospaced'>
+     CARD8	major_opcode;
+     CARD8	minor_opcode;
+     CARD8	data[2];
+     CARD32	length B32;
+</literallayout>
+
+<para>
+The 3rd and 4th bytes of the message header can be used as needed.
+The length field is specified in units of 8 bytes.
+</para>
+
+<sect1 id='sending_ice_messages'>
+<title>Sending ICE Messages</title>
+
+<para>
+The ICE library maintains an output buffer used for generating messages.
+Protocol libraries layered on top of ICE may choose to batch messages
+together and flush the output buffer at appropriate times.
+</para>
+
+<para>
+If an IO error has occurred on an ICE connection, all write operations
+will be ignored.  For further information, see
+<link linkend="error_handling">
+<xref linkend="error_handling"></xref></link>.
+</para>
+
+
+<para>
+To get the size of the ICE output buffer, use
+<function>IceGetOutBufSize</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function> IceGetOutBufSize</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+To flush the ICE output buffer, use <function>IceFlush</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function> IceFlush</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+Note that the output buffer may be implicitly flushed if there is
+insufficient space to generate a message.
+</para>
+
+<para>The following macros can be used to generate ICE messages:</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceGetHeader</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> major_opcode</parameter></paramdef>
+    <paramdef>int<parameter> minor_opcode</parameter></paramdef>
+    <paramdef>int<parameter> header_size</parameter></paramdef>
+    <paramdef>&lt;C_data_type&gt;<parameter> *pmsg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>major_opcode</emphasis></term>
+    <listitem>
+      <para>The major opcode of the message.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>minor_opcode</emphasis></term>
+    <listitem>
+      <para>The minor opcode of the message.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>header_size</emphasis></term>
+    <listitem>
+      <para>The size of the message header (in bytes).</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>&lt;C_data_type&gt;</emphasis></term>
+    <listitem>
+      <para>The actual C data type of the message header.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>pmsg</emphasis></term>
+    <listitem>
+      <para>
+The message header pointer.  After this macro is called, the
+library can store data in the message header.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+<function>IceGetHeader</function>
+is used to set up a message header on an ICE connection.
+It sets the major and minor opcodes of the message, and initializes
+the message's length to the length of the header.  If additional
+variable length data follows, the message's length field should be
+updated.
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceGetHeaderExtra</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> major_opcode</parameter></paramdef>
+    <paramdef>int<parameter> minor_opcode</parameter></paramdef>
+    <paramdef>int<parameter> header_size</parameter></paramdef>
+    <paramdef>int<parameter> extra</parameter></paramdef>
+    <paramdef>&lt;C_data_type&gt;<parameter> *pmsg</parameter></paramdef>
+    <paramdef>char<parameter> *pdata</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>major_opcode</emphasis></term>
+    <listitem>
+      <para>The major opcode of the message.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>minor_opcode</emphasis></term>
+    <listitem>
+      <para>The minor opcode of the message.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>header_size</emphasis></term>
+    <listitem>
+      <para>The size of the message header (in bytes).</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>extra</emphasis></term>
+    <listitem>
+      <para>
+The size of the extra data beyond the header (in 8-byte units).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>&lt;C_data_type&gt;</emphasis></term>
+    <listitem>
+      <para>The actual C data type of the message header.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>pmsg</emphasis></term>
+    <listitem>
+      <para>
+The message header pointer.  After this macro is called, the
+library can store data in the message header.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>pdata</emphasis></term>
+    <listitem>
+      <para>
+Returns a pointer to the ICE output buffer that points
+immediately after the message header.  The variable length
+data should be stored here.  If there was not enough room
+in the ICE output buffer, pdata is set to NULL.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+<function>IceGetHeaderExtra</function>
+is used to generate a message with a fixed (and relatively small) amount
+of variable length data.  The complete message must fit in the ICE output
+buffer.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceSimpleMessage</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> major_opcode</parameter></paramdef>
+    <paramdef>int<parameter> minor_opcode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>major_opcode</emphasis></term>
+    <listitem>
+      <para>The major opcode of the message.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>minor_opcode</emphasis></term>
+    <listitem>
+      <para>The minor opcode of the message.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<function>IceSimpleMessage</function>
+is used to generate a message that is identical
+in size to the ICE header message, and has no additional data.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceErrorHeader</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> offending_major_opcode</parameter></paramdef>
+    <paramdef>int<parameter> offending_minor_opcode</parameter></paramdef>
+    <paramdef>int<parameter> offending_sequence_num</parameter></paramdef>
+    <paramdef>int<parameter> severity</parameter></paramdef>
+    <paramdef>int<parameter> error_class</parameter></paramdef>
+    <paramdef>int<parameter> data_length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>offending_major_opcode</emphasis></term>
+    <listitem>
+      <para>
+The major opcode of the protocol in which an error was detected.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>offending_minor_opcode</emphasis></term>
+    <listitem>
+      <para>
+The minor opcode of the protocol in which an error was detected.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>offending_sequence_num</emphasis></term>
+    <listitem>
+      <para>The sequence number of the message that caused the error.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>severity</emphasis></term>
+    <listitem>
+      <para>
+<function>IceCanContinue</function>
+<function>IceFatalToProtocol</function>
+or
+<function>IceFatalToConnection</function>
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>error_class</emphasis></term>
+    <listitem>
+      <para>The error class.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>data_length</emphasis></term>
+    <listitem>
+      <para>
+Length of data (in 8-byte units) to be written after the header.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<function>IceErrorHeader</function> sets up an error message header.
+</para>
+
+<para>
+Note that the two clients connected by ICE may be using different
+major opcodes for a given protocol.  The offending_major_opcode passed
+to this macro is the major opcode of the protocol for the client
+sending the error message.
+</para>
+
+<para>
+Generic errors, which are common to all protocols, have classes
+in the range 0x8000..0xFFFF.
+See the <emphasis remap='I'>Inter-Client Exchange Protocol</emphasis>
+standard for more details.
+</para>
+
+<informaltable pgwide='0' frame='none'>
+  <tgroup cols='2' align='center'>
+    <colspec colname='c1'/>
+    <colspec colname='c2'/>
+    <tbody>
+      <row>
+        <entry align='left'>IceBadMinor</entry>
+        <entry align='left'>0x8000</entry>
+      </row>
+      <row>
+        <entry align='left'>IceBadState</entry>
+        <entry align='left'>0x8001</entry>
+      </row>
+      <row>
+        <entry align='left'>IceBadLength</entry>
+        <entry align='left'>0x8002</entry>
+      </row>
+      <row>
+        <entry align='left'>IceBadValue</entry>
+        <entry align='left'>0x8003</entry>
+      </row>
+    </tbody>
+  </tgroup>
+</informaltable>
+
+<para>Per-protocol errors have classes in the range 0x0000-0x7fff.</para>
+
+<para>
+To write data to an ICE connection, use the
+<function>IceWriteData</function> macro.  If the data fits into the
+ICE output buffer, it is copied there.  Otherwise, the ICE output buffer
+is flushed and the data is directly sent.
+</para>
+
+<para>
+This macro is used in conjunction with
+<function>IceGetHeader</function> and
+<function>IceErrorHeader</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceWriteData</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> bytes</parameter></paramdef>
+    <paramdef>char<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>bytes</emphasis></term>
+    <listitem>
+      <para>The number of bytes to write.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>data</emphasis></term>
+    <listitem>
+      <para>The data to write.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+To write data as 16-bit quantities, use <function>IceWriteData16</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceWriteData16</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> bytes</parameter></paramdef>
+    <paramdef>char<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>bytes</emphasis></term>
+    <listitem>
+      <para>The number of bytes to write.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>data</emphasis></term>
+    <listitem>
+      <para>The data to write.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+To write data as 32-bit quantities, use <function>IceWriteData32</function>
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceWriteData32</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> bytes</parameter></paramdef>
+    <paramdef>char<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>bytes</emphasis></term>
+    <listitem>
+      <para>The number of bytes to write.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>data</emphasis></term>
+    <listitem>
+      <para>The data to write.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+To write data as 32-bit quantities, use <function>IceWriteData32</function>
+</para>
+
+<para>
+To bypass copying data to the ICE output buffer, use
+<function>IceSendData</function> to directly send data over the network
+connection.  If necessary, the ICE output buffer is first flushed.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceSendData</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> bytes</parameter></paramdef>
+    <paramdef>char<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>bytes</emphasis></term>
+    <listitem>
+      <para>The number of bytes to send.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>data</emphasis></term>
+    <listitem>
+      <para>The data to send.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+To force 32-bit or 64-bit alignment, use <function>IceWritePad</function>
+A maximum of 7 pad bytes can be specified.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceWritePad</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> bytes</parameter></paramdef>
+    <paramdef>char<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>bytes</emphasis></term>
+    <listitem>
+      <para>The number of bytes to write.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>data</emphasis></term>
+    <listitem>
+      <para>The number of pad bytes to write.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id='reading_ice_messages'>
+<title>Reading ICE Messages</title>
+
+
+<para>
+The ICE library maintains an input buffer used for reading messages.
+If the ICE library chooses to perform nonblocking reads (this is
+implementation-dependent), then for every read operation that it makes,
+zero or more complete messages may be read into the input buffer.  As
+a result, for all of the macros described in this section that read
+messages, an actual read operation will occur on the connection only if
+the data is not already present in the input buffer.
+</para>
+
+
+<para>
+To get the size of the ICE input buffer, use
+<function>IceGetInBufSize</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int<function> IceGetInBufSize</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+When reading messages, care must be taken to check for IO errors.  If
+any IO error occurs in reading any part of a message, the message should
+be thrown out.  After using any of the macros described below for reading
+messages, the <function>IceValidIO</function>
+macro can be used to check if an IO error occurred on the
+connection.  After an IO error has occurred on an ICE connection, all
+read operations will be ignored.  For further information, see
+<link linkend="error_handling">
+<xref linkend="error_handling"></xref></link>.
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Bool<function> IceValidIO</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>The following macros can be used to read ICE messages.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceReadSimpleMessage</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>&lt;C_data_type&gt;<parameter> *pmsg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>&lt;C_data_type&gt;</emphasis></term>
+    <listitem>
+      <para>The actual C data type of the message header.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>pmsg</emphasis></term>
+    <listitem>
+      <para>This pointer is set to the message header.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<function>IceReadSimpleMessage</function>
+is used for messages that are identical in size to the 8-byte ICE header, but
+use the spare 2 bytes in the header to encode additional data.  Note that the
+ICE library always reads in these first 8 bytes, so it can obtain the major
+opcode of the message.  <function>IceReadSimpleMessage</function>
+simply returns a pointer to these 8 bytes; it does not actually read any data
+into the input buffer.
+</para>
+
+<para>
+For a message with variable length data, there are two ways of reading
+the message.  One method involves reading the complete message in one
+pass using <function>IceReadCompleteMessage</function>
+The second method involves reading the message header (note that this may
+be larger than the 8-byte ICE header), then reading
+the variable length data in chunks (see
+<function>IceReadMessageHeader</function> and
+<function>IceReadData</function>
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceReadCompleteMessage</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> header_size</parameter></paramdef>
+    <paramdef>&lt;C_data_type&gt;<parameter> *pmsg</parameter></paramdef>
+    <paramdef>char<parameter> *pdata</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>header_size</emphasis></term>
+    <listitem>
+      <para>The size of the message header (in bytes).</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>&lt;C_data_type&gt;</emphasis></term>
+    <listitem>
+      <para>The actual C data type of the message header.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>pmsg</emphasis></term>
+    <listitem>
+      <para>This pointer is set to the message header.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>pdata</emphasis></term>
+    <listitem>
+      <para>
+This pointer is set to the variable length data of the message.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+If the ICE input buffer has sufficient space,
+<function>IceReadCompleteMessage</function>
+will read the complete message into the
+ICE input buffer.  Otherwise, a buffer will be allocated to hold the
+variable length data.  After the call, the pdata argument should
+be checked against NULL to make sure that there was sufficient memory
+to allocate the buffer.
+</para>
+
+<para>
+After calling <function>IceReadCompleteMessage</function>
+and processing the message, <function>IceDisposeCompleteMessage</function>
+should be called.
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceDisposeCompleteMessage</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>char<parameter> *pdata</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>pdata</emphasis></term>
+    <listitem>
+      <para>
+The pointer to the variable length data returned in
+<function>IceReadCompleteMessage</function>
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+If a buffer had to be allocated to hold the variable length data (because
+it did not fit in the ICE input buffer), it is freed here by ICElib.
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceReadMessageHeader</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> header_size</parameter></paramdef>
+    <paramdef>&lt;C_data_type&gt;<parameter> *pmsg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>header_size</emphasis></term>
+    <listitem>
+      <para>The size of the message header (in bytes).</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>&lt;C_data_type&gt;</emphasis></term>
+    <listitem>
+      <para>The actual C data type of the message header.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>pmsg</emphasis></term>
+    <listitem>
+      <para>This pointer is set to the message header.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<function>IceReadMessageHeader</function> reads just the message header.
+The rest of the data should be read with the
+<function>IceReadData</function>
+family of macros.  This method of reading a message should be used when the
+variable length data must be read in chunks.
+</para>
+
+
+<para>
+To read data directly into a user supplied buffer, use
+<function>IceReadData</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceReadData</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> bytes</parameter></paramdef>
+    <paramdef>char<parameter> *pdata</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>bytes</emphasis></term>
+    <listitem>
+      <para>The number of bytes to read.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>pdata</emphasis></term>
+    <listitem>
+      <para>The data is read into this user supplied buffer.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+To read data as 16-bit quantities, use <function>IceReadData16</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceReadData16</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>Bool<parameter> swap</parameter></paramdef>
+    <paramdef>int<parameter> bytes</parameter></paramdef>
+    <paramdef>char<parameter> *pdata</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>swap</emphasis></term>
+    <listitem>
+      <para>
+If <function>True,</function> the values will be byte swapped.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>bytes</emphasis></term>
+    <listitem>
+      <para>The number of bytes to read.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>pdata</emphasis></term>
+    <listitem>
+      <para>The data is read into this user supplied buffer.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+To read data as 32-bit quantities, use <function>IceReadData32</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceReadData32</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>Bool<parameter> swap</parameter></paramdef>
+    <paramdef>int<parameter> bytes</parameter></paramdef>
+    <paramdef>char<parameter> *pdata</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>swap</emphasis></term>
+    <listitem>
+      <para>
+If <function>True,</function> the values will be byte swapped.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>bytes</emphasis></term>
+    <listitem>
+      <para>The number of bytes to read.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>pdata</emphasis></term>
+    <listitem>
+      <para>The data is read into this user supplied buffer.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>To force 32-bit or 64-bit alignment, use
+<function>IceReadPad</function>
+A maximum of 7 pad bytes can be specified.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceReadPad</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem>
+      <para>A valid ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>bytes</emphasis></term>
+    <listitem>
+      <para>The number of pad bytes.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+</sect1>
+</chapter>
+
+<chapter id='error_handling'>
+<title>Error Handling</title>
+
+
+<para>There are two default error handlers in ICElib:</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+One to handle typically fatal conditions (for example,
+a connection dying because a machine crashed)
+    </para>
+  </listitem>
+  <listitem>
+    <para>One to handle ICE-specific protocol errors</para>
+  </listitem>
+</itemizedlist>
+
+<para>
+These error handlers can be changed to user-supplied routines if you
+prefer your own error handling and can be changed as often as you like.
+</para>
+
+
+<para>
+To set the ICE error handler, use <function>IceSetErrorHandler</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function> IceSetErrorHandler</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>int<parameter> bytes</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>handler</emphasis></term>
+    <listitem>
+      <para>
+The ICE error handler.  You should pass NULL to restore the default handler.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<function>IceSetErrorHandler</function> returns the previous error handler.
+</para>
+
+<para>
+The ICE error handler is invoked when an unexpected ICE protocol
+error (major opcode 0) is encountered.  The action of the default
+handler is to print an explanatory message to
+<function>stderr</function>
+and if the severity is fatal, call
+<function>exit</function>
+with a nonzero value.  If exiting
+is undesirable, the application should register its own error handler.
+</para>
+
+<para>
+Note that errors in other protocol
+domains should be handled by their respective libraries (these libraries
+should have their own error handlers).
+</para>
+
+<para>
+An ICE error handler has the type of <function>IceErrorHandler</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void<function> IceErrorHandler</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>Bool<parameter> swap</parameter></paramdef>
+    <paramdef>int<parameter> offending_minor_opcode</parameter></paramdef>
+    <paramdef>unsigned long<parameter> offending_sequence_num</parameter></paramdef>
+    <paramdef>int<parameter> error_class</parameter></paramdef>
+    <paramdef>int<parameter> severity</parameter></paramdef>
+    <paramdef>IcePointer<parameter> values</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>handler</emphasis></term>
+    <listitem>
+      <para>The ICE connection object.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>swap</emphasis></term>
+    <listitem>
+      <para>A flag that indicates if the values need byte swapping.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>offending_minor_opcode</emphasis></term>
+    <listitem>
+      <para>The ICE minor opcode of the offending message.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>offending_sequence_num</emphasis></term>
+    <listitem>
+      <para>The sequence number of the offending message.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>error_class</emphasis></term>
+    <listitem>
+      <para>The error class of the offending message.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>severity</emphasis></term>
+    <listitem>
+      <para>
+<function>IceCanContinue</function>
+<function>IceFatalToProtocol</function>
+or
+<function>IceFatalToConnection</function>
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>values</emphasis></term>
+    <listitem>
+      <para>
+Any additional error values specific to the minor opcode and class.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>The following error classes are defined at the ICE level:</para>
+
+<literallayout remap='Ds'>
+<function>IceBadMinor</function>
+<function>IceBadState</function>
+<function>IceBadLength</function>
+<function>IceBadValue</function>
+<function>IceBadMajor</function>
+<function>IceNoAuth</function>
+<function>IceNoVersion</function>
+<function>IceSetupFailed</function>
+<function>IceAuthRejected</function>
+<function>IceAuthFailed</function>
+<function>IceProtocolDuplicate</function>
+<function>IceMajorOpcodeDuplicate</function>
+<function>IceUnknownProtocol</function>
+</literallayout>
+
+<para>
+For further information, see
+the <emphasis remap='I'>Inter-Client Exchange Protocol</emphasis> standard.
+</para>
+
+
+<para>
+To handle fatal I/O errors, use <function>IceSetIOErrorHandler</function>
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IceIOErrorHandler<function> IceSetIOErrorHandler</function></funcdef>
+    <paramdef>IceIOErrorHandler<parameter> handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>handler</emphasis></term>
+    <listitem>
+      <para>
+The I/O error handler.  You should pass NULL to restore the default handler.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<function>IceSetIOErrorHandler</function> returns the previous
+IO error handler.
+</para>
+
+<para>
+An ICE I/O error handler has the type of
+<function>IceIOErrorHandler</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void<function> IceIOErrorHandler</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem><para>The ICE connection object.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para> There are two ways of handling IO errors in ICElib:</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+In the first, the IO error handler does whatever is necessary
+to respond to the IO error and then returns, but it does not call
+<function>IceCloseConnection</function>
+The ICE connection is given a "bad IO" status, and all future reads
+and writes to the connection are ignored.  The next time
+<function>IceProcessMessages</function>
+is called it will return a status of
+<function>IceProcessMessagesIOError</function>
+At that time, the application should call
+<function>IceCloseConnection</function>
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+In the second, the IO error handler does call
+<function>IceCloseConnection</function>
+and then uses the <function>longjmp</function>
+call to get back to the application's main event loop.  The
+<function>setjmp</function> and
+<function>longjmp</function>
+calls may not work properly on all platforms,
+and special care must be taken to avoid memory leaks.
+Therefore, this second model is less desirable.
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para>
+Before the application I/O error handler is invoked, protocol libraries
+that were interested in being notified of I/O errors will have their
+<function>IceIOErrorProc</function>
+handlers invoked.  This handler is set up in the protocol registration
+functions (see <function>IceRegisterForProtocolSetup</function> and
+<function>IceRegisterForProtocolReply</function>
+and could be used to clean up state specific to the protocol.
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void<function> IceIOErrorProc</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem><para>The ICE connection object.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+Note that every <function>IceIOErrorProc</function>
+callback must return.  This is required
+because each active protocol must be notified of the broken connection,
+and the application IO error handler must be invoked afterwards.
+</para>
+</chapter>
+
+<chapter id='multithreading_support'>
+<title>Multi-Threading Support</title>
+
+
+<para>To declare that multiple threads in an application will be using the ICE
+library, use
+<function>IceInitThreads</function></para>
+
+<literallayout remap='FD'>
+Status IceInitThreads()
+</literallayout>
+
+
+<para>The
+<function>IceInitThreads</function>
+function must be the first ICElib function a
+multi-threaded program calls.  It must complete before any other ICElib
+call is made.
+<function>IceInitThreads</function>
+returns a nonzero status if and only if it was able
+to initialize the threads package successfully.
+It is safe to call
+<function>IceInitThreads</function>
+more than once, although the threads package will only be initialized once.</para>
+
+<para>Protocol libraries layered on top of ICElib will have to lock critical
+sections of code that access an ICE connection (for example, when
+generating messages).  Two calls, which are generally implemented as
+macros, are provided:</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void<function> IceLockConn</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void<function> IceUnlockConn</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem><para>The ICE connection object.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>To keep an ICE connection locked across several ICElib calls, applications use
+<function>IceAppLockConn</function>
+and
+<function>IceAppUnlockConn</function></para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void<function> IceAppLockConn</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem><para>The ICE connection object.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>The
+<function>IceAppLockConn</function>
+function completely locks out other threads using the connection
+until
+<function>IceAppUnlockConn</function>
+is called.  Other threads attempting to use ICElib
+calls on the connection will block.
+If the program has not previously called
+<function>IceInitThreads</function>
+<function>IceAppLockConn</function>
+has no effect.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void<function> IceAppUnlockConn</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem><para>The ICE connection object.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>The
+<function>IceAppUnlockConn</function>
+function allows other threads to complete ICElib
+calls on the connection that were blocked by a previous call to
+<function>IceAppLockConn</function>
+from this thread.  If the program has not previously called
+<function>IceInitThreads</function>
+<function>IceAppUnlockConn</function>
+has no effect.</para>
+</chapter>
+
+<chapter id='miscellaneous_functions'>
+<title>Miscellaneous Functions</title>
+
+
+
+
+<para>To allocate scratch space (for example, when generating
+messages with variable data), use
+<function>IceAllocScratch</function>
+Each ICE connection has one scratch space associated with it.
+The scratch space starts off as empty and grows as needed.
+The contents of the scratch space is not guaranteed to be preserved
+after any ICElib function is called.</para>
+
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>char<function> *IceAllocScratch</function></funcdef>
+    <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
+    <paramdef>unsigned long<parameter> size</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>ice_conn</emphasis></term>
+    <listitem><para>The ICE connection object.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>size</emphasis></term>
+    <listitem><para>The number of bytes required.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>Note that the memory returned by
+<function>IceAllocScratch</function>
+should not be freed by the caller.
+The ICE library will free the memory when the ICE connection is closed.</para>
+</chapter>
+
+<chapter id='acknowledgements'>
+<title>Acknowledgements</title>
+
+
+<para>
+Thanks to Bob Scheifler for his thoughtful input on the design
+of the ICE library.  Thanks also to Jordan Brown, Larry Cable, Donna Converse,
+Clive Feather, Stephen Gildea, Vania Joloboff, Kaleb Keithley,
+Stuart Marks, Hiro Miyamoto, Ralph Swick, Jim VanGilder, and Mike Wexler.
+</para>
+</chapter>
+
+<appendix id="authentication_utility_functions">
+<title>Authentication Utility Functions</title>
+
+
+<para>
+As discussed in this document, the means by which authentication data
+is obtained by the ICE library (for
+<function>ConnectionSetup</function>
+messages or
+<function>ProtocolSetup</function>
+messages) is implementation-dependent.&dagger;
+<footnote remap='FS'>
+<para>The X Consortium's ICElib implementation assumes the presence of an
+ICE authority file.
+</para></footnote>
+</para>
+
+<para>
+This appendix describes some utility functions that manipulate an
+ICE authority file.  The authority file can be used to pass authentication
+data between clients.
+</para>
+
+<para>The basic operations on the .ICEauthority file are:</para>
+
+<itemizedlist>
+  <listitem>
+    <para>Get file name</para>
+  </listitem>
+  <listitem>
+    <para>Lock</para>
+  </listitem>
+  <listitem>
+    <para>Unlock</para>
+  </listitem>
+  <listitem>
+    <para>Read entry</para>
+  </listitem>
+  <listitem>
+    <para>Write entry</para>
+  </listitem>
+  <listitem>
+    <para>Search for entry</para>
+  </listitem>
+</itemizedlist>
+
+<para>
+These are fairly low-level operations, and it is expected that a program,
+like "iceauth", would exist to add, remove, and display entries in the file.
+</para>
+
+<para>
+In order to use these utility functions, the
+&lt;<symbol role='Pn'>X11/ICE/ICEutil.h</symbol>&gt;
+header file must be included.
+</para>
+
+<para>
+An entry in the .ICEauthority file is defined by the following data structure:
+</para>
+
+
+<literallayout class="monospaced">
+typedef struct {
+     char *protocol_name;
+     unsigned short protocol_data_length;
+     char *protocol_data;
+     char *network_id;
+     char *auth_name;
+     unsigned short auth_data_length;
+     char *auth_data;
+} IceAuthFileEntry;
+</literallayout>
+
+
+<para>
+The protocol_name member is either "ICE" for connection setup authentication
+or the subprotocol name, such as "XSMP".  For each entry, protocol specific
+data can be specified in the protocol_data member.  This can be used
+to search for old entries that need to be removed from the file.
+</para>
+
+<para>
+The network_id member is the network ID of the client accepting
+authentication (for example, the network ID of a session manager).
+A network ID has the following form:
+</para>
+
+<informaltable pgwide='0' frame='none'>
+  <tgroup cols='3' align='center'>
+    <colspec colname='c1'/>
+    <colspec colname='c2'/>
+    <colspec colname='c3'/>
+    <tbody>
+      <row>
+        <entry align='left'></entry>
+        <entry align='left'>tcp/&lt;hostname&gt;:&lt;portnumber&gt;</entry>
+        <entry align='left'>or</entry>
+      </row>
+      <row>
+        <entry align='left'></entry>
+        <entry align='left'>decnet/&lt;hostname&gt;::&lt;objname&gt;</entry>
+        <entry align='left'>or</entry>
+      </row>
+      <row>
+        <entry align='left'></entry>
+        <entry align='left'>local/&lt;hostname&gt;:&lt;path&gt;</entry>
+        <entry align='left'></entry>
+      </row>
+    </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+The auth_name member is the name of the authentication method.
+The auth_data member is the actual authentication data,
+and the auth_data_length member is the number of bytes in the data.
+</para>
+
+<para>
+To obtain the default authorization file name, use
+<function>IceAuthFileName</function>
+</para>
+
+<literallayout remap='FD'>
+char *IceAuthFileName()
+</literallayout>
+
+<para>
+If the ICEAUTHORITY environment variable if set, this value is returned.
+Otherwise, the default authorization file name is $HOME/.ICEauthority.
+This name is statically allocated and should not be freed.
+</para>
+
+<para>
+To synchronously update the authorization file, the file must
+be locked with a call to
+<function>IceLockAuthFile</function>
+This function takes advantage of the fact that the
+<function>link</function>
+system call will fail if the name of the new link already exists.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int<function> IceLockAuthFile</function></funcdef>
+    <paramdef>char<parameter> *file_name</parameter></paramdef>
+    <paramdef>int<parameter> retries</parameter></paramdef>
+    <paramdef>int<parameter> timeout</parameter></paramdef>
+    <paramdef>long<parameter> dead</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>file_name</emphasis></term>
+    <listitem><para>The authorization file to lock.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>retries</emphasis></term>
+    <listitem>
+      <para>The number of retries.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>timeout</emphasis></term>
+    <listitem>
+      <para>The number of seconds before each retry.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>dead</emphasis></term>
+    <listitem>
+      <para>
+If a lock already exists that is the specified dead seconds old,
+it is broken.
+A value of zero is used to unconditionally break an old lock.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>One of three values is returned:</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+<function>IceAuthLockSuccess</function> - the lock succeeded.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>IceAuthLockError</function> - a system error occurred, and
+<function>errno</function> may prove useful.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>IceAuthLockTimeout</function> - the specified number of
+retries failed.
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para>
+To unlock an authorization file, use <function>IceUnlockAuthFile</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int<function> IceUnlockAuthFile</function></funcdef>
+    <paramdef>char<parameter> *file_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>file_name</emphasis></term>
+    <listitem><para>The authorization file to unlock.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+To read the next entry in an authorization file, use
+<function>IceReadAuthFileEntry</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IceAuthFileEntry<function> *IceReadAuthFileEntry</function></funcdef>
+    <paramdef>FILE<parameter> *auth_file</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>auth_file</emphasis></term>
+    <listitem><para>The authorization file.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+Note that it is the responsibility of the application to open the file
+for reading before calling this function.  If an error is encountered,
+or there are no more entries to read, NULL is returned.
+</para>
+
+<para>
+Entries should be free with a call to
+<function>IceFreeAuthFileEntry</function>
+</para>
+
+<para>
+To write an entry in an authorization file, use
+<function>IceWriteAuthFileEntry</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status<function> IceWriteAuthFileEntry</function></funcdef>
+    <paramdef>FILE<parameter> *auth_file</parameter></paramdef>
+    <paramdef>IceAuthFileEntry<parameter> *entry</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>auth_file</emphasis></term>
+    <listitem><para>The authorization file.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>entry</emphasis></term>
+    <listitem><para>The entry to write.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+Note that it is the responsibility of the application to open the file
+for writing before calling this function.  The function returns a nonzero
+status if the operation was successful.
+</para>
+
+
+<para>
+To search the default authorization file for an entry that matches a given
+protocol_name/network_id/auth_name tuple, use
+<function>IceGetAuthFileEntry</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>IceAuthFileEntry<function> *IceGetAuthFileEntry</function></funcdef>
+    <paramdef>char<parameter> *protocol_name</parameter></paramdef>
+    <paramdef>char<parameter> *network_id</parameter></paramdef>
+    <paramdef>char<parameter> *auth_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>auth_file</emphasis></term>
+    <listitem><para>The name of the protocol to search on.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>network_id</emphasis></term>
+    <listitem>
+      <para>The network ID to search on.</para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>auth_name</emphasis></term>
+    <listitem>
+      <para>The authentication method to search on.</para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+If <function>IceGetAuthFileEntry</function>
+fails to find such an entry, NULL is returned.
+</para>
+
+
+<para>
+To free an entry returned by
+<function>IceReadAuthFileEntry</function> or
+<function>IceGetAuthFileEntry</function> use
+<function>IceFreeAuthFileEntry</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void<function> IceFreeAuthFileEntry</function></funcdef>
+    <paramdef>IceAuthFileEntry<parameter> *entry</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>entry</emphasis></term>
+    <listitem><para>The entry to free.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+</appendix>
+
+<appendix id="mit_magic_cookie_1_authentication">
+<title>MIT-MAGIC-COOKIE-1 Authentication</title>
+
+
+<para>The X Consortium's ICElib implementation supports a simple
+MIT-MAGIC-COOKIE-1 authentication scheme using the authority file utilities
+described in Appendix A.</para>
+
+<para>In this model, an application, such as a session manager, obtains a
+magic cookie by calling
+<function>IceGenerateMagicCookie</function>
+and then stores it in the user's local .ICEauthority file
+so that local clients can connect.  In order to allow remote clients to
+connect, some remote execution mechanism should be used to store the
+magic cookie in the user's .ICEauthority file on a remote machine.</para>
+
+<para>In addition to storing the magic cookie in the .ICEauthority file, the
+application needs to call the
+<function>IceSetPaAuthData</function>
+function in order to store the magic cookie in memory.  When it comes time
+for the MIT-MAGIC-COOKIE-1 authentication procedure to accept or reject the
+connection, it will compare the magic cookie presented by the requestor to
+the magic cookie in memory.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>char<function> *IceGenerateMagicCookie</function></funcdef>
+    <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>length</emphasis></term>
+    <listitem><para>The desired length of the magic cookie.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>The magic cookie returned will be null-terminated.  If memory can not be
+allocated for the magic cookie, the function will return NULL.
+Otherwise, the magic cookie should be freed with a call to
+<function>free</function></para>
+
+
+<para>To store the authentication data in memory, use
+<function>IceSetPaAuthData</function>
+Currently, this function is only used for MIT-MAGIC-COOKIE-1
+authentication, but it may be used for additional authentication
+methods in the future.</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void<function> IceSetPaAuthData</function></funcdef>
+    <paramdef>int<parameter> num_entries</parameter></paramdef>
+    <paramdef>IceAuthDataEntry<parameter> *entries</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>num_entries</emphasis></term>
+    <listitem><para>The number of authentication data entries.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>entries</emphasis></term>
+    <listitem><para>The list of authentication data entries.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>Each entry has associated with it a protocol name
+(for example, "ICE" for ICE connection setup authentication,
+"XSMP" for session management authentication), a network ID for the
+"accepting" client, an authentication name (for example, MIT-MAGIC-COOKIE-1),
+and authentication data.  The ICE library
+will merge these entries with previously set entries, based on the
+(protocol_name, network_id, auth_name) tuple.</para>
+
+
+
+<literallayout class="monospaced">
+typedef struct {
+	char *protocol_name;
+	char *network_id;
+	char *auth_name;
+	unsigned short auth_data_length;
+	char *auth_data;
+} IceAuthDataEntry;
+</literallayout>
+
+</appendix>
+</book>
+