.\" Use tbl macros.t ice.ms | troff -ms
.\"
.\" 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.4
.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 X Consortium, Inc.
.EH '\fBInter-Client Exchange Protocol\fP''\fBX11, Release 6.4\fP'
.OH '\fBInter-Client Exchange Protocol\fP''\fBX11, Release 6.4\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