specs/ice.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
   4 [
   5 <!ENTITY % defs SYSTEM "defs.ent"> %defs;
   6 ]>
   7
   8
   9 <!-- lifted from troff+ms+XMan by doclifter -->
  10 <book id="ice">
  11
  12 <bookinfo>
  13    <title>Inter-Client Exchange (ICE) Protocol</title>
  14    <subtitle>X Consortium Standard</subtitle>
  15    <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
  16    <authorgroup>
  17       <author>
  18          <firstname>Robert</firstname><surname>Scheifler</surname>
  19          <affiliation><orgname>X Consortium</orgname></affiliation>
  20       </author>
  21       <othercredit>
  22          <firstname>Jordan</firstname><surname>Brown</surname>
  23          <affiliation><orgname>Quarterdeck Office Systems</orgname></affiliation>
  24       </othercredit>
  25    </authorgroup>
  26    <releaseinfo>Version 1.1</releaseinfo>
  27    <copyright>
  28      <year>1993</year><year>1994</year>
  29      <holder>X Consortium</holder>
  30    </copyright>
  31
  32 <legalnotice>
  33 <para>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the &ldquo;Software&rdquo;), 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>
  34
  35 <para>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</para>
  36
  37 <para>THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, 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>
  38
  39 <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>
  40
  41 <para>X Window System is a trademark of The Open Group.</para>
  42 </legalnotice>
  43
  44 <abstract>
  45 <para>
  46 There are numerous possible protocols that can be used for communication
  47 among clients.  They have many similarities and common needs, including
  48 authentication, version negotiation, data typing, and connection management.  The <emphasis remap='I'> Inter-Client Exchange</emphasis> (ICE) protocol
  49 is intended to provide a framework for building such protocols.  Using
  50 ICE reduces the complexity of designing new protocols and
  51 allows the sharing of many aspects of the implementation.
  52 </para>
  53 </abstract>
  54 </bookinfo>
  55
  56 <chapter id='Purpose_and_Goals'>
  57 <title>Purpose and Goals</title>
  58
  59 <para>
  60 In discussing a variety of protocols -- existing, under development, and
  61 hypothetical -- it was noted that they have many elements in common.  Most
  62 protocols need mechanisms for authentication, for
  63 version negotiation,
  64 and for setting up and taking down connections.  There are also
  65 cases where the same two parties need to talk to each other using multiple
  66 protocols.  For example, an embedding relationship between two parties is
  67 likely to require the simultaneous use of session management, data transfer,
  68 focus negotiation, and command notification protocols.  While these are
  69 logically separate protocols, it is desirable for them to share as many
  70 pieces of implementation as possible.</para>
  71
  72 <para>The
  73 <emphasis remap='I'>
  74 Inter-Client Exchange
  75 </emphasis>
  76 (ICE) protocol provides a generic framework for building protocols on top of
  77 reliable, byte-stream transport connections.  It provides basic mechanisms
  78 for setting up and shutting down connections, for performing authentication,
  79 for negotiating
  80 versions,
  81 and for reporting errors.  The
  82 protocols running within an ICE connection are referred to here as
  83 <emphasis remap='I'>subprotocols.</emphasis>
  84 ICE provides facilities for each subprotocol to do its own version
  85 negotiation, authentication, and error reporting.  In addition, if two
  86 parties are communicating using several different subprotocols, ICE will
  87 allow them to share the same transport layer connection.</para>
  88
  89 </chapter>
  90
  91 <chapter id='Overview_of_the_Protocol'>
  92 <title>Overview of the Protocol</title>
  93
  94
  95 <para>Through some mechanism outside ICE, two parties make themselves known to
  96 each other and agree that they would like to communicate using an ICE
  97 subprotocol.  ICE assumes that this negotation includes some notion by which
  98 the parties will decide which is the \*Qoriginating\*U party and which is
  99 the \*Qanswering\*U party.  The negotiation will also need to provide the
 100 originating party with a name or address of the answering party.  Examples
 101 of mechanisms by which parties can make themselves known to each other are
 102 the X selection mechanism, environment
 103 variables, and shared files.</para>
 104
 105 <para>The originating party first determines whether there is an existing ICE
 106 connection between the two parties.  If there is, it can re-use the existing
 107 connection and move directly to the setup of the subprotocol.  If no ICE
 108 connection exists, the originating party will open a transport connection to
 109 the answering party and will start ICE connection setup.</para>
 110
 111 <para>The ICE connection setup dialog consists of three major parts: byte order
 112 exchange, authentication, and connection information exchange.  The first
 113 message in each direction is a
 114 <function>ByteOrder</function>
 115 message telling which byte order will be used by the sending party in
 116 messages that it sends.  After that, the originating party sends a
 117 <function>ConnectionSetup</function>
 118 message giving information about itself (vendor name and release number) and
 119 giving a list of ICE version numbers it is capable of supporting and a list
 120 of authentication schemes it is willing to accept.  Authentication is
 121 optional.  If no authentication is required, the answering party responds
 122 with a
 123 <function>ConnectionReply</function>
 124 message giving information about itself, and the connection setup is complete.</para>
 125
 126 <para>If the connection setup is to be authenticated, the answering party will
 127 respond with an
 128 <function>AuthenticationRequired</function>
 129 message instead of a
 130 <function>ConnectionReply</function>
 131 message.  The parties then exchange
 132 <function>AuthenticationReply</function>
 133 and
 134 <function>AuthenticationNextPhase</function>
 135 messages until authentication is complete, at which time the answering party
 136 finally sends its
 137 <function>ConnectionReply</function>
 138 message.</para>
 139
 140 <para>Once an ICE connection is established (or an existing connection reused),
 141 the originating party starts subprotocol negotiation by sending a
 142 <function>ProtocolSetup</function>
 143 message.  This message gives the name of the subprotocol that the parties
 144 have agreed to use, along with the ICE major opcode that the originating
 145 party has assigned to that subprotocol.  Authentication can also occur for
 146 the subprotocol, independently of authentication for the connection.
 147 Subprotocol authentication is optional.  If there is no subprotocol
 148 authentication, the answering party responds with a
 149 <function>ProtocolReply</function>
 150 message, giving the ICE major opcode that it has assigned
 151 for the subprotocol.</para>
 152
 153 <para>Subprotocols are authenticated independently of each other, because they may
 154 have differing security requirements.  If there is authentication for this
 155 particular subprotocol, it takes place before the answering party emits the
 156 <function>ProtocolReply</function>
 157 message, and it uses the
 158 <function>AuthenticationRequired</function>
 159 <function>AuthenticationReply</function>
 160 and
 161 <function>AuthenticationNextPhase</function>
 162 messages, just as for the connection authentication.  Only when subprotocol
 163 authentication is complete does the answering party send its
 164 <function>ProtocolReply</function>
 165 message.</para>
 166
 167 <para>When a subprotocol has been set up and authenticated, the two parties can
 168 communicate using messages defined by the subprotocol.  Each message has two
 169 opcodes: a major opcode and a minor opcode.  Each party will send messages
 170 using the major opcode it has assigned in its
 171 <function>ProtocolSetup</function>
 172 or
 173 <function>ProtocolReply</function>
 174 message.  These opcodes will, in general, not be the same.  For a particular
 175 subprotocol, each party will need to keep track of two major opcodes: the
 176 major opcode it uses when it sends messages, and the major opcode it expects
 177 to see in messages it receives.  The minor opcode values and semantics are
 178 defined by each individual subprotocol.</para>
 179
 180 <para>Each subprotocol will have one or more messages whose semantics are that the
 181 subprotocol is to be shut down.  Whether this is done unilaterally or is
 182 performed through negotiation is defined by each subprotocol.  Once a
 183 subprotocol is shut down, its major opcodes are removed from
 184 use; no further messages on this subprotocol should be sent until the
 185 opcode is reestablished with
 186 <function>ProtocolSetup</function>
 187 </para>
 188
 189 <para>ICE has a facility to negotiate the closing of the connection when there are
 190 no longer any active subprotocols.  When either party decides that no
 191 subprotocols are active, it can send a
 192 <function>WantToClose</function>
 193 message.  If the other party agrees to close the connection, it can simply
 194 do so.  If the other party wants to keep the connection open, it can
 195 indicate its desire by replying with a
 196 <function>NoClose</function>
 197 message.</para>
 198 <!--  XXX \- Note that it's likely that both parties will WantToClose at once. -->
 199
 200 <para>It should be noted that the party that initiates the connection isn't
 201 necessarily the same as the one that initiates setting up a subprotocol.
 202 For example, suppose party A connects to party B.  Party A will issue the
 203 <function>ConnectionSetup</function>
 204 message and party B will respond with a
 205 <function>ConnectionReply</function>
 206 message.  (The authentication steps are omitted here for brevity.)
 207 Typically, party A will also issue the
 208 <function>ProtocolSetup</function>
 209 message and expect a
 210 <function>ProtocolReply</function>
 211 from party B.  Once the connection is established, however, either party may
 212 initiate the negotiation of a subprotocol.  Continuing this example, party B
 213 may decide that it needs to set up a subprotocol for communication with
 214 party A.  Party B would issue the
 215 <function>ProtocolSetup</function>
 216 message and expect a
 217 <function>ProtocolReply</function>
 218 from party A.</para>
 219 <!--  .nH 1 "Data Types" -->
 220 </chapter>
 221
 222 <chapter id='Data_Types'>
 223 <title>Data Types</title>
 224
 225 <para>ICE messages contain several types of data.  Byte order is negotiated in
 226 the initial connection messages; in general data is sent in the sender's
 227 byte order and the receiver is required to swap it appropriately.
 228 In order to support 64-bit machines, ICE messages
 229 are padded to multiples of 8 bytes.  All messages are designed so that
 230 fields are \*Qnaturally\*U aligned on 16-, 32-, and 64-bit boundaries.
 231 The following formula gives the number of bytes necessary
 232 to pad <emphasis remap='I'>E</emphasis> bytes to the next multiple of
 233 <emphasis remap='I'>b</emphasis>:</para>
 234 <literallayout remap='DS'>
 235
 236 pad(<emphasis remap='I'>E</emphasis>, <emphasis remap='I'>b</emphasis>) = (<emphasis remap='I'>b</emphasis> - (<emphasis remap='I'>E</emphasis> mod <emphasis remap='I'>b</emphasis>)) mod <emphasis remap='I'>b</emphasis>
 237 </literallayout>
 238
 239 <sect1 id='Primitive_Types'>
 240 <title>Primitive Types</title>
 241
 242 <informaltable frame='topbot'>
 243   <?dbfo keep-together="always" ?>
 244   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 245     <colspec colname='c1' colwidth='1.0*'/>
 246     <colspec colname='c2' colwidth='3.0*'/>
 247     <thead>
 248       <row rowsep='1'>
 249         <entry>Type Name</entry>
 250         <entry>Description</entry>
 251       </row>
 252     </thead>
 253     <tbody>
 254       <row>
 255         <entry>CARD8</entry>
 256         <entry>8-bit unsigned integer</entry>
 257       </row>
 258       <row>
 259         <entry>CARD16</entry>
 260         <entry>16-bit unsigned integer</entry>
 261       </row>
 262       <row>
 263         <entry>CARD32</entry>
 264         <entry>32-bit unsigned integer</entry>
 265       </row>
 266       <row>
 267         <entry>BOOL</entry>
 268         <entry><para><function>False</function>
 269 or
 270 <function>True</function></para></entry>
 271       </row>
 272       <row>
 273         <entry>LPCE</entry>
 274         <entry>A character from the X Portable Character Set in Latin Portable Character
 275 Encoding</entry>
 276       </row>
 277     </tbody>
 278   </tgroup>
 279 </informaltable>
 280
 281 </sect1>
 282
 283 <sect1 id='Complex_Types'>
 284 <title>Complex Types</title>
 285
 286 <informaltable frame='topbot'>
 287   <?dbfo keep-together="always" ?>
 288   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 289     <colspec colname='c1' colwidth='1.0*'/>
 290     <colspec colname='c2' colwidth='3.0*'/>
 291     <thead>
 292       <row rowsep='1'>
 293         <entry>Type Name</entry>
 294         <entry>Type</entry>
 295       </row>
 296     </thead>
 297     <tbody>
 298       <row>
 299         <entry>VERSION</entry>
 300         <entry>[Major, minor: CARD16]</entry>
 301       </row>
 302       <row>
 303         <entry>STRING</entry>
 304         <entry>LISTofLPCE</entry>
 305       </row>
 306     </tbody>
 307   </tgroup>
 308 </informaltable>
 309
 310
 311 <para>LISTof&lt;type&gt; denotes a counted collection of &lt;type&gt;.  The exact encoding
 312 varies depending on the context; see the encoding section.</para>
 313 <!--  .nH 1 "Message Format" -->
 314 </sect1>
 315
 316 <sect1 id='Message_Format'>
 317 <title>Message Format</title>
 318
 319 <para>All ICE messages include the following information:</para>
 320
 321 <informaltable frame='topbot'>
 322   <?dbfo keep-together="always" ?>
 323   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 324     <colspec colname='c1' colwidth='1.0*'/>
 325     <colspec colname='c2' colwidth='3.0*'/>
 326     <thead>
 327       <row rowsep='1'>
 328         <entry>Field Type</entry>
 329         <entry>Description</entry>
 330       </row>
 331     </thead>
 332     <tbody>
 333       <row>
 334         <entry>CARD8</entry>
 335         <entry>protocol major opcode</entry>
 336       </row>
 337       <row>
 338         <entry>CARD8</entry>
 339         <entry>protocol minor opcode</entry>
 340       </row>
 341       <row>
 342         <entry>CARD32</entry>
 343         <entry>length of remaining data in 8-byte units</entry>
 344       </row>
 345     </tbody>
 346   </tgroup>
 347 </informaltable>
 348
 349
 350 <para>The fields are as follows:</para>
 351
 352 <variablelist>
 353   <varlistentry>
 354     <term>Protocol major opcode</term>
 355     <listitem>
 356       <para>
 357 This specifies what subprotocol the message is intended for.  Major opcode
 358 0 is reserved for ICE control messages.  The major opcodes of other
 359 subprotocols are dynamically assigned and exchanged at protocol
 360 negotiation time.
 361       </para>
 362     </listitem>
 363   </varlistentry>
 364   <varlistentry>
 365     <term>Protocol minor opcode</term>
 366     <listitem>
 367       <para>
 368 This specifies what protocol-specific operation is to be performed.
 369 Minor opcode 0 is reserved for Errors; other values are protocol-specific.
 370       </para>
 371     </listitem>
 372   </varlistentry>
 373   <varlistentry>
 374     <term>Length of data in 8-byte units</term>
 375     <listitem>
 376       <para>
 377 This specifies the length of the information following the first 8 bytes.
 378 Each message-type has a different format, and will need to be separately
 379 length-checked against this value.  As every data item has either an
 380 explicit length, or an implicit length, this can be easily accomplished.
 381 Messages that have too little or too much data indicate a serious
 382 protocol failure, and should result in a <function>BadLength</function>
 383 error.
 384       </para>
 385     </listitem>
 386   </varlistentry>
 387 </variablelist>
 388 </sect1>
 389
 390 </chapter>
 391
 392 <chapter id='Overall_Protocol_Description'>
 393 <title>Overall Protocol Description</title>
 394
 395 <para>
 396 Every message sent in a given direction has an implicit sequence number,
 397 starting with 1.  Sequence numbers are global to the connection; independent
 398 sequence numbers are <emphasis remap='I'>not</emphasis> maintained for each protocol.</para>
 399
 400 <para>Messages of a given major-opcode (i.e., of a given protocol) must be
 401 responded to (if a response is called for) in order by the receiving party.
 402 Messages from different protocols can be responded to in arbitrary order.</para>
 403
 404 <para>Minor opcode 0 in every protocol is for reporting errors.  At most one error
 405 is generated per request.  If more than one error condition is encountered
 406 in processing a request, the choice of which error is returned is
 407 implementation-dependent.
 408 </para>
 409
 410 <para><function>Error</function></para>
 411 <variablelist remap='IP'>
 412   <varlistentry>
 413     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
 414     <listitem>
 415       <para>CARD8</para>
 416     </listitem>
 417   </varlistentry>
 418   <varlistentry>
 419     <term><emphasis remap='I'>severity</emphasis>:</term>
 420     <listitem>
 421       <para>
 422 {<symbol role='Pn'>CanContinue</symbol>,
 423 <function>FatalToProtocol</function>
 424 <function>FatalToConnection</function>
 425       </para>
 426     </listitem>
 427   </varlistentry>
 428   <varlistentry>
 429     <term><emphasis remap='I'>sequence-number</emphasis>:</term>
 430     <listitem>
 431       <para>CARD32</para>
 432     </listitem>
 433   </varlistentry>
 434   <varlistentry>
 435     <term><emphasis remap='I'>class</emphasis>:</term>
 436     <listitem>
 437       <para>CARD16</para>
 438     </listitem>
 439   </varlistentry>
 440   <varlistentry>
 441     <term><emphasis remap='I'>value(s)</emphasis>:</term>
 442     <listitem>
 443       <para>&lt;dependent on major/minor opcode and class&gt;</para>
 444     </listitem>
 445   </varlistentry>
 446 </variablelist>
 447
 448 <para>
 449 This message is sent to report an error in response to a message
 450 from any protocol.  The <function>Error</function> message
 451 exists in all protocol major-opcode spaces; it
 452 is minor-opcode zero in every protocol.  The minor opcode of the
 453 message that caused the error is reported, as well as the sequence
 454 number of that message.
 455 The severity indicates the sender's behavior following
 456 the identification of the error.  <function>CanContinue</function>
 457 indicates the sender is willing to accept additional messages for this
 458 protocol.  <function>FatalToProcotol</function>
 459 indicates the sender is unwilling to accept further messages for this
 460 protocol but that messages for other protocols may be accepted.
 461 <function>FatalToConnection</function>
 462 indicates the sender is unwilling to accept any further
 463 messages for any protocols on the connection.  The sender
 464 is required to conform to specified severity conditions
 465 for generic and ICE (major opcode 0) errors; see
 466 <xref linkend='Generic_Error_Classes' xrefstyle='select: title'/>
 467 <xref linkend='ICE_Error_Classes' xrefstyle='select: title'/>
 468 .
 469 The class defines the generic class of
 470 error.  Classes are specified separately for each protocol (numeric
 471 values can mean different things in different protocols).  The error
 472 values, if any, and their types vary with the specific error class
 473 for the protocol.
 474 </para>
 475 </chapter>
 476
 477 <chapter id='ICE_Control_Subprotocol____Major_Opcode_0_0'>
 478 <title>ICE Control Subprotocol -- Major Opcode 0</title>
 479
 480 <para>
 481 Each of the ICE control opcodes is described below.
 482 Most of the messages have additional information included beyond the
 483 description above.  The additional information is appended to the message
 484 header and the length field is computed accordingly.
 485 </para>
 486
 487 <para>
 488 In the following message descriptions, \*QExpected errors\*U indicates
 489 errors that may occur in the normal course of events.  Other errors
 490 (in particular
 491 <function>BadMajor</function>
 492 <function>BadMinor</function>
 493 <function>BadState</function>
 494 <function>BadLength</function>
 495 <function>BadValue</function>
 496 <function>ProtocolDuplicate</function> and
 497 <function>MajorOpcodeDuplicate</function>
 498 might occur, but generally indicate a serious implementation failure on
 499 the part of the errant peer.
 500 </para>
 501 <para><function>ByteOrder</function></para>
 502
 503 <variablelist>
 504   <varlistentry>
 505     <term><emphasis remap='I'>byte-order</emphasis>:</term>
 506     <listitem>
 507       <para>
 508 {<symbol role='Pn'>MSBfirst</symbol>,
 509 <function>LSBfirst</function>
 510       </para>
 511     </listitem>
 512   </varlistentry>
 513 </variablelist>
 514
 515 <para>
 516 Both parties must send this message before sending any other,
 517 including errors.  This message specifies the byte order that
 518 will be used on subsequent messages sent by this party.
 519 </para>
 520
 521 <note>
 522 <para>
 523 Note:  If the receiver detects an error in this message,
 524 it must be sure to send its own
 525 <function>ByteOrder</function> message before sending the
 526 <function>Error</function>.
 527 </para>
 528 </note>
 529
 530 <para><function>ConnectionSetup</function></para>
 531
 532 <variablelist>
 533   <varlistentry>
 534     <term><emphasis remap='I'>versions</emphasis>:</term>
 535     <listitem>
 536       <para>LISTofVERSION</para>
 537     </listitem>
 538   </varlistentry>
 539   <varlistentry>
 540     <term><emphasis remap='I'>must-authenticate</emphasis>:</term>
 541     <listitem>
 542       <para>BOOL</para>
 543     </listitem>
 544   </varlistentry>
 545   <varlistentry>
 546     <term><emphasis remap='I'>authentication-protocol-names</emphasis>:</term>
 547     <listitem>
 548       <para>LISTofSTRING</para>
 549     </listitem>
 550   </varlistentry>
 551   <varlistentry>
 552     <term><emphasis remap='I'>vendor</emphasis>:</term>
 553     <listitem>
 554       <para>STRING</para>
 555     </listitem>
 556   </varlistentry>
 557   <varlistentry>
 558     <term><emphasis remap='I'>release</emphasis>:</term>
 559     <listitem>
 560       <para>STRING</para>
 561     </listitem>
 562   </varlistentry>
 563   <varlistentry>
 564     <term>Responses:</term>
 565     <listitem>
 566       <para>
 567 <function>ConnectionReply</function>,
 568 <function>AuthenticationRequired</function> (See note)
 569       </para>
 570     </listitem>
 571   </varlistentry>
 572   <varlistentry>
 573     <term>Expected errors:</term>
 574     <listitem>
 575       <para>
 576 <function>NoVersion</function>,
 577 <function>SetupFailed</function>,
 578 <function>NoAuthentication</function>,
 579 <function>AuthenticationRejected</function>,
 580 <function>AuthenticationFailed</function>
 581       </para>
 582     </listitem>
 583   </varlistentry>
 584 </variablelist>
 585
 586 <para>
 587 The party that initiates the connection (the one that does the
 588 "connect()") must send this message as the second message (after
 589 <function>ByteOrder</function> on startup.
 590 </para>
 591
 592 <para>
 593 Versions gives a list, in decreasing order of preference, of the
 594 protocol versions this party is capable of speaking.  This document
 595 specifies major version 1, minor version 0.
 596 </para>
 597
 598 <para>
 599 If must-authenticate is <function>True</function> the initiating
 600 party demands authentication; the accepting party
 601 <emphasis remap='I'>must</emphasis> pick an authentication scheme
 602 and use it.  In this case, the only valid response is
 603 <function>AuthenticationRequired</function>
 604 </para>
 605
 606 <para>
 607 If must-authenticate is <function>False</function> the accepting
 608 party may choose an authentication mechanism, use a host-address-based
 609 authentication scheme, or skip authentication.  When must-authenticate
 610 is <function>False</function> <function>ConnectionReply</function> and
 611 <function>AuthenticationRequired</function> are both valid responses.
 612 If a host-address-based authentication scheme is used,
 613 <function>AuthenticationRejected</function> and
 614 <function>AuthenticationFailed</function> errors are possible.
 615 </para>
 616
 617 <para>
 618 Authentication-protocol-names specifies a (possibly null, if
 619 must-authenticate is <function>False</function>
 620 list of authentication protocols the party is willing to perform.  If
 621 must-authenticate is <function>True</function>
 622 presumably the party will offer only authentication mechanisms
 623 allowing mutual authentication.
 624 </para>
 625
 626 <para>
 627 Vendor gives the name of the vendor of this ICE implementation.
 628 </para>
 629
 630 <para>
 631 Release gives the release identifier of this ICE implementation.
 632 </para>
 633
 634 <para><function>AuthenticationRequired</function></para>
 635
 636 <variablelist>
 637   <varlistentry>
 638     <term><emphasis remap='I'>authentication-protocol-index</emphasis>:</term>
 639     <listitem>
 640       <para>CARD8</para>
 641     </listitem>
 642   </varlistentry>
 643   <varlistentry>
 644     <term><emphasis remap='I'>data</emphasis>:</term>
 645     <listitem>
 646       <para>&lt;specific to authentication protocol&gt;</para>
 647     </listitem>
 648   </varlistentry>
 649   <varlistentry>
 650     <term>Response:</term>
 651     <listitem>
 652       <para><function>AuthenticationReply</function></para>
 653     </listitem>
 654   </varlistentry>
 655     <varlistentry>
 656     <term>Expected errors:</term>
 657     <listitem>
 658       <para>
 659 <function>AuthenticationRejected</function>,
 660 <function>AuthenticationFailed</function>
 661       </para>
 662     </listitem>
 663   </varlistentry>
 664 </variablelist>
 665
 666 <para>
 667 This message is sent in response to a <function>ConnectionSetup</function>
 668 or <function>ProtocolSetup</function>
 669 message to specify that authentication is to be done and what
 670 authentication mechanism is to be used.
 671 </para>
 672
 673 <para>
 674 The authentication protocol is specified by a 0-based index into the list
 675 of names given in the <function>ConnectionSetup</function> or
 676 <function>ProtocolSetup</function>
 677 Any protocol-specific data that might be required is also sent.
 678 </para>
 679
 680
 681 <para><function>AuthenticationReply</function></para>
 682 <variablelist>
 683   <varlistentry>
 684     <term><emphasis remap='I'>data</emphasis>:</term>
 685     <listitem>
 686       <para>&lt;specific to authentication protocol&gt;</para>
 687     </listitem>
 688   </varlistentry>
 689   <varlistentry>
 690     <term>Responses:</term>
 691     <listitem>
 692       <para>
 693 <function>AuthenticationNextPhase</function>,
 694 <function>ConnectionReply</function>,
 695 <function>ProtocolReply</function>
 696       </para>
 697     </listitem>
 698   </varlistentry>
 699   <varlistentry>
 700     <term>Expected errors:</term>
 701     <listitem>
 702       <para>
 703 <function>AuthenticationRejected</function>,
 704 <function>AuthenticationFailed</function>,
 705 <function>SetupFailed</function>
 706       </para>
 707     </listitem>
 708   </varlistentry>
 709 </variablelist>
 710
 711 <para>
 712 This message is sent in response to an
 713 <function>AuthenticationRequired</function> or
 714 <function>AuthenticationNextPhase</function> message, to
 715 supply authentication data as defined by the authentication protocol
 716 being used.
 717 </para>
 718
 719 <para>
 720 Note that this message is sent by the party that initiated the current
 721 negotiation -- the party that sent the
 722 <function>ConnectionSetup</function> or
 723 <function>ProtocolSetup</function> message.
 724 </para>
 725
 726 <para>
 727 <function>AuthenticationNextPhase</function>
 728 indicates that more is to be done to complete the authentication.
 729 If the authentication is complete,
 730 <function>ConnectionReply</function>
 731 is appropriate if the current authentication handshake is the result of a
 732 <function>ConnectionSetup</function> and a
 733 <function>ProtocolReply</function>
 734 is appropriate if it is the result of a
 735 <function>ProtocolSetup</function>.
 736 </para>
 737
 738 <para><function>AuthenticationNextPhase</function></para>
 739
 740 <variablelist>
 741   <varlistentry>
 742     <term><emphasis remap='I'>data</emphasis>:</term>
 743     <listitem>
 744       <para>&lt;specific to authentication protocol&gt;</para>
 745     </listitem>
 746   </varlistentry>
 747   <varlistentry>
 748     <term>Response:</term>
 749     <listitem>
 750       <para><function>AuthenticationReply</function></para>
 751     </listitem>
 752   </varlistentry>
 753   <varlistentry>
 754     <term>Expected errors:</term>
 755     <listitem>
 756       <para>
 757 <function>AuthenticationRejected</function>,
 758 <function>AuthenticationFailed</function>
 759       </para>
 760     </listitem>
 761   </varlistentry>
 762 </variablelist>
 763
 764 <para>
 765 This message is sent in response to an
 766 <function>AuthenticationReply</function>
 767 message, to supply authentication data as defined by the authentication
 768 protocol being used.
 769 </para>
 770
 771 <para><function>ConnectionReply</function></para>
 772 <variablelist>
 773   <varlistentry>
 774     <term><emphasis remap='I'>version-index</emphasis>:</term>
 775     <listitem>
 776       <para>CARD8</para>
 777     </listitem>
 778   </varlistentry>
 779   <varlistentry>
 780     <term><emphasis remap='I'>vendor</emphasis>:</term>
 781     <listitem>
 782       <para>STRING</para>
 783     </listitem>
 784   </varlistentry>
 785   <varlistentry>
 786     <term><emphasis remap='I'>release</emphasis>:</term>
 787     <listitem>
 788       <para>STRING</para>
 789     </listitem>
 790   </varlistentry>
 791 </variablelist>
 792
 793 <para>
 794 This message is sent in response to a
 795 <function>ConnectionSetup</function> or
 796 <function>AuthenticationReply</function>
 797 message to indicate that the authentication handshake is complete.
 798 </para>
 799
 800 <para>
 801 Version-index gives a 0-based index into the list of versions offered in
 802 the <function>ConnectionSetup</function> message; it specifies the
 803 version of the ICE protocol that both parties
 804 should speak for the duration of the connection.
 805 </para>
 806
 807 <para>Vendor gives the name of the vendor of this ICE implementation.</para>
 808
 809 <para>
 810 Release gives the release identifier of this ICE implementation.
 811 </para>
 812
 813 <para><function>ProtocolSetup</function></para>
 814
 815 <variablelist>
 816   <varlistentry>
 817     <term><emphasis remap='I'>protocol-name</emphasis>:</term>
 818     <listitem>
 819       <para>STRING</para>
 820     </listitem>
 821   </varlistentry>
 822   <varlistentry>
 823     <term><emphasis remap='I'>major-opcode</emphasis>:</term>
 824     <listitem>
 825       <para>CARD8</para>
 826     </listitem>
 827   </varlistentry>
 828   <varlistentry>
 829     <term><emphasis remap='I'>versions</emphasis>:</term>
 830     <listitem>
 831       <para>LISTofVERSION</para>
 832     </listitem>
 833   </varlistentry>
 834   <varlistentry>
 835     <term><emphasis remap='I'>vendor</emphasis>:</term>
 836     <listitem>
 837       <para>STRING</para>
 838     </listitem>
 839   </varlistentry>
 840   <varlistentry>
 841     <term><emphasis remap='I'>release</emphasis>:</term>
 842     <listitem>
 843       <para>STRING</para>
 844     </listitem>
 845   </varlistentry>
 846   <varlistentry>
 847     <term><emphasis remap='I'>must-authenticate</emphasis>:</term>
 848     <listitem>
 849       <para>BOOL</para>
 850     </listitem>
 851   </varlistentry>
 852   <varlistentry>
 853   <term><emphasis remap='I'>authentication-protocol-names</emphasis>:</term>
 854     <listitem>
 855       <para>LISTofSTRING</para>
 856     </listitem>
 857   </varlistentry>
 858   <varlistentry>
 859     <term>Responses:</term>
 860     <listitem>
 861       <para>
 862 <function>AuthenticationRequired</function>,
 863 <function>ProtocolReply</function>
 864       </para>
 865     </listitem>
 866   </varlistentry>
 867   <varlistentry>
 868     <term>Expected errors:</term>
 869     <listitem>
 870       <para>
 871 <function>UnknownProtocol</function>,
 872 <function>NoVersion</function>,
 873 <function>SetupFailed</function>,
 874 <function>NoAuthentication</function>,
 875 <function>AuthenticationRejected</function>,
 876 <function>AuthenticationFailed</function>
 877       </para>
 878     </listitem>
 879   </varlistentry>
 880 </variablelist>
 881
 882 <para>
 883 This message is used to initiate negotiation of a protocol and
 884 establish any authentication specific to it.
 885 </para>
 886
 887 <para>
 888 Protocol-name gives the name of the protocol the party wishes
 889 to speak.
 890 </para>
 891
 892 <para>
 893 Major-opcode gives the opcode that the party will use in messages
 894 it sends.
 895 </para>
 896
 897 <para>
 898 Versions gives a list of version numbers, in decreasing order of
 899 preference, that the party is willing to speak.
 900 </para>
 901
 902 <para>
 903 Vendor and release are identification strings with semantics defined
 904 by the specific protocol being negotiated.
 905 </para>
 906
 907 <para>
 908 If must-authenticate is <function>True</function>,
 909 the initiating party demands authentication; the accepting party
 910 <emphasis remap='I'>must</emphasis> pick an authentication scheme
 911 and use it.  In this case, the only valid response is
 912 <function>AuthenticationRequired</function>
 913 </para>
 914
 915 <para>
 916 If must-authenticate is <function>False</function>,
 917 the accepting party may choose an authentication mechanism, use a
 918 host-address-based authentication scheme, or skip authentication.
 919 When must-authenticate is <function>False</function>,
 920 <function>ProtocolReply</function> and
 921 <function>AuthenticationRequired</function>
 922 are both valid responses.  If a host-address-based authentication
 923 scheme is used, <function>AuthenticationRejected</function> and
 924 <function>AuthenticationFailed</function> errors are possible.
 925 </para>
 926
 927 <para>
 928 Authentication-protocol-names  specifies a (possibly null, if
 929 must-authenticate is <function>False</function>
 930 list of authentication protocols the party is willing to perform.  If
 931 must-authenticate is <function>True</function>
 932 presumably the party will offer only authentication mechanisms
 933 allowing mutual authentication.
 934 </para>
 935
 936 <para><function>ProtocolReply</function></para>
 937 <variablelist>
 938   <varlistentry>
 939     <term><emphasis remap='I'>major-opcode</emphasis>:</term>
 940     <listitem>
 941       <para>CARD8</para>
 942     </listitem>
 943   </varlistentry>
 944   <varlistentry>
 945     <term><emphasis remap='I'>version-index</emphasis>:</term>
 946     <listitem>
 947       <para>CARD8</para>
 948     </listitem>
 949   </varlistentry>
 950   <varlistentry>
 951     <term><emphasis remap='I'>vendor</emphasis>:</term>
 952     <listitem>
 953       <para>STRING</para>
 954     </listitem>
 955   </varlistentry>
 956   <varlistentry>
 957     <term><emphasis remap='I'>release</emphasis>:</term>
 958     <listitem>
 959       <para>STRING</para>
 960     </listitem>
 961   </varlistentry>
 962 </variablelist>
 963
 964 <para>
 965 This message is sent in response to a <function>ProtocolSetup</function>
 966 or <function>AuthenticationReply</function>
 967 message to indicate that the authentication handshake is complete.
 968 </para>
 969
 970 <para>
 971 Major-opcode gives the opcode that this party will use in
 972 messages that it sends.
 973 </para>
 974
 975 <para>
 976 Version-index gives a 0-based index into the list of versions offered in the
 977 <function>ProtocolSetup</function> message; it specifies the version
 978 of the protocol that both parties should speak for the duration of
 979 the connection.
 980 </para>
 981
 982 <para>
 983 Vendor and release are identification strings with semantics defined
 984 by the specific protocol being negotiated.
 985 </para>
 986
 987 <para><function>Ping</function></para>
 988 <variablelist>
 989   <varlistentry>
 990     <term>Response:</term>
 991     <listitem>
 992       <para><function>PingReply</function></para>
 993     </listitem>
 994   </varlistentry>
 995 </variablelist>
 996
 997 <para>
 998 This message is used to test if the connection is still functioning.
 999 </para>
1000
1001 <para><function>PingReply</function></para>
1002
1003 <para>
1004 This message is sent in response to a <function>Ping</function>
1005 message, indicating that the connection is still functioning.
1006 </para>
1007
1008 <para><function>WantToClose</function></para>
1009 <variablelist>
1010   <varlistentry>
1011     <term>Responses:</term>
1012     <listitem>
1013       <para>
1014 <function>WantToClose</function>,
1015 <function>NoClose</function>,
1016 <function>ProtocolSetup</function>
1017       </para>
1018     </listitem>
1019   </varlistentry>
1020 </variablelist>
1021
1022
1023 <para>
1024 This message is used to initiate a possible close of the connection.
1025 The sending party has noticed that, as a result of mechanisms specific
1026 to each protocol, there are no active protocols left.
1027 There are four possible scenarios arising from this request:
1028 </para>
1029
1030 <orderedlist>
1031   <listitem>
1032     <para>
1033 The receiving side noticed too, and has already sent a
1034 <function>WantToClose</function> On receiving a
1035 <function>WantToClose</function> while already attempting to
1036 shut down, each party should simply close the connection.
1037     </para>
1038   </listitem>
1039   <listitem>
1040     <para>
1041 The receiving side hasn't noticed, but agrees.  It closes the connection.
1042     </para>
1043   </listitem>
1044   <listitem>
1045     <para>
1046 The receiving side has a <function>ProtocolSetup</function>
1047 "in flight," in which case it is to ignore
1048 <function>WantToClose</function> and the party sending
1049 <function>WantToClose</function> is to abandon the shutdown attempt
1050 when it receives the <function>ProtocolSetup</function>
1051     </para>
1052   </listitem>
1053   <listitem>
1054     <para>
1055 The receiving side wants the connection kept open for some
1056 reason not specified by the ICE protocol, in which case it
1057 sends <function>NoClose</function>
1058     </para>
1059   </listitem>
1060 </orderedlist>
1061
1062 <para>
1063 See the state transition diagram for additional information.
1064 </para>
1065
1066 <para><function>NoClose</function></para>
1067
1068 <para>
1069 This message is sent in response to a <function>WantToClose</function>
1070 message to indicate that the responding party does not want the
1071 connection closed at this time.  The receiving party should not close the
1072 connection.  Either party may again initiate
1073 <function>WantToClose</function> at some future time.
1074 </para>
1075
1076 <sect1 id='Generic_Error_Classes'>
1077 <title>Generic Error Classes</title>
1078
1079 <para>
1080 These errors should be used by all protocols, as applicable.
1081 For ICE (major opcode 0), <function>FatalToProtocol</function>
1082 should be interpreted as <function>FatalToConnection</function>.
1083 </para>
1084
1085 <para><function>BadMinor</function></para>
1086
1087 <variablelist>
1088   <varlistentry>
1089     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1090     <listitem>
1091       <para>&lt;any&gt;</para>
1092     </listitem>
1093   </varlistentry>
1094   <varlistentry>
1095     <term><emphasis remap='I'>severity</emphasis>:</term>
1096     <listitem>
1097       <para>
1098 <function>FatalToProtocol</function> or
1099 <function>CanContinue</function>
1100 (protocol's discretion)
1101       </para>
1102     </listitem>
1103   </varlistentry>
1104   <varlistentry>
1105     <term><emphasis remap='I'>values</emphasis>:</term>
1106     <listitem>
1107       <para>(none)</para>
1108     </listitem>
1109   </varlistentry>
1110 </variablelist>
1111
1112 <para>
1113 Received a message with an unknown minor opcode.
1114 </para>
1115
1116 <para><function>BadState</function></para>
1117 <variablelist>
1118   <varlistentry>
1119     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1120     <listitem>
1121       <para>&lt;any&gt;</para>
1122     </listitem>
1123   </varlistentry>
1124   <varlistentry>
1125     <term><emphasis remap='I'>severity</emphasis>:</term>
1126     <listitem>
1127       <para>
1128 <function>FatalToProtocol</function> or
1129 <function>CanContinue</function> (protocol's discretion)
1130       </para>
1131     </listitem>
1132   </varlistentry>
1133   <varlistentry>
1134     <term><emphasis remap='I'>values</emphasis>:</term>
1135     <listitem>
1136       <para>(none)</para>
1137     </listitem>
1138   </varlistentry>
1139 </variablelist>
1140
1141 <para>
1142 Received a message with a valid minor opcode which is not appropriate
1143 for the current state of the protocol.
1144 </para>
1145
1146 <para><function>BadLength</function></para>
1147
1148 <variablelist>
1149   <varlistentry>
1150     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1151     <listitem>
1152       <para>&lt;any&gt;</para>
1153     </listitem>
1154   </varlistentry>
1155   <varlistentry>
1156     <term><emphasis remap='I'>severity</emphasis>:</term>
1157     <listitem>
1158       <para>
1159 <function>FatalToProtocol</function> or
1160 <function>CanContinue</function> (protocol's discretion)
1161       </para>
1162     </listitem>
1163   </varlistentry>
1164   <varlistentry>
1165     <term><emphasis remap='I'>values</emphasis>:</term>
1166     <listitem>
1167       <para>(none)</para>
1168     </listitem>
1169   </varlistentry>
1170 </variablelist>
1171
1172 <para>
1173 Received a message with a bad length.  The length of the message is
1174 longer or shorter than required to contain the data.
1175 </para>
1176
1177 <para><function>BadValue</function></para>
1178
1179 <variablelist>
1180   <varlistentry>
1181     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1182     <listitem>
1183       <para>&lt;any&gt;</para>
1184   </listitem>
1185   </varlistentry>
1186   <varlistentry>
1187     <term><emphasis remap='I'>severity</emphasis>:</term>
1188     <listitem>
1189       <para><function>CanContinue</function></para>
1190     </listitem>
1191   </varlistentry>
1192   <varlistentry>
1193     <term><emphasis remap='I'>values</emphasis>:</term>
1194     <listitem>
1195       <para>
1196 CARD32 Byte offset to offending value in offending message.
1197 CARD32 Length of offending value.
1198 &lt;varies&gt; Offending value
1199       </para>
1200     </listitem>
1201   </varlistentry>
1202 </variablelist>
1203
1204 <para>Received a message with a bad value specified.</para>
1205
1206 </sect1>
1207
1208 <sect1 id='ICE_Error_Classes'>
1209 <title>ICE Error Classes</title>
1210
1211 <para>These errors are all major opcode 0 errors.</para>
1212
1213 <para><function>BadMajor</function></para>
1214 <variablelist>
1215   <varlistentry>
1216     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1217     <listitem>
1218       <para>&lt;any&gt;</para>
1219     </listitem>
1220   </varlistentry>
1221   <varlistentry>
1222     <term><emphasis remap='I'>severity</emphasis>:</term>
1223     <listitem>
1224       <para><function>CanContinue</function></para>
1225     </listitem>
1226   </varlistentry>
1227   <varlistentry>
1228     <term><emphasis remap='I'>values</emphasis>:</term>
1229     <listitem>
1230       <para>CARD8 Opcode</para>
1231     </listitem>
1232   </varlistentry>
1233 </variablelist>
1234
1235 <para>The opcode given is not one that has been registered.</para>
1236
1237
1238 <para><function>NoAuthentication</function></para>
1239
1240 <variablelist>
1241   <varlistentry>
1242     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1243     <listitem>
1244       <para>
1245 <function>ConnectionSetup</function>,
1246 <function>ProtocolSetup</function>
1247       </para>
1248     </listitem>
1249   </varlistentry>
1250   <varlistentry>
1251     <term><emphasis remap='I'>severity</emphasis>:</term>
1252     <listitem>
1253       <para>
1254 <function>ConnectionSetup</function> \(-&gt;
1255 <function>FatalToConnection</function>
1256 <function>ProtocolSetup</function> \(-&gt;
1257 <function>FatalToProtocol</function>
1258        </para>
1259     </listitem>
1260   </varlistentry>
1261   <varlistentry>
1262     <term><emphasis remap='I'>values</emphasis>:</term>
1263     <listitem>
1264       <para>(none)</para>
1265     </listitem>
1266   </varlistentry>
1267 </variablelist>
1268
1269 <para>None of the authentication protocols offered are available.</para>
1270
1271 <para><function>NoVersion</function></para>
1272
1273 <variablelist>
1274   <varlistentry>
1275     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1276     <listitem>
1277       <para>
1278 <function>ConnectionSetup</function>,
1279 <function>ProtocolSetup</function>
1280       </para>
1281     </listitem>
1282   </varlistentry>
1283   <varlistentry>
1284     <term><emphasis remap='I'>severity</emphasis>:</term>
1285     <listitem>
1286       <para>
1287 <function>ConnectionSetup</function> \(-&gt;
1288 <function>FatalToConnection</function>
1289 <function>ProtocolSetup</function> \(-&gt;
1290 <function>FatalToProtocol</function>
1291       </para>
1292     </listitem>
1293   </varlistentry>
1294   <varlistentry>
1295     <term><emphasis remap='I'>values</emphasis>:</term>
1296     <listitem>
1297       <para>(none)</para>
1298     </listitem>
1299   </varlistentry>
1300 </variablelist>
1301
1302 <para>None of the protocol versions offered are available.</para>
1303
1304 <para><function>SetupFailed</function></para>
1305
1306 <variablelist>
1307   <varlistentry>
1308     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1309     <listitem>
1310       <para>
1311 <function>ConnectionSetup</function>,
1312 <function>ProtocolSetup</function>,
1313 <function>AuthenticationReply</function>
1314       </para>
1315     </listitem>
1316   </varlistentry>
1317   <varlistentry>
1318     <term><emphasis remap='I'>severity</emphasis>:</term>
1319     <listitem>
1320       <para>
1321 <function>ConnectionSetup</function> \(-&gt;
1322 <function>FatalToConnection</function>
1323 <function>ProtocolSetup</function> \(-&gt;
1324 <function>FatalToProtocol</function>
1325 <function>AuthenticationReply</function> \(-&gt;
1326 <function>FatalToConnection</function> if authenticating a connection,
1327 otherwise <function>FatalToProtocol</function>
1328       </para>
1329     </listitem>
1330   </varlistentry>
1331   <varlistentry>
1332     <term><emphasis remap='I'>values</emphasis>:</term>
1333     <listitem>
1334       <para>STRING reason</para>
1335     </listitem>
1336   </varlistentry>
1337 </variablelist>
1338
1339 <para>
1340 The sending side is unable to accept the
1341 new connection or new protocol for a reason other than authentication
1342 failure.  Typically this error will be a result of inability to allocate
1343 additional resources on the sending side.  The reason field will give a
1344 human-interpretable message providing further detail on the type of failure.
1345 </para>
1346
1347 <para><function>AuthenticationRejected</function></para>
1348 <variablelist>
1349   <varlistentry>
1350     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1351     <listitem>
1352       <para>
1353 <function>AuthenticationReply</function>,
1354 <function>AuthenticationRequired</function>,
1355 <function>AuthenticationNextPhase</function>
1356       </para>
1357     </listitem>
1358   </varlistentry>
1359   <varlistentry>
1360     <term><emphasis remap='I'>severity</emphasis>:</term>
1361     <listitem>
1362       <para><function>FatalToProtocol</function></para>
1363     </listitem>
1364   </varlistentry>
1365   <varlistentry>
1366     <term><emphasis remap='I'>values</emphasis>:</term>
1367     <listitem>
1368       <para>STRING reason</para>
1369     </listitem>
1370   </varlistentry>
1371 </variablelist>
1372
1373 <para>
1374 Authentication rejected.  The peer has failed to properly
1375 authenticate itself.  The reason field will give a human-interpretable
1376 message providing further detail.
1377 </para>
1378
1379 <para><function>AuthenticationFailed</function></para>
1380 <variablelist>
1381   <varlistentry>
1382     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1383     <listitem>
1384       <para>
1385 <function>AuthenticationReply</function>,
1386 <function>AuthenticationRequired</function>,
1387 <function>AuthenticationNextPhase</function>
1388       </para>
1389     </listitem>
1390   </varlistentry>
1391   <varlistentry>
1392     <term><emphasis remap='I'>severity</emphasis>:</term>
1393     <listitem>
1394       <para><function>FatalToProtocol</function></para>
1395     </listitem>
1396   </varlistentry>
1397   <varlistentry>
1398     <term><emphasis remap='I'>values</emphasis>:</term>
1399     <listitem>
1400       <para>STRING reason</para>
1401     </listitem>
1402   </varlistentry>
1403 </variablelist>
1404
1405 <para>
1406 Authentication failed.  <function>AuthenticationFailed</function>
1407 does not imply that the authentication was rejected, as
1408 <function>AuthenticationRejected</function>
1409 does.  Instead it means that the sender was unable to complete
1410 the authentication for some other reason.  (For instance, it
1411 may have been unable to contact an authentication server.)
1412 The reason field will give a human-interpretable message
1413 providing further detail.
1414 </para>
1415
1416 <para><function>ProtocolDuplicate</function></para>
1417 <variablelist>
1418   <varlistentry>
1419     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1420     <listitem>
1421       <para><function>ProtocolSetup</function></para>
1422     </listitem>
1423   </varlistentry>
1424   <varlistentry>
1425     <term><emphasis remap='I'>severity</emphasis>:</term>
1426     <listitem>
1427       <para><function>FatalToProtocol</function> (but see note)</para>
1428     </listitem>
1429   </varlistentry>
1430   <varlistentry>
1431     <term><emphasis remap='I'>values</emphasis>:</term>
1432     <listitem>
1433       <para>STRING protocol name</para>
1434     </listitem>
1435   </varlistentry>
1436 </variablelist>
1437
1438 <para>
1439 The protocol name was already registered.  This is fatal to
1440 the "new" protocol being set up by <function>ProtocolSetup</function>
1441 but it does not affect the existing registration.
1442 </para>
1443
1444 <para><function>MajorOpcodeDuplicate</function></para>
1445 <variablelist>
1446   <varlistentry>
1447     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1448     <listitem>
1449       <para><function>ProtocolSetup</function></para>
1450     </listitem>
1451   </varlistentry>
1452   <varlistentry>
1453     <term><emphasis remap='I'>severity</emphasis>:</term>
1454     <listitem>
1455       <para><function>FatalToProtocol</function> (but see note)</para>
1456   </listitem>
1457   </varlistentry>
1458   <varlistentry>
1459     <term><emphasis remap='I'>values</emphasis>:</term>
1460     <listitem>
1461       <para>CARD8 opcode</para>
1462     </listitem>
1463   </varlistentry>
1464 </variablelist>
1465
1466 <para>
1467 The major opcode specified was already registered.  This is
1468 fatal to the \*Qnew\*U protocol being set up by
1469 <function>ProtocolSetup</function> but it does not affect the
1470 existing registration.
1471 </para>
1472
1473 <para><function>UnknownProtocol</function></para>
1474 <variablelist>
1475   <varlistentry>
1476     <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1477     <listitem>
1478       <para><function>ProtocolSetup</function></para>
1479     </listitem>
1480   </varlistentry>
1481   <varlistentry>
1482     <term><emphasis remap='I'>severity</emphasis>:</term>
1483     <listitem>
1484       <para><function>FatalToProtocol</function></para>
1485     </listitem>
1486   </varlistentry>
1487   <varlistentry>
1488     <term><emphasis remap='I'>values</emphasis>:</term>
1489     <listitem>
1490       <para>STRING protocol name</para>
1491     </listitem>
1492   </varlistentry>
1493 </variablelist>
1494
1495 <para>The protocol specified is not supported.</para>
1496
1497 </sect1>
1498 </chapter>
1499
1500 <chapter id='State_Diagrams'>
1501 <title>State Diagrams</title>
1502
1503 <para>
1504 Here are the state diagrams for the party that initiates the connection:
1505 </para>
1506
1507 <literallayout>
1508 <emphasis remap='C'>start</emphasis>:
1509      connect to other end, send <function>ByteOrder</function> <function>ConnectionSetup</function> -&gt; <emphasis remap='C'>conn_wait</emphasis>
1510
1511 <emphasis remap='C'>conn_wait</emphasis>:
1512      receive <function>ConnectionReply</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1513      receive <function>AuthenticationRequired</function> -&gt; <emphasis remap='C'>conn_auth1</emphasis>
1514      receive <function>Error</function> -&gt; <emphasis remap='C'>quit</emphasis>
1515      receive &lt;other&gt;, send <function>Error</function> -&gt; <emphasis remap='C'>quit</emphasis>
1516
1517 <emphasis remap='C'>conn_auth1</emphasis>:
1518      if good auth data, send <function>AuthenticationReply</function> -&gt; <emphasis remap='C'>conn_auth2</emphasis>
1519      if bad auth data, send <function>Error</function> -&gt; <emphasis remap='C'>quit</emphasis>
1520
1521 <emphasis remap='C'>conn_auth2</emphasis>:
1522      receive <function>ConnectionReply</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1523      receive <function>AuthenticationNextPhase</function> -&gt; <emphasis remap='C'>conn_auth1</emphasis>
1524      receive <function>Error</function> -&gt; <emphasis remap='C'>quit</emphasis>
1525      receive &lt;other&gt;, send <function>Error</function> -&gt; <emphasis remap='C'>quit</emphasis>
1526 </literallayout>
1527
1528 <para>
1529 Here are top-level state transitions for the party
1530 that accepts connections.
1531 </para>
1532
1533 <literallayout>
1534 <emphasis remap='C'>listener</emphasis>:
1535      accept connection -&gt; <emphasis remap='C'>init_wait</emphasis>
1536
1537 <emphasis remap='C'>init_wait</emphasis>:
1538      receive <function>ByteOrder</function> <function>ConnectionSetup</function> -&gt; <emphasis remap='C'>auth_ask</emphasis>
1539      receive &lt;other&gt;, send <function>Error</function> -&gt; <emphasis remap='C'>quit</emphasis>
1540
1541 <emphasis remap='C'>auth_ask</emphasis>:
1542      send <function>ByteOrder</function> <function>ConnectionReply</function>
1543 -&gt; <emphasis remap='C'>stasis</emphasis>
1544
1545      send <function>AuthenticationRequired</function> -&gt; <emphasis remap='C'>auth_wait</emphasis>
1546
1547      send <function>Error</function> -&gt; <emphasis remap='C'>quit</emphasis>
1548
1549 <emphasis remap='C'>auth_wait</emphasis>:
1550      receive <function>AuthenticationReply</function> -&gt; <emphasis remap='C'>auth_check</emphasis>
1551
1552      receive &lt;other&gt;, send <function>Error</function> -&gt; <emphasis remap='C'>quit</emphasis>
1553
1554 <emphasis remap='C'>auth_check</emphasis>:
1555      if no more auth needed, send <function>ConnectionReply</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1556      if good auth data, send <function>AuthenticationNextPhase</function> -&gt; <emphasis remap='C'>auth_wait</emphasis>
1557      if bad auth data, send <function>Error</function> -&gt; <emphasis remap='C'>quit</emphasis>
1558 </literallayout>
1559
1560 <para>
1561 Here are the top-level state transitions for all parties after the initial
1562 connection establishment subprotocol.
1563 </para>
1564
1565 <note>
1566 <para>
1567 Note:  this is not quite the truth for branches out from stasis, in
1568 that multiple conversations can be interleaved on the connection.
1569 </para>
1570 </note>
1571
1572 <literallayout>
1573 <emphasis remap='C'>stasis</emphasis>:
1574      send <function>ProtocolSetup</function> -&gt; <emphasis remap='C'>proto_wait</emphasis>
1575      receive <function>ProtocolSetup</function> -&gt; <emphasis remap='C'>proto_reply</emphasis>
1576      send <function>Ping</function> -&gt; <emphasis remap='C'>ping_wait</emphasis>
1577      receive <function>Ping</function> send <function>PingReply</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1578      receive <function>WantToClose</function> -&gt; <emphasis remap='C'>shutdown_attempt</emphasis>
1579      receive &lt;other&gt;, send <function>Error</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1580      all protocols shut down, send <function>WantToClose</function> -&gt; <emphasis remap='C'>close_wait</emphasis>
1581
1582 <emphasis remap='C'>proto_wait</emphasis>:
1583      receive <function>ProtocolReply</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1584      receive <function>AuthenticationRequired</function> -&gt; <emphasis remap='C'>give_auth1</emphasis>
1585      receive <function>Error</function> give up on this protocol -&gt; <emphasis remap='C'>stasis</emphasis>
1586      receive <function>WantToClose</function> -&gt; <emphasis remap='C'>proto_wait</emphasis>
1587
1588 <emphasis remap='C'>give_auth1</emphasis>:
1589      if good auth data, send <function>AuthenticationReply</function> -&gt; <emphasis remap='C'>give_auth2</emphasis>
1590      if bad auth data, send <function>Error</function> give up on this protocol -&gt; <emphasis remap='C'>stasis</emphasis>
1591      receive <function>WantToClose</function> -&gt; <emphasis remap='C'>give_auth1</emphasis>
1592
1593 <emphasis remap='C'>give_auth2</emphasis>:
1594      receive <function>ProtocolReply</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1595      receive <function>AuthenticationNextPhase</function> -&gt; <emphasis remap='C'>give_auth1</emphasis>
1596      receive <function>Error</function> give up on this protocol -&gt; <emphasis remap='C'>stasis</emphasis>
1597      receive <function>WantToClose</function> -&gt; <emphasis remap='C'>give_auth2</emphasis>
1598
1599 <emphasis remap='C'>proto_reply</emphasis>:
1600      send <function>ProtocolReply</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1601      send <function>AuthenticationRequired</function> -&gt; <emphasis remap='C'>take_auth1</emphasis>
1602      send <function>Error</function> give up on this protocol -&gt; <emphasis remap='C'>stasis</emphasis>
1603
1604 <emphasis remap='C'>take_auth1</emphasis>:
1605      receive <function>AuthenticationReply</function> -&gt; <emphasis remap='C'>take_auth2</emphasis>
1606      receive <function>Error</function> give up on this protocol -&gt; <emphasis remap='C'>stasis</emphasis>
1607
1608 <emphasis remap='C'>take_auth2</emphasis>:
1609      if good auth data \(-&gt; <emphasis remap='C'>take_auth3</emphasis>
1610      if bad auth data, send <function>Error</function> give up on this protocol -&gt; <emphasis remap='C'>stasis</emphasis>
1611
1612 <emphasis remap='C'>take_auth3</emphasis>:
1613      if no more auth needed, send <function>ProtocolReply</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1614      if good auth data, send <function>AuthenticationNextPhase</function> -&gt; <emphasis remap='C'>take_auth1</emphasis>
1615      if bad auth data, send <function>Error</function> give up on this protocol -&gt; <emphasis remap='C'>stasis</emphasis>
1616
1617 <emphasis remap='C'>ping_wait</emphasis>:
1618      receive <function>PingReply</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1619
1620 <emphasis remap='C'>quit</emphasis>:
1621      -&gt; close connection
1622 </literallayout>
1623
1624 <para>
1625 Here are the state transitions for shutting down the connection:
1626 </para>
1627
1628 <literallayout>
1629 <emphasis remap='C'>shutdown_attempt</emphasis>:
1630      if want to stay alive anyway, send <function>NoClose</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1631      else -&gt; <emphasis remap='C'>quit</emphasis>
1632
1633 <emphasis remap='C'>close_wait</emphasis>:
1634      receive <function>ProtocolSetup</function> -&gt; <emphasis remap='C'>proto_reply</emphasis>
1635      receive <function>NoClose</function> -&gt; <emphasis remap='C'>stasis</emphasis>
1636      receive <function>WantToClose</function> -&gt; <emphasis remap='C'>quit</emphasis>
1637      connection close -&gt; <emphasis remap='C'>quit</emphasis>
1638 </literallayout>
1639 </chapter>
1640 <chapter id='Protocol_Encoding'>
1641 <title>Protocol Encoding</title>
1642
1643 <para>
1644 In the encodings below, the first column is the number of bytes occupied.
1645 The second column is either the type (if the value is variable) or the
1646 actual value.  The third column is the description of the value (e.g.,
1647 the parameter name).  Receivers must ignore bytes that are designated
1648 as unused or pad bytes.
1649 </para>
1650
1651 <para>
1652 This document describes major version 1, minor version 0
1653 of the ICE protocol.
1654 </para>
1655
1656 <para>
1657 LISTof&lt;type&gt; indicates some number of repetitions of
1658 &lt;type&gt;, with no
1659 additional padding.  The number of repetitions must be specified elsewhere
1660 in the message.
1661 </para>
1662
1663 <sect1 id='Primitives'>
1664 <title>Primitives</title>
1665
1666 <informaltable frame='topbot'>
1667   <?dbfo keep-together="always" ?>
1668   <tgroup cols='3' align='left' colsep='0' rowsep='0'>
1669     <colspec colname='c1' colwidth='1.0*'/>
1670     <colspec colname='c2' colwidth='1.0*'/>
1671     <colspec colname='c3' colwidth='3.0*'/>
1672     <thead>
1673       <row rowsep='1'>
1674         <entry>Type Name</entry>
1675         <entry>Length (bytes)</entry>
1676         <entry>Description</entry>
1677       </row>
1678     </thead>
1679     <tbody>
1680       <row>
1681         <entry>CARD8</entry>
1682         <entry>1</entry>
1683         <entry>8-bit unsigned integer</entry>
1684       </row>
1685       <row>
1686         <entry>CARD16</entry>
1687         <entry>2</entry>
1688         <entry>16-bit unsigned integer</entry>
1689       </row>
1690       <row>
1691         <entry>CARD32</entry>
1692         <entry>4</entry>
1693         <entry>32-bit unsigned integer</entry>
1694       </row>
1695       <row>
1696         <entry>LPCE</entry>
1697         <entry>1</entry>
1698         <entry><para>A character from the X Portable Character Set in Latin Portable Character
1699 Encoding</para></entry>
1700       </row>
1701     </tbody>
1702   </tgroup>
1703 </informaltable>
1704
1705 </sect1>
1706
1707 <sect1 id='Enumerations'>
1708 <title>Enumerations</title>
1709
1710
1711 <informaltable frame='topbot'>
1712   <?dbfo keep-together="always" ?>
1713   <tgroup cols='3' align='left' colsep='0' rowsep='0'>
1714     <colspec colname='c1' colwidth='1.0*'/>
1715     <colspec colname='c2' colwidth='1.0*'/>
1716     <colspec colname='c3' colwidth='3.0*'/>
1717     <thead>
1718       <row rowsep='1'>
1719         <entry>Type Name</entry>
1720         <entry>Value</entry>
1721         <entry>Description</entry>
1722       </row>
1723     </thead>
1724     <tbody>
1725       <row>
1726         <entry>BOOL</entry>
1727         <entry>0</entry>
1728         <entry>False</entry>
1729       </row>
1730       <row>
1731         <entry></entry>
1732         <entry>1</entry>
1733         <entry>True</entry>
1734       </row>
1735     </tbody>
1736   </tgroup>
1737 </informaltable>
1738
1739 </sect1>
1740
1741 <sect1 id='Compound_Types'>
1742 <title>Compound Types</title>
1743
1744 <informaltable frame='topbot'>
1745   <?dbfo keep-together="always" ?>
1746   <tgroup cols='4' align='left' colsep='0' rowsep='0'>
1747     <colspec colname='c1' colwidth='1.0*'/>
1748     <colspec colname='c2' colwidth='1.0*'/>
1749     <colspec colname='c3' colwidth='1.0*'/>
1750     <colspec colname='c4' colwidth='2.0*'/>
1751     <thead>
1752       <row rowsep='1'>
1753         <entry>Type Name</entry>
1754         <entry>Length (bytes)</entry>
1755         <entry>Type</entry>
1756         <entry>Description</entry>
1757       </row>
1758     </thead>
1759     <tbody>
1760       <row>
1761         <entry>VERSION</entry>
1762         <entry></entry>
1763         <entry></entry>
1764         <entry></entry>
1765       </row>
1766       <row>
1767         <entry></entry>
1768         <entry>2</entry>
1769         <entry>CARD16</entry>
1770         <entry>Major version number</entry>
1771       </row>
1772       <row>
1773         <entry></entry>
1774         <entry>2</entry>
1775         <entry>CARD16</entry>
1776         <entry>Minor version number</entry>
1777       </row>
1778       <row>
1779         <entry>STRING</entry>
1780         <entry></entry>
1781         <entry></entry>
1782         <entry></entry>
1783       </row>
1784       <row>
1785         <entry></entry>
1786         <entry>2</entry>
1787         <entry>CARD16</entry>
1788         <entry>length of string in bytes</entry>
1789       </row>
1790       <row>
1791         <entry></entry>
1792         <entry>n</entry>
1793         <entry>LISTofLPCE</entry>
1794         <entry>string</entry>
1795       </row>
1796       <row>
1797         <entry></entry>
1798         <entry>p</entry>
1799         <entry></entry>
1800         <entry>unused, p = pad(n+2, 4)</entry>
1801       </row>
1802     </tbody>
1803   </tgroup>
1804 </informaltable>
1805
1806 </sect1>
1807
1808 <sect1 id='ICE_Minor_opcodes'>
1809 <title>ICE Minor opcodes</title>
1810
1811 <informaltable frame='topbot'>
1812   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
1813     <colspec colname='c1' colwidth='1.0*'/>
1814     <colspec colname='c2' colwidth='1.0*'/>
1815     <thead>
1816       <row rowsep='1'>
1817         <entry>Message Name</entry>
1818         <entry>Encoding</entry>
1819       </row>
1820     </thead>
1821     <tbody>
1822       <row>
1823         <entry>Error</entry>
1824         <entry>0</entry>
1825       </row>
1826       <row>
1827         <entry>ByteOrder</entry>
1828         <entry>1</entry>
1829       </row>
1830       <row>
1831         <entry>ConnectionSetup</entry>
1832         <entry>2</entry>
1833       </row>
1834       <row>
1835         <entry>AuthenticationRequired</entry>
1836         <entry>3</entry>
1837       </row>
1838       <row>
1839         <entry>AuthenticationReply</entry>
1840         <entry>4</entry>
1841       </row>
1842       <row>
1843         <entry>AuthenticationNextPhase</entry>
1844         <entry>5</entry>
1845       </row>
1846       <row>
1847         <entry>ConnectionReply</entry>
1848         <entry>6</entry>
1849       </row>
1850       <row>
1851         <entry>ProtocolSetup</entry>
1852         <entry>7</entry>
1853       </row>
1854       <row>
1855         <entry>ProtocolReply</entry>
1856         <entry>8</entry>
1857       </row>
1858       <row>
1859         <entry>Ping</entry>
1860         <entry>9</entry>
1861       </row>
1862       <row>
1863         <entry>PingReply</entry>
1864         <entry>10</entry>
1865       </row>
1866       <row>
1867         <entry>WantToClose</entry>
1868         <entry>11</entry>
1869       </row>
1870       <row>
1871         <entry>NoClose</entry>
1872         <entry>12</entry>
1873       </row>
1874     </tbody>
1875   </tgroup>
1876 </informaltable>
1877
1878 </sect1>
1879
1880 <sect1 id='Message_Encoding'>
1881 <title>Message Encoding</title>
1882
1883 <literallayout class="monospaced">
1884 <function>Error</function>
1885      1     CARD8         major-opcode
1886      1     0             Error
1887      2     CARD16        class
1888      4     (n+p)/8+1     length
1889      1     CARD8         offending-minor-opcode
1890      1                   severity:
1891            0               CanContinue
1892            1               FatalToProtocol
1893            2               FatalToConnection
1894      2                   unused
1895      4     CARD32        sequence number of erroneous message
1896      n     &lt;varies&gt;     value(s)
1897      p                   pad, p = pad(n,8)
1898 </literallayout>
1899
1900
1901 <literallayout class="monospaced">
1902 <function>ByteOrder</function>
1903      1     0     ICE
1904      1     1     ByteOrder
1905      1           byte-order:
1906            0        LSBfirst
1907            1        MSBfirst
1908      1           unused
1909      4     0     length
1910 </literallayout>
1911
1912 <literallayout class="monospaced">
1913 <function>ConnectionSetup</function>
1914      1     0                   ICE
1915      1     2                   ConnectionSetup
1916      1     CARD8               Number of versions offered
1917      1     CARD8               Number of authentication protocol names offered
1918      4     (i+j+k+m+p)/8+1     length
1919      1     BOOL                must-authenticate
1920      7                         unused
1921      i     STRING              vendor
1922      j     STRING              release
1923      k     LISTofSTRING        authentication-protocol-names
1924      m     LISTofVERSION       version-list
1925      p                         unused, p = pad(i+j+k+m,8)
1926 </literallayout>
1927
1928 <literallayout class="monospaced">
1929 <function>AuthenticationRequired</function>
1930      1     0             ICE
1931      1     3             AuthenticationRequired
1932      1     CARD8         authentication-protocol-index
1933      1                   unused
1934      4     (n+p)/8+1     length
1935      2     n             length of authentication data
1936      6          unused
1937      n     &lt;varies&gt;     data
1938      p                   unused, p = pad(n,8)
1939 </literallayout>
1940
1941 <literallayout class="monospaced">
1942 <function>AuthenticationReply</function>
1943      1     0             ICE
1944      1     4             AuthenticationReply
1945      2                   unused
1946      4     (n+p)/8+1     length
1947      2     n             length of authentication data
1948      6                   unused
1949      n     &lt;varies&gt;     data
1950      p                   unused, p = pad(n,8)
1951 </literallayout>
1952
1953 <literallayout class="monospaced">
1954 <function>AuthenticationNextPhase</function>
1955      1     0             ICE
1956      1     5             AuthenticationNextPhase
1957      2                   unused
1958      4     (n+p)/8+1     length
1959      2     n             length of authentication data
1960      6                   unused
1961      n     &lt;varies&gt;     data
1962      p                   unused, p = pad(n,8)
1963 </literallayout>
1964
1965 <literallayout class="monospaced">
1966 <function>ConnectionReply</function>
1967      1     0             ICE
1968      1     6             ConnectionReply
1969      1     CARD8         version-index
1970      1                   unused
1971      4     (i+j+p)/8     length
1972      i     STRING        vendor
1973      j     STRING        release
1974      p                   unused, p = pad(i+j,8)
1975 </literallayout>
1976
1977 <literallayout class="monospaced">
1978 <function>ProtocolSetup</function>
1979      1     0                     ICE
1980      1     7                     ProtocolSetup
1981      1     CARD8                 major-opcode
1982      1     BOOL                  must-authenticate
1983      4     (i+j+k+m+n+p)/8+1     length
1984      1     CARD8                 Number of versions offered
1985      1     CARD8                 Number of authentication protocol names offered
1986      6                           unused
1987      i     STRING                protocol-name
1988      j     STRING                vendor
1989      k     STRING                release
1990      m     LISTofSTRING          authentication-protocol-names
1991      n     LISTofVERSION         version-list
1992      p                           unused, p = pad(i+j+k+m+n,8)
1993 </literallayout>
1994
1995 <literallayout class="monospaced">
1996 <function>ProtocolReply</function>
1997      1     0             ICE
1998      1     8             ProtocolReply
1999      1     CARD8         version-index
2000      1     CARD8         major-opcode
2001      4     (i+j+p)/8     length
2002      i     STRING        vendor
2003      j     STRING        release
2004      p                   unused, p = pad(i+j, 8)
2005 </literallayout>
2006
2007 <literallayout class="monospaced">
2008 <function>Ping</function>
2009      1     0     ICE
2010      1     9     Ping
2011      2     0     unused
2012      4     0     length
2013 </literallayout>
2014
2015 <literallayout class="monospaced">
2016 <function>PingReply</function>
2017      1     0     ICE
2018      1     10    PingReply
2019      2     0     unused
2020      4     0     length
2021 </literallayout>
2022
2023 <literallayout class="monospaced">
2024 <function>WantToClose</function>
2025      1     0     ICE
2026      1     11    WantToClose
2027      2     0     unused
2028      4     0     length
2029 </literallayout>
2030
2031 <literallayout class="monospaced">
2032 <function>NoClose</function>
2033      1     0     ICE
2034      1     12    NoClose
2035      2     0     unused
2036      4     0     length
2037 </literallayout>
2038
2039 </sect1>
2040
2041 <sect1 id='Error_Class_Encoding'>
2042 <title>Error Class Encoding</title>
2043
2044 <para>
2045 Generic errors have classes in the range 0x8000-0xFFFF, and
2046 subprotocol-specific errors are in the range 0x0000-0x7FFF.
2047 </para>
2048
2049 <sect2 id='Generic_Error_Class_Encoding'>
2050 <title>Generic Error Class Encoding</title>
2051
2052 <informaltable frame='topbot'>
2053   <?dbfo keep-together="always" ?>
2054   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
2055     <colspec colname='c1' colwidth='1.0*'/>
2056     <colspec colname='c2' colwidth='3.0*'/>
2057     <thead>
2058       <row rowsep='1'>
2059         <entry>Class</entry>
2060         <entry>Encoding</entry>
2061       </row>
2062     </thead>
2063     <tbody>
2064       <row>
2065         <entry>BadMinor</entry>
2066         <entry>0x8000</entry>
2067       </row>
2068       <row>
2069         <entry>BadState</entry>
2070         <entry>0x8001</entry>
2071       </row>
2072       <row>
2073         <entry>BadLength</entry>
2074         <entry>0x8002</entry>
2075       </row>
2076       <row>
2077         <entry>BadValue</entry>
2078         <entry>0x8003</entry>
2079       </row>
2080     </tbody>
2081   </tgroup>
2082 </informaltable>
2083
2084 </sect2>
2085 <sect2 id='ICE_specific_Error_Class_Encoding'>
2086 <title>ICE-specific Error Class Encoding</title>
2087
2088 <informaltable frame='topbot'>
2089   <?dbfo keep-together="always" ?>
2090   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
2091     <colspec colname='c1' colwidth='1.0*'/>
2092     <colspec colname='c2' colwidth='3.0*'/>
2093     <thead>
2094       <row rowsep='1'>
2095         <entry>Class</entry>
2096         <entry>Encoding</entry>
2097       </row>
2098     </thead>
2099     <tbody>
2100       <row>
2101         <entry>BadMajor</entry>
2102         <entry>0</entry>
2103       </row>
2104       <row>
2105         <entry>NoAuthentication</entry>
2106         <entry>1</entry>
2107       </row>
2108       <row>
2109         <entry>NoVersion</entry>
2110         <entry>2</entry>
2111       </row>
2112       <row>
2113         <entry>SetupFailed</entry>
2114         <entry>3</entry>
2115       </row>
2116       <row>
2117         <entry>AuthenticationRejected</entry>
2118         <entry>4</entry>
2119       </row>
2120       <row>
2121         <entry>AuthenticationFailed</entry>
2122         <entry>5</entry>
2123       </row>
2124       <row>
2125         <entry>ProtocolDuplicate</entry>
2126         <entry>6</entry>
2127       </row>
2128       <row>
2129         <entry>MajorOpcodeDuplicate</entry>
2130         <entry>7</entry>
2131       </row>
2132       <row>
2133         <entry>UnknownProtocol</entry>
2134         <entry>8</entry>
2135       </row>
2136     </tbody>
2137   </tgroup>
2138 </informaltable>
2139
2140 </sect2>
2141 </sect1>
2142 </chapter>
2143
2144 <appendix id="modification_history">
2145
2146 <title>Modification History</title>
2147
2148 <sect1 id='Release_6_to_Release_61_1'>
2149 <title>Release 6 to Release 6.1</title>
2150 <para>
2151 Release 6.1 added the ICE X rendezvous protocol (Appendix B) and
2152 updated the document version to 1.1.
2153 </para>
2154 </sect1>
2155
2156 <sect1 id='Release_61_to_Release_63_3'>
2157 <title>Release 6.1 to Release 6.3</title>
2158 <para>Release 6.3 added the listen on well known ports feature.</para>
2159 </sect1>
2160
2161 </appendix>
2162
2163 <appendix id="ice_x_rendezvous_protocol">
2164 <title>ICE X Rendezvous Protocol</title>
2165
2166 <sect1 id='Introduction'>
2167 <title>Introduction</title>
2168 <para>
2169 The ICE X rendezvous protocol is designed to answer the need posed
2170 in Section 2 for one mechanism by which two clients interested in
2171 communicating via ICE are able to exchange the necessary information.
2172 This protocol is appropriate for any two ICE clients who also have X
2173 connections to the same X server.
2174 </para>
2175 </sect1>
2176
2177 <sect1 id='Overview_of_ICE_X_Rendezvous'>
2178 <title>Overview of ICE X Rendezvous</title>
2179
2180 <para>
2181 The ICE X Rendezvous Mechanism requires clients willing to act as ICE
2182 originating parties to pre-register the ICE subprotocols they support in an
2183 ICE_PROTOCOLS property on their top-level window.  Clients willing to
2184 act as ICE answering parties then send an ICE_PROTOCOLS X
2185 <function>ClientMessage</function>
2186 event to the ICE originating parties.  This
2187 <function>ClientMessage</function>
2188 event identifies
2189 the ICE network IDs of the ICE answering party as well as the ICE
2190 subprotocol it wishes to speak.  Upon receipt of this message the ICE
2191 originating party uses the information to establish an ICE connection
2192 with the ICE answering party.
2193 </para>
2194 </sect1>
2195
2196 <sect1 id='Registering_Known_Protocols'>
2197 <title>Registering Known Protocols</title>
2198
2199 <para>
2200 Clients willing to act as ICE originating parties preregister
2201 the ICE subprotocols they support in a list of atoms held by an
2202 ICE_PROTOCOLS property on their top-level window.  The name of each
2203 atom listed in ICE_PROTOCOLS must be of the form
2204 ICE_INITIATE_<emphasis remap='I'>pname</emphasis> where
2205 <emphasis remap='I'>pname</emphasis> is the name of the ICE
2206 subprotocol the ICE originating party is willing to speak, as would be
2207 specified in an ICE
2208 <function>ProtocolSetup</function>
2209 message.
2210 </para>
2211
2212 <para>
2213 Clients with an ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom
2214 in the ICE_PROTOCOLS property on their top-level windows must respond to
2215 <function>ClientMessage</function> events of
2216 type ICE_PROTOCOLS specifying ICE_INITIATE_
2217 <emphasis remap='I'>pname</emphasis>.  If a client does not
2218 want to respond to these client message events, it should
2219 remove the ICE_INITIATE_<emphasis remap='I'>pname</emphasis>
2220 atom from its ICE_PROTOCOLS property
2221 or remove the ICE_PROTOCOLS property entirely.
2222 </para>
2223 </sect1>
2224
2225 <sect1 id='Initiating_the_Rendezvous'>
2226 <title>Initiating the Rendezvous</title>
2227
2228 <para>
2229 To initiate the rendezvous a client acting as an ICE answering
2230 party sends an X
2231 <function>ClientMessage</function>
2232 event of type ICE_PROTOCOLS to an ICE
2233 originating party.  This ICE_PROTOCOLS client message contains the
2234 information the ICE originating party needs to identify the ICE
2235 subprotocol the two parties will use as well as the ICE network
2236 identification string of the ICE answering party.
2237 </para>
2238
2239 <para>
2240 Before the ICE answering party sends the client message event it must
2241 define a text property on one of its windows.  This text property
2242 contains the ICE answering party's ICE network identification string
2243 and will be used by ICE originating parties to determine the ICE
2244 answering party's list of ICE network IDs.
2245 </para>
2246
2247 <para>
2248 The property name will normally be ICE_NETWORK_IDS, but may be any
2249 name of the ICE answering party's choosing.  The format for this text
2250 property is as follows:
2251 </para>
2252
2253 <informaltable frame='topbot'>
2254   <?dbfo keep-together="always" ?>
2255   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
2256     <colspec colname='c1' colwidth='1.0*'/>
2257     <colspec colname='c2' colwidth='3.0*'/>
2258     <thead>
2259       <row rowsep='1'>
2260         <entry>Field</entry>
2261         <entry>Value</entry>
2262       </row>
2263     </thead>
2264     <tbody>
2265       <row>
2266         <entry>type</entry>
2267         <entry>XA_STRING</entry>
2268       </row>
2269       <row>
2270         <entry>format</entry>
2271         <entry>8</entry>
2272       </row>
2273       <row>
2274         <entry>value</entry>
2275         <entry>comma-separated list of ICE network IDs</entry>
2276       </row>
2277     </tbody>
2278   </tgroup>
2279 </informaltable>
2280
2281
2282
2283 <para>
2284 Once the ICE answering party has established this text property on one
2285 of its windows, it initiates the rendezvous by sending an
2286 ICE_PROTOCOLS
2287 <function>ClientMessage</function>
2288 event to an ICE originating party's
2289 top-level window.  This event has the following format
2290 and must only be sent to windows that have pre-registered the ICE
2291 subprotocol in an ICE_PROTOCOLS property on their top-level window.
2292 </para>
2293
2294 <informaltable frame='topbot'>
2295   <?dbfo keep-together="always" ?>
2296   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
2297     <colspec colname='c1' colwidth='1.0*'/>
2298     <colspec colname='c2' colwidth='3.0*'/>
2299     <thead>
2300       <row rowsep='1'>
2301         <entry>Field</entry>
2302         <entry>Value</entry>
2303       </row>
2304     </thead>
2305     <tbody>
2306       <row>
2307         <entry>message_type</entry>
2308         <entry>Atom = "ICE_PROTOCOLS"</entry>
2309       </row>
2310       <row>
2311         <entry>format</entry>
2312         <entry>32</entry>
2313       </row>
2314       <row>
2315         <entry>data.l[0]</entry>
2316         <entry>Atom identifying the ICE subprotocol to speak</entry>
2317       </row>
2318       <row>
2319         <entry>data.l[1]</entry>
2320         <entry>Timestamp</entry>
2321       </row>
2322       <row>
2323         <entry>data.l[2]</entry>
2324         <entry><para>ICE answering party's window ID with
2325 ICE network IDs text property</para></entry>
2326       </row>
2327       <row>
2328         <entry>data.l[3]</entry>
2329         <entry>Atom naming text property containing the ICE
2330 answering party's ICE network IDs</entry>
2331       </row>
2332       <row>
2333         <entry>data.l[4]</entry>
2334         <entry>Reserved.  Must be 0.</entry>
2335       </row>
2336     </tbody>
2337   </tgroup>
2338 </informaltable>
2339
2340
2341 <para>
2342 The name of the atom in data.l[0] must be of the form
2343 ICE_INITIATE_<emphasis remap='I'>pname</emphasis>, where
2344 <emphasis remap='I'>pname</emphasis> is the name of the ICE
2345 subprotocol the ICE answering party wishes to speak.
2346 </para>
2347
2348 <para>
2349 When an ICE originating party receives a
2350 <function>ClientMessage</function>
2351 event of type
2352 ICE_PROTOCOLS specifying ICE_INITIATE_<emphasis remap='I'>pname</emphasis>
2353 it can initiate an ICE connection with the ICE answering party.
2354 To open this connection the client retrieves the ICE answering
2355 party's ICE network IDs from the window specified in data.l[2] using
2356 the text property specified in data.l[3].
2357 </para>
2358
2359 <para>
2360 If the connection attempt fails for any reason, the client must
2361 respond to the client message event by sending a return
2362 <function>ClientMessage</function>
2363 event to the window specified in data.l[2].  This return
2364 event has the following format:
2365 </para>
2366
2367 <informaltable frame='topbot'>
2368   <?dbfo keep-together="always" ?>
2369   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
2370     <colspec colname='c1' colwidth='1.0*'/>
2371     <colspec colname='c2' colwidth='3.0*'/>
2372     <thead>
2373       <row rowsep='1'>
2374         <entry>Field</entry>
2375         <entry>Value</entry>
2376       </row>
2377     </thead>
2378     <tbody>
2379       <row>
2380         <entry>message_type</entry>
2381         <entry>Atom = "ICE_INITIATE_FAILED"</entry>
2382       </row>
2383       <row>
2384         <entry>format</entry>
2385         <entry>32</entry>
2386       </row>
2387       <row>
2388         <entry>data.l[0]</entry>
2389         <entry>Atom identifying the ICE subprotocol requested</entry>
2390       </row>
2391       <row>
2392         <entry>data.l[1]</entry>
2393         <entry>Timestamp</entry>
2394       </row>
2395       <row>
2396         <entry>data.l[2]</entry>
2397         <entry><para>Initiating party's window ID
2398 (holding ICE_PROTOCOLS)</para></entry>
2399       </row>
2400       <row>
2401         <entry>data.l[3]</entry>
2402         <entry>int: reason for failure</entry>
2403       </row>
2404       <row>
2405         <entry>data.l[4]</entry>
2406         <entry>Reserved, must be 0</entry>
2407       </row>
2408     </tbody>
2409   </tgroup>
2410 </informaltable>
2411
2412
2413 <para>
2414 The values of data.l[0] and data.l[1] are copied directly from the
2415 client message event the client received.
2416 </para>
2417
2418 <para>
2419 The value in data.l[2] is
2420 the id of the window to which the
2421 ICE_PROTOCOLS.ICE_INITIATE_<emphasis remap='I'>pname</emphasis>
2422 client message event was sent.
2423 </para>
2424
2425 <para>Data.l[3] has one of the following values:</para>
2426
2427 <!-- .ne 21 -->
2428
2429 <informaltable frame='topbot'>
2430   <tgroup cols='3' align='left' colsep='0' rowsep='0'>
2431     <colspec colname='c1' colwidth='1.5*'/>
2432     <colspec colname='c2' colwidth='1.0*'/>
2433     <colspec colname='c3' colwidth='3.0*'/>
2434     <thead>
2435       <row rowsep='1'>
2436         <entry>Value</entry>
2437         <entry>Encoding</entry>
2438         <entry>Description</entry>
2439       </row>
2440     </thead>
2441     <tbody>
2442       <row>
2443         <entry>OpenFailed</entry>
2444         <entry>1</entry>
2445         <entry>
2446 The client was unable to open the connection
2447 (e.g. a call to IceOpenConnection() failed).  If the
2448 client is able to distinguish authentication or
2449 authorization errors from general errors, then
2450 the preferred reply is <function>AuthenticationFailed</function>
2451 for authorization errors.
2452           </entry>
2453       </row>
2454       <row>
2455         <entry>AuthenticationFailed</entry>
2456         <entry>2</entry>
2457         <entry>Authentication or authorization of the
2458 connection or protocol setup was refused.
2459 This reply will be given only if the client is
2460 able to distinguish it from
2461 <function>OpenFailed</function>
2462 otherwise
2463 <function>OpenFailed</function>
2464 will be returned.</entry>
2465       </row>
2466       <row>
2467         <entry>SetupFailed</entry>
2468         <entry>3</entry>
2469         <entry>The client was unable to initiate the specified
2470 protocol on the connection (e.g. a call to
2471 IceProtocolSetup() failed).</entry>
2472       </row>
2473       <row>
2474         <entry>UnknownProtocol</entry>
2475         <entry>4</entry>
2476         <entry>The client does not recognize the requested
2477 protocol.  (This represents a semantic error
2478 on the part of the answering party.)</entry>
2479       </row>
2480       <row>
2481         <entry>Refused</entry>
2482         <entry>5</entry>
2483         <entry>
2484 The client was in the process of removing
2485 ICE_INITIATE_<emphasis remap='I'>pname</emphasis>
2486 from its ICE_PROTOCOLS list
2487 when the client message was sent; the client no
2488 longer is willing to establish the specified ICE
2489 communication.</entry>
2490       </row>
2491     </tbody>
2492   </tgroup>
2493 </informaltable>
2494
2495
2496 <note>
2497 <para>
2498 Clients willing to act as ICE originating parties must update the
2499 ICE_PROTOCOLS property on their top-level windows to include the
2500 ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom(s) identifying
2501 the ICE subprotocols they
2502 speak.  The method a client uses to update the ICE_PROTOCOLS property
2503 to include ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atoms is
2504 implementation dependent, but
2505 the client must ensure the integrity of the list to prevent the
2506 accidental omission of any atoms previously in the list.
2507 </para>
2508
2509 <para>
2510 When setting up the ICE network IDs text property on one of its
2511 windows, the ICE answering party can determine its comma-separated
2512 list of ICE network IDs by calling IceComposeNetworkIdList() after
2513 making a call to IceListenForConnections().  The method an ICE
2514 answering party uses to find the top-level windows of clients willing
2515 to act as ICE originating parties is dependent upon the nature of the
2516 answering party.  Some may wish to use the approach of requiring the
2517 user to click on a client's window.  Others wishing to find existing
2518 clients without requiring user interaction might use something similar
2519 to the XQueryTree() method used by several freely-available
2520 applications.  In order for the ICE answering party to become
2521 automatically aware of new clients willing to originate ICE
2522 connections, the ICE answering party might register for
2523 SubstructureNotify events on the root window of the display.  When it
2524 receives a SubstructureNotify event, the ICE answering party can check
2525 to see if it was the result of the creation of a new client top-level
2526 window with an ICE_PROTOCOLS property.
2527 </para>
2528
2529 <para>
2530 In any case, before attempting to use this ICE X Rendezvous Mechanism
2531 ICE answering parties wishing to speak ICE subprotocol
2532 <emphasis remap='I'>pname</emphasis> should
2533 check for the ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom
2534 in the ICE_PROTOCOLS property on
2535 a client's top-level window.  A client that does not include an
2536 ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom in a
2537 ICE_PROTOCOLS property on some top-level window should be assumed to ignore
2538 <function>ClientMessage</function>
2539 events of type
2540 ICE_PROTOCOLS specifying ICE_INITIATE_<emphasis remap='I'>pname</emphasis>
2541 for ICE subprotocol <emphasis remap='I'>pname</emphasis>.
2542 </para>
2543 </note>
2544 </sect1>
2545
2546 <sect1 id='ICE_Subprotocol_Versioning'>
2547 <title>ICE Subprotocol Versioning</title>
2548
2549 <para>
2550 Although the version of the ICE subprotocol could be passed in the
2551 client message event, ICE provides more a flexible version negotiation
2552 mechanism than will fit within a single
2553 <function>ClientMessage</function>
2554 event.  Because
2555 of this, ICE subprotocol versioning is handled within the ICE protocol
2556 setup phase.</para>
2557 <note remap='NT'>
2558 <para>Clients wish to communicate with each other via an ICE subprotocol
2559 known as "RAP V1.0".  In RAP terminology one party, the "agent",
2560 communicates with other RAP-enabled applications on demand.  The
2561 user may direct the agent to establish communication with a specific
2562 application by clicking on the application's window, or the agent may
2563 watch for new application windows to be created and automatically
2564 establish communication.
2565 </para>
2566
2567 <para>
2568 During startup the ICE answering party (the agent) first calls
2569 IceRegisterForProtocolReply() with a list of
2570 the versions (i.e., 1.0) of RAP the agent can speak.  The answering
2571 party then calls IceListenForConnections() followed by
2572 IceComposeNetworkIdList() and stores the resulting ICE network IDs
2573 string in a text property on one of its windows.
2574 </para>
2575
2576 <para>
2577 When the answering party (agent) finds a client with which it wishes to
2578 speak, it checks to see if the ICE_INITIATE_RAP atom is in the ICE_PROTOCOLS
2579 property on the client's top-level window.  If it is present the agent
2580 sends the client's top-level window an ICE_PROTOCOLS client
2581 message event as described above.  When the client receives the client
2582 message event and is willing to originate an ICE connection using RAP,
2583 it performs an IceRegisterForProtocolSetup() with a list of the
2584 versions of RAP the client can speak.  The client then retrieves
2585 the agent's ICE network ID from the property and window specified by
2586 the agent in the client message event and calls IceOpenConnection().
2587 After this call succeeds the client calls IceProtocolSetup() specifying
2588 the RAP protocol.  During this
2589 process, ICE calls the RAP protocol routines that handle the version
2590 negotiation.
2591 </para>
2592
2593 <para>
2594 Note that it is not necessary for purposes of this rendezvous that
2595 the client application call any ICElib functions prior to receipt
2596 of the client message event.
2597 </para>
2598 </note>
2599 </sect1>
2600 </appendix>
2601 </book>