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 “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</para> 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 “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para> 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> 46There are numerous possible protocols that can be used for communication 47among clients. They have many similarities and common needs, including 48authentication, version negotiation, data typing, and connection management. The <emphasis remap='I'> Inter-Client Exchange</emphasis> (ICE) protocol 49is intended to provide a framework for building such protocols. Using 50ICE reduces the complexity of designing new protocols and 51allows 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> 60In discussing a variety of protocols -- existing, under development, and 61hypothetical -- it was noted that they have many elements in common. Most 62protocols need mechanisms for authentication, for 63version negotiation, 64and for setting up and taking down connections. There are also 65cases where the same two parties need to talk to each other using multiple 66protocols. For example, an embedding relationship between two parties is 67likely to require the simultaneous use of session management, data transfer, 68focus negotiation, and command notification protocols. While these are 69logically separate protocols, it is desirable for them to share as many 70pieces of implementation as possible.</para> 71 72<para>The 73<emphasis remap='I'> 74Inter-Client Exchange 75</emphasis> 76(ICE) protocol provides a generic framework for building protocols on top of 77reliable, byte-stream transport connections. It provides basic mechanisms 78for setting up and shutting down connections, for performing authentication, 79for negotiating 80versions, 81and for reporting errors. The 82protocols running within an ICE connection are referred to here as 83<emphasis remap='I'>subprotocols.</emphasis> 84ICE provides facilities for each subprotocol to do its own version 85negotiation, authentication, and error reporting. In addition, if two 86parties are communicating using several different subprotocols, ICE will 87allow 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 96each other and agree that they would like to communicate using an ICE 97subprotocol. ICE assumes that this negotiation includes some notion by which 98the parties will decide which is the <quote>originating</quote> party and which is 99the <quote>answering</quote> party. The negotiation will also need to provide the 100originating party with a name or address of the answering party. Examples 101of mechanisms by which parties can make themselves known to each other are 102the X selection mechanism, environment 103variables, and shared files.</para> 104 105<para>The originating party first determines whether there is an existing ICE 106connection between the two parties. If there is, it can re-use the existing 107connection and move directly to the setup of the subprotocol. If no ICE 108connection exists, the originating party will open a transport connection to 109the answering party and will start ICE connection setup.</para> 110 111<para>The ICE connection setup dialog consists of three major parts: byte order 112exchange, authentication, and connection information exchange. The first 113message in each direction is a 114<function>ByteOrder</function> 115message telling which byte order will be used by the sending party in 116messages that it sends. After that, the originating party sends a 117<function>ConnectionSetup</function> 118message giving information about itself (vendor name and release number) and 119giving a list of ICE version numbers it is capable of supporting and a list 120of authentication schemes it is willing to accept. Authentication is 121optional. If no authentication is required, the answering party responds 122with a 123<function>ConnectionReply</function> 124message 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 127respond with an 128<function>AuthenticationRequired</function> 129message instead of a 130<function>ConnectionReply</function> 131message. The parties then exchange 132<function>AuthenticationReply</function> 133and 134<function>AuthenticationNextPhase</function> 135messages until authentication is complete, at which time the answering party 136finally sends its 137<function>ConnectionReply</function> 138message.</para> 139 140<para>Once an ICE connection is established (or an existing connection reused), 141the originating party starts subprotocol negotiation by sending a 142<function>ProtocolSetup</function> 143message. This message gives the name of the subprotocol that the parties 144have agreed to use, along with the ICE major opcode that the originating 145party has assigned to that subprotocol. Authentication can also occur for 146the subprotocol, independently of authentication for the connection. 147Subprotocol authentication is optional. If there is no subprotocol 148authentication, the answering party responds with a 149<function>ProtocolReply</function> 150message, giving the ICE major opcode that it has assigned 151for the subprotocol.</para> 152 153<para>Subprotocols are authenticated independently of each other, because they may 154have differing security requirements. If there is authentication for this 155particular subprotocol, it takes place before the answering party emits the 156<function>ProtocolReply</function> 157message, and it uses the 158<function>AuthenticationRequired</function> 159<function>AuthenticationReply</function> 160and 161<function>AuthenticationNextPhase</function> 162messages, just as for the connection authentication. Only when subprotocol 163authentication is complete does the answering party send its 164<function>ProtocolReply</function> 165message.</para> 166 167<para>When a subprotocol has been set up and authenticated, the two parties can 168communicate using messages defined by the subprotocol. Each message has two 169opcodes: a major opcode and a minor opcode. Each party will send messages 170using the major opcode it has assigned in its 171<function>ProtocolSetup</function> 172or 173<function>ProtocolReply</function> 174message. These opcodes will, in general, not be the same. For a particular 175subprotocol, each party will need to keep track of two major opcodes: the 176major opcode it uses when it sends messages, and the major opcode it expects 177to see in messages it receives. The minor opcode values and semantics are 178defined by each individual subprotocol.</para> 179 180<para>Each subprotocol will have one or more messages whose semantics are that the 181subprotocol is to be shut down. Whether this is done unilaterally or is 182performed through negotiation is defined by each subprotocol. Once a 183subprotocol is shut down, its major opcodes are removed from 184use; no further messages on this subprotocol should be sent until the 185opcode 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 190no longer any active subprotocols. When either party decides that no 191subprotocols are active, it can send a 192<function>WantToClose</function> 193message. If the other party agrees to close the connection, it can simply 194do so. If the other party wants to keep the connection open, it can 195indicate its desire by replying with a 196<function>NoClose</function> 197message.</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 201necessarily the same as the one that initiates setting up a subprotocol. 202For example, suppose party A connects to party B. Party A will issue the 203<function>ConnectionSetup</function> 204message and party B will respond with a 205<function>ConnectionReply</function> 206message. (The authentication steps are omitted here for brevity.) 207Typically, party A will also issue the 208<function>ProtocolSetup</function> 209message and expect a 210<function>ProtocolReply</function> 211from party B. Once the connection is established, however, either party may 212initiate the negotiation of a subprotocol. Continuing this example, party B 213may decide that it needs to set up a subprotocol for communication with 214party A. Party B would issue the 215<function>ProtocolSetup</function> 216message and expect a 217<function>ProtocolReply</function> 218from 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 226the initial connection messages; in general data is sent in the sender's 227byte order and the receiver is required to swap it appropriately. 228In order to support 64-bit machines, ICE messages 229are padded to multiples of 8 bytes. All messages are designed so that 230fields are <quote>naturally</quote> aligned on 16-, 32-, and 64-bit boundaries. 231The following formula gives the number of bytes necessary 232to pad <emphasis remap='I'>E</emphasis> bytes to the next multiple of 233<emphasis remap='I'>b</emphasis>:</para> 234<literallayout remap='DS'> 235 236pad(<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> 269or 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 275Encoding</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<type> denotes a counted collection of <type>. The exact encoding 312varies 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> 357This specifies what subprotocol the message is intended for. Major opcode 3580 is reserved for ICE control messages. The major opcodes of other 359subprotocols are dynamically assigned and exchanged at protocol 360negotiation time. 361 </para> 362 </listitem> 363 </varlistentry> 364 <varlistentry> 365 <term>Protocol minor opcode</term> 366 <listitem> 367 <para> 368This specifies what protocol-specific operation is to be performed. 369Minor 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> 377This specifies the length of the information following the first 8 bytes. 378Each message-type has a different format, and will need to be separately 379length-checked against this value. As every data item has either an 380explicit length, or an implicit length, this can be easily accomplished. 381Messages that have too little or too much data indicate a serious 382protocol failure, and should result in a <function>BadLength</function> 383error. 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> 396Every message sent in a given direction has an implicit sequence number, 397starting with 1. Sequence numbers are global to the connection; independent 398sequence 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 401responded to (if a response is called for) in order by the receiving party. 402Messages 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 405is generated per request. If more than one error condition is encountered 406in processing a request, the choice of which error is returned is 407implementation-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><dependent on major/minor opcode and class></para> 444 </listitem> 445 </varlistentry> 446</variablelist> 447 448<para> 449This message is sent to report an error in response to a message 450from any protocol. The <function>Error</function> message 451exists in all protocol major-opcode spaces; it 452is minor-opcode zero in every protocol. The minor opcode of the 453message that caused the error is reported, as well as the sequence 454number of that message. 455The severity indicates the sender's behavior following 456the identification of the error. <function>CanContinue</function> 457indicates the sender is willing to accept additional messages for this 458protocol. <function>FatalToProcotol</function> 459indicates the sender is unwilling to accept further messages for this 460protocol but that messages for other protocols may be accepted. 461<function>FatalToConnection</function> 462indicates the sender is unwilling to accept any further 463messages for any protocols on the connection. The sender 464is required to conform to specified severity conditions 465for 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. 469The class defines the generic class of 470error. Classes are specified separately for each protocol (numeric 471values can mean different things in different protocols). The error 472values, if any, and their types vary with the specific error class 473for 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> 481Each of the ICE control opcodes is described below. 482Most of the messages have additional information included beyond the 483description above. The additional information is appended to the message 484header and the length field is computed accordingly. 485</para> 486 487<para> 488In the following message descriptions, <quote>Expected errors</quote> indicates 489errors 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> 498might occur, but generally indicate a serious implementation failure on 499the 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> 516Both parties must send this message before sending any other, 517including errors. This message specifies the byte order that 518will be used on subsequent messages sent by this party. 519</para> 520 521<note> 522<para> 523Note: If the receiver detects an error in this message, 524it 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> 587The 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> 593Versions gives a list, in decreasing order of preference, of the 594protocol versions this party is capable of speaking. This document 595specifies major version 1, minor version 0. 596</para> 597 598<para> 599If must-authenticate is <function>True</function> the initiating 600party demands authentication; the accepting party 601<emphasis remap='I'>must</emphasis> pick an authentication scheme 602and use it. In this case, the only valid response is 603<function>AuthenticationRequired</function> 604</para> 605 606<para> 607If must-authenticate is <function>False</function> the accepting 608party may choose an authentication mechanism, use a host-address-based 609authentication scheme, or skip authentication. When must-authenticate 610is <function>False</function> <function>ConnectionReply</function> and 611<function>AuthenticationRequired</function> are both valid responses. 612If 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> 618Authentication-protocol-names specifies a (possibly null, if 619must-authenticate is <function>False</function> 620list of authentication protocols the party is willing to perform. If 621must-authenticate is <function>True</function> 622presumably the party will offer only authentication mechanisms 623allowing mutual authentication. 624</para> 625 626<para> 627Vendor gives the name of the vendor of this ICE implementation. 628</para> 629 630<para> 631Release 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><specific to authentication protocol></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> 667This message is sent in response to a <function>ConnectionSetup</function> 668or <function>ProtocolSetup</function> 669message to specify that authentication is to be done and what 670authentication mechanism is to be used. 671</para> 672 673<para> 674The authentication protocol is specified by a 0-based index into the list 675of names given in the <function>ConnectionSetup</function> or 676<function>ProtocolSetup</function> 677Any 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><specific to authentication protocol></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> 712This message is sent in response to an 713<function>AuthenticationRequired</function> or 714<function>AuthenticationNextPhase</function> message, to 715supply authentication data as defined by the authentication protocol 716being used. 717</para> 718 719<para> 720Note that this message is sent by the party that initiated the current 721negotiation -- the party that sent the 722<function>ConnectionSetup</function> or 723<function>ProtocolSetup</function> message. 724</para> 725 726<para> 727<function>AuthenticationNextPhase</function> 728indicates that more is to be done to complete the authentication. 729If the authentication is complete, 730<function>ConnectionReply</function> 731is appropriate if the current authentication handshake is the result of a 732<function>ConnectionSetup</function> and a 733<function>ProtocolReply</function> 734is 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><specific to authentication protocol></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> 765This message is sent in response to an 766<function>AuthenticationReply</function> 767message, to supply authentication data as defined by the authentication 768protocol 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> 794This message is sent in response to a 795<function>ConnectionSetup</function> or 796<function>AuthenticationReply</function> 797message to indicate that the authentication handshake is complete. 798</para> 799 800<para> 801Version-index gives a 0-based index into the list of versions offered in 802the <function>ConnectionSetup</function> message; it specifies the 803version of the ICE protocol that both parties 804should 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> 810Release 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> 883This message is used to initiate negotiation of a protocol and 884establish any authentication specific to it. 885</para> 886 887<para> 888Protocol-name gives the name of the protocol the party wishes 889to speak. 890</para> 891 892<para> 893Major-opcode gives the opcode that the party will use in messages 894it sends. 895</para> 896 897<para> 898Versions gives a list of version numbers, in decreasing order of 899preference, that the party is willing to speak. 900</para> 901 902<para> 903Vendor and release are identification strings with semantics defined 904by the specific protocol being negotiated. 905</para> 906 907<para> 908If must-authenticate is <function>True</function>, 909the initiating party demands authentication; the accepting party 910<emphasis remap='I'>must</emphasis> pick an authentication scheme 911and use it. In this case, the only valid response is 912<function>AuthenticationRequired</function> 913</para> 914 915<para> 916If must-authenticate is <function>False</function>, 917the accepting party may choose an authentication mechanism, use a 918host-address-based authentication scheme, or skip authentication. 919When must-authenticate is <function>False</function>, 920<function>ProtocolReply</function> and 921<function>AuthenticationRequired</function> 922are both valid responses. If a host-address-based authentication 923scheme is used, <function>AuthenticationRejected</function> and 924<function>AuthenticationFailed</function> errors are possible. 925</para> 926 927<para> 928Authentication-protocol-names specifies a (possibly null, if 929must-authenticate is <function>False</function> 930list of authentication protocols the party is willing to perform. If 931must-authenticate is <function>True</function> 932presumably the party will offer only authentication mechanisms 933allowing 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> 965This message is sent in response to a <function>ProtocolSetup</function> 966or <function>AuthenticationReply</function> 967message to indicate that the authentication handshake is complete. 968</para> 969 970<para> 971Major-opcode gives the opcode that this party will use in 972messages that it sends. 973</para> 974 975<para> 976Version-index gives a 0-based index into the list of versions offered in the 977<function>ProtocolSetup</function> message; it specifies the version 978of the protocol that both parties should speak for the duration of 979the connection. 980</para> 981 982<para> 983Vendor and release are identification strings with semantics defined 984by 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> 998This message is used to test if the connection is still functioning. 999</para> 1000 1001<para><function>PingReply</function></para> 1002 1003<para> 1004This message is sent in response to a <function>Ping</function> 1005message, 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> 1024This message is used to initiate a possible close of the connection. 1025The sending party has noticed that, as a result of mechanisms specific 1026to each protocol, there are no active protocols left. 1027There are four possible scenarios arising from this request: 1028</para> 1029 1030<orderedlist> 1031 <listitem> 1032 <para> 1033The receiving side noticed too, and has already sent a 1034<function>WantToClose</function> On receiving a 1035<function>WantToClose</function> while already attempting to 1036shut down, each party should simply close the connection. 1037 </para> 1038 </listitem> 1039 <listitem> 1040 <para> 1041The receiving side hasn't noticed, but agrees. It closes the connection. 1042 </para> 1043 </listitem> 1044 <listitem> 1045 <para> 1046The 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 1050when it receives the <function>ProtocolSetup</function> 1051 </para> 1052 </listitem> 1053 <listitem> 1054 <para> 1055The receiving side wants the connection kept open for some 1056reason not specified by the ICE protocol, in which case it 1057sends <function>NoClose</function> 1058 </para> 1059 </listitem> 1060</orderedlist> 1061 1062<para> 1063See the state transition diagram for additional information. 1064</para> 1065 1066<para><function>NoClose</function></para> 1067 1068<para> 1069This message is sent in response to a <function>WantToClose</function> 1070message to indicate that the responding party does not want the 1071connection closed at this time. The receiving party should not close the 1072connection. 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> 1080These errors should be used by all protocols, as applicable. 1081For ICE (major opcode 0), <function>FatalToProtocol</function> 1082should 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><any></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> 1113Received 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><any></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> 1142Received a message with a valid minor opcode which is not appropriate 1143for 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><any></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> 1173Received a message with a bad length. The length of the message is 1174longer 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><any></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> 1196CARD32 Byte offset to offending value in offending message. 1197CARD32 Length of offending value. 1198<varies> 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><any></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> \(-> 1255<function>FatalToConnection</function> 1256<function>ProtocolSetup</function> \(-> 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> \(-> 1288<function>FatalToConnection</function> 1289<function>ProtocolSetup</function> \(-> 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> \(-> 1322<function>FatalToConnection</function> 1323<function>ProtocolSetup</function> \(-> 1324<function>FatalToProtocol</function> 1325<function>AuthenticationReply</function> \(-> 1326<function>FatalToConnection</function> if authenticating a connection, 1327otherwise <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> 1340The sending side is unable to accept the 1341new connection or new protocol for a reason other than authentication 1342failure. Typically this error will be a result of inability to allocate 1343additional resources on the sending side. The reason field will give a 1344human-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> 1374Authentication rejected. The peer has failed to properly 1375authenticate itself. The reason field will give a human-interpretable 1376message 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> 1406Authentication failed. <function>AuthenticationFailed</function> 1407does not imply that the authentication was rejected, as 1408<function>AuthenticationRejected</function> 1409does. Instead it means that the sender was unable to complete 1410the authentication for some other reason. (For instance, it 1411may have been unable to contact an authentication server.) 1412The reason field will give a human-interpretable message 1413providing 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> 1439The protocol name was already registered. This is fatal to 1440the "new" protocol being set up by <function>ProtocolSetup</function> 1441but 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> 1467The major opcode specified was already registered. This is 1468fatal to the <quote>new</quote> protocol being set up by 1469<function>ProtocolSetup</function> but it does not affect the 1470existing 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> 1504Here 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> -> <emphasis remap='C'>conn_wait</emphasis> 1510 1511<emphasis remap='C'>conn_wait</emphasis>: 1512 receive <function>ConnectionReply</function> -> <emphasis remap='C'>stasis</emphasis> 1513 receive <function>AuthenticationRequired</function> -> <emphasis remap='C'>conn_auth1</emphasis> 1514 receive <function>Error</function> -> <emphasis remap='C'>quit</emphasis> 1515 receive <other>, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis> 1516 1517<emphasis remap='C'>conn_auth1</emphasis>: 1518 if good auth data, send <function>AuthenticationReply</function> -> <emphasis remap='C'>conn_auth2</emphasis> 1519 if bad auth data, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis> 1520 1521<emphasis remap='C'>conn_auth2</emphasis>: 1522 receive <function>ConnectionReply</function> -> <emphasis remap='C'>stasis</emphasis> 1523 receive <function>AuthenticationNextPhase</function> -> <emphasis remap='C'>conn_auth1</emphasis> 1524 receive <function>Error</function> -> <emphasis remap='C'>quit</emphasis> 1525 receive <other>, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis> 1526</literallayout> 1527 1528<para> 1529Here are top-level state transitions for the party 1530that accepts connections. 1531</para> 1532 1533<literallayout> 1534<emphasis remap='C'>listener</emphasis>: 1535 accept connection -> <emphasis remap='C'>init_wait</emphasis> 1536 1537<emphasis remap='C'>init_wait</emphasis>: 1538 receive <function>ByteOrder</function> <function>ConnectionSetup</function> -> <emphasis remap='C'>auth_ask</emphasis> 1539 receive <other>, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis> 1540 1541<emphasis remap='C'>auth_ask</emphasis>: 1542 send <function>ByteOrder</function> <function>ConnectionReply</function> 1543-> <emphasis remap='C'>stasis</emphasis> 1544 1545 send <function>AuthenticationRequired</function> -> <emphasis remap='C'>auth_wait</emphasis> 1546 1547 send <function>Error</function> -> <emphasis remap='C'>quit</emphasis> 1548 1549<emphasis remap='C'>auth_wait</emphasis>: 1550 receive <function>AuthenticationReply</function> -> <emphasis remap='C'>auth_check</emphasis> 1551 1552 receive <other>, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis> 1553 1554<emphasis remap='C'>auth_check</emphasis>: 1555 if no more auth needed, send <function>ConnectionReply</function> -> <emphasis remap='C'>stasis</emphasis> 1556 if good auth data, send <function>AuthenticationNextPhase</function> -> <emphasis remap='C'>auth_wait</emphasis> 1557 if bad auth data, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis> 1558</literallayout> 1559 1560<para> 1561Here are the top-level state transitions for all parties after the initial 1562connection establishment subprotocol. 1563</para> 1564 1565<note> 1566<para> 1567Note: this is not quite the truth for branches out from stasis, in 1568that 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> -> <emphasis remap='C'>proto_wait</emphasis> 1575 receive <function>ProtocolSetup</function> -> <emphasis remap='C'>proto_reply</emphasis> 1576 send <function>Ping</function> -> <emphasis remap='C'>ping_wait</emphasis> 1577 receive <function>Ping</function> send <function>PingReply</function> -> <emphasis remap='C'>stasis</emphasis> 1578 receive <function>WantToClose</function> -> <emphasis remap='C'>shutdown_attempt</emphasis> 1579 receive <other>, send <function>Error</function> -> <emphasis remap='C'>stasis</emphasis> 1580 all protocols shut down, send <function>WantToClose</function> -> <emphasis remap='C'>close_wait</emphasis> 1581 1582<emphasis remap='C'>proto_wait</emphasis>: 1583 receive <function>ProtocolReply</function> -> <emphasis remap='C'>stasis</emphasis> 1584 receive <function>AuthenticationRequired</function> -> <emphasis remap='C'>give_auth1</emphasis> 1585 receive <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis> 1586 receive <function>WantToClose</function> -> <emphasis remap='C'>proto_wait</emphasis> 1587 1588<emphasis remap='C'>give_auth1</emphasis>: 1589 if good auth data, send <function>AuthenticationReply</function> -> <emphasis remap='C'>give_auth2</emphasis> 1590 if bad auth data, send <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis> 1591 receive <function>WantToClose</function> -> <emphasis remap='C'>give_auth1</emphasis> 1592 1593<emphasis remap='C'>give_auth2</emphasis>: 1594 receive <function>ProtocolReply</function> -> <emphasis remap='C'>stasis</emphasis> 1595 receive <function>AuthenticationNextPhase</function> -> <emphasis remap='C'>give_auth1</emphasis> 1596 receive <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis> 1597 receive <function>WantToClose</function> -> <emphasis remap='C'>give_auth2</emphasis> 1598 1599<emphasis remap='C'>proto_reply</emphasis>: 1600 send <function>ProtocolReply</function> -> <emphasis remap='C'>stasis</emphasis> 1601 send <function>AuthenticationRequired</function> -> <emphasis remap='C'>take_auth1</emphasis> 1602 send <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis> 1603 1604<emphasis remap='C'>take_auth1</emphasis>: 1605 receive <function>AuthenticationReply</function> -> <emphasis remap='C'>take_auth2</emphasis> 1606 receive <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis> 1607 1608<emphasis remap='C'>take_auth2</emphasis>: 1609 if good auth data \(-> <emphasis remap='C'>take_auth3</emphasis> 1610 if bad auth data, send <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis> 1611 1612<emphasis remap='C'>take_auth3</emphasis>: 1613 if no more auth needed, send <function>ProtocolReply</function> -> <emphasis remap='C'>stasis</emphasis> 1614 if good auth data, send <function>AuthenticationNextPhase</function> -> <emphasis remap='C'>take_auth1</emphasis> 1615 if bad auth data, send <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis> 1616 1617<emphasis remap='C'>ping_wait</emphasis>: 1618 receive <function>PingReply</function> -> <emphasis remap='C'>stasis</emphasis> 1619 1620<emphasis remap='C'>quit</emphasis>: 1621 -> close connection 1622</literallayout> 1623 1624<para> 1625Here 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> -> <emphasis remap='C'>stasis</emphasis> 1631 else -> <emphasis remap='C'>quit</emphasis> 1632 1633<emphasis remap='C'>close_wait</emphasis>: 1634 receive <function>ProtocolSetup</function> -> <emphasis remap='C'>proto_reply</emphasis> 1635 receive <function>NoClose</function> -> <emphasis remap='C'>stasis</emphasis> 1636 receive <function>WantToClose</function> -> <emphasis remap='C'>quit</emphasis> 1637 connection close -> <emphasis remap='C'>quit</emphasis> 1638</literallayout> 1639</chapter> 1640<chapter id='Protocol_Encoding'> 1641<title>Protocol Encoding</title> 1642 1643<para> 1644In the encodings below, the first column is the number of bytes occupied. 1645The second column is either the type (if the value is variable) or the 1646actual value. The third column is the description of the value (e.g., 1647the parameter name). Receivers must ignore bytes that are designated 1648as unused or pad bytes. 1649</para> 1650 1651<para> 1652This document describes major version 1, minor version 0 1653of the ICE protocol. 1654</para> 1655 1656<para> 1657LISTof<type> indicates some number of repetitions of 1658<type>, with no 1659additional padding. The number of repetitions must be specified elsewhere 1660in 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 1699Encoding</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 <varies> 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 <varies> 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 <varies> 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 <varies> 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> 2045Generic errors have classes in the range 0x8000-0xFFFF, and 2046subprotocol-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> 2151Release 6.1 added the ICE X rendezvous protocol (Appendix B) and 2152updated 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> 2169The ICE X rendezvous protocol is designed to answer the need posed 2170in Section 2 for one mechanism by which two clients interested in 2171communicating via ICE are able to exchange the necessary information. 2172This protocol is appropriate for any two ICE clients who also have X 2173connections 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> 2181The ICE X Rendezvous Mechanism requires clients willing to act as ICE 2182originating parties to pre-register the ICE subprotocols they support in an 2183ICE_PROTOCOLS property on their top-level window. Clients willing to 2184act as ICE answering parties then send an ICE_PROTOCOLS X 2185<function>ClientMessage</function> 2186event to the ICE originating parties. This 2187<function>ClientMessage</function> 2188event identifies 2189the ICE network IDs of the ICE answering party as well as the ICE 2190subprotocol it wishes to speak. Upon receipt of this message the ICE 2191originating party uses the information to establish an ICE connection 2192with the ICE answering party. 2193</para> 2194</sect1> 2195 2196<sect1 id='Registering_Known_Protocols'> 2197<title>Registering Known Protocols</title> 2198 2199<para> 2200Clients willing to act as ICE originating parties preregister 2201the ICE subprotocols they support in a list of atoms held by an 2202ICE_PROTOCOLS property on their top-level window. The name of each 2203atom listed in ICE_PROTOCOLS must be of the form 2204ICE_INITIATE_<emphasis remap='I'>pname</emphasis> where 2205<emphasis remap='I'>pname</emphasis> is the name of the ICE 2206subprotocol the ICE originating party is willing to speak, as would be 2207specified in an ICE 2208<function>ProtocolSetup</function> 2209message. 2210</para> 2211 2212<para> 2213Clients with an ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom 2214in the ICE_PROTOCOLS property on their top-level windows must respond to 2215<function>ClientMessage</function> events of 2216type ICE_PROTOCOLS specifying ICE_INITIATE_ 2217<emphasis remap='I'>pname</emphasis>. If a client does not 2218want to respond to these client message events, it should 2219remove the ICE_INITIATE_<emphasis remap='I'>pname</emphasis> 2220atom from its ICE_PROTOCOLS property 2221or 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> 2229To initiate the rendezvous a client acting as an ICE answering 2230party sends an X 2231<function>ClientMessage</function> 2232event of type ICE_PROTOCOLS to an ICE 2233originating party. This ICE_PROTOCOLS client message contains the 2234information the ICE originating party needs to identify the ICE 2235subprotocol the two parties will use as well as the ICE network 2236identification string of the ICE answering party. 2237</para> 2238 2239<para> 2240Before the ICE answering party sends the client message event it must 2241define a text property on one of its windows. This text property 2242contains the ICE answering party's ICE network identification string 2243and will be used by ICE originating parties to determine the ICE 2244answering party's list of ICE network IDs. 2245</para> 2246 2247<para> 2248The property name will normally be ICE_NETWORK_IDS, but may be any 2249name of the ICE answering party's choosing. The format for this text 2250property 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> 2284Once the ICE answering party has established this text property on one 2285of its windows, it initiates the rendezvous by sending an 2286ICE_PROTOCOLS 2287<function>ClientMessage</function> 2288event to an ICE originating party's 2289top-level window. This event has the following format 2290and must only be sent to windows that have pre-registered the ICE 2291subprotocol 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 2325ICE 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 2330answering 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> 2342The name of the atom in data.l[0] must be of the form 2343ICE_INITIATE_<emphasis remap='I'>pname</emphasis>, where 2344<emphasis remap='I'>pname</emphasis> is the name of the ICE 2345subprotocol the ICE answering party wishes to speak. 2346</para> 2347 2348<para> 2349When an ICE originating party receives a 2350<function>ClientMessage</function> 2351event of type 2352ICE_PROTOCOLS specifying ICE_INITIATE_<emphasis remap='I'>pname</emphasis> 2353it can initiate an ICE connection with the ICE answering party. 2354To open this connection the client retrieves the ICE answering 2355party's ICE network IDs from the window specified in data.l[2] using 2356the text property specified in data.l[3]. 2357</para> 2358 2359<para> 2360If the connection attempt fails for any reason, the client must 2361respond to the client message event by sending a return 2362<function>ClientMessage</function> 2363event to the window specified in data.l[2]. This return 2364event 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> 2414The values of data.l[0] and data.l[1] are copied directly from the 2415client message event the client received. 2416</para> 2417 2418<para> 2419The value in data.l[2] is 2420the id of the window to which the 2421ICE_PROTOCOLS.ICE_INITIATE_<emphasis remap='I'>pname</emphasis> 2422client 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> 2446The client was unable to open the connection 2447(e.g. a call to IceOpenConnection() failed). If the 2448client is able to distinguish authentication or 2449authorization errors from general errors, then 2450the preferred reply is <function>AuthenticationFailed</function> 2451for authorization errors. 2452 </entry> 2453 </row> 2454 <row> 2455 <entry>AuthenticationFailed</entry> 2456 <entry>2</entry> 2457 <entry>Authentication or authorization of the 2458connection or protocol setup was refused. 2459This reply will be given only if the client is 2460able to distinguish it from 2461<function>OpenFailed</function> 2462otherwise 2463<function>OpenFailed</function> 2464will 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 2470protocol on the connection (e.g. a call to 2471IceProtocolSetup() failed).</entry> 2472 </row> 2473 <row> 2474 <entry>UnknownProtocol</entry> 2475 <entry>4</entry> 2476 <entry>The client does not recognize the requested 2477protocol. (This represents a semantic error 2478on the part of the answering party.)</entry> 2479 </row> 2480 <row> 2481 <entry>Refused</entry> 2482 <entry>5</entry> 2483 <entry> 2484The client was in the process of removing 2485ICE_INITIATE_<emphasis remap='I'>pname</emphasis> 2486from its ICE_PROTOCOLS list 2487when the client message was sent; the client no 2488longer is willing to establish the specified ICE 2489communication.</entry> 2490 </row> 2491 </tbody> 2492 </tgroup> 2493</informaltable> 2494 2495 2496<note> 2497<para> 2498Clients willing to act as ICE originating parties must update the 2499ICE_PROTOCOLS property on their top-level windows to include the 2500ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom(s) identifying 2501the ICE subprotocols they 2502speak. The method a client uses to update the ICE_PROTOCOLS property 2503to include ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atoms is 2504implementation dependent, but 2505the client must ensure the integrity of the list to prevent the 2506accidental omission of any atoms previously in the list. 2507</para> 2508 2509<para> 2510When setting up the ICE network IDs text property on one of its 2511windows, the ICE answering party can determine its comma-separated 2512list of ICE network IDs by calling IceComposeNetworkIdList() after 2513making a call to IceListenForConnections(). The method an ICE 2514answering party uses to find the top-level windows of clients willing 2515to act as ICE originating parties is dependent upon the nature of the 2516answering party. Some may wish to use the approach of requiring the 2517user to click on a client's window. Others wishing to find existing 2518clients without requiring user interaction might use something similar 2519to the XQueryTree() method used by several freely-available 2520applications. In order for the ICE answering party to become 2521automatically aware of new clients willing to originate ICE 2522connections, the ICE answering party might register for 2523SubstructureNotify events on the root window of the display. When it 2524receives a SubstructureNotify event, the ICE answering party can check 2525to see if it was the result of the creation of a new client top-level 2526window with an ICE_PROTOCOLS property. 2527</para> 2528 2529<para> 2530In any case, before attempting to use this ICE X Rendezvous Mechanism 2531ICE answering parties wishing to speak ICE subprotocol 2532<emphasis remap='I'>pname</emphasis> should 2533check for the ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom 2534in the ICE_PROTOCOLS property on 2535a client's top-level window. A client that does not include an 2536ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom in a 2537ICE_PROTOCOLS property on some top-level window should be assumed to ignore 2538<function>ClientMessage</function> 2539events of type 2540ICE_PROTOCOLS specifying ICE_INITIATE_<emphasis remap='I'>pname</emphasis> 2541for 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> 2550Although the version of the ICE subprotocol could be passed in the 2551client message event, ICE provides more a flexible version negotiation 2552mechanism than will fit within a single 2553<function>ClientMessage</function> 2554event. Because 2555of this, ICE subprotocol versioning is handled within the ICE protocol 2556setup phase.</para> 2557<note remap='NT'> 2558<para>Clients wish to communicate with each other via an ICE subprotocol 2559known as "RAP V1.0". In RAP terminology one party, the "agent", 2560communicates with other RAP-enabled applications on demand. The 2561user may direct the agent to establish communication with a specific 2562application by clicking on the application's window, or the agent may 2563watch for new application windows to be created and automatically 2564establish communication. 2565</para> 2566 2567<para> 2568During startup the ICE answering party (the agent) first calls 2569IceRegisterForProtocolReply() with a list of 2570the versions (i.e., 1.0) of RAP the agent can speak. The answering 2571party then calls IceListenForConnections() followed by 2572IceComposeNetworkIdList() and stores the resulting ICE network IDs 2573string in a text property on one of its windows. 2574</para> 2575 2576<para> 2577When the answering party (agent) finds a client with which it wishes to 2578speak, it checks to see if the ICE_INITIATE_RAP atom is in the ICE_PROTOCOLS 2579property on the client's top-level window. If it is present the agent 2580sends the client's top-level window an ICE_PROTOCOLS client 2581message event as described above. When the client receives the client 2582message event and is willing to originate an ICE connection using RAP, 2583it performs an IceRegisterForProtocolSetup() with a list of the 2584versions of RAP the client can speak. The client then retrieves 2585the agent's ICE network ID from the property and window specified by 2586the agent in the client message event and calls IceOpenConnection(). 2587After this call succeeds the client calls IceProtocolSetup() specifying 2588the RAP protocol. During this 2589process, ICE calls the RAP protocol routines that handle the version 2590negotiation. 2591</para> 2592 2593<para> 2594Note that it is not necessary for purposes of this rendezvous that 2595the client application call any ICElib functions prior to receipt 2596of the client message event. 2597</para> 2598</note> 2599</sect1> 2600</appendix> 2601</book> 2602