home *** CD-ROM | disk | FTP | other *** search
/ Chip 2001 August - Disc 2 / chip_20018102_hu.iso / linux / X-4.1.0 / doc / XIMTransport.TXT < prev    next >
Text File  |  2001-06-27  |  29KB  |  1,255 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.           The XIM Transport Specification
  20.  
  21.  
  22.             Revision 0.1
  23.  
  24.          X Version 11, Release 6.4
  25.  
  26.  
  27.  
  28.  
  29.               Takashi Fujiwara
  30.               FUJITSU LIMITED
  31.  
  32.  
  33.  
  34.  
  35.  
  36.               ABSTRACT
  37.  
  38.  
  39.  
  40.      This specification describes the transport layer
  41.      interfaces between Xlib and IM Server, which makes
  42.      various channels usable such as X protocol or,
  43.      TCP/IP, DECnet and etc.
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83. Copyright (C) 1994 by FUJITSU LIMITED
  84.  
  85. Permission to use, copy, modify, and distribute this docu-
  86. mentation for any purpose and without fee is hereby granted,
  87. provided that the above copyright notice and this permission
  88. notice appear in all copies.  Fujitsu makes no representa-
  89. tions about the suitability for any purpose of the informa-
  90. tion in this document.    This documentation is provided as is
  91. without express or implied warranty.
  92.  
  93.  
  94.  
  95.  
  96.  
  97. Copyright (C) 1994 X Consortium
  98.  
  99. Permission is hereby granted, free of charge, to any person
  100. obtaining a copy of this software and associated documenta-
  101. tion files (the ``Software''), to deal in the Software with-
  102. out restriction, including without limitation the rights to
  103. use, copy, modify, merge, publish, distribute, sublicense,
  104. and/or sell copies of the Software, and to permit persons to
  105. whom the Software is furnished to do so, subject to the fol-
  106. lowing conditions:
  107.  
  108. The above copyright notice and this permission notice shall
  109. be included in all copies or substantial portions of the
  110. Software.
  111.  
  112. THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY
  113. KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  114. WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR-
  115. POSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR-
  116. TIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  117. WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  118. FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
  119. OR OTHER DEALINGS IN THE SOFTWARE.
  120.  
  121. Except as contained in this notice, the name of the X Con-
  122. sortium shall not be used in advertising or otherwise to
  123. promote the sale, use or other dealings in this Software
  124. without prior written authorization from the X Consortium.
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. X Window System is a trademark of X Consortium, Inc.
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205. 1.  Introduction
  206.  
  207. The Xlib XIM implementation is layered into three functions,
  208. a protocol layer, an interface layer and a transport layer.
  209. The purpose of this layering is to make the protocol inde-
  210. pendent of transport implementation.  Each function of these
  211. layers are:
  212.  
  213.      The protocol layer
  214.       implements overall function of XIM and calls the
  215.       interface layer functions when it needs to commu-
  216.       nicate to IM Server.
  217.  
  218.      The interface layer
  219.       separates the implementation of the transport
  220.       layer from the protocol layer, in other words, it
  221.       provides implementation independent hook for the
  222.       transport layer functions.
  223.  
  224.      The transport layer
  225.       handles actual data communication with IM Server.
  226.       It is done by a set of several functions named
  227.       transporters.
  228.  
  229. This specification describes the interface layer and the
  230. transport layer, which makes various communication channels
  231. usable such as X protocol or, TCP/IP, DECnet, STREAM, etc.,
  232. and provides the information needed for adding another new
  233. transport layer.  In addition, sample implementations for
  234. the transporter using the X connection is described in sec-
  235. tion 4.
  236.  
  237. 2.  Initialization
  238.  
  239. 2.1.  Registering structure to initialize
  240.  
  241. The structure typed as TransportSW contains the list of the
  242. transport layer the specific implementations supports.
  243.  
  244.  
  245. typedef struct {
  246.       char *transport_name;
  247.       Bool (*config);
  248. } TransportSW;
  249.  
  250.  
  251.  
  252. transport_name name of transport(*1)
  253.  
  254. config           initial configuration function
  255.  
  256. -----------
  257. (*1) Refer to "The Input Method Protocol: Appendix
  258. B"
  259.  
  260.  
  261.  
  262.                   1
  263.  
  264.  
  265.  
  266.  
  267.  
  268. XIM Transport Specification            X11, Release 6.4
  269.  
  270.  
  271. A sample entry for the Xlib supporting transporters is shown
  272. below:
  273.  
  274.  
  275. TransportSW _XimTransportRec[] = {
  276. /*   char *:
  277.  *   transport_name,     Bool (*config)()
  278.  */
  279.      ``X'',         _XimXConf,
  280.      ``tcp'',         _XimTransConf,
  281.      ``local'',      _XimTransConf,
  282.      ``decnet'',     _XimTransConf,
  283.      ``streams'',     _XimTransConf,
  284.      (char *)NULL,     (Bool (*)())NULL,
  285. };
  286.  
  287.  
  288.  
  289. 2.2.  Initialization function
  290.  
  291. The following function will be called once when Xlib config-
  292. ures the transporter functions.
  293.  
  294. Bool (*config)(im, transport_data)
  295.       XIM im;
  296.       char *transport_data;
  297.  
  298.  
  299. im      Specifies XIM structure address.
  300.  
  301. transport_data
  302.       Specifies the data specific to the transporter, in
  303.       IM Server address. (*1)
  304.  
  305. This function must setup the transporter function pointers.
  306.  
  307. The actual config function will be chosen by IM Server at
  308. the pre-connection time, matching by the transport_name
  309. specified in the _XimTransportRec array; The specific mem-
  310. bers of XimProto structure listed below must be initialized
  311. so that point they appropriate transporter functions.
  312.  
  313. If the specified transporter has been configured success-
  314. fully, this function returns True. There is no Alternative
  315. Entry for config function itself.
  316.  
  317. The structure XimProto contains the following function
  318. pointers:
  319.  
  320.  
  321.  
  322. -----------
  323. (*1) Refer to "The Input Method Protocol: Appendix
  324. B"
  325.  
  326.  
  327.  
  328.                   2
  329.  
  330.  
  331.  
  332.  
  333.  
  334. XIM Transport Specification            X11, Release 6.4
  335.  
  336.  
  337.      Bool (*connect)();       /* Open connection */
  338.      Bool (*shutdown)();      /* Close connection */
  339.      Bool (*write)();          /* Write data */
  340.      Bool (*read)();          /* Read data */
  341.      Bool (*flush)();          /* Flush data buffer */
  342.      Bool (*register_dispatcher)();/* Register asynchronous data handler */
  343.      Bool (*call_dispatcher)();/* Call dispatcher */
  344.  
  345. These functions are called when Xlib needs to communicate
  346. the IM Server. These functions must process the appropriate
  347. procedure described below.
  348.  
  349.  
  350. 3.  The interface/transport layer functions
  351.  
  352. Following functions are used for the transport interface.
  353.  
  354.      Table 3-1; The Transport Layer Functions.
  355.  
  356.  +-----------------------+---------------------+----------+
  357.  |  Alternative Entry     |   XimProto member   | Section  |
  358.  |  (Interface Layer)     |  (Transport Layer)  |      |
  359.  +-----------------------+---------------------+----------+
  360.  |_XimConnect         | connect           |   3.1      |
  361.  +-----------------------+---------------------+----------+
  362.  |_XimShutdown         | shutdown           |   3.2      |
  363.  +-----------------------+---------------------+----------+
  364.  |_XimWrite         | write           |   3.3      |
  365.  +-----------------------+---------------------+----------+
  366.  |_XimRead         | read            |   3.4      |
  367.  +-----------------------+---------------------+----------+
  368.  |_XimFlush         | flush           |   3.5      |
  369.  +-----------------------+---------------------+----------+
  370.  |_XimRegisterDispatcher | register_dispatcher |   3.6      |
  371.  +-----------------------+---------------------+----------+
  372.  |_XimCallDispatcher     | call_dispatcher     |   3.7      |
  373.  +-----------------------+---------------------+----------+
  374.  
  375. The Protocol layer calls the above functions using the
  376. Alternative Entry in the left column. The transport imple-
  377. mentation defines XimProto member function in the right col-
  378. umn. The Alternative Entry is provided so as to make easier
  379. to implement the Protocol Layer.
  380.  
  381.  
  382. 3.1.  Opening connection
  383.  
  384. When XOpenIM is called, the following function is called to
  385. connect with the IM Server.
  386.  
  387. Bool (*connect)(im)
  388.       XIM im;
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                   3
  395.  
  396.  
  397.  
  398.  
  399.  
  400. XIM Transport Specification            X11, Release 6.4
  401.  
  402.  
  403. im      Specifies XIM structure address.
  404.  
  405. This function must establishes the connection to the IM
  406. Server. If the connection is established successfully, this
  407. function returns True.    The Alternative Entry for this func-
  408. tion is:
  409.  
  410. Bool _XimConnect(im)
  411.       XIM im;
  412.  
  413.  
  414. im      Specifies XIM structure address.
  415.  
  416.  
  417. 3.2.  Closing connection
  418.  
  419. When XCloseIM is called, the following function is called to
  420. disconnect the connection with the IM Server. The Alterna-
  421. tive Entry for this function is:
  422.  
  423. Bool (*shutdown)(im)
  424.       XIM im;
  425.  
  426.  
  427. im      Specifies XIM structure address.
  428.  
  429. This function must close connection with the IM Server. If
  430. the connection is closed successfully, this function returns
  431. True. The Alternative Entry for this function is:
  432.  
  433. Bool _XimShutdown(im)
  434.       XIM im;
  435.  
  436.  
  437. im   Specifies XIM structure address.
  438.  
  439.  
  440. 3.3.  Writing data
  441.  
  442. The following function is called, when Xlib needs to write
  443. data to the IM Server.
  444.  
  445. Bool (*write)(im, len, data)
  446.       XIM im;
  447.       INT16 len;
  448.       XPointer data;
  449.  
  450.  
  451. im      Specifies XIM structure address.
  452.  
  453. len      Specifies the length of writing data.
  454.  
  455. data      Specifies the writing data.
  456.  
  457.  
  458.  
  459.  
  460.                   4
  461.  
  462.  
  463.  
  464.  
  465.  
  466. XIM Transport Specification            X11, Release 6.4
  467.  
  468.  
  469. This function writes the data to the IM Server, regardless
  470. of the contents.  The number of bytes is passed to len. The
  471. writing data is passed to data. If data is sent success-
  472. fully, the function returns True. Refer to "The Input Method
  473. Protocol" for the contents of the writing data. The Alterna-
  474. tive Entry for this function is:
  475.  
  476. Bool _XimWrite(im, len, data)
  477.       XIM im;
  478.       INT16 len;
  479.       XPointer data;
  480.  
  481.  
  482. im      Specifies XIM structure address.
  483.  
  484. len      Specifies the length of writing data.
  485.  
  486. data      Specifies the writing data.
  487.  
  488.  
  489. 3.4.  Reading data
  490.  
  491. The following function is called when Xlib waits for
  492. response from IM server synchronously.
  493.  
  494. Bool (*read)(im, read_buf, buf_len, ret_len)
  495.       XIM im;
  496.       XPointer read_buf;
  497.       int buf_len;
  498.       int *ret_len;
  499.  
  500.  
  501. im      Specifies XIM structure address.
  502.  
  503. read_buf  Specifies the buffer to store data.
  504.  
  505. buf_len   Specifies the size of the buffer
  506.  
  507. ret_len   Specifies the length of stored data.
  508.  
  509. This function stores the read data in read_buf, which size
  510. is specified as buf_len. The size of data is set to ret_len.
  511. This function return True, if the data is read normally or
  512. reading data is completed.
  513.  
  514. The Alternative Entry for this function is:
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.                   5
  527.  
  528.  
  529.  
  530.  
  531.  
  532. XIM Transport Specification            X11, Release 6.4
  533.  
  534.  
  535. Bool _XimRead(im, ret_len, buf, buf_len, predicate, predicate_arg)
  536.       XIM im;
  537.       INT16 *ret_len;
  538.       XPointer buf;
  539.       int buf_len;
  540.       Bool (*predicate)();
  541.       XPointer predicate_arg;
  542.  
  543.  
  544. im      Specifies XIM structure address.
  545.  
  546. ret_len   Specifies the size of the data buffer.
  547.  
  548. buf      Specifies the buffer to store data.
  549.  
  550. buf_len   Specifies the length of buffer.
  551.  
  552. predicate Specifies the predicate for the XIM data.
  553.  
  554. predicate_arg
  555.       Specifies the predicate specific data.
  556.  
  557. The predicate procedure indicates whether the data is for
  558. the XIM or not. len This function stores the read data in
  559. buf, which size is specified as buf_len. The size of data is
  560. set to ret_len.  If preedicate() returns True, this function
  561. returns True.  If not, it calls the registered callback
  562. function.
  563.  
  564. The procedure and its arguments are:
  565.  
  566.  
  567. Bool (*predicate)(im, len, data, predicate_arg)
  568.       XIM im;
  569.       INT16 len;
  570.       XPointer data;
  571.       XPointer predicate_arg;
  572.  
  573.  
  574. im      Specifies XIM structure address.
  575.  
  576. len      Specifies the size of the data buffer.
  577.  
  578. data      Specifies the buffer to store data.
  579.  
  580. predicate_arg
  581.       Specifies the predicate specific data.
  582.  
  583.  
  584. 3.5.  Flushing buffer
  585.  
  586. The following function is called when Xlib needs to flush
  587. the data.
  588.  
  589.  
  590.  
  591.  
  592.                   6
  593.  
  594.  
  595.  
  596.  
  597.  
  598. XIM Transport Specification            X11, Release 6.4
  599.  
  600.  
  601. void (*flush)(im)
  602.       XIM im;
  603.  
  604.  
  605. im      Specifies XIM structure address.
  606.  
  607. This function must flush the data stored in internal buffer
  608. on the transport layer. If data transfer is completed, the
  609. function returns True.    The Alternative Entry for this func-
  610. tion is:
  611.  
  612. void _XimFlush(im)
  613.       XIM im;
  614.  
  615.  
  616. im      Specifies XIM structure address.
  617.  
  618.  
  619. 3.6.  Registering asynchronous data handler
  620.  
  621. Xlib needs to handle asynchronous response from IM Server.
  622. This is because some of the XIM data occur asynchronously to
  623. X events.
  624.  
  625. Those data will be handled in the Filter, and the Filter
  626. will call asynchronous data handler in the protocol layer.
  627. Then it calls dispatchers in the transport layer. The dis-
  628. patchers are implemented by the protocol layer. This func-
  629. tion must store the information and prepare for later call
  630. of the dispatchers using _XimCallDispatcher.
  631.  
  632. When multiple dispatchers are registered, they will be
  633. called sequentially in order of registration, on arrival of
  634. asynchronous data. The register_dispatcher is declared as
  635. following:
  636.  
  637. Bool (*register_dispatcher)(im, dispatcher, call_data)
  638.       XIM im;
  639.       Bool (*dispatcher)();
  640.       XPointer call_data;
  641.  
  642.  
  643. im      Specifies XIM structure address.
  644.  
  645. dispatcher
  646.       Specifies the dispatcher function to register.
  647.  
  648. call_data Specifies a parameter for the dispatcher.
  649.  
  650. The dispatcher is a function of the following type:
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.                   7
  659.  
  660.  
  661.  
  662.  
  663.  
  664. XIM Transport Specification            X11, Release 6.4
  665.  
  666.  
  667. Bool (*dispatcher)(im, len, data, call_data)
  668.       XIM im;
  669.       INT16 len;
  670.       XPointer data;
  671.       XPointer call_data;
  672.  
  673.  
  674. im      Specifies XIM structure address.
  675.  
  676. len      Specifies the size of the data buffer.
  677.  
  678. data      Specifies the buffer to store data.
  679.  
  680. call_data Specifies a parameter passed to the register_dis-
  681.       patcher.
  682.  
  683. The dispatcher is provided by the protocol layer. They are
  684. called once for every asynchronous data, in order of regis-
  685. tration. If the data is used, it must return True. other-
  686. wise, it must return False.
  687.  
  688. If the dispatcher function returns True, the Transport Layer
  689. assume that the data has been processed by the upper layer.
  690. The Alternative Entry for this function is:
  691.  
  692. Bool _XimRegisterDispatcher(im, dispatcher, call_data)
  693.       XIM im;
  694.       Bool (*dispatcher)();
  695.       XPointer call_data;
  696.  
  697.  
  698. im      Specifies XIM structure address.
  699.  
  700. dispatcher
  701.       Specifies the dispatcher function to register.
  702.  
  703. call_data Specifies a parameter for the dispatcher.
  704.  
  705.  
  706. 3.7.  Calling dispatcher
  707.  
  708. The following function is used to call the registered dis-
  709. patcher function, when the asynchronous response from IM
  710. Server has arrived.
  711.  
  712. Bool (*call_dispatcher)(im, len, data)
  713.       XIM im;
  714.       INT16 len;
  715.       XPointer data;
  716.  
  717.  
  718. im      Specifies XIM structure address.
  719.  
  720.  
  721.  
  722.  
  723.  
  724.                   8
  725.  
  726.  
  727.  
  728.  
  729.  
  730. XIM Transport Specification            X11, Release 6.4
  731.  
  732.  
  733. len      Specifies the size of data buffer.
  734.  
  735. data      Specifies the buffer to store data.
  736.  
  737. The call_dispatcher must call the dispatcher function, in
  738. order of their registration. len and data are the data
  739. passed to register_dispatcher.
  740.  
  741. The return values are checked at each invocation, and if it
  742. finds True, it immediately return with true for its return
  743. value.
  744.  
  745. It is depend on the upper layer whether the read data is XIM
  746. Protocol packet unit or not.  The Alternative Entry for this
  747. function is:
  748.  
  749. Bool _XimCallDispatcher(im, len, data)
  750.       XIM im;
  751.       INT16 len;
  752.       XPointer call_data;
  753.  
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.                   9
  791.  
  792.  
  793.  
  794.  
  795.  
  796. XIM Transport Specification            X11, Release 6.4
  797.  
  798.  
  799. 4.  Sample implementations for the Transport Layer
  800.  
  801. Sample implementations for the transporter using the X con-
  802. nection is described here.
  803.  
  804.  
  805. 4.1.  X Transport
  806.  
  807. At the beginning of the X Transport connection for the XIM
  808. transport mechanism, two different windows must be created
  809. either in an Xlib XIM or in an IM Server, with which the
  810. Xlib and the IM Server exchange the XIM transports by using
  811. the ClientMessage events and Window Properties.  In the fol-
  812. lowing, the window created by the Xlib is referred as the
  813. "client communication window", and on the other hand, the
  814. window created by the IM Server is referred as the "IMS com-
  815. munication window".
  816.  
  817.  
  818. 4.1.1.    Connection
  819.  
  820. In order to establish a connection, a communication window
  821. is created.  A ClientMessage in the following event's format
  822. is sent to the owner window of XIM_SERVER selection, which
  823. the IM Server has created.
  824.  
  825. Refer to "The Input Method Protocol" for the XIM_SERVER
  826. atom.
  827.  
  828.     Table 4-1; The ClientMessage sent to the IMS window.
  829.  
  830. -----------------------+------------------------------------------------
  831. Structure Member       | Contents
  832. -----------------------+------------------------------------------------
  833. int      type           | ClientMessage
  834. u_long      serial       | Set by the X Window System
  835. Bool      send_event   | Set by the X Window System
  836. Display   *display     | The display to which connects
  837. Window      window       | IMS Window ID
  838. Atom      message_type | XInternAtom(display, ``_XIM_XCONNECT'', False)
  839. int      format       | 32
  840. long      data.l[0]    | client communication window ID
  841. long      data.l[1]    | client-major-transport-version (*1)
  842. long      data.l[2]    | client-major-transport-version (*1)
  843. -----------------------+------------------------------------------------
  844.  
  845.  
  846. In order to establish the connection (to notify the IM
  847. Server communication window), the IM Server sends a
  848. ClientMessage in the following event's format to the client
  849. communication window.
  850.  
  851.       Table 4-2; The ClientMessage sent by IM Server.
  852.  
  853.  
  854.  
  855.  
  856.                  10
  857.  
  858.  
  859.  
  860.  
  861.  
  862. XIM Transport Specification            X11, Release 6.4
  863.  
  864.  
  865. -----------------------+-------------------------------------------------------
  866. Structure Member       | Contents
  867. -----------------------+-------------------------------------------------------
  868. int      type           | ClientMessage
  869. u_long      serial       | Set by the X Window System
  870. Bool      send_event   | Set by the X Window System
  871. Display   *display     | The display to which connects
  872. Window      window       | client communication window ID
  873. Atom      message_type | XInternAtom(display, ``_XIM_XCONNECT'', False)
  874. int      format       | 32
  875. long      data.l[0]    | IMS communication window ID
  876. long      data.l[1]    | server-major-transport-version (*1)
  877. long      data.l[2]    | server-minor-transport-version (*1)
  878. long      data.l[3]    | dividing size between ClientMessage and Property (*2)
  879. -----------------------+-------------------------------------------------------
  880.  
  881.  
  882.  
  883. (*1) major/minor-transport-version
  884.       The read/write method is decided by the combina-
  885.       tion of major/minor-transport-version, as follows:
  886.  
  887.      Table 4-3; The read/write method and the major/minor-transport-version
  888.  
  889.    +------------------+---------------------------------------+
  890.    |Transport-version | read/write                  |
  891.    +--------+---------+---------------------------------------+
  892.    | major  |  minor  |                       |
  893.    +--------+---------+---------------------------------------+
  894.    |   0    |     0    | only-CM & Property-with-CM          |
  895.    |        |     1    | only-CM & multi-CM              |
  896.    |        |     2    | only-CM & multi-CM & Property-with-CM |
  897.    +--------+---------+---------------------------------------+
  898.    |   1    |     0    | PropertyNotify                  |
  899.    +--------+---------+---------------------------------------+
  900.    |   2    |     0    | only-CM & PropertyNotify          |
  901.    |        |     1    | only-CM & multi-CM & PropertyNotify   |
  902.    +--------+---------+---------------------------------------+
  903.  
  904.  
  905.  
  906.    only-CM          :   data is sent via a ClientMessage
  907.    multi-CM          :   data is sent via multiple ClientMessages
  908.    Property-with-CM   :   data is written in Property, and its Atom
  909.               is send via ClientMessage
  910.    PropertyNotify     :   data is written in Property, and its Atom
  911.               is send via PropertyNotify
  912.  
  913.  
  914.      The method to decide major/minor-transport-version is
  915.      as follows:
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.                  11
  923.  
  924.  
  925.  
  926.  
  927.  
  928. XIM Transport Specification            X11, Release 6.4
  929.  
  930.  
  931.      (1)  The client sends 0 as major/minor-transport-ver-
  932.       sion to the IM Server.  The client must support
  933.       all methods in Table 4-3.  The client may send
  934.       another number as major/minor-transport-version to
  935.       use other method than the above in the future.
  936.  
  937.      (2)  The IM Server sends its major/minor-transport-ver-
  938.       sion number to the client. The client sends data
  939.       using the method specified by the IM Server.
  940.  
  941.      (3)  If major/minor-transport-version number is not
  942.       available, it is regarded as 0.
  943.  
  944.  
  945. (*2) dividing size between ClientMessage and Property
  946.       If data is sent via both of multi-CM and Property,
  947.       specify the dividing size between ClientMessage
  948.       and Property. The data, which is smaller than this
  949.       size, is sent via multi-CM (or only-CM), and the
  950.       data, which is lager than this size, is sent via
  951.       Property.
  952.  
  953.  
  954. 4.1.2.    read/write
  955.  
  956. The data is transferred via either ClientMessage or Window
  957. Property in the X Window System.
  958.  
  959.  
  960. 4.1.2.1.  Format for the data from the Client to the IM
  961. Server
  962.  
  963. ClientMessage
  964.  
  965.      If data is sent via ClientMessage event, the format is
  966.      as follows:
  967.  
  968.      Table 4-4; The ClientMessage event's format (first or middle)
  969.  
  970.      -----------------------+------------------------------------------------
  971.      Structure Member        | Contents
  972.      -----------------------+------------------------------------------------
  973.      int       type        | ClientMessage
  974.      u_long    serial        | Set by the X Window System
  975.      Bool      send_event   | Set by the X Window System
  976.      Display   *display     | The display to which connects
  977.      Window    window        | IMS communication window ID
  978.      Atom      message_type | XInternAtom(display, ``_XIM_MOREDATA'', False)
  979.      int       format        | 8
  980.      char      data.b[20]   | (read/write DATA : 20 byte)
  981.      -----------------------+------------------------------------------------
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.                  12
  989.  
  990.  
  991.  
  992.  
  993.  
  994. XIM Transport Specification            X11, Release 6.4
  995.  
  996.  
  997.      Table 4-5; The ClientMessage event's format (only or last)
  998.  
  999.      -----------------------+------------------------------------------------
  1000.      Structure Member        | Contents
  1001.      -----------------------+------------------------------------------------
  1002.      int       type        | ClientMessage
  1003.      u_long    serial        | Set by the X Window System
  1004.      Bool      send_event   | Set by the X Window System
  1005.      Display   *display     | The display to which connects
  1006.      Window    window        | IMS communication window ID
  1007.      Atom      message_type | XInternAtom(display, ``_XIM_PROTOCOL'', False)
  1008.      int       format        | 8
  1009.      char      data.b[20]   | (read/write DATA : MAX 20 byte)  (*1)
  1010.      -----------------------+------------------------------------------------
  1011.  
  1012.  
  1013.      (*1) If the data is smaller than 20 byte, all data
  1014.       other than available data must be 0.
  1015.  
  1016. Property
  1017.  
  1018.      In the case of large data, data will be sent via the
  1019.      Window Property for the efficiency.  There are the fol-
  1020.      lowing two methods to notify Property, and transport-
  1021.      version is decided which method is used.
  1022.  
  1023.  
  1024.      (1)  The XChangeProperty function is used to store data
  1025.       in the client communication window, and Atom of
  1026.       the stored data is notified to the IM Server via
  1027.       ClientMessage event.
  1028.  
  1029.      (2)  The XChangeProperty function is used to store data
  1030.       in the client communication window, and Atom of
  1031.       the stored data is notified to the IM Server via
  1032.       PropertyNotify event.
  1033.  
  1034.      The arguments of the XChangeProperty are as follows:
  1035.  
  1036.       Table 4-6; The XChangeProperty event's format
  1037.  
  1038.      --------------------+--------------------------------
  1039.      Argument         | Contents
  1040.      --------------------+--------------------------------
  1041.      Display   *display  | The display to which connects
  1042.      Window    window     | IMS communication window ID
  1043.      Atom      property  | read/write property Atom (*1)
  1044.      Atom      type     | XA_STRING
  1045.      int       format     | 8
  1046.      int       mode     | PropModeAppend
  1047.      u_char    *data     | read/write DATA
  1048.      int       nelements | length of DATA
  1049.      --------------------+--------------------------------
  1050.  
  1051.  
  1052.  
  1053.  
  1054.                  13
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060. XIM Transport Specification            X11, Release 6.4
  1061.  
  1062.  
  1063.      (*1) The read/write property ATOM allocates the follow-
  1064.       ing strings by XInternAtom.
  1065.            ``_clientXXX''
  1066.  
  1067.      The client changes the property with the mode of Prop-
  1068.      ModeAppend and the IM Server will read it with the
  1069.      delete mode i.e. (delete = True).
  1070.  
  1071.      If Atom is notified via ClientMessage event, the format
  1072.      of the ClientMessage is as follows:
  1073.  
  1074.      Table 4-7; The ClientMessage event's format to send
  1075.             Atom of property
  1076.  
  1077.      -----------------------+------------------------------------------------
  1078.      Structure Member        | Contents
  1079.      -----------------------+------------------------------------------------
  1080.      int       type        | ClientMessage
  1081.      u_long    serial        | Set by the X Window System
  1082.      Bool      send_event   | Set by the X Window System
  1083.      Display   *display     | The display to which connects
  1084.      Window    window        | IMS communication window ID
  1085.      Atom      message_type | XInternAtom(display, ``_XIM_PROTOCOL'', False)
  1086.      int       format        | 32
  1087.      long      data.l[0]    | length of read/write property Atom
  1088.      long      data.l[1]    | read/write property Atom
  1089.      -----------------------+------------------------------------------------
  1090.  
  1091.  
  1092.  
  1093. 4.1.2.2.  Format for the data from the IM Server to the
  1094. Client
  1095.  
  1096. ClientMessage
  1097.  
  1098.      The format of the ClientMessage is as follows:
  1099.  
  1100.      Table 4-8; The ClientMessage event's format (first or middle)
  1101.  
  1102.      -----------------------+------------------------------------------------
  1103.      Structure Member        | Contents
  1104.      -----------------------+------------------------------------------------
  1105.      int       type        | ClientMessage
  1106.      u_long    serial        | Set by the X Window System
  1107.      Bool      send_event   | Set by the X Window System
  1108.      Display   *display     | The display to which connects
  1109.      Window    window        | client communication window ID
  1110.      Atom      message_type | XInternAtom(display, ``_XIM_MOREDATA'', False)
  1111.      int       format        | 8
  1112.      char      data.b[20]   | (read/write DATA : 20 byte)
  1113.      -----------------------+------------------------------------------------
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.                  14
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126. XIM Transport Specification            X11, Release 6.4
  1127.  
  1128.  
  1129.      Table 4-9; The ClientMessage event's format (only or last)
  1130.  
  1131.      -----------------------+------------------------------------------------
  1132.      Structure Member        | Contents
  1133.      -----------------------+------------------------------------------------
  1134.      int       type        | ClientMessage
  1135.      u_long    serial        | Set by the X Window System
  1136.      Bool      send_event   | Set by the X Window System
  1137.      Display   *display     | The display to which connects
  1138.      Window    window        | client communication window ID
  1139.      Atom      message_type | XInternAtom(display, ``_XIM_PROTOCOL'', False)
  1140.      int       format        | 8
  1141.      char      data.b[20]   | (read/write DATA : MAX 20 byte) (*1)
  1142.      -----------------------+------------------------------------------------
  1143.  
  1144.  
  1145.  
  1146.      (*1) If the data size is smaller than 20 bytes, all
  1147.       data other than available data must be 0.
  1148.  
  1149. Property
  1150.  
  1151.      In the case of large data, data will be sent via the
  1152.      Window Property for the efficiency. There are the fol-
  1153.      lowing two methods to notify Property, and transport-
  1154.      version is decided which method is used.
  1155.  
  1156.  
  1157.      (1)  The XChangeProperty function is used to store data
  1158.       in the IMS communication window, and Atom of the
  1159.       property is sent via the ClientMessage event.
  1160.  
  1161.      (2)  The XChangeProperty function is used to store data
  1162.       in the IMS communication window, and Atom of the
  1163.       property is sent via PropertyNotify event.
  1164.  
  1165.      The arguments of the XChangeProperty are as follows:
  1166.  
  1167.      Table 4-10; The XChangeProperty event's format
  1168.  
  1169.      --------------------+----------------------------------
  1170.      Argument         | Contents
  1171.      --------------------+----------------------------------
  1172.      Display   *display  | The display which to connects
  1173.      Window    window     | client communication window ID
  1174.      Atom      property  | read/write property Atom (*1)
  1175.      Atom      type     | XA_STRING
  1176.      int       format     | 8
  1177.      int       mode     | PropModeAppend
  1178.      u_char    *data     | read/write DATA
  1179.      int       nelements | length of DATA
  1180.      --------------------+----------------------------------
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.                  15
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192. XIM Transport Specification            X11, Release 6.4
  1193.  
  1194.  
  1195.      (*1) The read/write property ATOM allocates some
  1196.       strings, which are not allocated by the client, by
  1197.       XInternAtom.
  1198.  
  1199.      The IM Server changes the property with the mode of
  1200.      PropModeAppend and the client reads it with the delete
  1201.      mode, i.e. (delete = True).
  1202.  
  1203.      If Atom is notified via ClientMessage event, the format
  1204.      of the ClientMessage is as follows:
  1205.  
  1206.      Table 4-11; The ClientMessage event's format to send
  1207.             Atom of property
  1208.  
  1209.      -----------------------+------------------------------------------------
  1210.      Structure Member        | Contents
  1211.      -----------------------+------------------------------------------------
  1212.      int       type        | ClientMessage
  1213.      u_long    serial        | Set by the X Window System
  1214.      Bool      send_event   | Set by the X Window System
  1215.      Display   *display     | The display to which connects
  1216.      Window    window        | client communication window ID
  1217.      Atom      message_type | XInternAtom(display, ``_XIM_PROTOCOL'', False)
  1218.      int       format        | 32
  1219.      long      data.l[0]    | length of read/write property ATOM
  1220.      long      data.l[1]    | read/write property ATOM
  1221.      -----------------------+------------------------------------------------
  1222.  
  1223.  
  1224.  
  1225. 4.1.3.    Closing Connection
  1226.  
  1227. If the client disconnect with the IM Server, shutdown func-
  1228. tion should free the communication window properties and
  1229. etc..
  1230.  
  1231.  
  1232. 5.  References
  1233.  
  1234. [1] Masahiko Narita and Hideki Hiura, ``The Input Method
  1235. Protocol''
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.                  16
  1253.  
  1254.  
  1255.