1mInter-Client Exchange Library0m

			1mVersion 1.00m

		   1mX Consortium Standard0m

		 1mX Version 11, Release 6.40m


			 4mRalph24m 4mMor0m
			X Consortium



	 Copyright © 1993, 1994, 1996 X Consortium







Permission  is hereby granted, free of charge, to any person
obtaining a copy of this software and associated  documenta-
tion files (the ``Software''), to deal in the Software with-
out 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 fol-
lowing conditions:

The above copyright notice and this permission notice  shall
be  included  in  all  copies or substantial portions of the
Software.

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 PUR-
POSE  AND  NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR-
TIUM 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.

Except	as  contained in this notice, the name of the X Con-
sortium 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.















X Window System is a trademark of X Consortium, Inc.



































































































































1m1.  Overview of ICE0m

There are numerous  possible  inter-client  protocols,	with
many similarities and common needs - authentication, version
negotiation, byte order negotiation, and so on.	 The  Inter-
Client	Exchange  (ICE)	 protocol  is  intended to provide a
framework for building such protocols, allowing them to make
use  of	 common negotiation mechanisms and to be multiplexed
over a single transport connection.

1m2.  The ICE Library - C Language Interface to ICE0m

A client that wishes to utilize ICE must first register	 the
protocols  it understands with the ICE library.	 Each proto-
col is dynamically assigned  a	major  opcode  ranging	from
1-255  (two  clients can use different major opcodes for the
same protocol).	 The next step for the client is  either  to
open a connection with another client or to wait for connec-
tions  made  by	 other	clients.   Authentication   may	  be
required.  A client can both initiate connections with other
clients and be waiting for clients to connect to  itself  (a
nested	session manager is an example).	 Once an ICE connec-
tion is established between the	 two  clients,	one  of	 the
clients needs to initiate a 4mProtocolSetup24m in order to "acti-
vate" a given protocol.	 Once the other client	accepts	 the
4mProtocolSetup24m  (once again, authentication may be required),
the two clients are ready to start passing messages specific
to  that  protocol to each other.  Multiple protocols may be
active on a single ICE connection.  Clients are	 responsible
for  notifying	the ICE library when a protocol is no longer
active on an ICE connection, although ICE  does	 not  define
how each subprotocol triggers a protocol shutdown.

The  ICE library utilizes callbacks to process incoming mes-
sages.	Using callbacks allows	4mProtocolSetup24m  messages  and
authentication	to  happen behind the scenes.  An additional
benefit is that messages never need to be buffered up by the
library when the client blocks waiting for a particular mes-
sage.

1m3.  Intended Audience0m

This document is intended primarily for implementors of pro-
tocol  libraries layered on top of ICE.	 Typically, applica-
tions that wish to utilize ICE will make calls into individ-
ual  protocol libraries rather than directly make calls into
the ICE library.  However, some applications  will  have  to
make  some  initial  calls  into the ICE library in order to
accept ICE  connections	 (for  example,	 a  session  manager
accepting connections from clients).  But in general, proto-
col libraries should be designed to hide the  inner  details
of ICE from applications.





			    - 1 -





1mInter-Client Exchange Library		      X11, Release 6.40m


1m4.  Header Files and Library Name0m

The header file <4mX11/ICE/ICElib.h24m> defines all of the ICElib
data structures and function prototypes.  4mICElib.h24m	 includes
the  header  file  <4mX11/ICE/ICE.h24m>, which defines all of the
ICElib constants.  Protocol libraries that need to read	 and
write	 messages    should    include	 the   header	file
<4mX11/ICE/ICEmsg.h24m>.

Applications should link against ICElib using -lICE.

1m5.  Note on Prefixes0m

The following name prefixes are used in the library to	dis-
tinguish between a client that initiates a 4mProtocolSetup24m and
a client that responds with a 4mProtocolReply24m:

·    4mIcePo24m - Ice Protocol Originator

·    4mIcePa24m - Ice Protocol Acceptor

1m6.  Protocol Registration0m

In order for two clients to exchange messages  for  a  given
protocol,  each side must register the protocol with the ICE
library.  The purpose of registration is for  each  side  to
obtain	a major opcode for the protocol and to provide call-
backs for processing messages and  handling  authentication.
There are two separate registration functions:

·    One to handle the side that does a 4mProtocolSetup0m

·    One to handle the side that responds with a 4mProtocolRe-0m
     4mply0m

It is recommended that protocol	 registration  occur  before
the  two  clients  establish an ICE connection.	 If protocol
registration occurs after  an  ICE  connection	is  created,
there  can  be	a  brief  interval of time in which a 4mProto-0m
4mcolSetup24m is received, but the protocol  is	 not  registered.
If it is not possible to register a protocol before the cre-
ation of an ICE connection,  proper  precautions  should  be
taken to avoid the above race condition.


The  4mIceRegisterForProtocolSetup24m  function	 should be called
for the client that initiates a 4mProtocolSetup24m.
__
|








			    - 2 -





1mInter-Client Exchange Library		      X11, Release 6.40m


int IceRegisterForProtocolSetup(4mprotocol_name24m, 4mvendor24m, 4mrelease24m, 4mversion_count24m, 4mversion_recs24m,
		 4mauth_count24m, 4mauth_names24m, 4mauth_procs24m, 4mio_error_proc24m)
     char *4mprotocol_name24m;
     char *4mvendor24m;
     char *4mrelease24m;
     int 4mversion_count24m;
     IcePoVersionRec *4mversion_recs24m;
     int 4mauth_count24m;
     char **4mauth_names24m;
     IcePoAuthProc *4mauth_procs24m;
     IceIOErrorProc 4mio_error_proc24m;


4mprotocol_name0m
	  A string specifying the name of  the	protocol  to
	  register.

4mvendor24m    A  vendor  string  with semantics specified by the
	  protocol.

4mrelease24m   A release string with semantics specified  by  the
	  protocol.

4mversion_count0m
	  The  number  of different versions of the protocol
	  supported.

4mversion_recs0m
	  List of versions and associated callbacks.

4mauth_count0m
	  The number of authentication methods supported.

4mauth_names0m
	  The list of authentication methods supported.

4mauth_procs0m
	  The list of authentication callbacks, one for each
	  authentication method.

4mio_error_proc0m
	  IO error handler, or NULL.
|__

4mIceRegisterForProtocolSetup24m   returns   the   major   opcode
reserved or -1 if an error occurred.  In order	to  actually
activate  the  protocol, the 4mIceProtocolSetup24m function needs
to be called with this major opcode.  Once the	protocol  is
activated,  all	 messages  for	the  protocol should be sent
using this major opcode.

A protocol library may support multiple versions of the same
protocol.   The	 version_recs  argument	 specifies a list of
supported versions of the protocol, which are prioritized in



			    - 3 -





1mInter-Client Exchange Library		      X11, Release 6.40m


decreasing  order  of  preference.  Each version record con-
sists of a major and minor version of the protocol  as	well
as a callback to be used for processing incoming messages.

__
|
typedef struct {
     int major_version;
     int minor_version;
     IcePoProcessMsgProc process_msg_proc;
} IcePoVersionRec;

|__

The 4mIcePoProcessMsgProc24m callback is responsible for process-
ing the set of messages that can be received by	 the  client
that  initiated the 4mProtocolSetup24m.	 For further information,
see section 6.1, ``Callbacks for Processing Messages.''

Authentication may  be	required  before  the  protocol	 can
become	active.	  The  protocol	 library  must	register the
authentication	methods	 that  it  supports  with  the	 ICE
library.  The auth_names and auth_procs arguments are a list
of authentication names and callbacks that are	 prioritized
in  decreasing	order of preference.  For information on the
4mIcePoAuthProc24m callback, see  section  6.2,	 ``Authentication
Methods.''

The 4mIceIOErrorProc24m callback is invoked if the ICE connection
unexpectedly breaks.  You should pass NULL for io_error_proc
if  not	 interested in being notified.	For further informa-
tion, see section 13, ``Error Handling.''


The 4mIceRegisterForProtocolReply24m function  should  be  called
for  the client that responds to a 4mProtocolSetup24m with a 4mPro-0m
4mtocolReply24m.
__
|


















			    - 4 -





1mInter-Client Exchange Library		      X11, Release 6.40m


int IceRegisterForProtocolReply(4mprotocol_name24m, 4mvendor24m, 4mrelease24m, 4mversion_count24m, 4mversion_recs24m,
		    4mauth_count24m, 4mauth_names24m, 4mauth_procs24m, 4mhost_based_auth_proc24m, 4mprotocol_setup_proc24m,
		     4mprotocol_activate_proc24m, 4mio_error_proc24m)
     char *4mprotocol_name24m;
     char *4mvendor24m;
     char *4mrelease24m;
     int 4mversion_count24m;
     IcePaVersionRec *4mversion_recs24m;
     int 4mauth_count24m;
     char **4mauth_names24m;
     IcePaAuthProc *4mauth_procs24m;
     IceHostBasedAuthProc 4mhost_based_auth_proc24m;
     IceProtocolSetupProc 4mprotocol_setup_proc24m;
     IceProtocolActivateProc 4mprotocol_activate_proc24m;
     IceIOErrorProc 4mio_error_proc24m;


4mprotocol_name0m
	  A string specifying the name of  the	protocol  to
	  register.

4mvendor24m    A  vendor  string  with semantics specified by the
	  protocol.

4mrelease24m   A release string with semantics specified  by  the
	  protocol.

4mversion_count0m
	  The  number  of different versions of the protocol
	  supported.

4mversion_recs0m
	  List of versions and associated callbacks.

4mauth_count0m
	  The number of authentication methods supported.

4mauth_names0m
	  The list of authentication methods supported.

4mauth_procs0m
	  The list of authentication callbacks, one for each
	  authentication method.

4mhost_based_auth_proc0m
	  Host based authentication callback.

4mprotocol_setup_proc0m
	  A  callback  to be invoked when authentication has
	  succeeded for a 4mProtocolSetup24m but before the  4mPro-0m
	  4mtocolReply24m is sent.

4mprotocol_activate_proc0m
	  A  callback  to be invoked after the 4mProtocolReply0m



			    - 5 -





1mInter-Client Exchange Library		      X11, Release 6.40m


	  is sent.

4mio_error_proc0m
	  IO error handler, or NULL.
|__

4mIceRegisterForProtocolReply24m   returns   the   major   opcode
reserved  or  -1  if  an  error	 occurred.  The major opcode
should be used in all subsequent messages sent for this pro-
tocol.

A protocol library may support multiple versions of the same
protocol.  The version_recs argument  specifies	 a  list  of
supported versions of the protocol, which are prioritized in
decreasing order of preference.	 Each  version	record	con-
sists  of  a major and minor version of the protocol as well
as a callback to be used for processing incoming messages.

__
|
typedef struct {
     int major_version;
     int minor_version;
     IcePaProcessMsgProc process_msg_proc;
} IcePaVersionRec;

|__

The 4mIcePaProcessMsgProc24m callback is responsible for process-
ing  the  set of messages that can be received by the client
that accepted the 4mProtocolSetup24m.  For  further  information,
see section 6.1, ``Callbacks for Processing Messages.''

Authentication	may  be	 required  before  the	protocol can
become active.	 The  protocol	library	 must  register	 the
authentication	 methods  that	it  supports  with  the	 ICE
library.  The auth_names and auth_procs arguments are a list
of  authentication  names and callbacks that are prioritized
in decreasing order of preference.  For information  on	 the
4mIcePaAuthProc24m  callback,  see  section 6.2, ``Authentication
Methods.''

If authentication fails and the client attempting to  initi-
ate  the  4mProtocolSetup24m has not required authentication, the
4mIceHostBasedAuthProc24m callback is invoked with the host  name
of  the	 originating  client.  If the callback returns 4mTrue24m,
the 4mProtocolSetup24m will succeed,  even  though  the	 original
authentication	failed.	 Note that authentication can effec-
tively be disabled by registering  an  4mIceHostBasedAuthProc24m,
which  always returns 4mTrue24m.  If no host based authentication
is allowed, you should pass NULL for host_based_auth_proc.






			    - 6 -





1mInter-Client Exchange Library		      X11, Release 6.40m

__
|
typedef Bool (*IceHostBasedAuthProc) ();

Bool HostBasedAuthProc(4mhost_name24m)
    char *4mhost_name24m;


4mhost_name24m The host name of the client that sent  the  4mProto-0m
	  4mcolSetup24m.
|__

The  host_name	argument  is  a	 string	 of  the form 4mproto-0m
4mcol24m/4mhostname24m, where 4mprotocol24m is one of {tcp, decnet, local}.

Because	 4mProtocolSetup24m  messages  and  authentication happen
behind the scenes via callbacks, the protocol library  needs
some  way  of being notified when the 4mProtocolSetup24m has com-
pleted.	 This occurs in two phases.  In the first phase, the
4mIceProtocolSetupProc24m  callback  is invoked after authentica-
tion has successfully completed but before the	ICE  library
sends a 4mProtocolReply24m.  Any resources required for this pro-
tocol should be allocated at this time.	  If  the  4mIceProto-0m
4mcolSetupProc24m  returns  a  successful status, the ICE library
will send the 4mProtocolReply24m and then invoke the  4mIceProtoco-0m
4mlActivateProc24m callback.  Otherwise, an error will be sent to
the other client in response to the 4mProtocolSetup24m.

The 4mIceProtocolActivateProc24m  is  an  optional  callback  and
should be registered only if the protocol library intends to
generate a message immediately following the  4mProtocolReply24m.
You  should  pass  NULL	 for  protocol_activate_proc  if not
interested in this callback.
__
|
typedef Status (*IceProtocolSetupProc) ();

Status ProtocolSetupProc(4mice_conn24m, 4mmajor_version24m, 4mminor_version24m, 4mvendor24m, 4mrelease24m,
		    4mclient_data_ret24m, 4mfailure_reason_ret24m)
     IceConn 4mice_conn24m;
     int 4mmajor_version24m;
     int 4mminor_version24m;
     char *4mvendor24m;
     char *4mrelease24m;
     IcePointer *4mclient_data_ret24m;
     char **4mfailure_reason_ret24m;


4mice_conn24m  The ICE connection object.

4mmajor_version0m
	  The major version of the protocol.

4mminor_version0m
	  The minor version of the protocol.



			    - 7 -





1mInter-Client Exchange Library		      X11, Release 6.40m


4mvendor24m    The vendor string registered by the protocol orig-
	  inator.

4mrelease24m   The  release  string  registered	 by  the protocol
	  originator.

4mclient_data_ret0m
	  Client data to be set by callback.

4mfailure_reason_ret0m
	  Failure reason returned.
|__

The pointer stored in the client_data_ret argument  will  be
passed	to  the 4mIcePaProcessMsgProc24m callback whenever a mes-
sage has arrived for this protocol on the ICE connection.

The vendor and release strings should  be  freed  with	4mfree0m
when they are no longer needed.

If  a failure occurs, the 4mIceProtocolSetupProc24m should return
a zero status as well as allocate and return a failure	rea-
son  string  in failure_reason_ret.  The ICE library will be
responsible for freeing this memory.

The 4mIceProtocolActivateProc24m callback is defined as follows:
__
|
typedef void (*IceProtocolActivateProc)();

void ProtocolActivateProc(4mice_conn24m, 4mclient_data24m)
    IceConn 4mice_conn24m;
    IcePointer 4mclient_data24m;


4mice_conn24m  The ICE connection object.

4mclient_data0m
	  The client data set  in  the	4mIceProtocolSetupProc0m
	  callback.
|__

The 4mIceIOErrorProc24m callback is invoked if the ICE connection
unexpectedly breaks.  You should pass NULL for io_error_proc
if  not	 interested in being notified.	For further informa-
tion, see section 13, ``Error Handling.''

1m6.1.	Callbacks for Processing Messages0m

When an application detects that there is new data  to	read
on  an	ICE  connection	 (via  4mselect24m), it calls the 4mIcePro-0m
4mcessMessages24m function  (see  section  9,  ``Processing  Mes-
sages'').   When  4mIceProcessMessages24m  reads  an  ICE message
header with a major opcode other than zero (reserved for the



			    - 8 -





1mInter-Client Exchange Library		      X11, Release 6.40m


ICE  protocol),	 it  needs to call a function that will read
the rest of the message, unpack it, and process	 it  accord-
ingly.

If the message arrives at the client that initiated the 4mPro-0m
4mtocolSetup24m, the 4mIcePoProcessMsgProc24m callback is invoked.
__
|
typedef void (*IcePoProcessMsgProc)();

void PoProcessMsgProc(4mice_conn24m, 4mclient_data24m, 4mopcode24m, 4mlength24m, 4mswap24m, 4mreply_wait24m, 4mreply_ready_ret24m)
    IceConn 4mice_conn24m;
    IcePointer 4mclient_data24m;
    int 4mopcode24m;
    unsigned long 4mlength24m;
    Bool 4mswap24m;
    IceReplyWaitInfo *4mreply_wait24m;
    Bool *4mreply_ready_ret24m;


4mice_conn24m  The ICE connection object.

4mclient_data0m
	  Client data associated with this protocol  on	 the
	  ICE connection.

4mopcode24m    The minor opcode of the message.

4mlength24m    The length (in 8-byte units) of the message beyond
	  the ICE header.

4mswap24m      A flag that indicates if byte swapping  is  neces-
	  sary.

4mreply_wait0m
	  Indicates  if the invoking client is waiting for a
	  reply.

4mreply_ready_ret0m
	  If set to 4mTrue24m, a reply is ready.
|__

If the message arrives at the client that accepted the	4mPro-0m
4mtocolSetup24m, the 4mIcePaProcessMsgProc24m callback is invoked.
__
|











			    - 9 -





1mInter-Client Exchange Library		      X11, Release 6.40m


typedef void (*IcePaProcessMsgProc)();

void PaProcessMsgProc(4mice_conn24m, 4mclient_data24m, 4mopcode24m, 4mlength24m, 4mswap24m)
    IceConn 4mice_conn24m;
    IcePointer 4mclient_data24m;
    int 4mopcode24m;
    unsigned long 4mlength24m;
    Bool 4mswap24m;


4mice_conn24m  The ICE connection object.

4mclient_data0m
	  Client  data	associated with this protocol on the
	  ICE connection.

4mopcode24m    The minor opcode of the message.

4mlength24m    The length (in 8-byte units) of the message beyond
	  the ICE header.

4mswap24m      A  flag	that indicates if byte swapping is neces-
	  sary.
|__

In order to read the message, both of these callbacks should
use  the  macros defined for this purpose (see section 12.2,
``Reading ICE Messages'').  Note that byte swapping  may  be
necessary.   As	 a  convenience, the length field in the ICE
header will be swapped by ICElib if necessary.

In both of these callbacks, the client_data  argument  is  a
pointer	 to client data that was registered at 4mProtocolSetup0m
time.  In the case of 4mIcePoProcessMsgProc24m, the  client  data
was  set  in  the  call to 4mIceProtocolSetup24m.  In the case of
4mIcePaProcessMsgProc24m, the client data was set in the  4mIcePro-0m
4mtocolSetupProc24m callback.

The   4mIcePoProcessMsgProc24m	 callback   needs  to  check  the
reply_wait argument.   If  reply_wait  is  NULL	 ,  the	 ICE
library	 expects  the  function	 to  pass the message to the
client via a callback.	For example, if this  is  a  Session
Management  ``Save  Yourself'' message, this function should
notify the client of the ``Save Yourself'' via	a  callback.
The  details  of  how  such  a callback would be defined are
implementation-dependent.

However, if reply_wait is not NULL  ,  then  the  client  is
waiting	 for a reply or an error for a message it previously
sent.  The reply_wait is of type 4mIceReplyWaitInfo24m.
__
|
typedef struct {
     unsigned long sequence_of_request;



			   - 10 -





1mInter-Client Exchange Library		      X11, Release 6.40m


     int major_opcode_of_request;
     int minor_opcode_of_request;
     IcePointer reply;
} IceReplyWaitInfo;

|__

4mIceReplyWaitInfo24m  contains	 the  major/minor   opcodes   and
sequence  number  of  the message for which a reply is being
awaited.  It also contains a pointer to the reply message to
be  filled  in	(the  protocol library should cast this 4mIce-0m
4mPointer24m to the appropriate reply type).  In most cases,  the
reply will have some fixed-size part, and the client waiting
for the reply will have provided a pointer to a structure to
hold  this  fixed-size	data.	If  there is variable-length
data, it would	be  expected  that  the	 4mIcePoProcessMsgProc0m
callback  will	have to allocate additional memory and store
pointer(s) to that memory in the fixed-size  structure.	  If
the  entire  data is variable length (for example., a single
variable-length string), then the  client  waiting  for	 the
reply would probably just pass a pointer to fixed-size space
to hold a  pointer,  and  the  4mIcePoProcessMsgProc24m	 callback
would allocate the storage and store the pointer.  It is the
responsibility of the client receiving the reply to free any
memory allocated on its behalf.

If  reply_wait	is  not	 NULL  and 4mIcePoProcessMsgProc24m has a
reply or error to return  in  response	to  this  reply_wait
(that	is,   no   callback   was   generated),	  then	 the
reply_ready_ret argument should be set to 4mTrue24m.   Note  that
an  error  should  only be returned if it corresponds to the
reply being waited for.	 Otherwise, the	 4mIcePoProcessMsgProc0m
should either handle the error internally or invoke an error
handler for its library.

If reply_wait is NULL, then care must be taken not to  store
any  value in reply_ready_ret, because this pointer may also
be NULL.

The 4mIcePaProcessMsgProc24m callback, on the other hand,  should
always	pass  the message to the client via a callback.	 For
example,  if  this  is	a  Session   Management	  ``Interact
Request'' message, this function should notify the client of
the ``Interact Request'' via a callback.

The reason the 4mIcePaProcessMsgProc24m callback does not have	a
reply_wait,  like  4mIcePoProcessMsgProc24m  does,  is	because a
process that is acting as a server should never block for  a
reply  (infinite blocking can occur if the connecting client
does not act properly, denying access to other clients).







			   - 11 -





1mInter-Client Exchange Library		      X11, Release 6.40m


1m6.2.	Authentication Methods0m

As already stated, a  protocol	library	 must  register	 the
authentication	 methods  that	it  supports  with  the	 ICE
library.  For each  authentication  method,  there  are	 two
callbacks that may be registered:

·    One to handle the side that initiates a 4mProtocolSetup0m

·    One  to  handle  the  side that accepts or rejects this
     request

4mIcePoAuthProc24m is the callback invoked for	the  client  that
initiated  the 4mProtocolSetup24m.  This callback must be able to
respond to the initial ``Authentication	 Required''  message
or subsequent ``Authentication Next Phase'' messages sent by
the other client.
__
|
typedef IcePoAuthStatus (*IcePoAuthProc)();

IcePoAuthStatus PoAuthProc(4mice_conn24m, 4mauth_state_ptr24m, 4mclean_up24m, 4mswap24m, 4mauth_datalen24m, 4mauth_data24m,
		    4mreply_datalen_ret24m, 4mreply_data_ret24m, 4merror_string_ret24m)
    IceConn 4mice_conn24m;
    IcePointer *4mauth_state_ptr24m;
    Bool 4mclean_up24m;
    Bool 4mswap24m;
    int 4mauth_datalen24m;
    IcePointer 4mauth_data24m;
    int *4mreply_datalen_ret24m;
    IcePointer *4mreply_data_ret24m;
    char **4merror_string_ret24m;


4mice_conn24m  The ICE connection object.

4mauth_state_ptr0m
	  A pointer to state for use by	 the  authentication
	  callback procedure.

4mclean_up24m  If  4mTrue24m, authentication is over, and the function
	  should clean up any state it was maintaining.	 The
	  last 6 arguments should be ignored.

4mswap24m      If 4mTrue24m, the auth_data may have to be byte swapped
	  (depending on its contents).

4mauth_datalen0m
	  The length (in bytes) of the authenticator data.

4mauth_data24m The data from the authenticator.

4mreply_datalen_ret0m
	  The length (in bytes) of the reply data  returned.



			   - 12 -





1mInter-Client Exchange Library		      X11, Release 6.40m


4mreply_data_ret0m
	  The reply data returned.

4merror_string_ret0m
	  If  the  authentication  procedure  encounters  an
	  error during authentication,	it  should  allocate
	  and return an error string.
|__

Authentication	may require several phases, depending on the
authentication method.	As a result, the  4mIcePoAuthProc24m  may
be  called  more than once when authenticating a client, and
some state will have to be maintained between  each  invoca-
tion.	At  the start of each 4mProtocolSetup24m, *auth_state_ptr
is NULL, and the function should initialize  its  state	 and
set  this  pointer.   In subsequent invocations of the call-
back, the pointer should be used to get at any state  previ-
ously stored by the callback.

If needed, the network ID of the client accepting the 4mProto-0m
4mcolSetup24m can be obtained by calling the  4mIceConnectionString0m
function.

ICElib	will  be  responsible for freeing the reply_data_ret
and error_string_ret pointers with 4mfree24m.

The auth_data pointer may point to a volatile block of	mem-
ory.  If the data must be kept beyond this invocation of the
callback, be sure to make a copy of it.

The 4mIcePoAuthProc24m should return one of four values:

·    4mIcePoAuthHaveReply24m - a reply is available.

·    4mIcePoAuthRejected24m - authentication rejected.

·    4mIcePoAuthFailed24m - authentication failed.

·    4mIcePoAuthDoneCleanup24m - done cleaning up.

4mIcePaAuthProc24m is the callback invoked for	the  client  that
received the 4mProtocolSetup24m.
__
|













			   - 13 -





1mInter-Client Exchange Library		      X11, Release 6.40m


typedef IcePaAuthStatus (*IcePaAuthProc) ();

IcePaAuthStatus PaAuthProc(4mice_conn24m, 4mauth_state_ptr24m, 4mswap24m, 4mauth_datalen24m, 4mauth_data24m,
		    4mreply_datalen_ret24m, 4mreply_data_ret24m, 4merror_string_ret24m)
    IceConn 4mice_conn24m;
    IcePointer *4mauth_state_ptr24m;
    Bool 4mswap24m;
    int 4mauth_datalen24m;
    IcePointer 4mauth_data24m;
    int *4mreply_datalen_ret24m;
    IcePointer *4mreply_data_ret24m;
    char **4merror_string_ret24m;


4mice_conn24m  The ICE connection object.

4mauth_state_ptr0m
	  A  pointer  to state for use by the authentication
	  callback procedure.

4mswap24m      If 4mTrue24m, auth_data may have	 to  be	 byte  swapped
	  (depending on its contents).

4mauth_datalen0m
	  The  length  (in bytes) of the protocol originator
	  authentication data.

4mauth_data24m The authentication data from the protocol origina-
	  tor.

4mreply_datalen_ret0m
	  The length of the authentication data returned.

4mreply_data_ret0m
	  The authentication data returned.

4merror_string_ret0m
	  If  authentication  is rejected or fails, an error
	  string is returned.
|__


Authentication may require several phases, depending on	 the
authentication	method.	  As a result, the 4mIcePaAuthProc24m may
be called more than once when authenticating a	client,	 and
some  state  will have to be maintained between each invoca-
tion.  At the start of each 4mProtocolSetup24m,	 auth_datalen  is
zero,  *auth_state_ptr is NULL, and the function should ini-
tialize its state and set this pointer.	 In subsequent invo-
cations	 of  the callback, the pointer should be used to get
at any state previously stored by the callback.

If needed, the network ID of the client accepting the 4mProto-0m
4mcolSetup24m  can be obtained by calling the 4mIceConnectionString0m



			   - 14 -





1mInter-Client Exchange Library		      X11, Release 6.40m


function.

The auth_data pointer may point to a volatile block of	mem-
ory.  If the data must be kept beyond this invocation of the
callback, be sure to make a copy of it.

ICElib will be responsible for transmitting and freeing	 the
reply_data_ret and error_string_ret pointers with 4mfree24m.

The 4mIcePaAuthProc24m should return one of four values:

·    4mIcePaAuthContinue24m - continue (or start) authentication.

·    4mIcePaAuthAccepted24m - authentication accepted.

·    4mIcePaAuthRejected24m - authentication rejected.

·    4mIcePaAuthFailed24m - authentication failed.

1m7.  ICE Connections0m

In order for two clients to establish an ICE connection, one
client	has  to	 be  waiting  for connections, and the other
client has to initiate the connection.	 Most  clients	will
initiate connections, so we discuss that first.

1m7.1.	Opening an ICE Connection0m

To  open  an  ICE  connection  with another client (that is,
waiting for connections), use 4mIceOpenConnection24m.
__
|
IceConn IceOpenConnection(4mnetwork_ids_list24m, 4mcontext24m, 4mmust_authenticate24m, 4mmajor_opcode_check24m,
		    4merror_length24m, 4merror_string_ret24m)
     char *4mnetwork_ids_list24m;
     IcePointer 4mcontext24m;
     Bool 4mmust_authenticate24m;
     int 4mmajor_opcode_check24m;
     int  4merror_length24m;
     char *4merror_string_ret24m;


4mnetwork_ids_list0m
	  Specifies the network ID(s) of the other client.

4mcontext24m   A pointer to an opaque object or	 NULL.	 Used  to
	  determine  if an ICE connection can be shared (see
	  below).

4mmust_authenticate0m
	  If 4mTrue24m, the other client may not bypass authenti-
	  cation.





			   - 15 -





1mInter-Client Exchange Library		      X11, Release 6.40m


4mmajor_opcode_check0m
	  Used	to  force a new ICE connection to be created
	  (see below).

4merror_length0m
	  Length of the error_string_ret argument passed in.

4merror_string_ret0m
	  Returns  a  null-terminated error message, if any.
	  The error_string_ret argument points to user	sup-
	  plied memory.	 No more than error_length bytes are
	  used.
|__

4mIceOpenConnection24m returns an opaque ICE connection object if
it succeeds; otherwise, it returns NULL.

The network_ids_list argument contains a list of network IDs
separated by commas.  An attempt will be  made	to  use	 the
first  network	ID.   If that fails, an attempt will be made
using the second network ID, and so on.	 Each network ID has
the following format:

     tcp/<hostname>:<portnumber>    or
     decnet/<hostname>::<objname>   or
     local/<hostname>:<path>


Most protocol libraries will have some sort of open function
that should internally make a call  into  4mIceOpenConnection24m.
When  4mIceOpenConnection24m is called, it may be possible to use
a previously opened ICE connection (if the target client  is
the  same).   However,	there  are cases in which shared ICE
connections are not desired.

The context argument is used to determine if an ICE  connec-
tion  can be shared.  If context is NULL, then the caller is
always willing to share the connection.	 If context  is	 not
NULL,  then  the  caller  is not willing to use a previously
opened ICE connection that has a different non-NULL  context
associated with it.

In  addition, if major_opcode_check contains a nonzero major
opcode value, a previously created ICE	connection  will  be
used  only  if the major opcode is not active on the connec-
tion.  This can be used to force  multiple  ICE	 connections
between two clients for the same protocol.

Any  authentication  requirements  are handled internally by
the ICE library.  The method  by  which	 the  authentication
data is obtained is implementation-dependent.-
-----------
  - The	 X Consortium's ICElib implementation uses
an .ICEauthority file (see Appendix A).



			   - 16 -





1mInter-Client Exchange Library		      X11, Release 6.40m


After 4mIceOpenConnection24m is called, the client  is	ready  to
send  a	 4mProtocolSetup24m  (provided	that 4mIceRegisterForProto-0m
4mcolSetup24m was called) or receive  a	 4mProtocolSetup24m  (provided
that 4mIceRegisterForProtocolReply24m was called).

1m7.2.	Listening for ICE Connections0m

Clients	 wishing  to  accept ICE connections must first call
4mIceListenForConnections24m or	 4mIceListenForWellKnownConnections0m
so  that  they can listen for connections.  A list of opaque
"listen" objects are returned, one for each type  of  trans-
port  method  that  is	available (for example, Unix Domain,
TCP, DECnet, and so on).

Normally clients will let ICElib allocate an available	name
in  each transport and return listen objects.  Such a client
will then use 4mIceComposeNetworkIdList24m to extract the  chosen
names  and  make them available to other clients for opening
the connection.	 In certain cases it may be necessary for  a
client	to  listen for connections on pre-arranged transport
object names.  Such a client may use  4mIceListenForWellKnown-0m
4mConnections24m to specify the names for the listen objects.
__
|
Status IceListenForConnections(4mcount_ret24m, 4mlisten_objs_ret24m, 4merror_length24m, 4merror_string_ret24m)
     int  *4mcount_ret24m;
     IceListenObj **4mlisten_objs_ret24m;
     int  4merror_length24m;
     char *4merror_string_ret24m;


4mcount_ret24m Returns the number of listen objects created.

4mlisten_objs_ret0m
	  Returns  a  list  of	pointers  to  opaque  listen
	  objects.

4merror_length0m
	  The length of the error_string_ret argument passed
	  in.

4merror_string_ret0m
	  Returns  a  null-terminated error message, if any.
	  The error_string_ret points to user supplied	mem-
	  ory.	No more than error_length bytes are used.
|__

The  return  value  of	4mIceListenForConnections24m  is zero for
failure and a positive value for success.

__
|





			   - 17 -





1mInter-Client Exchange Library		      X11, Release 6.40m


Status IceListenForWellKnownConnections(4mport_id24m, 4mcount_ret24m, 4mlisten_objs_ret24m, 4merror_length24m, 4merror_string_ret24m)
     char *4mport_id24m;
     int  *4mcount_ret24m;
     IceListenObj **4mlisten_objs_ret24m;
     int  4merror_length24m;
     char *4merror_string_ret24m;


4mport_id24m   Specifies  the	port   identification	for   the
	  address(es) to be opened.  The value must not con-
	  tain the slash (``/'') or comma (``,'') character;
	  these are reserved for future use.

4mcount_ret24m Returns the number of listen objects created.

4mlisten_objs_ret0m
	  Returns  a  list  of	pointers  to  opaque  listen
	  objects.

4merror_length0m
	  The length of the error_string_ret argument passed
	  in.

4merror_string_ret0m
	  Returns  a  null-terminated error message, if any.
	  The error_string_ret points to user supplied	mem-
	  ory.	No more than error_length bytes are used.
|__

4mIceListenForWellKnownConnections24m  constructs  a list of net-
work IDs by prepending each known transport to	port_id	 and
then  attempts	to  create  listen  objects  for the result.
Port_id is the portnumber, objname, or path portion  of	 the
ICE  network ID. If a listen object for a particular network
ID cannot be created the network ID is ignored.	 If no	lis-
ten  objects  are  created  4mIceListenForWellKnownConnections0m
returns failure.

The return value of 4mIceListenForWellKnownConnections24m is zero
for failure and a positive value for success.


To close and free the listen objects, use 4mIceFreeListenObjs24m.

__
|
void IceFreeListenObjs(4mcount24m, 4mlisten_objs24m)
    int 4mcount24m;
    IceListenObj *4mlisten_objs24m;


4mcount24m     The number of listen objects.





			   - 18 -





1mInter-Client Exchange Library		      X11, Release 6.40m


4mlisten_objs0m
	  The listen objects.
|__


To detect a new connection on a listen object, use 4mselect24m on
the descriptor associated with the listen object.


To  obtain the descriptor, use 4mIceGetListenConnectionNumber24m.

__
|
int IceGetListenConnectionNumber(4mlisten_obj24m)
    IceListenObj 4mlisten_obj24m;


4mlisten_obj0m
	  The listen object.
|__


To obtain the network ID string	 associated  with  a  listen
object, use 4mIceGetListenConnectionString24m.
__
|
char *IceGetListenConnectionString(4mlisten_obj24m)
    IceListenObj 4mlisten_obj24m;


4mlisten_obj0m
	  The listen object.
|__


A network ID has the following format:

     tcp/<hostname>:<portnumber>    or
     decnet/<hostname>::<objname>   or
     local/<hostname>:<path>


To  compose  a string containing a list of network IDs sepa-
rated by commas (the  format  recognized  by  4mIceOpenConnec-0m
4mtion24m), use 4mIceComposeNetworkIdList24m.

__
|
char *IceComposeNetworkIdList(4mcount24m, 4mlisten_objs24m)
    int 4mcount24m;
    IceListenObj *4mlisten_objs24m;






			   - 19 -





1mInter-Client Exchange Library		      X11, Release 6.40m


4mcount24m     The number of listen objects.

4mlisten_objs0m
	  The listen objects.
|__


1m7.3.	Host Based Authentication for ICE Connections0m

If authentication fails when a client attempts	to  open  an
ICE  connection	 and  the initiating client has not required
authentication, a host based authentication procedure may be
invoked	 to provide a last chance for the client to connect.
Each listen object has such a callback associated  with	 it,
and  this  callback is set using the 4mIceSetHostBasedAuthProc0m
function.
__
|
void IceSetHostBasedAuthProc(4mlisten_obj24m, 4mhost_based_auth_proc24m)
    IceListenObj 4mlisten_obj24m;
    IceHostBasedAuthProc 4mhost_based_auth_proc24m;


4mlisten_obj0m
	  The listen object.

4mhost_based_auth_proc0m
	  The host based authentication procedure.
|__

By default, each listen object has no host based authentica-
tion   procedure  associated  with  it.	  Passing  NULL	 for
host_based_auth_proc turns off host based authentication  if
it was previously set.

__
|
typedef Bool (*IceHostBasedAuthProc) ();

Bool HostBasedAuthProc(4mhost_name24m)
    char *4mhost_name24m;


4mhost_name24m The  host name of the client that tried to open an
	  ICE connection.
|__

The host_name argument	is  a  string  in  the	form  4mproto-0m
4mcol24m/4mhostname24m, where 4mprotocol24m is one of {tcp, decnet, local}.

If  4mIceHostBasedAuthProc24m  returns	4mTrue24m,  access   will   be
granted,  even	though	the  original authentication failed.
Note that authentication can effectively be disabled by reg-
istering an 4mIceHostBasedAuthProc24m, which always returns 4mTrue24m.



			   - 20 -





1mInter-Client Exchange Library		      X11, Release 6.40m


Host based authentication is also allowed  at  4mProtocolSetup0m
time.  The callback is specified in the 4mIceRegisterForProto-0m
4mcolReply24m  function	 (see  section	6,  ``Protocol	Registra-
tion'').

1m7.4.	Accepting ICE Connections0m

After  a  connection  attempt is detected on a listen object
returned by 4mIceListenForConnections24m, you should call  4mIceAc-0m
4mceptConnection24m.   This  returns  a new opaque ICE connection
object.
__
|
IceConn IceAcceptConnection(4mlisten_obj24m, 4mstatus_ret24m)
    IceListenObj 4mlisten_obj24m;
    IceAcceptStatus *4mstatus_ret24m;


4mlisten_obj0m
	  The listen object on which a	new  connection	 was
	  detected.

4mstatus_ret0m
	  Return status information.
|__

The  status_ret argument is set to one of the following val-
ues:

·    4mIceAcceptSuccess24m - the accept operation succeeded,  and
     the function returns a new connection object.

·    4mIceAcceptFailure24m - the accept operation failed, and the
     function returns NULL.

·    4mIceAcceptBadMalloc24m - a memory	 allocation  failed,  and
     the function returns NULL.

In  general,  to  detect  new  connections,  you should call
4mselect24m on the file descriptors associated	with  the  listen
objects.   When a new connection is detected, the 4mIceAccept-0m
4mConnection24m function should be  called.   4mIceAcceptConnection0m
may  return a new ICE connection that is in a pending state.
This is because before	the  connection	 can  become  valid,
authentication	may  be	 necessary.  Because the ICE library
cannot block and wait for the  connection  to  become  valid
(infinite  blocking  can occur if the connecting client does
not act properly), the application must wait for the connec-
tion status to become valid.

The  following	pseudo-code demonstrates how connections are
accepted:





			   - 21 -





1mInter-Client Exchange Library		      X11, Release 6.40m


new_ice_conn = IceAcceptConnection (listen_obj, &accept_status);
if (accept_status != IceAcceptSuccess)
{
     close the file descriptor and return
}

status = IceConnectionStatus (new_ice_conn);
time_start = time_now;

while (status == IceConnectPending)
{
     select() on {new_ice_conn, all open connections}

     for (each ice_conn in the list of open connections)
	  if (data ready on ice_conn)
	  {
	       status = IceProcessMessages (ice_conn, NULL, NULL);
	       if (status == IceProcessMessagesIOError)
		    IceCloseConnection (ice_conn);
	  }

     if (data ready on new_ice_conn)
     {
	  /*
	   * IceProcessMessages is called until the connection
	   * is non-pending.  Doing so handles the connection
	   * setup request and any authentication requirements.
	   */

	  IceProcessMessages (new_ice_conn, NULL, NULL);
	  status = IceConnectionStatus (new_ice_conn);
     }
     else
     {
	  if (time_now - time_start > MAX_WAIT_TIME)
	       status = IceConnectRejected;
     }
}

if (status == IceConnectAccepted)
{
     Add new_ice_conn to the list of open connections
}
else
{
     IceCloseConnection (new_ice_conn);
}


After 4mIceAcceptConnection24m is called and the  connection  has
been  validated,  the  client  is  ready to receive a 4mProto-0m
4mcolSetup24m  (provided  that	4mIceRegisterForProtocolReply24m   was
called)	 or send a 4mProtocolSetup24m (provided that 4mIceRegister-0m
4mForProtocolSetup24m was called).



			   - 22 -





1mInter-Client Exchange Library		      X11, Release 6.40m


1m7.5.	Closing ICE Connections0m

To close an ICE connection created with 4mIceOpenConnection24m or
4mIceAcceptConnection24m, use 4mIceCloseConnection24m.
__
|
IceCloseStatus IceCloseConnection(4mice_conn24m)
    IceConn 4mice_conn24m;


4mice_conn24m  The ICE connection to close.
|__

To  actually  close  an ICE connection, the following condi-
tions must be met:

·    The 4mopen24m 4mreference24m 4mcount24m must have reached zero on this
     ICE  connection.	When 4mIceOpenConnection24m is called, it
     tries to use a previously opened ICE connection.  If it
     is	 able  to  use an existing connection, it increments
     the open reference count on the connection by one.	 So,
     to close an ICE connection, each call to 4mIceOpenConnec-0m
     4mtion24m must be matched with a call to 4mIceCloseConnection24m.
     The  connection  can be closed only on the last call to
     4mIceCloseConnection24m.

·    The 4mactive24m 4mprotocol24m 4mcount24m must have reached zero.  Each
     time  a  4mProtocolSetup24m  succeeds on the connection, the
     active protocol count is incremented by one.  When	 the
     client  no	 longer	 expects  to use the protocol on the
     connection, the 4mIceProtocolShutdown24m function should  be
     called,  which  decrements the active protocol count by
     one (see section 8, ``Protocol Setup and Shutdown'').

·    If shutdown negotiation is enabled on  the	 connection,
     the client on the other side of the ICE connection must
     agree to have the connection closed.

4mIceCloseConnection24m returns one of the following values:

·    4mIceClosedNow24m - the ICE connection was	 closed	 at  this
     time.   The  watch procedures were invoked and the con-
     nection was freed.

·    4mIceClosedASAP24m - an IO error had occurred on the connec-
     tion,  but	 4mIceCloseConnection24m is being called within a
     nested 4mIceProcessMessages24m.  The watch	 procedures  have
     been  invoked  at this time, but the connection will be
     freed as soon  as	possible  (when	 the  nesting  level
     reaches zero and 4mIceProcessMessages24m returns a status of
     4mIceProcessMessagesConnectionClosed24m).

·    4mIceConnectionInUse24m - the connection was not  closed  at
     this  time,  because  it  is being used by other active



			   - 23 -





1mInter-Client Exchange Library		      X11, Release 6.40m


     protocols.

·    4mIceStartedShutdownNegotiation24m - the connection was  not
     closed  at	 this  time and shutdown negotiation started
     with the client on the other side of  the	ICE  connec-
     tion.   When the connection is actually closed, 4mIcePro-0m
     4mcessMessages24m will return  a  status  of  4mIceProcessMes-0m
     4msagesConnectionClosed24m.


When  it  is  known that the client on the other side of the
ICE connection has terminated the connection without  initi-
ating  shutdown	 negotiation,  the 4mIceSetShutdownNegotiation0m
function should be called to turn off shutdown	negotiation.
This  will prevent 4mIceCloseConnection24m from writing to a bro-
ken connection.
__
|
void IceSetShutdownNegotiation(4mice_conn24m, 4mnegotiate24m)
    IceConn 4mice_conn24m;
    Bool 4mnegotiate24m;


4mice_conn24m  A valid ICE connection object.

4mnegotiate24m If 4mFalse24m, shutdown negotiating will be turned off.
|__


To  check  the shutdown negotiation status of an ICE connec-
tion, use 4mIceCheckShutdownNegotiation24m.
__
|
Bool IceCheckShutdownNegotiation(4mice_conn24m)
    IceConn 4mice_conn24m;


4mice_conn24m  A valid ICE connection object.
|__

4mIceCheckShutdownNegotiation24m returns 4mTrue24m if shutdown negoti-
ation  will  take  place  on  the  connection; otherwise, it
returns 4mFalse24m.  Negotiation is on by default for  a  connec-
tion.  It can only be changed with the 4mIceSetShutdownNegoti-0m
4mation24m function.

1m7.6.	Connection Watch Procedures0m

To add a watch procedure  that	will  be  called  each	time
ICElib	opens  a  new  connection  via	4mIceOpenConnection24m or
4mIceAcceptConnection24m or closes a connection via  4mIceCloseCon-0m






			   - 24 -





1mInter-Client Exchange Library		      X11, Release 6.40m


4mnection24m, use 4mIceAddConnectionWatch24m.
__
|
Status IceAddConnectionWatch(4mwatch_proc24m, 4mclient_data24m)
    IceWatchProc 4mwatch_proc24m;
    IcePointer 4mclient_data24m;


4mwatch_proc0m
	  The watch procedure to invoke when ICElib opens or
	  closes a connection.

4mclient_data0m
	  This pointer will be passed to  the  watch  proce-
	  dure.
|__

The  return value of 4mIceAddConnectionWatch24m is zero for fail-
ure, and a positive value for success.

Note that several calls to 4mIceOpenConnection24m might share the
same ICE connection.  In such a case, the watch procedure is
only invoked when the connection  is  first  created  (after
authentication	succeeds).   Similarly,	 because connections
might be shared, the watch procedure is called only if	4mIce-0m
4mCloseConnection24m actually closes the connection (right before
the IceConn is freed).

The watch procedures are very useful for  applications	that
need  to  add  a file descriptor to a select mask when a new
connection is created and remove the  file  descriptor	when
the   connection  is  destroyed.   Because  connections	 are
shared, knowing when to add and remove the  file  descriptor
from  the  select  mask would be difficult without the watch
procedures.

Multiple watch procedures may be  registered  with  the	 ICE
library.  No assumptions should be made about their order of
invocation.

If one or more ICE connections were already created  by	 the
ICE  library  at the time the watch procedure is registered,
the watch procedure will instantly be invoked  for  each  of
these  ICE  connections	 (with	the  opening argument set to
4mTrue24m).

The watch procedure is of type 4mIceWatchProc24m.
__
|








			   - 25 -





1mInter-Client Exchange Library		      X11, Release 6.40m


typedef void (*IceWatchProc)();

void WatchProc(4mice_conn24m, 4mclient_data24m, 4mopening24m, 4mwatch_data24m)
    IceConn 4mice_conn24m;
    IcePointer 4mclient_data24m;
    Bool 4mopening24m;
    IcePointer *4mwatch_data24m;


4mice_conn24m  The opened or closed ICE connection.  Call 4mIceCon-0m
	  4mnectionNumber24m  to  get the file descriptor associ-
	  ated with this connection.

4mclient_data0m
	  Client data specified in the call to 4mIceAddConnec-0m
	  4mtionWatch24m.

4mopening24m   If  4mTrue24m,  the  connection	is  being  opened.  If
	  4mFalse24m, the connection is being closed.

4mwatch_data0m
	  Can be used to save a pointer to client data.
|__

If opening is 4mTrue24m, the client should  set	 the  *watch_data
pointer to any data it may need to save until the connection
is closed and the watch	 procedure  is	invoked	 again	with
opening set to 4mFalse24m.


To remove a watch procedure, use 4mIceRemoveConnectionWatch24m.
__
|
void IceRemoveConnectionWatch(4mwatch_proc24m, 4mclient_data24m)
    IceWatchProc 4mwatch_proc24m;
    IcePointer 4mclient_data24m;



4mwatch_proc0m
	  The  watch procedure that was passed to 4mIceAddCon-0m
	  4mnectionWatch24m.

4mclient_data0m
	  The client_data pointer that was passed to 4mIceAdd-0m
	  4mConnectionWatch24m.
|__


1m8.  Protocol Setup and Shutdown0m

To  activate  a protocol on a given ICE connection, use 4mIce-0m
4mProtocolSetup24m.




			   - 26 -





1mInter-Client Exchange Library		      X11, Release 6.40m

__
|
IceProtocolSetupStatus IceProtocolSetup(4mice_conn24m, 4mmy_opcode24m, 4mclient_data24m, 4mmust_authenticate24m,
		    4mmajor_version_ret24m, 4mminor_version_ret24m, 4mvendor_ret24m, 4mrelease_ret24m, 4merror_length24m, 4merror_string_ret24m)
    IceConn 4mice_conn24m;
    int 4mmy_opcode24m;
    IcePointer 4mclient_data24m;
    Bool 4mmust_authenticate24m;
    int *4mmajor_version_ret24m;
    int *4mminor_version_ret24m;
    char **4mvendor_ret24m;
    char **4mrelease_ret24m;
    int 4merror_length24m;
    char *4merror_string_ret24m;


4mice_conn24m  A valid ICE connection object.

4mmy_opcode24m The major opcode of the protocol to be set up,  as
	  returned by 4mIceRegisterForProtocolSetup24m.

4mclient_data0m
	  The  client  data  stored  in this pointer will be
	  passed to the 4mIcePoProcessMsgProc24m callback.

4mmust_authenticate0m
	  If 4mTrue24m, the other client may not bypass authenti-
	  cation.

4mmajor_version_ret0m
	  The  major  version  of the protocol to be used is
	  returned.

4mminor_version_ret0m
	  The minor version of the protocol to	be  used  is
	  returned.

4mvendor_ret0m
	  The vendor string specified by the protocol accep-
	  tor.

4mrelease_ret0m
	  The  release	string	specified  by  the  protocol
	  acceptor.

4merror_length0m
	  Specifies the length of the error_string_ret argu-
	  ment passed in.

4merror_string_ret0m
	  Returns a null-terminated error message,  if	any.
	  The  error_string_ret argument points to user sup-
	  plied memory.	 No more than error_length bytes are
	  used.




			   - 27 -





1mInter-Client Exchange Library		      X11, Release 6.40m


|__

The  vendor_ret and release_ret strings should be freed with
4mfree24m when no longer needed.

4mIceProtocolSetup24m returns one of the following values:

·    4mIceProtocolSetupSuccess24m   -	the    major_version_ret,
     minor_version_ret, vendor_ret, release_ret are set.

·    4mIceProtocolSetupFailure24m  or  4mIceProtocolSetupIOError24m  -
     check  error_string_ret  for   failure   reason.	 The
     major_version_ret,	   minor_version_ret,	 vendor_ret,
     release_ret are not set.

·    4mIceProtocolAlreadyActive24m -  this  protocol  is  already
     active  on	 this  connection.   The  major_version_ret,
     minor_version_ret, vendor_ret, release_ret are not set.


To  notify  the	 ICE  library  when a given protocol will no
longer be used on an ICE  connection,  use  4mIceProtocolShut-0m
4mdown24m.

__
|
Status IceProtocolShutdown(4mice_conn24m, 4mmajor_opcode24m)
    IceConn 4mice_conn24m;
    int 4mmajor_opcode24m;


4mice_conn24m  A valid ICE connection object.

4mmajor_opcode0m
	  The major opcode of the protocol to shut down.
|__

The  return value of 4mIceProtocolShutdown24m is zero for failure
and a positive value for success.

Failure will occur if the major opcode was never  registered
OR  the	 protocol of the major opcode was never activated on
the connection.	 By activated, we mean that a  4mProtocolSetup0m
succeeded  on the connection.  Note that ICE does not define
how each sub-protocol triggers a protocol shutdown.

1m9.  Processing Messages0m

To process incoming messages on an ICE connection, use	4mIce-0m
4mProcessMessages24m.
__
|





			   - 28 -





1mInter-Client Exchange Library		      X11, Release 6.40m


IceProcessMessagesStatus IceProcessMessages(4mice_conn24m, 4mreply_wait24m, 4mreply_ready_ret24m)
    IceConn 4mice_conn24m;
    IceReplyWaitInfo *4mreply_wait24m;
    Bool *4mreply_ready_ret24m;


4mice_conn24m  A valid ICE connection object.

4mreply_wait0m
	  Indicates if a reply is being waited for.

4mreply_ready_ret0m
	  If set to 4mTrue24m on return, a reply is ready.
|__

4mIceProcessMessages24m is used in two ways:

·    In the first, a client may generate a message and block
     by calling 4mIceProcessMessages24m repeatedly until it  gets
     its reply.

·    In	 the  second, a client calls 4mIceProcessMessages24m with
     reply_wait set to NULL in response	 to  4mselect24m  showing
     that  there is data to read on the ICE connection.	 The
     ICE library may process zero or more complete messages.
     Note  that messages that are not blocked for are always
     processed by invoking callbacks.

4mIceReplyWaitInfo24m  contains	 the  major/minor   opcodes   and
sequence  number  of  the message for which a reply is being
awaited.  It also contains a pointer to the reply message to
be  filled  in	(the  protocol library should cast this 4mIce-0m
4mPointer24m to the appropriate reply type).  In most cases,  the
reply will have some fixed-size part, and the client waiting
for the reply will have provided a pointer to a structure to
hold  this  fixed-size	data.	If  there is variable-length
data, it would	be  expected  that  the	 4mIcePoProcessMsgProc0m
callback  will	have to allocate additional memory and store
pointer(s) to that memory in the fixed-size  structure.	  If
the  entire  data  is variable length (for example, a single
variable-length string), then the  client  waiting  for	 the
reply would probably just pass a pointer to fixed-size space
to hold a  pointer,  and  the  4mIcePoProcessMsgProc24m	 callback
would allocate the storage and store the pointer.  It is the
responsibility of the client receiving the reply to free  up
any memory allocated on its behalf.

__
|
typedef struct {
     unsigned long sequence_of_request;
     int major_opcode_of_request;
     int minor_opcode_of_request;
     IcePointer reply;



			   - 29 -





1mInter-Client Exchange Library		      X11, Release 6.40m


} IceReplyWaitInfo;

|__

If reply_wait is not NULL and 4mIceProcessMessages24m has a reply
or error to return in response to this reply_wait (that	 is,
no  callback  was generated), then the reply_ready_ret argu-
ment will be set to 4mTrue24m.

If reply_wait is NULL, then the caller may  also  pass	NULL
for  reply_ready_ret and be guaranteed that no value will be
stored in this pointer.

4mIceProcessMessages24m returns one of the following values:

·    4mIceProcessMessagesSuccess24m - no error occurred.

·    4mIceProcessMessagesIOError24m - an IO error  occurred,  and
     the  caller  must	explicitly  close  the connection by
     calling 4mIceCloseConnection24m.

·    4mIceProcessMessagesConnectionClosed24m - the ICE connection
     has been closed (closing of the connection was deferred
     because of shutdown negotiation, or because the 4mIcePro-0m
     4mcessMessages24m	nesting	 level	was  not  zero).   Do not
     attempt to access the ICE	connection  at	this  point,
     since it has been freed.

1m10.  Ping0m

To  send  a ``Ping'' message to the client on the other side
of the ICE connection, use 4mIcePing24m.
__
|
Status IcePing(4mice_conn24m, 4mping_reply_proc24m, 4mclient_data24m)
    IceConn 4mice_conn24m;
    IcePingReplyProc 4mping_reply_proc24m;
    IcePointer 4mclient_data24m;


4mice_conn24m  A valid ICE connection object.

4mping_reply_proc0m
	  The  callback	 to  invoke  when  the	Ping   reply
	  arrives.

4mclient_data0m
	  This	pointer	 will  be  passed  to the 4mIcePingRe-0m
	  4mplyProc24m callback.
|__

4mIcePing24m returns zero for failure and a  positive  value  for
success.




			   - 30 -





1mInter-Client Exchange Library		      X11, Release 6.40m


When  4mIceProcessMessages24m  processes  the Ping reply, it will
invoke the 4mIcePingReplyProc24m callback.
__
|
typedef void (*IcePingReplyProc)();

void PingReplyProc(4mice_conn24m, 4mclient_data24m)
    IceConn 4mice_conn24m;
    IcePointer 4mclient_data24m;


4mice_conn24m  The ICE connection object.

4mclient_data0m
	  The client data specified in the call to  4mIcePing24m.
|__


1m11.  Using ICElib Informational Functions0m

__
|
IceConnectStatus IceConnectionStatus(4mice_conn24m)
    IceConn 4mice_conn24m;
|__

4mIceConnectionStatus24m returns the status of an ICE connection.
The possible return values are:

·    4mIceConnectPending24m - the connection  is  not  valid  yet
     (that  is,	 authentication	 is  taking place).  This is
     only relevant to connections created  by  4mIceAcceptCon-0m
     4mnection24m.

·    4mIceConnectAccepted24m  - the connection has been accepted.
     This is only relevant to connections created by  4mIceAc-0m
     4mceptConnection24m.

·    4mIceConnectRejected24m  -	 the connection had been rejected
     (that is, authentication failed).	This is	 only  rele-
     vant to connections created by 4mIceAcceptConnection24m.

·    4mIceConnectIOError24m  -	an  IO	error has occurred on the
     connection.

__
|
char *IceVendor(4mice_conn24m)
    IceConn 4mice_conn24m;
|__

4mIceVendor24m returns the ICE library vendor identification  for
the  other  side  of  the  connection.	The string should be
freed with a call to 4mfree24m when no longer needed.



			   - 31 -





1mInter-Client Exchange Library		      X11, Release 6.40m

__
|
char *IceRelease(4mice_conn24m)
    IceConn 4mice_conn24m;
|__

4mIceRelease24m returns the release  identification  of	 the  ICE
library	 on  the  other	 side of the connection.  The string
should be freed with a call to 4mfree24m when no longer needed.

__
|
int IceProtocolVersion(4mice_conn24m)
    IceConn 4mice_conn24m;
|__

4mIceProtocolVersion24m returns the major version of the ICE pro-
tocol on this connection.

__
|
int IceProtocolRevision(4mice_conn24m)
    IceConn 4mice_conn24m;
|__

4mIceProtocolRevision24m  returns  the	minor  version of the ICE
protocol on this connection.

__
|
int IceConnectionNumber(4mice_conn24m)
    IceConn 4mice_conn24m;
|__

4mIceConnectionNumber24m returns the file descriptor of this  ICE
connection.

__
|
char *IceConnectionString(4mice_conn24m)
    IceConn 4mice_conn24m;
|__

4mIceConnectionString24m  returns  the	network	 ID of the client
that accepted this connection.	The string should  be  freed
with a call to 4mfree24m when no longer needed.

__
|
unsigned long IceLastSentSequenceNumber(4mice_conn24m)
    IceConn 4mice_conn24m;
|__

4mIceLastSentSequenceNumber24m returns the sequence number of the
last message sent on this ICE connection.



			   - 32 -





1mInter-Client Exchange Library		      X11, Release 6.40m

__
|
unsigned long IceLastReceivedSequenceNumber(4mice_conn24m)
    IceConn 4mice_conn24m;
|__

4mIceLastReceivedSequenceNumber24m returns the sequence number of
the last message received on this ICE connection.

__
|
Bool IceSwapping(4mice_conn24m)
    IceConn 4mice_conn24m;
|__

4mIceSwapping24m  returns 4mTrue24m if byte swapping is necessary when
reading messages on the ICE connection.

__
|
IcePointer IceGetContext(4mice_conn24m)
    IceConn 4mice_conn24m;
|__

4mIceGetContext24m returns the context associated with a  connec-
tion created by 4mIceOpenConnection24m.

1m12.  ICE Messages0m

All  ICE messages have a standard 8-byte header.  The ICElib
macros that read and write messages rely  on  the  following
naming convention for message headers:


     CARD8major_opcode;
     CARD8minor_opcode;
     CARD8data[2];
     CARD32length B32;


The  3rd  and 4th bytes of the message header can be used as
needed.	 The length field is specified in units of 8  bytes.

1m12.1.	 Sending ICE Messages0m

The ICE library maintains an output buffer used for generat-
ing messages.  Protocol libraries layered on top of ICE	 may
choose	to  batch  messages  together  and  flush the output
buffer at appropriate times.

If an IO error has occurred on an ICE connection, all  write
operations  will  be  ignored.	For further information, see
section 13, ``Error Handling.''





			   - 33 -





1mInter-Client Exchange Library		      X11, Release 6.40m


To get the size of the ICE output buffer, use  4mIceGetOutBuf-0m
4mSize24m.
__
|
int IceGetOutBufSize(4mice_conn24m)
     IceConn 4mice_conn24m;


4mice_conn24m  A valid ICE connection object.
|__


To flush the ICE output buffer, use 4mIceFlush24m.
__
|
IceFlush(4mice_conn24m)
     IceConn 4mice_conn24m;


4mice_conn24m  A valid ICE connection object.
|__

Note  that  the	 output	 buffer may be implicitly flushed if
there is insufficient space to generate a message.

The following macros can be used to generate ICE messages:

__
|
IceGetHeader(4mice_conn24m, 4mmajor_opcode24m, 4mminor_opcode24m, 4mheader_size24m, 4m<C_data_type>24m, 4mpmsg24m)
     IceConn 4mice_conn24m;
     int 4mmajor_opcode24m;
     int 4mminor_opcode24m;
     int 4mheader_size24m;
     <C_data_type> *4mpmsg24m;


4mice_conn24m  A valid ICE connection object.

4mmajor_opcode0m
	  The major opcode of the message.

4mminor_opcode0m
	  The minor opcode of the message.

4mheader_size0m
	  The size of the message header (in bytes).

4m<C_data_type>0m
	  The actual C data type of the message header.

4mpmsg24m      The message header pointer.  After this	macro  is
	  called,  the library can store data in the message
	  header.



			   - 34 -





1mInter-Client Exchange Library		      X11, Release 6.40m


|__

4mIceGetHeader24m is used to set up a message header  on  an  ICE
connection.  It sets the major and minor opcodes of the mes-
sage, and initializes the message's length to the length  of
the header.  If additional variable length data follows, the
message's length field should be updated.


__
|
IceGetHeaderExtra(4mice_conn24m, 4mmajor_opcode24m, 4mminor_opcode24m, 4mheader_size24m, 4mextra24m, 4m<C_data_type>24m, 4mpmsg24m, 4mpdata24m)
     IceConn 4mice_conn24m;
     int 4mmajor_opcode24m;
     int 4mminor_opcode24m;
     int 4mheader_size24m;
     int 4mextra24m;
     <C_data_type> *4mpmsg24m;
     char *4mpdata24m;


4mice_conn24m  A valid ICE connection object.

4mmajor_opcode0m
	  The major opcode of the message.

4mminor_opcode0m
	  The minor opcode of the message.

4mheader_size0m
	  The size of the message header (in bytes).

4mextra24m     The size of the extra data beyond the  header  (in
	  8-byte units).

4m<C_data_type>0m
	  The actual C data type of the message header.

4mpmsg24m      The  message  header pointer.  After this macro is
	  called, the library can store data in the  message
	  header.

4mpdata24m     Returns	a  pointer  to the ICE output buffer that
	  points immediately after the message header.	 The
	  variable  length  data  should be stored here.  If
	  there was  not  enough  room	in  the	 ICE  output
	  buffer, pdata is set to NULL.
|__

4mIceGetHeaderExtra24m is used to generate a message with a fixed
(and relatively small) amount of variable length data.	 The
complete message must fit in the ICE output buffer.





			   - 35 -





1mInter-Client Exchange Library		      X11, Release 6.40m

__
|
IceSimpleMessage(4mice_conn24m, 4mmajor_opcode24m, 4mminor_opcode24m)
     IceConn 4mice_conn24m;
     int 4mmajor_opcode24m;
     int 4mminor_opcode24m;


4mice_conn24m  A valid ICE connection object.

4mmajor_opcode0m
	  The major opcode of the message.

4mminor_opcode0m
	  The minor opcode of the message.
|__

4mIceSimpleMessage24m is used to generate a message that is iden-
tical in size to the ICE header message, and  has  no  addi-
tional data.


__
|
IceErrorHeader(4mice_conn24m, 4moffending_major_opcode24m, 4moffending_minor_opcode24m, 4moffending_sequence_num24m,
		    4mseverity24m, 4merror_class24m, 4mdata_length24m)
     IceConn 4mice_conn24m;
     int 4moffending_major_opcode24m;
     int 4moffending_minor_opcode24m;
     int 4moffending_sequence_num24m;
     int 4mseverity24m;
     int 4merror_class24m;
     int 4mdata_length24m;


4mice_conn24m  A valid ICE connection object.

4moffending_major_opcode0m
	  The major opcode of the protocol in which an error
	  was detected.

4moffending_minor_opcode0m
	  The minor opcode of the protocol in which an error
	  was detected.

4moffending_sequence_num0m
	  The sequence number of the message that caused the
	  error.

4mseverity24m  4mIceCanContinue24m, 4mIceFatalToProtocol24m, or 4mIceFatalTo-0m
	  4mConnection24m.

4merror_class0m
	  The error class.




			   - 36 -





1mInter-Client Exchange Library		      X11, Release 6.40m


4mdata_length0m
	  Length  of  data  (in	 8-byte units) to be written
	  after the header.
|__

4mIceErrorHeader24m sets up an error message header.

Note that the two clients connected by ICE may be using dif-
ferent	major  opcodes	for  a	given protocol.	 The offend-
ing_major_opcode passed to this macro is the major opcode of
the protocol for the client sending the error message.

Generic	 errors,  which	 are  common  to all protocols, have
classes in the range 0x8000..0xFFFF.  See  the	4mInter-Client0m
4mExchange24m 4mProtocol24m standard for more details.

4mIceBadMi-24m	  0x8000
4mnor0m
4mIceBad-24m	  0x8001
4mState0m
4mIce-24m	  0x8002
4mBadLength0m
4mIceBad-24m	  0x8003
4mValue0m


Per-protocol errors have classes in the range 0x0000-0x7fff.


To write data to an ICE	 connection,  use  the	4mIceWriteData0m
macro.	 If  the data fits into the ICE output buffer, it is
copied there.  Otherwise, the ICE output buffer	 is  flushed
and the data is directly sent.

This  macro  is	 used  in  conjunction with 4mIceGetHeader24m and
4mIceErrorHeader24m.


__
|
IceWriteData(4mice_conn24m, 4mbytes24m, 4mdata24m)
     IceConn 4mice_conn24m;
     int 4mbytes24m;
     char *4mdata24m;


4mice_conn24m  A valid ICE connection object.

4mbytes24m     The number of bytes to write.

4mdata24m      The data to write.
|__





			   - 37 -





1mInter-Client Exchange Library		      X11, Release 6.40m


To write data as 16-bit quantities, use 4mIceWriteData1624m.
__
|
IceWriteData16(4mice_conn24m, 4mbytes24m, 4mdata24m)
     IceConn 4mice_conn24m;
     int 4mbytes24m;
     short *4mdata24m;


4mice_conn24m  A valid ICE connection object.

4mbytes24m     The number of bytes to write.

4mdata24m      The data to write.
|__


To write data as 32-bit quantities, use 4mIceWriteData3224m.
__
|
IceWriteData32(4mice_conn24m, 4mbytes24m, 4mdata24m)
     IceConn 4mice_conn24m;
     int 4mbytes24m;
     long *4mdata24m;


4mice_conn24m  A valid ICE connection object.

4mbytes24m     The number of bytes to write.

4mdata24m      The data to write.
|__


To bypass copying data to the ICE output  buffer,  use	4mIce-0m
4mSendData24m  to directly send data over the network connection.
If necessary, the ICE output buffer is first flushed.
__
|
IceSendData(4mice_conn24m, 4mbytes24m, 4m(char24m 4m*)24m 4mdata24m)
     IceConn 4mice_conn24m;
     int 4mbytes24m;
     char *4mdata24m;


4mice_conn24m  A valid ICE connection object.

4mbytes24m     The number of bytes to send.

4mdata24m      The data to send.
|__


To force 32-bit or 64-bit  alignment,  use  4mIceWritePad24m.	A



			   - 38 -





1mInter-Client Exchange Library		      X11, Release 6.40m


maximum of 7 pad bytes can be specified.
__
|
IceWritePad(4mice_conn24m, 4mbytes24m)
     IceConn 4mice_conn24m;
     int 4mbytes24m;


4mice_conn24m  A valid ICE connection object.

4mbytes24m     The number of pad bytes.
|__


1m12.2.	 Reading ICE Messages0m

The  ICE  library maintains an input buffer used for reading
messages.  If the ICE library chooses to perform nonblocking
reads  (this  is  implementation-dependent),  then for every
read operation that it makes, zero or more complete messages
may  be read into the input buffer.  As a result, for all of
the macros described in this section that read messages,  an
actual	read  operation will occur on the connection only if
the data is not already present in the input buffer.


To get the size of the ICE input  buffer,  use	4mIceGetInBuf-0m
4mSize24m.
__
|
int IceGetInBufSize(4mice_conn24m)
     IceConn 4mice_conn24m;


4mice_conn24m  A valid ICE connection object.
|__


When  reading  messages,  care must be taken to check for IO
errors.	 If any IO error occurs in reading  any	 part  of  a
message,  the message should be thrown out.  After using any
of the macros described below for reading messages, the 4mIce-0m
4mValidIO24m  macro  can be used to check if an IO error occurred
on the connection.  After an IO error has occurred on an ICE
connection,  all  read operations will be ignored.  For fur-
ther information, see section 13, ``Error Handling.''


__
|
Bool IceValidIO(4mice_conn24m)
    IceConn 4mice_conn24m;





			   - 39 -





1mInter-Client Exchange Library		      X11, Release 6.40m


|__


The following macros can be used to read ICE messages.
__
|
IceReadSimpleMessage(4mice_conn24m, 4m<C_data_type>24m, 4mpmsg24m)
     IceConn 4mice_conn24m;
     <C_data_type> *4mpmsg24m;


4mice_conn24m  A valid ICE connection object.

4m<C_data_type>0m
	  The actual C data type of the message header.

4mpmsg24m      This pointer is set to the message header.
|__

4mIceReadSimpleMessage24m is used for messages that are identical
in  size to the 8-byte ICE header, but use the spare 2 bytes
in the header to encode additional data.  Note that the	 ICE
library	 always	 reads	in  these  first  8 bytes, so it can
obtain the major opcode of the	message.   4mIceReadSimpleMes-0m
4msage24m  simply returns a pointer to these 8 bytes; it does not
actually read any data into the input buffer.

For a message with variable length data, there are two	ways
of  reading  the  message.   One method involves reading the
complete message in one pass  using  4mIceReadCompleteMessage24m.
The  second method involves reading the message header (note
that this may be larger than the 8-byte	 ICE  header),	then
reading	 the variable length data in chunks (see 4mIceReadMes-0m
4msageHeader24m and 4mIceReadData24m).


__
|
IceReadCompleteMessage(4mice_conn24m, 4mheader_size24m, 4m<C_data_type>24m, 4mpmsg24m, 4mpdata24m)
     IceConn 4mice_conn24m;
     int 4mheader_size24m;
     <C_data_type> *4mpmsg24m;
     char *4mpdata24m;


4mice_conn24m  A valid ICE connection object.

4mheader_size0m
	  The size of the message header (in bytes).

4m<C_data_type>0m
	  The actual C data type of the message header.





			   - 40 -





1mInter-Client Exchange Library		      X11, Release 6.40m


4mpmsg24m      This pointer is set to the message header.

4mpdata24m     This pointer is set to the variable length data of
	  the message.
|__

If  the	 ICE  input buffer has sufficient space, 4mIceReadCom-0m
4mpleteMessage24m will read the complete  message  into	 the  ICE
input buffer.  Otherwise, a buffer will be allocated to hold
the variable length data.  After the call, the	pdata  argu-
ment  should be checked against NULL to make sure that there
was sufficient memory to allocate the buffer.


After calling 4mIceReadCompleteMessage24m and processing the mes-
sage, 4mIceDisposeCompleteMessage24m should be called.

__
|
IceDisposeCompleteMessage(4mice_conn24m, 4mpdata24m)
     IceConn 4mice_conn24m;
     char *4mpdata24m;


4mice_conn24m  A valid ICE connection object.

4mpdata24m     The  pointer  to the variable length data returned
	  in 4mIceReadCompleteMessage24m.
|__

If a buffer had to be allocated to hold the variable  length
data (because it did not fit in the ICE input buffer), it is
freed here by ICElib.


__
|
IceReadMessageHeader(4mice_conn24m, 4mheader_size24m, 4m<C_data_type>24m, 4mpmsg24m)
     IceConn 4mice_conn24m;
     int 4mheader_size24m;
     <C_data_type> *4mpmsg24m;


4mice_conn24m  A valid ICE connection object.

4mheader_size0m
	  The size of the message header (in bytes).

4m<C_data_type>0m
	  The actual C data type of the message header.

4mpmsg24m      This pointer is set to the message header.





			   - 41 -





1mInter-Client Exchange Library		      X11, Release 6.40m


|__

4mIceReadMessageHeader24m reads just  the  message  header.   The
rest  of the data should be read with the 4mIceReadData24m family
of macros.  This method of reading a message should be	used
when the variable length data must be read in chunks.


To  read  data	directly  into	a  user supplied buffer, use
4mIceReadData24m.
__
|
IceReadData(4mice_conn24m, 4mbytes24m, 4mpdata24m)
     IceConn 4mice_conn24m;
     int 4mbytes24m;
     char *4mpdata24m;


4mice_conn24m  A valid ICE connection object.

4mbytes24m     The number of bytes to read.

4mpdata24m     The data is read into this user supplied buffer.
|__


To read data as 16-bit quantities, use 4mIceReadData1624m.
__
|
IceReadData16(4mice_conn24m, 4mswap24m, 4mbytes24m, 4mpdata24m)
     IceConn 4mice_conn24m;
     Bool 4mswap24m;
     int 4mbytes24m;
     short *4mpdata24m;


4mice_conn24m  A valid ICE connection object.

4mswap24m      If 4mTrue,24m the values will be byte swapped.

4mbytes24m     The number of bytes to read.

4mpdata24m     The data is read into this user supplied buffer.
|__


To read data as 32-bit quantities, use 4mIceReadData3224m.
__
|








			   - 42 -





1mInter-Client Exchange Library		      X11, Release 6.40m


IceReadData32(4mice_conn24m, 4mswap24m, 4mbytes24m, 4mpdata24m)
     IceConn 4mice_conn24m;
     Bool 4mswap24m;
     int 4mbytes24m;
     long *4mpdata24m;


4mice_conn24m  A valid ICE connection object.

4mswap24m      If 4mTrue,24m the values will be byte swapped.

4mbytes24m     The number of bytes to read.

4mpdata24m     The data is read into this user supplied buffer.
|__


To force 32-bit or 64-bit alignment, use 4mIceReadPad24m.  A max-
imum of 7 pad bytes can be specified.
__
|
IceReadPad(4mice_conn24m, 4mbytes24m)
     IceConn 4mice_conn24m;
     int 4mbytes24m;


4mice_conn24m  A valid ICE connection object.

4mbytes24m     The number of pad bytes.
|__


1m13.  Error Handling0m

There are two default error handlers in ICElib:

·    One  to handle typically fatal conditions (for example,
     a connection dying because a machine crashed)

·    One to handle ICE-specific protocol errors

These error handlers can be changed  to	 user-supplied	rou-
tines  if  you	prefer	your  own  error handling and can be
changed as often as you like.


To set the ICE error handler, use 4mIceSetErrorHandler24m.
__
|
IceErrorHandler IceSetErrorHandler(4mhandler24m)
    IceErrorHandler 4mhandler24m;






			   - 43 -





1mInter-Client Exchange Library		      X11, Release 6.40m


4mhandler24m   The ICE error handler.  You should  pass	 NULL  to
	  restore the default handler.
|__

4mIceSetErrorHandler24m returns the previous error handler.

The ICE error handler is invoked when an unexpected ICE pro-
tocol error (major opcode 0) is encountered.  The action  of
the  default  handler  is to print an explanatory message to
4mstderr24m and if the	severity  is  fatal,  call  4mexit24m  with  a
nonzero	 value.	  If exiting is undesirable, the application
should register its own error handler.

Note that errors in other protocol domains should be handled
by  their  respective libraries (these libraries should have
their own error handlers).

An ICE error handler has the type of 4mIceErrorHandler24m.
__
|
typedef void (*IceErrorHandler)();

void ErrorHandler(4mice_conn24m, 4mswap24m, 4moffending_minor_opcode24m, 4moffending_sequence_num24m, 4merror_class24m,
		     4mseverity24m, 4mvalues24m)
    IceConn 4mice_conn24m;
    Bool 4mswap24m;
    int 4moffending_minor_opcode24m;
    unsigned long 4moffending_sequence_num24m;
    int 4merror_class24m;
    int 4mseverity24m;
    IcePointer 4mvalues24m;


4mice_conn24m  The ICE connection object.

4mswap24m      A flag that indicates  if  the  values  need  byte
	  swapping.

4moffending_minor_opcode0m
	  The ICE minor opcode of the offending message.

4moffending_sequence_num0m
	  The sequence number of the offending message.

4merror_class0m
	  The error class of the offending message.

4mseverity24m  4mIceCanContinue24m, 4mIceFatalToProtocol24m, or 4mIceFatalTo-0m
	  4mConnection24m.

4mvalues24m    Any additional error values specific to the  minor
	  opcode and class.





			   - 44 -





1mInter-Client Exchange Library		      X11, Release 6.40m


|__

The following error classes are defined at the ICE level:


4mIceBadMinor0m
4mIceBadState0m
4mIceBadLength0m
4mIceBadValue0m
4mIceBadMajor0m
4mIceNoAuth0m
4mIceNoVersion0m
4mIceSetupFailed0m
4mIceAuthRejected0m
4mIceAuthFailed0m
4mIceProtocolDuplicate0m
4mIceMajorOpcodeDuplicate0m
4mIceUnknownProtocol0m


For  further information, see the 4mInter-Client24m 4mExchange24m 4mPro-0m
4mtocol24m standard.


To handle fatal I/O errors, use 4mIceSetIOErrorHandler24m.

__
|
IceIOErrorHandler IceSetIOErrorHandler(4mhandler24m)
    IceIOErrorHandler 4mhandler24m;


4mhandler24m   The I/O error handler.  You should  pass	 NULL  to
	  restore the default handler.
|__

4mIceSetIOErrorHandler24m  returns the previous IO error handler.

An ICE I/O error handler has the type of  4mIceIOErrorHandler24m.

__
|
typedef void (*IceIOErrorHandler)();

void IOErrorHandler(4mice_conn24m)
    IceConn 4mice_conn24m;


4mice_conn24m  The ICE connection object.
|__

There are two ways of handling IO errors in ICElib:





			   - 45 -





1mInter-Client Exchange Library		      X11, Release 6.40m


·    In	 the  first,  the  IO error handler does whatever is
     necessary to respond to the IO error and then  returns,
     but  it does not call 4mIceCloseConnection24m.  The ICE con-
     nection is given a ``bad IO'' status,  and	 all  future
     reads  and	 writes	 to the connection are ignored.	 The
     next time 4mIceProcessMessages24m is called it will return a
     status of 4mIceProcessMessagesIOError24m.	At that time, the
     application should call 4mIceCloseConnection24m.

·    In the second, the IO  error  handler  does  call	4mIce-0m
     4mCloseConnection24m,  and then uses the 4mlongjmp24m call to get
     back to the application's main event loop.	 The  4msetjmp0m
     and  4mlongjmp24m	calls  may not work properly on all plat-
     forms, and special care must be taken to  avoid  memory
     leaks.  Therefore, this second model is less desirable.

Before the application I/O error handler is invoked,  proto-
col  libraries that were interested in being notified of I/O
errors will  have  their  4mIceIOErrorProc24m  handlers	 invoked.
This  handler  is  set up in the protocol registration func-
tions (see 4mIceRegisterForProtocolSetup24m  and  4mIceRegisterFor-0m
4mProtocolReply24m)  and could be used to clean up state specific
to the protocol.


__
|  typedef void (*IceIOErrorProc)();


void IOErrorProc(4mice_conn24m)
    IceConn 4mice_conn24m;


4mice_conn24m  The ICE connection object.
|__

Note that every 4mIceIOErrorProc24m callback must  return.   This
is required because each active protocol must be notified of
the broken connection, and the application IO error  handler
must be invoked afterwards.

1m14.  Multi-Threading Support0m

To  declare  that multiple threads in an application will be
using the ICE library, use 4mIceInitThreads24m.

__
|
Status IceInitThreads()

|__

The 4mIceInitThreads24m function must be the first  ICElib  func-
tion  a	 multi-threaded	 program  calls.   It  must complete



			   - 46 -





1mInter-Client Exchange Library		      X11, Release 6.40m


before	any  other  ICElib  call  is  made.   4mIceInitThreads0m
returns	 a nonzero status if and only if it was able to ini-
tialize the threads package successfully.   It	is  safe  to
call  4mIceInitThreads24m  more	 than  once, although the threads
package will only be initialized once.

Protocol libraries layered on top of  ICElib  will  have  to
lock critical sections of code that access an ICE connection
(for example, when generating messages).  Two  calls,  which
are generally implemented as macros, are provided:
__
|
IceLockConn(4mice_conn24m)
    IceConn 4mice_conn24m;

IceUnlockConn(4mice_conn24m)
    IceConn 4mice_conn24m;


4mice_conn24m  The ICE connection.
|__


To  keep  an  ICE  connection  locked  across several ICElib
calls, applications use 4mIceAppLockConn24m and 4mIceAppUnlockConn24m.
__
|
void IceAppLockConn(4mice_conn24m)
    IceConn 4mice_conn24m;


4mice_conn24m  The ICE connection to lock.
|__

The  4mIceAppLockConn24m  function  completely	locks  out  other
threads	 using	the  connection	 until	4mIceAppUnlockConn24m  is
called.	 Other threads attempting to use ICElib calls on the
connection will block.	If the program	has  not  previously
called 4mIceInitThreads24m, 4mIceAppLockConn24m has no effect.

__
|
void IceAppUnlockConn(4mice_conn24m)
    IceConn 4mice_conn24m;


4mice_conn24m  The ICE connection to unlock.
|__

The  4mIceAppUnlockConn24m  function allows other threads to com-
plete ICElib calls on the connection that were blocked by  a
previous  call	to  4mIceAppLockConn24m from this thread.  If the
program has not previously called 4mIceInitThreads24m,	4mIceAppUn-0m
4mlockConn24m has no effect.



			   - 47 -





1mInter-Client Exchange Library		      X11, Release 6.40m


1m15.  Miscellaneous Functions0m

To allocate scratch space (for example, when generating mes-
sages with variable data), use	4mIceAllocScratch24m.	Each  ICE
connection  has	 one  scratch space associated with it.	 The
scratch space starts off as empty and grows as needed.	 The
contents  of  the scratch space is not guaranteed to be pre-
served after any ICElib function is called.

__
|
char *IceAllocScratch(4mice_conn24m, 4msize24m)
    IceConn 4mice_conn24m;
    unsigned long 4msize24m;


4mice_conn24m  A valid ICE connection object.

4msize24m      The number of bytes required.
|__

Note that the memory returned by 4mIceAllocScratch24m should  not
be  freed by the caller.  The ICE library will free the mem-
ory when the ICE connection is closed.

1m16.  Acknowledgements0m

Thanks to Bob Scheifler for  his  thoughtful  input  on	 the
design	of  the	 ICE  library.	Thanks also to Jordan Brown,
Larry Cable, Donna Converse, Clive Feather, Stephen  Gildea,
Vania Joloboff, Kaleb Keithley, Stuart Marks, Hiro Miyamoto,
Ralph Swick, Jim VanGilder, and Mike Wexler.

























			   - 48 -





1mInter-Client Exchange Library		      X11, Release 6.40m


			 1mAppendix A0m

	      1mAuthentication Utility Functions0m


As discussed in this document, the means by which  authenti-
cation	data is obtained by the ICE library (for 4mConnection-0m
4mSetup24m messages or 4mProtocolSetup24m messages) is implementation-
dependent.-

This appendix describes some utility functions that  manipu-
late  an ICE authority file.  The authority file can be used
to pass authentication data between clients.

The basic operations on the .ICEauthority file are:

·    Get file name

·    Lock

·    Unlock

·    Read entry

·    Write entry

·    Search for entry

These are fairly low-level operations, and  it	is  expected
that  a program, like "iceauth", would exist to add, remove,
and display entries in the file.

In order to use these utility functions, the  <4mX11/ICE/ICEu-0m
4mtil.h24m> header file must be included.

An entry in the .ICEauthority file is defined by the follow-
ing data structure:

__
|
typedef struct {
     char *protocol_name;
     unsigned short protocol_data_length;
     char *protocol_data;
     char *network_id;
     char *auth_name;
     unsigned short auth_data_length;
     char *auth_data;
} IceAuthFileEntry;


-----------
  - The	  X   Consortium's  ICElib  implementation
assumes the presence of an ICE authority file.



			   - 49 -





1mInter-Client Exchange Library		      X11, Release 6.40m


|__

The protocol_name member is either  ``ICE''  for  connection
setup  authentication  or  the	subprotocol  name,  such  as
``XSMP''.  For each entry, protocol  specific  data  can  be
specified  in the protocol_data member.	 This can be used to
search for old entries that need  to  be  removed  from	 the
file.

The  network_id	 member	 is  the  network  ID  of the client
accepting authentication (for example, the network ID  of  a
session manager).  A network ID has the following form:

     tcp/<hostname>:<portnumber>    or
     decnet/<hostname>::<objname>   or
     local/<hostname>:<path>


The  auth_name	member	is  the	 name  of the authentication
method.	 The auth_data member is the  actual  authentication
data, and the auth_data_length member is the number of bytes
in the data.


To obtain the default authorization file name, use  4mIceAuth-0m
4mFileName24m.
__
|
char *IceAuthFileName()

|__

If  the ICEAUTHORITY environment variable if set, this value
is returned.  Otherwise, the default authorization file name
is  $HOME/.ICEauthority.   This name is statically allocated
and should not be freed.

To synchronously update the  authorization  file,  the	file
must  be  locked with a call to 4mIceLockAuthFile24m.  This func-
tion takes advantage of the fact that the 4mlink24m  system  call
will fail if the name of the new link already exists.
__
|
int IceLockAuthFile(4mfile_name24m, 4mretries24m, 4mtimeout24m, 4mdead24m)
    char *4mfile_name24m;
    int 4mretries24m;
    int 4mtimeout24m;
    long 4mdead24m;


4mfile_name24m The authorization file to lock.

4mretries24m   The number of retries.




			   - 50 -





1mInter-Client Exchange Library		      X11, Release 6.40m


4mtimeout24m   The number of seconds before each retry.

4mdead24m      If  a  lock  already  exists that is the specified
	  dead seconds old, it is broken.  A value  of	zero
	  is used to unconditionally break an old lock.
|__

One of three values is returned:

·    4mIceAuthLockSuccess24m - the lock succeeded.

·    4mIceAuthLockError24m  -  a system error occurred, and 4merrno0m
     may prove useful.

·    4mIceAuthLockTimeout24m - the specified  number  of  retries
     failed.


To unlock an authorization file, use 4mIceUnlockAuthFile24m.
__
|
void IceUnlockAuthFile(4mfile_name24m)
    char *4mfile_name24m;


4mfile_name24m The authorization file to unlock.
|__


To  read  the  next  entry  in	an  authorization  file, use
4mIceReadAuthFileEntry24m.
__
|
IceAuthFileEntry *IceReadAuthFileEntry(4mauth_file24m)
    FILE *4mauth_file24m;


4mauth_file24m The authorization file.
|__

Note that it is the responsibility  of	the  application  to
open  the file for reading before calling this function.  If
an error is encountered, or there are  no  more	 entries  to
read, NULL is returned.

Entries	 should be free with a call to 4mIceFreeAuthFileEntry24m.


To write an entry in an authorization file, use	 4mIceWriteAu-0m
4mthFileEntry24m.
__
|





			   - 51 -





1mInter-Client Exchange Library		      X11, Release 6.40m


Status IceWriteAuthFileEntry(4mauth_file24m, 4mentry24m)
    FILE *4mauth_file24m;
    IceAuthFileEntry *4mentry24m;


4mauth_file24m The authorization file.

4mentry24m     The entry to write.
|__

Note  that  it	is  the responsibility of the application to
open the file for writing before calling this function.	 The
function  returns a nonzero status if the operation was suc-
cessful.


To search the default authorization file for an	 entry	that
matches	 a  given  protocol_name/network_id/auth_name tuple,
use 4mIceGetAuthFileEntry24m.
__
|
IceAuthFileEntry *IceGetAuthFileEntry(4mprotocol_name24m, 4mnetwork_id24m, 4mauth_name24m)
    char *4mprotocol_name24m;
    char *4mnetwork_id24m;
    char *4mauth_name24m;


4mprotocol_name0m
	  The name of the protocol to search on.

4mnetwork_id0m
	  The network ID to search on.

4mauth_name24m The authentication method to search on.
|__

If 4mIceGetAuthFileEntry24m fails to find such an entry, NULL  is
returned.


To  free an entry returned by 4mIceReadAuthFileEntry24m or 4mIceGe-0m
4mtAuthFileEntry24m, use 4mIceFreeAuthFileEntry24m.
__
|
void IceFreeAuthFileEntry(4mentry24m)
    IceAuthFileEntry *4mentry24m;


4mentry24m     The entry to free.
|__







			   - 52 -





1mInter-Client Exchange Library		      X11, Release 6.40m


			 1mAppendix B0m

	     1mMIT-MAGIC-COOKIE-1 Authentication0m


The X Consortium's ICElib implementation supports  a  simple
MIT-MAGIC-COOKIE-1 authentication scheme using the authority
file utilities described in Appendix A.

In this model, an application, such as	a  session  manager,
obtains	 a  magic  cookie by calling 4mIceGenerateMagicCookie24m,
and then stores it in the user's local .ICEauthority file so
that  local  clients  can connect.  In order to allow remote
clients to connect, some remote execution  mechanism  should
be  used to store the magic cookie in the user's .ICEauthor-
ity file on a remote machine.

In addition to storing the magic cookie in the .ICEauthority
file,  the  application	 needs	to call the 4mIceSetPaAuthData0m
function in order to store the magic cookie in memory.	When
it comes time for the MIT-MAGIC-COOKIE-1 authentication pro-
cedure to accept or reject the connection, it  will  compare
the  magic  cookie  presented  by the requestor to the magic
cookie in memory.

__
|
char *IceGenerateMagicCookie(4mlength24m)
    int 4mlength24m;


4mlength24m    The desired length of the magic cookie.
|__


The magic cookie returned will be null-terminated.  If	mem-
ory  can not be allocated for the magic cookie, the function
will return NULL.  Otherwise, the  magic  cookie  should  be
freed with a call to 4mfree24m.


To  store the authentication data in memory, use 4mIceSetPaAu-0m
4mthData24m.  Currently, this function	is  only  used	for  MIT-
MAGIC-COOKIE-1	authentication, but it may be used for addi-
tional authentication methods in the future.
__
|
void IceSetPaAuthData(4mnum_entries24m, 4mentries24m)
    int 4mnum_entries24m;
    IceAuthDataEntry *4mentries24m;


4mnum_entries0m
	  The number of authentication data entries.



			   - 53 -





1mInter-Client Exchange Library		      X11, Release 6.40m


4mentries24m   The list of authentication data entries.
|__

Each entry has associated with it a protocol name (for exam-
ple,   ``ICE''	for  ICE  connection  setup  authentication,
``XSMP'' for session management authentication),  a  network
ID for the ``accepting'' client, an authentication name (for
example, MIT-MAGIC-COOKIE-1), and authentication data.	 The
ICE  library  will  merge  these entries with previously set
entries, based on the (protocol_name, network_id, auth_name)
tuple.

__
|
typedef struct {
     char *protocol_name;
     char *network_id;
     char *auth_name;
     unsigned short auth_data_length;
     char *auth_data;
} IceAuthDataEntry;

|__


































			   - 54 -









		     1mTable of Contents0m


1. Overview of ICE . . . . . . . . . . . . . . . . . . .   1
2. The ICE Library - C Language Interface to ICE . . . .   1
3. Intended Audience . . . . . . . . . . . . . . . . . .   1
4. Header Files and Library Name . . . . . . . . . . . .   2
5. Note on Prefixes  . . . . . . . . . . . . . . . . . .   2
6. Protocol Registration . . . . . . . . . . . . . . . .   2
6.1. Callbacks for Processing Messages . . . . . . . . .   8
6.2. Authentication Methods  . . . . . . . . . . . . . .  12
7. ICE Connections . . . . . . . . . . . . . . . . . . .  15
7.1. Opening an ICE Connection . . . . . . . . . . . . .  15
7.2. Listening for ICE Connections . . . . . . . . . . .  17
7.3. Host Based Authentication for ICE Connections
 . . . . . . . . . . . . . . . . . . . . . . . . . . . .  20
7.4. Accepting ICE Connections . . . . . . . . . . . . .  21
7.5. Closing ICE Connections . . . . . . . . . . . . . .  23
7.6. Connection Watch Procedures . . . . . . . . . . . .  24
8. Protocol Setup and Shutdown . . . . . . . . . . . . .  26
9. Processing Messages . . . . . . . . . . . . . . . . .  28
10. Ping . . . . . . . . . . . . . . . . . . . . . . . .  30
11. Using ICElib Informational Functions . . . . . . . .  31
12. ICE Messages . . . . . . . . . . . . . . . . . . . .  33
12.1. Sending ICE Messages . . . . . . . . . . . . . . .  33
12.2. Reading ICE Messages . . . . . . . . . . . . . . .  39
13. Error Handling . . . . . . . . . . . . . . . . . . .  43
14. Multi-Threading Support  . . . . . . . . . . . . . .  46
15. Miscellaneous Functions  . . . . . . . . . . . . . .  48
16. Acknowledgements . . . . . . . . . . . . . . . . . .  48
Appendix A - Authentication Utility Functions  . . . . .  49
Appendix B - MIT-MAGIC-COOKIE-1 Authentication . . . . .  53
























			     iii