1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
10 <title>Inter-Client Exchange Library</title>
11 <subtitle>X Consortium Standard</subtitle>
12 <releaseinfo>X Version 11, Release 6.4</releaseinfo>
15 <firstname>Ralph</firstname><surname>Mor</surname>
16 <affiliation><orgname>X Consortium</orgname></affiliation>
19 <corpname>X Consortium Standard</corpname>
20 <copyright><year>1993</year><holder>X Consortium</holder></copyright>
21 <copyright><year>1994</year><holder>X Consortium</holder></copyright>
22 <copyright><year>1996</year><holder>X Consortium</holder></copyright>
23 <revhistory><revision><revnumber>1.0</revnumber><date></date></revision></revhistory>
27 Permission is hereby granted, free of charge, to any person obtaining a copy
28 of this software and associated documentation files (the
29 "Software"), to deal in the Software without restriction,
30 including without limitation the rights to use, copy, modify, merge,
31 publish, distribute, sublicense, and/or sell copies of the Software, and
32 to permit persons to whom the Software is furnished to do so, subject to
33 the following conditions:
36 <para>The above copyright notice and this permission notice shall be
37 included in all copies or substantial portions of the Software.
41 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
42 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
43 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
44 X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
45 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
46 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
50 Except as contained in this notice, the name of the X Consortium shall not be
51 used in advertising or otherwise to promote the sale, use or other dealings
52 in this Software without prior written authorization from the X Consortium.
58 <chapter id='overview_of_ice'>
59 <title>Overview of ICE</title>
62 There are numerous possible inter-client protocols, with many similarities
63 and common needs - authentication, version negotiation, byte
64 order negotiation, and so on.
65 The Inter-Client Exchange (ICE) protocol is intended to provide a framework
66 for building such protocols, allowing them to make use of common negotiation
67 mechanisms and to be multiplexed over a single transport connection.
71 <chapter id='the_ice_library__c_language_interface_to'>
72 <title>The ICE Library - C Language Interface to ICE</title>
75 A client that wishes to utilize ICE must first register the protocols it
76 understands with the ICE library. Each protocol is dynamically assigned
77 a major opcode ranging from 1-255 (two clients can use different
78 major opcodes for the same protocol). The next step for the client is either
79 to open a connection with another client or to wait for connections made
80 by other clients. Authentication may be required. A client can both
81 initiate connections with other clients and be
82 waiting for clients to connect to itself (a nested session manager is an
83 example). Once an ICE connection is established between the two clients, one
84 of the clients needs to initiate a
85 <function>ProtocolSetup</function>
87 "activate" a given protocol. Once the other client accepts the
88 <function>ProtocolSetup</function>
89 (once again, authentication may be required), the
90 two clients are ready to start passing messages specific to that protocol to
91 each other. Multiple protocols may be active on a single ICE connection.
92 Clients are responsible for notifying the ICE library when a protocol is no
93 longer active on an ICE connection, although ICE does not define how each
94 subprotocol triggers a protocol shutdown.
98 The ICE library utilizes callbacks to process incoming messages. Using
100 <function>ProtocolSetup</function>
101 messages and authentication to happen
102 behind the scenes. An additional benefit is that messages never need
103 to be buffered up by the library when the client blocks waiting for a
108 <chapter id='intended_audience'>
109 <title>Intended Audience</title>
111 <para>This document is intended primarily for implementors of protocol libraries
112 layered on top of ICE. Typically, applications that wish to utilize ICE
113 will make calls into individual protocol libraries rather than directly
114 make calls into the ICE library. However, some applications will have to
115 make some initial calls into the ICE library in order to accept ICE
116 connections (for example, a session manager accepting connections from
117 clients). But in general, protocol libraries should be designed to hide
118 the inner details of ICE from applications.</para>
121 <chapter id='header_files_and_library_name'>
122 <title>Header Files and Library Name</title>
125 <para>The header file
126 <<symbol role='Pn'>X11/ICE/ICElib.h</symbol>>
127 defines all of the ICElib data structures and function prototypes.
128 <function>ICElib.h</function>
129 includes the header file
130 <<symbol role='Pn'>X11/ICE/ICE.h</symbol>>,
131 which defines all of the ICElib constants.
132 Protocol libraries that need to read and write messages should include
134 <<symbol role='Pn'>X11/ICE/ICEmsg.h</symbol>>.</para>
136 <para>Applications should link against ICElib using -lICE.</para>
139 <chapter id='note_on_prefixes'>
140 <title>Note on Prefixes</title>
143 <para>The following name prefixes are used in the library to distinguish between
144 a client that initiates a
145 <function>ProtocolSetup</function>
148 <function>ProtocolReply</function></para>
152 <para><function>IcePo</function>
153 - Ice Protocol Originator</para>
156 <para><function>IcePa</function>
157 - Ice Protocol Acceptor</para>
162 <chapter id='protocol_registration'>
163 <title>Protocol Registration</title>
166 In order for two clients to exchange messages for a given protocol, each
167 side must register the protocol with the ICE library. The purpose of
168 registration is for each side to obtain a major opcode for the protocol
169 and to provide callbacks for processing messages and handling authentication.
170 There are two separate registration functions:
176 One to handle the side that does a
177 <function>ProtocolSetup</function>
182 One to handle the side that responds with a
183 <function>ProtocolReply</function>
189 It is recommended that protocol registration occur before the two clients
190 establish an ICE connection. If protocol registration occurs after an
191 ICE connection is created, there can be a brief interval of time in which a
192 <function>ProtocolSetup</function>
193 is received, but the protocol is not registered.
194 If it is not possible to register a protocol before the creation of an
195 ICE connection, proper precautions should be taken to avoid the above race
201 The <function>IceRegisterForProtocolSetup</function>
202 function should be called for the client that initiates a
203 <function>ProtocolSetup</function>
208 <funcdef>int <function>IceRegisterForProtocolSetup</function></funcdef>
209 <paramdef>char<parameter> *protocol_name</parameter></paramdef>
210 <paramdef>char<parameter> *vendor</parameter></paramdef>
211 <paramdef>char<parameter> *release</parameter></paramdef>
212 <paramdef>int<parameter> *version_count</parameter></paramdef>
213 <paramdef>int<parameter> *version_count</parameter></paramdef>
214 <paramdef>IcePoVersionRec<parameter> *version_recs</parameter></paramdef>
215 <paramdef>int<parameter> auth_names</parameter></paramdef>
216 <paramdef>char<parameter> **auth_names</parameter></paramdef>
217 <paramdef>IcePoAuthProc<parameter> *auth_procs</parameter></paramdef>
218 <paramdef>IceIOErrorProc<parameter> *io_error_proc</parameter></paramdef>
223 <variablelist remap='IP'>
225 <term><emphasis remap='I'>protocol_name</emphasis></term>
228 A string specifying the name of the protocol to register.
233 <term><emphasis remap='I'>vendor</emphasis></term>
235 <para>A vendor string with semantics specified by the protocol.</para>
239 <term><emphasis remap='I'>release</emphasis></term>
241 <para>A release string with semantics specified by the protocol.</para>
245 <term><emphasis remap='I'>version_count</emphasis></term>
247 <para>The number of different versions of the protocol supported.</para>
251 <term><emphasis remap='I'>version_recs</emphasis></term>
253 <para>List of versions and associated callbacks.</para>
257 <term><emphasis remap='I'>auth_count</emphasis></term>
259 <para>The number of authentication methods supported.</para>
263 <term><emphasis remap='I'>auth_names</emphasis></term>
265 <para>The list of authentication methods supported.</para>
269 <term><emphasis remap='I'>auth_procs</emphasis></term>
272 The list of authentication callbacks, one for each authentication method.
277 <term><emphasis remap='I'>io_error_proc</emphasis></term>
279 <para>IO error handler, or NULL.</para>
286 <function>IceRegisterForProtocolSetup</function> returns the major
287 opcode reserved or -1 if an error occurred. In order to actually activate
288 the protocol, the <function>IceProtocolSetup</function>
289 function needs to be called with this major opcode. Once the protocol is
290 activated, all messages for the protocol should be sent using this major
295 A protocol library may support multiple versions of the same protocol.
296 The version_recs argument specifies a list of supported versions of the
297 protocol, which are prioritized in decreasing order of preference.
298 Each version record consists of a major and minor version of the protocol
299 as well as a callback to be used for processing incoming messages.
303 <literallayout remap='Ds'>
307 IcePoProcessMsgProc process_msg_proc;
312 <function>IcePoProcessMsgProc</function>
313 callback is responsible for processing the set of messages that can be
314 received by the client that initiated the
315 <function>ProtocolSetup</function>
316 For further information,
318 <link linkend="callbacks_for_processing_messages">
319 <xref linkend="callbacks_for_processing_messages"></xref></link>.</para>
321 <para>Authentication may be required before the protocol can become active.
322 The protocol library must register the authentication methods that it
323 supports with the ICE library.
324 The auth_names and auth_procs arguments are a list of authentication names
325 and callbacks that are prioritized in decreasing order of preference.
326 For information on the
327 <function>IcePoAuthProc</function>
329 <link linkend="authentication_methods">
330 <xref linkend="authentication_methods"></xref></link>
334 <function>IceIOErrorProc</function>
335 callback is invoked if the ICE connection unexpectedly breaks.
336 You should pass NULL for io_error_proc if not interested in being notified.
337 For further information,
338 <link linkend="error_handling">
339 <xref linkend="error_handling"></xref></link>
344 <function>IceRegisterForProtocolReply</function>
345 function should be called for the client that responds to a
346 <function>ProtocolSetup</function>
348 <function>ProtocolReply</function></para>
353 <funcdef>Bool <function>IceRegisterForProtocolReply</function></funcdef>
354 <paramdef>char<parameter> *host_name</parameter></paramdef>
358 <variablelist remap='IP'>
360 <term><emphasis remap='I'>protocol_name</emphasis></term>
361 <listitem><para>A string specifying the name of the protocol to register.</para></listitem>
364 <term><emphasis remap='I'>vendor</emphasis></term>
366 <para>A vendor string with semantics specified by the protocol.</para>
370 <term><emphasis remap='I'>release</emphasis></term>
372 <para>A release string with semantics specified by the protocol.</para>
376 <term><emphasis remap='I'>version_count</emphasis></term>
378 <para>The number of different versions of the protocol supported.</para>
382 <term><emphasis remap='I'>version_recs</emphasis></term>
384 <para>List of versions and associated callbacks.</para>
388 <term><emphasis remap='I'>auth_count</emphasis></term>
390 <para>The number of authentication methods supported.</para>
394 <term><emphasis remap='I'>auth_names</emphasis></term>
396 <para>The list of authentication methods supported.</para>
400 <term><emphasis remap='I'>auth_procs</emphasis></term>
402 <para>The list of authentication callbacks, one for each authentication method.</para>
406 <term><emphasis remap='I'>host_based_auth_proc</emphasis></term>
408 <para>Host based authentication callback.</para>
412 <term><emphasis remap='I'>protocol_setup_proc</emphasis></term>
414 <para>A callback to be invoked when authentication has succeeded for a
415 <function>ProtocolSetup</function>
417 <function>ProtocolReply</function>
422 <term><emphasis remap='I'>protocol_activate_proc</emphasis></term>
424 <para>A callback to be invoked after the
425 <function>ProtocolReply</function>
430 <term><emphasis remap='I'>io_error_proc</emphasis></term>
432 <para>IO error handler, or NULL.</para>
438 <para><function>IceRegisterForProtocolReply</function>
439 returns the major opcode reserved or -1 if an error occurred. The major
440 opcode should be used in all subsequent messages sent for this protocol.</para>
442 <para>A protocol library may support multiple versions of the same protocol.
443 The version_recs argument specifies a list of supported versions of the protocol,
444 which are prioritized in decreasing order of preference.
445 Each version record consists of a major and minor version of the protocol
446 as well as a callback to be used for processing incoming messages.</para>
449 <literallayout remap='Ds'>
453 IcePaProcessMsgProc process_msg_proc;
459 <function>IcePaProcessMsgProc</function>
460 callback is responsible for processing the set of messages that can be
461 received by the client that accepted the
462 <function>ProtocolSetup</function>
463 For further information,
465 <link linkend="callbacks_for_processing_messages">
466 <xref linkend="callbacks_for_processing_messages"></xref></link>
469 <para>Authentication may be required before the protocol can become active.
470 The protocol library must register the authentication methods that it
471 supports with the ICE library.
472 The auth_names and auth_procs arguments are a list of authentication names
473 and callbacks that are prioritized in decreasing order of preference.
474 For information on the
475 <function>IcePaAuthProc</function>,
477 <link linkend="authentication_methods">
478 <xref linkend="authentication_methods"></xref></link>
482 <para>If authentication fails and the client attempting to initiate
484 <function>ProtocolSetup</function>
485 has not required authentication, the
486 <function>IceHostBasedAuthProc</function>
487 callback is invoked with the host name of the originating client.
488 If the callback returns
489 <function>True</function>
491 <function>ProtocolSetup</function>
492 will succeed, even though the original
493 authentication failed.
494 Note that authentication can effectively be disabled by registering an
495 <function>IceHostBasedAuthProc</function>
497 <function>True</function>
499 authentication is allowed, you should pass NULL for host_based_auth_proc.</para>
503 <funcdef>Bool <function>HostBasedAuthProc</function></funcdef>
504 <paramdef>char<parameter> *host_name</parameter></paramdef>
508 <variablelist remap='IP'>
510 <term><emphasis remap='I'>protocol_name</emphasis></term>
511 <listitem><para>The host name of the client that sent the <function>ProtocolSetup</function></para></listitem>
516 <para>The host_name argument is a string of the form <emphasis remap='I'>protocol</emphasis>/<emphasis remap='I'>hostname</emphasis>,
517 where <emphasis remap='I'>protocol</emphasis> is one of {tcp, decnet, local}.</para>
520 <function>ProtocolSetup</function>
521 messages and authentication happen behind the scenes
522 via callbacks, the protocol library needs some way of being notified when the
523 <function>ProtocolSetup</function>
525 This occurs in two phases.
526 In the first phase, the
527 <function>IceProtocolSetupProc</function>
528 callback is invoked after authentication has
529 successfully completed but before the ICE library sends a
530 <function>ProtocolReply</function>
531 Any resources required for this protocol should be allocated at this time.
533 <function>IceProtocolSetupProc</function>
534 returns a successful status, the ICE library will
536 <function>ProtocolReply</function>
538 <function>IceProtocolActivateProc</function>
539 callback. Otherwise, an error will be sent to the
540 other client in response to the
541 <function>ProtocolSetup</function></para>
544 <function>IceProtocolActivateProc</function>
545 is an optional callback and should be registered only if the protocol
546 library intends to generate a message immediately following the
547 <function>ProtocolReply</function>
548 You should pass NULL for protocol_activate_proc if not interested
549 in this callback.</para>
553 <funcdef>Status <function>ProtocolSetupProc</function></funcdef>
554 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
555 <paramdef>int<parameter> major_version</parameter></paramdef>
556 <paramdef>int<parameter> minor_version</parameter></paramdef>
557 <paramdef>char<parameter> *vendor</parameter></paramdef>
558 <paramdef>char<parameter> *release</parameter></paramdef>
559 <paramdef>IcePointer<parameter> *client_data_ret</parameter></paramdef>
560 <paramdef>char<parameter> **failure_reason_ret</parameter></paramdef>
564 <variablelist remap='IP'>
566 <term><emphasis remap='I'>protocol_name</emphasis></term>
568 <para>The ICE connection object.</para>
572 <term><emphasis remap='I'>major_version</emphasis></term>
574 <para>The major version of the protocol.</para>
578 <term><emphasis remap='I'>minor_version</emphasis></term>
580 <para>The minor version of the protocol.</para>
584 <term><emphasis remap='I'>vendor</emphasis></term>
586 <para>The vendor string registered by the protocol originator.</para>
590 <term><emphasis remap='I'>release</emphasis></term>
592 <para>The release string registered by the protocol originator.</para>
596 <term><emphasis remap='I'>client_data_ret</emphasis></term>
598 <para>Client data to be set by callback.</para>
602 <term><emphasis remap='I'>failure_reason_ret</emphasis></term>
604 <para>Failure reason returned.</para>
609 <para>The pointer stored in the client_data_ret argument will be passed
611 <function>IcePaProcessMsgProc</function>
612 callback whenever a message has arrived for this protocol on the
613 ICE connection.</para>
615 <para>The vendor and release strings should be freed with
616 <function>free</function>
617 when they are no longer needed.</para>
619 <para>If a failure occurs, the
620 <function>IceProtocolSetupProc</function>
621 should return a zero status as well as allocate and return a failure
622 reason string in failure_reason_ret.
623 The ICE library will be responsible for freeing this memory.</para>
626 <function>IceProtocolActivateProc</function>
627 callback is defined as follows:</para>
631 <funcdef>void <function>ProtocolActivateProc</function></funcdef>
632 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
633 <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
637 <variablelist remap='IP'>
639 <term><emphasis remap='I'>ice_conn</emphasis></term>
640 <listitem><para>The ICE connection object.</para></listitem>
643 <term><emphasis remap='I'>client_data</emphasis></term>
646 The client data set in the <function>IceProtocolSetupProc</function> callback.
654 <function>IceIOErrorProc</function>
655 callback is invoked if the ICE connection unexpectedly breaks.
656 You should pass NULL for io_error_proc if not interested in being notified.
657 For further information,
659 <link linkend="error_handling">
660 <xref linkend="error_handling"></xref></link>
663 <sect1 id='callbacks_for_processing_messages'>
664 <title>Callbacks for Processing Messages</title>
666 <para>When an application detects that there is new data to read on an ICE
668 <function>select</function>
670 <function>IceProcessMessages</function>
672 <link linkend="processing_messages">
673 <xref linkend="processing_messages"></xref></link>.
676 <function>IceProcessMessages</function>
677 reads an ICE message header with a major opcode other than
678 zero (reserved for the ICE protocol), it needs to call a function that will
679 read the rest of the message, unpack it, and process it accordingly.</para>
681 <para>If the message arrives at the client that initiated the
682 <function>ProtocolSetup</function>
684 <function>IcePoProcessMsgProc</function>
685 callback is invoked.</para>
689 <funcdef>void <function>PoProcessMsgProc</function></funcdef>
690 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
691 <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
692 <paramdef>int<parameter> opcode</parameter></paramdef>
693 <paramdef>unsigned long<parameter> length</parameter></paramdef>
694 <paramdef>Bool<parameter> swap</parameter></paramdef>
695 <paramdef>IceReplyWaitInfo<parameter> *reply_wait</parameter></paramdef>
696 <paramdef>Bool<parameter> *reply_ready_ret</parameter></paramdef>
700 <variablelist remap='IP'>
702 <term><emphasis remap='I'>ice_conn</emphasis></term>
703 <listitem><para>The ICE connection object.</para></listitem>
706 <term><emphasis remap='I'>client_data</emphasis></term>
708 <para>Client data associated with this protocol on the ICE connection.</para>
712 <term><emphasis remap='I'>opcode</emphasis></term>
714 <para>The minor opcode of the message.</para>
718 <term><emphasis remap='I'>length</emphasis></term>
720 <para>The length (in 8-byte units) of the message beyond the ICE header.</para>
724 <term><emphasis remap='I'>swap</emphasis></term>
726 <para>A flag that indicates if byte swapping is necessary.</para>
730 <term><emphasis remap='I'>reply_wait</emphasis></term>
732 <para>Indicates if the invoking client is waiting for a reply.</para>
736 <term><emphasis remap='I'>reply_ready_ret</emphasis></term>
739 <function>True</function>
740 a reply is ready.</para>
746 <para>If the message arrives at the client that accepted the
747 <function>ProtocolSetup</function>
749 <function>IcePaProcessMsgProc</function>
750 callback is invoked.</para>
755 <funcdef>void <function>IcePaProcessMsgProc</function></funcdef>
756 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
757 <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
758 <paramdef>int<parameter> opcode</parameter></paramdef>
759 <paramdef>unsigned long<parameter> length</parameter></paramdef>
760 <paramdef>Bool<parameter> swap</parameter></paramdef>
764 <variablelist remap='IP'>
766 <term><emphasis remap='I'>ice_conn</emphasis></term>
767 <listitem><para>The ICE connection object.</para></listitem>
770 <term><emphasis remap='I'>client_data</emphasis></term>
772 <para>Client data associated with this protocol on the ICE connection.</para>
776 <term><emphasis remap='I'>opcode</emphasis></term>
778 <para>The minor opcode of the message.</para>
782 <term><emphasis remap='I'>length</emphasis></term>
784 <para>The length (in 8-byte units) of the message beyond the ICE header.</para>
788 <term><emphasis remap='I'>swap</emphasis></term>
790 <para>A flag that indicates if byte swapping is necessary.</para>
796 <para>In order to read the message, both of these callbacks should use the
797 macros defined for this purpose (see
798 <link linkend="reading_ice_messages">
799 <xref linkend="reading_ice_messages"></xref></link>.).
800 Note that byte swapping may be necessary.
801 As a convenience, the length field in the ICE header will be swapped by ICElib
804 <para>In both of these callbacks, the client_data argument is a pointer to client
805 data that was registered at
806 <function>ProtocolSetup</function>
809 <function>IcePoProcessMsgProc</function>
810 the client data was set in the call to
811 <function>IceProtocolSetup</function>
813 <function>IcePaProcessMsgProc</function>
814 the client data was set in the
815 <function>IceProtocolSetupProc</function>
819 <function>IcePoProcessMsgProc</function>
820 callback needs to check the reply_wait argument.
821 If reply_wait is NULL ,
822 the ICE library expects the function to
823 pass the message to the client via a callback.
824 For example, if this is a Session Management "Save Yourself" message,
825 this function should notify the client of the "Save Yourself" via a callback.
826 The details of how such a callback would be defined
827 are implementation-dependent.</para>
829 <para>However, if reply_wait is not NULL ,
830 then the client is waiting for
831 a reply or an error for a message it previously sent.
832 The reply_wait is of type
833 <function>IceReplyWaitInfo</function></para>
836 <literallayout remap='Ds'>
838 unsigned long sequence_of_request;
839 int major_opcode_of_request;
840 int minor_opcode_of_request;
845 <para><function>IceReplyWaitInfo</function>
846 contains the major/minor opcodes and sequence number of
847 the message for which a reply is being awaited.
848 It also contains a pointer to the reply message to be filled in
849 (the protocol library should cast this
850 <function>IcePointer</function>
851 to the appropriate reply type).
852 In most cases, the reply will have some fixed-size part, and the client waiting
853 for the reply will have provided a pointer to a structure to hold
854 this fixed-size data. If there is variable-length data, it would be
856 <function>IcePoProcessMsgProc</function>
857 callback will have to allocate additional
858 memory and store pointer(s) to that memory in the fixed-size
859 structure. If the entire data is variable length (for example., a single
860 variable-length string), then the client waiting for the reply would probably
861 just pass a pointer to fixed-size space to hold a pointer, and the
862 <function>IcePoProcessMsgProc</function>
863 callback would allocate the storage and store the pointer.
864 It is the responsibility of the client receiving the reply to
865 free any memory allocated on its behalf.</para>
867 <para>If reply_wait is not NULL and
868 <function>IcePoProcessMsgProc</function>
869 has a reply or error to return in response to this reply_wait
870 (that is, no callback was generated), then the reply_ready_ret argument
872 <function>True</function>
873 Note that an error should only be returned
874 if it corresponds to the reply being waited for. Otherwise, the
875 <function>IcePoProcessMsgProc</function>
876 should either handle the error internally or invoke an error handler
877 for its library.</para>
879 <para>If reply_wait is NULL,
880 then care must be taken not to store any value in reply_ready_ret,
881 because this pointer may also be NULL.</para>
884 <function>IcePaProcessMsgProc</function>
885 callback, on the other hand, should always pass
886 the message to the client via a callback. For example, if this is a Session
887 Management "Interact Request" message, this function should notify the
888 client of the "Interact Request" via a callback.</para>
891 <function>IcePaProcessMsgProc</function>
892 callback does not have a reply_wait, like
893 <function>IcePoProcessMsgProc</function>
894 does, is because a process that is acting as
895 a server should never block for a reply (infinite blocking can
896 occur if the connecting client does not act properly, denying access
897 to other clients).</para>
900 <sect1 id='authentication_methods'>
901 <title>Authentication Methods</title>
903 <para>As already stated, a protocol library must register the authentication
904 methods that it supports with the ICE library. For each authentication
905 method, there are two callbacks that may be registered:</para>
909 One to handle the side that initiates a <function>ProtocolSetup</function>
914 One to handle the side that accepts or rejects this request
919 <para><function>IcePoAuthProc</function>
920 is the callback invoked for the client that initiated the
921 <function>ProtocolSetup</function>
922 This callback must be able to respond
923 to the initial "Authentication Required" message or subsequent
924 "Authentication Next Phase" messages sent by the other client.</para>
929 <funcdef>IcePoAuthStatus <function>IcePoAuthStatus </function></funcdef>
930 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
931 <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
932 <paramdef>int<parameter> opcode</parameter></paramdef>
937 <variablelist remap='IP'>
939 <term><emphasis remap='I'>ice_conn</emphasis></term>
940 <listitem><para>The ICE connection object.</para></listitem>
943 <term><emphasis remap='I'>auth_state_ptr</emphasis></term>
945 <para>A pointer to state for use by the authentication callback procedure.</para>
949 <term><emphasis remap='I'>clean_up</emphasis></term>
952 <function>True</function>
953 authentication is over, and the function
954 should clean up any state it was maintaining. The
955 last 6 arguments should be ignored.</para>
959 <term><emphasis remap='I'>swap</emphasis></term>
962 <function>True</function>
963 the auth_data may have to be byte swapped
964 (depending on its contents).</para>
968 <term><emphasis remap='I'>auth_datalen</emphasis></term>
970 <para>The length (in bytes) of the authenticator data.</para>
974 <term><emphasis remap='I'>auth_data</emphasis></term>
976 <para>The data from the authenticator.</para>
980 <term><emphasis remap='I'>reply_datalen_ret</emphasis></term>
982 <para>The length (in bytes) of the reply data returned.</para>
986 <term><emphasis remap='I'>reply_data_ret</emphasis></term>
988 <para>The reply data returned.</para>
992 <term><emphasis remap='I'>error_string_ret</emphasis></term>
994 <para>If the authentication procedure encounters an error during
995 authentication, it should allocate and return
996 an error string.</para>
1002 <para>Authentication may require several phases, depending on the authentication
1003 method. As a result, the
1004 <function>IcePoAuthProc</function>
1005 may be called more than once when authenticating a client, and
1006 some state will have to be maintained between each invocation.
1007 At the start of each
1008 <function>ProtocolSetup</function>
1009 *auth_state_ptr is NULL,
1010 and the function should initialize its state and set
1011 this pointer. In subsequent invocations of the callback, the pointer
1012 should be used to get at any state previously stored by the callback.</para>
1014 <para>If needed, the network ID of the client accepting the
1015 <function>ProtocolSetup</function>
1016 can be obtained by calling the
1017 <function>IceConnectionString</function>
1020 <para>ICElib will be responsible for freeing the reply_data_ret and
1021 error_string_ret pointers with
1022 <function>free</function></para>
1024 <para>The auth_data pointer may point to a volatile block of memory.
1025 If the data must be kept beyond this invocation of the callback, be sure
1026 to make a copy of it.</para>
1029 <function>IcePoAuthProc</function>
1030 should return one of four values:</para>
1033 <para><function>IcePoAuthHaveReply</function>
1034 - a reply is available.</para>
1037 <para><function>IcePoAuthRejected</function>
1038 - authentication rejected.</para>
1041 <para><function>IcePoAuthFailed</function>
1042 - authentication failed.</para>
1045 <para><function>IcePoAuthDoneCleanup</function>
1046 - done cleaning up.</para>
1050 <para><function>IcePaAuthProc</function>
1051 is the callback invoked for the client that received the
1052 <function>ProtocolSetup</function></para>
1056 <funcdef>IcePoAuthStatus <function>PoAuthStatus </function></funcdef>
1057 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
1058 <paramdef>IcePointer<parameter> *auth_state_ptr</parameter></paramdef>
1059 <paramdef>Bool<parameter> swap</parameter></paramdef>
1060 <paramdef>int<parameter> auth_datalen</parameter></paramdef>
1061 <paramdef>IcePointer<parameter> auth_data</parameter></paramdef>
1062 <paramdef>int<parameter> *reply_datalen_ret</parameter></paramdef>
1063 <paramdef>IcePointer<parameter> *reply_data_ret</parameter></paramdef>
1064 <paramdef>char<parameter> **error_string_ret</parameter></paramdef>
1068 <variablelist remap='IP'>
1070 <term><emphasis remap='I'>ice_conn</emphasis></term>
1071 <listitem><para>The ICE connection object.</para></listitem>
1074 <term><emphasis remap='I'>auth_state_ptr</emphasis></term>
1076 <para>A pointer to state for use by the authentication callback procedure.</para>
1080 <term><emphasis remap='I'>swap</emphasis></term>
1083 <function>True</function>
1084 auth_data may have to be byte swapped
1085 (depending on its contents).</para>
1089 <term><emphasis remap='I'>auth_datalen</emphasis></term>
1091 <para>The length (in bytes) of the protocol originator authentication data.</para>
1095 <term><emphasis remap='I'>auth_data</emphasis></term>
1097 <para>The authentication data from the protocol originator.</para>
1101 <term><emphasis remap='I'>reply_datalen_ret</emphasis></term>
1103 <para>The length of the authentication data returned.</para>
1107 <term><emphasis remap='I'>reply_data_ret</emphasis></term>
1109 <para>The authentication data returned.</para>
1113 <term><emphasis remap='I'>error_string_ret</emphasis></term>
1115 <para>If authentication is rejected or fails, an error
1116 string is returned.</para>
1122 <para>Authentication may require several phases, depending on the authentication
1123 method. As a result, the
1124 <function>IcePaAuthProc</function>
1125 may be called more than once when authenticating a client, and
1126 some state will have to be maintained between each invocation.
1127 At the start of each
1128 <function>ProtocolSetup</function>
1129 auth_datalen is zero,
1130 *auth_state_ptr is NULL,
1131 and the function should initialize its state and set
1132 this pointer. In subsequent invocations of the callback, the pointer
1133 should be used to get at any state previously stored by the callback.</para>
1135 <para>If needed, the network ID of the client accepting the
1136 <function>ProtocolSetup</function>
1137 can be obtained by calling the
1138 <function>IceConnectionString</function>
1141 <para>The auth_data pointer may point to a volatile block of memory.
1142 If the data must be kept beyond this invocation of the callback, be sure
1143 to make a copy of it.</para>
1145 <para>ICElib will be responsible for transmitting and freeing the reply_data_ret and
1146 error_string_ret pointers with
1147 <function>free</function></para>
1150 The <function>IcePaAuthProc</function> should return one of four values:
1157 <function>IcePaAuthContinue</function> - continue (or start) authentication.
1162 <function>IcePaAuthAccepted</function> - authentication accepted.
1167 <function>IcePaAuthRejected</function> - authentication rejected.
1172 <function>IcePaAuthFailed</function> - authentication failed.
1180 <chapter id='ice_connections'>
1181 <title>ICE Connections</title>
1184 In order for two clients to establish an ICE connection, one client has to be
1185 waiting for connections, and the other client has to initiate the connection.
1186 Most clients will initiate connections, so we discuss that first.
1189 <sect1 id='opening_an_ice_connection'>
1190 <title>Opening an ICE Connection</title>
1194 To open an ICE connection with another client (that is, waiting
1195 for connections), use <function>IceOpenConnection</function>
1200 <funcdef>IceConn <function>IceOpenConnection</function></funcdef>
1201 <paramdef>char<parameter> *network_ids_list</parameter></paramdef>
1202 <paramdef>IcePointer<parameter> context</parameter></paramdef>
1203 <paramdef>Bool<parameter> must_authenticate</parameter></paramdef>
1204 <paramdef>int<parameter> major_opcode_check</parameter></paramdef>
1205 <paramdef>int<parameter> error_length</parameter></paramdef>
1206 <paramdef>char<parameter> *error_string_ret</parameter></paramdef>
1210 <variablelist remap='IP'>
1212 <term><emphasis remap='I'>network_ids_list</emphasis></term>
1215 Specifies the network ID(s) of the other client.
1220 <term><emphasis remap='I'>context</emphasis></term>
1223 A pointer to an opaque object or NULL. Used to determine if an
1224 ICE connection can be shared (see below).
1229 <term><emphasis remap='I'>must_authenticate</emphasis></term>
1232 If <function>True</function> the other client may not bypass authentication.
1237 <term><emphasis remap='I'>major_opcode_check</emphasis></term>
1240 Used to force a new ICE connection to be created (see below).
1245 <term><emphasis remap='I'>error_length</emphasis></term>
1247 <para>Length of the error_string_ret argument passed in.</para>
1251 <term><emphasis remap='I'>error_string_ret</emphasis></term>
1254 Returns a null-terminated error message, if any. The error_string_ret
1255 argument points to user supplied memory. No more than error_length bytes
1264 <function>IceOpenConnection</function>
1265 returns an opaque ICE connection object if it succeeds;
1266 otherwise, it returns NULL.
1270 The network_ids_list argument contains a list of network IDs separated
1271 by commas. An attempt will be made to use the first network ID. If
1272 that fails, an attempt will be made using the second network ID, and so on.
1273 Each network ID has the following format:
1276 <informaltable pgwide='0' frame='none'>
1277 <tgroup cols='3' align='center'>
1278 <colspec colname='c1'/>
1279 <colspec colname='c2'/>
1280 <colspec colname='c3'/>
1283 <entry align='left'></entry>
1284 <entry align='left'>tcp/<hostname>:<portnumber></entry>
1285 <entry align='left'>or</entry>
1288 <entry align='left'></entry>
1289 <entry align='left'>decnet/<hostname>::<objname></entry>
1290 <entry align='left'>or</entry>
1293 <entry align='left'></entry>
1294 <entry align='left'>local/<hostname>:<path></entry>
1295 <entry align='left'></entry>
1302 <para>Most protocol libraries will have some sort of open function that should
1303 internally make a call into
1304 <function>IceOpenConnection</function>
1306 <function>IceOpenConnection</function>
1307 is called, it may be possible to use a previously opened ICE connection (if
1308 the target client is the same). However, there are cases in which shared
1309 ICE connections are not desired.</para>
1311 <para>The context argument is used to determine if an ICE connection can
1314 then the caller is always willing to share the connection.
1315 If context is not NULL,
1316 then the caller is not willing to use a previously opened ICE connection
1317 that has a different non-NULL context associated with it.</para>
1319 <para>In addition, if major_opcode_check contains a nonzero major opcode value,
1320 a previously created ICE connection will be used only if the major opcode
1321 is not active on the connection. This can be used to force multiple ICE
1322 connections between two clients for the same protocol.</para>
1324 <para>Any authentication requirements are handled internally by the ICE library.
1325 The method by which the authentication data is obtained
1326 is implementation-dependent.
1327 <footnote remap='FS'>
1328 <para>The X Consortium's ICElib implementation uses an .ICEauthority file (see
1330 </para></footnote> </para>
1333 <function>IceOpenConnection</function>
1334 is called, the client is ready to send a
1335 <function>ProtocolSetup</function>
1337 <function>IceRegisterForProtocolSetup</function>
1338 was called) or receive a
1339 <function>ProtocolSetup</function>
1341 <function>IceRegisterForProtocolReply</function>
1345 <sect1 id='listening_for_ice_connections'>
1346 <title>Listening for ICE Connections</title>
1348 <para>Clients wishing to accept ICE connections must first call
1349 <function>IceListenForConnections</function>
1351 <function>IceListenForWellKnownConnections</function>
1352 so that they can listen for connections. A list of opaque "listen" objects are
1353 returned, one for each type of transport method that is available
1354 (for example, Unix Domain, TCP, DECnet, and so on).</para>
1356 <para>Normally clients will let ICElib allocate an available name in each
1357 transport and return listen objects. Such a client will then use
1358 <function>IceComposeNetworkIdList</function>
1359 to extract the chosen names and make them
1360 available to other clients for opening the connection. In certain
1361 cases it may be necessary for a client to listen for connections
1362 on pre-arranged transport object names. Such a client may use
1363 <function>IceListenForWellKnownConnections</function>
1364 to specify the names for the listen objects.</para>
1368 <funcdef>Status <function>IceListenForConnections</function></funcdef>
1369 <paramdef>int<parameter> *count_ret</parameter></paramdef>
1370 <paramdef>IceListenObj<parameter> **listen_objs_ret</parameter></paramdef>
1371 <paramdef>int<parameter> error_length</parameter></paramdef>
1372 <paramdef>char<parameter> *error_string_ret</parameter></paramdef>
1376 <variablelist remap='IP'>
1378 <term><emphasis remap='I'>count_ret</emphasis></term>
1379 <listitem><para>Returns the number of listen objects created.</para></listitem>
1382 <term><emphasis remap='I'>listen_objs_ret</emphasis></term>
1383 <listitem><para>Returns a list of pointers to opaque listen objects.</para></listitem>
1386 <term><emphasis remap='I'>error_length</emphasis></term>
1388 <para>The length of the error_string_ret argument passed in.</para>
1392 <term><emphasis remap='I'>error_string_ret</emphasis></term>
1394 <para>Returns a null-terminated error message, if any.
1395 The error_string_ret points to user supplied memory.
1396 No more than error_length bytes are used.</para>
1402 <para>The return value of
1403 <function>IceListenForConnections</function>
1404 is zero for failure and a positive value for success.</para>
1408 <funcdef>Status <function>IceListenForWellKnownConnections</function></funcdef>
1409 <paramdef>char<parameter> *port_id</parameter></paramdef>
1410 <paramdef>int<parameter> *count_ret</parameter></paramdef>
1411 <paramdef>IceListenObj<parameter> **listen_objs_ret</parameter></paramdef>
1412 <paramdef>int<parameter> error_length</parameter></paramdef>
1413 <paramdef>char<parameter> *error_string_ret</parameter></paramdef>
1417 <variablelist remap='IP'>
1419 <term><emphasis remap='I'>port_id</emphasis></term>
1422 Specifies the port identification for the address(es) to be opened. The
1423 value must not contain the slash ("/"> or comma (".") character; thse are
1424 reserved for future use.
1429 <term><emphasis remap='I'>count_ret</emphasis></term>
1431 <para>Returns the number of listen objects created.</para>
1435 <term><emphasis remap='I'>listen_objs_ret</emphasis></term>
1438 Returns a list of pointers to opaque listen objects.
1443 <term><emphasis remap='I'>listen_objs_ret</emphasis></term>
1446 Returns a list of pointers to opaque listen objects.
1451 <term><emphasis remap='I'>error_length</emphasis></term>
1454 The length of the error_string_ret argument passed in.
1459 <term><emphasis remap='I'>error_string_ret</emphasis></term>
1462 Returns a null-terminated error message, if any. The error_string_ret
1463 points to user supplied memory. No more than error_length bytes are used.
1470 <function>IceListenForWellKnownConnections</function> constructs a list
1471 of network IDs by prepending each known transport to port_id and then
1472 attempts to create listen objects for the result. Port_id is the portnumber,
1473 objname, or path portion of the ICE network ID. If a listen object for
1474 a particular network ID cannot be created the network ID is ignored.
1475 If no listen objects are created
1476 <function>IceListenForWellKnownConnections</function>
1481 The return value of <function>IceListenForWellKnownConnections</function>
1482 is zero for failure and a positive value for success.
1486 To close and free the listen objects, use
1487 <function>IceFreeListenObjs</function>
1492 <funcdef>void <function>IceFreeListenObjs</function></funcdef>
1493 <paramdef>int<parameter> count</parameter></paramdef>
1494 <paramdef>IceListenObj<parameter> *listen_objs</parameter></paramdef>
1498 <variablelist remap='IP'>
1500 <term><emphasis remap='I'>count</emphasis></term>
1502 <para>The number of listen objects.</para>
1506 <term><emphasis remap='I'>listen_objs</emphasis></term>
1508 <para>The listen objects.</para>
1515 To detect a new connection on a listen object, use
1516 <function>select</function> on the descriptor associated with
1521 To obtain the descriptor, use
1522 <function>IceGetListenConnectionNumber</function>
1527 <funcdef>int <function>IceGetListenConnectionNumber</function></funcdef>
1528 <paramdef>IceListenObj<parameter> *listen_objs</parameter></paramdef>
1532 <variablelist remap='IP'>
1534 <term><emphasis remap='I'>listen_obj</emphasis></term>
1536 <para>The listen objects.</para>
1542 To obtain the network ID string associated with a listen object, use
1543 <function>IceGetListenConnectionString</function>
1549 <funcdef>char <function>IceGetListenConnectionString</function></funcdef>
1550 <paramdef>IceListenObj<parameter> listen_obj</parameter></paramdef>
1554 <variablelist remap='IP'>
1556 <term><emphasis remap='I'>listen_obj</emphasis></term>
1558 <para>The listen objects.</para>
1563 <para>A network ID has the following format:</para>
1565 <informaltable pgwide='0' frame='none'>
1566 <tgroup cols='3' align='center'>
1567 <colspec colname='c1'/>
1568 <colspec colname='c2'/>
1569 <colspec colname='c3'/>
1572 <entry align='left'></entry>
1573 <entry align='left'>tcp/<hostname>:<portnumber></entry>
1574 <entry align='left'>or</entry>
1577 <entry align='left'></entry>
1578 <entry align='left'>decnet/<hostname>::<objname></entry>
1579 <entry align='left'>or</entry>
1582 <entry align='left'></entry>
1583 <entry align='left'>local/<hostname>:<path></entry>
1584 <entry align='left'></entry>
1591 To compose a string containing a list of network IDs separated by commas
1592 (the format recognized by <function>IceOpenConnection</function>
1593 use <function>IceComposeNetworkIdList</function>
1598 <funcdef>char <function>IceComposeNetworkIdList</function></funcdef>
1599 <paramdef>int<parameter> count</parameter></paramdef>
1600 <paramdef>IceListenObj<parameter> *listen_objs</parameter></paramdef>
1604 <variablelist remap='IP'>
1606 <term><emphasis remap='I'>count</emphasis></term>
1608 <para>The number of listen objects.</para>
1612 <term><emphasis remap='I'>listen_objs</emphasis></term>
1614 <para>The listen objects.</para>
1621 <sect1 id='host_based_authentication_for_ice_connec'>
1622 <title>Host Based Authentication for ICE Connections</title>
1625 If authentication fails when a client attempts to open an
1626 ICE connection and the initiating client has not required authentication,
1627 a host based authentication procedure may be invoked to provide
1628 a last chance for the client to connect. Each listen object has such a
1629 callback associated with it, and this callback is set using the
1630 <function>IceSetHostBasedAuthProc</function>
1636 <funcdef>void <function>IceSetHostBasedAuthProc</function></funcdef>
1637 <paramdef>IceListenObj<parameter> listen_obj</parameter></paramdef>
1638 <paramdef>IceHostBasedAuthProc<parameter> host_based_auth_proc</parameter></paramdef>
1642 <variablelist remap='IP'>
1644 <term><emphasis remap='I'>IceListenObj</emphasis></term>
1646 <para>The listen object.</para>
1650 <term><emphasis remap='I'>host_based_auth_proc</emphasis></term>
1652 <para>The host based authentication procedure.</para>
1659 By default, each listen object has no host based authentication procedure
1660 associated with it. Passing NULL for host_based_auth_proc turns off
1661 host based authentication if it was previously set.
1667 <funcdef>Bool <function>HostBasedAuthProc</function></funcdef>
1668 <paramdef>char<parameter> *host_name</parameter></paramdef>
1672 <variablelist remap='IP'>
1674 <term><emphasis remap='I'>host_name</emphasis></term>
1677 The host name of the client that tried to open an ICE connection.
1685 The host_name argument is a string in the form
1686 <emphasis remap='I'>protocol</emphasis>/
1687 <emphasis remap='I'>hostname</emphasis>,
1688 where <emphasis remap='I'>protocol</emphasis> is one of
1689 {tcp, decnet, local}.
1693 If <function>IceHostBasedAuthProc</function> returns
1694 <function>True</function>
1695 access will be granted, even though the original authentication failed.
1696 Note that authentication can effectively be disabled by registering an
1697 <function>IceHostBasedAuthProc</function>
1698 which always returns <function>True</function>
1702 Host based authentication is also allowed at
1703 <function>ProtocolSetup</function> time.
1704 The callback is specified in the
1705 <function>IceRegisterForProtocolReply</function>
1707 <link linkend="protocol_registration">
1708 <xref linkend="protocol_registration"></xref></link>).
1712 <sect1 id='accepting_ice_connections'>
1713 <title>Accepting ICE Connections</title>
1717 After a connection attempt is detected on a listen object returned by
1718 <function>IceListenForConnections</function>
1719 you should call <function>IceAcceptConnection</function>
1720 This returns a new opaque ICE connection object.
1725 <funcdef>IceConn <function>IceAcceptConnection</function></funcdef>
1726 <paramdef>IceListenObj<parameter> listen_obj</parameter></paramdef>
1727 <paramdef>IceAcceptStatus<parameter> *status_ret</parameter></paramdef>
1732 <variablelist remap='IP'>
1734 <term><emphasis remap='I'>listen_obj</emphasis></term>
1736 <para>The listen object on which a new connection was detected.</para>
1740 <variablelist remap='IP'>
1742 <term><emphasis remap='I'>status_ret</emphasis></term>
1744 <para>Return status information.</para>
1750 <para>The status_ret argument is set to one of the following values:</para>
1753 <para><function>IceAcceptSuccess</function>
1754 - the accept operation succeeded,
1755 and the function returns a new connection object.</para>
1758 <para><function>IceAcceptFailure</function>
1759 - the accept operation failed, and the function returns NULL.</para>
1762 <para><function>IceAcceptBadMalloc</function>
1763 - a memory allocation failed, and the function returns NULL.</para>
1767 <para>In general, to detect new connections, you should call
1768 <function>select</function>
1769 on the file descriptors associated with the listen objects.
1770 When a new connection is detected, the
1771 <function>IceAcceptConnection</function>
1772 function should be called.
1773 <function>IceAcceptConnection</function>
1774 may return a new ICE connection that is in a pending state. This is because
1775 before the connection can become valid, authentication may be necessary.
1776 Because the ICE library cannot block and wait for the connection to
1777 become valid (infinite blocking can occur if the connecting client
1778 does not act properly), the application must wait for the connection status
1779 to become valid.</para>
1781 <para>The following pseudo-code demonstrates how connections are accepted:</para>
1783 <literallayout class="monospaced">
1784 new_ice_conn = IceAcceptConnection (listen_obj, &accept_status);
1785 if (accept_status != IceAcceptSuccess)
1787 close the file descriptor and return
1790 status = IceConnectionStatus (new_ice_conn);
1791 time_start = time_now;
1793 while (status == IceConnectPending)
1795 select() on {new_ice_conn, all open connections}
1797 for (each ice_conn in the list of open connections)
1798 if (data ready on ice_conn)
1800 status = IceProcessMessages (ice_conn, NULL, NULL);
1801 if (status == IceProcessMessagesIOError)
1802 IceCloseConnection(ice_conn);
1804 if data ready on new_ice_conn
1807 * IceProcessMessages is called until the connection
1808 * is non-pending. Doing so handles the connection
1809 * setup request and any authentication requirements.
1812 IceProcessMessages ( new_ice_conn, NULL, NULL);
1813 status = IceConnectionStatus (new_ice_conn);
1817 if (time_now - time_start > MAX_WAIT_TIME)
1818 status = IceConnectRejected;
1822 if (status == IceConnectAccepted)
1824 Add new_ice_conn to the list of open connections
1834 <function>IceAcceptConnection</function>
1835 is called and the connection has been
1836 validated, the client is ready to receive a
1837 <function>ProtocolSetup</function>
1840 <function>IceRegisterForProtocolReply</function>
1841 was called) or send a
1842 <function>ProtocolSetup</function>
1844 <function>IceRegisterForProtocolSetup</function>
1848 <sect1 id='closing_ice_connections'>
1849 <title>Closing ICE Connections</title>
1851 <para>To close an ICE connection created with
1852 <function>IceOpenConnection</function>
1854 <function>IceAcceptConnection</function>
1856 <function>IceCloseConnection</function></para>
1860 <funcdef>IceCloseStatus <function>IceCloseConnection</function></funcdef>
1861 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
1865 <variablelist remap='IP'>
1867 <term><emphasis remap='I'>ice_conn</emphasis></term>
1869 <para>The ICE connection to close.</para>
1874 <para>To actually close an ICE connection, the following conditions
1879 <para>The <emphasis remap='I'>open reference count</emphasis> must have reached zero on this ICE connection.
1881 <function>IceOpenConnection</function>
1882 is called, it tries to use a previously opened
1883 ICE connection. If it is able to use an existing connection, it increments
1884 the open reference count on the connection by one.
1885 So, to close an ICE connection, each call to
1886 <function>IceOpenConnection</function>
1887 must be matched with a call to
1888 <function>IceCloseConnection</function>
1889 The connection can be closed only
1891 <function>IceCloseConnection</function></para>
1894 <para>The <emphasis remap='I'>active protocol count</emphasis> must have reached zero. Each time a
1895 <function>ProtocolSetup</function>
1896 succeeds on the connection, the active protocol count
1897 is incremented by one. When the client no longer expects to use the
1898 protocol on the connection, the
1899 <function>IceProtocolShutdown</function>
1900 function should be called, which decrements the active protocol count
1902 <link linkend="protocol_setup_and_shutdown">
1903 <xref linkend="protocol_setup_and_shutdown"></xref></link>).
1907 <para>If shutdown negotiation is enabled on the connection, the client on the other
1908 side of the ICE connection must agree to have the connection closed.</para>
1910 <para><function>IceCloseConnection</function>
1911 returns one of the following values:</para>
1914 <para><function>IceClosedNow</function>
1915 - the ICE connection was closed at this time. The watch procedures were
1916 invoked and the connection was freed.</para>
1919 <para><function>IceClosedASAP</function>
1920 - an IO error had occurred on the connection, but
1921 <function>IceCloseConnection</function>
1922 is being called within a nested
1923 <function>IceProcessMessages</function>
1924 The watch procedures have been invoked at this time, but the connection
1925 will be freed as soon as possible (when the nesting level reaches zero and
1926 <function>IceProcessMessages</function>
1928 <function>IceProcessMessagesConnectionClosed</function></para>
1931 <para><function>IceConnectionInUse</function>
1932 - the connection was not closed at this time, because it is being used by
1933 other active protocols.</para>
1936 <para><function>IceStartedShutdownNegotiation</function>
1937 - the connection was not closed at this time and shutdown negotiation started
1938 with the client on the other side of the ICE connection. When the connection
1940 <function>IceProcessMessages</function>
1941 will return a status of
1942 <function>IceProcessMessagesConnectionClosed</function></para>
1946 <para>When it is known that the client on the other side of the ICE connection
1947 has terminated the connection without initiating shutdown negotiation, the
1948 <function>IceSetShutdownNegotiation</function>
1949 function should be called to turn off shutdown negotiation. This will prevent
1950 <function>IceCloseConnection</function>
1951 from writing to a broken connection.</para>
1955 <funcdef>void <function>IceSetShutdownNegotiation</function></funcdef>
1956 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
1957 <paramdef>Bool<parameter> negotiate</parameter></paramdef>
1961 <variablelist remap='IP'>
1963 <term><emphasis remap='I'>ice_conn</emphasis></term>
1965 <para>A valid ICE connection object.</para>
1969 <term><emphasis remap='I'>negotiate</emphasis></term>
1972 <function>False</function>
1973 shutdown negotiating will be turned off.</para>
1978 <para>To check the shutdown negotiation status of an ICE connection, use
1979 <function>IceCheckShutdownNegotiation</function></para>
1983 <funcdef>Bool <function>IceCheckShutdownNegotiation</function></funcdef>
1984 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
1988 <variablelist remap='IP'>
1990 <term><emphasis remap='I'>ice_conn</emphasis></term>
1992 <para>A valid ICE connection object.</para>
1998 <para><function>IceCheckShutdownNegotiation</function>
2000 <function>True</function>
2001 if shutdown negotiation will take place on the connection;
2002 otherwise, it returns
2003 <function>False</function>
2004 Negotiation is on by default for a connection. It
2005 can only be changed with the
2006 <function>IceSetShutdownNegotiation</function>
2010 <sect1 id='connection_watch_procedures'>
2011 <title>Connection Watch Procedures</title>
2013 <para>To add a watch procedure that will be called
2014 each time ICElib opens a new connection via
2015 <function>IceOpenConnection</function>
2017 <function>IceAcceptConnection</function>
2018 or closes a connection via
2019 <function>IceCloseConnection</function>
2021 <function>IceAddConnectionWatch</function></para>
2025 <funcdef>Status <function>IceAddConnectionWatch</function></funcdef>
2026 <paramdef>IceWatchProc<parameter> watch_proc</parameter></paramdef>
2027 <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
2031 <variablelist remap='IP'>
2033 <term><emphasis remap='I'>watch_proc</emphasis></term>
2036 The watch procedure to invoke when ICElib opens or closes a connection.
2041 <term><emphasis remap='I'>client_data</emphasis></term>
2043 <para>This pointer will be passed to the watch procedure.</para>
2050 The return value of <function>IceAddConnectionWatch</function>
2051 is zero for failure, and a positive value for success.
2055 Note that several calls to <function>IceOpenConnection</function>
2056 might share the same ICE connection. In such a case, the watch procedure
2057 is only invoked when the connection is first created (after authentication
2058 succeeds). Similarly, because connections might be shared, the
2059 watch procedure is called only if <function>IceCloseConnection</function>
2060 actually closes the connection (right before the IceConn is freed).
2064 The watch procedures are very useful for applications that
2065 need to add a file descriptor to a select mask when a new connection
2066 is created and remove the file descriptor when the connection is destroyed.
2067 Because connections are shared, knowing when to add and remove the file
2068 descriptor from the select mask would be difficult without the watch
2073 Multiple watch procedures may be registered with the ICE library.
2074 No assumptions should be made about their order of invocation.
2078 If one or more ICE connections were already created by the ICE library at the
2079 time the watch procedure is registered, the watch procedure will instantly
2080 be invoked for each of these ICE connections (with the opening argument
2081 set to <function>True</function>
2085 The watch procedure is of type <function>IceWatchProc</function>
2090 <funcdef>void <function>WatchProc</function></funcdef>
2091 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2092 <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
2093 <paramdef>Bool<parameter> opening</parameter></paramdef>
2094 <paramdef>IcePointer<parameter> *watch_data</parameter></paramdef>
2098 <variablelist remap='IP'>
2100 <term><emphasis remap='I'>ice_conn</emphasis></term>
2103 The opened or closed ICE connection. Call
2104 <function>IceConnectionNumber</function>
2105 to get the file descriptor associated with this connection.
2110 <term><emphasis remap='I'>client_data</emphasis></term>
2113 Client data specified in the call to
2114 <function>IceAddConnectionWatch</function>
2119 <term><emphasis remap='I'>opening</emphasis></term>
2122 If <function>True</function> the connection is being opened. If
2123 <function>False</function> the connection is being closed.
2128 <term><emphasis remap='I'>watch_data</emphasis></term>
2130 <para>Can be used to save a pointer to client data.</para>
2136 If opening is <function>True</function> the client should set the
2137 *watch_data pointer to any data it may need to save until the connection
2138 is closed and the watch procedure is invoked again with opening set to
2139 <function>False</function>
2143 To remove a watch procedure, use
2144 <function>IceRemoveConnectionWatch</function>
2149 <funcdef>void <function>IceRemoveConnectionWatch</function></funcdef>
2150 <paramdef>IceWatchProc<parameter> watch_proc</parameter></paramdef>
2151 <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
2155 <variablelist remap='IP'>
2157 <term><emphasis remap='I'>watch_proc</emphasis></term>
2160 The watch procedure that was passed to
2161 <function>IceAddConnectionWatch</function>
2166 <term><emphasis remap='I'>client_data</emphasis></term>
2169 The client_data pointer that was passed to
2170 <function>IceAddConnectionWatch</function>
2179 <chapter id='protocol_setup_and_shutdown'>
2180 <title>Protocol Setup and Shutdown</title>
2183 To activate a protocol on a given ICE connection, use
2184 <function>IceProtocolSetup</function>
2189 <funcdef>IceProtocolSetupStatus <function>IceProtocolSetup</function></funcdef>
2190 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2191 <paramdef>int<parameter> my_opcode</parameter></paramdef>
2192 <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
2193 <paramdef>Bool<parameter> must_authenticate</parameter></paramdef>
2194 <paramdef>int<parameter> *major_version_ret</parameter></paramdef>
2195 <paramdef>int<parameter> *minor_version_ret</parameter></paramdef>
2196 <paramdef>char<parameter> **vendor_ret</parameter></paramdef>
2197 <paramdef>char<parameter> **release_ret</parameter></paramdef>
2198 <paramdef>int<parameter> error_length</parameter></paramdef>
2199 <paramdef>char<parameter> *error_string_ret</parameter></paramdef>
2203 <variablelist remap='IP'>
2205 <term><emphasis remap='I'>ice_conn</emphasis></term>
2207 <para>A valid ICE connection object.</para>
2211 <term><emphasis remap='I'>my_opcode</emphasis></term>
2214 The major opcode of the protocol to be set up, as returned by
2215 <function>IceRegisterForProtocolSetup</function>
2220 <term><emphasis remap='I'>client_data</emphasis></term>
2223 The client data stored in this pointer will be passed to the
2224 <function>IcePoProcessMsgProc</function> callback.
2229 <term><emphasis remap='I'>must_authenticate</emphasis></term>
2232 If <function>True</function> the other client may
2233 not bypass authentication.
2238 <term><emphasis remap='I'>major_version_ret</emphasis></term>
2240 <para>The major version of the protocol to be used is returned.</para>
2244 <term><emphasis remap='I'>minor_version_ret</emphasis></term>
2246 <para>The minor version of the protocol to be used is returned.</para>
2250 <term><emphasis remap='I'>vendor_ret</emphasis></term>
2252 <para>The vendor string specified by the protocol acceptor.</para>
2256 <term><emphasis remap='I'>release_ret</emphasis></term>
2258 <para>The release string specified by the protocol acceptor.</para>
2262 <term><emphasis remap='I'>error_length</emphasis></term>
2265 Specifies the length of the error_string_ret argument passed in.
2270 <term><emphasis remap='I'>error_string_ret</emphasis></term>
2273 Returns a null-terminated error message, if any.
2274 The error_string_ret argument points to user supplied memory.
2275 No more than error_length bytes are used.
2282 The vendor_ret and release_ret strings should be freed with
2283 <function>free</function> when no longer needed.
2287 <function>IceProtocolSetup</function> returns one of the following values:
2293 <function>IceProtocolSetupSuccess</function> - the major_version_ret,
2294 minor_version_ret, vendor_ret, release_ret are set.
2299 <function>IceProtocolSetupFailure</function> or
2300 <function>IceProtocolSetupIOError</function>
2301 - check error_string_ret for failure reason. The major_version_ret,
2302 minor_version_ret, vendor_ret, release_ret are not set.
2307 <function>IceProtocolAlreadyActive</function>
2308 - this protocol is already active on this connection.
2309 The major_version_ret, minor_version_ret, vendor_ret, release_ret
2316 To notify the ICE library when a given protocol will no longer be used
2317 on an ICE connection, use <function>IceProtocolShutdown</function>
2322 <funcdef>Status <function>IceProtocolShutdown</function></funcdef>
2323 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2324 <paramdef>int<parameter> major_opcode</parameter></paramdef>
2328 <variablelist remap='IP'>
2330 <term><emphasis remap='I'>ice_conn</emphasis></term>
2332 <para>A valid ICE connection object.</para>
2336 <term><emphasis remap='I'>major_opcode</emphasis></term>
2338 <para>The major opcode of the protocol to shut down.</para>
2345 The return value of <function>IceProtocolShutdown</function>
2346 is zero for failure and a positive value for success.
2350 Failure will occur if the major opcode was never registered OR the protocol
2351 of the major opcode was never activated on the connection. By activated,
2352 we mean that a <function>ProtocolSetup</function> succeeded on the connection.
2353 Note that ICE does not define how each sub-protocol triggers a
2358 <chapter id='processing_messages'>
2359 <title>Processing Messages</title>
2362 <para>To process incoming messages on an ICE connection, use
2363 <function>IceProcessMessages</function></para>
2367 <funcdef>IceProcessMessagesStatus <function>IceProcessMessages</function></funcdef>
2368 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2369 <paramdef>IceReplyWaitInfo<parameter> *reply_wait</parameter></paramdef>
2370 <paramdef>Bool<parameter> *reply_ready_ret</parameter></paramdef>
2374 <variablelist remap='IP'>
2376 <term><emphasis remap='I'>ice_conn</emphasis></term>
2378 <para>A valid ICE connection object.</para>
2382 <term><emphasis remap='I'>reply_wait</emphasis></term>
2384 <para>Indicates if a reply is being waited for.</para>
2388 <term><emphasis remap='I'>reply_ready_ret</emphasis></term>
2391 If set to <function>True</function> on return, a reply is ready.
2398 <function>IceProcessMessages</function> is used in two ways:
2404 In the first, a client may generate a message and block by calling
2405 <function>IceProcessMessages</function> repeatedly until it gets its reply.
2410 In the second, a client calls <function>IceProcessMessages</function>
2411 with reply_wait set to NULL in response to <function>select</function>
2412 showing that there is data to read on the ICE connection.
2413 The ICE library may process zero or more complete messages.
2414 Note that messages that are not blocked for are always processed by
2421 <function>IceReplyWaitInfo</function> contains the major/minor opcodes
2422 and sequence number of the message for which a reply is being awaited.
2423 It also contains a pointer to the reply message to be filled in (the
2424 protocol library should cast this <function>IcePointer</function>
2425 to the appropriate reply type). In most
2426 cases, the reply will have some fixed-size part, and the client waiting
2427 for the reply will have provided a pointer to a structure to hold
2428 this fixed-size data. If there is variable-length data, it would be
2430 <function>IcePoProcessMsgProc</function>
2431 callback will have to allocate additional
2432 memory and store pointer(s) to that memory in the fixed-size
2433 structure. If the entire data is variable length (for example, a single
2434 variable-length string), then the client waiting for the reply would probably
2435 just pass a pointer to fixed-size space to hold a pointer, and the
2436 <function>IcePoProcessMsgProc</function>
2437 callback would allocate the storage and store the pointer.
2438 It is the responsibility of the client receiving the reply to
2439 free up any memory allocated on its behalf.
2442 <literallayout class="monospaced">
2444 unsigned long sequence_of_request;
2445 int major_opcode_of_request;
2446 int minor_opcode_of_request;
2452 If reply_wait is not NULL and
2453 <function>IceProcessMessages</function>
2454 has a reply or error to return in response to this reply_wait
2455 (that is, no callback was generated), then the reply_ready_ret argument
2456 will be set to <function>True</function>
2460 If reply_wait is NULL, then the caller may also pass NULL for
2461 reply_ready_ret and be guaranteed that no value will be stored in
2466 <function>IceProcessMessages</function> returns one of the following values:
2472 <function>IceProcessMessagesSuccess</function> - no error occurred.
2477 <function>IceProcessMessagesIOError</function> - an IO error occurred,
2478 and the caller must explicitly close the connection by calling
2479 <function>IceCloseConnection</function>
2484 <function>IceProcessMessagesConnectionClosed</function>
2485 - the ICE connection has been closed (closing of the connection was deferred
2486 because of shutdown negotiation, or because the
2487 <function>IceProcessMessages</function>
2488 nesting level was not zero). Do not attempt
2489 to access the ICE connection at this point, since it has been freed.
2500 To send a "Ping" message to the client on the other side of the
2501 ICE connection, use <function>IcePing</function>
2506 <funcdef>Status <function>IcePing</function></funcdef>
2507 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2508 <paramdef>IcePingReplyProc<parameter> ping_reply_proc</parameter></paramdef>
2509 <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
2513 <variablelist remap='IP'>
2515 <term><emphasis remap='I'>ice_conn</emphasis></term>
2517 <para>A valid ICE connection object.</para>
2521 <term><emphasis remap='I'>ping_reply_proc</emphasis></term>
2523 <para>The callback to invoke when the Ping reply arrives.</para>
2527 <term><emphasis remap='I'>client_data</emphasis></term>
2530 This pointer will be passed to the <function>IcePingReplyProc</function>
2538 <para><function>IcePing</function>
2539 returns zero for failure and a positive value for success.</para>
2542 <function>IceProcessMessages</function>
2543 processes the Ping reply, it will invoke the
2544 <function>IcePingReplyProc</function>
2549 <funcdef>void <function>PingReplyProc</function></funcdef>
2550 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2551 <paramdef>IcePointer<parameter> client_data</parameter></paramdef>
2555 <variablelist remap='IP'>
2557 <term><emphasis remap='I'>ice_conn</emphasis></term>
2559 <para>A valid ICE connection object.</para>
2563 <term><emphasis remap='I'>client_data</emphasis></term>
2565 <para>The client data specified in the call to
2566 <function>IcePing</function></para>
2573 <chapter id='using_icelib_informational_functions'>
2574 <title>Using ICElib Informational Functions</title>
2578 <funcdef>IceConnectStatus <function>IceConnectionStatus</function></funcdef>
2579 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2583 <para><function>IceConnectionStatus</function>
2584 returns the status of an ICE connection. The possible return values are:</para>
2588 <para><function>IceConnectPending</function>
2589 - the connection is not valid yet (that is, authentication is taking place).
2590 This is only relevant to connections created by
2591 <function>IceAcceptConnection</function></para>
2594 <para><function>IceConnectAccepted</function>
2595 - the connection has been accepted.
2596 This is only relevant to connections created by
2597 <function>IceAcceptConnection</function></para>
2600 <para><function>IceConnectRejected</function>
2601 - the connection had been rejected (that is, authentication failed).
2602 This is only relevant to connections created by
2603 <function>IceAcceptConnection</function></para>
2606 <para><function>IceConnectIOError</function>
2607 - an IO error has occurred on the connection.</para>
2613 <funcdef>char <function> *IceVendor</function></funcdef>
2614 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2618 <para><function>IceVendor</function>
2619 returns the ICE library vendor identification
2620 for the other side of the connection.
2621 The string should be freed with a call to
2622 <function>free</function>
2623 when no longer needed.</para>
2627 <funcdef>char <function> *IceRelease</function></funcdef>
2628 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2632 <para><function>IceRelease</function>
2633 returns the release identification of the ICE library
2634 on the other side of the connection.
2635 The string should be freed with a call to
2636 <function>free</function>
2637 when no longer needed.</para>
2641 <funcdef>int <function> IceProtocolVersion</function></funcdef>
2642 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2646 <para><function>IceProtocolVersion</function>
2647 returns the major version of the ICE protocol on this connection.</para>
2651 <funcdef>int <function> IceProtocolRevision</function></funcdef>
2652 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2657 <para><function>IceProtocolRevision</function>
2658 returns the minor version of the ICE protocol on this connection.</para>
2662 <funcdef>int <function> IceConnectionNumber</function></funcdef>
2663 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2668 <para><function>IceConnectionNumber</function>
2669 returns the file descriptor of this ICE connection.</para>
2673 <funcdef>char <function> *IceConnectionString</function></funcdef>
2674 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2678 <para><function>IceConnectionString</function>
2679 returns the network ID of the client that
2680 accepted this connection. The string should be freed with a call to
2681 <function>free</function>
2682 when no longer needed.</para>
2686 <funcdef>unsigned long <function> IceLastSentSequenceNumber</function></funcdef>
2687 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2692 <para><function>IceLastSentSequenceNumber</function>
2693 returns the sequence number of the last message sent on this ICE connection.</para>
2697 <funcdef>unsigned long <function> IceLastReceivedSequenceNumber</function></funcdef>
2698 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2702 <para><function>IceLastReceivedSequenceNumber</function>
2703 returns the sequence number of the last message received on this
2704 ICE connection.</para>
2708 <funcdef>Bool <function> IceSwapping</function></funcdef>
2709 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2714 <para><function>IceSwapping</function>
2716 <function>True</function>
2717 if byte swapping is necessary when reading messages on the ICE connection.</para>
2721 <funcdef>IcePointer <function> IceGetContext</function></funcdef>
2722 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2726 <para><function>IceGetContext</function>
2727 returns the context associated with a connection created by
2728 <function>IceOpenConnection</function></para>
2731 <chapter id='ice_messages'>
2732 <title>ICE Messages</title>
2735 All ICE messages have a standard 8-byte header. The ICElib macros that
2736 read and write messages rely on the following naming convention for message
2740 <literallayout class='monospaced'>
2748 The 3rd and 4th bytes of the message header can be used as needed.
2749 The length field is specified in units of 8 bytes.
2752 <sect1 id='sending_ice_messages'>
2753 <title>Sending ICE Messages</title>
2756 The ICE library maintains an output buffer used for generating messages.
2757 Protocol libraries layered on top of ICE may choose to batch messages
2758 together and flush the output buffer at appropriate times.
2762 If an IO error has occurred on an ICE connection, all write operations
2763 will be ignored. For further information, see
2764 <link linkend="error_handling">
2765 <xref linkend="error_handling"></xref></link>.
2770 To get the size of the ICE output buffer, use
2771 <function>IceGetOutBufSize</function>
2776 <funcdef>int <function> IceGetOutBufSize</function></funcdef>
2777 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2781 <variablelist remap='IP'>
2783 <term><emphasis remap='I'>ice_conn</emphasis></term>
2785 <para>A valid ICE connection object.</para>
2792 To flush the ICE output buffer, use <function>IceFlush</function>
2797 <funcdef>int <function> IceFlush</function></funcdef>
2798 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2802 <variablelist remap='IP'>
2804 <term><emphasis remap='I'>ice_conn</emphasis></term>
2806 <para>A valid ICE connection object.</para>
2812 Note that the output buffer may be implicitly flushed if there is
2813 insufficient space to generate a message.
2816 <para>The following macros can be used to generate ICE messages:</para>
2820 <funcdef><function> IceGetHeader</function></funcdef>
2821 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2822 <paramdef>int<parameter> major_opcode</parameter></paramdef>
2823 <paramdef>int<parameter> minor_opcode</parameter></paramdef>
2824 <paramdef>int<parameter> header_size</parameter></paramdef>
2825 <paramdef><C_data_type><parameter> *pmsg</parameter></paramdef>
2829 <variablelist remap='IP'>
2831 <term><emphasis remap='I'>ice_conn</emphasis></term>
2833 <para>A valid ICE connection object.</para>
2837 <term><emphasis remap='I'>major_opcode</emphasis></term>
2839 <para>The major opcode of the message.</para>
2843 <term><emphasis remap='I'>minor_opcode</emphasis></term>
2845 <para>The minor opcode of the message.</para>
2849 <term><emphasis remap='I'>header_size</emphasis></term>
2851 <para>The size of the message header (in bytes).</para>
2855 <term><emphasis remap='I'><C_data_type></emphasis></term>
2857 <para>The actual C data type of the message header.</para>
2861 <term><emphasis remap='I'>pmsg</emphasis></term>
2864 The message header pointer. After this macro is called, the
2865 library can store data in the message header.
2873 <function>IceGetHeader</function>
2874 is used to set up a message header on an ICE connection.
2875 It sets the major and minor opcodes of the message, and initializes
2876 the message's length to the length of the header. If additional
2877 variable length data follows, the message's length field should be
2884 <funcdef><function> IceGetHeaderExtra</function></funcdef>
2885 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2886 <paramdef>int<parameter> major_opcode</parameter></paramdef>
2887 <paramdef>int<parameter> minor_opcode</parameter></paramdef>
2888 <paramdef>int<parameter> header_size</parameter></paramdef>
2889 <paramdef>int<parameter> extra</parameter></paramdef>
2890 <paramdef><C_data_type><parameter> *pmsg</parameter></paramdef>
2891 <paramdef>char<parameter> *pdata</parameter></paramdef>
2895 <variablelist remap='IP'>
2897 <term><emphasis remap='I'>ice_conn</emphasis></term>
2899 <para>A valid ICE connection object.</para>
2903 <term><emphasis remap='I'>major_opcode</emphasis></term>
2905 <para>The major opcode of the message.</para>
2909 <term><emphasis remap='I'>minor_opcode</emphasis></term>
2911 <para>The minor opcode of the message.</para>
2915 <term><emphasis remap='I'>header_size</emphasis></term>
2917 <para>The size of the message header (in bytes).</para>
2921 <term><emphasis remap='I'>extra</emphasis></term>
2924 The size of the extra data beyond the header (in 8-byte units).
2929 <term><emphasis remap='I'><C_data_type></emphasis></term>
2931 <para>The actual C data type of the message header.</para>
2935 <term><emphasis remap='I'>pmsg</emphasis></term>
2938 The message header pointer. After this macro is called, the
2939 library can store data in the message header.
2944 <term><emphasis remap='I'>pdata</emphasis></term>
2947 Returns a pointer to the ICE output buffer that points
2948 immediately after the message header. The variable length
2949 data should be stored here. If there was not enough room
2950 in the ICE output buffer, pdata is set to NULL.
2958 <function>IceGetHeaderExtra</function>
2959 is used to generate a message with a fixed (and relatively small) amount
2960 of variable length data. The complete message must fit in the ICE output
2966 <funcdef><function> IceSimpleMessage</function></funcdef>
2967 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
2968 <paramdef>int<parameter> major_opcode</parameter></paramdef>
2969 <paramdef>int<parameter> minor_opcode</parameter></paramdef>
2973 <variablelist remap='IP'>
2975 <term><emphasis remap='I'>ice_conn</emphasis></term>
2977 <para>A valid ICE connection object.</para>
2981 <term><emphasis remap='I'>major_opcode</emphasis></term>
2983 <para>The major opcode of the message.</para>
2987 <term><emphasis remap='I'>minor_opcode</emphasis></term>
2989 <para>The minor opcode of the message.</para>
2995 <function>IceSimpleMessage</function>
2996 is used to generate a message that is identical
2997 in size to the ICE header message, and has no additional data.
3002 <funcdef><function> IceErrorHeader</function></funcdef>
3003 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3004 <paramdef>int<parameter> offending_major_opcode</parameter></paramdef>
3005 <paramdef>int<parameter> offending_minor_opcode</parameter></paramdef>
3006 <paramdef>int<parameter> offending_sequence_num</parameter></paramdef>
3007 <paramdef>int<parameter> severity</parameter></paramdef>
3008 <paramdef>int<parameter> error_class</parameter></paramdef>
3009 <paramdef>int<parameter> data_length</parameter></paramdef>
3013 <variablelist remap='IP'>
3015 <term><emphasis remap='I'>ice_conn</emphasis></term>
3017 <para>A valid ICE connection object.</para>
3021 <term><emphasis remap='I'>offending_major_opcode</emphasis></term>
3024 The major opcode of the protocol in which an error was detected.
3029 <term><emphasis remap='I'>offending_minor_opcode</emphasis></term>
3032 The minor opcode of the protocol in which an error was detected.
3037 <term><emphasis remap='I'>offending_sequence_num</emphasis></term>
3039 <para>The sequence number of the message that caused the error.</para>
3043 <term><emphasis remap='I'>severity</emphasis></term>
3046 <function>IceCanContinue</function>
3047 <function>IceFatalToProtocol</function>
3049 <function>IceFatalToConnection</function>
3054 <term><emphasis remap='I'>error_class</emphasis></term>
3056 <para>The error class.</para>
3060 <term><emphasis remap='I'>data_length</emphasis></term>
3063 Length of data (in 8-byte units) to be written after the header.
3070 <function>IceErrorHeader</function> sets up an error message header.
3074 Note that the two clients connected by ICE may be using different
3075 major opcodes for a given protocol. The offending_major_opcode passed
3076 to this macro is the major opcode of the protocol for the client
3077 sending the error message.
3081 Generic errors, which are common to all protocols, have classes
3082 in the range 0x8000..0xFFFF.
3083 See the <emphasis remap='I'>Inter-Client Exchange Protocol</emphasis>
3084 standard for more details.
3087 <informaltable pgwide='0' frame='none'>
3088 <tgroup cols='2' align='center'>
3089 <colspec colname='c1'/>
3090 <colspec colname='c2'/>
3093 <entry align='left'>IceBadMinor</entry>
3094 <entry align='left'>0x8000</entry>
3097 <entry align='left'>IceBadState</entry>
3098 <entry align='left'>0x8001</entry>
3101 <entry align='left'>IceBadLength</entry>
3102 <entry align='left'>0x8002</entry>
3105 <entry align='left'>IceBadValue</entry>
3106 <entry align='left'>0x8003</entry>
3112 <para>Per-protocol errors have classes in the range 0x0000-0x7fff.</para>
3115 To write data to an ICE connection, use the
3116 <function>IceWriteData</function> macro. If the data fits into the
3117 ICE output buffer, it is copied there. Otherwise, the ICE output buffer
3118 is flushed and the data is directly sent.
3122 This macro is used in conjunction with
3123 <function>IceGetHeader</function> and
3124 <function>IceErrorHeader</function>
3129 <funcdef><function> IceWriteData</function></funcdef>
3130 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3131 <paramdef>int<parameter> bytes</parameter></paramdef>
3132 <paramdef>char<parameter> *data</parameter></paramdef>
3136 <variablelist remap='IP'>
3138 <term><emphasis remap='I'>ice_conn</emphasis></term>
3140 <para>A valid ICE connection object.</para>
3144 <term><emphasis remap='I'>bytes</emphasis></term>
3146 <para>The number of bytes to write.</para>
3150 <term><emphasis remap='I'>data</emphasis></term>
3152 <para>The data to write.</para>
3159 To write data as 16-bit quantities, use <function>IceWriteData16</function>
3164 <funcdef><function> IceWriteData16</function></funcdef>
3165 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3166 <paramdef>int<parameter> bytes</parameter></paramdef>
3167 <paramdef>char<parameter> *data</parameter></paramdef>
3171 <variablelist remap='IP'>
3173 <term><emphasis remap='I'>ice_conn</emphasis></term>
3175 <para>A valid ICE connection object.</para>
3179 <term><emphasis remap='I'>bytes</emphasis></term>
3181 <para>The number of bytes to write.</para>
3185 <term><emphasis remap='I'>data</emphasis></term>
3187 <para>The data to write.</para>
3193 To write data as 32-bit quantities, use <function>IceWriteData32</function>
3199 <funcdef><function> IceWriteData32</function></funcdef>
3200 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3201 <paramdef>int<parameter> bytes</parameter></paramdef>
3202 <paramdef>char<parameter> *data</parameter></paramdef>
3206 <variablelist remap='IP'>
3208 <term><emphasis remap='I'>ice_conn</emphasis></term>
3210 <para>A valid ICE connection object.</para>
3214 <term><emphasis remap='I'>bytes</emphasis></term>
3216 <para>The number of bytes to write.</para>
3220 <term><emphasis remap='I'>data</emphasis></term>
3222 <para>The data to write.</para>
3228 To write data as 32-bit quantities, use <function>IceWriteData32</function>
3232 To bypass copying data to the ICE output buffer, use
3233 <function>IceSendData</function> to directly send data over the network
3234 connection. If necessary, the ICE output buffer is first flushed.
3239 <funcdef><function> IceSendData</function></funcdef>
3240 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3241 <paramdef>int<parameter> bytes</parameter></paramdef>
3242 <paramdef>char<parameter> *data</parameter></paramdef>
3246 <variablelist remap='IP'>
3248 <term><emphasis remap='I'>ice_conn</emphasis></term>
3250 <para>A valid ICE connection object.</para>
3254 <term><emphasis remap='I'>bytes</emphasis></term>
3256 <para>The number of bytes to send.</para>
3260 <term><emphasis remap='I'>data</emphasis></term>
3262 <para>The data to send.</para>
3269 To force 32-bit or 64-bit alignment, use <function>IceWritePad</function>
3270 A maximum of 7 pad bytes can be specified.
3275 <funcdef><function> IceWritePad</function></funcdef>
3276 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3277 <paramdef>int<parameter> bytes</parameter></paramdef>
3278 <paramdef>char<parameter> *data</parameter></paramdef>
3282 <variablelist remap='IP'>
3284 <term><emphasis remap='I'>ice_conn</emphasis></term>
3286 <para>A valid ICE connection object.</para>
3290 <term><emphasis remap='I'>bytes</emphasis></term>
3292 <para>The number of bytes to write.</para>
3296 <term><emphasis remap='I'>data</emphasis></term>
3298 <para>The number of pad bytes to write.</para>
3305 <sect1 id='reading_ice_messages'>
3306 <title>Reading ICE Messages</title>
3310 The ICE library maintains an input buffer used for reading messages.
3311 If the ICE library chooses to perform nonblocking reads (this is
3312 implementation-dependent), then for every read operation that it makes,
3313 zero or more complete messages may be read into the input buffer. As
3314 a result, for all of the macros described in this section that read
3315 messages, an actual read operation will occur on the connection only if
3316 the data is not already present in the input buffer.
3321 To get the size of the ICE input buffer, use
3322 <function>IceGetInBufSize</function>
3327 <funcdef>int<function> IceGetInBufSize</function></funcdef>
3328 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3332 <variablelist remap='IP'>
3334 <term><emphasis remap='I'>ice_conn</emphasis></term>
3336 <para>A valid ICE connection object.</para>
3342 When reading messages, care must be taken to check for IO errors. If
3343 any IO error occurs in reading any part of a message, the message should
3344 be thrown out. After using any of the macros described below for reading
3345 messages, the <function>IceValidIO</function>
3346 macro can be used to check if an IO error occurred on the
3347 connection. After an IO error has occurred on an ICE connection, all
3348 read operations will be ignored. For further information, see
3349 <link linkend="error_handling">
3350 <xref linkend="error_handling"></xref></link>.
3356 <funcdef>Bool<function> IceValidIO</function></funcdef>
3357 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3361 <variablelist remap='IP'>
3363 <term><emphasis remap='I'>ice_conn</emphasis></term>
3365 <para>A valid ICE connection object.</para>
3370 <para>The following macros can be used to read ICE messages.</para>
3374 <funcdef><function> IceReadSimpleMessage</function></funcdef>
3375 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3376 <paramdef><C_data_type><parameter> *pmsg</parameter></paramdef>
3380 <variablelist remap='IP'>
3382 <term><emphasis remap='I'>ice_conn</emphasis></term>
3384 <para>A valid ICE connection object.</para>
3388 <term><emphasis remap='I'><C_data_type></emphasis></term>
3390 <para>The actual C data type of the message header.</para>
3394 <term><emphasis remap='I'>pmsg</emphasis></term>
3396 <para>This pointer is set to the message header.</para>
3402 <function>IceReadSimpleMessage</function>
3403 is used for messages that are identical in size to the 8-byte ICE header, but
3404 use the spare 2 bytes in the header to encode additional data. Note that the
3405 ICE library always reads in these first 8 bytes, so it can obtain the major
3406 opcode of the message. <function>IceReadSimpleMessage</function>
3407 simply returns a pointer to these 8 bytes; it does not actually read any data
3408 into the input buffer.
3412 For a message with variable length data, there are two ways of reading
3413 the message. One method involves reading the complete message in one
3414 pass using <function>IceReadCompleteMessage</function>
3415 The second method involves reading the message header (note that this may
3416 be larger than the 8-byte ICE header), then reading
3417 the variable length data in chunks (see
3418 <function>IceReadMessageHeader</function> and
3419 <function>IceReadData</function>
3425 <funcdef><function> IceReadCompleteMessage</function></funcdef>
3426 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3427 <paramdef>int<parameter> header_size</parameter></paramdef>
3428 <paramdef><C_data_type><parameter> *pmsg</parameter></paramdef>
3429 <paramdef>char<parameter> *pdata</parameter></paramdef>
3433 <variablelist remap='IP'>
3435 <term><emphasis remap='I'>ice_conn</emphasis></term>
3437 <para>A valid ICE connection object.</para>
3441 <term><emphasis remap='I'>header_size</emphasis></term>
3443 <para>The size of the message header (in bytes).</para>
3447 <term><emphasis remap='I'><C_data_type></emphasis></term>
3449 <para>The actual C data type of the message header.</para>
3453 <term><emphasis remap='I'>pmsg</emphasis></term>
3455 <para>This pointer is set to the message header.</para>
3459 <term><emphasis remap='I'>pdata</emphasis></term>
3462 This pointer is set to the variable length data of the message.
3469 If the ICE input buffer has sufficient space,
3470 <function>IceReadCompleteMessage</function>
3471 will read the complete message into the
3472 ICE input buffer. Otherwise, a buffer will be allocated to hold the
3473 variable length data. After the call, the pdata argument should
3474 be checked against NULL to make sure that there was sufficient memory
3475 to allocate the buffer.
3479 After calling <function>IceReadCompleteMessage</function>
3480 and processing the message, <function>IceDisposeCompleteMessage</function>
3487 <funcdef><function> IceDisposeCompleteMessage</function></funcdef>
3488 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3489 <paramdef>char<parameter> *pdata</parameter></paramdef>
3493 <variablelist remap='IP'>
3495 <term><emphasis remap='I'>ice_conn</emphasis></term>
3497 <para>A valid ICE connection object.</para>
3501 <term><emphasis remap='I'>pdata</emphasis></term>
3504 The pointer to the variable length data returned in
3505 <function>IceReadCompleteMessage</function>
3512 If a buffer had to be allocated to hold the variable length data (because
3513 it did not fit in the ICE input buffer), it is freed here by ICElib.
3519 <funcdef><function> IceReadMessageHeader</function></funcdef>
3520 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3521 <paramdef>int<parameter> header_size</parameter></paramdef>
3522 <paramdef><C_data_type><parameter> *pmsg</parameter></paramdef>
3526 <variablelist remap='IP'>
3528 <term><emphasis remap='I'>ice_conn</emphasis></term>
3530 <para>A valid ICE connection object.</para>
3534 <term><emphasis remap='I'>header_size</emphasis></term>
3536 <para>The size of the message header (in bytes).</para>
3540 <term><emphasis remap='I'><C_data_type></emphasis></term>
3542 <para>The actual C data type of the message header.</para>
3546 <term><emphasis remap='I'>pmsg</emphasis></term>
3548 <para>This pointer is set to the message header.</para>
3554 <function>IceReadMessageHeader</function> reads just the message header.
3555 The rest of the data should be read with the
3556 <function>IceReadData</function>
3557 family of macros. This method of reading a message should be used when the
3558 variable length data must be read in chunks.
3563 To read data directly into a user supplied buffer, use
3564 <function>IceReadData</function>
3569 <funcdef><function> IceReadData</function></funcdef>
3570 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3571 <paramdef>int<parameter> bytes</parameter></paramdef>
3572 <paramdef>char<parameter> *pdata</parameter></paramdef>
3576 <variablelist remap='IP'>
3578 <term><emphasis remap='I'>ice_conn</emphasis></term>
3580 <para>A valid ICE connection object.</para>
3584 <term><emphasis remap='I'>bytes</emphasis></term>
3586 <para>The number of bytes to read.</para>
3590 <term><emphasis remap='I'>pdata</emphasis></term>
3592 <para>The data is read into this user supplied buffer.</para>
3599 To read data as 16-bit quantities, use <function>IceReadData16</function>
3604 <funcdef><function> IceReadData16</function></funcdef>
3605 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3606 <paramdef>Bool<parameter> swap</parameter></paramdef>
3607 <paramdef>int<parameter> bytes</parameter></paramdef>
3608 <paramdef>char<parameter> *pdata</parameter></paramdef>
3612 <variablelist remap='IP'>
3614 <term><emphasis remap='I'>ice_conn</emphasis></term>
3616 <para>A valid ICE connection object.</para>
3620 <term><emphasis remap='I'>swap</emphasis></term>
3623 If <function>True,</function> the values will be byte swapped.
3628 <term><emphasis remap='I'>bytes</emphasis></term>
3630 <para>The number of bytes to read.</para>
3634 <term><emphasis remap='I'>pdata</emphasis></term>
3636 <para>The data is read into this user supplied buffer.</para>
3643 To read data as 32-bit quantities, use <function>IceReadData32</function>
3648 <funcdef><function> IceReadData32</function></funcdef>
3649 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3650 <paramdef>Bool<parameter> swap</parameter></paramdef>
3651 <paramdef>int<parameter> bytes</parameter></paramdef>
3652 <paramdef>char<parameter> *pdata</parameter></paramdef>
3656 <variablelist remap='IP'>
3658 <term><emphasis remap='I'>ice_conn</emphasis></term>
3660 <para>A valid ICE connection object.</para>
3664 <term><emphasis remap='I'>swap</emphasis></term>
3667 If <function>True,</function> the values will be byte swapped.
3672 <term><emphasis remap='I'>bytes</emphasis></term>
3674 <para>The number of bytes to read.</para>
3678 <term><emphasis remap='I'>pdata</emphasis></term>
3680 <para>The data is read into this user supplied buffer.</para>
3685 <para>To force 32-bit or 64-bit alignment, use
3686 <function>IceReadPad</function>
3687 A maximum of 7 pad bytes can be specified.</para>
3691 <funcdef><function> IceReadPad</function></funcdef>
3692 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3693 <paramdef>int<parameter> bytes</parameter></paramdef>
3697 <variablelist remap='IP'>
3699 <term><emphasis remap='I'>ice_conn</emphasis></term>
3701 <para>A valid ICE connection object.</para>
3705 <term><emphasis remap='I'>bytes</emphasis></term>
3707 <para>The number of pad bytes.</para>
3715 <chapter id='error_handling'>
3716 <title>Error Handling</title>
3719 <para>There are two default error handlers in ICElib:</para>
3724 One to handle typically fatal conditions (for example,
3725 a connection dying because a machine crashed)
3729 <para>One to handle ICE-specific protocol errors</para>
3734 These error handlers can be changed to user-supplied routines if you
3735 prefer your own error handling and can be changed as often as you like.
3740 To set the ICE error handler, use <function>IceSetErrorHandler</function>
3745 <funcdef><function> IceSetErrorHandler</function></funcdef>
3746 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3747 <paramdef>int<parameter> bytes</parameter></paramdef>
3751 <variablelist remap='IP'>
3753 <term><emphasis remap='I'>handler</emphasis></term>
3756 The ICE error handler. You should pass NULL to restore the default handler.
3763 <function>IceSetErrorHandler</function> returns the previous error handler.
3767 The ICE error handler is invoked when an unexpected ICE protocol
3768 error (major opcode 0) is encountered. The action of the default
3769 handler is to print an explanatory message to
3770 <function>stderr</function>
3771 and if the severity is fatal, call
3772 <function>exit</function>
3773 with a nonzero value. If exiting
3774 is undesirable, the application should register its own error handler.
3778 Note that errors in other protocol
3779 domains should be handled by their respective libraries (these libraries
3780 should have their own error handlers).
3784 An ICE error handler has the type of <function>IceErrorHandler</function>
3789 <funcdef>void<function> IceErrorHandler</function></funcdef>
3790 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3791 <paramdef>Bool<parameter> swap</parameter></paramdef>
3792 <paramdef>int<parameter> offending_minor_opcode</parameter></paramdef>
3793 <paramdef>unsigned long<parameter> offending_sequence_num</parameter></paramdef>
3794 <paramdef>int<parameter> error_class</parameter></paramdef>
3795 <paramdef>int<parameter> severity</parameter></paramdef>
3796 <paramdef>IcePointer<parameter> values</parameter></paramdef>
3800 <variablelist remap='IP'>
3802 <term><emphasis remap='I'>handler</emphasis></term>
3804 <para>The ICE connection object.</para>
3808 <term><emphasis remap='I'>swap</emphasis></term>
3810 <para>A flag that indicates if the values need byte swapping.</para>
3814 <term><emphasis remap='I'>offending_minor_opcode</emphasis></term>
3816 <para>The ICE minor opcode of the offending message.</para>
3820 <term><emphasis remap='I'>offending_sequence_num</emphasis></term>
3822 <para>The sequence number of the offending message.</para>
3826 <term><emphasis remap='I'>error_class</emphasis></term>
3828 <para>The error class of the offending message.</para>
3832 <term><emphasis remap='I'>severity</emphasis></term>
3835 <function>IceCanContinue</function>
3836 <function>IceFatalToProtocol</function>
3838 <function>IceFatalToConnection</function>
3843 <term><emphasis remap='I'>values</emphasis></term>
3846 Any additional error values specific to the minor opcode and class.
3853 <para>The following error classes are defined at the ICE level:</para>
3855 <literallayout remap='Ds'>
3856 <function>IceBadMinor</function>
3857 <function>IceBadState</function>
3858 <function>IceBadLength</function>
3859 <function>IceBadValue</function>
3860 <function>IceBadMajor</function>
3861 <function>IceNoAuth</function>
3862 <function>IceNoVersion</function>
3863 <function>IceSetupFailed</function>
3864 <function>IceAuthRejected</function>
3865 <function>IceAuthFailed</function>
3866 <function>IceProtocolDuplicate</function>
3867 <function>IceMajorOpcodeDuplicate</function>
3868 <function>IceUnknownProtocol</function>
3872 For further information, see
3873 the <emphasis remap='I'>Inter-Client Exchange Protocol</emphasis> standard.
3878 To handle fatal I/O errors, use <function>IceSetIOErrorHandler</function>
3884 <funcdef>IceIOErrorHandler<function> IceSetIOErrorHandler</function></funcdef>
3885 <paramdef>IceIOErrorHandler<parameter> handler</parameter></paramdef>
3889 <variablelist remap='IP'>
3891 <term><emphasis remap='I'>handler</emphasis></term>
3894 The I/O error handler. You should pass NULL to restore the default handler.
3901 <function>IceSetIOErrorHandler</function> returns the previous
3906 An ICE I/O error handler has the type of
3907 <function>IceIOErrorHandler</function>
3912 <funcdef>void<function> IceIOErrorHandler</function></funcdef>
3913 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3917 <variablelist remap='IP'>
3919 <term><emphasis remap='I'>ice_conn</emphasis></term>
3920 <listitem><para>The ICE connection object.</para></listitem>
3925 <para> There are two ways of handling IO errors in ICElib:</para>
3930 In the first, the IO error handler does whatever is necessary
3931 to respond to the IO error and then returns, but it does not call
3932 <function>IceCloseConnection</function>
3933 The ICE connection is given a "bad IO" status, and all future reads
3934 and writes to the connection are ignored. The next time
3935 <function>IceProcessMessages</function>
3936 is called it will return a status of
3937 <function>IceProcessMessagesIOError</function>
3938 At that time, the application should call
3939 <function>IceCloseConnection</function>
3944 In the second, the IO error handler does call
3945 <function>IceCloseConnection</function>
3946 and then uses the <function>longjmp</function>
3947 call to get back to the application's main event loop. The
3948 <function>setjmp</function> and
3949 <function>longjmp</function>
3950 calls may not work properly on all platforms,
3951 and special care must be taken to avoid memory leaks.
3952 Therefore, this second model is less desirable.
3958 Before the application I/O error handler is invoked, protocol libraries
3959 that were interested in being notified of I/O errors will have their
3960 <function>IceIOErrorProc</function>
3961 handlers invoked. This handler is set up in the protocol registration
3962 functions (see <function>IceRegisterForProtocolSetup</function> and
3963 <function>IceRegisterForProtocolReply</function>
3964 and could be used to clean up state specific to the protocol.
3970 <funcdef>void<function> IceIOErrorProc</function></funcdef>
3971 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
3975 <variablelist remap='IP'>
3977 <term><emphasis remap='I'>ice_conn</emphasis></term>
3978 <listitem><para>The ICE connection object.</para></listitem>
3983 Note that every <function>IceIOErrorProc</function>
3984 callback must return. This is required
3985 because each active protocol must be notified of the broken connection,
3986 and the application IO error handler must be invoked afterwards.
3990 <chapter id='multithreading_support'>
3991 <title>Multi-Threading Support</title>
3994 <para>To declare that multiple threads in an application will be using the ICE
3996 <function>IceInitThreads</function></para>
3998 <literallayout remap='FD'>
3999 Status IceInitThreads()
4004 <function>IceInitThreads</function>
4005 function must be the first ICElib function a
4006 multi-threaded program calls. It must complete before any other ICElib
4008 <function>IceInitThreads</function>
4009 returns a nonzero status if and only if it was able
4010 to initialize the threads package successfully.
4012 <function>IceInitThreads</function>
4013 more than once, although the threads package will only be initialized once.</para>
4015 <para>Protocol libraries layered on top of ICElib will have to lock critical
4016 sections of code that access an ICE connection (for example, when
4017 generating messages). Two calls, which are generally implemented as
4018 macros, are provided:</para>
4022 <funcdef>void<function> IceLockConn</function></funcdef>
4023 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
4029 <funcdef>void<function> IceUnlockConn</function></funcdef>
4030 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
4034 <variablelist remap='IP'>
4036 <term><emphasis remap='I'>ice_conn</emphasis></term>
4037 <listitem><para>The ICE connection object.</para></listitem>
4041 <para>To keep an ICE connection locked across several ICElib calls, applications use
4042 <function>IceAppLockConn</function>
4044 <function>IceAppUnlockConn</function></para>
4048 <funcdef>void<function> IceAppLockConn</function></funcdef>
4049 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
4053 <variablelist remap='IP'>
4055 <term><emphasis remap='I'>ice_conn</emphasis></term>
4056 <listitem><para>The ICE connection object.</para></listitem>
4062 <function>IceAppLockConn</function>
4063 function completely locks out other threads using the connection
4065 <function>IceAppUnlockConn</function>
4066 is called. Other threads attempting to use ICElib
4067 calls on the connection will block.
4068 If the program has not previously called
4069 <function>IceInitThreads</function>
4070 <function>IceAppLockConn</function>
4071 has no effect.</para>
4075 <funcdef>void<function> IceAppUnlockConn</function></funcdef>
4076 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
4080 <variablelist remap='IP'>
4082 <term><emphasis remap='I'>ice_conn</emphasis></term>
4083 <listitem><para>The ICE connection object.</para></listitem>
4088 <function>IceAppUnlockConn</function>
4089 function allows other threads to complete ICElib
4090 calls on the connection that were blocked by a previous call to
4091 <function>IceAppLockConn</function>
4092 from this thread. If the program has not previously called
4093 <function>IceInitThreads</function>
4094 <function>IceAppUnlockConn</function>
4095 has no effect.</para>
4098 <chapter id='miscellaneous_functions'>
4099 <title>Miscellaneous Functions</title>
4104 <para>To allocate scratch space (for example, when generating
4105 messages with variable data), use
4106 <function>IceAllocScratch</function>
4107 Each ICE connection has one scratch space associated with it.
4108 The scratch space starts off as empty and grows as needed.
4109 The contents of the scratch space is not guaranteed to be preserved
4110 after any ICElib function is called.</para>
4115 <funcdef>char<function> *IceAllocScratch</function></funcdef>
4116 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef>
4117 <paramdef>unsigned long<parameter> size</parameter></paramdef>
4121 <variablelist remap='IP'>
4123 <term><emphasis remap='I'>ice_conn</emphasis></term>
4124 <listitem><para>The ICE connection object.</para></listitem>
4127 <term><emphasis remap='I'>size</emphasis></term>
4128 <listitem><para>The number of bytes required.</para></listitem>
4132 <para>Note that the memory returned by
4133 <function>IceAllocScratch</function>
4134 should not be freed by the caller.
4135 The ICE library will free the memory when the ICE connection is closed.</para>
4138 <chapter id='acknowledgements'>
4139 <title>Acknowledgements</title>
4143 Thanks to Bob Scheifler for his thoughtful input on the design
4144 of the ICE library. Thanks also to Jordan Brown, Larry Cable, Donna Converse,
4145 Clive Feather, Stephen Gildea, Vania Joloboff, Kaleb Keithley,
4146 Stuart Marks, Hiro Miyamoto, Ralph Swick, Jim VanGilder, and Mike Wexler.
4150 <appendix id="authentication_utility_functions">
4151 <title>Authentication Utility Functions</title>
4155 As discussed in this document, the means by which authentication data
4156 is obtained by the ICE library (for
4157 <function>ConnectionSetup</function>
4159 <function>ProtocolSetup</function>
4160 messages) is implementation-dependent.†
4161 <footnote remap='FS'>
4162 <para>The X Consortium's ICElib implementation assumes the presence of an
4168 This appendix describes some utility functions that manipulate an
4169 ICE authority file. The authority file can be used to pass authentication
4170 data between clients.
4173 <para>The basic operations on the .ICEauthority file are:</para>
4177 <para>Get file name</para>
4186 <para>Read entry</para>
4189 <para>Write entry</para>
4192 <para>Search for entry</para>
4197 These are fairly low-level operations, and it is expected that a program,
4198 like "iceauth", would exist to add, remove, and display entries in the file.
4202 In order to use these utility functions, the
4203 <<symbol role='Pn'>X11/ICE/ICEutil.h</symbol>>
4204 header file must be included.
4208 An entry in the .ICEauthority file is defined by the following data structure:
4212 <literallayout class="monospaced">
4214 char *protocol_name;
4215 unsigned short protocol_data_length;
4216 char *protocol_data;
4219 unsigned short auth_data_length;
4226 The protocol_name member is either "ICE" for connection setup authentication
4227 or the subprotocol name, such as "XSMP". For each entry, protocol specific
4228 data can be specified in the protocol_data member. This can be used
4229 to search for old entries that need to be removed from the file.
4233 The network_id member is the network ID of the client accepting
4234 authentication (for example, the network ID of a session manager).
4235 A network ID has the following form:
4238 <informaltable pgwide='0' frame='none'>
4239 <tgroup cols='3' align='center'>
4240 <colspec colname='c1'/>
4241 <colspec colname='c2'/>
4242 <colspec colname='c3'/>
4245 <entry align='left'></entry>
4246 <entry align='left'>tcp/<hostname>:<portnumber></entry>
4247 <entry align='left'>or</entry>
4250 <entry align='left'></entry>
4251 <entry align='left'>decnet/<hostname>::<objname></entry>
4252 <entry align='left'>or</entry>
4255 <entry align='left'></entry>
4256 <entry align='left'>local/<hostname>:<path></entry>
4257 <entry align='left'></entry>
4264 The auth_name member is the name of the authentication method.
4265 The auth_data member is the actual authentication data,
4266 and the auth_data_length member is the number of bytes in the data.
4270 To obtain the default authorization file name, use
4271 <function>IceAuthFileName</function>
4274 <literallayout remap='FD'>
4275 char *IceAuthFileName()
4279 If the ICEAUTHORITY environment variable if set, this value is returned.
4280 Otherwise, the default authorization file name is $HOME/.ICEauthority.
4281 This name is statically allocated and should not be freed.
4285 To synchronously update the authorization file, the file must
4286 be locked with a call to
4287 <function>IceLockAuthFile</function>
4288 This function takes advantage of the fact that the
4289 <function>link</function>
4290 system call will fail if the name of the new link already exists.
4295 <funcdef>int<function> IceLockAuthFile</function></funcdef>
4296 <paramdef>char<parameter> *file_name</parameter></paramdef>
4297 <paramdef>int<parameter> retries</parameter></paramdef>
4298 <paramdef>int<parameter> timeout</parameter></paramdef>
4299 <paramdef>long<parameter> dead</parameter></paramdef>
4303 <variablelist remap='IP'>
4305 <term><emphasis remap='I'>file_name</emphasis></term>
4306 <listitem><para>The authorization file to lock.</para></listitem>
4309 <term><emphasis remap='I'>retries</emphasis></term>
4311 <para>The number of retries.</para>
4315 <term><emphasis remap='I'>timeout</emphasis></term>
4317 <para>The number of seconds before each retry.</para>
4321 <term><emphasis remap='I'>dead</emphasis></term>
4324 If a lock already exists that is the specified dead seconds old,
4326 A value of zero is used to unconditionally break an old lock.
4332 <para>One of three values is returned:</para>
4337 <function>IceAuthLockSuccess</function> - the lock succeeded.
4342 <function>IceAuthLockError</function> - a system error occurred, and
4343 <function>errno</function> may prove useful.
4348 <function>IceAuthLockTimeout</function> - the specified number of
4355 To unlock an authorization file, use <function>IceUnlockAuthFile</function>
4360 <funcdef>int<function> IceUnlockAuthFile</function></funcdef>
4361 <paramdef>char<parameter> *file_name</parameter></paramdef>
4365 <variablelist remap='IP'>
4367 <term><emphasis remap='I'>file_name</emphasis></term>
4368 <listitem><para>The authorization file to unlock.</para></listitem>
4373 To read the next entry in an authorization file, use
4374 <function>IceReadAuthFileEntry</function>
4379 <funcdef>IceAuthFileEntry<function> *IceReadAuthFileEntry</function></funcdef>
4380 <paramdef>FILE<parameter> *auth_file</parameter></paramdef>
4384 <variablelist remap='IP'>
4386 <term><emphasis remap='I'>auth_file</emphasis></term>
4387 <listitem><para>The authorization file.</para></listitem>
4392 Note that it is the responsibility of the application to open the file
4393 for reading before calling this function. If an error is encountered,
4394 or there are no more entries to read, NULL is returned.
4398 Entries should be free with a call to
4399 <function>IceFreeAuthFileEntry</function>
4403 To write an entry in an authorization file, use
4404 <function>IceWriteAuthFileEntry</function>
4409 <funcdef>Status<function> IceWriteAuthFileEntry</function></funcdef>
4410 <paramdef>FILE<parameter> *auth_file</parameter></paramdef>
4411 <paramdef>IceAuthFileEntry<parameter> *entry</parameter></paramdef>
4415 <variablelist remap='IP'>
4417 <term><emphasis remap='I'>auth_file</emphasis></term>
4418 <listitem><para>The authorization file.</para></listitem>
4421 <term><emphasis remap='I'>entry</emphasis></term>
4422 <listitem><para>The entry to write.</para></listitem>
4427 Note that it is the responsibility of the application to open the file
4428 for writing before calling this function. The function returns a nonzero
4429 status if the operation was successful.
4434 To search the default authorization file for an entry that matches a given
4435 protocol_name/network_id/auth_name tuple, use
4436 <function>IceGetAuthFileEntry</function>
4441 <funcdef>IceAuthFileEntry<function> *IceGetAuthFileEntry</function></funcdef>
4442 <paramdef>char<parameter> *protocol_name</parameter></paramdef>
4443 <paramdef>char<parameter> *network_id</parameter></paramdef>
4444 <paramdef>char<parameter> *auth_name</parameter></paramdef>
4448 <variablelist remap='IP'>
4450 <term><emphasis remap='I'>auth_file</emphasis></term>
4451 <listitem><para>The name of the protocol to search on.</para></listitem>
4454 <term><emphasis remap='I'>network_id</emphasis></term>
4456 <para>The network ID to search on.</para>
4460 <term><emphasis remap='I'>auth_name</emphasis></term>
4462 <para>The authentication method to search on.</para>
4468 If <function>IceGetAuthFileEntry</function>
4469 fails to find such an entry, NULL is returned.
4474 To free an entry returned by
4475 <function>IceReadAuthFileEntry</function> or
4476 <function>IceGetAuthFileEntry</function> use
4477 <function>IceFreeAuthFileEntry</function>
4482 <funcdef>void<function> IceFreeAuthFileEntry</function></funcdef>
4483 <paramdef>IceAuthFileEntry<parameter> *entry</parameter></paramdef>
4487 <variablelist remap='IP'>
4489 <term><emphasis remap='I'>entry</emphasis></term>
4490 <listitem><para>The entry to free.</para></listitem>
4496 <appendix id="mit_magic_cookie_1_authentication">
4497 <title>MIT-MAGIC-COOKIE-1 Authentication</title>
4500 <para>The X Consortium's ICElib implementation supports a simple
4501 MIT-MAGIC-COOKIE-1 authentication scheme using the authority file utilities
4502 described in Appendix A.</para>
4504 <para>In this model, an application, such as a session manager, obtains a
4505 magic cookie by calling
4506 <function>IceGenerateMagicCookie</function>
4507 and then stores it in the user's local .ICEauthority file
4508 so that local clients can connect. In order to allow remote clients to
4509 connect, some remote execution mechanism should be used to store the
4510 magic cookie in the user's .ICEauthority file on a remote machine.</para>
4512 <para>In addition to storing the magic cookie in the .ICEauthority file, the
4513 application needs to call the
4514 <function>IceSetPaAuthData</function>
4515 function in order to store the magic cookie in memory. When it comes time
4516 for the MIT-MAGIC-COOKIE-1 authentication procedure to accept or reject the
4517 connection, it will compare the magic cookie presented by the requestor to
4518 the magic cookie in memory.</para>
4522 <funcdef>char<function> *IceGenerateMagicCookie</function></funcdef>
4523 <paramdef>int<parameter> length</parameter></paramdef>
4527 <variablelist remap='IP'>
4529 <term><emphasis remap='I'>length</emphasis></term>
4530 <listitem><para>The desired length of the magic cookie.</para></listitem>
4535 <para>The magic cookie returned will be null-terminated. If memory can not be
4536 allocated for the magic cookie, the function will return NULL.
4537 Otherwise, the magic cookie should be freed with a call to
4538 <function>free</function></para>
4541 <para>To store the authentication data in memory, use
4542 <function>IceSetPaAuthData</function>
4543 Currently, this function is only used for MIT-MAGIC-COOKIE-1
4544 authentication, but it may be used for additional authentication
4545 methods in the future.</para>
4549 <funcdef>void<function> IceSetPaAuthData</function></funcdef>
4550 <paramdef>int<parameter> num_entries</parameter></paramdef>
4551 <paramdef>IceAuthDataEntry<parameter> *entries</parameter></paramdef>
4555 <variablelist remap='IP'>
4557 <term><emphasis remap='I'>num_entries</emphasis></term>
4558 <listitem><para>The number of authentication data entries.</para></listitem>
4561 <term><emphasis remap='I'>entries</emphasis></term>
4562 <listitem><para>The list of authentication data entries.</para></listitem>
4566 <para>Each entry has associated with it a protocol name
4567 (for example, "ICE" for ICE connection setup authentication,
4568 "XSMP" for session management authentication), a network ID for the
4569 "accepting" client, an authentication name (for example, MIT-MAGIC-COOKIE-1),
4570 and authentication data. The ICE library
4571 will merge these entries with previously set entries, based on the
4572 (protocol_name, network_id, auth_name) tuple.</para>
4576 <literallayout class="monospaced">
4578 char *protocol_name;
4581 unsigned short auth_data_length;