1<?xml version="1.0" encoding="UTF-8" ?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" 4[ 5<!ENTITY % defs SYSTEM "defs.ent"> %defs; 6]> 7 8 9<book id="ICElib"> 10 11<bookinfo> 12 <title>Inter-Client Exchange Library</title> 13 <subtitle>X Consortium Standard</subtitle> 14 <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo> 15 <releaseinfo>Version 1.0</releaseinfo> 16 <authorgroup> 17 <author> 18 <firstname>Ralph</firstname><surname>Mor</surname> 19 <affiliation><orgname>X Consortium</orgname></affiliation> 20 </author> 21 </authorgroup> 22 <copyright> 23 <year>1993</year><year>1994</year><year>1996</year> 24 <holder>X Consortium</holder> 25 </copyright> 26 27<legalnotice> 28<para> 29Permission is hereby granted, free of charge, to any person obtaining a copy 30of this software and associated documentation files (the 31"Software"), to deal in the Software without restriction, 32including without limitation the rights to use, copy, modify, merge, 33publish, distribute, sublicense, and/or sell copies of the Software, and 34to permit persons to whom the Software is furnished to do so, subject to 35the following conditions: 36</para> 37 38<para>The above copyright notice and this permission notice shall be 39included in all copies or substantial portions of the Software. 40</para> 41 42<para> 43THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 44IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 45FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 46X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN 47AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 48CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 49</para> 50 51<para> 52Except as contained in this notice, the name of the X Consortium shall not be 53used in advertising or otherwise to promote the sale, use or other dealings 54in this Software without prior written authorization from the X Consortium. 55</para> 56 57</legalnotice> 58</bookinfo> 59 60<chapter id='Overview_of_ICE'> 61<title>Overview of ICE</title> 62 63<para> 64There are numerous possible inter-client protocols, with many similarities 65and common needs - authentication, version negotiation, byte 66order negotiation, and so on. 67The Inter-Client Exchange (ICE) protocol is intended to provide a framework 68for building such protocols, allowing them to make use of common negotiation 69mechanisms and to be multiplexed over a single transport connection. 70</para> 71</chapter> 72 73<chapter id='The_ICE_Library___C_Language_Interface_to_ICE'> 74<title>The ICE Library - C Language Interface to ICE</title> 75 76<para> 77A client that wishes to utilize ICE must first register the protocols it 78understands with the ICE library. Each protocol is dynamically assigned 79a major opcode ranging from 1-255 (two clients can use different 80major opcodes for the same protocol). The next step for the client is either 81to open a connection with another client or to wait for connections made 82by other clients. Authentication may be required. A client can both 83initiate connections with other clients and be 84waiting for clients to connect to itself (a nested session manager is an 85example). Once an ICE connection is established between the two clients, one 86of the clients needs to initiate a 87<function>ProtocolSetup</function> 88in order to 89"activate" a given protocol. Once the other client accepts the 90<function>ProtocolSetup</function> 91(once again, authentication may be required), the 92two clients are ready to start passing messages specific to that protocol to 93each other. Multiple protocols may be active on a single ICE connection. 94Clients are responsible for notifying the ICE library when a protocol is no 95longer active on an ICE connection, although ICE does not define how each 96subprotocol triggers a protocol shutdown. 97</para> 98 99<para> 100The ICE library utilizes callbacks to process incoming messages. Using 101callbacks allows 102<function>ProtocolSetup</function> 103messages and authentication to happen 104behind the scenes. An additional benefit is that messages never need 105to be buffered up by the library when the client blocks waiting for a 106particular message. 107</para> 108</chapter> 109 110<chapter id='Intended_Audience'> 111<title>Intended Audience</title> 112 113<para>This document is intended primarily for implementors of protocol libraries 114layered on top of ICE. Typically, applications that wish to utilize ICE 115will make calls into individual protocol libraries rather than directly 116make calls into the ICE library. However, some applications will have to 117make some initial calls into the ICE library in order to accept ICE 118connections (for example, a session manager accepting connections from 119clients). But in general, protocol libraries should be designed to hide 120the inner details of ICE from applications.</para> 121</chapter> 122 123<chapter id='Header_Files_and_Library_Name'> 124<title>Header Files and Library Name</title> 125 126 127<para>The header file 128<<symbol role='Pn'>X11/ICE/ICElib.h</symbol>> 129defines all of the ICElib data structures and function prototypes. 130<function>ICElib.h</function> 131includes the header file 132<<symbol role='Pn'>X11/ICE/ICE.h</symbol>>, 133which defines all of the ICElib constants. 134Protocol libraries that need to read and write messages should include 135the header file 136<<symbol role='Pn'>X11/ICE/ICEmsg.h</symbol>>.</para> 137 138<para>Applications should link against ICElib using -lICE.</para> 139</chapter> 140 141<chapter id='Note_on_Prefixes'> 142<title>Note on Prefixes</title> 143 144 145<para>The following name prefixes are used in the library to distinguish between 146a client that initiates a 147<function>ProtocolSetup</function> 148and a client that 149responds with a 150<function>ProtocolReply</function></para> 151 152<itemizedlist> 153 <listitem> 154<para><function>IcePo</function> 155- Ice Protocol Originator</para> 156 </listitem> 157 <listitem> 158<para><function>IcePa</function> 159- Ice Protocol Acceptor</para> 160 </listitem> 161</itemizedlist> 162</chapter> 163 164<chapter id='Protocol_Registration'> 165<title>Protocol Registration</title> 166 167<para> 168In order for two clients to exchange messages for a given protocol, each 169side must register the protocol with the ICE library. The purpose of 170registration is for each side to obtain a major opcode for the protocol 171and to provide callbacks for processing messages and handling authentication. 172There are two separate registration functions: 173</para> 174 175<itemizedlist> 176 <listitem> 177 <para> 178One to handle the side that does a 179<function>ProtocolSetup</function> 180 </para> 181 </listitem> 182 <listitem> 183 <para> 184One to handle the side that responds with a 185<function>ProtocolReply</function> 186 </para> 187 </listitem> 188</itemizedlist> 189 190<para> 191It is recommended that protocol registration occur before the two clients 192establish an ICE connection. If protocol registration occurs after an 193ICE connection is created, there can be a brief interval of time in which a 194<function>ProtocolSetup</function> 195is received, but the protocol is not registered. 196If it is not possible to register a protocol before the creation of an 197ICE connection, proper precautions should be taken to avoid the above race 198condition. 199</para> 200 201 202<para> 203The <xref linkend='IceRegisterForProtocolSetup' xrefstyle='select: title'/> 204function should be called for the client that initiates a 205<function>ProtocolSetup</function> 206</para> 207 208<funcsynopsis id='IceRegisterForProtocolSetup'> 209<funcprototype> 210 <funcdef>int <function>IceRegisterForProtocolSetup</function></funcdef> 211 <paramdef>const char<parameter> *protocol_name</parameter></paramdef> 212 <paramdef>const char<parameter> *vendor</parameter></paramdef> 213 <paramdef>const char<parameter> *release</parameter></paramdef> 214 <paramdef>int<parameter> version_count</parameter></paramdef> 215 <paramdef>IcePoVersionRec<parameter> *version_recs</parameter></paramdef> 216 <paramdef>int<parameter> auth_count</parameter></paramdef> 217 <paramdef>char<parameter> **auth_names</parameter></paramdef> 218 <paramdef>IcePoAuthProc<parameter> *auth_procs</parameter></paramdef> 219 <paramdef>IceIOErrorProc<parameter> io_error_proc</parameter></paramdef> 220</funcprototype> 221</funcsynopsis> 222 223 224<variablelist remap='IP'> 225 <varlistentry> 226 <term><emphasis remap='I'>protocol_name</emphasis></term> 227 <listitem> 228 <para> 229A string specifying the name of the protocol to register. 230 </para> 231 </listitem> 232 </varlistentry> 233 <varlistentry> 234 <term><emphasis remap='I'>vendor</emphasis></term> 235 <listitem> 236 <para>A vendor string with semantics specified by the protocol.</para> 237 </listitem> 238 </varlistentry> 239 <varlistentry> 240 <term><emphasis remap='I'>release</emphasis></term> 241 <listitem> 242 <para>A release string with semantics specified by the protocol.</para> 243 </listitem> 244 </varlistentry> 245 <varlistentry> 246 <term><emphasis remap='I'>version_count</emphasis></term> 247 <listitem> 248 <para>The number of different versions of the protocol supported.</para> 249 </listitem> 250 </varlistentry> 251 <varlistentry> 252 <term><emphasis remap='I'>version_recs</emphasis></term> 253 <listitem> 254 <para>List of versions and associated callbacks.</para> 255 </listitem> 256 </varlistentry> 257 <varlistentry> 258 <term><emphasis remap='I'>auth_count</emphasis></term> 259 <listitem> 260 <para>The number of authentication methods supported.</para> 261 </listitem> 262 </varlistentry> 263 <varlistentry> 264 <term><emphasis remap='I'>auth_names</emphasis></term> 265 <listitem> 266 <para>The list of authentication methods supported.</para> 267 </listitem> 268 </varlistentry> 269 <varlistentry> 270 <term><emphasis remap='I'>auth_procs</emphasis></term> 271 <listitem> 272 <para> 273The list of authentication callbacks, one for each authentication method. 274 </para> 275 </listitem> 276 </varlistentry> 277 <varlistentry> 278 <term><emphasis remap='I'>io_error_proc</emphasis></term> 279 <listitem> 280 <para>IO error handler, or NULL.</para> 281 </listitem> 282 </varlistentry> 283</variablelist> 284 285 286<para> 287<xref linkend='IceRegisterForProtocolSetup' xrefstyle='select: title'/> returns the major 288opcode reserved or -1 if an error occurred. In order to actually activate 289the protocol, the <xref linkend='IceProtocolSetup' xrefstyle='select: title'/> 290function needs to be called with this major opcode. Once the protocol is 291activated, all messages for the protocol should be sent using this major 292opcode. 293</para> 294 295<para> 296A protocol library may support multiple versions of the same protocol. 297The version_recs argument specifies a list of supported versions of the 298protocol, which are prioritized in decreasing order of preference. 299Each version record consists of a major and minor version of the protocol 300as well as a callback to be used for processing incoming messages. 301</para> 302 303 304<literallayout remap='Ds'> 305typedef struct { 306 int major_version; 307 int minor_version; 308 IcePoProcessMsgProc process_msg_proc; 309} IcePoVersionRec; 310</literallayout> 311 312<para>The 313<function>IcePoProcessMsgProc</function> 314callback is responsible for processing the set of messages that can be 315received by the client that initiated the 316<function>ProtocolSetup</function> 317For further information, 318see 319<xref linkend='Callbacks_for_Processing_Messages' xrefstyle='select: title'/> 320</para> 321 322<para>Authentication may be required before the protocol can become active. 323The protocol library must register the authentication methods that it 324supports with the ICE library. 325The auth_names and auth_procs arguments are a list of authentication names 326and callbacks that are prioritized in decreasing order of preference. 327For information on the 328<function>IcePoAuthProc</function> 329callback, see 330<xref linkend='Authentication_Methods' xrefstyle='select: title'/> 331</para> 332 333<para>The 334<xref linkend='IceIOErrorProc' xrefstyle='select: title'/> 335callback is invoked if the ICE connection unexpectedly breaks. 336You should pass NULL for io_error_proc if not interested in being notified. 337For further information, 338<xref linkend='Error_Handling' xrefstyle='select: title'/> 339</para> 340 341 342<para>The 343<xref linkend='IceRegisterForProtocolReply' xrefstyle='select: title'/> 344function should be called for the client that responds to a 345<function>ProtocolSetup</function> 346with a 347<function>ProtocolReply</function></para> 348 349 350<funcsynopsis id='IceRegisterForProtocolReply'> 351<funcprototype> 352 <funcdef>Bool <function>IceRegisterForProtocolReply</function></funcdef> 353 <paramdef>const char<parameter> *protocol_name</parameter></paramdef> 354 <paramdef>const char<parameter> *vendor</parameter></paramdef> 355 <paramdef>const char<parameter> *release</parameter></paramdef> 356 <paramdef>int<parameter> version_count</parameter></paramdef> 357 <paramdef>IcePoVersionRec<parameter> *version_recs</parameter></paramdef> 358 <paramdef>int<parameter> auth_count</parameter></paramdef> 359 <paramdef>const char<parameter> **auth_names</parameter></paramdef> 360 <paramdef>IcePoAuthProc<parameter> *auth_procs</parameter></paramdef> 361 <paramdef>IceHostBasedAuthProc<parameter> host_based_auth_proc</parameter></paramdef> 362 <paramdef>IceProtocolSetupProc<parameter> protocol_setup_proc</parameter></paramdef> 363 <paramdef>IceProtocolActivateProc<parameter> protocol_activate_proc</parameter></paramdef> 364 <paramdef>IceIOErrorProc<parameter> io_error_proc</parameter></paramdef> 365</funcprototype> 366</funcsynopsis> 367 368<variablelist remap='IP'> 369 <varlistentry> 370 <term><emphasis remap='I'>protocol_name</emphasis></term> 371 <listitem><para>A string specifying the name of the protocol to register.</para></listitem> 372 </varlistentry> 373 <varlistentry> 374 <term><emphasis remap='I'>vendor</emphasis></term> 375 <listitem> 376<para>A vendor string with semantics specified by the protocol.</para> 377 </listitem> 378 </varlistentry> 379 <varlistentry> 380 <term><emphasis remap='I'>release</emphasis></term> 381 <listitem> 382<para>A release string with semantics specified by the protocol.</para> 383 </listitem> 384 </varlistentry> 385 <varlistentry> 386 <term><emphasis remap='I'>version_count</emphasis></term> 387 <listitem> 388<para>The number of different versions of the protocol supported.</para> 389 </listitem> 390 </varlistentry> 391 <varlistentry> 392 <term><emphasis remap='I'>version_recs</emphasis></term> 393 <listitem> 394<para>List of versions and associated callbacks.</para> 395 </listitem> 396 </varlistentry> 397 <varlistentry> 398 <term><emphasis remap='I'>auth_count</emphasis></term> 399 <listitem> 400<para>The number of authentication methods supported.</para> 401 </listitem> 402 </varlistentry> 403 <varlistentry> 404 <term><emphasis remap='I'>auth_names</emphasis></term> 405 <listitem> 406<para>The list of authentication methods supported.</para> 407 </listitem> 408 </varlistentry> 409 <varlistentry> 410 <term><emphasis remap='I'>auth_procs</emphasis></term> 411 <listitem> 412<para>The list of authentication callbacks, one for each authentication method.</para> 413 </listitem> 414 </varlistentry> 415 <varlistentry> 416 <term><emphasis remap='I'>host_based_auth_proc</emphasis></term> 417 <listitem> 418<para>Host based authentication callback.</para> 419 </listitem> 420 </varlistentry> 421 <varlistentry> 422 <term><emphasis remap='I'>protocol_setup_proc</emphasis></term> 423 <listitem> 424<para>A callback to be invoked when authentication has succeeded for a 425<function>ProtocolSetup</function> 426but before the 427<function>ProtocolReply</function> 428is sent.</para> 429 </listitem> 430 </varlistentry> 431 <varlistentry> 432 <term><emphasis remap='I'>protocol_activate_proc</emphasis></term> 433 <listitem> 434<para>A callback to be invoked after the 435<function>ProtocolReply</function> 436is sent.</para> 437 </listitem> 438 </varlistentry> 439 <varlistentry> 440 <term><emphasis remap='I'>io_error_proc</emphasis></term> 441 <listitem> 442<para>IO error handler, or NULL.</para> 443 </listitem> 444 </varlistentry> 445</variablelist> 446 447 448<para><xref linkend='IceRegisterForProtocolReply' xrefstyle='select: title'/> 449returns the major opcode reserved or -1 if an error occurred. The major 450opcode should be used in all subsequent messages sent for this protocol.</para> 451 452<para>A protocol library may support multiple versions of the same protocol. 453The version_recs argument specifies a list of supported versions of the protocol, 454which are prioritized in decreasing order of preference. 455Each version record consists of a major and minor version of the protocol 456as well as a callback to be used for processing incoming messages.</para> 457 458 459<literallayout remap='Ds'> 460typedef struct { 461 int major_version; 462 int minor_version; 463 IcePaProcessMsgProc process_msg_proc; 464} IcePaVersionRec; 465</literallayout> 466 467 468<para>The 469<xref linkend='IcePaProcessMsgProc' xrefstyle='select: title'/> 470callback is responsible for processing the set of messages that can be 471received by the client that accepted the 472<function>ProtocolSetup</function> 473For further information, 474see 475<xref linkend='Callbacks_for_Processing_Messages' xrefstyle='select: title'/> 476</para> 477 478<para>Authentication may be required before the protocol can become active. 479The protocol library must register the authentication methods that it 480supports with the ICE library. 481The auth_names and auth_procs arguments are a list of authentication names 482and callbacks that are prioritized in decreasing order of preference. 483For information on the 484<function>IcePaAuthProc</function>, 485See 486<xref linkend='Authentication_Methods' xrefstyle='select: title'/> 487 488</para> 489 490<para>If authentication fails and the client attempting to initiate 491the 492<function>ProtocolSetup</function> 493has not required authentication, the 494<function>IceHostBasedAuthProc</function> 495callback is invoked with the host name of the originating client. 496If the callback returns 497<function>True</function> 498the 499<function>ProtocolSetup</function> 500will succeed, even though the original 501authentication failed. 502Note that authentication can effectively be disabled by registering an 503<function>IceHostBasedAuthProc</function> 504which always returns 505<function>True</function> 506If no host based 507authentication is allowed, you should pass NULL for host_based_auth_proc.</para> 508 509<funcsynopsis> 510<funcprototype> 511 <funcdef>Bool <function>HostBasedAuthProc</function></funcdef> 512 <paramdef>char<parameter> *host_name</parameter></paramdef> 513</funcprototype> 514</funcsynopsis> 515 516<variablelist remap='IP'> 517 <varlistentry> 518 <term><emphasis remap='I'>protocol_name</emphasis></term> 519 <listitem><para>The host name of the client that sent the <function>ProtocolSetup</function></para></listitem> 520 </varlistentry> 521</variablelist> 522 523 524<para>The host_name argument is a string of the form <emphasis remap='I'>protocol</emphasis>/<emphasis remap='I'>hostname</emphasis>, 525where <emphasis remap='I'>protocol</emphasis> is one of {tcp, decnet, local}.</para> 526 527<para>Because 528<function>ProtocolSetup</function> 529messages and authentication happen behind the scenes 530via callbacks, the protocol library needs some way of being notified when the 531<function>ProtocolSetup</function> 532has completed. 533This occurs in two phases. 534In the first phase, the 535<function>IceProtocolSetupProc</function> 536callback is invoked after authentication has 537successfully completed but before the ICE library sends a 538<function>ProtocolReply</function> 539Any resources required for this protocol should be allocated at this time. 540If the 541<function>IceProtocolSetupProc</function> 542returns a successful status, the ICE library will 543send the 544<function>ProtocolReply</function> 545and then invoke the 546<function>IceProtocolActivateProc</function> 547callback. Otherwise, an error will be sent to the 548other client in response to the 549<function>ProtocolSetup</function></para> 550 551<para>The 552<function>IceProtocolActivateProc</function> 553is an optional callback and should be registered only if the protocol 554library intends to generate a message immediately following the 555<function>ProtocolReply</function> 556You should pass NULL for protocol_activate_proc if not interested 557in this callback.</para> 558 559<funcsynopsis id='ProtocolSetupProc'> 560<funcprototype> 561 <funcdef>Status <function>ProtocolSetupProc</function></funcdef> 562 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 563 <paramdef>int<parameter> major_version</parameter></paramdef> 564 <paramdef>int<parameter> minor_version</parameter></paramdef> 565 <paramdef>char<parameter> *vendor</parameter></paramdef> 566 <paramdef>char<parameter> *release</parameter></paramdef> 567 <paramdef>IcePointer<parameter> *client_data_ret</parameter></paramdef> 568 <paramdef>char<parameter> **failure_reason_ret</parameter></paramdef> 569</funcprototype> 570</funcsynopsis> 571 572<variablelist remap='IP'> 573 <varlistentry> 574 <term><emphasis remap='I'>protocol_name</emphasis></term> 575 <listitem> 576<para>The ICE connection object.</para> 577 </listitem> 578 </varlistentry> 579 <varlistentry> 580 <term><emphasis remap='I'>major_version</emphasis></term> 581 <listitem> 582<para>The major version of the protocol.</para> 583 </listitem> 584 </varlistentry> 585 <varlistentry> 586 <term><emphasis remap='I'>minor_version</emphasis></term> 587 <listitem> 588<para>The minor version of the protocol.</para> 589 </listitem> 590 </varlistentry> 591 <varlistentry> 592 <term><emphasis remap='I'>vendor</emphasis></term> 593 <listitem> 594<para>The vendor string registered by the protocol originator.</para> 595 </listitem> 596 </varlistentry> 597 <varlistentry> 598 <term><emphasis remap='I'>release</emphasis></term> 599 <listitem> 600<para>The release string registered by the protocol originator.</para> 601 </listitem> 602 </varlistentry> 603 <varlistentry> 604 <term><emphasis remap='I'>client_data_ret</emphasis></term> 605 <listitem> 606<para>Client data to be set by callback.</para> 607 </listitem> 608 </varlistentry> 609 <varlistentry> 610 <term><emphasis remap='I'>failure_reason_ret</emphasis></term> 611 <listitem> 612<para>Failure reason returned.</para> 613 </listitem> 614 </varlistentry> 615</variablelist> 616 617<para>The pointer stored in the client_data_ret argument will be passed 618to the 619<xref linkend='IcePaProcessMsgProc' xrefstyle='select: title'/> 620callback whenever a message has arrived for this protocol on the 621ICE connection.</para> 622 623<para>The vendor and release strings should be freed with 624<function>free</function> 625when they are no longer needed.</para> 626 627<para>If a failure occurs, the 628<function>IceProtocolSetupProc</function> 629should return a zero status as well as allocate and return a failure 630reason string in failure_reason_ret. 631The ICE library will be responsible for freeing this memory.</para> 632 633<para>The 634<function>IceProtocolActivateProc</function> 635callback is defined as follows:</para> 636 637<funcsynopsis id='ProtocolActivateProc'> 638<funcprototype> 639 <funcdef>void <function>ProtocolActivateProc</function></funcdef> 640 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 641 <paramdef>IcePointer<parameter> client_data</parameter></paramdef> 642</funcprototype> 643</funcsynopsis> 644 645<variablelist remap='IP'> 646 <varlistentry> 647 <term><emphasis remap='I'>ice_conn</emphasis></term> 648 <listitem><para>The ICE connection object.</para></listitem> 649 </varlistentry> 650 <varlistentry> 651 <term><emphasis remap='I'>client_data</emphasis></term> 652 <listitem> 653 <para> 654The client data set in the <function>IceProtocolSetupProc</function> callback. 655 </para> 656 </listitem> 657 </varlistentry> 658</variablelist> 659 660 661<para>The 662<xref linkend='IceIOErrorProc' xrefstyle='select: title'/> 663callback is invoked if the ICE connection unexpectedly breaks. 664You should pass NULL for io_error_proc if not interested in being notified. 665For further information, 666see 667<xref linkend='Error_Handling' xrefstyle='select: title'/> 668</para> 669 670<sect1 id='Callbacks_for_Processing_Messages'> 671<title>Callbacks for Processing Messages</title> 672 673<para>When an application detects that there is new data to read on an ICE 674connection (via 675<function>select</function> 676it calls the 677<xref linkend='IceProcessMessages' xrefstyle='select: title'/> 678function 679<xref linkend='Processing_Messages' xrefstyle='select: title'/> 680 681When 682<xref linkend='IceProcessMessages' xrefstyle='select: title'/> 683reads an ICE message header with a major opcode other than 684zero (reserved for the ICE protocol), it needs to call a function that will 685read the rest of the message, unpack it, and process it accordingly.</para> 686 687<para>If the message arrives at the client that initiated the 688<function>ProtocolSetup</function> 689the 690<function>IcePoProcessMsgProc</function> 691callback is invoked.</para> 692 693<funcsynopsis id='PoProcessMsgProc'> 694<funcprototype> 695 <funcdef>void <function>PoProcessMsgProc</function></funcdef> 696 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 697 <paramdef>IcePointer<parameter> client_data</parameter></paramdef> 698 <paramdef>int<parameter> opcode</parameter></paramdef> 699 <paramdef>unsigned long<parameter> length</parameter></paramdef> 700 <paramdef>Bool<parameter> swap</parameter></paramdef> 701 <paramdef>IceReplyWaitInfo<parameter> *reply_wait</parameter></paramdef> 702 <paramdef>Bool<parameter> *reply_ready_ret</parameter></paramdef> 703</funcprototype> 704</funcsynopsis> 705 706<variablelist remap='IP'> 707 <varlistentry> 708 <term><emphasis remap='I'>ice_conn</emphasis></term> 709 <listitem><para>The ICE connection object.</para></listitem> 710 </varlistentry> 711 <varlistentry> 712 <term><emphasis remap='I'>client_data</emphasis></term> 713 <listitem> 714<para>Client data associated with this protocol on the ICE connection.</para> 715 </listitem> 716 </varlistentry> 717 <varlistentry> 718 <term><emphasis remap='I'>opcode</emphasis></term> 719 <listitem> 720<para>The minor opcode of the message.</para> 721 </listitem> 722 </varlistentry> 723 <varlistentry> 724 <term><emphasis remap='I'>length</emphasis></term> 725 <listitem> 726<para>The length (in 8-byte units) of the message beyond the ICE header.</para> 727 </listitem> 728 </varlistentry> 729 <varlistentry> 730 <term><emphasis remap='I'>swap</emphasis></term> 731 <listitem> 732<para>A flag that indicates if byte swapping is necessary.</para> 733 </listitem> 734 </varlistentry> 735 <varlistentry> 736 <term><emphasis remap='I'>reply_wait</emphasis></term> 737 <listitem> 738<para>Indicates if the invoking client is waiting for a reply.</para> 739 </listitem> 740 </varlistentry> 741 <varlistentry> 742 <term><emphasis remap='I'>reply_ready_ret</emphasis></term> 743 <listitem> 744<para>If set to 745<function>True</function> 746a reply is ready.</para> 747 </listitem> 748 </varlistentry> 749</variablelist> 750 751 752<para>If the message arrives at the client that accepted the 753<function>ProtocolSetup</function> 754the 755<xref linkend='IcePaProcessMsgProc' xrefstyle='select: title'/> 756callback is invoked.</para> 757 758 759<funcsynopsis id='IcePaProcessMsgProc'> 760<funcprototype> 761 <funcdef>void <function>IcePaProcessMsgProc</function></funcdef> 762 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 763 <paramdef>IcePointer<parameter> client_data</parameter></paramdef> 764 <paramdef>int<parameter> opcode</parameter></paramdef> 765 <paramdef>unsigned long<parameter> length</parameter></paramdef> 766 <paramdef>Bool<parameter> swap</parameter></paramdef> 767</funcprototype> 768</funcsynopsis> 769 770<variablelist remap='IP'> 771 <varlistentry> 772 <term><emphasis remap='I'>ice_conn</emphasis></term> 773 <listitem><para>The ICE connection object.</para></listitem> 774 </varlistentry> 775 <varlistentry> 776 <term><emphasis remap='I'>client_data</emphasis></term> 777 <listitem> 778<para>Client data associated with this protocol on the ICE connection.</para> 779 </listitem> 780 </varlistentry> 781 <varlistentry> 782 <term><emphasis remap='I'>opcode</emphasis></term> 783 <listitem> 784<para>The minor opcode of the message.</para> 785 </listitem> 786 </varlistentry> 787 <varlistentry> 788 <term><emphasis remap='I'>length</emphasis></term> 789 <listitem> 790<para>The length (in 8-byte units) of the message beyond the ICE header.</para> 791 </listitem> 792 </varlistentry> 793 <varlistentry> 794 <term><emphasis remap='I'>swap</emphasis></term> 795 <listitem> 796<para>A flag that indicates if byte swapping is necessary.</para> 797 </listitem> 798 </varlistentry> 799</variablelist> 800 801 802<para>In order to read the message, both of these callbacks should use the 803macros defined for this purpose (see 804<xref linkend='Reading_ICE_Messages' xrefstyle='select: title'/>.). 805Note that byte swapping may be necessary. 806As a convenience, the length field in the ICE header will be swapped by ICElib 807if necessary.</para> 808 809<para>In both of these callbacks, the client_data argument is a pointer to client 810data that was registered at 811<function>ProtocolSetup</function> 812time. 813In the case of 814<function>IcePoProcessMsgProc</function> 815the client data was set in the call to 816<xref linkend='IceProtocolSetup' xrefstyle='select: title'/> 817In the case of 818<xref linkend='IcePaProcessMsgProc' xrefstyle='select: title'/> 819the client data was set in the 820<function>IceProtocolSetupProc</function> 821callback.</para> 822 823<para>The 824<function>IcePoProcessMsgProc</function> 825callback needs to check the reply_wait argument. 826If reply_wait is NULL , 827the ICE library expects the function to 828pass the message to the client via a callback. 829For example, if this is a Session Management "Save Yourself" message, 830this function should notify the client of the "Save Yourself" via a callback. 831The details of how such a callback would be defined 832are implementation-dependent.</para> 833 834<para>However, if reply_wait is not NULL , 835then the client is waiting for 836a reply or an error for a message it previously sent. 837The reply_wait is of type 838<function>IceReplyWaitInfo</function></para> 839 840 841<literallayout remap='Ds'> 842typedef struct { 843 unsigned long sequence_of_request; 844 int major_opcode_of_request; 845 int minor_opcode_of_request; 846 IcePointer reply; 847} IceReplyWaitInfo; 848</literallayout> 849 850<para><function>IceReplyWaitInfo</function> 851contains the major/minor opcodes and sequence number of 852the message for which a reply is being awaited. 853It also contains a pointer to the reply message to be filled in 854(the protocol library should cast this 855<function>IcePointer</function> 856to the appropriate reply type). 857In most cases, the reply will have some fixed-size part, and the client waiting 858for the reply will have provided a pointer to a structure to hold 859this fixed-size data. If there is variable-length data, it would be 860expected that the 861<function>IcePoProcessMsgProc</function> 862callback will have to allocate additional 863memory and store pointer(s) to that memory in the fixed-size 864structure. If the entire data is variable length (for example., a single 865variable-length string), then the client waiting for the reply would probably 866just pass a pointer to fixed-size space to hold a pointer, and the 867<function>IcePoProcessMsgProc</function> 868callback would allocate the storage and store the pointer. 869It is the responsibility of the client receiving the reply to 870free any memory allocated on its behalf.</para> 871 872<para>If reply_wait is not NULL and 873<function>IcePoProcessMsgProc</function> 874has a reply or error to return in response to this reply_wait 875(that is, no callback was generated), then the reply_ready_ret argument 876should be set to 877<function>True</function> 878Note that an error should only be returned 879if it corresponds to the reply being waited for. Otherwise, the 880<function>IcePoProcessMsgProc</function> 881should either handle the error internally or invoke an error handler 882for its library.</para> 883 884<para>If reply_wait is NULL, 885then care must be taken not to store any value in reply_ready_ret, 886because this pointer may also be NULL.</para> 887 888<para>The 889<xref linkend='IcePaProcessMsgProc' xrefstyle='select: title'/> 890callback, on the other hand, should always pass 891the message to the client via a callback. For example, if this is a Session 892Management "Interact Request" message, this function should notify the 893client of the "Interact Request" via a callback.</para> 894 895<para>The reason the 896<xref linkend='IcePaProcessMsgProc' xrefstyle='select: title'/> 897callback does not have a reply_wait, like 898<function>IcePoProcessMsgProc</function> 899does, is because a process that is acting as 900a server should never block for a reply (infinite blocking can 901occur if the connecting client does not act properly, denying access 902to other clients).</para> 903</sect1> 904 905<sect1 id='Authentication_Methods'> 906<title>Authentication Methods</title> 907 908<para>As already stated, a protocol library must register the authentication 909methods that it supports with the ICE library. For each authentication 910method, there are two callbacks that may be registered:</para> 911<itemizedlist> 912 <listitem> 913 <para> 914One to handle the side that initiates a <function>ProtocolSetup</function> 915 </para> 916 </listitem> 917 <listitem> 918 <para> 919One to handle the side that accepts or rejects this request 920 </para> 921 </listitem> 922</itemizedlist> 923 924<para><function>IcePoAuthProc</function> 925is the callback invoked for the client that initiated the 926<function>ProtocolSetup</function> 927This callback must be able to respond 928to the initial "Authentication Required" message or subsequent 929"Authentication Next Phase" messages sent by the other client.</para> 930 931 932<funcsynopsis id='IcePoAuthStatus'> 933<funcprototype> 934 <funcdef>IcePoAuthStatus <function>IcePoAuthStatus </function></funcdef> 935 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 936 <paramdef>IcePointer<parameter> client_data</parameter></paramdef> 937 <paramdef>int<parameter> opcode</parameter></paramdef> 938</funcprototype> 939</funcsynopsis> 940 941 942<variablelist remap='IP'> 943 <varlistentry> 944 <term><emphasis remap='I'>ice_conn</emphasis></term> 945 <listitem><para>The ICE connection object.</para></listitem> 946 </varlistentry> 947 <varlistentry> 948 <term><emphasis remap='I'>auth_state_ptr</emphasis></term> 949 <listitem> 950<para>A pointer to state for use by the authentication callback procedure.</para> 951 </listitem> 952 </varlistentry> 953 <varlistentry> 954 <term><emphasis remap='I'>clean_up</emphasis></term> 955 <listitem> 956<para>If 957<function>True</function> 958authentication is over, and the function 959should clean up any state it was maintaining. The 960last 6 arguments should be ignored.</para> 961 </listitem> 962 </varlistentry> 963 <varlistentry> 964 <term><emphasis remap='I'>swap</emphasis></term> 965 <listitem> 966<para>If 967<function>True</function> 968the auth_data may have to be byte swapped 969(depending on its contents).</para> 970 </listitem> 971 </varlistentry> 972 <varlistentry> 973 <term><emphasis remap='I'>auth_datalen</emphasis></term> 974 <listitem> 975<para>The length (in bytes) of the authenticator data.</para> 976 </listitem> 977 </varlistentry> 978 <varlistentry> 979 <term><emphasis remap='I'>auth_data</emphasis></term> 980 <listitem> 981<para>The data from the authenticator.</para> 982 </listitem> 983 </varlistentry> 984 <varlistentry> 985 <term><emphasis remap='I'>reply_datalen_ret</emphasis></term> 986 <listitem> 987<para>The length (in bytes) of the reply data returned.</para> 988 </listitem> 989 </varlistentry> 990 <varlistentry> 991 <term><emphasis remap='I'>reply_data_ret</emphasis></term> 992 <listitem> 993<para>The reply data returned.</para> 994 </listitem> 995 </varlistentry> 996 <varlistentry> 997 <term><emphasis remap='I'>error_string_ret</emphasis></term> 998 <listitem> 999<para>If the authentication procedure encounters an error during 1000authentication, it should allocate and return 1001an error string.</para> 1002 </listitem> 1003 </varlistentry> 1004</variablelist> 1005 1006 1007<para>Authentication may require several phases, depending on the authentication 1008method. As a result, the 1009<function>IcePoAuthProc</function> 1010may be called more than once when authenticating a client, and 1011some state will have to be maintained between each invocation. 1012At the start of each 1013<function>ProtocolSetup</function> 1014*auth_state_ptr is NULL, 1015and the function should initialize its state and set 1016this pointer. In subsequent invocations of the callback, the pointer 1017should be used to get at any state previously stored by the callback.</para> 1018 1019<para>If needed, the network ID of the client accepting the 1020<function>ProtocolSetup</function> 1021can be obtained by calling the 1022<function>IceConnectionString</function> 1023function.</para> 1024 1025<para>ICElib will be responsible for freeing the reply_data_ret and 1026error_string_ret pointers with 1027<function>free</function></para> 1028 1029<para>The auth_data pointer may point to a volatile block of memory. 1030If the data must be kept beyond this invocation of the callback, be sure 1031to make a copy of it.</para> 1032 1033<para>The 1034<function>IcePoAuthProc</function> 1035should return one of four values:</para> 1036<itemizedlist> 1037 <listitem> 1038<para><function>IcePoAuthHaveReply</function> 1039- a reply is available.</para> 1040 </listitem> 1041 <listitem> 1042<para><function>IcePoAuthRejected</function> 1043- authentication rejected.</para> 1044 </listitem> 1045 <listitem> 1046<para><function>IcePoAuthFailed</function> 1047- authentication failed.</para> 1048 </listitem> 1049 <listitem> 1050<para><function>IcePoAuthDoneCleanup</function> 1051- done cleaning up.</para> 1052 </listitem> 1053</itemizedlist> 1054 1055<para><function>IcePaAuthProc</function> 1056is the callback invoked for the client that received the 1057<function>ProtocolSetup</function></para> 1058 1059<funcsynopsis id='PoAuthStatus'> 1060<funcprototype> 1061 <funcdef>IcePoAuthStatus <function>PoAuthStatus </function></funcdef> 1062 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 1063 <paramdef>IcePointer<parameter> *auth_state_ptr</parameter></paramdef> 1064 <paramdef>Bool<parameter> swap</parameter></paramdef> 1065 <paramdef>int<parameter> auth_datalen</parameter></paramdef> 1066 <paramdef>IcePointer<parameter> auth_data</parameter></paramdef> 1067 <paramdef>int<parameter> *reply_datalen_ret</parameter></paramdef> 1068 <paramdef>IcePointer<parameter> *reply_data_ret</parameter></paramdef> 1069 <paramdef>char<parameter> **error_string_ret</parameter></paramdef> 1070</funcprototype> 1071</funcsynopsis> 1072 1073<variablelist remap='IP'> 1074 <varlistentry> 1075 <term><emphasis remap='I'>ice_conn</emphasis></term> 1076 <listitem><para>The ICE connection object.</para></listitem> 1077 </varlistentry> 1078 <varlistentry> 1079 <term><emphasis remap='I'>auth_state_ptr</emphasis></term> 1080 <listitem> 1081<para>A pointer to state for use by the authentication callback procedure.</para> 1082 </listitem> 1083 </varlistentry> 1084 <varlistentry> 1085 <term><emphasis remap='I'>swap</emphasis></term> 1086 <listitem> 1087<para>If 1088<function>True</function> 1089auth_data may have to be byte swapped 1090(depending on its contents).</para> 1091 </listitem> 1092 </varlistentry> 1093 <varlistentry> 1094 <term><emphasis remap='I'>auth_datalen</emphasis></term> 1095 <listitem> 1096<para>The length (in bytes) of the protocol originator authentication data.</para> 1097 </listitem> 1098 </varlistentry> 1099 <varlistentry> 1100 <term><emphasis remap='I'>auth_data</emphasis></term> 1101 <listitem> 1102<para>The authentication data from the protocol originator.</para> 1103 </listitem> 1104 </varlistentry> 1105 <varlistentry> 1106 <term><emphasis remap='I'>reply_datalen_ret</emphasis></term> 1107 <listitem> 1108<para>The length of the authentication data returned.</para> 1109 </listitem> 1110 </varlistentry> 1111 <varlistentry> 1112 <term><emphasis remap='I'>reply_data_ret</emphasis></term> 1113 <listitem> 1114<para>The authentication data returned.</para> 1115 </listitem> 1116 </varlistentry> 1117 <varlistentry> 1118 <term><emphasis remap='I'>error_string_ret</emphasis></term> 1119 <listitem> 1120<para>If authentication is rejected or fails, an error 1121string is returned.</para> 1122 </listitem> 1123 </varlistentry> 1124</variablelist> 1125 1126 1127<para>Authentication may require several phases, depending on the authentication 1128method. As a result, the 1129<function>IcePaAuthProc</function> 1130may be called more than once when authenticating a client, and 1131some state will have to be maintained between each invocation. 1132At the start of each 1133<function>ProtocolSetup</function> 1134auth_datalen is zero, 1135*auth_state_ptr is NULL, 1136and the function should initialize its state and set 1137this pointer. In subsequent invocations of the callback, the pointer 1138should be used to get at any state previously stored by the callback.</para> 1139 1140<para>If needed, the network ID of the client accepting the 1141<function>ProtocolSetup</function> 1142can be obtained by calling the 1143<function>IceConnectionString</function> 1144function.</para> 1145 1146<para>The auth_data pointer may point to a volatile block of memory. 1147If the data must be kept beyond this invocation of the callback, be sure 1148to make a copy of it.</para> 1149 1150<para>ICElib will be responsible for transmitting and freeing the reply_data_ret and 1151error_string_ret pointers with 1152<function>free</function></para> 1153 1154<para> 1155The <function>IcePaAuthProc</function> should return one of four values: 1156</para> 1157 1158 1159<itemizedlist> 1160 <listitem> 1161 <para> 1162<function>IcePaAuthContinue</function> - continue (or start) authentication. 1163 </para> 1164 </listitem> 1165 <listitem> 1166 <para> 1167<function>IcePaAuthAccepted</function> - authentication accepted. 1168 </para> 1169 </listitem> 1170 <listitem> 1171 <para> 1172<function>IcePaAuthRejected</function> - authentication rejected. 1173 </para> 1174 </listitem> 1175 <listitem> 1176 <para> 1177<function>IcePaAuthFailed</function> - authentication failed. 1178 </para> 1179 </listitem> 1180</itemizedlist> 1181</sect1> 1182 1183</chapter> 1184 1185<chapter id='ICE_Connections'> 1186<title>ICE Connections</title> 1187 1188<para> 1189In order for two clients to establish an ICE connection, one client has to be 1190waiting for connections, and the other client has to initiate the connection. 1191Most clients will initiate connections, so we discuss that first. 1192</para> 1193 1194<sect1 id='Opening_an_ICE_Connection'> 1195<title>Opening an ICE Connection</title> 1196 1197 1198<para> 1199To open an ICE connection with another client (that is, waiting 1200for connections), use <xref linkend='IceOpenConnection' xrefstyle='select: title'/> 1201</para> 1202 1203<funcsynopsis id='IceOpenConnection'> 1204<funcprototype> 1205 <funcdef>IceConn <function>IceOpenConnection</function></funcdef> 1206 <paramdef>char<parameter> *network_ids_list</parameter></paramdef> 1207 <paramdef>IcePointer<parameter> context</parameter></paramdef> 1208 <paramdef>Bool<parameter> must_authenticate</parameter></paramdef> 1209 <paramdef>int<parameter> major_opcode_check</parameter></paramdef> 1210 <paramdef>int<parameter> error_length</parameter></paramdef> 1211 <paramdef>char<parameter> *error_string_ret</parameter></paramdef> 1212</funcprototype> 1213</funcsynopsis> 1214 1215<variablelist remap='IP'> 1216 <varlistentry> 1217 <term><emphasis remap='I'>network_ids_list</emphasis></term> 1218 <listitem> 1219 <para> 1220Specifies the network ID(s) of the other client. 1221 </para> 1222 </listitem> 1223 </varlistentry> 1224 <varlistentry> 1225 <term><emphasis remap='I'>context</emphasis></term> 1226 <listitem> 1227 <para> 1228A pointer to an opaque object or NULL. Used to determine if an 1229ICE connection can be shared (see below). 1230 </para> 1231 </listitem> 1232 </varlistentry> 1233 <varlistentry> 1234 <term><emphasis remap='I'>must_authenticate</emphasis></term> 1235 <listitem> 1236 <para> 1237If <function>True</function> the other client may not bypass authentication. 1238 </para> 1239 </listitem> 1240 </varlistentry> 1241 <varlistentry> 1242 <term><emphasis remap='I'>major_opcode_check</emphasis></term> 1243 <listitem> 1244 <para> 1245Used to force a new ICE connection to be created (see below). 1246 </para> 1247 </listitem> 1248 </varlistentry> 1249 <varlistentry> 1250 <term><emphasis remap='I'>error_length</emphasis></term> 1251 <listitem> 1252 <para>Length of the error_string_ret argument passed in.</para> 1253 </listitem> 1254 </varlistentry> 1255 <varlistentry> 1256 <term><emphasis remap='I'>error_string_ret</emphasis></term> 1257 <listitem> 1258 <para> 1259Returns a null-terminated error message, if any. The error_string_ret 1260argument points to user supplied memory. No more than error_length bytes 1261are used. 1262 </para> 1263 </listitem> 1264 </varlistentry> 1265</variablelist> 1266 1267 1268<para> 1269<xref linkend='IceOpenConnection' xrefstyle='select: title'/> 1270returns an opaque ICE connection object if it succeeds; 1271otherwise, it returns NULL. 1272</para> 1273 1274<para> 1275The network_ids_list argument contains a list of network IDs separated 1276by commas. An attempt will be made to use the first network ID. If 1277that fails, an attempt will be made using the second network ID, and so on. 1278Each network ID has the following format: 1279</para> 1280 1281<informaltable frame='none'> 1282 <?dbfo keep-together="always" ?> 1283 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1284 <colspec colname='c1' colwidth='1.0*'/> 1285 <colspec colname='c2' colwidth='2.0*'/> 1286 <tbody> 1287 <row> 1288 <entry>tcp/<hostname>:<portnumber></entry> 1289 <entry>or</entry> 1290 </row> 1291 <row> 1292 <entry>decnet/<hostname>::<objname></entry> 1293 <entry>or</entry> 1294 </row> 1295 <row> 1296 <entry>local/<hostname>:<path></entry> 1297 <entry></entry> 1298 </row> 1299 </tbody> 1300 </tgroup> 1301</informaltable> 1302 1303 1304<para>Most protocol libraries will have some sort of open function that should 1305internally make a call into 1306<xref linkend='IceOpenConnection' xrefstyle='select: title'/> 1307When 1308<xref linkend='IceOpenConnection' xrefstyle='select: title'/> 1309is called, it may be possible to use a previously opened ICE connection (if 1310the target client is the same). However, there are cases in which shared 1311ICE connections are not desired.</para> 1312 1313<para>The context argument is used to determine if an ICE connection can 1314be shared. 1315If context is NULL, 1316then the caller is always willing to share the connection. 1317If context is not NULL, 1318then the caller is not willing to use a previously opened ICE connection 1319that has a different non-NULL context associated with it.</para> 1320 1321<para>In addition, if major_opcode_check contains a nonzero major opcode value, 1322a previously created ICE connection will be used only if the major opcode 1323is not active on the connection. This can be used to force multiple ICE 1324connections between two clients for the same protocol.</para> 1325 1326<para>Any authentication requirements are handled internally by the ICE library. 1327The method by which the authentication data is obtained 1328is implementation-dependent. 1329 <footnote remap='FS'> 1330<para>The X Consortium's ICElib implementation uses an .ICEauthority file (see 1331Appendix A). 1332 </para></footnote> </para> 1333 1334<para>After 1335<xref linkend='IceOpenConnection' xrefstyle='select: title'/> 1336is called, the client is ready to send a 1337<function>ProtocolSetup</function> 1338(provided that 1339<xref linkend='IceRegisterForProtocolSetup' xrefstyle='select: title'/> 1340was called) or receive a 1341<function>ProtocolSetup</function> 1342(provided that 1343<xref linkend='IceRegisterForProtocolReply' xrefstyle='select: title'/> 1344was called).</para> 1345</sect1> 1346 1347<sect1 id='Listening_for_ICE_Connections'> 1348<title>Listening for ICE Connections</title> 1349 1350<para>Clients wishing to accept ICE connections must first call 1351<xref linkend='IceListenForConnections' xrefstyle='select: title'/> 1352or 1353<xref linkend='IceListenForWellKnownConnections' xrefstyle='select: title'/> 1354so that they can listen for connections. A list of opaque "listen" objects are 1355returned, one for each type of transport method that is available 1356(for example, Unix Domain, TCP, DECnet, and so on).</para> 1357 1358<para>Normally clients will let ICElib allocate an available name in each 1359transport and return listen objects. Such a client will then use 1360<xref linkend='IceComposeNetworkIdList' xrefstyle='select: title'/> 1361to extract the chosen names and make them 1362available to other clients for opening the connection. In certain 1363cases it may be necessary for a client to listen for connections 1364on pre-arranged transport object names. Such a client may use 1365<xref linkend='IceListenForWellKnownConnections' xrefstyle='select: title'/> 1366to specify the names for the listen objects.</para> 1367 1368<funcsynopsis id='IceListenForConnections'> 1369<funcprototype> 1370 <funcdef>Status <function>IceListenForConnections</function></funcdef> 1371 <paramdef>int<parameter> *count_ret</parameter></paramdef> 1372 <paramdef>IceListenObj<parameter> **listen_objs_ret</parameter></paramdef> 1373 <paramdef>int<parameter> error_length</parameter></paramdef> 1374 <paramdef>char<parameter> *error_string_ret</parameter></paramdef> 1375</funcprototype> 1376</funcsynopsis> 1377 1378<variablelist remap='IP'> 1379 <varlistentry> 1380 <term><emphasis remap='I'>count_ret</emphasis></term> 1381 <listitem><para>Returns the number of listen objects created.</para></listitem> 1382 </varlistentry> 1383 <varlistentry> 1384 <term><emphasis remap='I'>listen_objs_ret</emphasis></term> 1385 <listitem><para>Returns a list of pointers to opaque listen objects.</para></listitem> 1386 </varlistentry> 1387 <varlistentry> 1388 <term><emphasis remap='I'>error_length</emphasis></term> 1389 <listitem> 1390<para>The length of the error_string_ret argument passed in.</para> 1391 </listitem> 1392 </varlistentry> 1393 <varlistentry> 1394 <term><emphasis remap='I'>error_string_ret</emphasis></term> 1395 <listitem> 1396<para>Returns a null-terminated error message, if any. 1397The error_string_ret points to user supplied memory. 1398No more than error_length bytes are used.</para> 1399 </listitem> 1400 </varlistentry> 1401</variablelist> 1402 1403 1404<para>The return value of 1405<xref linkend='IceListenForConnections' xrefstyle='select: title'/> 1406is zero for failure and a positive value for success.</para> 1407 1408<funcsynopsis id='IceListenForWellKnownConnections'> 1409<funcprototype> 1410 <funcdef>Status <function>IceListenForWellKnownConnections</function></funcdef> 1411 <paramdef>char<parameter> *port_id</parameter></paramdef> 1412 <paramdef>int<parameter> *count_ret</parameter></paramdef> 1413 <paramdef>IceListenObj<parameter> **listen_objs_ret</parameter></paramdef> 1414 <paramdef>int<parameter> error_length</parameter></paramdef> 1415 <paramdef>char<parameter> *error_string_ret</parameter></paramdef> 1416</funcprototype> 1417</funcsynopsis> 1418 1419<variablelist remap='IP'> 1420 <varlistentry> 1421 <term><emphasis remap='I'>port_id</emphasis></term> 1422 <listitem> 1423 <para> 1424Specifies the port identification for the address(es) to be opened. The 1425value must not contain the slash ("/"> or comma (".") character; thse are 1426reserved for future use. 1427 </para> 1428 </listitem> 1429 </varlistentry> 1430 <varlistentry> 1431 <term><emphasis remap='I'>count_ret</emphasis></term> 1432 <listitem> 1433 <para>Returns the number of listen objects created.</para> 1434 </listitem> 1435 </varlistentry> 1436 <varlistentry> 1437 <term><emphasis remap='I'>listen_objs_ret</emphasis></term> 1438 <listitem> 1439 <para> 1440Returns a list of pointers to opaque listen objects. 1441 </para> 1442 </listitem> 1443 </varlistentry> 1444 <varlistentry> 1445 <term><emphasis remap='I'>listen_objs_ret</emphasis></term> 1446 <listitem> 1447 <para> 1448Returns a list of pointers to opaque listen objects. 1449 </para> 1450 </listitem> 1451 </varlistentry> 1452 <varlistentry> 1453 <term><emphasis remap='I'>error_length</emphasis></term> 1454 <listitem> 1455 <para> 1456The length of the error_string_ret argument passed in. 1457 </para> 1458 </listitem> 1459 </varlistentry> 1460 <varlistentry> 1461 <term><emphasis remap='I'>error_string_ret</emphasis></term> 1462 <listitem> 1463 <para> 1464Returns a null-terminated error message, if any. The error_string_ret 1465points to user supplied memory. No more than error_length bytes are used. 1466 </para> 1467 </listitem> 1468 </varlistentry> 1469</variablelist> 1470 1471<para> 1472<xref linkend='IceListenForWellKnownConnections' xrefstyle='select: title'/> constructs a list 1473of network IDs by prepending each known transport to port_id and then 1474attempts to create listen objects for the result. Port_id is the portnumber, 1475objname, or path portion of the ICE network ID. If a listen object for 1476a particular network ID cannot be created the network ID is ignored. 1477If no listen objects are created 1478<xref linkend='IceListenForWellKnownConnections' xrefstyle='select: title'/> 1479returns failure. 1480</para> 1481 1482<para> 1483The return value of <xref linkend='IceListenForWellKnownConnections' xrefstyle='select: title'/> 1484is zero for failure and a positive value for success. 1485</para> 1486 1487<para> 1488To close and free the listen objects, use 1489<xref linkend='IceFreeListenObjs' xrefstyle='select: title'/> 1490</para> 1491 1492<funcsynopsis id='IceFreeListenObjs'> 1493<funcprototype> 1494 <funcdef>void <function>IceFreeListenObjs</function></funcdef> 1495 <paramdef>int<parameter> count</parameter></paramdef> 1496 <paramdef>IceListenObj<parameter> *listen_objs</parameter></paramdef> 1497</funcprototype> 1498</funcsynopsis> 1499 1500<variablelist remap='IP'> 1501 <varlistentry> 1502 <term><emphasis remap='I'>count</emphasis></term> 1503 <listitem> 1504 <para>The number of listen objects.</para> 1505 </listitem> 1506 </varlistentry> 1507 <varlistentry> 1508 <term><emphasis remap='I'>listen_objs</emphasis></term> 1509 <listitem> 1510 <para>The listen objects.</para> 1511 </listitem> 1512 </varlistentry> 1513</variablelist> 1514 1515 1516<para> 1517To detect a new connection on a listen object, use 1518<function>select</function> on the descriptor associated with 1519the listen object. 1520</para> 1521 1522<para> 1523To obtain the descriptor, use 1524<xref linkend='IceGetListenConnectionNumber' xrefstyle='select: title'/> 1525</para> 1526 1527<funcsynopsis id='IceGetListenConnectionNumber'> 1528<funcprototype> 1529 <funcdef>int <function>IceGetListenConnectionNumber</function></funcdef> 1530 <paramdef>IceListenObj<parameter> *listen_objs</parameter></paramdef> 1531</funcprototype> 1532</funcsynopsis> 1533 1534<variablelist remap='IP'> 1535 <varlistentry> 1536 <term><emphasis remap='I'>listen_obj</emphasis></term> 1537 <listitem> 1538 <para>The listen objects.</para> 1539 </listitem> 1540 </varlistentry> 1541</variablelist> 1542 1543<para> 1544To obtain the network ID string associated with a listen object, use 1545<xref linkend='IceGetListenConnectionString' xrefstyle='select: title'/> 1546</para> 1547 1548 1549<funcsynopsis id='IceGetListenConnectionString'> 1550<funcprototype> 1551 <funcdef>char <function>IceGetListenConnectionString</function></funcdef> 1552 <paramdef>IceListenObj<parameter> listen_obj</parameter></paramdef> 1553</funcprototype> 1554</funcsynopsis> 1555 1556<variablelist remap='IP'> 1557 <varlistentry> 1558 <term><emphasis remap='I'>listen_obj</emphasis></term> 1559 <listitem> 1560 <para>The listen objects.</para> 1561 </listitem> 1562 </varlistentry> 1563</variablelist> 1564 1565<para>A network ID has the following format:</para> 1566 1567<informaltable frame='none'> 1568 <?dbfo keep-together="always" ?> 1569 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 1570 <colspec colname='c1' colwidth='1.0*'/> 1571 <colspec colname='c2' colwidth='2.0*'/> 1572 <tbody> 1573 <row> 1574 <entry>tcp/<hostname>:<portnumber></entry> 1575 <entry>or</entry> 1576 </row> 1577 <row> 1578 <entry>decnet/<hostname>::<objname></entry> 1579 <entry>or</entry> 1580 </row> 1581 <row> 1582 <entry>local/<hostname>:<path></entry> 1583 <entry></entry> 1584 </row> 1585 </tbody> 1586 </tgroup> 1587</informaltable> 1588 1589<para> 1590To compose a string containing a list of network IDs separated by commas 1591(the format recognized by <xref linkend='IceOpenConnection' xrefstyle='select: title'/> 1592use <xref linkend='IceComposeNetworkIdList' xrefstyle='select: title'/> 1593</para> 1594 1595<funcsynopsis id='IceComposeNetworkIdList'> 1596<funcprototype> 1597 <funcdef>char <function>IceComposeNetworkIdList</function></funcdef> 1598 <paramdef>int<parameter> count</parameter></paramdef> 1599 <paramdef>IceListenObj<parameter> *listen_objs</parameter></paramdef> 1600</funcprototype> 1601</funcsynopsis> 1602 1603<variablelist remap='IP'> 1604 <varlistentry> 1605 <term><emphasis remap='I'>count</emphasis></term> 1606 <listitem> 1607 <para>The number of listen objects.</para> 1608 </listitem> 1609 </varlistentry> 1610 <varlistentry> 1611 <term><emphasis remap='I'>listen_objs</emphasis></term> 1612 <listitem> 1613 <para>The listen objects.</para> 1614 </listitem> 1615 </varlistentry> 1616</variablelist> 1617 1618</sect1> 1619 1620<sect1 id='Host_Based_Authentication_for_ICE_Connections'> 1621<title>Host Based Authentication for ICE Connections</title> 1622 1623<para> 1624If authentication fails when a client attempts to open an 1625ICE connection and the initiating client has not required authentication, 1626a host based authentication procedure may be invoked to provide 1627a last chance for the client to connect. Each listen object has such a 1628callback associated with it, and this callback is set using the 1629<xref linkend='IceSetHostBasedAuthProc' xrefstyle='select: title'/> 1630function. 1631</para> 1632 1633<funcsynopsis id='IceSetHostBasedAuthProc'> 1634<funcprototype> 1635 <funcdef>void <function>IceSetHostBasedAuthProc</function></funcdef> 1636 <paramdef>IceListenObj<parameter> listen_obj</parameter></paramdef> 1637 <paramdef>IceHostBasedAuthProc<parameter> host_based_auth_proc</parameter></paramdef> 1638</funcprototype> 1639</funcsynopsis> 1640 1641<variablelist remap='IP'> 1642 <varlistentry> 1643 <term><emphasis remap='I'>IceListenObj</emphasis></term> 1644 <listitem> 1645 <para>The listen object.</para> 1646 </listitem> 1647 </varlistentry> 1648 <varlistentry> 1649 <term><emphasis remap='I'>host_based_auth_proc</emphasis></term> 1650 <listitem> 1651 <para>The host based authentication procedure.</para> 1652 </listitem> 1653 </varlistentry> 1654</variablelist> 1655 1656 1657<para> 1658By default, each listen object has no host based authentication procedure 1659associated with it. Passing NULL for host_based_auth_proc turns off 1660host based authentication if it was previously set. 1661</para> 1662 1663 1664<funcsynopsis id='HostBasedAuthProc'> 1665<funcprototype> 1666 <funcdef>Bool <function>HostBasedAuthProc</function></funcdef> 1667 <paramdef>char<parameter> *host_name</parameter></paramdef> 1668</funcprototype> 1669</funcsynopsis> 1670 1671<variablelist remap='IP'> 1672 <varlistentry> 1673 <term><emphasis remap='I'>host_name</emphasis></term> 1674 <listitem> 1675 <para> 1676The host name of the client that tried to open an ICE connection. 1677 </para> 1678 </listitem> 1679 </varlistentry> 1680</variablelist> 1681 1682 1683<para> 1684The host_name argument is a string in the form 1685<emphasis remap='I'>protocol</emphasis>/ 1686<emphasis remap='I'>hostname</emphasis>, 1687where <emphasis remap='I'>protocol</emphasis> is one of 1688{tcp, decnet, local}. 1689</para> 1690 1691<para> 1692If <function>IceHostBasedAuthProc</function> returns 1693<function>True</function> 1694access will be granted, even though the original authentication failed. 1695Note that authentication can effectively be disabled by registering an 1696<function>IceHostBasedAuthProc</function> 1697which always returns <function>True</function> 1698</para> 1699 1700<para> 1701Host based authentication is also allowed at 1702<function>ProtocolSetup</function> time. 1703The callback is specified in the 1704<xref linkend='IceRegisterForProtocolReply' xrefstyle='select: title'/> 1705function (see 1706<xref linkend='Protocol_Registration' xrefstyle='select: title'/>). 1707</para> 1708</sect1> 1709 1710<sect1 id='Accepting_ICE_Connections'> 1711<title>Accepting ICE Connections</title> 1712 1713 1714<para> 1715After a connection attempt is detected on a listen object returned by 1716<xref linkend='IceListenForConnections' xrefstyle='select: title'/> 1717you should call <xref linkend='IceAcceptConnection' xrefstyle='select: title'/> 1718This returns a new opaque ICE connection object. 1719</para> 1720 1721<funcsynopsis id='IceAcceptConnection'> 1722<funcprototype> 1723 <funcdef>IceConn <function>IceAcceptConnection</function></funcdef> 1724 <paramdef>IceListenObj<parameter> listen_obj</parameter></paramdef> 1725 <paramdef>IceAcceptStatus<parameter> *status_ret</parameter></paramdef> 1726</funcprototype> 1727</funcsynopsis> 1728 1729 1730<variablelist remap='IP'> 1731 <varlistentry> 1732 <term><emphasis remap='I'>listen_obj</emphasis></term> 1733 <listitem> 1734<para>The listen object on which a new connection was detected.</para> 1735 </listitem> 1736 </varlistentry> 1737 </variablelist> 1738 <variablelist remap='IP'> 1739 <varlistentry> 1740 <term><emphasis remap='I'>status_ret</emphasis></term> 1741 <listitem> 1742<para>Return status information.</para> 1743 </listitem> 1744 </varlistentry> 1745</variablelist> 1746 1747 1748<para>The status_ret argument is set to one of the following values:</para> 1749<itemizedlist> 1750 <listitem> 1751<para><function>IceAcceptSuccess</function> 1752- the accept operation succeeded, 1753and the function returns a new connection object.</para> 1754 </listitem> 1755 <listitem> 1756<para><function>IceAcceptFailure</function> 1757- the accept operation failed, and the function returns NULL.</para> 1758 </listitem> 1759 <listitem> 1760<para><function>IceAcceptBadMalloc</function> 1761- a memory allocation failed, and the function returns NULL.</para> 1762 </listitem> 1763</itemizedlist> 1764 1765<para>In general, to detect new connections, you should call 1766<function>select</function> 1767on the file descriptors associated with the listen objects. 1768When a new connection is detected, the 1769<xref linkend='IceAcceptConnection' xrefstyle='select: title'/> 1770function should be called. 1771<xref linkend='IceAcceptConnection' xrefstyle='select: title'/> 1772may return a new ICE connection that is in a pending state. This is because 1773before the connection can become valid, authentication may be necessary. 1774Because the ICE library cannot block and wait for the connection to 1775become valid (infinite blocking can occur if the connecting client 1776does not act properly), the application must wait for the connection status 1777to become valid.</para> 1778 1779<para>The following pseudo-code demonstrates how connections are accepted:</para> 1780 1781<literallayout class="monospaced"> 1782new_ice_conn = IceAcceptConnection (listen_obj, &accept_status); 1783if (accept_status != IceAcceptSuccess) 1784{ 1785 close the file descriptor and return 1786} 1787 1788status = IceConnectionStatus (new_ice_conn); 1789time_start = time_now; 1790 1791while (status == IceConnectPending) 1792{ 1793 select() on {new_ice_conn, all open connections} 1794 1795 for (each ice_conn in the list of open connections) 1796 if (data ready on ice_conn) 1797 { 1798 status = IceProcessMessages (ice_conn, NULL, NULL); 1799 if (status == IceProcessMessagesIOError) 1800 IceCloseConnection(ice_conn); 1801 } 1802 if data ready on new_ice_conn 1803 { 1804 /* 1805 * IceProcessMessages is called until the connection 1806 * is non-pending. Doing so handles the connection 1807 * setup request and any authentication requirements. 1808 */ 1809 1810 IceProcessMessages ( new_ice_conn, NULL, NULL); 1811 status = IceConnectionStatus (new_ice_conn); 1812 } 1813 else 1814 { 1815 if (time_now - time_start > MAX_WAIT_TIME) 1816 status = IceConnectRejected; 1817 } 1818} 1819 1820if (status == IceConnectAccepted) 1821{ 1822 Add new_ice_conn to the list of open connections 1823} 1824else 1825{ 1826 IceCloseConnection 1827 new_ice_conn 1828} 1829</literallayout> 1830 1831<para>After 1832<xref linkend='IceAcceptConnection' xrefstyle='select: title'/> 1833is called and the connection has been 1834validated, the client is ready to receive a 1835<function>ProtocolSetup</function> 1836(provided 1837that 1838<xref linkend='IceRegisterForProtocolReply' xrefstyle='select: title'/> 1839was called) or send a 1840<function>ProtocolSetup</function> 1841(provided that 1842<xref linkend='IceRegisterForProtocolSetup' xrefstyle='select: title'/> 1843was called).</para> 1844</sect1> 1845 1846<sect1 id='Closing_ICE_Connections'> 1847<title>Closing ICE Connections</title> 1848 1849<para>To close an ICE connection created with 1850<xref linkend='IceOpenConnection' xrefstyle='select: title'/> 1851or 1852<xref linkend='IceAcceptConnection' xrefstyle='select: title'/> 1853use 1854<xref linkend='IceCloseConnection' xrefstyle='select: title'/></para> 1855 1856<funcsynopsis id='IceCloseConnection'> 1857<funcprototype> 1858 <funcdef>IceCloseStatus <function>IceCloseConnection</function></funcdef> 1859 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 1860</funcprototype> 1861</funcsynopsis> 1862 1863<variablelist remap='IP'> 1864 <varlistentry> 1865 <term><emphasis remap='I'>ice_conn</emphasis></term> 1866 <listitem> 1867 <para>The ICE connection to close.</para> 1868 </listitem> 1869 </varlistentry> 1870</variablelist> 1871 1872<para>To actually close an ICE connection, the following conditions 1873must be met:</para> 1874 1875<itemizedlist> 1876 <listitem> 1877<para>The <emphasis remap='I'>open reference count</emphasis> must have reached zero on this ICE connection. 1878When 1879<xref linkend='IceOpenConnection' xrefstyle='select: title'/> 1880is called, it tries to use a previously opened 1881ICE connection. If it is able to use an existing connection, it increments 1882the open reference count on the connection by one. 1883So, to close an ICE connection, each call to 1884<xref linkend='IceOpenConnection' xrefstyle='select: title'/> 1885must be matched with a call to 1886<xref linkend='IceCloseConnection' xrefstyle='select: title'/> 1887The connection can be closed only 1888on the last call to 1889<xref linkend='IceCloseConnection' xrefstyle='select: title'/></para> 1890 </listitem> 1891 <listitem> 1892<para>The <emphasis remap='I'>active protocol count</emphasis> must have reached zero. Each time a 1893<function>ProtocolSetup</function> 1894succeeds on the connection, the active protocol count 1895is incremented by one. When the client no longer expects to use the 1896protocol on the connection, the 1897<xref linkend='IceProtocolShutdown' xrefstyle='select: title'/> 1898function should be called, which decrements the active protocol count 1899by one (see 1900<xref linkend='Protocol_Setup_and_Shutdown' xrefstyle='select: title'/>). 1901</para> 1902 </listitem> 1903 <listitem> 1904<para>If shutdown negotiation is enabled on the connection, the client on the other 1905side of the ICE connection must agree to have the connection closed.</para> 1906 1907<para><xref linkend='IceCloseConnection' xrefstyle='select: title'/> 1908returns one of the following values:</para> 1909 </listitem> 1910 <listitem> 1911<para><function>IceClosedNow</function> 1912- the ICE connection was closed at this time. The watch procedures were 1913invoked and the connection was freed.</para> 1914 </listitem> 1915 <listitem> 1916<para><function>IceClosedASAP</function> 1917- an IO error had occurred on the connection, but 1918<xref linkend='IceCloseConnection' xrefstyle='select: title'/> 1919is being called within a nested 1920<xref linkend='IceProcessMessages' xrefstyle='select: title'/> 1921The watch procedures have been invoked at this time, but the connection 1922will be freed as soon as possible (when the nesting level reaches zero and 1923<xref linkend='IceProcessMessages' xrefstyle='select: title'/> 1924returns a status of 1925<function>IceProcessMessagesConnectionClosed</function></para> 1926 </listitem> 1927 <listitem> 1928<para><function>IceConnectionInUse</function> 1929- the connection was not closed at this time, because it is being used by 1930other active protocols.</para> 1931 </listitem> 1932 <listitem> 1933<para><function>IceStartedShutdownNegotiation</function> 1934- the connection was not closed at this time and shutdown negotiation started 1935with the client on the other side of the ICE connection. When the connection 1936is actually closed, 1937<xref linkend='IceProcessMessages' xrefstyle='select: title'/> 1938will return a status of 1939<function>IceProcessMessagesConnectionClosed</function></para> 1940 </listitem> 1941</itemizedlist> 1942 1943<para>When it is known that the client on the other side of the ICE connection 1944has terminated the connection without initiating shutdown negotiation, the 1945<xref linkend='IceSetShutdownNegotiation' xrefstyle='select: title'/> 1946function should be called to turn off shutdown negotiation. This will prevent 1947<xref linkend='IceCloseConnection' xrefstyle='select: title'/> 1948from writing to a broken connection.</para> 1949 1950<funcsynopsis id='IceSetShutdownNegotiation'> 1951<funcprototype> 1952 <funcdef>void <function>IceSetShutdownNegotiation</function></funcdef> 1953 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 1954 <paramdef>Bool<parameter> negotiate</parameter></paramdef> 1955</funcprototype> 1956</funcsynopsis> 1957 1958<variablelist remap='IP'> 1959 <varlistentry> 1960 <term><emphasis remap='I'>ice_conn</emphasis></term> 1961 <listitem> 1962 <para>A valid ICE connection object.</para> 1963 </listitem> 1964 </varlistentry> 1965 <varlistentry> 1966 <term><emphasis remap='I'>negotiate</emphasis></term> 1967 <listitem> 1968<para>If 1969<function>False</function> 1970shutdown negotiating will be turned off.</para> 1971 </listitem> 1972 </varlistentry> 1973</variablelist> 1974 1975<para>To check the shutdown negotiation status of an ICE connection, use 1976<xref linkend='IceCheckShutdownNegotiation' xrefstyle='select: title'/></para> 1977 1978<funcsynopsis id='IceCheckShutdownNegotiation'> 1979<funcprototype> 1980 <funcdef>Bool <function>IceCheckShutdownNegotiation</function></funcdef> 1981 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 1982</funcprototype> 1983</funcsynopsis> 1984 1985<variablelist remap='IP'> 1986 <varlistentry> 1987 <term><emphasis remap='I'>ice_conn</emphasis></term> 1988 <listitem> 1989 <para>A valid ICE connection object.</para> 1990 </listitem> 1991 </varlistentry> 1992</variablelist> 1993 1994 1995<para><xref linkend='IceCheckShutdownNegotiation' xrefstyle='select: title'/> 1996returns 1997<function>True</function> 1998if shutdown negotiation will take place on the connection; 1999otherwise, it returns 2000<function>False</function> 2001Negotiation is on by default for a connection. It 2002can only be changed with the 2003<xref linkend='IceSetShutdownNegotiation' xrefstyle='select: title'/> 2004function.</para> 2005</sect1> 2006 2007<sect1 id='Connection_Watch_Procedures'> 2008<title>Connection Watch Procedures</title> 2009 2010<para>To add a watch procedure that will be called 2011each time ICElib opens a new connection via 2012<xref linkend='IceOpenConnection' xrefstyle='select: title'/> 2013or 2014<xref linkend='IceAcceptConnection' xrefstyle='select: title'/> 2015or closes a connection via 2016<xref linkend='IceCloseConnection' xrefstyle='select: title'/> 2017use 2018<xref linkend='IceAddConnectionWatch' xrefstyle='select: title'/></para> 2019 2020<funcsynopsis id='IceAddConnectionWatch'> 2021<funcprototype> 2022 <funcdef>Status <function>IceAddConnectionWatch</function></funcdef> 2023 <paramdef>IceWatchProc<parameter> watch_proc</parameter></paramdef> 2024 <paramdef>IcePointer<parameter> client_data</parameter></paramdef> 2025</funcprototype> 2026</funcsynopsis> 2027 2028<variablelist remap='IP'> 2029 <varlistentry> 2030 <term><emphasis remap='I'>watch_proc</emphasis></term> 2031 <listitem> 2032 <para> 2033The watch procedure to invoke when ICElib opens or closes a connection. 2034 </para> 2035 </listitem> 2036 </varlistentry> 2037 <varlistentry> 2038 <term><emphasis remap='I'>client_data</emphasis></term> 2039 <listitem> 2040 <para>This pointer will be passed to the watch procedure.</para> 2041 </listitem> 2042 </varlistentry> 2043</variablelist> 2044 2045 2046<para> 2047The return value of <xref linkend='IceAddConnectionWatch' xrefstyle='select: title'/> 2048is zero for failure, and a positive value for success. 2049</para> 2050 2051<para> 2052Note that several calls to <xref linkend='IceOpenConnection' xrefstyle='select: title'/> 2053might share the same ICE connection. In such a case, the watch procedure 2054is only invoked when the connection is first created (after authentication 2055succeeds). Similarly, because connections might be shared, the 2056watch procedure is called only if <xref linkend='IceCloseConnection' xrefstyle='select: title'/> 2057actually closes the connection (right before the IceConn is freed). 2058</para> 2059 2060<para> 2061The watch procedures are very useful for applications that 2062need to add a file descriptor to a select mask when a new connection 2063is created and remove the file descriptor when the connection is destroyed. 2064Because connections are shared, knowing when to add and remove the file 2065descriptor from the select mask would be difficult without the watch 2066procedures. 2067</para> 2068 2069<para> 2070Multiple watch procedures may be registered with the ICE library. 2071No assumptions should be made about their order of invocation. 2072</para> 2073 2074<para> 2075If one or more ICE connections were already created by the ICE library at the 2076time the watch procedure is registered, the watch procedure will instantly 2077be invoked for each of these ICE connections (with the opening argument 2078set to <function>True</function> 2079</para> 2080 2081<para> 2082The watch procedure is of type <function>IceWatchProc</function> 2083</para> 2084 2085<funcsynopsis id='WatchProc'> 2086<funcprototype> 2087 <funcdef>void <function>WatchProc</function></funcdef> 2088 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2089 <paramdef>IcePointer<parameter> client_data</parameter></paramdef> 2090 <paramdef>Bool<parameter> opening</parameter></paramdef> 2091 <paramdef>IcePointer<parameter> *watch_data</parameter></paramdef> 2092</funcprototype> 2093</funcsynopsis> 2094 2095<variablelist remap='IP'> 2096 <varlistentry> 2097 <term><emphasis remap='I'>ice_conn</emphasis></term> 2098 <listitem> 2099 <para> 2100The opened or closed ICE connection. Call 2101<function>IceConnectionNumber</function> 2102to get the file descriptor associated with this connection. 2103 </para> 2104 </listitem> 2105 </varlistentry> 2106 <varlistentry> 2107 <term><emphasis remap='I'>client_data</emphasis></term> 2108 <listitem> 2109 <para> 2110Client data specified in the call to 2111<xref linkend='IceAddConnectionWatch' xrefstyle='select: title'/> 2112 </para> 2113 </listitem> 2114 </varlistentry> 2115 <varlistentry> 2116 <term><emphasis remap='I'>opening</emphasis></term> 2117 <listitem> 2118 <para> 2119If <function>True</function> the connection is being opened. If 2120<function>False</function> the connection is being closed. 2121 </para> 2122 </listitem> 2123 </varlistentry> 2124 <varlistentry> 2125 <term><emphasis remap='I'>watch_data</emphasis></term> 2126 <listitem> 2127 <para>Can be used to save a pointer to client data.</para> 2128 </listitem> 2129 </varlistentry> 2130</variablelist> 2131 2132<para> 2133If opening is <function>True</function> the client should set the 2134*watch_data pointer to any data it may need to save until the connection 2135is closed and the watch procedure is invoked again with opening set to 2136<function>False</function> 2137</para> 2138 2139<para> 2140To remove a watch procedure, use 2141<xref linkend='IceRemoveConnectionWatch' xrefstyle='select: title'/> 2142</para> 2143 2144<funcsynopsis id='IceRemoveConnectionWatch'> 2145<funcprototype> 2146 <funcdef>void <function>IceRemoveConnectionWatch</function></funcdef> 2147 <paramdef>IceWatchProc<parameter> watch_proc</parameter></paramdef> 2148 <paramdef>IcePointer<parameter> client_data</parameter></paramdef> 2149</funcprototype> 2150</funcsynopsis> 2151 2152<variablelist remap='IP'> 2153 <varlistentry> 2154 <term><emphasis remap='I'>watch_proc</emphasis></term> 2155 <listitem> 2156 <para> 2157The watch procedure that was passed to 2158<xref linkend='IceAddConnectionWatch' xrefstyle='select: title'/> 2159 </para> 2160 </listitem> 2161 </varlistentry> 2162 <varlistentry> 2163 <term><emphasis remap='I'>client_data</emphasis></term> 2164 <listitem> 2165 <para> 2166The client_data pointer that was passed to 2167<xref linkend='IceAddConnectionWatch' xrefstyle='select: title'/> 2168 </para> 2169 </listitem> 2170 </varlistentry> 2171</variablelist> 2172 2173</sect1> 2174</chapter> 2175 2176<chapter id='Protocol_Setup_and_Shutdown'> 2177<title>Protocol Setup and Shutdown</title> 2178 2179<para> 2180To activate a protocol on a given ICE connection, use 2181<xref linkend='IceProtocolSetup' xrefstyle='select: title'/> 2182</para> 2183 2184<funcsynopsis id='IceProtocolSetup'> 2185<funcprototype> 2186 <funcdef>IceProtocolSetupStatus <function>IceProtocolSetup</function></funcdef> 2187 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2188 <paramdef>int<parameter> my_opcode</parameter></paramdef> 2189 <paramdef>IcePointer<parameter> client_data</parameter></paramdef> 2190 <paramdef>Bool<parameter> must_authenticate</parameter></paramdef> 2191 <paramdef>int<parameter> *major_version_ret</parameter></paramdef> 2192 <paramdef>int<parameter> *minor_version_ret</parameter></paramdef> 2193 <paramdef>char<parameter> **vendor_ret</parameter></paramdef> 2194 <paramdef>char<parameter> **release_ret</parameter></paramdef> 2195 <paramdef>int<parameter> error_length</parameter></paramdef> 2196 <paramdef>char<parameter> *error_string_ret</parameter></paramdef> 2197</funcprototype> 2198</funcsynopsis> 2199 2200<variablelist remap='IP'> 2201 <varlistentry> 2202 <term><emphasis remap='I'>ice_conn</emphasis></term> 2203 <listitem> 2204 <para>A valid ICE connection object.</para> 2205 </listitem> 2206 </varlistentry> 2207 <varlistentry> 2208 <term><emphasis remap='I'>my_opcode</emphasis></term> 2209 <listitem> 2210 <para> 2211The major opcode of the protocol to be set up, as returned by 2212<xref linkend='IceRegisterForProtocolSetup' xrefstyle='select: title'/> 2213 </para> 2214 </listitem> 2215 </varlistentry> 2216 <varlistentry> 2217 <term><emphasis remap='I'>client_data</emphasis></term> 2218 <listitem> 2219 <para> 2220The client data stored in this pointer will be passed to the 2221<function>IcePoProcessMsgProc</function> callback. 2222 </para> 2223 </listitem> 2224 </varlistentry> 2225 <varlistentry> 2226 <term><emphasis remap='I'>must_authenticate</emphasis></term> 2227 <listitem> 2228 <para> 2229If <function>True</function> the other client may 2230not bypass authentication. 2231 </para> 2232 </listitem> 2233 </varlistentry> 2234 <varlistentry> 2235 <term><emphasis remap='I'>major_version_ret</emphasis></term> 2236 <listitem> 2237 <para>The major version of the protocol to be used is returned.</para> 2238 </listitem> 2239 </varlistentry> 2240 <varlistentry> 2241 <term><emphasis remap='I'>minor_version_ret</emphasis></term> 2242 <listitem> 2243 <para>The minor version of the protocol to be used is returned.</para> 2244 </listitem> 2245 </varlistentry> 2246 <varlistentry> 2247 <term><emphasis remap='I'>vendor_ret</emphasis></term> 2248 <listitem> 2249 <para>The vendor string specified by the protocol acceptor.</para> 2250 </listitem> 2251 </varlistentry> 2252 <varlistentry> 2253 <term><emphasis remap='I'>release_ret</emphasis></term> 2254 <listitem> 2255 <para>The release string specified by the protocol acceptor.</para> 2256 </listitem> 2257 </varlistentry> 2258 <varlistentry> 2259 <term><emphasis remap='I'>error_length</emphasis></term> 2260 <listitem> 2261 <para> 2262Specifies the length of the error_string_ret argument passed in. 2263 </para> 2264 </listitem> 2265 </varlistentry> 2266 <varlistentry> 2267 <term><emphasis remap='I'>error_string_ret</emphasis></term> 2268 <listitem> 2269 <para> 2270Returns a null-terminated error message, if any. 2271The error_string_ret argument points to user supplied memory. 2272No more than error_length bytes are used. 2273 </para> 2274 </listitem> 2275 </varlistentry> 2276</variablelist> 2277 2278<para> 2279The vendor_ret and release_ret strings should be freed with 2280<function>free</function> when no longer needed. 2281</para> 2282 2283<para> 2284<xref linkend='IceProtocolSetup' xrefstyle='select: title'/> returns one of the following values: 2285</para> 2286 2287<itemizedlist> 2288 <listitem> 2289 <para> 2290<function>IceProtocolSetupSuccess</function> - the major_version_ret, 2291minor_version_ret, vendor_ret, release_ret are set. 2292 </para> 2293 </listitem> 2294 <listitem> 2295 <para> 2296<function>IceProtocolSetupFailure</function> or 2297<function>IceProtocolSetupIOError</function> 2298- check error_string_ret for failure reason. The major_version_ret, 2299minor_version_ret, vendor_ret, release_ret are not set. 2300 </para> 2301 </listitem> 2302 <listitem> 2303 <para> 2304<function>IceProtocolAlreadyActive</function> 2305- this protocol is already active on this connection. 2306The major_version_ret, minor_version_ret, vendor_ret, release_ret 2307are not set. 2308 </para> 2309 </listitem> 2310</itemizedlist> 2311 2312<para> 2313To notify the ICE library when a given protocol will no longer be used 2314on an ICE connection, use <xref linkend='IceProtocolShutdown' xrefstyle='select: title'/> 2315</para> 2316 2317<funcsynopsis id='IceProtocolShutdown'> 2318<funcprototype> 2319 <funcdef>Status <function>IceProtocolShutdown</function></funcdef> 2320 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2321 <paramdef>int<parameter> major_opcode</parameter></paramdef> 2322</funcprototype> 2323</funcsynopsis> 2324 2325<variablelist remap='IP'> 2326 <varlistentry> 2327 <term><emphasis remap='I'>ice_conn</emphasis></term> 2328 <listitem> 2329 <para>A valid ICE connection object.</para> 2330 </listitem> 2331 </varlistentry> 2332 <varlistentry> 2333 <term><emphasis remap='I'>major_opcode</emphasis></term> 2334 <listitem> 2335 <para>The major opcode of the protocol to shut down.</para> 2336 </listitem> 2337 </varlistentry> 2338</variablelist> 2339 2340 2341<para> 2342The return value of <xref linkend='IceProtocolShutdown' xrefstyle='select: title'/> 2343is zero for failure and a positive value for success. 2344</para> 2345 2346<para> 2347Failure will occur if the major opcode was never registered OR the protocol 2348of the major opcode was never activated on the connection. By activated, 2349we mean that a <function>ProtocolSetup</function> succeeded on the connection. 2350Note that ICE does not define how each sub-protocol triggers a 2351protocol shutdown. 2352</para> 2353</chapter> 2354 2355<chapter id='Processing_Messages'> 2356<title>Processing Messages</title> 2357 2358 2359<para>To process incoming messages on an ICE connection, use 2360<xref linkend='IceProcessMessages' xrefstyle='select: title'/></para> 2361 2362<funcsynopsis id='IceProcessMessages'> 2363<funcprototype> 2364 <funcdef>IceProcessMessagesStatus <function>IceProcessMessages</function></funcdef> 2365 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2366 <paramdef>IceReplyWaitInfo<parameter> *reply_wait</parameter></paramdef> 2367 <paramdef>Bool<parameter> *reply_ready_ret</parameter></paramdef> 2368</funcprototype> 2369</funcsynopsis> 2370 2371<variablelist remap='IP'> 2372 <varlistentry> 2373 <term><emphasis remap='I'>ice_conn</emphasis></term> 2374 <listitem> 2375 <para>A valid ICE connection object.</para> 2376 </listitem> 2377 </varlistentry> 2378 <varlistentry> 2379 <term><emphasis remap='I'>reply_wait</emphasis></term> 2380 <listitem> 2381 <para>Indicates if a reply is being waited for.</para> 2382 </listitem> 2383 </varlistentry> 2384 <varlistentry> 2385 <term><emphasis remap='I'>reply_ready_ret</emphasis></term> 2386 <listitem> 2387 <para> 2388If set to <function>True</function> on return, a reply is ready. 2389 </para> 2390 </listitem> 2391 </varlistentry> 2392</variablelist> 2393 2394<para> 2395<xref linkend='IceProcessMessages' xrefstyle='select: title'/> is used in two ways: 2396</para> 2397 2398<itemizedlist> 2399 <listitem> 2400 <para> 2401In the first, a client may generate a message and block by calling 2402<xref linkend='IceProcessMessages' xrefstyle='select: title'/> repeatedly until it gets its reply. 2403 </para> 2404 </listitem> 2405 <listitem> 2406 <para> 2407In the second, a client calls <xref linkend='IceProcessMessages' xrefstyle='select: title'/> 2408with reply_wait set to NULL in response to <function>select</function> 2409showing that there is data to read on the ICE connection. 2410The ICE library may process zero or more complete messages. 2411Note that messages that are not blocked for are always processed by 2412invoking callbacks. 2413 </para> 2414 </listitem> 2415</itemizedlist> 2416 2417<para> 2418<function>IceReplyWaitInfo</function> contains the major/minor opcodes 2419and sequence number of the message for which a reply is being awaited. 2420It also contains a pointer to the reply message to be filled in (the 2421protocol library should cast this <function>IcePointer</function> 2422to the appropriate reply type). In most 2423cases, the reply will have some fixed-size part, and the client waiting 2424for the reply will have provided a pointer to a structure to hold 2425this fixed-size data. If there is variable-length data, it would be 2426expected that the 2427<function>IcePoProcessMsgProc</function> 2428callback will have to allocate additional 2429memory and store pointer(s) to that memory in the fixed-size 2430structure. If the entire data is variable length (for example, a single 2431variable-length string), then the client waiting for the reply would probably 2432just pass a pointer to fixed-size space to hold a pointer, and the 2433<function>IcePoProcessMsgProc</function> 2434callback would allocate the storage and store the pointer. 2435It is the responsibility of the client receiving the reply to 2436free up any memory allocated on its behalf. 2437</para> 2438 2439<literallayout class="monospaced"> 2440typedef struct { 2441 unsigned long sequence_of_request; 2442 int major_opcode_of_request; 2443 int minor_opcode_of_request; 2444 IcePointer reply; 2445} IceReplyWaitInfo; 2446</literallayout> 2447 2448<para> 2449If reply_wait is not NULL and 2450<xref linkend='IceProcessMessages' xrefstyle='select: title'/> 2451has a reply or error to return in response to this reply_wait 2452(that is, no callback was generated), then the reply_ready_ret argument 2453will be set to <function>True</function> 2454</para> 2455 2456<para> 2457If reply_wait is NULL, then the caller may also pass NULL for 2458reply_ready_ret and be guaranteed that no value will be stored in 2459this pointer. 2460</para> 2461 2462<para> 2463<xref linkend='IceProcessMessages' xrefstyle='select: title'/> returns one of the following values: 2464</para> 2465 2466<itemizedlist> 2467 <listitem> 2468 <para> 2469<function>IceProcessMessagesSuccess</function> - no error occurred. 2470 </para> 2471 </listitem> 2472 <listitem> 2473 <para> 2474<function>IceProcessMessagesIOError</function> - an IO error occurred, 2475and the caller must explicitly close the connection by calling 2476<xref linkend='IceCloseConnection' xrefstyle='select: title'/> 2477 </para> 2478 </listitem> 2479 <listitem> 2480 <para> 2481<function>IceProcessMessagesConnectionClosed</function> 2482- the ICE connection has been closed (closing of the connection was deferred 2483because of shutdown negotiation, or because the 2484<xref linkend='IceProcessMessages' xrefstyle='select: title'/> 2485nesting level was not zero). Do not attempt 2486to access the ICE connection at this point, since it has been freed. 2487 </para> 2488 </listitem> 2489</itemizedlist> 2490 2491</chapter> 2492 2493<chapter id='Ping'> 2494<title>Ping</title> 2495 2496<para> 2497To send a "Ping" message to the client on the other side of the 2498ICE connection, use <xref linkend='IcePing' xrefstyle='select: title'/> 2499</para> 2500 2501<funcsynopsis id='IcePing'> 2502<funcprototype> 2503 <funcdef>Status <function>IcePing</function></funcdef> 2504 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2505 <paramdef>IcePingReplyProc<parameter> ping_reply_proc</parameter></paramdef> 2506 <paramdef>IcePointer<parameter> client_data</parameter></paramdef> 2507</funcprototype> 2508</funcsynopsis> 2509 2510<variablelist remap='IP'> 2511 <varlistentry> 2512 <term><emphasis remap='I'>ice_conn</emphasis></term> 2513 <listitem> 2514 <para>A valid ICE connection object.</para> 2515 </listitem> 2516 </varlistentry> 2517 <varlistentry> 2518 <term><emphasis remap='I'>ping_reply_proc</emphasis></term> 2519 <listitem> 2520 <para>The callback to invoke when the Ping reply arrives.</para> 2521 </listitem> 2522 </varlistentry> 2523 <varlistentry> 2524 <term><emphasis remap='I'>client_data</emphasis></term> 2525 <listitem> 2526 <para> 2527This pointer will be passed to the <olink targetdoc='SMlib' targetptr='IcePingReplyProc'><function>IcePingReplyProc</function></olink> 2528callback. 2529 </para> 2530 </listitem> 2531 </varlistentry> 2532</variablelist> 2533 2534 2535<para><xref linkend='IcePing' xrefstyle='select: title'/> 2536returns zero for failure and a positive value for success.</para> 2537 2538<para>When 2539<xref linkend='IceProcessMessages' xrefstyle='select: title'/> 2540processes the Ping reply, it will invoke the 2541<olink targetdoc='SMlib' targetptr='IcePingReplyProc'><function>IcePingReplyProc</function></olink> 2542callback.</para> 2543 2544<funcsynopsis id='PingReplyProc'> 2545<funcprototype> 2546 <funcdef>void <function>PingReplyProc</function></funcdef> 2547 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2548 <paramdef>IcePointer<parameter> client_data</parameter></paramdef> 2549</funcprototype> 2550</funcsynopsis> 2551 2552<variablelist remap='IP'> 2553 <varlistentry> 2554 <term><emphasis remap='I'>ice_conn</emphasis></term> 2555 <listitem> 2556<para>A valid ICE connection object.</para> 2557 </listitem> 2558 </varlistentry> 2559 <varlistentry> 2560 <term><emphasis remap='I'>client_data</emphasis></term> 2561 <listitem> 2562<para>The client data specified in the call to 2563<xref linkend='IcePing' xrefstyle='select: title'/></para> 2564 </listitem> 2565 </varlistentry> 2566</variablelist> 2567 2568</chapter> 2569 2570<chapter id='Using_ICElib_Informational_Functions'> 2571<title>Using ICElib Informational Functions</title> 2572 2573<funcsynopsis id='IceConnectionStatus'> 2574<funcprototype> 2575 <funcdef>IceConnectStatus <function>IceConnectionStatus</function></funcdef> 2576 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2577</funcprototype> 2578</funcsynopsis> 2579 2580<para><xref linkend='IceConnectionStatus' xrefstyle='select: title'/> 2581returns the status of an ICE connection. The possible return values are:</para> 2582 2583<itemizedlist> 2584 <listitem> 2585<para><function>IceConnectPending</function> 2586- the connection is not valid yet (that is, authentication is taking place). 2587This is only relevant to connections created by 2588<xref linkend='IceAcceptConnection' xrefstyle='select: title'/></para> 2589 </listitem> 2590 <listitem> 2591<para><function>IceConnectAccepted</function> 2592- the connection has been accepted. 2593This is only relevant to connections created by 2594<xref linkend='IceAcceptConnection' xrefstyle='select: title'/></para> 2595 </listitem> 2596 <listitem> 2597<para><function>IceConnectRejected</function> 2598- the connection had been rejected (that is, authentication failed). 2599This is only relevant to connections created by 2600<xref linkend='IceAcceptConnection' xrefstyle='select: title'/></para> 2601 </listitem> 2602 <listitem> 2603<para><function>IceConnectIOError</function> 2604- an IO error has occurred on the connection.</para> 2605 </listitem> 2606</itemizedlist> 2607 2608<funcsynopsis id='IceVendor'> 2609<funcprototype> 2610 <funcdef>char <function> *IceVendor</function></funcdef> 2611 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2612</funcprototype> 2613</funcsynopsis> 2614 2615<para><function>IceVendor</function> 2616returns the ICE library vendor identification 2617for the other side of the connection. 2618The string should be freed with a call to 2619<function>free</function> 2620when no longer needed.</para> 2621 2622<funcsynopsis id='IceRelease'> 2623<funcprototype> 2624 <funcdef>char <function> *IceRelease</function></funcdef> 2625 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2626</funcprototype> 2627</funcsynopsis> 2628 2629<para><function>IceRelease</function> 2630returns the release identification of the ICE library 2631on the other side of the connection. 2632The string should be freed with a call to 2633<function>free</function> 2634when no longer needed.</para> 2635 2636<funcsynopsis id='IceProtocolVersion'> 2637<funcprototype> 2638 <funcdef>int <function> IceProtocolVersion</function></funcdef> 2639 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2640</funcprototype> 2641</funcsynopsis> 2642 2643<para><xref linkend='IceProtocolVersion' xrefstyle='select: title'/> 2644returns the major version of the ICE protocol on this connection.</para> 2645 2646<funcsynopsis id='IceProtocolRevision'> 2647<funcprototype> 2648 <funcdef>int <function> IceProtocolRevision</function></funcdef> 2649 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2650</funcprototype> 2651</funcsynopsis> 2652 2653 2654<para><xref linkend='IceProtocolRevision' xrefstyle='select: title'/> 2655returns the minor version of the ICE protocol on this connection.</para> 2656 2657<funcsynopsis> 2658<funcprototype> 2659 <funcdef>int <function> IceConnectionNumber</function></funcdef> 2660 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2661</funcprototype> 2662</funcsynopsis> 2663 2664 2665<para><function>IceConnectionNumber</function> 2666returns the file descriptor of this ICE connection.</para> 2667 2668<funcsynopsis id='IceConnectionString'> 2669<funcprototype> 2670 <funcdef>char <function> *IceConnectionString</function></funcdef> 2671 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2672</funcprototype> 2673</funcsynopsis> 2674 2675<para><function>IceConnectionString</function> 2676returns the network ID of the client that 2677accepted this connection. The string should be freed with a call to 2678<function>free</function> 2679when no longer needed.</para> 2680 2681<funcsynopsis id='IceLastSentSequenceNumber'> 2682<funcprototype> 2683 <funcdef>unsigned long <function> IceLastSentSequenceNumber</function></funcdef> 2684 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2685</funcprototype> 2686</funcsynopsis> 2687 2688 2689<para><xref linkend='IceLastSentSequenceNumber' xrefstyle='select: title'/> 2690returns the sequence number of the last message sent on this ICE connection.</para> 2691 2692<funcsynopsis> 2693<funcprototype> 2694 <funcdef>unsigned long <function> IceLastReceivedSequenceNumber</function></funcdef> 2695 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2696</funcprototype> 2697</funcsynopsis> 2698 2699<para><function>IceLastReceivedSequenceNumber</function> 2700returns the sequence number of the last message received on this 2701ICE connection.</para> 2702 2703<funcsynopsis id='IceSwapping'> 2704<funcprototype> 2705 <funcdef>Bool <function> IceSwapping</function></funcdef> 2706 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2707</funcprototype> 2708</funcsynopsis> 2709 2710 2711<para><xref linkend='IceSwapping' xrefstyle='select: title'/> 2712returns 2713<function>True</function> 2714if byte swapping is necessary when reading messages on the ICE connection.</para> 2715 2716<funcsynopsis id='IceGetContext'> 2717<funcprototype> 2718 <funcdef>IcePointer <function> IceGetContext</function></funcdef> 2719 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2720</funcprototype> 2721</funcsynopsis> 2722 2723<para><xref linkend='IceGetContext' xrefstyle='select: title'/> 2724returns the context associated with a connection created by 2725<xref linkend='IceOpenConnection' xrefstyle='select: title'/></para> 2726</chapter> 2727 2728<chapter id='ICE_Messages'> 2729<title>ICE Messages</title> 2730 2731<para> 2732All ICE messages have a standard 8-byte header. The ICElib macros that 2733read and write messages rely on the following naming convention for message 2734headers: 2735</para> 2736 2737<literallayout class='monospaced'> 2738 CARD8 major_opcode; 2739 CARD8 minor_opcode; 2740 CARD8 data[2]; 2741 CARD32 length; 2742</literallayout> 2743 2744<para> 2745The 3rd and 4th bytes of the message header can be used as needed. 2746The length field is specified in units of 8 bytes. 2747</para> 2748 2749<sect1 id='Sending_ICE_Messages'> 2750<title>Sending ICE Messages</title> 2751 2752<para> 2753The ICE library maintains an output buffer used for generating messages. 2754Protocol libraries layered on top of ICE may choose to batch messages 2755together and flush the output buffer at appropriate times. 2756</para> 2757 2758<para> 2759If an IO error has occurred on an ICE connection, all write operations 2760will be ignored. For further information, see 2761<xref linkend='Error_Handling' xrefstyle='select: title'/>. 2762</para> 2763 2764 2765<para> 2766To get the size of the ICE output buffer, use 2767<xref linkend='IceGetOutBufSize' xrefstyle='select: title'/> 2768</para> 2769 2770<funcsynopsis id='IceGetOutBufSize'> 2771<funcprototype> 2772 <funcdef>int <function> IceGetOutBufSize</function></funcdef> 2773 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2774</funcprototype> 2775</funcsynopsis> 2776 2777<variablelist remap='IP'> 2778 <varlistentry> 2779 <term><emphasis remap='I'>ice_conn</emphasis></term> 2780 <listitem> 2781 <para>A valid ICE connection object.</para> 2782 </listitem> 2783 </varlistentry> 2784</variablelist> 2785 2786 2787<para> 2788To flush the ICE output buffer, use <xref linkend='IceFlush' xrefstyle='select: title'/> 2789</para> 2790 2791<funcsynopsis id='IceFlush'> 2792<funcprototype> 2793 <funcdef>int <function> IceFlush</function></funcdef> 2794 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2795</funcprototype> 2796</funcsynopsis> 2797 2798<variablelist remap='IP'> 2799 <varlistentry> 2800 <term><emphasis remap='I'>ice_conn</emphasis></term> 2801 <listitem> 2802 <para>A valid ICE connection object.</para> 2803 </listitem> 2804 </varlistentry> 2805</variablelist> 2806 2807<para> 2808Note that the output buffer may be implicitly flushed if there is 2809insufficient space to generate a message. 2810</para> 2811 2812<para>The following macros can be used to generate ICE messages:</para> 2813 2814<funcsynopsis id='IceGetHeader'> 2815<funcprototype> 2816 <funcdef><function> IceGetHeader</function></funcdef> 2817 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2818 <paramdef>int<parameter> major_opcode</parameter></paramdef> 2819 <paramdef>int<parameter> minor_opcode</parameter></paramdef> 2820 <paramdef>int<parameter> header_size</parameter></paramdef> 2821 <paramdef><C_data_type><parameter> *pmsg</parameter></paramdef> 2822</funcprototype> 2823</funcsynopsis> 2824 2825<variablelist remap='IP'> 2826 <varlistentry> 2827 <term><emphasis remap='I'>ice_conn</emphasis></term> 2828 <listitem> 2829 <para>A valid ICE connection object.</para> 2830 </listitem> 2831 </varlistentry> 2832 <varlistentry> 2833 <term><emphasis remap='I'>major_opcode</emphasis></term> 2834 <listitem> 2835 <para>The major opcode of the message.</para> 2836 </listitem> 2837 </varlistentry> 2838 <varlistentry> 2839 <term><emphasis remap='I'>minor_opcode</emphasis></term> 2840 <listitem> 2841 <para>The minor opcode of the message.</para> 2842 </listitem> 2843 </varlistentry> 2844 <varlistentry> 2845 <term><emphasis remap='I'>header_size</emphasis></term> 2846 <listitem> 2847 <para>The size of the message header (in bytes).</para> 2848 </listitem> 2849 </varlistentry> 2850 <varlistentry> 2851 <term><emphasis remap='I'><C_data_type></emphasis></term> 2852 <listitem> 2853 <para>The actual C data type of the message header.</para> 2854 </listitem> 2855 </varlistentry> 2856 <varlistentry> 2857 <term><emphasis remap='I'>pmsg</emphasis></term> 2858 <listitem> 2859 <para> 2860The message header pointer. After this macro is called, the 2861library can store data in the message header. 2862 </para> 2863 </listitem> 2864 </varlistentry> 2865</variablelist> 2866 2867 2868<para> 2869<xref linkend='IceGetHeader' xrefstyle='select: title'/> 2870is used to set up a message header on an ICE connection. 2871It sets the major and minor opcodes of the message, and initializes 2872the message's length to the length of the header. If additional 2873variable length data follows, the message's length field should be 2874updated. 2875</para> 2876 2877 2878<funcsynopsis id='IceGetHeaderExtra'> 2879<funcprototype> 2880 <funcdef><function> IceGetHeaderExtra</function></funcdef> 2881 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2882 <paramdef>int<parameter> major_opcode</parameter></paramdef> 2883 <paramdef>int<parameter> minor_opcode</parameter></paramdef> 2884 <paramdef>int<parameter> header_size</parameter></paramdef> 2885 <paramdef>int<parameter> extra</parameter></paramdef> 2886 <paramdef><C_data_type><parameter> *pmsg</parameter></paramdef> 2887 <paramdef>char<parameter> *pdata</parameter></paramdef> 2888</funcprototype> 2889</funcsynopsis> 2890 2891<variablelist remap='IP'> 2892 <varlistentry> 2893 <term><emphasis remap='I'>ice_conn</emphasis></term> 2894 <listitem> 2895 <para>A valid ICE connection object.</para> 2896 </listitem> 2897 </varlistentry> 2898 <varlistentry> 2899 <term><emphasis remap='I'>major_opcode</emphasis></term> 2900 <listitem> 2901 <para>The major opcode of the message.</para> 2902 </listitem> 2903 </varlistentry> 2904 <varlistentry> 2905 <term><emphasis remap='I'>minor_opcode</emphasis></term> 2906 <listitem> 2907 <para>The minor opcode of the message.</para> 2908 </listitem> 2909 </varlistentry> 2910 <varlistentry> 2911 <term><emphasis remap='I'>header_size</emphasis></term> 2912 <listitem> 2913 <para>The size of the message header (in bytes).</para> 2914 </listitem> 2915 </varlistentry> 2916 <varlistentry> 2917 <term><emphasis remap='I'>extra</emphasis></term> 2918 <listitem> 2919 <para> 2920The size of the extra data beyond the header (in 8-byte units). 2921 </para> 2922 </listitem> 2923 </varlistentry> 2924 <varlistentry> 2925 <term><emphasis remap='I'><C_data_type></emphasis></term> 2926 <listitem> 2927 <para>The actual C data type of the message header.</para> 2928 </listitem> 2929 </varlistentry> 2930 <varlistentry> 2931 <term><emphasis remap='I'>pmsg</emphasis></term> 2932 <listitem> 2933 <para> 2934The message header pointer. After this macro is called, the 2935library can store data in the message header. 2936 </para> 2937 </listitem> 2938 </varlistentry> 2939 <varlistentry> 2940 <term><emphasis remap='I'>pdata</emphasis></term> 2941 <listitem> 2942 <para> 2943Returns a pointer to the ICE output buffer that points 2944immediately after the message header. The variable length 2945data should be stored here. If there was not enough room 2946in the ICE output buffer, pdata is set to NULL. 2947 </para> 2948 </listitem> 2949 </varlistentry> 2950</variablelist> 2951 2952 2953<para> 2954<xref linkend='IceGetHeaderExtra' xrefstyle='select: title'/> 2955is used to generate a message with a fixed (and relatively small) amount 2956of variable length data. The complete message must fit in the ICE output 2957buffer. 2958</para> 2959 2960<funcsynopsis id='IceSimpleMessage'> 2961<funcprototype> 2962 <funcdef><function> IceSimpleMessage</function></funcdef> 2963 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 2964 <paramdef>int<parameter> major_opcode</parameter></paramdef> 2965 <paramdef>int<parameter> minor_opcode</parameter></paramdef> 2966</funcprototype> 2967</funcsynopsis> 2968 2969<variablelist remap='IP'> 2970 <varlistentry> 2971 <term><emphasis remap='I'>ice_conn</emphasis></term> 2972 <listitem> 2973 <para>A valid ICE connection object.</para> 2974 </listitem> 2975 </varlistentry> 2976 <varlistentry> 2977 <term><emphasis remap='I'>major_opcode</emphasis></term> 2978 <listitem> 2979 <para>The major opcode of the message.</para> 2980 </listitem> 2981 </varlistentry> 2982 <varlistentry> 2983 <term><emphasis remap='I'>minor_opcode</emphasis></term> 2984 <listitem> 2985 <para>The minor opcode of the message.</para> 2986 </listitem> 2987 </varlistentry> 2988</variablelist> 2989 2990<para> 2991<xref linkend='IceSimpleMessage' xrefstyle='select: title'/> 2992is used to generate a message that is identical 2993in size to the ICE header message, and has no additional data. 2994</para> 2995 2996<funcsynopsis id='IceErrorHeader'> 2997<funcprototype> 2998 <funcdef><function> IceErrorHeader</function></funcdef> 2999 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3000 <paramdef>int<parameter> offending_major_opcode</parameter></paramdef> 3001 <paramdef>int<parameter> offending_minor_opcode</parameter></paramdef> 3002 <paramdef>int<parameter> offending_sequence_num</parameter></paramdef> 3003 <paramdef>int<parameter> severity</parameter></paramdef> 3004 <paramdef>int<parameter> error_class</parameter></paramdef> 3005 <paramdef>int<parameter> data_length</parameter></paramdef> 3006</funcprototype> 3007</funcsynopsis> 3008 3009<variablelist remap='IP'> 3010 <varlistentry> 3011 <term><emphasis remap='I'>ice_conn</emphasis></term> 3012 <listitem> 3013 <para>A valid ICE connection object.</para> 3014 </listitem> 3015 </varlistentry> 3016 <varlistentry> 3017 <term><emphasis remap='I'>offending_major_opcode</emphasis></term> 3018 <listitem> 3019 <para> 3020The major opcode of the protocol in which an error was detected. 3021 </para> 3022 </listitem> 3023 </varlistentry> 3024 <varlistentry> 3025 <term><emphasis remap='I'>offending_minor_opcode</emphasis></term> 3026 <listitem> 3027 <para> 3028The minor opcode of the protocol in which an error was detected. 3029 </para> 3030 </listitem> 3031 </varlistentry> 3032 <varlistentry> 3033 <term><emphasis remap='I'>offending_sequence_num</emphasis></term> 3034 <listitem> 3035 <para>The sequence number of the message that caused the error.</para> 3036 </listitem> 3037 </varlistentry> 3038 <varlistentry> 3039 <term><emphasis remap='I'>severity</emphasis></term> 3040 <listitem> 3041 <para> 3042<function>IceCanContinue</function> 3043<function>IceFatalToProtocol</function> 3044or 3045<function>IceFatalToConnection</function> 3046 </para> 3047 </listitem> 3048 </varlistentry> 3049 <varlistentry> 3050 <term><emphasis remap='I'>error_class</emphasis></term> 3051 <listitem> 3052 <para>The error class.</para> 3053 </listitem> 3054 </varlistentry> 3055 <varlistentry> 3056 <term><emphasis remap='I'>data_length</emphasis></term> 3057 <listitem> 3058 <para> 3059Length of data (in 8-byte units) to be written after the header. 3060 </para> 3061 </listitem> 3062 </varlistentry> 3063</variablelist> 3064 3065<para> 3066<xref linkend='IceErrorHeader' xrefstyle='select: title'/> sets up an error message header. 3067</para> 3068 3069<para> 3070Note that the two clients connected by ICE may be using different 3071major opcodes for a given protocol. The offending_major_opcode passed 3072to this macro is the major opcode of the protocol for the client 3073sending the error message. 3074</para> 3075 3076<para> 3077Generic errors, which are common to all protocols, have classes 3078in the range 0x8000..0xFFFF. 3079See the <emphasis remap='I'>Inter-Client Exchange Protocol</emphasis> 3080standard for more details. 3081</para> 3082 3083<informaltable frame='none'> 3084 <?dbfo keep-together="always" ?> 3085 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 3086 <colspec colname='c1' colwidth='1.0*'/> 3087 <colspec colname='c2' colwidth='2.0*'/> 3088 <tbody> 3089 <row> 3090 <entry>IceBadMinor</entry> 3091 <entry>0x8000</entry> 3092 </row> 3093 <row> 3094 <entry>IceBadState</entry> 3095 <entry>0x8001</entry> 3096 </row> 3097 <row> 3098 <entry>IceBadLength</entry> 3099 <entry>0x8002</entry> 3100 </row> 3101 <row> 3102 <entry>IceBadValue</entry> 3103 <entry>0x8003</entry> 3104 </row> 3105 </tbody> 3106 </tgroup> 3107</informaltable> 3108 3109<para>Per-protocol errors have classes in the range 0x0000-0x7fff.</para> 3110 3111<para> 3112To write data to an ICE connection, use the 3113<xref linkend='IceWriteData' xrefstyle='select: title'/> macro. If the data fits into the 3114ICE output buffer, it is copied there. Otherwise, the ICE output buffer 3115is flushed and the data is directly sent. 3116</para> 3117 3118<para> 3119This macro is used in conjunction with 3120<xref linkend='IceGetHeader' xrefstyle='select: title'/> and 3121<xref linkend='IceErrorHeader' xrefstyle='select: title'/> 3122</para> 3123 3124<funcsynopsis id='IceWriteData'> 3125<funcprototype> 3126 <funcdef><function> IceWriteData</function></funcdef> 3127 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3128 <paramdef>int<parameter> bytes</parameter></paramdef> 3129 <paramdef>char<parameter> *data</parameter></paramdef> 3130</funcprototype> 3131</funcsynopsis> 3132 3133<variablelist remap='IP'> 3134 <varlistentry> 3135 <term><emphasis remap='I'>ice_conn</emphasis></term> 3136 <listitem> 3137 <para>A valid ICE connection object.</para> 3138 </listitem> 3139 </varlistentry> 3140 <varlistentry> 3141 <term><emphasis remap='I'>bytes</emphasis></term> 3142 <listitem> 3143 <para>The number of bytes to write.</para> 3144 </listitem> 3145 </varlistentry> 3146 <varlistentry> 3147 <term><emphasis remap='I'>data</emphasis></term> 3148 <listitem> 3149 <para>The data to write.</para> 3150 </listitem> 3151 </varlistentry> 3152</variablelist> 3153 3154 3155<para> 3156To write data as 16-bit quantities, use <xref linkend='IceWriteData16' xrefstyle='select: title'/> 3157</para> 3158 3159<funcsynopsis id='IceWriteData16'> 3160<funcprototype> 3161 <funcdef><function> IceWriteData16</function></funcdef> 3162 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3163 <paramdef>int<parameter> bytes</parameter></paramdef> 3164 <paramdef>char<parameter> *data</parameter></paramdef> 3165</funcprototype> 3166</funcsynopsis> 3167 3168<variablelist remap='IP'> 3169 <varlistentry> 3170 <term><emphasis remap='I'>ice_conn</emphasis></term> 3171 <listitem> 3172 <para>A valid ICE connection object.</para> 3173 </listitem> 3174 </varlistentry> 3175 <varlistentry> 3176 <term><emphasis remap='I'>bytes</emphasis></term> 3177 <listitem> 3178 <para>The number of bytes to write.</para> 3179 </listitem> 3180 </varlistentry> 3181 <varlistentry> 3182 <term><emphasis remap='I'>data</emphasis></term> 3183 <listitem> 3184 <para>The data to write.</para> 3185 </listitem> 3186 </varlistentry> 3187</variablelist> 3188 3189<para> 3190To write data as 32-bit quantities, use <xref linkend='IceWriteData32' xrefstyle='select: title'/> 3191</para> 3192 3193 3194<funcsynopsis id='IceWriteData32'> 3195<funcprototype> 3196 <funcdef><function> IceWriteData32</function></funcdef> 3197 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3198 <paramdef>int<parameter> bytes</parameter></paramdef> 3199 <paramdef>char<parameter> *data</parameter></paramdef> 3200</funcprototype> 3201</funcsynopsis> 3202 3203<variablelist remap='IP'> 3204 <varlistentry> 3205 <term><emphasis remap='I'>ice_conn</emphasis></term> 3206 <listitem> 3207 <para>A valid ICE connection object.</para> 3208 </listitem> 3209 </varlistentry> 3210 <varlistentry> 3211 <term><emphasis remap='I'>bytes</emphasis></term> 3212 <listitem> 3213 <para>The number of bytes to write.</para> 3214 </listitem> 3215 </varlistentry> 3216 <varlistentry> 3217 <term><emphasis remap='I'>data</emphasis></term> 3218 <listitem> 3219 <para>The data to write.</para> 3220 </listitem> 3221 </varlistentry> 3222</variablelist> 3223 3224<para> 3225To write data as 32-bit quantities, use <xref linkend='IceWriteData32' xrefstyle='select: title'/> 3226</para> 3227 3228<para> 3229To bypass copying data to the ICE output buffer, use 3230<xref linkend='IceSendData' xrefstyle='select: title'/> to directly send data over the network 3231connection. If necessary, the ICE output buffer is first flushed. 3232</para> 3233 3234<funcsynopsis id='IceSendData'> 3235<funcprototype> 3236 <funcdef><function> IceSendData</function></funcdef> 3237 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3238 <paramdef>int<parameter> bytes</parameter></paramdef> 3239 <paramdef>char<parameter> *data</parameter></paramdef> 3240</funcprototype> 3241</funcsynopsis> 3242 3243<variablelist remap='IP'> 3244 <varlistentry> 3245 <term><emphasis remap='I'>ice_conn</emphasis></term> 3246 <listitem> 3247 <para>A valid ICE connection object.</para> 3248 </listitem> 3249 </varlistentry> 3250 <varlistentry> 3251 <term><emphasis remap='I'>bytes</emphasis></term> 3252 <listitem> 3253 <para>The number of bytes to send.</para> 3254 </listitem> 3255 </varlistentry> 3256 <varlistentry> 3257 <term><emphasis remap='I'>data</emphasis></term> 3258 <listitem> 3259 <para>The data to send.</para> 3260 </listitem> 3261 </varlistentry> 3262</variablelist> 3263 3264 3265<para> 3266To force 32-bit or 64-bit alignment, use <xref linkend='IceWritePad' xrefstyle='select: title'/> 3267A maximum of 7 pad bytes can be specified. 3268</para> 3269 3270<funcsynopsis id='IceWritePad'> 3271<funcprototype> 3272 <funcdef><function> IceWritePad</function></funcdef> 3273 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3274 <paramdef>int<parameter> bytes</parameter></paramdef> 3275 <paramdef>char<parameter> *data</parameter></paramdef> 3276</funcprototype> 3277</funcsynopsis> 3278 3279<variablelist remap='IP'> 3280 <varlistentry> 3281 <term><emphasis remap='I'>ice_conn</emphasis></term> 3282 <listitem> 3283 <para>A valid ICE connection object.</para> 3284 </listitem> 3285 </varlistentry> 3286 <varlistentry> 3287 <term><emphasis remap='I'>bytes</emphasis></term> 3288 <listitem> 3289 <para>The number of bytes to write.</para> 3290 </listitem> 3291 </varlistentry> 3292 <varlistentry> 3293 <term><emphasis remap='I'>data</emphasis></term> 3294 <listitem> 3295 <para>The number of pad bytes to write.</para> 3296 </listitem> 3297 </varlistentry> 3298</variablelist> 3299 3300</sect1> 3301 3302<sect1 id='Reading_ICE_Messages'> 3303<title>Reading ICE Messages</title> 3304 3305 3306<para> 3307The ICE library maintains an input buffer used for reading messages. 3308If the ICE library chooses to perform nonblocking reads (this is 3309implementation-dependent), then for every read operation that it makes, 3310zero or more complete messages may be read into the input buffer. As 3311a result, for all of the macros described in this section that read 3312messages, an actual read operation will occur on the connection only if 3313the data is not already present in the input buffer. 3314</para> 3315 3316 3317<para> 3318To get the size of the ICE input buffer, use 3319<xref linkend='IceGetInBufSize' xrefstyle='select: title'/> 3320</para> 3321 3322<funcsynopsis id='IceGetInBufSize'> 3323<funcprototype> 3324 <funcdef>int<function> IceGetInBufSize</function></funcdef> 3325 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3326</funcprototype> 3327</funcsynopsis> 3328 3329<variablelist remap='IP'> 3330 <varlistentry> 3331 <term><emphasis remap='I'>ice_conn</emphasis></term> 3332 <listitem> 3333 <para>A valid ICE connection object.</para> 3334 </listitem> 3335 </varlistentry> 3336</variablelist> 3337 3338<para> 3339When reading messages, care must be taken to check for IO errors. If 3340any IO error occurs in reading any part of a message, the message should 3341be thrown out. After using any of the macros described below for reading 3342messages, the <xref linkend='IceValidIO' xrefstyle='select: title'/> 3343macro can be used to check if an IO error occurred on the 3344connection. After an IO error has occurred on an ICE connection, all 3345read operations will be ignored. For further information, see 3346<xref linkend='Error_Handling' xrefstyle='select: title'/>. 3347</para> 3348 3349 3350<funcsynopsis id='IceValidIO'> 3351<funcprototype> 3352 <funcdef>Bool<function> IceValidIO</function></funcdef> 3353 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3354</funcprototype> 3355</funcsynopsis> 3356 3357<variablelist remap='IP'> 3358 <varlistentry> 3359 <term><emphasis remap='I'>ice_conn</emphasis></term> 3360 <listitem> 3361 <para>A valid ICE connection object.</para> 3362 </listitem> 3363 </varlistentry> 3364</variablelist> 3365 3366<para>The following macros can be used to read ICE messages.</para> 3367 3368<funcsynopsis id='IceReadSimpleMessage'> 3369<funcprototype> 3370 <funcdef><function> IceReadSimpleMessage</function></funcdef> 3371 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3372 <paramdef><C_data_type><parameter> *pmsg</parameter></paramdef> 3373</funcprototype> 3374</funcsynopsis> 3375 3376<variablelist remap='IP'> 3377 <varlistentry> 3378 <term><emphasis remap='I'>ice_conn</emphasis></term> 3379 <listitem> 3380 <para>A valid ICE connection object.</para> 3381 </listitem> 3382 </varlistentry> 3383 <varlistentry> 3384 <term><emphasis remap='I'><C_data_type></emphasis></term> 3385 <listitem> 3386 <para>The actual C data type of the message header.</para> 3387 </listitem> 3388 </varlistentry> 3389 <varlistentry> 3390 <term><emphasis remap='I'>pmsg</emphasis></term> 3391 <listitem> 3392 <para>This pointer is set to the message header.</para> 3393 </listitem> 3394 </varlistentry> 3395</variablelist> 3396 3397<para> 3398<xref linkend='IceReadSimpleMessage' xrefstyle='select: title'/> 3399is used for messages that are identical in size to the 8-byte ICE header, but 3400use the spare 2 bytes in the header to encode additional data. Note that the 3401ICE library always reads in these first 8 bytes, so it can obtain the major 3402opcode of the message. <xref linkend='IceReadSimpleMessage' xrefstyle='select: title'/> 3403simply returns a pointer to these 8 bytes; it does not actually read any data 3404into the input buffer. 3405</para> 3406 3407<para> 3408For a message with variable length data, there are two ways of reading 3409the message. One method involves reading the complete message in one 3410pass using <xref linkend='IceReadCompleteMessage' xrefstyle='select: title'/> 3411The second method involves reading the message header (note that this may 3412be larger than the 8-byte ICE header), then reading 3413the variable length data in chunks (see 3414<xref linkend='IceReadMessageHeader' xrefstyle='select: title'/> and 3415<xref linkend='IceReadData' xrefstyle='select: title'/> 3416</para> 3417 3418 3419<funcsynopsis id='IceReadCompleteMessage'> 3420<funcprototype> 3421 <funcdef><function> IceReadCompleteMessage</function></funcdef> 3422 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3423 <paramdef>int<parameter> header_size</parameter></paramdef> 3424 <paramdef><C_data_type><parameter> *pmsg</parameter></paramdef> 3425 <paramdef>char<parameter> *pdata</parameter></paramdef> 3426</funcprototype> 3427</funcsynopsis> 3428 3429<variablelist remap='IP'> 3430 <varlistentry> 3431 <term><emphasis remap='I'>ice_conn</emphasis></term> 3432 <listitem> 3433 <para>A valid ICE connection object.</para> 3434 </listitem> 3435 </varlistentry> 3436 <varlistentry> 3437 <term><emphasis remap='I'>header_size</emphasis></term> 3438 <listitem> 3439 <para>The size of the message header (in bytes).</para> 3440 </listitem> 3441 </varlistentry> 3442 <varlistentry> 3443 <term><emphasis remap='I'><C_data_type></emphasis></term> 3444 <listitem> 3445 <para>The actual C data type of the message header.</para> 3446 </listitem> 3447 </varlistentry> 3448 <varlistentry> 3449 <term><emphasis remap='I'>pmsg</emphasis></term> 3450 <listitem> 3451 <para>This pointer is set to the message header.</para> 3452 </listitem> 3453 </varlistentry> 3454 <varlistentry> 3455 <term><emphasis remap='I'>pdata</emphasis></term> 3456 <listitem> 3457 <para> 3458This pointer is set to the variable length data of the message. 3459 </para> 3460 </listitem> 3461 </varlistentry> 3462</variablelist> 3463 3464<para> 3465If the ICE input buffer has sufficient space, 3466<xref linkend='IceReadCompleteMessage' xrefstyle='select: title'/> 3467will read the complete message into the 3468ICE input buffer. Otherwise, a buffer will be allocated to hold the 3469variable length data. After the call, the pdata argument should 3470be checked against NULL to make sure that there was sufficient memory 3471to allocate the buffer. 3472</para> 3473 3474<para> 3475After calling <xref linkend='IceReadCompleteMessage' xrefstyle='select: title'/> 3476and processing the message, <xref linkend='IceDisposeCompleteMessage' xrefstyle='select: title'/> 3477should be called. 3478</para> 3479 3480 3481<funcsynopsis id='IceDisposeCompleteMessage'> 3482<funcprototype> 3483 <funcdef><function> IceDisposeCompleteMessage</function></funcdef> 3484 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3485 <paramdef>char<parameter> *pdata</parameter></paramdef> 3486</funcprototype> 3487</funcsynopsis> 3488 3489<variablelist remap='IP'> 3490 <varlistentry> 3491 <term><emphasis remap='I'>ice_conn</emphasis></term> 3492 <listitem> 3493 <para>A valid ICE connection object.</para> 3494 </listitem> 3495 </varlistentry> 3496 <varlistentry> 3497 <term><emphasis remap='I'>pdata</emphasis></term> 3498 <listitem> 3499 <para> 3500The pointer to the variable length data returned in 3501<xref linkend='IceReadCompleteMessage' xrefstyle='select: title'/> 3502 </para> 3503 </listitem> 3504 </varlistentry> 3505</variablelist> 3506 3507<para> 3508If a buffer had to be allocated to hold the variable length data (because 3509it did not fit in the ICE input buffer), it is freed here by ICElib. 3510</para> 3511 3512 3513<funcsynopsis id='IceReadMessageHeader'> 3514<funcprototype> 3515 <funcdef><function> IceReadMessageHeader</function></funcdef> 3516 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3517 <paramdef>int<parameter> header_size</parameter></paramdef> 3518 <paramdef><C_data_type><parameter> *pmsg</parameter></paramdef> 3519</funcprototype> 3520</funcsynopsis> 3521 3522<variablelist remap='IP'> 3523 <varlistentry> 3524 <term><emphasis remap='I'>ice_conn</emphasis></term> 3525 <listitem> 3526 <para>A valid ICE connection object.</para> 3527 </listitem> 3528 </varlistentry> 3529 <varlistentry> 3530 <term><emphasis remap='I'>header_size</emphasis></term> 3531 <listitem> 3532 <para>The size of the message header (in bytes).</para> 3533 </listitem> 3534 </varlistentry> 3535 <varlistentry> 3536 <term><emphasis remap='I'><C_data_type></emphasis></term> 3537 <listitem> 3538 <para>The actual C data type of the message header.</para> 3539 </listitem> 3540 </varlistentry> 3541 <varlistentry> 3542 <term><emphasis remap='I'>pmsg</emphasis></term> 3543 <listitem> 3544 <para>This pointer is set to the message header.</para> 3545 </listitem> 3546 </varlistentry> 3547</variablelist> 3548 3549<para> 3550<xref linkend='IceReadMessageHeader' xrefstyle='select: title'/> reads just the message header. 3551The rest of the data should be read with the 3552<xref linkend='IceReadData' xrefstyle='select: title'/> 3553family of macros. This method of reading a message should be used when the 3554variable length data must be read in chunks. 3555</para> 3556 3557 3558<para> 3559To read data directly into a user supplied buffer, use 3560<xref linkend='IceReadData' xrefstyle='select: title'/> 3561</para> 3562 3563<funcsynopsis id='IceReadData'> 3564<funcprototype> 3565 <funcdef><function> IceReadData</function></funcdef> 3566 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3567 <paramdef>int<parameter> bytes</parameter></paramdef> 3568 <paramdef>char<parameter> *pdata</parameter></paramdef> 3569</funcprototype> 3570</funcsynopsis> 3571 3572<variablelist remap='IP'> 3573 <varlistentry> 3574 <term><emphasis remap='I'>ice_conn</emphasis></term> 3575 <listitem> 3576 <para>A valid ICE connection object.</para> 3577 </listitem> 3578 </varlistentry> 3579 <varlistentry> 3580 <term><emphasis remap='I'>bytes</emphasis></term> 3581 <listitem> 3582 <para>The number of bytes to read.</para> 3583 </listitem> 3584 </varlistentry> 3585 <varlistentry> 3586 <term><emphasis remap='I'>pdata</emphasis></term> 3587 <listitem> 3588 <para>The data is read into this user supplied buffer.</para> 3589 </listitem> 3590 </varlistentry> 3591</variablelist> 3592 3593 3594<para> 3595To read data as 16-bit quantities, use <xref linkend='IceReadData16' xrefstyle='select: title'/> 3596</para> 3597 3598<funcsynopsis id='IceReadData16'> 3599<funcprototype> 3600 <funcdef><function> IceReadData16</function></funcdef> 3601 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3602 <paramdef>Bool<parameter> swap</parameter></paramdef> 3603 <paramdef>int<parameter> bytes</parameter></paramdef> 3604 <paramdef>char<parameter> *pdata</parameter></paramdef> 3605</funcprototype> 3606</funcsynopsis> 3607 3608<variablelist remap='IP'> 3609 <varlistentry> 3610 <term><emphasis remap='I'>ice_conn</emphasis></term> 3611 <listitem> 3612 <para>A valid ICE connection object.</para> 3613 </listitem> 3614 </varlistentry> 3615 <varlistentry> 3616 <term><emphasis remap='I'>swap</emphasis></term> 3617 <listitem> 3618 <para> 3619If <function>True,</function> the values will be byte swapped. 3620 </para> 3621 </listitem> 3622 </varlistentry> 3623 <varlistentry> 3624 <term><emphasis remap='I'>bytes</emphasis></term> 3625 <listitem> 3626 <para>The number of bytes to read.</para> 3627 </listitem> 3628 </varlistentry> 3629 <varlistentry> 3630 <term><emphasis remap='I'>pdata</emphasis></term> 3631 <listitem> 3632 <para>The data is read into this user supplied buffer.</para> 3633 </listitem> 3634 </varlistentry> 3635</variablelist> 3636 3637 3638<para> 3639To read data as 32-bit quantities, use <xref linkend='IceReadData32' xrefstyle='select: title'/> 3640</para> 3641 3642<funcsynopsis id='IceReadData32'> 3643<funcprototype> 3644 <funcdef><function> IceReadData32</function></funcdef> 3645 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3646 <paramdef>Bool<parameter> swap</parameter></paramdef> 3647 <paramdef>int<parameter> bytes</parameter></paramdef> 3648 <paramdef>char<parameter> *pdata</parameter></paramdef> 3649</funcprototype> 3650</funcsynopsis> 3651 3652<variablelist remap='IP'> 3653 <varlistentry> 3654 <term><emphasis remap='I'>ice_conn</emphasis></term> 3655 <listitem> 3656 <para>A valid ICE connection object.</para> 3657 </listitem> 3658 </varlistentry> 3659 <varlistentry> 3660 <term><emphasis remap='I'>swap</emphasis></term> 3661 <listitem> 3662 <para> 3663If <function>True,</function> the values will be byte swapped. 3664 </para> 3665 </listitem> 3666 </varlistentry> 3667 <varlistentry> 3668 <term><emphasis remap='I'>bytes</emphasis></term> 3669 <listitem> 3670 <para>The number of bytes to read.</para> 3671 </listitem> 3672 </varlistentry> 3673 <varlistentry> 3674 <term><emphasis remap='I'>pdata</emphasis></term> 3675 <listitem> 3676 <para>The data is read into this user supplied buffer.</para> 3677 </listitem> 3678 </varlistentry> 3679</variablelist> 3680 3681<para>To force 32-bit or 64-bit alignment, use 3682<xref linkend='IceReadPad' xrefstyle='select: title'/> 3683A maximum of 7 pad bytes can be specified.</para> 3684 3685<funcsynopsis id='IceReadPad'> 3686<funcprototype> 3687 <funcdef><function> IceReadPad</function></funcdef> 3688 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3689 <paramdef>int<parameter> bytes</parameter></paramdef> 3690</funcprototype> 3691</funcsynopsis> 3692 3693<variablelist remap='IP'> 3694 <varlistentry> 3695 <term><emphasis remap='I'>ice_conn</emphasis></term> 3696 <listitem> 3697 <para>A valid ICE connection object.</para> 3698 </listitem> 3699 </varlistentry> 3700 <varlistentry> 3701 <term><emphasis remap='I'>bytes</emphasis></term> 3702 <listitem> 3703 <para>The number of pad bytes.</para> 3704 </listitem> 3705 </varlistentry> 3706</variablelist> 3707 3708</sect1> 3709</chapter> 3710 3711<chapter id='Error_Handling'> 3712<title>Error Handling</title> 3713 3714 3715<para>There are two default error handlers in ICElib:</para> 3716 3717<itemizedlist> 3718 <listitem> 3719 <para> 3720One to handle typically fatal conditions (for example, 3721a connection dying because a machine crashed) 3722 </para> 3723 </listitem> 3724 <listitem> 3725 <para>One to handle ICE-specific protocol errors</para> 3726 </listitem> 3727</itemizedlist> 3728 3729<para> 3730These error handlers can be changed to user-supplied routines if you 3731prefer your own error handling and can be changed as often as you like. 3732</para> 3733 3734 3735<para> 3736To set the ICE error handler, use <xref linkend='IceSetErrorHandler' xrefstyle='select: title'/> 3737</para> 3738 3739<funcsynopsis id='IceSetErrorHandler'> 3740<funcprototype> 3741 <funcdef><function> IceSetErrorHandler</function></funcdef> 3742 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3743 <paramdef>int<parameter> bytes</parameter></paramdef> 3744</funcprototype> 3745</funcsynopsis> 3746 3747<variablelist remap='IP'> 3748 <varlistentry> 3749 <term><emphasis remap='I'>handler</emphasis></term> 3750 <listitem> 3751 <para> 3752The ICE error handler. You should pass NULL to restore the default handler. 3753 </para> 3754 </listitem> 3755 </varlistentry> 3756</variablelist> 3757 3758<para> 3759<xref linkend='IceSetErrorHandler' xrefstyle='select: title'/> returns the previous error handler. 3760</para> 3761 3762<para> 3763The ICE error handler is invoked when an unexpected ICE protocol 3764error (major opcode 0) is encountered. The action of the default 3765handler is to print an explanatory message to 3766<function>stderr</function> 3767and if the severity is fatal, call 3768<function>exit</function> 3769with a nonzero value. If exiting 3770is undesirable, the application should register its own error handler. 3771</para> 3772 3773<para> 3774Note that errors in other protocol 3775domains should be handled by their respective libraries (these libraries 3776should have their own error handlers). 3777</para> 3778 3779<para> 3780An ICE error handler has the type of <xref linkend='IceErrorHandler' xrefstyle='select: title'/> 3781</para> 3782 3783<funcsynopsis id='IceErrorHandler'> 3784<funcprototype> 3785 <funcdef>void<function> IceErrorHandler</function></funcdef> 3786 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3787 <paramdef>Bool<parameter> swap</parameter></paramdef> 3788 <paramdef>int<parameter> offending_minor_opcode</parameter></paramdef> 3789 <paramdef>unsigned long<parameter> offending_sequence_num</parameter></paramdef> 3790 <paramdef>int<parameter> error_class</parameter></paramdef> 3791 <paramdef>int<parameter> severity</parameter></paramdef> 3792 <paramdef>IcePointer<parameter> values</parameter></paramdef> 3793</funcprototype> 3794</funcsynopsis> 3795 3796<variablelist remap='IP'> 3797 <varlistentry> 3798 <term><emphasis remap='I'>handler</emphasis></term> 3799 <listitem> 3800 <para>The ICE connection object.</para> 3801 </listitem> 3802 </varlistentry> 3803 <varlistentry> 3804 <term><emphasis remap='I'>swap</emphasis></term> 3805 <listitem> 3806 <para>A flag that indicates if the values need byte swapping.</para> 3807 </listitem> 3808 </varlistentry> 3809 <varlistentry> 3810 <term><emphasis remap='I'>offending_minor_opcode</emphasis></term> 3811 <listitem> 3812 <para>The ICE minor opcode of the offending message.</para> 3813 </listitem> 3814 </varlistentry> 3815 <varlistentry> 3816 <term><emphasis remap='I'>offending_sequence_num</emphasis></term> 3817 <listitem> 3818 <para>The sequence number of the offending message.</para> 3819 </listitem> 3820 </varlistentry> 3821 <varlistentry> 3822 <term><emphasis remap='I'>error_class</emphasis></term> 3823 <listitem> 3824 <para>The error class of the offending message.</para> 3825 </listitem> 3826 </varlistentry> 3827 <varlistentry> 3828 <term><emphasis remap='I'>severity</emphasis></term> 3829 <listitem> 3830 <para> 3831<function>IceCanContinue</function> 3832<function>IceFatalToProtocol</function> 3833or 3834<function>IceFatalToConnection</function> 3835 </para> 3836 </listitem> 3837 </varlistentry> 3838 <varlistentry> 3839 <term><emphasis remap='I'>values</emphasis></term> 3840 <listitem> 3841 <para> 3842Any additional error values specific to the minor opcode and class. 3843 </para> 3844 </listitem> 3845 </varlistentry> 3846</variablelist> 3847 3848 3849<para>The following error classes are defined at the ICE level:</para> 3850 3851<literallayout remap='Ds'> 3852<function>IceBadMinor</function> 3853<function>IceBadState</function> 3854<function>IceBadLength</function> 3855<function>IceBadValue</function> 3856<function>IceBadMajor</function> 3857<function>IceNoAuth</function> 3858<function>IceNoVersion</function> 3859<function>IceSetupFailed</function> 3860<function>IceAuthRejected</function> 3861<function>IceAuthFailed</function> 3862<function>IceProtocolDuplicate</function> 3863<function>IceMajorOpcodeDuplicate</function> 3864<function>IceUnknownProtocol</function> 3865</literallayout> 3866 3867<para> 3868For further information, see 3869the <emphasis remap='I'>Inter-Client Exchange Protocol</emphasis> standard. 3870</para> 3871 3872 3873<para> 3874To handle fatal I/O errors, use <xref linkend='IceSetIOErrorHandler' xrefstyle='select: title'/> 3875</para> 3876 3877 3878<funcsynopsis id='IceSetIOErrorHandler'> 3879<funcprototype> 3880 <funcdef>IceIOErrorHandler<function> IceSetIOErrorHandler</function></funcdef> 3881 <paramdef>IceIOErrorHandler<parameter> handler</parameter></paramdef> 3882</funcprototype> 3883</funcsynopsis> 3884 3885<variablelist remap='IP'> 3886 <varlistentry> 3887 <term><emphasis remap='I'>handler</emphasis></term> 3888 <listitem> 3889 <para> 3890The I/O error handler. You should pass NULL to restore the default handler. 3891 </para> 3892 </listitem> 3893 </varlistentry> 3894</variablelist> 3895 3896<para> 3897<xref linkend='IceSetIOErrorHandler' xrefstyle='select: title'/> returns the previous 3898IO error handler. 3899</para> 3900 3901<para> 3902An ICE I/O error handler has the type of 3903<xref linkend='IceIOErrorHandler' xrefstyle='select: title'/> 3904</para> 3905 3906<funcsynopsis id='IceIOErrorHandler'> 3907<funcprototype> 3908 <funcdef>void<function> IceIOErrorHandler</function></funcdef> 3909 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3910</funcprototype> 3911</funcsynopsis> 3912 3913<variablelist remap='IP'> 3914 <varlistentry> 3915 <term><emphasis remap='I'>ice_conn</emphasis></term> 3916 <listitem><para>The ICE connection object.</para></listitem> 3917 </varlistentry> 3918</variablelist> 3919 3920 3921<para> There are two ways of handling IO errors in ICElib:</para> 3922 3923<itemizedlist> 3924 <listitem> 3925 <para> 3926In the first, the IO error handler does whatever is necessary 3927to respond to the IO error and then returns, but it does not call 3928<xref linkend='IceCloseConnection' xrefstyle='select: title'/> 3929The ICE connection is given a "bad IO" status, and all future reads 3930and writes to the connection are ignored. The next time 3931<xref linkend='IceProcessMessages' xrefstyle='select: title'/> 3932is called it will return a status of 3933<function>IceProcessMessagesIOError</function> 3934At that time, the application should call 3935<xref linkend='IceCloseConnection' xrefstyle='select: title'/> 3936 </para> 3937 </listitem> 3938 <listitem> 3939 <para> 3940In the second, the IO error handler does call 3941<xref linkend='IceCloseConnection' xrefstyle='select: title'/> 3942and then uses the <function>longjmp</function> 3943call to get back to the application's main event loop. The 3944<function>setjmp</function> and 3945<function>longjmp</function> 3946calls may not work properly on all platforms, 3947and special care must be taken to avoid memory leaks. 3948Therefore, this second model is less desirable. 3949 </para> 3950 </listitem> 3951</itemizedlist> 3952 3953<para> 3954Before the application I/O error handler is invoked, protocol libraries 3955that were interested in being notified of I/O errors will have their 3956<xref linkend='IceIOErrorProc' xrefstyle='select: title'/> 3957handlers invoked. This handler is set up in the protocol registration 3958functions (see <xref linkend='IceRegisterForProtocolSetup' xrefstyle='select: title'/> and 3959<xref linkend='IceRegisterForProtocolReply' xrefstyle='select: title'/> 3960and could be used to clean up state specific to the protocol. 3961</para> 3962 3963 3964<funcsynopsis id='IceIOErrorProc'> 3965<funcprototype> 3966 <funcdef>void<function> IceIOErrorProc</function></funcdef> 3967 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 3968</funcprototype> 3969</funcsynopsis> 3970 3971<variablelist remap='IP'> 3972 <varlistentry> 3973 <term><emphasis remap='I'>ice_conn</emphasis></term> 3974 <listitem><para>The ICE connection object.</para></listitem> 3975 </varlistentry> 3976</variablelist> 3977 3978<para> 3979Note that every <xref linkend='IceIOErrorProc' xrefstyle='select: title'/> 3980callback must return. This is required 3981because each active protocol must be notified of the broken connection, 3982and the application IO error handler must be invoked afterwards. 3983</para> 3984</chapter> 3985 3986<chapter id='Multi_Threading_Support'> 3987<title>Multi-Threading Support</title> 3988 3989 3990<para>To declare that multiple threads in an application will be using the ICE 3991library, use 3992<function>IceInitThreads</function></para> 3993 3994<literallayout remap='FD'> 3995Status IceInitThreads() 3996</literallayout> 3997 3998 3999<para>The 4000<function>IceInitThreads</function> 4001function must be the first ICElib function a 4002multi-threaded program calls. It must complete before any other ICElib 4003call is made. 4004<function>IceInitThreads</function> 4005returns a nonzero status if and only if it was able 4006to initialize the threads package successfully. 4007It is safe to call 4008<function>IceInitThreads</function> 4009more than once, although the threads package will only be initialized once.</para> 4010 4011<para>Protocol libraries layered on top of ICElib will have to lock critical 4012sections of code that access an ICE connection (for example, when 4013generating messages). Two calls, which are generally implemented as 4014macros, are provided:</para> 4015 4016<funcsynopsis id='IceLockConn'> 4017<funcprototype> 4018 <funcdef>void<function> IceLockConn</function></funcdef> 4019 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 4020</funcprototype> 4021</funcsynopsis> 4022 4023<funcsynopsis id='IceUnlockConn'> 4024<funcprototype> 4025 <funcdef>void<function> IceUnlockConn</function></funcdef> 4026 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 4027</funcprototype> 4028</funcsynopsis> 4029 4030<variablelist remap='IP'> 4031 <varlistentry> 4032 <term><emphasis remap='I'>ice_conn</emphasis></term> 4033 <listitem><para>The ICE connection object.</para></listitem> 4034 </varlistentry> 4035</variablelist> 4036 4037<para>To keep an ICE connection locked across several ICElib calls, applications use 4038<xref linkend='IceAppLockConn' xrefstyle='select: title'/> 4039and 4040<xref linkend='IceAppUnlockConn' xrefstyle='select: title'/></para> 4041 4042<funcsynopsis id='IceAppLockConn'> 4043<funcprototype> 4044 <funcdef>void<function> IceAppLockConn</function></funcdef> 4045 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 4046</funcprototype> 4047</funcsynopsis> 4048 4049<variablelist remap='IP'> 4050 <varlistentry> 4051 <term><emphasis remap='I'>ice_conn</emphasis></term> 4052 <listitem><para>The ICE connection object.</para></listitem> 4053 </varlistentry> 4054</variablelist> 4055 4056 4057<para>The 4058<xref linkend='IceAppLockConn' xrefstyle='select: title'/> 4059function completely locks out other threads using the connection 4060until 4061<xref linkend='IceAppUnlockConn' xrefstyle='select: title'/> 4062is called. Other threads attempting to use ICElib 4063calls on the connection will block. 4064If the program has not previously called 4065<function>IceInitThreads</function> 4066<xref linkend='IceAppLockConn' xrefstyle='select: title'/> 4067has no effect.</para> 4068 4069<funcsynopsis id='IceAppUnlockConn'> 4070<funcprototype> 4071 <funcdef>void<function> IceAppUnlockConn</function></funcdef> 4072 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 4073</funcprototype> 4074</funcsynopsis> 4075 4076<variablelist remap='IP'> 4077 <varlistentry> 4078 <term><emphasis remap='I'>ice_conn</emphasis></term> 4079 <listitem><para>The ICE connection object.</para></listitem> 4080 </varlistentry> 4081</variablelist> 4082 4083<para>The 4084<xref linkend='IceAppUnlockConn' xrefstyle='select: title'/> 4085function allows other threads to complete ICElib 4086calls on the connection that were blocked by a previous call to 4087<xref linkend='IceAppLockConn' xrefstyle='select: title'/> 4088from this thread. If the program has not previously called 4089<function>IceInitThreads</function> 4090<xref linkend='IceAppUnlockConn' xrefstyle='select: title'/> 4091has no effect.</para> 4092</chapter> 4093 4094<chapter id='Miscellaneous_Functions'> 4095<title>Miscellaneous Functions</title> 4096 4097 4098 4099 4100<para>To allocate scratch space (for example, when generating 4101messages with variable data), use 4102<function>IceAllocScratch</function> 4103Each ICE connection has one scratch space associated with it. 4104The scratch space starts off as empty and grows as needed. 4105The contents of the scratch space is not guaranteed to be preserved 4106after any ICElib function is called.</para> 4107 4108 4109<funcsynopsis id='IceAllocScratch'> 4110<funcprototype> 4111 <funcdef>char<function> *IceAllocScratch</function></funcdef> 4112 <paramdef>IceConn<parameter> ice_conn</parameter></paramdef> 4113 <paramdef>unsigned long<parameter> size</parameter></paramdef> 4114</funcprototype> 4115</funcsynopsis> 4116 4117<variablelist remap='IP'> 4118 <varlistentry> 4119 <term><emphasis remap='I'>ice_conn</emphasis></term> 4120 <listitem><para>The ICE connection object.</para></listitem> 4121 </varlistentry> 4122 <varlistentry> 4123 <term><emphasis remap='I'>size</emphasis></term> 4124 <listitem><para>The number of bytes required.</para></listitem> 4125 </varlistentry> 4126</variablelist> 4127 4128<para>Note that the memory returned by 4129<function>IceAllocScratch</function> 4130should not be freed by the caller. 4131The ICE library will free the memory when the ICE connection is closed.</para> 4132</chapter> 4133 4134<chapter id='Acknowledgements'> 4135<title>Acknowledgements</title> 4136 4137 4138<para> 4139Thanks to Bob Scheifler for his thoughtful input on the design 4140of the ICE library. Thanks also to Jordan Brown, Larry Cable, Donna Converse, 4141Clive Feather, Stephen Gildea, Vania Joloboff, Kaleb Keithley, 4142Stuart Marks, Hiro Miyamoto, Ralph Swick, Jim VanGilder, and Mike Wexler. 4143</para> 4144</chapter> 4145 4146<appendix id="authentication_utility_functions"> 4147<title>Authentication Utility Functions</title> 4148 4149 4150<para> 4151As discussed in this document, the means by which authentication data 4152is obtained by the ICE library (for 4153<function>ConnectionSetup</function> 4154messages or 4155<function>ProtocolSetup</function> 4156messages) is implementation-dependent.† 4157<footnote remap='FS'> 4158<para>The X Consortium's ICElib implementation assumes the presence of an 4159ICE authority file. 4160</para></footnote> 4161</para> 4162 4163<para> 4164This appendix describes some utility functions that manipulate an 4165ICE authority file. The authority file can be used to pass authentication 4166data between clients. 4167</para> 4168 4169<para>The basic operations on the .ICEauthority file are:</para> 4170 4171<itemizedlist> 4172 <listitem> 4173 <para>Get file name</para> 4174 </listitem> 4175 <listitem> 4176 <para>Lock</para> 4177 </listitem> 4178 <listitem> 4179 <para>Unlock</para> 4180 </listitem> 4181 <listitem> 4182 <para>Read entry</para> 4183 </listitem> 4184 <listitem> 4185 <para>Write entry</para> 4186 </listitem> 4187 <listitem> 4188 <para>Search for entry</para> 4189 </listitem> 4190</itemizedlist> 4191 4192<para> 4193These are fairly low-level operations, and it is expected that a program, 4194like "iceauth", would exist to add, remove, and display entries in the file. 4195</para> 4196 4197<para> 4198In order to use these utility functions, the 4199<<symbol role='Pn'>X11/ICE/ICEutil.h</symbol>> 4200header file must be included. 4201</para> 4202 4203<para> 4204An entry in the .ICEauthority file is defined by the following data structure: 4205</para> 4206 4207 4208<literallayout class="monospaced"> 4209typedef struct { 4210 char *protocol_name; 4211 unsigned short protocol_data_length; 4212 char *protocol_data; 4213 char *network_id; 4214 char *auth_name; 4215 unsigned short auth_data_length; 4216 char *auth_data; 4217} IceAuthFileEntry; 4218</literallayout> 4219 4220 4221<para> 4222The protocol_name member is either "ICE" for connection setup authentication 4223or the subprotocol name, such as "XSMP". For each entry, protocol specific 4224data can be specified in the protocol_data member. This can be used 4225to search for old entries that need to be removed from the file. 4226</para> 4227 4228<para> 4229The network_id member is the network ID of the client accepting 4230authentication (for example, the network ID of a session manager). 4231A network ID has the following form: 4232</para> 4233 4234<informaltable frame='none'> 4235 <?dbfo keep-together="always" ?> 4236 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 4237 <colspec colname='c1' colwidth='1.0*'/> 4238 <colspec colname='c2' colwidth='2.0*'/> 4239 <tbody> 4240 <row> 4241 <entry>tcp/<hostname>:<portnumber></entry> 4242 <entry>or</entry> 4243 </row> 4244 <row> 4245 <entry>decnet/<hostname>::<objname></entry> 4246 <entry>or</entry> 4247 </row> 4248 <row> 4249 <entry>local/<hostname>:<path></entry> 4250 <entry></entry> 4251 </row> 4252 </tbody> 4253 </tgroup> 4254</informaltable> 4255 4256<para> 4257The auth_name member is the name of the authentication method. 4258The auth_data member is the actual authentication data, 4259and the auth_data_length member is the number of bytes in the data. 4260</para> 4261 4262<para> 4263To obtain the default authorization file name, use 4264<function>IceAuthFileName</function> 4265</para> 4266 4267<literallayout remap='FD'> 4268char *IceAuthFileName() 4269</literallayout> 4270 4271<para> 4272If the ICEAUTHORITY environment variable if set, this value is returned. 4273Otherwise, the default authorization file name is $HOME/.ICEauthority. 4274This name is statically allocated and should not be freed. 4275</para> 4276 4277<para> 4278To synchronously update the authorization file, the file must 4279be locked with a call to 4280<xref linkend='IceLockAuthFile' xrefstyle='select: title'/> 4281This function takes advantage of the fact that the 4282<function>link</function> 4283system call will fail if the name of the new link already exists. 4284</para> 4285 4286<funcsynopsis id='IceLockAuthFile'> 4287<funcprototype> 4288 <funcdef>int<function> IceLockAuthFile</function></funcdef> 4289 <paramdef>char<parameter> *file_name</parameter></paramdef> 4290 <paramdef>int<parameter> retries</parameter></paramdef> 4291 <paramdef>int<parameter> timeout</parameter></paramdef> 4292 <paramdef>long<parameter> dead</parameter></paramdef> 4293</funcprototype> 4294</funcsynopsis> 4295 4296<variablelist remap='IP'> 4297 <varlistentry> 4298 <term><emphasis remap='I'>file_name</emphasis></term> 4299 <listitem><para>The authorization file to lock.</para></listitem> 4300 </varlistentry> 4301 <varlistentry> 4302 <term><emphasis remap='I'>retries</emphasis></term> 4303 <listitem> 4304 <para>The number of retries.</para> 4305 </listitem> 4306 </varlistentry> 4307 <varlistentry> 4308 <term><emphasis remap='I'>timeout</emphasis></term> 4309 <listitem> 4310 <para>The number of seconds before each retry.</para> 4311 </listitem> 4312 </varlistentry> 4313 <varlistentry> 4314 <term><emphasis remap='I'>dead</emphasis></term> 4315 <listitem> 4316 <para> 4317If a lock already exists that is the specified dead seconds old, 4318it is broken. 4319A value of zero is used to unconditionally break an old lock. 4320 </para> 4321 </listitem> 4322 </varlistentry> 4323</variablelist> 4324 4325<para>One of three values is returned:</para> 4326 4327<itemizedlist> 4328 <listitem> 4329 <para> 4330<function>IceAuthLockSuccess</function> - the lock succeeded. 4331 </para> 4332 </listitem> 4333 <listitem> 4334 <para> 4335<function>IceAuthLockError</function> - a system error occurred, and 4336<function>errno</function> may prove useful. 4337 </para> 4338 </listitem> 4339 <listitem> 4340 <para> 4341<function>IceAuthLockTimeout</function> - the specified number of 4342retries failed. 4343 </para> 4344 </listitem> 4345</itemizedlist> 4346 4347<para> 4348To unlock an authorization file, use <xref linkend='IceUnlockAuthFile' xrefstyle='select: title'/> 4349</para> 4350 4351<funcsynopsis id='IceUnlockAuthFile'> 4352<funcprototype> 4353 <funcdef>int<function> IceUnlockAuthFile</function></funcdef> 4354 <paramdef>char<parameter> *file_name</parameter></paramdef> 4355</funcprototype> 4356</funcsynopsis> 4357 4358<variablelist remap='IP'> 4359 <varlistentry> 4360 <term><emphasis remap='I'>file_name</emphasis></term> 4361 <listitem><para>The authorization file to unlock.</para></listitem> 4362 </varlistentry> 4363</variablelist> 4364 4365<para> 4366To read the next entry in an authorization file, use 4367<function>IceReadAuthFileEntry</function> 4368</para> 4369 4370<funcsynopsis id='IceReadAuthFileEntry'> 4371<funcprototype> 4372 <funcdef>IceAuthFileEntry<function> *IceReadAuthFileEntry</function></funcdef> 4373 <paramdef>FILE<parameter> *auth_file</parameter></paramdef> 4374</funcprototype> 4375</funcsynopsis> 4376 4377<variablelist remap='IP'> 4378 <varlistentry> 4379 <term><emphasis remap='I'>auth_file</emphasis></term> 4380 <listitem><para>The authorization file.</para></listitem> 4381 </varlistentry> 4382</variablelist> 4383 4384<para> 4385Note that it is the responsibility of the application to open the file 4386for reading before calling this function. If an error is encountered, 4387or there are no more entries to read, NULL is returned. 4388</para> 4389 4390<para> 4391Entries should be free with a call to 4392<xref linkend='IceFreeAuthFileEntry' xrefstyle='select: title'/> 4393</para> 4394 4395<para> 4396To write an entry in an authorization file, use 4397<xref linkend='IceWriteAuthFileEntry' xrefstyle='select: title'/> 4398</para> 4399 4400<funcsynopsis id='IceWriteAuthFileEntry'> 4401<funcprototype> 4402 <funcdef>Status<function> IceWriteAuthFileEntry</function></funcdef> 4403 <paramdef>FILE<parameter> *auth_file</parameter></paramdef> 4404 <paramdef>IceAuthFileEntry<parameter> *entry</parameter></paramdef> 4405</funcprototype> 4406</funcsynopsis> 4407 4408<variablelist remap='IP'> 4409 <varlistentry> 4410 <term><emphasis remap='I'>auth_file</emphasis></term> 4411 <listitem><para>The authorization file.</para></listitem> 4412 </varlistentry> 4413 <varlistentry> 4414 <term><emphasis remap='I'>entry</emphasis></term> 4415 <listitem><para>The entry to write.</para></listitem> 4416 </varlistentry> 4417</variablelist> 4418 4419<para> 4420Note that it is the responsibility of the application to open the file 4421for writing before calling this function. The function returns a nonzero 4422status if the operation was successful. 4423</para> 4424 4425 4426<para> 4427To search the default authorization file for an entry that matches a given 4428protocol_name/network_id/auth_name tuple, use 4429<function>IceGetAuthFileEntry</function> 4430</para> 4431 4432<funcsynopsis id='IceGetAuthFileEntry'> 4433<funcprototype> 4434 <funcdef>IceAuthFileEntry<function> *IceGetAuthFileEntry</function></funcdef> 4435 <paramdef>const char *<parameter>protocol_name</parameter></paramdef> 4436 <paramdef>const char *<parameter>network_id</parameter></paramdef> 4437 <paramdef>const char *<parameter>auth_name</parameter></paramdef> 4438</funcprototype> 4439</funcsynopsis> 4440 4441<variablelist remap='IP'> 4442 <varlistentry> 4443 <term><emphasis remap='I'>auth_file</emphasis></term> 4444 <listitem><para>The name of the protocol to search on.</para></listitem> 4445 </varlistentry> 4446 <varlistentry> 4447 <term><emphasis remap='I'>network_id</emphasis></term> 4448 <listitem> 4449 <para>The network ID to search on.</para> 4450 </listitem> 4451 </varlistentry> 4452 <varlistentry> 4453 <term><emphasis remap='I'>auth_name</emphasis></term> 4454 <listitem> 4455 <para>The authentication method to search on.</para> 4456 </listitem> 4457 </varlistentry> 4458</variablelist> 4459 4460<para> 4461If <function>IceGetAuthFileEntry</function> 4462fails to find such an entry, NULL is returned. 4463</para> 4464 4465 4466<para> 4467To free an entry returned by 4468<function>IceReadAuthFileEntry</function> or 4469<function>IceGetAuthFileEntry</function> use 4470<xref linkend='IceFreeAuthFileEntry' xrefstyle='select: title'/> 4471</para> 4472 4473<funcsynopsis id='IceFreeAuthFileEntry'> 4474<funcprototype> 4475 <funcdef>void<function> IceFreeAuthFileEntry</function></funcdef> 4476 <paramdef>IceAuthFileEntry<parameter> *entry</parameter></paramdef> 4477</funcprototype> 4478</funcsynopsis> 4479 4480<variablelist remap='IP'> 4481 <varlistentry> 4482 <term><emphasis remap='I'>entry</emphasis></term> 4483 <listitem><para>The entry to free.</para></listitem> 4484 </varlistentry> 4485</variablelist> 4486 4487</appendix> 4488 4489<appendix id="mit_magic_cookie_1_authentication"> 4490<title>MIT-MAGIC-COOKIE-1 Authentication</title> 4491 4492 4493<para>The X Consortium's ICElib implementation supports a simple 4494MIT-MAGIC-COOKIE-1 authentication scheme using the authority file utilities 4495described in Appendix A.</para> 4496 4497<para>In this model, an application, such as a session manager, obtains a 4498magic cookie by calling 4499<function>IceGenerateMagicCookie</function> 4500and then stores it in the user's local .ICEauthority file 4501so that local clients can connect. In order to allow remote clients to 4502connect, some remote execution mechanism should be used to store the 4503magic cookie in the user's .ICEauthority file on a remote machine.</para> 4504 4505<para>In addition to storing the magic cookie in the .ICEauthority file, the 4506application needs to call the 4507<xref linkend='IceSetPaAuthData' xrefstyle='select: title'/> 4508function in order to store the magic cookie in memory. When it comes time 4509for the MIT-MAGIC-COOKIE-1 authentication procedure to accept or reject the 4510connection, it will compare the magic cookie presented by the requestor to 4511the magic cookie in memory.</para> 4512 4513<funcsynopsis id='IceGenerateMagicCookie'> 4514<funcprototype> 4515 <funcdef>char<function> *IceGenerateMagicCookie</function></funcdef> 4516 <paramdef>int<parameter> length</parameter></paramdef> 4517</funcprototype> 4518</funcsynopsis> 4519 4520<variablelist remap='IP'> 4521 <varlistentry> 4522 <term><emphasis remap='I'>length</emphasis></term> 4523 <listitem><para>The desired length of the magic cookie.</para></listitem> 4524 </varlistentry> 4525</variablelist> 4526 4527 4528<para>The magic cookie returned will be null-terminated. If memory can not be 4529allocated for the magic cookie, the function will return NULL. 4530Otherwise, the magic cookie should be freed with a call to 4531<function>free</function></para> 4532 4533 4534<para>To store the authentication data in memory, use 4535<xref linkend='IceSetPaAuthData' xrefstyle='select: title'/> 4536Currently, this function is only used for MIT-MAGIC-COOKIE-1 4537authentication, but it may be used for additional authentication 4538methods in the future.</para> 4539 4540<funcsynopsis id='IceSetPaAuthData'> 4541<funcprototype> 4542 <funcdef>void<function> IceSetPaAuthData</function></funcdef> 4543 <paramdef>int<parameter> num_entries</parameter></paramdef> 4544 <paramdef>IceAuthDataEntry<parameter> *entries</parameter></paramdef> 4545</funcprototype> 4546</funcsynopsis> 4547 4548<variablelist remap='IP'> 4549 <varlistentry> 4550 <term><emphasis remap='I'>num_entries</emphasis></term> 4551 <listitem><para>The number of authentication data entries.</para></listitem> 4552 </varlistentry> 4553 <varlistentry> 4554 <term><emphasis remap='I'>entries</emphasis></term> 4555 <listitem><para>The list of authentication data entries.</para></listitem> 4556 </varlistentry> 4557</variablelist> 4558 4559<para>Each entry has associated with it a protocol name 4560(for example, "ICE" for ICE connection setup authentication, 4561"XSMP" for session management authentication), a network ID for the 4562"accepting" client, an authentication name (for example, MIT-MAGIC-COOKIE-1), 4563and authentication data. The ICE library 4564will merge these entries with previously set entries, based on the 4565(protocol_name, network_id, auth_name) tuple.</para> 4566 4567 4568 4569<literallayout class="monospaced"> 4570typedef struct { 4571 char *protocol_name; 4572 char *network_id; 4573 char *auth_name; 4574 unsigned short auth_data_length; 4575 char *auth_data; 4576} IceAuthDataEntry; 4577</literallayout> 4578 4579</appendix> 4580</book> 4581 4582