diff options
Diffstat (limited to 'doc/ice.ms')
| -rw-r--r-- | doc/ice.ms | 1878 |
1 files changed, 0 insertions, 1878 deletions
diff --git a/doc/ice.ms b/doc/ice.ms deleted file mode 100644 index 7d31ea6..0000000 --- a/doc/ice.ms +++ /dev/null @@ -1,1878 +0,0 @@ -.\" Use tbl macros.t ice.ms | troff -ms -.\" $XdotOrg: xc/doc/specs/ICE/ice.ms,v 1.2 2004/04/23 18:42:16 eich Exp $ -.\" -.\" TODO: -.\" Think about connector/listener originator/answerer terminology. -.EH '''' -.OH '''' -.EF '''' -.OF '''' -.\" -.\" Disable hyphenation. I hate it. -.hy 0 -.de hy -.. -.\" A couple of macros to standardize things and make them -.\" easy to type. -.de Ss \" Begin state - .Ss <state name> -.KS -.LP -\fC\\$1\fP\^: -.br -.. -.de St \" Transition - .St "condition" message <new state> -.RS -\\$1 -.PN \\$2 -\(-> \fC\\$3\fP -.RE -.. -.de Se \" End state - .Se -.LP -.KE -.. -.de Ms \" Start message header - .Ms messagename -.sM -.PN \\$1 -.RS -.. -.de Mf \" Field in message - .Mf name; types follow on separate line(s) -.\".br -.IP "\fI\\$1\fP\^:" "\w'\fI\\$1\fP\^:'u+1" -.. -.de Mc \" Field Continuation - .Mc; description follows on separate line(s) -.br -.\" \h'1i' -.. -.de Ma \" Message addendum - .Ma title; contents follow -.IP "\\$1:" "\w'\\$1:'u+1" -.. -.de Me \" End of message header - .Me -.RE -.LP -.eM -.. -.de Es \" Start Encoding - .Es messagename -.KS -.LP -.nf -.PN \\$1 -.ta .2i .5i 2.0i -.. -.de Ee \" End Encoding - .Ee -.fi -.LP -.KE -.. -.\" -.\" --- cT --- centered title; centers $1, adds TOC entry unless $2 is "no" -.\" -.de cT -\\& \" filler so that the following .sp really leaves a space -.sp 1 -.ce 1 -\\s+1\\fB\\$1\\fP\\s-1 -.sp 1 -.if !'\\$2'no' \{\ -.XS \\n(PN -\\$1 -.XE -\} -.. -.ps 10 -.nr PS 10 -\& -.TL -\s+2\fBInter-Client Exchange (ICE) Protocol\fP\s-2 -.sp -Version 1.1 -.sp -X Consortium Standard -.sp -X Version 11, Release 6.8 - - - -.AU -Robert Scheifler -.AI -X Consortium, Inc. -.AU -Jordan Brown -.AI -Quarterdeck Office Systems - - - -.AB -.LP -There are numerous possible protocols that can be used for communication -among clients. They have many similarities and common needs, including -authentication, -version negotiation, -data typing, and -connection management. The -.I -Inter-Client Exchange -.R -(ICE) protocol is intended to provide a framework for building such -protocols. Using ICE reduces the complexity of designing new protocols and -allows the sharing of many aspects of the implementation. -.AE -.LP -.bp -\& -.sp 8 -.LP -.DS C -.if n Copyright (c) 1993, 1994 X Consortium -.if t Copyright \(co 1993, 1994 X Consortium -.DE -.sp 3 -.LP -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: -.LP -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. -.LP -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. -.LP -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. -.sp 5 -X Window System is a trademark of The Open Group. -.EH '\fBInter-Client Exchange Protocol\fP''\fBX11, Release 6.8\fP' -.OH '\fBInter-Client Exchange Protocol\fP''\fBX11, Release 6.8\fP' -.bp 1 -.EF ''\fB % \fP'' -.OF ''\fB % \fP'' -.nH 1 "Purpose and Goals" -.LP -In discussing a variety of protocols \(em existing, under development, and -hypothetical \(em it was noted that they have many elements in common. Most -protocols need mechanisms for authentication, for -version negotiation, -and for setting up and taking down connections. There are also -cases where the same two parties need to talk to each other using multiple -protocols. For example, an embedding relationship between two parties is -likely to require the simultaneous use of session management, data transfer, -focus negotiation, and command notification protocols. While these are -logically separate protocols, it is desirable for them to share as many -pieces of implementation as possible. -.LP -The -.I -Inter-Client Exchange -.R -(ICE) protocol provides a generic framework for building protocols on top of -reliable, byte-stream transport connections. It provides basic mechanisms -for setting up and shutting down connections, for performing authentication, -for negotiating -versions, -and for reporting errors. The -protocols running within an ICE connection are referred to here as -.I subprotocols. -ICE provides facilities for each subprotocol to do its own version -negotiation, authentication, and error reporting. In addition, if two -parties are communicating using several different subprotocols, ICE will -allow them to share the same transport layer connection. -.nH 1 "Overview of the protocol" -.LP -Through some mechanism outside ICE, two parties make themselves known to -each other and agree that they would like to communicate using an ICE -subprotocol. ICE assumes that this negotation includes some notion by which -the parties will decide which is the \*Qoriginating\*U party and which is -the \*Qanswering\*U party. The negotiation will also need to provide the -originating party with a name or address of the answering party. Examples -of mechanisms by which parties can make themselves known to each other are -the X selection mechanism, environment -variables, and shared files. -.LP -The originating party first determines whether there is an existing ICE -connection between the two parties. If there is, it can re-use the existing -connection and move directly to the setup of the subprotocol. If no ICE -connection exists, the originating party will open a transport connection to -the answering party and will start ICE connection setup. -.LP -The ICE connection setup dialog consists of three major parts: byte order -exchange, authentication, and connection information exchange. The first -message in each direction is a -.PN ByteOrder -message telling which byte order will be used by the sending party in -messages that it sends. After that, the originating party sends a -.PN ConnectionSetup -message giving information about itself (vendor name and release number) and -giving a list of ICE version numbers it is capable of supporting and a list -of authentication schemes it is willing to accept. Authentication is -optional. If no authentication is required, the answering party responds -with a -.PN ConnectionReply -message giving information about itself, and the connection setup is complete. -.LP -If the connection setup is to be authenticated, the answering party will -respond with an -.PN AuthenticationRequired -message instead of a -.PN ConnectionReply -message. The parties then exchange -.PN AuthenticationReply -and -.PN AuthenticationNextPhase -messages until authentication is complete, at which time the answering party -finally sends its -.PN ConnectionReply -message. -.LP -Once an ICE connection is established (or an existing connection reused), -the originating party starts subprotocol negotiation by sending a -.PN ProtocolSetup -message. This message gives the name of the subprotocol that the parties -have agreed to use, along with the ICE major opcode that the originating -party has assigned to that subprotocol. Authentication can also occur for -the subprotocol, independently of authentication for the connection. -Subprotocol authentication is optional. If there is no subprotocol -authentication, the answering party responds with a -.PN ProtocolReply -message, giving the ICE major opcode that it has assigned -for the subprotocol. -.LP -Subprotocols are authenticated independently of each other, because they may -have differing security requirements. If there is authentication for this -particular subprotocol, it takes place before the answering party emits the -.PN ProtocolReply -message, and it uses the -.PN AuthenticationRequired , -.PN AuthenticationReply , -and -.PN AuthenticationNextPhase -messages, just as for the connection authentication. Only when subprotocol -authentication is complete does the answering party send its -.PN ProtocolReply -message. -.LP -When a subprotocol has been set up and authenticated, the two parties can -communicate using messages defined by the subprotocol. Each message has two -opcodes: a major opcode and a minor opcode. Each party will send messages -using the major opcode it has assigned in its -.PN ProtocolSetup -or -.PN ProtocolReply -message. These opcodes will, in general, not be the same. For a particular -subprotocol, each party will need to keep track of two major opcodes: the -major opcode it uses when it sends messages, and the major opcode it expects -to see in messages it receives. The minor opcode values and semantics are -defined by each individual subprotocol. -.LP -Each subprotocol will have one or more messages whose semantics are that the -subprotocol is to be shut down. Whether this is done unilaterally or is -performed through negotiation is defined by each subprotocol. Once a -subprotocol is shut down, its major opcodes are removed from -use; no further messages on this subprotocol should be sent until the -opcode is reestablished with -.PN ProtocolSetup . -.LP -ICE has a facility to negotiate the closing of the connection when there are -no longer any active subprotocols. When either party decides that no -subprotocols are active, it can send a -.PN WantToClose -message. If the other party agrees to close the connection, it can simply -do so. If the other party wants to keep the connection open, it can -indicate its desire by replying with a -.PN NoClose -message. -.\" XXX - Note that it's likely that both parties will WantToClose at once. -.LP -It should be noted that the party that initiates the connection isn't -necessarily the same as the one that initiates setting up a subprotocol. -For example, suppose party A connects to party B. Party A will issue the -.PN ConnectionSetup -message and party B will respond with a -.PN ConnectionReply -message. (The authentication steps are omitted here for brevity.) -Typically, party A will also issue the -.PN ProtocolSetup -message and expect a -.PN ProtocolReply -from party B. Once the connection is established, however, either party may -initiate the negotiation of a subprotocol. Continuing this example, party B -may decide that it needs to set up a subprotocol for communication with -party A. Party B would issue the -.PN ProtocolSetup -message and expect a -.PN ProtocolReply -from party A. -.nH 1 "Data Types" -.LP -ICE messages contain several types of data. Byte order is negotiated in -the initial connection messages; in general data is sent in the sender's -byte order and the receiver is required to swap it appropriately. -In order to support 64-bit machines, ICE messages -are padded to multiples of 8 bytes. All messages are designed so that -fields are \*Qnaturally\*U aligned on 16-, 32-, and 64-bit boundaries. -The following formula gives the number of bytes necessary -to pad \fIE\fP bytes to the next multiple of \fIb\fP\^: -.DS -pad(\fIE\fP, \fIb\fP\^) = (\fIb\fP \- (\fIE\fP mod \fIb\fP\^)) mod \fIb\fP -.DE -.nH 2 "Primitive Types" -.LP -.TS H -expand; -lB lB -l lw(3.5i). -_ -.sp 6p -Type Name Description -.sp 6p -_ -.sp 6p -.TH -.R -CARD8 8-bit unsigned integer -CARD16 16-bit unsigned integer -CARD32 32-bit unsigned integer -BOOL T{ -.PN False -or -.PN True -T} -LPCE T{ -A character from the X Portable Character Set in Latin Portable Character -Encoding -T} -.sp 6p -_ -.TE -.KS -.nH 2 "Complex Types" -.LP -.TS H -expand; -lB lB -l lw(3.5i). -_ -.sp 6p -Type Name Type -.sp 6p -_ -.sp 6p -.TH -.R -VERSION [Major, minor: CARD16] -STRING LISTofLPCE -.sp 6p -_ -.TE -.KE -LISTof<type> denotes a counted collection of <type>. The exact encoding -varies depending on the context; see the encoding section. -.nH 1 "Message Format" -.LP -All ICE messages include the following information: -.TS H -expand; -cB lB - -l lw(3.5i). -_ -.sp 6p -Field Type Description -.sp 6p -_ -.sp 6p -.TH -CARD8 protocol major opcode -CARD8 protocol minor opcode -CARD32 length of remaining data in 8-byte units -.sp 6p -_ -.TE -.LP -The fields are as follows: -.LP -Protocol major opcode -.RS -This specifies what subprotocol the message is intended for. Major opcode -0 is reserved for ICE control messages. The major opcodes of other -subprotocols are dynamically assigned and exchanged at protocol -negotiation time. -.RE -.LP -Protocol minor opcode -.RS -This specifies what protocol-specific operation is to be performed. -Minor opcode 0 is reserved for Errors; other values are protocol-specific. -.RE -.LP -Length of data in 8-byte units -.RS -This specifies the length of the information following the first 8 bytes. -Each message-type has a different format, and will need to be separately -length-checked against this value. As every data item has either an -explicit length, or an implicit length, this can be easily accomplished. -Messages that have too little or too much data indicate a serious -protocol failure, and should result in a -.PN BadLength -error. -.RE -.nH 1 "Overall Protocol Description" -.LP -Every message sent in a given direction has an implicit sequence number, -starting with 1. Sequence numbers are global to the connection; independent -sequence numbers are \fInot\fP maintained for each protocol. -.LP -Messages of a given major-opcode (i.e., of a given protocol) must be -responded to (if a response is called for) in order by the receiving party. -Messages from different protocols can be responded to in arbitrary order. -.LP -Minor opcode 0 in every protocol is for reporting errors. At most one error -is generated per request. If more than one error condition is encountered -in processing a request, the choice of which error is returned is -implementation-dependent. -.Ms Error -.Mf offending-minor-opcode -CARD8 -.Mf severity -.Pn { CanContinue , -.PN FatalToProtocol , -.PN FatalToConnection } -.Mf sequence-number -CARD32 -.Mf class -CARD16 -.Mf value(s) -<dependent on major/minor opcode and class> -.Me -This message is sent to report an error in response to a message -from any protocol. -The -.PN Error -message -exists in all protocol major-opcode spaces; it -is minor-opcode zero in every protocol. The minor opcode of the -message that caused the error is reported, as well as the sequence -number of that message. -The severity indicates the sender's behavior following -the identification of the error. -.PN CanContinue -indicates the sender is willing to accept additional messages for this -protocol. -.PN FatalToProcotol -indicates the sender is unwilling to accept further messages for this -protocol but that messages for other protocols may be accepted. -.PN FatalToConnection -indicates the sender is unwilling to accept any further -messages for any protocols on the connection. The sender -is required to conform to specified severity conditions -for generic and ICE (major opcode 0) errors; see Sections 6.1 -and 6.2. -The class defines the generic class of -error. Classes are specified separately for each protocol (numeric -values can mean different things in different protocols). The error -values, if any, and their types vary with the specific error class -for the protocol. -.LP -.\" XXX -.\" (Asynchronous errors \(em errors not associated with a previous -.\" message??? If so, offending-minor and sequence = 0.) -.nH 1 "ICE Control Subprotocol \(em Major Opcode 0" -.LP -Each of the ICE control opcodes is described below. -Most of the messages have additional information included beyond the -description above. The additional information is appended to the message -header and -the length field is computed accordingly. -.LP -In the following message descriptions, \*QExpected errors\*U indicates -errors that may occur in the normal course of events. Other errors -(in particular -.PN BadMajor , -.PN BadMinor , -.PN BadState , -.PN BadLength , -.PN BadValue , -.PN ProtocolDuplicate , -and -.PN MajorOpcodeDuplicate ) -might occur, but generally indicate a serious implementation failure on -the part of the -errant -peer. -.Ms ByteOrder -.Mf byte-order -.Pn { MSBfirst , -.PN LSBfirst } -.Me -Both parties must send this message before sending any other, -including errors. This message specifies the byte order that -will be used on subsequent messages sent by this party. -.LP -Note: If the receiver detects an error in this message, -it must be sure to send its own -.PN ByteOrder -message before sending the -.PN Error . -.Ms ConnectionSetup -.Mf versions -LISTofVERSION -.Mf must-authenticate -BOOL -.Mf authentication-protocol-names -LISTofSTRING -.Mf vendor -STRING -.Mf release -STRING -.LP -.Ma "Responses" -.PN ConnectionReply , -.PN AuthenticationRequired . -(See note) -.Ma "Expected errors" -.PN NoVersion , -.PN SetupFailed , -.PN NoAuthentication , -.PN AuthenticationRejected , -.Mc -.PN AuthenticationFailed . -.Me -The party that initiates the connection -(the -one that does the \*Qconnect()\*U) -must send this -message -as the second message (after -.PN ByteOrder ) -on startup. -.LP -Versions gives a list, in decreasing order of preference, of the -protocol versions this party is capable of speaking. This document -specifies major version 1, minor version 0. -.LP -If must-authenticate is -.PN True , -the initiating party demands authentication; the accepting party \fImust\fP -pick an authentication scheme and use it. In this case, the only valid -response is -.PN AuthenticationRequired . -.LP -If must-authenticate is -.PN False , -the accepting party may choose an authentication mechanism, use a -host-address-based authentication scheme, or skip authentication. -When must-authenticate is -.PN False , -.PN ConnectionReply -and -.PN AuthenticationRequired -are both valid responses. If a host-address-based authentication scheme is -used, -.PN AuthenticationRejected -and -.PN AuthenticationFailed -errors are possible. -.LP -Authentication-protocol-names specifies a (possibly null, if -must-authenticate is -.PN False ) -list of authentication protocols the party is willing to perform. If -must-authenticate is -.PN True , -presumably the party will offer only authentication mechanisms -allowing mutual authentication. -.LP -Vendor gives the name of the vendor of this ICE implementation. -.LP -Release gives the release identifier of this ICE implementation. -.LP -.Ms AuthenticationRequired -.Mf authentication-protocol-index -CARD8 -.Mf data -<specific to authentication protocol> -.LP -.Ma "Response" -.PN AuthenticationReply . -.Ma "Expected errors" -.PN AuthenticationRejected , -.PN AuthenticationFailed . -.Me -This message is sent in response to a -.PN ConnectionSetup -or -.PN ProtocolSetup -message to specify that authentication is to be done and what authentication -mechanism is to be used. -.LP -The authentication protocol is specified by a 0-based index into the list -of names given in the -.PN ConnectionSetup -or -.PN ProtocolSetup . -Any protocol-specific data that might be required is also sent. -.Ms AuthenticationReply -.Mf data -<specific to authentication protocol> -.LP -.Ma "Responses" -.PN AuthenticationNextPhase , -.PN ConnectionReply , -.PN ProtocolReply . -.Ma "Expected errors" -.PN AuthenticationRejected , -.PN AuthenticationFailed , -.PN SetupFailed . -.Me -This message is sent in response to an -.PN AuthenticationRequired -or -.PN AuthenticationNextPhase -message, to -supply authentication data as defined by the authentication protocol -being used. -.LP -Note that this message is sent by the party that initiated the current -negotiation \(em the party that sent the -.PN ConnectionSetup -or -.PN ProtocolSetup -message. -.LP -.PN AuthenticationNextPhase -indicates that more is to be done to complete the authentication. -If the authentication is complete, -.PN ConnectionReply -is appropriate if the current authentication handshake is the result of a -.PN ConnectionSetup , -and a -.PN ProtocolReply -is appropriate if it is the result of a -.PN ProtocolSetup . -.Ms AuthenticationNextPhase -.Mf data -<specific to authentication protocol> -.LP -.Ma "Response" -.PN AuthenticationReply . -.Ma "Expected errors" -.PN AuthenticationRejected , -.PN AuthenticationFailed . -.Me -This message is sent in response to an -.PN AuthenticationReply -message, to supply authentication data as defined by the authentication -protocol being used. -.Ms ConnectionReply -.Mf version-index -CARD8 -.Mf vendor -STRING -.Mf release -STRING -.Me -This message is sent in response to a -.PN ConnectionSetup -or -.PN AuthenticationReply -message to indicate that the authentication handshake is complete. -.LP -Version-index gives a 0-based index into the list of versions offered in -the -.PN ConnectionSetup -message; it specifies the version of the ICE protocol that both parties -should speak for the duration of the connection. -.LP -Vendor gives the name of the vendor of this ICE implementation. -.LP -Release gives the release identifier of this ICE implementation. -.Ms ProtocolSetup -.Mf protocol-name -STRING -.Mf major-opcode -CARD8 -.Mf versions -LISTofVERSION -.Mf vendor -STRING -.Mf release -STRING -.Mf must-authenticate -BOOL -.Mf authentication-protocol-names -LISTofSTRING -.LP -.Ma "Responses" -.PN AuthenticationRequired , -.PN ProtocolReply . -.Ma "Expected errors" -.PN UnknownProtocol , -.PN NoVersion , -.PN SetupFailed , -.PN NoAuthentication , -.Mc -.PN AuthenticationRejected , -.PN AuthenticationFailed . -.Me -This message is used to initiate negotiation of -a protocol and establish any authentication -specific to it. -.LP -Protocol-name gives the name of the protocol the party wishes -to speak. -.LP -Major-opcode gives the opcode that the party will use in messages -it sends. -.LP -Versions gives a list of version numbers, in decreasing order of -preference, that the party is willing to speak. -.LP -Vendor and release are identification strings with semantics defined -by the specific protocol being negotiated. -.LP -If must-authenticate is -.PN True , -the initiating party demands authentication; the accepting party \fImust\fP -pick an authentication scheme and use it. In this case, the only valid -response is -.PN AuthenticationRequired . -.LP -If must-authenticate is -.PN False , -the accepting party may choose an authentication mechanism, use a -host-address-based authentication scheme, or skip authentication. -When must-authenticate is -.PN False , -.PN ProtocolReply -and -.PN AuthenticationRequired -are both valid responses. If a host-address-based authentication scheme is -used, -.PN AuthenticationRejected -and -.PN AuthenticationFailed -errors are possible. -.LP -Authentication-protocol-names specifies a (possibly null, if -must-authenticate is -.PN False ) -list of authentication protocols the party is willing to perform. If -must-authenticate is -.PN True , -presumably the party will offer only authentication mechanisms -allowing mutual authentication. -.Ms ProtocolReply -.Mf major-opcode -CARD8 -.Mf version-index -CARD8 -.Mf vendor -STRING -.Mf release -STRING -.Me -This message is sent in response to a -.PN ProtocolSetup -or -.PN AuthenticationReply -message to indicate that the authentication handshake is complete. -.LP -Major-opcode gives the opcode that this party will use in -messages that it sends. -.LP -Version-index gives a 0-based index into the list of versions offered in the -.PN ProtocolSetup -message; it specifies the version of the protocol that both -parties should speak for the duration of the connection. -.LP -Vendor and release are identification strings with semantics defined -by the specific protocol being negotiated. -.LP -.Ms Ping -.Ma "Response" -.PN PingReply . -.Me -This message is used to test if the connection is still functioning. -.Ms PingReply -.Me -This message is sent in response to a -.PN Ping -message, indicating that the connection is still functioning. -.Ms WantToClose -.Ma "Responses" -.PN WantToClose , -.PN NoClose , -.PN ProtocolSetup . -.Me -This message is used to initiate a possible close of the connection. -The sending party has noticed that, as a result of mechanisms specific -to each protocol, there are no active -protocols -left. -There are -four possible scenarios arising from this request: -.IP (1) 5 -The receiving side noticed too, and has already sent a -.PN WantToClose . -On receiving a -.PN WantToClose -while already attempting to shut down, each party should simply close the -connection. -.IP (2) -The receiving side hasn't noticed, but agrees. It closes -the connection. -.IP (3) -The receiving side has a -.PN ProtocolSetup -\*Qin flight,\*U in which case it is to ignore -.PN WantToClose -and the party sending -.PN WantToClose -is to abandon the shutdown attempt when it receives the -.PN ProtocolSetup . -.IP (4) -The receiving side wants the connection kept open for some -reason not specified by the ICE protocol, in which case it -sends -.PN NoClose . -.LP -See the state transition diagram for additional information. -.Ms NoClose -.Me -This message is sent in response to a -.PN WantToClose -message to indicate that the responding -party does not want the connection closed at -this time. The receiving party should not close the -connection. Either party may again initiate -.PN WantToClose -at some future time. -.nH 2 "Generic Error Classes" -.LP -These errors should be used by all protocols, as applicable. -For ICE (major opcode 0), -.PN FatalToProtocol -should -be interpreted as -.PN FatalToConnection. -.Ms BadMinor -.Mf offending-minor-opcode -<any> -.Mf severity -.PN FatalToProtocol -or -.PN CanContinue -(protocol's discretion) -.Mf values -(none) -.Me -Received a message with an unknown minor opcode. -.br -.ne 9 -.Ms BadState -.Mf offending-minor-opcode -<any> -.Mf severity -.PN FatalToProtocol -or -.PN CanContinue -(protocol's discretion) -.Mf values -(none) -.Me -Received a message with a valid minor opcode which is not appropriate -for the current state of the protocol. -.Ms BadLength -.Mf offending-minor-opcode -<any> -.Mf severity -.PN FatalToProtocol -or -.PN CanContinue -(protocol's discretion) -.Mf values -(none) -.Me -Received a message with a bad length. The length of the message is -longer or shorter than required to contain the data. -.Ms BadValue -.Mf offending-minor-opcode -<any> -.Mf severity -.PN CanContinue -.Mf values -CARD32 Byte offset to offending value in offending message -.Mc -CARD32 Length of offending value -.Mc -<varies> Offending value -.Me -Received a message with a bad value specified. -.nH 2 "ICE Error Classes" -.LP -These errors are all major opcode 0 errors. -.Ms BadMajor -.Mf offending-minor-opcode -<any> -.Mf severity -.PN CanContinue -.Mf values -CARD8 Opcode -.Me -The opcode given is not one that has been registered. -.Ms NoAuthentication -.Mf offending-minor-opcode -.PN ConnectionSetup , -.PN ProtocolSetup -.Mf severity -.PN ConnectionSetup -\(-> -.PN FatalToConnection -.Mc -.PN ProtocolSetup -\(-> -.PN FatalToProtocol -.Mf values -(none) -.Me -None of the authentication protocols offered are available. -.Ms NoVersion -.Mf offending-minor-opcode -.PN ConnectionSetup , -.PN ProtocolSetup -.Mf severity -.PN ConnectionSetup -\(-> -.PN FatalToConnection -.Mc -.PN ProtocolSetup -\(-> -.PN FatalToProtocol -.Mf values -(none) -.Me -None of the protocol versions offered are available. -.\" .Ms SetupFailed -.sM -.PN SetupFailed -.RS -.Mf offending-minor-opcode -.PN ConnectionSetup , -.PN ProtocolSetup , -.PN AuthenticationReply -.Mf severity -.PN ConnectionSetup -\(-> -.PN FatalToConnection -.Mc -.PN ProtocolSetup -\(-> -.PN FatalToProtocol -.Mc -.PN AuthenticationReply -\(-> -.PN FatalToConnection -if authenticating a connection, otherwise -.PN FatalToProtocol -.Mf values -STRING reason -.Me -The sending side is unable to accept the -new connection or new protocol for a reason other than authentication -failure. Typically this error will be a result of inability to allocate -additional resources on the sending side. The reason field will give a -human-interpretable message providing further detail on the type of failure. -.br -.Ms AuthenticationRejected -.Mf offending-minor-opcode -.PN AuthenticationReply , -.PN AuthenticationRequired , -.br -.PN AuthenticationNextPhase -.Mf severity -.PN FatalToProtocol -.Mf values -STRING reason -.Me -Authentication rejected. The peer has failed to properly -authenticate itself. -The reason field will give a human-interpretable message -providing further detail. -.Ms AuthenticationFailed -.Mf offending-minor-opcode -.PN AuthenticationReply , -.PN AuthenticationRequired , -.br -.PN AuthenticationNextPhase -.Mf severity -.PN FatalToProtocol -.Mf values -STRING reason -.Me -Authentication failed. -.PN AuthenticationFailed -does not imply that the authentication was rejected, as -.PN AuthenticationRejected -does. Instead it means that the sender was unable to complete -the authentication for some other reason. (For instance, it -may have been unable to contact an authentication server.) -The reason field will give a human-interpretable message -providing further detail. -.br -.ne 10 -.Ms ProtocolDuplicate -.Mf offending-minor-opcode -.PN ProtocolSetup -.Mf severity -.PN FatalToProtocol -(but see note) -.Mf values -STRING protocol name -.Me -The protocol name was already registered. This is fatal to -the \*Qnew\*U protocol being set up by -.PN ProtocolSetup , -but it does not affect the existing registration. -.Ms MajorOpcodeDuplicate -.Mf offending-minor-opcode -.PN ProtocolSetup -.Mf severity -.PN FatalToProtocol -(but see note) -.Mf values -CARD8 opcode -.Me -The major opcode specified was already registered. This is -fatal to the \*Qnew\*U protocol being set up by -.PN ProtocolSetup , -but it does not affect the existing registration. -.Ms UnknownProtocol -.Mf offending-minor-opcode -.PN ProtocolSetup -.Mf severity -.PN FatalToProtocol -.Mf values -STRING protocol name -.Me -The protocol specified is not supported. -.nH 1 "State Diagrams" -.LP -Here are the state diagrams for the party that initiates the connection: -.Ss start -.\" .St "connect to other end, send" ConnectionSetup conn_wait -.RS -connect to other end, send -.PN ByteOrder , -.PN ConnectionSetup -\(-> \fCconn_wait\fP -.RE -.Se -.Ss conn_wait -.St "receive" ConnectionReply stasis -.St "receive" AuthenticationRequired conn_auth1 -.St "receive" Error quit -.St "receive <other>, send" Error quit -.Se -.Ss conn_auth1 -.St "if good auth data, send" AuthenticationReply conn_auth2 -.St "if bad auth data, send" Error quit -.Se -.Ss conn_auth2 -.St "receive" ConnectionReply stasis -.St "receive" AuthenticationNextPhase conn_auth1 -.St "receive" Error quit -.St "receive <other>, send" Error quit -.Se -.br -.ne 22 -Here are top-level state transitions for the party that accepts connections. -.Ss listener -.\" .St "accept connection" "" init_wait -.RS -accept connection \(-> \fCinit_wait\fP -.RE -.Se -.Ss init_wait -.\" .St "receive ByteOrder, ConnectionSetup" auth_ask -.RS -receive -.PN ByteOrder , -.PN ConnectionSetup -\(-> \fCauth_ask\fP -.RE -.St "receive <other>, send" Error quit -.Se -.Ss auth_ask -.\" .St "send ByteOrder, ConnectionReply" stasis -.RS -send -.PN ByteOrder , -.PN ConnectionReply -\(-> \fCstasis\fP -.RE -.St "send" AuthenticationRequired auth_wait -.St "send" Error quit -.Se -.Ss auth_wait -.St "receive" AuthenticationReply auth_check -.St "receive <other>, send" Error quit -.Se -.Ss auth_check -.St "if no more auth needed, send" ConnectionReply stasis -.St "if good auth data, send" AuthenticationNextPhase auth_wait -.St "if bad auth data, send" Error quit -.Se -.sp 1 -Here are the top-level state transitions for all parties after the initial -connection establishment subprotocol. -.LP -Note: this is not quite the truth for branches out from stasis, in -that multiple conversations can be interleaved on the connection. -.Ss stasis -.St "send" ProtocolSetup proto_wait -.St "receive" ProtocolSetup proto_reply -.St "send" Ping ping_wait -.\" .St "receive Ping, send PingReply" stasis -.RS -receive -.PN Ping , -send -.PN PingReply -\(-> \fCstasis\fP -.RE -.St "receive" WantToClose shutdown_attempt -.St "receive <other>, send" Error stasis -.St "all protocols shut down, send" WantToClose close_wait -.Se -.Ss proto_wait -.St "receive" ProtocolReply stasis -.St "receive" AuthenticationRequired give_auth1 -.\" .St "receive Error, give up on this protocol" stasis -.RS -receive -.PN Error , -give up on this protocol \(-> \fCstasis\fP -.RE -.St "receive" WantToClose proto_wait -.Se -.Ss give_auth1 -.St "if good auth data, send" AuthenticationReply give_auth2 -.\" .St "if bad auth data, send Error, give up on this protocol" stasis -.RS -if bad auth data, send -.PN Error , -give up on this protocol \(-> \fCstasis\fP -.RE -.St "receive" WantToClose give_auth1 -.Se -.Ss give_auth2 -.St "receive" ProtocolReply stasis -.St "receive" AuthenticationNextPhase give_auth1 -.\" .St "receive Error, give up on this protocol" stasis -.RS -receive -.PN Error , -give up on this protocol \(-> \fCstasis\fP -.RE -.St "receive" WantToClose give_auth2 -.Se -.Ss proto_reply -.St "send" ProtocolReply stasis -.St "send" AuthenticationRequired take_auth1 -.\" .St "send Error, give up on this protocol" stasis -.RS -send -.PN Error , -give up on this protocol \(-> \fCstasis\fP -.RE -.Se -.Ss take_auth1 -.St "receive" AuthenticationReply take_auth2 -.\" .St "receive Error, give up on this protocol" stasis -.RS -receive -.PN Error , -give up on this protocol \(-> \fCstasis\fP -.RE -.Se -.Ss take_auth2 -.\" .St "if good auth data" take_auth3 -.RS -if good auth data \(-> \fCtake_auth3\fP -.RE -.\" .St "if bad auth data, send Error, give up on this protocol" stasis -.RS -if bad auth data, send -.PN Error , -give up on this protocol \(-> \fCstasis\fP -.RE -.Se -.Ss take_auth3 -.St "if no more auth needed, send" ProtocolReply stasis -.St "if good auth data, send" AuthenticationNextPhase take_auth1 -.\" .St "if bad auth data, send Error, give up on this protocol" stasis -.RS -if bad auth data, send -.PN Error , -give up on this protocol \(-> \fCstasis\fP -.RE -.Se -.Ss ping_wait -.St "receive" PingReply stasis -.Se -.Ss quit -.RS -\(-> close connection -.RE -.Se -.sp 1 -Here are the state transitions for shutting down the connection: -.Ss shutdown_attempt -.St "if want to stay alive anyway, send" NoClose stasis -.\" .St "else" quit -.RS -else \(-> \fCquit\fP -.RE -.Se -.Ss close_wait -.St "receive" ProtocolSetup proto_reply -.St "receive" NoClose stasis -.St "receive" WantToClose quit -.\" .St "connection close" quit -.RS -connection close \(-> \fCquit\fP -.RE -.Se -.nH 1 "Protocol Encoding" -.LP -In the encodings below, the first column is the number of bytes occupied. -The second column is either the type (if the value is variable) or the -actual value. The third column is the description of the value (e.g., -the parameter name). Receivers must ignore bytes that are designated -as unused or pad bytes. -.LP -This document describes major version 1, minor version 0 of the ICE protocol. -.LP -LISTof<type> indicates some number of repetitions of <type>, with no -additional padding. The number of repetitions must be specified elsewhere -in the message. -.KS -.nH 2 "Primitive Types" -.LP -.TS H -expand; -lB lB lB -l l lw(3.5i). -_ -.sp 6p -Type Name Length (bytes) Description -.sp 6p -_ -.sp 6p -.TH -.R -CARD8 1 8-bit unsigned integer -CARD16 2 16-bit unsigned integer -CARD32 4 32-bit unsigned integer -LPCE 1 T{ -A character from the X Portable Character Set in Latin Portable Character -Encoding -T} -.sp 6p -_ -.TE -.KE -.KS -.nH 2 "Enumerations" -.LP -.TS H -expand; -lB lB lB -l l lw(3.5i). -_ -.sp 6p -Type Name Value Description -.sp 6p -_ -.sp 6p -.TH -.R -BOOL 0 T{ -.PN False -T} - 1 T{ -.PN True -T} -.sp 6p -_ -.TE -.KE -.KS -.nH 2 "Compound Types" -.LP -.TS H -expand; -lB lB lB lB -l l l lw(3.5i). -_ -.sp 6p -Type Name Length (bytes) Type Description -.sp 6p -_ -.sp 6p -.TH -.R -VERSION - 2 CARD16 Major version number - 2 CARD16 Minor version number -STRING - 2 CARD16 length of string in bytes - n LISTofLPCE string - p unused, p = pad(n+2, 4) -.sp 6p -_ -.TE -.KE -.ne 6 -.nH 2 "ICE Minor opcodes" -.LP -.RS -.TS -lB cB -l n. -_ -.sp 6p -Message Name Encoding -.sp 6p -_ -.sp 6p -Error 0 -ByteOrder 1 -ConnectionSetup 2 -AuthenticationRequired 3 -AuthenticationReply 4 -AuthenticationNextPhase 5 -ConnectionReply 6 -ProtocolSetup 7 -ProtocolReply 8 -Ping 9 -PingReply 10 -WantToClose 11 -NoClose 12 -.sp 6p -_ -.TE -.RE -.\" XXX - This is hokey, but I don't think you can nest .KS/.KE. -.ne 16 -.nH 2 "Message Encoding" -.LP -.Es Error - 1 CARD8 major-opcode - 1 0 Error - 2 CARD16 class - 4 (n+p)/8+1 length - 1 CARD8 offending-minor-opcode - 1 severity: - 0 CanContinue - 1 FatalToProtocol - 2 FatalToConnection - 2 unused - 4 CARD32 sequence number of erroneous message - n <varies> value(s) - p pad, p = pad(n,8) -.Ee -.Es ByteOrder - 1 0 ICE - 1 1 ByteOrder - 1 byte-order: - 0 LSBfirst - 1 MSBfirst - 1 unused - 4 0 length -.Ee -.Es ConnectionSetup - 1 0 ICE - 1 2 ConnectionSetup - 1 CARD8 Number of versions offered - 1 CARD8 Number of authentication protocol names offered - 4 (i+j+k+m+p)/8+1 length - 1 BOOL must-authenticate - 7 unused - i STRING vendor - j STRING release - k LISTofSTRING authentication-protocol-names - m LISTofVERSION version-list - p unused, p = pad(i+j+k+m,8) -.Ee -.Es AuthenticationRequired - 1 0 ICE - 1 3 AuthenticationRequired - 1 CARD8 authentication-protocol-index - 1 unused - 4 (n+p)/8+1 length - 2 n length of authentication data - 6 unused - n <varies> data - p unused, p = pad(n,8) -.Ee -.Es AuthenticationReply - 1 0 ICE - 1 4 AuthenticationReply - 2 unused - 4 (n+p)/8+1 length - 2 n length of authentication data - 6 unused - n <varies> data - p unused, p = pad(n,8) -.Ee -.Es AuthenticationNextPhase - 1 0 ICE - 1 5 AuthenticationNextPhase - 2 unused - 4 (n+p)/8+1 length - 2 n length of authentication data - 6 unused - n <varies> data - p unused, p = pad(n,8) -.Ee -.Es ConnectionReply - 1 0 ICE - 1 6 ConnectionReply - 1 CARD8 version-index - 1 unused - 4 (i+j+p)/8 length - i STRING vendor - j STRING release - p unused, p = pad(i+j,8) -.Ee -.Es ProtocolSetup - 1 0 ICE - 1 7 ProtocolSetup - 1 CARD8 major-opcode - 1 BOOL must-authenticate - 4 (i+j+k+m+n+p)/8+1 length - 1 CARD8 Number of versions offered - 1 CARD8 Number of authentication protocol names offered - 6 unused - i STRING protocol-name - j STRING vendor - k STRING release - m LISTofSTRING authentication-protocol-names - n LISTofVERSION version-list - p unused, p = pad(i+j+k+m+n,8) -.Ee -.Es ProtocolReply - 1 0 ICE - 1 8 ProtocolReply - 1 CARD8 version-index - 1 CARD8 major-opcode - 4 (i+j+p)/8 length - i STRING vendor - j STRING release - p unused, p = pad(i+j, 8) -.Ee -.Es Ping - 1 0 ICE - 1 9 Ping - 2 0 unused - 4 0 length -.Ee -.Es PingReply - 1 0 ICE - 1 10 PingReply - 2 0 unused - 4 0 length -.Ee -.Es WantToClose - 1 0 ICE - 1 11 WantToClose - 2 0 unused - 4 0 length -.Ee -.Es NoClose - 1 0 ICE - 1 12 NoClose - 2 0 unused - 4 0 length -.Ee -.nH 2 "Error Class Encoding" -.LP -Generic errors have classes in the range 0x8000\-0xFFFF, and -subprotocol-specific errors are in the range 0x0000\-0x7FFF. -.nH 3 "Generic Error Class Encoding" -.LP -.TS -lB cB -l n. -_ -.sp 6p -Class Encoding -.sp 6p -_ -.sp 6p -BadMinor 0x8000 -BadState 0x8001 -BadLength 0x8002 -BadValue 0x8003 -.sp 6p -_ -.TE -.nH 3 "ICE-specific Error Class Encoding" -.LP -.TS -lB cB -l n. -_ -.sp 6p -Class Encoding -.sp 6p -_ -.sp 6p -BadMajor 0 -NoAuthentication 1 -NoVersion 2 -SetupFailed 3 -AuthenticationRejected 4 -AuthenticationFailed 5 -ProtocolDuplicate 6 -MajorOpcodeDuplicate 7 -UnknownProtocol 8 -.sp 6p -_ -.TE -.bp -.\" Set registers to number the appendixes A.1, B.1, C.1, ... -.nr H1 0 -.af H1 A -.cT "Appendix A" no -.nH 1 "Modification History" -.nH 2 "Release 6 to Release 6.1" -.LP -Release 6.1 added the ICE X rendezvous protocol (Appendix B) and -updated the document version to 1.1. -.nH 2 "Release 6.1 to Release 6.3" -.LP -Release 6.3 added the listen on well known ports feature. -.bp -.cT "Appendix B" no -.nH 1 "ICE X Rendezvous Protocol" -.nH 2 "Introduction" -.LP -The ICE X rendezvous protocol is designed to answer the need posed -in Section 2 for one mechanism by which two clients interested in -communicating via ICE are able to exchange the necessary information. -This protocol is appropriate for any two ICE clients who also have X -connections to the same X server. -.nH 2 "Overview of ICE X Rendezvous" -.LP -The ICE X Rendezvous Mechanism requires clients willing to act as ICE -originating parties to pre-register the ICE subprotocols they support in an -ICE_PROTOCOLS property on their top-level window. Clients willing to -act as ICE answering parties then send an ICE_PROTOCOLS X -.PN ClientMessage -event to the ICE originating parties. This -.PN ClientMessage -event identifies -the ICE network IDs of the ICE answering party as well as the ICE -subprotocol it wishes to speak. Upon receipt of this message the ICE -originating party uses the information to establish an ICE connection -with the ICE answering party. -.nH 2 "Registering Known Protocols" -.LP -Clients willing to act as ICE originating parties preregister -the ICE subprotocols they support in a list of atoms held by an -ICE_PROTOCOLS property on their top-level window. The name of each -atom listed in ICE_PROTOCOLS must be of the form -ICE_INITIATE_\fIpname\fP where \fIpname\fP is the name of the ICE -subprotocol the ICE originating party is willing to speak, as would be -specified in an ICE -.PN ProtocolSetup -message. -.LP -Clients with an ICE_INITIATE_\fIpname\fP atom in the ICE_PROTOCOLS property -on their top-level windows must respond to -.PN ClientMessage -events of -type ICE_PROTOCOLS specifying ICE_INITIATE_\fIpname\fP. If a client does not -want to respond to these client message events, it should -remove the ICE_INITIATE_\fIpname\fP atom from its ICE_PROTOCOLS property -or remove the ICE_PROTOCOLS property entirely. -.nH 2 "Initiating the Rendezvous" -.LP -To initiate the rendezvous a client acting as an ICE answering -party sends an X -.PN ClientMessage -event of type ICE_PROTOCOLS to an ICE -originating party. This ICE_PROTOCOLS client message contains the -information the ICE originating party needs to identify the ICE -subprotocol the two parties will use as well as the ICE network -identification string of the ICE answering party. -.LP -Before the ICE answering party sends the client message event it must -define a text property on one of its windows. This text property -contains the ICE answering party's ICE network identification string -and will be used by ICE originating parties to determine the ICE -answering party's list of ICE network IDs. -.LP -The property name will normally be ICE_NETWORK_IDS, but may be any -name of the ICE answering party's choosing. The format for this text -property is as follows: -.ne 7 -.TS -lB lB -lw(1.25i) lw(4i) . -_ -.sp 6p -Field Value -.sp 6p -_ -.sp 6p -type XA_STRING -format 8 -value comma-separated list of ICE network IDs -.sp 6p -_ -.TE -.LP -Once the ICE answering party has established this text property on one -of its windows, it initiates the rendezvous by sending an -ICE_PROTOCOLS -.PN ClientMessage -event to an ICE originating party's -top-level window. This event has the following format -and must only be sent to windows that have pre-registered the ICE -subprotocol in an ICE_PROTOCOLS property on their top-level window. -.ne 13 -.TS -lB lB -lw(1.25i) lw(4i) . -_ -.sp 6p -Field Value -.sp 6p -_ -.sp 6p -message_type Atom = "ICE_PROTOCOLS" -format 32 -data.l[0] Atom identifying the ICE subprotocol to speak -data.l[1] Timestamp -data.l[2] T{ -ICE answering party's window ID with -ICE network IDs text property -T} -data.l[3] T{ -Atom naming text property containing the ICE -answering party's ICE network IDs -T} -data.l[4] Reserved. Must be 0. -.sp 6p -_ -.TE -The name of the atom in data.l[0] must be of the form -ICE_INITIATE_\fIpname\fP, where \fIpname\fP is the name of the ICE -subprotocol the ICE answering party wishes to speak. -.LP -When an ICE originating party receives a -.PN ClientMessage -event of type -ICE_PROTOCOLS specifying ICE_INITIATE_\fIpname\fP it can initiate an ICE -connection with the ICE answering party. -To open this connection the client retrieves the ICE answering -party's ICE network IDs from the window specified in data.l[2] using -the text property specified in data.l[3]. -.LP -If the connection attempt fails for any reason, the client must -respond to the client message event by sending a return -.PN ClientMessage -event to the window specified in data.l[2]. This return -event has the following format: -.ne 13 -.TS -lB lB -lw(1.25i) lw(4i) . -_ -.sp 6p -Field Value -.sp 6p -_ -.sp 6p -message_type Atom = "ICE_INITIATE_FAILED" -format 32 -data.l[0] Atom identifying the ICE subprotocol requested -data.l[1] Timestamp -data.l[2] T{ -Initiating party's window ID -(holding ICE_PROTOCOLS) -T} -data.l[3] int: reason for failure -data.l[4] Reserved, must be 0 -.sp 6p -_ -.TE -The values of data.l[0] and data.l[1] are copied directly from the -client message event the client received. -.LP -The value in data.l[2] is -the id of the window to which the ICE_PROTOCOLS.ICE_INITIATE_\fIpname\fP -client message event was sent. -.LP -Data.l[3] has one of the following values: -.LP -.ne 21 -.TS -lB cBw(0.6i) lB -l n lw(4i) . -_ -.sp 6p -Value Encoding Description -.sp 6p -_ -.sp 6p -T{ -.PN OpenFailed -T} 1 T{ -The client was unable to open the connection -(e.g. a call to IceOpenConnection() failed). If the -client is able to distinguish authentication or -authorization errors from general errors, then -the preferred reply is -.PN AuthenticationFailed -for authorization errors. -T} -.sp 4p -T{ -.PN AuthenticationFailed -T} 2 T{ -Authentication or authorization of the -connection or protocol setup was refused. -This reply will be given only if the client is -able to distinguish it from -.PN OpenFailed ; -otherwise -.PN OpenFailed -will be returned. -T} -.sp 4p -T{ -.PN SetupFailed -T} 3 T{ -The client was unable to initiate the specified -protocol on the connection (e.g. a call to -IceProtocolSetup() failed). -T} -.sp 4p -T{ -.PN UnknownProtocol -T} 4 T{ -The client does not recognize the requested -protocol. (This represents a semantic error -on the part of the answering party.) -T} -.sp 4p -T{ -.PN Refused -T} 5 T{ -The client was in the process of removing -ICE_INITIATE_\fIpname\fP from its ICE_PROTOCOLS list -when the client message was sent; the client no -longer is willing to establish the specified ICE -communication. -T} -.sp 6p -_ -.TE -.sp -.NT "Advice to Implementors" -Clients willing to act as ICE originating parties must update the -ICE_PROTOCOLS property on their top-level windows to include the -ICE_INITIATE_\fIpname\fP atom(s) identifying the ICE subprotocols they -speak. The method a client uses to update the ICE_PROTOCOLS property -to include ICE_INITIATE_\fIpname\fP atoms is implementation dependent, but -the client must ensure the integrity of the list to prevent the -accidental omission of any atoms previously in the list. -.LP -When setting up the ICE network IDs text property on one of its -windows, the ICE answering party can determine its comma-separated -list of ICE network IDs by calling IceComposeNetworkIdList() after -making a call to IceListenForConnections(). The method an ICE -answering party uses to find the top-level windows of clients willing -to act as ICE originating parties is dependent upon the nature of the -answering party. Some may wish to use the approach of requiring the -user to click on a client's window. Others wishing to find existing -clients without requiring user interaction might use something similar -to the XQueryTree() method used by several freely-available -applications. In order for the ICE answering party to become -automatically aware of new clients willing to originate ICE -connections, the ICE answering party might register for -SubstructureNotify events on the root window of the display. When it -receives a SubstructureNotify event, the ICE answering party can check -to see if it was the result of the creation of a new client top-level -window with an ICE_PROTOCOLS property. -.LP -In any case, before attempting to use this ICE X Rendezvous Mechanism -ICE answering parties wishing to speak ICE subprotocol \fIpname\fP should -check for the ICE_INITIATE_\fIpname\fP atom in the ICE_PROTOCOLS property on -a client's top-level window. A client that does not include an -ICE_INITIATE_\fIpname\fP atom in a ICE_PROTOCOLS property on some top-level -window should be assumed to ignore -.PN ClientMessage -events of type -ICE_PROTOCOLS specifying ICE_INITIATE_\fIpname\fP for ICE subprotocol -\fIpname\fP. -.NE -.nH 2 "ICE Subprotocol Versioning" -.LP -Although the version of the ICE subprotocol could be passed in the -client message event, ICE provides more a flexible version negotiation -mechanism than will fit within a single -.PN ClientMessage -event. Because -of this, ICE subprotocol versioning is handled within the ICE protocol -setup phase. -.NT Example -Clients wish to communicate with each other via an ICE subprotocol -known as "RAP V1.0". In RAP terminology one party, the "agent", -communicates with other RAP-enabled applications on demand. The -user may direct the agent to establish communication with a specific -application by clicking on the application's window, or the agent may -watch for new application windows to be created and automatically -establish communication. -.LP -During startup the ICE answering party (the agent) first calls -IceRegisterForProtocolReply() with a list of -the versions (i.e., 1.0) of RAP the agent can speak. The answering -party then calls IceListenForConnections() followed by -IceComposeNetworkIdList() and stores the resulting ICE network IDs -string in a text property on one of its windows. -.LP -When the answering party (agent) finds a client with which it wishes to -speak, it checks to see if the ICE_INITIATE_RAP atom is in the ICE_PROTOCOLS -property on the client's top-level window. If it is present the agent -sends the client's top-level window an ICE_PROTOCOLS client -message event as described above. When the client receives the client -message event and is willing to originate an ICE connection using RAP, -it performs an IceRegisterForProtocolSetup() with a list of the -versions of RAP the client can speak. The client then retrieves -the agent's ICE network ID from the property and window specified by -the agent in the client message event and calls IceOpenConnection(). -After this call succeeds the client calls IceProtocolSetup() specifying -the RAP protocol. During this -process, ICE calls the RAP protocol routines that handle the version -negotiation. -.LP -Note that it is not necessary for purposes of this rendezvous that -the client application call any ICElib functions prior to receipt -of the client message event. -.NE -.YZ 1 |