trans.xml revision 6cc2b21f
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<book id="trans"> 6 7<bookinfo> 8 <title>The XIM Transport Specification</title> 9 <subtitle>Revision 0.1</subtitle> 10 <releaseinfo>X Version 11, Release 7</releaseinfo> 11 <authorgroup> 12 <author> 13 <firstname>Takashi</firstname><surname>Fujiwara</surname> 14 <affiliation><orgname>FUJITSU LIMITED</orgname></affiliation> 15 </author> 16 </authorgroup> 17 <copyright><year>1994</year><holder>FUJITSU LIMITED</holder></copyright> 18 <copyright><year>1994</year><holder>X Consortium</holder></copyright> 19 20 <productnumber>Revision 0.1</productnumber> 21 22 23<abstract> 24<para> 25This specification describes the transport layer interfaces between Xlib and IM Server, 26which makes various channels usable such as X protocol or TCP/IP, DECnet and etc. 27</para> 28</abstract> 29 30<legalnotice> 31 32<para> 33Permission is hereby granted, free of charge, to any person obtaining a copy 34of this software and associated documentation files 35(the “Software”), to deal in the Software without restriction, 36including without limitation the rights to use, copy, modify, merge, publish, 37distribute, sublicense, and/or sell copies of the Software, and to permit 38persons to whom the Software is furnished to do so, subject to the following 39conditions: 40</para> 41 42<para> 43The above copyright notice and this permission notice shall be included in all 44copies or substantial portions of the Software. 45</para> 46 47<para> 48THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, 49EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 50MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN 51NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 52LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 53OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 54THE SOFTWARE. 55</para> 56 57<para> 58Except as contained in this notice, the name of The Open Group shall not 59be used in advertising or otherwise to promote the sale, use or other dealings 60in this Software without prior written authorization from X Consortium. 61</para> 62 63<para>X Window System is a trademark of The Open Group.</para> 64 65</legalnotice> 66</bookinfo> 67 68<chapter id="xim_transport_specification"> 69<title>X Transport Specification</title> 70 71<sect1 id="Introduction"> 72<title>Introduction</title> 73<!-- .XS --> 74<!-- (SN Introduction --> 75<!-- .XE --> 76<para> 77<!-- .LP --> 78The Xlib XIM implementation is layered into three functions, a protocol 79layer, an interface layer and a transport layer. The purpose of this 80layering is to make the protocol independent of transport implementation. 81Each function of these layers are: 82<!-- .RS 3 --> 83</para> 84<variablelist> 85 <varlistentry> 86 <term><emphasis>The protocol layer</emphasis></term> 87 <listitem> 88 <para> 89implements overall function of XIM and calls the interface layer 90functions when it needs to communicate to IM Server. 91 </para> 92 </listitem> 93 </varlistentry> 94 <varlistentry> 95 <term><emphasis>The interface layer</emphasis></term> 96 <listitem> 97 <para> 98separates the implementation of the transport layer from the protocol 99layer, in other words, it provides implementation independent hook for 100the transport layer functions. 101 </para> 102 </listitem> 103 </varlistentry> 104 105 <varlistentry> 106 <term><emphasis>The transport layer</emphasis></term> 107 <listitem> 108 <para> 109handles actual data communication with IM Server. It is done by a set 110of several functions named transporters. 111 </para> 112 </listitem> 113 </varlistentry> 114</variablelist> 115 116<para> 117This specification describes the interface layer and the transport 118layer, which makes various communication channels usable such as 119X protocol or, TCP/IP, DECnet, STREAM, etc., and provides 120the information needed for adding another new transport layer. 121In addition, sample implementations for the transporter using the 122X connection is described in section 4. <!-- xref --> 123</para> 124</sect1> 125 126<sect1 id="Initialization"> 127<title>Initialization</title> 128 129<sect2 id="Registering_structure_to_initialize"> 130<title>Registering structure to initialize</title> 131 132<para> 133The structure typed as TransportSW contains the list of the transport 134layer the specific implementations supports. 135</para> 136 137<literallayout class="monospaced"> 138typedef struct { 139 char *transport_name; 140 Bool (*config); 141} TransportSW; 142</literallayout> 143 144<informaltable frame="none"> 145 <tgroup cols="2"> 146 <colspec colname="col1" colwidth="1*" colsep="0"/> 147 <colspec colname="col2" colwidth="1*" colsep="0"/> 148 <tbody> 149 <row rowsep="0"> 150 <entry><emphasis>transport_name</emphasis></entry> 151 <entry>name of transport<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote></entry> 152 </row> 153 <row rowsep="0"> 154 <entry><emphasis>config</emphasis></entry> 155 <entry>initial configuration function</entry> 156 </row> 157 </tbody> 158 </tgroup> 159</informaltable> 160 161<para> 162A sample entry for the Xlib supporting transporters is shown below: 163</para> 164 165<literallayout class="monospaced"> 166TransportSW _XimTransportRec[] = { 167/* char <emphasis remap='I'>*</emphasis>: 168 * transport_name, Bool <emphasis remap='I'>(*config)()</emphasis> 169 */ 170 "X", _XimXConf, 171 "tcp", _XimTransConf, 172 "local", _XimTransConf, 173 "decnet", _XimTransConf, 174 "streams", _XimTransConf, 175 (char *)NULL, (Bool (*)())NULL, 176}; 177</literallayout> 178 179</sect2> 180<sect2 id="Initialization_function"> 181<title>Initialization function</title> 182<!-- .XS --> 183<!-- (SN Initialization function --> 184<!-- .XE --> 185<para> 186The following function will be called once when Xlib configures the 187transporter functions. 188</para> 189 190<funcsynopsis> 191<funcprototype> 192 <funcdef>Bool <function>(*config)</function></funcdef> 193 <paramdef>XIM<parameter> im</parameter></paramdef> 194 <paramdef>char<parameter> *transport_data</parameter></paramdef> 195</funcprototype> 196</funcsynopsis> 197 198<variablelist> 199 <varlistentry> 200 <term> 201 <emphasis remap='I'>im</emphasis> 202 </term> 203 <listitem> 204 <para> 205Specifies XIM structure address. 206 </para> 207 </listitem> 208 </varlistentry> 209 <varlistentry> 210 <term> 211 <emphasis remap='I'>transport_data</emphasis> 212 </term> 213 <listitem> 214 <para> 215Specifies the data specific to the transporter, in IM Server address.<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote> 216 </para> 217 </listitem> 218 </varlistentry> 219</variablelist> 220 221<para> 222This function must setup the transporter function pointers. 223</para> 224 225<para> 226<!-- .LP --> 227The actual <emphasis remap='I'>config</emphasis> function will be chosen by IM Server at the 228pre-connection time, matching by the <emphasis remap='I'>transport_name</emphasis> specified 229in the <function>_XimTransportRec</function> array; The specific members of XimProto 230structure listed below must be initialized so that point they 231appropriate transporter functions. 232</para> 233 234<para> 235If the specified transporter has been configured successfully, this 236function returns True. There is no Alternative Entry for config 237function itself. 238</para> 239 240<para> 241The structure XimProto contains the following function pointers: 242</para> 243 244<literallayout class="monospaced"> 245Bool (*connect)(); /* Open connection */ 246Bool (*shutdown)(); /* Close connection */ 247Bool (*write)(); /* Write data */ 248Bool (*read)(); /* Read data */ 249Bool (*flush)(); /* Flush data buffer */ 250Bool (*register_dispatcher)(); /* Register asynchronous data handler */ 251Bool (*call_dispatcher)(); /* Call dispatcher */ 252</literallayout> 253 254<para> 255These functions are called when Xlib needs to communicate the 256IM Server. These functions must process the appropriate procedure 257described below. 258</para> 259 260</sect2> 261</sect1> 262<sect1 id="The_interface_transport_layer_functions"> 263<title>The interface/transport layer functions</title> 264<para> 265Following functions are used for the transport interface. 266</para> 267 268<table frame="all" id="transport_layer_functions_2"> 269 <title>The Transport Layer Functions</title> 270 <tgroup cols="3"> 271 <colspec colname="col1" colwidth="3*" colsep="1"/> 272 <colspec colname="col2" colwidth="3*" colsep="1"/> 273 <colspec colname="col3" colwidth="1*" colsep="1"/> 274 <thead> 275 <row> 276 <entry align="center">Alternate Entry (Interface Layer)</entry> 277 <entry align="center">XimProto member (Transport Layer)</entry> 278 <entry align="center">Section</entry> 279 </row> 280 </thead> 281 <tbody> 282 <row> 283 <entry>_XimConnect</entry> 284 <entry>connect</entry> 285 <entry>3.1</entry> 286 </row> 287 <row> 288 <entry>_XimShutdown</entry> 289 <entry>shutdown</entry> 290 <entry>3.2</entry> 291 </row> 292 <row> 293 <entry>_XimWrite</entry> 294 <entry>write</entry> 295 <entry>3.3</entry> 296 </row> 297 <row> 298 <entry>_XimRead</entry> 299 <entry>read</entry> 300 <entry>3.4</entry> 301 </row> 302 <row> 303 <entry>_XimFlush</entry> 304 <entry>flush</entry> 305 <entry>3.5</entry> 306 </row> 307 <row> 308 <entry>_XimRegisterDispatcher</entry> 309 <entry>register_dispatcher</entry> 310 <entry>3.6</entry> 311 </row> 312 <row> 313 <entry>_XimCallDispatcher</entry> 314 <entry>call_dispatcher</entry> 315 <entry>3.7</entry> 316 </row> 317 </tbody> 318 </tgroup> 319</table> 320 321<para> 322The Protocol layer calls the above functions using the Alternative 323Entry in the left column. The transport implementation defines 324XimProto member function in the right column. The Alternative Entry is 325provided so as to make easier to implement the Protocol Layer. 326</para> 327 328<sect2 id="Opening_connection"> 329<title>Opening connection</title> 330<para> 331<!-- .LP --> 332When <function>XOpenIM</function> is called, the following function is called to connect 333with the IM Server. 334</para> 335 336<funcsynopsis> 337<funcprototype> 338 <funcdef>Bool <function>(*connect)</function></funcdef> 339 <paramdef>XIM<parameter> im</parameter></paramdef> 340</funcprototype> 341</funcsynopsis> 342 343<variablelist> 344 <varlistentry> 345 <term> 346 <emphasis remap='I'>im</emphasis> 347 </term> 348 <listitem> 349 <para> 350Specifies XIM structure address. 351 </para> 352 </listitem> 353 </varlistentry> 354</variablelist> 355 356<para> 357This function must establishes the connection to the IM Server. If the 358connection is established successfully, this function returns True. 359The Alternative Entry for this function is: 360</para> 361 362<funcsynopsis id='_ximconnect'> 363<funcprototype> 364 <funcdef>Bool <function> _XimConnect</function></funcdef> 365 <paramdef>XIM<parameter> im</parameter></paramdef> 366</funcprototype> 367</funcsynopsis> 368 369<variablelist> 370 <varlistentry> 371 <term> 372 <emphasis remap='I'>im</emphasis> 373 </term> 374 <listitem> 375 <para> 376Specifies XIM structure address. 377 </para> 378 </listitem> 379 </varlistentry> 380</variablelist> 381</sect2> 382 383<sect2 id="Closing_connection"> 384<title>Closing connection</title> 385<!-- .XS --> 386<!-- (SN Closing connection --> 387<!-- .XE --> 388<para> 389<!-- .LP --> 390When <function>XCloseIM</function> is called, the following function is called to 391disconnect the connection with the IM Server. The Alternative Entry 392for this function is: 393</para> 394 395<funcsynopsis> 396<funcprototype> 397 <funcdef>Bool <function> (*shutdown)</function></funcdef> 398 <paramdef>XIM<parameter> im</parameter></paramdef> 399</funcprototype> 400</funcsynopsis> 401 402<variablelist> 403 <varlistentry> 404 <term> 405 <emphasis remap='I'>im</emphasis> 406 </term> 407 <listitem> 408 <para> 409Specifies XIM structure address. 410 </para> 411 </listitem> 412 </varlistentry> 413</variablelist> 414 415<para> 416<!-- .LP --> 417This function must close connection with the IM Server. If the 418connection is closed successfully, this function returns True. The 419Alternative Entry for this function is: 420</para> 421 422<funcsynopsis id='_ximshutdown'> 423<funcprototype> 424 <funcdef>Bool <function>_XimShutdown</function></funcdef> 425 <paramdef>XIM<parameter> im</parameter></paramdef> 426</funcprototype> 427</funcsynopsis> 428 429<variablelist> 430 <varlistentry> 431 <term> 432 <emphasis remap='I'>im</emphasis> 433 </term> 434 <listitem> 435 <para> 436Specifies XIM structure address. 437 </para> 438 </listitem> 439 </varlistentry> 440</variablelist> 441 442</sect2> 443 444<sect2 id="Writing_data"> 445<title>Writing data</title> 446<para> 447The following function is called, when Xlib needs to write data to the 448IM Server. 449</para> 450 451<funcsynopsis id='_ximwrite'> 452<funcprototype> 453 <funcdef>Bool <function> _XimWrite</function></funcdef> 454 <paramdef>XIM<parameter> im</parameter></paramdef> 455 <paramdef>INT16<parameter> len</parameter></paramdef> 456 <paramdef>XPointer<parameter> data</parameter></paramdef> 457</funcprototype> 458</funcsynopsis> 459 460<variablelist> 461 <varlistentry> 462 <term> 463 <emphasis remap='I'>im</emphasis> 464 </term> 465 <listitem> 466 <para> 467Specifies XIM structure address. 468 </para> 469 </listitem> 470 </varlistentry> 471 <varlistentry> 472 <term> 473 <emphasis remap='I'>len</emphasis> 474 </term> 475 <listitem> 476 <para> 477Specifies the length of writing data. 478 </para> 479 </listitem> 480 </varlistentry> 481 <varlistentry> 482 <term> 483 <emphasis remap='I'>data</emphasis> 484 </term> 485 <listitem> 486 <para> 487Specifies the writing data. 488 </para> 489 </listitem> 490 </varlistentry> 491</variablelist> 492 493<para> 494This function writes the <emphasis remap='I'>data</emphasis> to the IM Server, regardless 495of the contents. The number of bytes is passed to <emphasis remap='I'>len</emphasis>. The 496writing data is passed to <emphasis remap='I'>data</emphasis>. If data is sent successfully, 497the function returns True. Refer to "The Input Method Protocol" for 498the contents of the writing data. The Alternative Entry for this 499function is: 500</para> 501 502<funcsynopsis> 503<funcprototype> 504 <funcdef>Bool <function>_XimWrite</function></funcdef> 505 <paramdef>XIM<parameter> im</parameter></paramdef> 506 <paramdef>INT16<parameter> len</parameter></paramdef> 507 <paramdef>XPointer<parameter> data</parameter></paramdef> 508</funcprototype> 509</funcsynopsis> 510 511<variablelist> 512 <varlistentry> 513 <term> 514 <emphasis remap='I'>im</emphasis> 515 </term> 516 <listitem> 517 <para> 518Specifies XIM structure address. 519 </para> 520 </listitem> 521 </varlistentry> 522 <varlistentry> 523 <term> 524 <emphasis remap='I'>len</emphasis> 525 </term> 526 <listitem> 527 <para> 528Specifies the length of writing data. 529 </para> 530 </listitem> 531 </varlistentry> 532 <varlistentry> 533 <term> 534 <emphasis remap='I'>data</emphasis> 535 </term> 536 <listitem> 537 <para> 538Specifies the writing data. 539 </para> 540 </listitem> 541 </varlistentry> 542</variablelist> 543 544</sect2> 545<sect2 id="Reading_data"> 546<title>Reading data</title> 547<para> 548The following function is called when Xlib waits for response from IM 549server synchronously. 550</para> 551 552<funcsynopsis id='_ximread'> 553<funcprototype> 554 <funcdef>Bool <function> _XimRead</function></funcdef> 555 <paramdef>XIM<parameter> im</parameter></paramdef> 556 <paramdef>XPointer<parameter> read_buf</parameter></paramdef> 557 <paramdef>int<parameter> buf_len</parameter></paramdef> 558 <paramdef>int<parameter> *ret_len</parameter></paramdef> 559</funcprototype> 560</funcsynopsis> 561 562<variablelist> 563 <varlistentry> 564 <term> 565 <emphasis remap='I'>im</emphasis> 566 </term> 567 <listitem> 568 <para> 569Specifies XIM structure address. 570 </para> 571 </listitem> 572 </varlistentry> 573 <varlistentry> 574 <term> 575 <emphasis remap='I'>read_buf</emphasis> 576 </term> 577 <listitem> 578 <para> 579Specifies the buffer to store data. 580 </para> 581 </listitem> 582 </varlistentry> 583 <varlistentry> 584 <term> 585 <emphasis remap='I'>buf_len</emphasis> 586 </term> 587 <listitem> 588 <para> 589Specifies the size of the <emphasis remap='I'>buffer</emphasis> 590 </para> 591 </listitem> 592 </varlistentry> 593 <varlistentry> 594 <term> 595 <emphasis remap='I'>ret_len</emphasis> 596 </term> 597 <listitem> 598 <para> 599Specifies the length of stored data. 600 </para> 601 </listitem> 602 </varlistentry> 603</variablelist> 604 605<para> 606This function stores the read data in <emphasis remap='I'>read_buf</emphasis>, which size is 607specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to <emphasis remap='I'>ret_len</emphasis>. 608This function return True, if the data is read normally or reading 609data is completed. 610</para> 611<para> 612The Alternative Entry for this function is: 613</para> 614 615<funcsynopsis> 616<funcprototype> 617 <funcdef>Bool <function> _XimRead</function></funcdef> 618 <paramdef>XIM<parameter> im</parameter></paramdef> 619 <paramdef>INT16<parameter> *ret_len</parameter></paramdef> 620 <paramdef>XPointer<parameter> buf</parameter></paramdef> 621 <paramdef>int<parameter> buf_len</parameter></paramdef> 622 <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef> 623 <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef> 624</funcprototype> 625</funcsynopsis> 626 627<variablelist> 628 <varlistentry> 629 <term> 630 <emphasis remap='I'>im</emphasis> 631 </term> 632 <listitem> 633 <para> 634Specifies XIM structure address. 635 </para> 636 </listitem> 637 </varlistentry> 638 <varlistentry> 639 <term> 640 <emphasis remap='I'>ret_len</emphasis> 641 </term> 642 <listitem> 643 <para> 644Specifies the size of the <emphasis remap='I'>data</emphasis> buffer. 645 </para> 646 </listitem> 647 </varlistentry> 648 <varlistentry> 649 <term> 650 <emphasis remap='I'>buf</emphasis> 651 </term> 652 <listitem> 653 <para> 654Specifies the buffer to store data. 655 </para> 656 </listitem> 657 </varlistentry> 658 <varlistentry> 659 <term> 660 <emphasis remap='I'>buf_len</emphasis> 661 </term> 662 <listitem> 663 <para> 664Specifies the length of <emphasis remap='I'>buffer</emphasis>. 665 </para> 666 </listitem> 667 </varlistentry> 668 <varlistentry> 669 <term> 670 <emphasis remap='I'>predicate</emphasis> 671 </term> 672 <listitem> 673 <para> 674Specifies the predicate for the XIM data. 675 </para> 676 </listitem> 677 </varlistentry> 678 <varlistentry> 679 <term> 680 <emphasis remap='I'>predicate_arg</emphasis> 681 </term> 682 <listitem> 683 <para> 684Specifies the predicate specific data. 685<!-- .sp 6p --> 686 </para> 687 </listitem> 688 </varlistentry> 689</variablelist> 690 691<para> 692The predicate procedure indicates whether the <emphasis remap='I'>data</emphasis> is for the 693XIM or not. <emphasis remap='I'>len</emphasis> 694This function stores the read data in <emphasis remap='I'>buf</emphasis>, which size 695is specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to 696<emphasis remap='I'>ret_len</emphasis>. If <emphasis remap='I'>preedicate()</emphasis> 697returns True, this function returns True. If not, it calls the registered callback function. 698</para> 699 700<para> 701The procedure and its arguments are: 702</para> 703 704 705<funcsynopsis> 706<funcprototype> 707 <funcdef>void <function>(*predicate)</function></funcdef> 708 <paramdef>XIM<parameter> im</parameter></paramdef> 709 <paramdef>INT16<parameter> len</parameter></paramdef> 710 <paramdef>XPointer<parameter> data</parameter></paramdef> 711 <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef> 712</funcprototype> 713</funcsynopsis> 714 715<variablelist> 716 <varlistentry> 717 <term> 718 <emphasis remap='I'>im</emphasis> 719 </term> 720 <listitem> 721 <para> 722Specifies XIM structure address. 723 </para> 724 </listitem> 725 </varlistentry> 726 <varlistentry> 727 <term> 728 <emphasis remap='I'>len</emphasis> 729 </term> 730 <listitem> 731 <para> 732Specifies the size of the <emphasis remap='I'>data</emphasis> buffer. 733 </para> 734 </listitem> 735 </varlistentry> 736 <varlistentry> 737 <term> 738 <emphasis remap='I'>data</emphasis> 739 </term> 740 <listitem> 741 <para> 742Specifies the buffer to store data. 743 </para> 744 </listitem> 745 </varlistentry> 746 <varlistentry> 747 <term> 748 <emphasis remap='I'>predicate_arg</emphasis> 749 </term> 750 <listitem> 751 <para> 752Specifies the predicate specific data. 753 </para> 754 </listitem> 755 </varlistentry> 756</variablelist> 757 758</sect2> 759<sect2 id="Flushing_buffer"> 760<title>Flushing buffer</title> 761<para> 762The following function is called when Xlib needs to flush the data. 763</para> 764 765<funcsynopsis> 766<funcprototype> 767 <funcdef>void <function>(*flush)</function></funcdef> 768 <paramdef>XIM<parameter> im</parameter></paramdef> 769</funcprototype> 770</funcsynopsis> 771 772<variablelist> 773 <varlistentry> 774 <term> 775 <emphasis remap='I'>im</emphasis> 776 </term> 777 <listitem> 778 <para> 779Specifies XIM structure address. 780 </para> 781 </listitem> 782 </varlistentry> 783</variablelist> 784 785<para> 786This function must flush the data stored in internal buffer on the 787transport layer. If data transfer is completed, the function returns 788True. The Alternative Entry for this function is: 789</para> 790 791<funcsynopsis id='_ximflush'> 792<funcprototype> 793 <funcdef>void <function> _XimFlush</function></funcdef> 794 <paramdef>XIM<parameter> im</parameter></paramdef> 795</funcprototype> 796</funcsynopsis> 797 798<variablelist> 799 <varlistentry> 800 <term> 801 <emphasis remap='I'>im</emphasis> 802 </term> 803 <listitem> 804 <para> 805Specifies XIM structure address. 806 </para> 807 </listitem> 808 </varlistentry> 809</variablelist> 810 811</sect2> 812<sect2 id="Registering_asynchronous_data_handler"> 813<title>Registering asynchronous data handler</title> 814<para> 815Xlib needs to handle asynchronous response from IM Server. This is 816because some of the XIM data occur asynchronously to X events. 817</para> 818 819<para> 820Those data will be handled in the <emphasis remap='I'>Filter</emphasis>, 821and the <emphasis remap='I'>Filter</emphasis> 822will call asynchronous data handler in the protocol layer. Then it 823calls dispatchers in the transport layer. The dispatchers are 824implemented by the protocol layer. This function must store the 825information and prepare for later call of the dispatchers using 826<function>_XimCallDispatcher</function>. 827</para> 828 829<para> 830When multiple dispatchers are registered, they will be called 831sequentially in order of registration, on arrival of asynchronous 832data. The register_dispatcher is declared as following: 833</para> 834 835<funcsynopsis> 836<funcprototype> 837 <funcdef>Bool <function>(*register_dispatcher)</function></funcdef> 838 <paramdef>XIM<parameter> im</parameter></paramdef> 839 <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef> 840 <paramdef>XPointer<parameter> call_data</parameter></paramdef> 841</funcprototype> 842</funcsynopsis> 843 844<variablelist> 845 <varlistentry> 846 <term> 847 <emphasis remap='I'>im</emphasis> 848 </term> 849 <listitem> 850 <para> 851Specifies XIM structure address. 852 </para> 853 </listitem> 854 </varlistentry> 855 <varlistentry> 856 <term> 857 <emphasis remap='I'>dispatcher</emphasis> 858 </term> 859 <listitem> 860 <para> 861Specifies the dispatcher function to register. 862 </para> 863 </listitem> 864 </varlistentry> 865 <varlistentry> 866 <term> 867 <emphasis remap='I'>call_data</emphasis> 868 </term> 869 <listitem> 870 <para> 871Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>. 872 </para> 873 </listitem> 874 </varlistentry> 875</variablelist> 876 877<para> 878The dispatcher is a function of the following type: 879</para> 880 881<funcsynopsis> 882<funcprototype> 883 <funcdef>Bool <function>(*dispatcher)</function></funcdef> 884 <paramdef>XIM<parameter> im</parameter></paramdef> 885 <paramdef>INT16<parameter> len</parameter></paramdef> 886 <paramdef>XPointer<parameter> data</parameter></paramdef> 887 <paramdef>XPointer<parameter> call_data</parameter></paramdef> 888</funcprototype> 889</funcsynopsis> 890 891<variablelist> 892 <varlistentry> 893 <term> 894 <emphasis remap='I'>im</emphasis> 895 </term> 896 <listitem> 897 <para> 898Specifies XIM structure address. 899 </para> 900 </listitem> 901 </varlistentry> 902 <varlistentry> 903 <term> 904 <emphasis remap='I'>len</emphasis> 905 </term> 906 <listitem> 907 <para> 908Specifies the size of the <emphasis remap='I'>data</emphasis> buffer. 909 </para> 910 </listitem> 911 </varlistentry> 912 <varlistentry> 913 <term> 914 <emphasis remap='I'>data</emphasis> 915 </term> 916 <listitem> 917 <para> 918Specifies the buffer to store data. 919 </para> 920 </listitem> 921 </varlistentry> 922 <varlistentry> 923 <term> 924 <emphasis remap='I'>call_data</emphasis> 925 </term> 926 <listitem> 927 <para> 928Specifies a parameter passed to the register_dispatcher. 929 </para> 930 </listitem> 931 </varlistentry> 932</variablelist> 933 934<para> 935The dispatcher is provided by the protocol layer. They are called once 936for every asynchronous data, in order of registration. If the data is 937used, it must return True. otherwise, it must return False. 938</para> 939 940<para> 941If the dispatcher function returns True, the Transport Layer assume 942that the data has been processed by the upper layer. The Alternative 943Entry for this function is: 944</para> 945 946<funcsynopsis id='_ximregisterdispatcher'> 947<funcprototype> 948 <funcdef>Bool <function> _XimRegisterDispatcher</function></funcdef> 949 <paramdef>XIM<parameter> im</parameter></paramdef> 950 <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef> 951 <paramdef>XPointer<parameter> call_data</parameter></paramdef> 952</funcprototype> 953</funcsynopsis> 954 955<variablelist> 956 <varlistentry> 957 <term> 958 <emphasis remap='I'>im</emphasis> 959 </term> 960 <listitem> 961 <para> 962Specifies XIM structure address. 963 </para> 964 </listitem> 965 </varlistentry> 966 <varlistentry> 967 <term> 968 <emphasis remap='I'>dispatcher</emphasis> 969 </term> 970 <listitem> 971 <para> 972Specifies the dispatcher function to register. 973 </para> 974 </listitem> 975 </varlistentry> 976 <varlistentry> 977 <term> 978 <emphasis remap='I'>call_data</emphasis> 979 </term> 980 <listitem> 981 <para> 982Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>. 983 </para> 984 </listitem> 985 </varlistentry> 986</variablelist> 987 988</sect2> 989<sect2 id="Calling_dispatcher"> 990<title>Calling dispatcher</title> 991<para> 992The following function is used to call the registered dispatcher 993function, when the asynchronous response from IM Server has arrived. 994</para> 995 996<funcsynopsis> 997<funcprototype> 998 <funcdef>Bool <function>(*call_dispatcher)</function></funcdef> 999 <paramdef>XIM<parameter> im</parameter></paramdef> 1000 <paramdef>INT16<parameter> len</parameter></paramdef> 1001 <paramdef>XPointer<parameter> data</parameter></paramdef> 1002</funcprototype> 1003</funcsynopsis> 1004 1005<variablelist> 1006 <varlistentry> 1007 <term> 1008 <emphasis remap='I'>im</emphasis> 1009 </term> 1010 <listitem> 1011 <para> 1012Specifies XIM structure address. 1013 </para> 1014 </listitem> 1015 </varlistentry> 1016 <varlistentry> 1017 <term> 1018 <emphasis remap='I'>len</emphasis> 1019 </term> 1020 <listitem> 1021 <para> 1022Specifies the size of <emphasis remap='I'>data</emphasis> buffer. 1023 </para> 1024 </listitem> 1025 </varlistentry> 1026 <varlistentry> 1027 <term> 1028 <emphasis remap='I'>data</emphasis> 1029 </term> 1030 <listitem> 1031 <para> 1032Specifies the buffer to store data. 1033 </para> 1034 </listitem> 1035 </varlistentry> 1036</variablelist> 1037 1038<para> 1039The call_dispatcher must call the dispatcher function, in order of 1040their registration. <emphasis remap='I'>len</emphasis> and <emphasis remap='I'>data</emphasis> are the data passed to 1041register_dispatcher. 1042</para> 1043 1044<para> 1045The return values are checked at each invocation, and if it finds 1046True, it immediately return with true for its return value. 1047</para> 1048 1049<para> 1050It is depend on the upper layer whether the read data is XIM 1051Protocol packet unit or not. 1052The Alternative Entry for this function is: 1053</para> 1054 1055<funcsynopsis id='_ximcalldispatcher'> 1056<funcprototype> 1057 <funcdef>Bool <function> _XimCallDispatcher</function></funcdef> 1058 <paramdef>XIM<parameter> im</parameter></paramdef> 1059 <paramdef>INT16<parameter> len</parameter></paramdef> 1060 <paramdef>XPointer<parameter> call_data</parameter></paramdef> 1061</funcprototype> 1062</funcsynopsis> 1063 1064</sect2> 1065</sect1> 1066<sect1 id="Sample_implementations_for_the_Transport_Layer"> 1067<title>Sample implementations for the Transport Layer</title> 1068<para> 1069Sample implementations for the transporter using the X connection is 1070described here. 1071</para> 1072 1073<sect2 id="X_Transport"> 1074<title>X Transport</title> 1075<para> 1076At the beginning of the X Transport connection for the XIM transport 1077mechanism, two different windows must be created either in an Xlib XIM 1078or in an IM Server, with which the Xlib and the IM Server exchange the 1079XIM transports by using the ClientMessage events and Window Properties. 1080In the following, the window created by the Xlib is referred as the 1081"client communication window", and on the other hand, the window created 1082by the IM Server is referred as the "IMS communication window". 1083</para> 1084 1085<sect3 id="Connection"> 1086<title>Connection</title> 1087<para> 1088In order to establish a connection, a communication window is created. 1089A ClientMessage in the following event's format is sent to the owner 1090window of XIM_SERVER selection, which the IM Server has created. 1091</para> 1092 1093<para> 1094<!-- .LP --> 1095Refer to "The Input Method Protocol" for the XIM_SERVER atom. 1096</para> 1097 1098<table frame="none" id="transport_layer_functions"> 1099 <title>The ClientMessage sent to the IMS window.</title> 1100 <tgroup cols="3"> 1101 <colspec colname="col1" colwidth="1*" colsep="0"/> 1102 <colspec colname="col2" colwidth="1*" colsep="1"/> 1103 <colspec colname="col3" colwidth="3.5*" colsep="0"/> 1104 <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> 1105 <thead> 1106 <row> 1107 <entry align="left" spanname="span-horiz">Structure Member</entry> 1108 <entry align="left">Contents</entry> 1109 </row> 1110 </thead> 1111 <tbody> 1112 <row rowsep="0"> 1113 <entry>int</entry> 1114 <entry>type</entry> 1115 <entry>ClientMessage</entry> 1116 </row> 1117 <row rowsep="0"> 1118 <entry>u_long</entry> 1119 <entry>serial</entry> 1120 <entry>Set by the X Window System</entry> 1121 </row> 1122 <row rowsep="0"> 1123 <entry>Bool</entry> 1124 <entry>send_event</entry> 1125 <entry>Set by the X Window System</entry> 1126 </row> 1127 <row rowsep="0"> 1128 <entry>Display</entry> 1129 <entry>*display</entry> 1130 <entry>The display to which connects</entry> 1131 </row> 1132 <row rowsep="0"> 1133 <entry>Window</entry> 1134 <entry>window</entry> 1135 <entry>IMS Window ID</entry> 1136 </row> 1137 <row rowsep="0"> 1138 <entry>Atom</entry> 1139 <entry>message_type</entry> 1140 <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry> 1141 </row> 1142 <row rowsep="0"> 1143 <entry>int</entry> 1144 <entry>format</entry> 1145 <entry>32</entry> 1146 </row> 1147 <row rowsep="0"> 1148 <entry>long</entry> 1149 <entry>data.1[0]</entry> 1150 <entry>client communication window ID</entry> 1151 </row> 1152 <row rowsep="0"> 1153 <entry>long</entry> 1154 <entry>data.1[1]</entry> 1155 <entry>client-major-transport-version(*1)</entry> 1156 </row> 1157 <row rowsep="0"> 1158 <entry>long</entry> 1159 <entry>data.1[2]</entry> 1160 <entry>client-major-transport-version(*1)</entry> 1161 </row> 1162 </tbody> 1163 </tgroup> 1164</table> 1165 1166<para> 1167In order to establish the connection (to notify the IM Server communication 1168window), the IM Server sends a ClientMessage in the following event's 1169format to the client communication window. 1170</para> 1171 1172<table frame="none" id="clientmessage_sent_by_im_server"> 1173 <title>The ClientMessage sent by IM Server.</title> 1174 <tgroup cols="3"> 1175 <colspec colname="col1" colwidth="1*" colsep="0"/> 1176 <colspec colname="col2" colwidth="1*" colsep="1"/> 1177 <colspec colname="col3" colwidth="3.5*" colsep="0"/> 1178 <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> 1179 <thead> 1180 <row> 1181 <entry align="left" spanname="span-horiz">Structure Member</entry> 1182 <entry align="left">Contents</entry> 1183 </row> 1184 </thead> 1185 <tbody> 1186 <row rowsep="0"> 1187 <entry>int</entry> 1188 <entry>type</entry> 1189 <entry>ClientMessage</entry> 1190 </row> 1191 <row rowsep="0"> 1192 <entry>u_long</entry> 1193 <entry>serial</entry> 1194 <entry>Set by the X Window System</entry> 1195 </row> 1196 <row rowsep="0"> 1197 <entry>Bool</entry> 1198 <entry>send_event</entry> 1199 <entry>Set by the X Window System</entry> 1200 </row> 1201 <row rowsep="0"> 1202 <entry>Display</entry> 1203 <entry>*display</entry> 1204 <entry>The display to which connects</entry> 1205 </row> 1206 <row rowsep="0"> 1207 <entry>Window</entry> 1208 <entry>window</entry> 1209 <entry>IMS Window ID</entry> 1210 </row> 1211 <row rowsep="0"> 1212 <entry>Atom</entry> 1213 <entry>message_type</entry> 1214 <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry> 1215 </row> 1216 <row rowsep="0"> 1217 <entry>int</entry> 1218 <entry>format</entry> 1219 <entry>32</entry> 1220 </row> 1221 <row rowsep="0"> 1222 <entry>long</entry> 1223 <entry>data.1[0]</entry> 1224 <entry>client communication window ID</entry> 1225 </row> 1226 <row rowsep="0"> 1227 <entry>long</entry> 1228 <entry>data.1[1]</entry> 1229 <entry>client-major-transport-version(*1)</entry> 1230 </row> 1231 <row rowsep="0"> 1232 <entry>long</entry> 1233 <entry>data.1[2]</entry> 1234 <entry>client-major-transport-version(*1)</entry> 1235 </row> 1236 <row rowsep="0"> 1237 <entry>long</entry> 1238 <entry>data.1[3]</entry> 1239 <entry>dividing size between ClientMessage and Property(*2)</entry> 1240 </row> 1241 </tbody> 1242 </tgroup> 1243</table> 1244 1245<para> 1246(*1) major/minor-transport-version 1247</para> 1248 1249<para> 1250The read/write method is decided by the combination of 1251major/minor-transport-version, as follows: 1252</para> 1253 1254<table frame="all" id="readwrite_method_and_the_majorminor_transport_version"> 1255<title>The read/write method and the major/minor-transport-version</title> 1256 <tgroup cols="3"> 1257 <colspec colname="col1" colwidth="1*" colsep="1"/> 1258 <colspec colname="col2" colwidth="1*" colsep="1"/> 1259 <colspec colname="col3" colwidth="3*" colsep="1"/> 1260 <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/> 1261 <thead> 1262 <row> 1263 <entry spanname="span-horiz">Transport-version</entry> 1264 <entry>read/write</entry> 1265 </row> 1266 <row> 1267 <entry>major</entry> 1268 <entry>minor</entry> 1269 <entry></entry> 1270 </row> 1271 </thead> 1272 <tbody> 1273 <row rowsep="0"> 1274 <entry morerows="2">0</entry> 1275 <entry>0</entry> 1276 <entry>only-CM & Property-with-CM</entry> 1277 </row> 1278 <row rowsep="0"> 1279 <entry>1</entry> 1280 <entry>only-CM & multi-CM</entry> 1281 </row> 1282 <row rowsep="1"> 1283 <entry>2</entry> 1284 <entry>only-CM & multi-CM & Property-with-CM</entry> 1285 </row> 1286 <row rowsep="1"> 1287 <entry>1</entry> 1288 <entry>0</entry> 1289 <entry>PropertyNotify</entry> 1290 </row> 1291 <row rowsep="0"> 1292 <entry morerows="1">2</entry> 1293 <entry>0</entry> 1294 <entry>only-CM & PropertyNotify</entry> 1295 </row> 1296 <row> 1297 <entry>1</entry> 1298 <entry>only-CM & multi-CM & PropertyNotify</entry> 1299 </row> 1300 </tbody> 1301 </tgroup> 1302</table> 1303 1304<literallayout class="monospaced"> 1305only-CM : data is sent via a ClientMessage 1306multi-CM : data is sent via multiple ClientMessages 1307Property-with-CM : data is written in Property, and its Atom 1308 is send via ClientMessage 1309PropertyNotify : data is written in Property, and its Atom 1310 is send via PropertyNotify 1311 1312</literallayout> 1313 1314 1315<para> 1316The method to decide major/minor-transport-version is as follows: 1317</para> 1318 1319<itemizedlist> 1320 <listitem> 1321 <para> 1322The client sends 0 as major/minor-transport-version to the IM Server. 1323The client must support all methods in Table 4-3. <!-- xref --> 1324The client may send another number as major/minor-transport-version to 1325use other method than the above in the future. 1326 </para> 1327 </listitem> 1328 <listitem> 1329 <para> 1330The IM Server sends its major/minor-transport-version number to 1331the client. The client sends data using the method specified by the 1332IM Server. 1333 </para> 1334 </listitem> 1335 <listitem> 1336 <para> 1337If major/minor-transport-version number is not available, it is regarded 1338as 0. 1339 </para> 1340 </listitem> 1341</itemizedlist> 1342 1343<para> 1344(*2) dividing size between ClientMessage and Property 1345</para> 1346 1347<para> 1348If data is sent via both of multi-CM and Property, specify the dividing 1349size between ClientMessage and Property. The data, which is smaller than 1350this size, is sent via multi-CM (or only-CM), and the data, which is 1351lager than this size, is sent via Property. 1352</para> 1353 1354</sect3> 1355 1356<sect3 id="read_write_"> 1357<title>read/write </title> 1358<para> 1359The data is transferred via either ClientMessage or Window Property in 1360the X Window System. 1361</para> 1362 1363<sect4 id="Format_for_the_data_from_the_Client_to_the_IM_Server"> 1364<title>Format for the data from the Client to the IM Server</title> 1365<para> 1366<emphasis role="bold">ClientMessage</emphasis> 1367</para> 1368 1369<para> 1370If data is sent via ClientMessage event, the format is as follows: 1371</para> 1372 1373<table frame="none" id="clientmessage_events_format_first_or_middle"> 1374 <title>The ClientMessage event's format (first or middle)</title> 1375 <tgroup cols="3"> 1376 <colspec colname="col1" colwidth="1*" colsep="0"/> 1377 <colspec colname="col2" colwidth="1*" colsep="1"/> 1378 <colspec colname="col3" colwidth="3.5*" colsep="0"/> 1379 <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> 1380 <thead> 1381 <row> 1382 <entry align="left" spanname="span-horiz">Structure Member</entry> 1383 <entry align="left">Contents</entry> 1384 </row> 1385 </thead> 1386 <tbody> 1387 <row rowsep="0"> 1388 <entry>int</entry> 1389 <entry>type</entry> 1390 <entry>ClientMessage</entry> 1391 </row> 1392 <row rowsep="0"> 1393 <entry>u_long</entry> 1394 <entry>serial</entry> 1395 <entry>Set by the X Window System</entry> 1396 </row> 1397 <row rowsep="0"> 1398 <entry>Bool</entry> 1399 <entry>send_event</entry> 1400 <entry>Set by the X Window System</entry> 1401 </row> 1402 <row rowsep="0"> 1403 <entry>Display</entry> 1404 <entry>*display</entry> 1405 <entry>The display to which connects</entry> 1406 </row> 1407 <row rowsep="0"> 1408 <entry>Window</entry> 1409 <entry>window</entry> 1410 <entry>IMS Window ID</entry> 1411 </row> 1412 <row rowsep="0"> 1413 <entry>Atom</entry> 1414 <entry>message_type</entry> 1415 <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry> 1416 </row> 1417 <row rowsep="0"> 1418 <entry>int</entry> 1419 <entry>format</entry> 1420 <entry>8</entry> 1421 </row> 1422 <row rowsep="0"> 1423 <entry>char</entry> 1424 <entry>data.b[20]</entry> 1425 <entry>(read/write DATA : 20 byte)</entry> 1426 </row> 1427 </tbody> 1428 </tgroup> 1429</table> 1430 1431 1432 1433<table frame="none" id="clientmessage_events_format_only_or_last"> 1434 <title>The ClientMessage event's format (only or last)</title> 1435 <tgroup cols="3"> 1436 <colspec colname="col1" colwidth="1*" colsep="0"/> 1437 <colspec colname="col2" colwidth="1*" colsep="1"/> 1438 <colspec colname="col3" colwidth="3.5*" colsep="0"/> 1439 <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> 1440 <thead> 1441 <row> 1442 <entry align="left" spanname="span-horiz">Structure Member</entry> 1443 <entry align="left">Contents</entry> 1444 </row> 1445 </thead> 1446 <tbody> 1447 <row rowsep="0"> 1448 <entry>int</entry> 1449 <entry>type</entry> 1450 <entry>ClientMessage</entry> 1451 </row> 1452 <row rowsep="0"> 1453 <entry>u_long</entry> 1454 <entry>serial</entry> 1455 <entry>Set by the X Window System</entry> 1456 </row> 1457 <row rowsep="0"> 1458 <entry>Bool</entry> 1459 <entry>send_event</entry> 1460 <entry>Set by the X Window System</entry> 1461 </row> 1462 <row rowsep="0"> 1463 <entry>Display</entry> 1464 <entry>*display</entry> 1465 <entry>The display to which connects</entry> 1466 </row> 1467 <row rowsep="0"> 1468 <entry>Window</entry> 1469 <entry>window</entry> 1470 <entry>IMS Window ID</entry> 1471 </row> 1472 <row rowsep="0"> 1473 <entry>Atom</entry> 1474 <entry>message_type</entry> 1475 <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> 1476 </row> 1477 <row rowsep="0"> 1478 <entry>int</entry> 1479 <entry>format</entry> 1480 <entry>8</entry> 1481 </row> 1482 <row rowsep="0"> 1483 <entry>char</entry> 1484 <entry>data.b[20]</entry> 1485 <entry>(read/write DATA : MAX 20 byte) 1486<footnote><para>If the data is smaller 1487than 20 bytes, all data other than available data must be 0. 1488</para></footnote> 1489 </entry> 1490 </row> 1491 </tbody> 1492 </tgroup> 1493</table> 1494 1495<para> 1496<emphasis role="bold">Property</emphasis> 1497</para> 1498 1499<para> 1500In the case of large data, data will be sent via the Window Property 1501for the efficiency. There are the following two methods to notify 1502Property, and transport-version is decided which method is used. 1503</para> 1504 1505<itemizedlist> 1506 <listitem> 1507 <para> 1508The XChangeProperty function is used to store data in the client 1509communication window, and Atom of the stored data is notified to the 1510IM Server via ClientMessage event. 1511 </para> 1512 </listitem> 1513 <listitem> 1514 <para> 1515The XChangeProperty function is used to store data in the client 1516communication window, and Atom of the stored data is notified to the 1517IM Server via PropertyNotify event. 1518 </para> 1519 </listitem> 1520</itemizedlist> 1521 1522<para> 1523The arguments of the XChangeProperty are as follows: 1524</para> 1525 1526 1527<table frame="none" id="xchangeproperty_events_format"> 1528 <title>The XChangeProperty event's format</title> 1529 <tgroup cols="3"> 1530 <colspec colname="col1" colwidth="1*" colsep="0"/> 1531 <colspec colname="col2" colwidth="1*" colsep="1"/> 1532 <colspec colname="col3" colwidth="3.5*" colsep="0"/> 1533 <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> 1534 <thead> 1535 <row> 1536 <entry align="left" spanname="span-horiz">Argument</entry> 1537 <entry align="left">Contents</entry> 1538 </row> 1539 </thead> 1540 <tbody> 1541 <row rowsep="0"> 1542 <entry>Display</entry> 1543 <entry>*display</entry> 1544 <entry>The display to which connects</entry> 1545 </row> 1546 <row rowsep="0"> 1547 <entry>Window</entry> 1548 <entry>window</entry> 1549 <entry>IMS communication window ID</entry> 1550 </row> 1551 <row rowsep="0"> 1552 <entry>Atom</entry> 1553 <entry>property</entry> 1554 <entry>read/write property Atom (*1)</entry> 1555 </row> 1556 <row rowsep="0"> 1557 <entry>int</entry> 1558 <entry>format</entry> 1559 <entry>8</entry> 1560 </row> 1561 <row rowsep="0"> 1562 <entry>int</entry> 1563 <entry>mode</entry> 1564 <entry>PropModeAppend</entry> 1565 </row> 1566 <row rowsep="0"> 1567 <entry>u_char</entry> 1568 <entry>*data</entry> 1569 <entry>read/write DATA</entry> 1570 </row> 1571 <row rowsep="0"> 1572 <entry>int</entry> 1573 <entry>nelements</entry> 1574 <entry>length of DATA</entry> 1575 </row> 1576 </tbody> 1577 </tgroup> 1578</table> 1579 1580<para> 1581(*1) The read/write property ATOM allocates the following strings by 1582<function>XInternAtom</function>. 1583"_clientXXX" 1584</para> 1585 1586<para> 1587The client changes the property with the mode of PropModeAppend and 1588the IM Server will read it with the delete mode i.e. (delete = True). 1589</para> 1590 1591<para> 1592If Atom is notified via ClientMessage event, the format of the ClientMessage 1593is as follows: 1594</para> 1595 1596<table frame="none" id="clientmessage_events_format_to_send_atom_of_property"> 1597 <title>The ClientMessage event's format to send Atom of property</title> 1598 <tgroup cols="3"> 1599 <colspec colname="col1" colwidth="1*" colsep="0"/> 1600 <colspec colname="col2" colwidth="1*" colsep="1"/> 1601 <colspec colname="col3" colwidth="3.5*" colsep="0"/> 1602 <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> 1603 <thead> 1604 <row> 1605 <entry align="left" spanname="span-horiz">Structure Member</entry> 1606 <entry align="left">Contents</entry> 1607 </row> 1608 </thead> 1609 <tbody> 1610 <row rowsep="0"> 1611 <entry>int</entry> 1612 <entry>type</entry> 1613 <entry>ClientMessage</entry> 1614 </row> 1615 <row rowsep="0"> 1616 <entry>u_long</entry> 1617 <entry>serial</entry> 1618 <entry>Set by the X Window System</entry> 1619 </row> 1620 <row rowsep="0"> 1621 <entry>Bool</entry> 1622 <entry>send_event</entry> 1623 <entry>Set by the X Window System</entry> 1624 </row> 1625 <row rowsep="0"> 1626 <entry>Display</entry> 1627 <entry>*display</entry> 1628 <entry>The display to which connects</entry> 1629 </row> 1630 <row rowsep="0"> 1631 <entry>Window</entry> 1632 <entry>window</entry> 1633 <entry>IMS Window ID</entry> 1634 </row> 1635 <row rowsep="0"> 1636 <entry>Atom</entry> 1637 <entry>message_type</entry> 1638 <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> 1639 </row> 1640 <row rowsep="0"> 1641 <entry>int</entry> 1642 <entry>format</entry> 1643 <entry>8</entry> 1644 </row> 1645 <row rowsep="0"> 1646 <entry>long</entry> 1647 <entry>data.1[0]</entry> 1648 <entry>length of read/write property Atom</entry> 1649 </row> 1650 <row rowsep="0"> 1651 <entry>long</entry> 1652 <entry>data.1[1]</entry> 1653 <entry>read/write property Atom</entry> 1654 </row> 1655 </tbody> 1656 </tgroup> 1657</table> 1658</sect4> 1659 1660<sect4 id="Format_for_the_data_from_the_IM_Server_to_the_Client"> 1661<title>Format for the data from the IM Server to the Client</title> 1662<para> 1663<emphasis role="bold">ClientMessage</emphasis> 1664</para> 1665 1666<para> 1667The format of the ClientMessage is as follows: 1668</para> 1669 1670<table frame="none" id="clientmessage_events_format_first_or_middle_2"> 1671 <title>The ClientMessage event's format (first or middle)</title> 1672 <tgroup cols="3"> 1673 <colspec colname="col1" colwidth="1*" colsep="0"/> 1674 <colspec colname="col2" colwidth="1*" colsep="1"/> 1675 <colspec colname="col3" colwidth="3.5*" colsep="0"/> 1676 <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> 1677 <thead> 1678 <row> 1679 <entry align="left" spanname="span-horiz">Structure Member</entry> 1680 <entry align="left">Contents</entry> 1681 </row> 1682 </thead> 1683 <tbody> 1684 <row rowsep="0"> 1685 <entry>int</entry> 1686 <entry>type</entry> 1687 <entry>ClientMessage</entry> 1688 </row> 1689 <row rowsep="0"> 1690 <entry>u_long</entry> 1691 <entry>serial</entry> 1692 <entry>Set by the X Window System</entry> 1693 </row> 1694 <row rowsep="0"> 1695 <entry>Bool</entry> 1696 <entry>send_event</entry> 1697 <entry>Set by the X Window System</entry> 1698 </row> 1699 <row rowsep="0"> 1700 <entry>Display</entry> 1701 <entry>*display</entry> 1702 <entry>The display to which connects</entry> 1703 </row> 1704 <row rowsep="0"> 1705 <entry>Window</entry> 1706 <entry>window</entry> 1707 <entry>IMS Window ID</entry> 1708 </row> 1709 <row rowsep="0"> 1710 <entry>Atom</entry> 1711 <entry>message_type</entry> 1712 <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry> 1713 </row> 1714 <row rowsep="0"> 1715 <entry>int</entry> 1716 <entry>format</entry> 1717 <entry>8</entry> 1718 </row> 1719 <row rowsep="0"> 1720 <entry>char</entry> 1721 <entry>data.b[20]</entry> 1722 <entry>(read/write DATA : 20 byte)</entry> 1723 </row> 1724 </tbody> 1725 </tgroup> 1726</table> 1727 1728 1729 1730 1731 1732<table frame="none" id="clientmessage_events_format_only_or_last_2"> 1733 <title>The ClientMessage event's format (only or last)</title> 1734 <tgroup cols="3"> 1735 <colspec colname="col1" colwidth="1*" colsep="0"/> 1736 <colspec colname="col2" colwidth="1*" colsep="1"/> 1737 <colspec colname="col3" colwidth="3.5*" colsep="0"/> 1738 <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> 1739 <thead> 1740 <row> 1741 <entry align="left" spanname="span-horiz">Structure Member</entry> 1742 <entry align="left">Contents</entry> 1743 </row> 1744 </thead> 1745 <tbody> 1746 <row rowsep="0"> 1747 <entry>int</entry> 1748 <entry>type</entry> 1749 <entry>ClientMessage</entry> 1750 </row> 1751 <row rowsep="0"> 1752 <entry>u_long</entry> 1753 <entry>serial</entry> 1754 <entry>Set by the X Window System</entry> 1755 </row> 1756 <row rowsep="0"> 1757 <entry>Bool</entry> 1758 <entry>send_event</entry> 1759 <entry>Set by the X Window System</entry> 1760 </row> 1761 <row rowsep="0"> 1762 <entry>Display</entry> 1763 <entry>*display</entry> 1764 <entry>The display to which connects</entry> 1765 </row> 1766 <row rowsep="0"> 1767 <entry>Window</entry> 1768 <entry>window</entry> 1769 <entry>IMS Window ID</entry> 1770 </row> 1771 <row rowsep="0"> 1772 <entry>Atom</entry> 1773 <entry>message_type</entry> 1774 <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> 1775 </row> 1776 <row rowsep="0"> 1777 <entry>int</entry> 1778 <entry>format</entry> 1779 <entry>8</entry> 1780 </row> 1781 <row rowsep="0"> 1782 <entry>char</entry> 1783 <entry>data.b[20]</entry> 1784 <entry>(read/write DATA : MAX 20 byte) (*1)</entry> 1785 </row> 1786 </tbody> 1787 </tgroup> 1788</table> 1789 1790<para> 1791(*1) If the data size is smaller than 20 bytes, all data other than available 1792data must be 0. 1793</para> 1794 1795<para> 1796<emphasis role="bold">Property</emphasis> 1797</para> 1798 1799<para> 1800In the case of large data, data will be sent via the Window Property 1801for the efficiency. There are the following two methods to notify 1802Property, and transport-version is decided which method is used. 1803</para> 1804 1805<itemizedlist> 1806 <listitem> 1807 <para> 1808The XChangeProperty function is used to store data in the IMS 1809communication window, and Atom of the property is sent via the 1810ClientMessage event. 1811 </para> 1812 </listitem> 1813 <listitem> 1814 <para> 1815The XChangeProperty function is used to store data in the IMS 1816communication window, and Atom of the property is sent via 1817PropertyNotify event. 1818 </para> 1819 </listitem> 1820</itemizedlist> 1821 1822<para> 1823The arguments of the XChangeProperty are as follows: 1824</para> 1825 1826<table frame="none" id="xchangeproperty_events_format_b"> 1827 <title>The XChangeProperty event's format</title> 1828 <tgroup cols="3"> 1829 <colspec colname="col1" colwidth="1*" colsep="0"/> 1830 <colspec colname="col2" colwidth="1*" colsep="1"/> 1831 <colspec colname="col3" colwidth="3.5*" colsep="0"/> 1832 <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> 1833 <thead> 1834 <row> 1835 <entry align="left" spanname="span-horiz">Argument</entry> 1836 <entry align="left">Contents</entry> 1837 </row> 1838 </thead> 1839 <tbody> 1840 <row rowsep="0"> 1841 <entry>Display</entry> 1842 <entry>*display</entry> 1843 <entry>The display to which connects</entry> 1844 </row> 1845 <row rowsep="0"> 1846 <entry>Window</entry> 1847 <entry>window</entry> 1848 <entry>IMS communication window ID</entry> 1849 </row> 1850 <row rowsep="0"> 1851 <entry>Atom</entry> 1852 <entry>property</entry> 1853 <entry>read/write property Atom (*1)</entry> 1854 </row> 1855 <row rowsep="0"> 1856 <entry>int</entry> 1857 <entry>format</entry> 1858 <entry>8</entry> 1859 </row> 1860 <row rowsep="0"> 1861 <entry>int</entry> 1862 <entry>mode</entry> 1863 <entry>PropModeAppend</entry> 1864 </row> 1865 <row rowsep="0"> 1866 <entry>u_char</entry> 1867 <entry>*data</entry> 1868 <entry>read/write DATA</entry> 1869 </row> 1870 <row rowsep="0"> 1871 <entry>int</entry> 1872 <entry>nelements</entry> 1873 <entry>length of DATA</entry> 1874 </row> 1875 </tbody> 1876 </tgroup> 1877</table> 1878 1879<para> 1880(*1) The read/write property ATOM allocates some strings, which are not 1881allocated by the client, by <function>XInternAtom</function>. 1882</para> 1883 1884<para> 1885The IM Server changes the property with the mode of PropModeAppend and 1886the client reads it with the delete mode, i.e. (delete = True). 1887</para> 1888 1889<para> 1890If Atom is notified via ClientMessage event, the format of the ClientMessage 1891is as follows: 1892</para> 1893 1894<table frame="none" id="clientmessage_events_format_to_send_atom_of_property_2"> 1895 <title>The ClientMessage event's format to send Atom of property</title> 1896 <tgroup cols="3"> 1897 <colspec colname="col1" colwidth="1*" colsep="0"/> 1898 <colspec colname="col2" colwidth="1*" colsep="1"/> 1899 <colspec colname="col3" colwidth="3.5*" colsep="0"/> 1900 <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> 1901 <thead> 1902 <row> 1903 <entry align="left" spanname="span-horiz">Structure Member</entry> 1904 <entry align="left">Contents</entry> 1905 </row> 1906 </thead> 1907 <tbody> 1908 <row rowsep="0"> 1909 <entry>int</entry> 1910 <entry>type</entry> 1911 <entry>ClientMessage</entry> 1912 </row> 1913 <row rowsep="0"> 1914 <entry>u_long</entry> 1915 <entry>serial</entry> 1916 <entry>Set by the X Window System</entry> 1917 </row> 1918 <row rowsep="0"> 1919 <entry>Bool</entry> 1920 <entry>send_event</entry> 1921 <entry>Set by the X Window System</entry> 1922 </row> 1923 <row rowsep="0"> 1924 <entry>Display</entry> 1925 <entry>*display</entry> 1926 <entry>The display to which connects</entry> 1927 </row> 1928 <row rowsep="0"> 1929 <entry>Window</entry> 1930 <entry>window</entry> 1931 <entry>IMS Window ID</entry> 1932 </row> 1933 <row rowsep="0"> 1934 <entry>Atom</entry> 1935 <entry>message_type</entry> 1936 <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> 1937 </row> 1938 <row rowsep="0"> 1939 <entry>int</entry> 1940 <entry>format</entry> 1941 <entry>8</entry> 1942 </row> 1943 <row rowsep="0"> 1944 <entry>long</entry> 1945 <entry>data.1[0]</entry> 1946 <entry>length of read/write property Atom</entry> 1947 </row> 1948 <row rowsep="0"> 1949 <entry>long</entry> 1950 <entry>data.1[1]</entry> 1951 <entry>read/write property Atom</entry> 1952 </row> 1953 </tbody> 1954 </tgroup> 1955</table> 1956 1957</sect4> 1958</sect3> 1959<sect3 id="Closing_Connection"> 1960<title>Closing Connection</title> 1961 1962<para> 1963If the client disconnect with the IM Server, shutdown function should 1964free the communication window properties and etc.. 1965</para> 1966 1967</sect3> 1968</sect2> 1969</sect1> 1970 1971<sect1 id="References"> 1972<title>References</title> 1973<para> 1974[1] Masahiko Narita and Hideki Hiura, <emphasis remap='I'>"The Input Method Protocol"</emphasis> 1975</para> 1976</sect1> 1977 1978</chapter> 1979</book> 1980