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