home *** CD-ROM | disk | FTP | other *** search
/ Chip 2001 August - Disc 2 / chip_20018102_hu.iso / linux / X-4.1.0 / doc / xtrans.txt < prev    next >
Text File  |  2001-06-27  |  38KB  |  1,123 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                           XX TTrraannssppoorrtt IInntteerrffaaccee
  9.  
  10.        Copyright (c) 1993, 1994 NCR Corporation - Dayton, Ohio, USA
  11.  
  12.        All Rights Reserved
  13.  
  14.        Permission  to  use,  copy,  modify,  and  distribute   this
  15.        software  and  its documentation for any purpose and without
  16.        fee is hereby granted, provided  that  the  above  copyright
  17.        notice  appear  in  all  copies and that both that copyright
  18.        notice and  this  permission  notice  appear  in  supporting
  19.        documentation,  and  that  the  name  NCR  not  be  used  in
  20.        advertising or publicity pertaining to distribution  of  the
  21.        software  without  specific,  written prior permission.  NCR
  22.        makes no  representations  about  the  suitability  of  this
  23.        software  for  any  purpose.  It is provided "as is" without
  24.        express or implied warranty.
  25.  
  26.        NCR DISCLAIM ALL WARRANTIES WITH REGARD  TO  THIS  SOFTWARE,
  27.        INCLUDING  ALL  IMPLIED  WARRANTIES  OF  MERCHANTABILITY AND
  28.        FITNESS, IN NO EVENT SHALL NCR BE LIABLE  FOR  ANY  SPECIAL,
  29.        INDIRECT  OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
  30.        RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER  IN  AN
  31.        ACTION  OF  CONTRACT,  NEGLIGENCE  OR OTHER TORTIOUS ACTION,
  32.        ARISING OUT OF OR IN CONNECTION WITH THE USE OR  PERFORMANCE
  33.        OF THIS SOFTWARE.
  34.  
  35.        Copyright 1993, 1994 X Consortium
  36.  
  37.        Permission  is hereby granted, free of charge, to any person
  38.        obtaining  a  copy   of   this   software   and   associated
  39.        documentation  files  (the  ``Software''),  to  deal  in the
  40.        Software without restriction, including  without  limitation
  41.        the rights to use, copy, modify, merge, publish, distribute,
  42.        sublicense, and/or sell  copies  of  the  Software,  and  to
  43.        permit  persons  to whom the Software is furnished to do so,
  44.        subject to the following conditions:
  45.  
  46.        The above copyright notice and this permission notice  shall
  47.        be  included  in  all  copies or substantial portions of the
  48.        Software.
  49.  
  50.        THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF  ANY
  51.        KIND,  EXPRESS  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  52.        WARRANTIES OF  MERCHANTABILITY,  FITNESS  FOR  A  PARTICULAR
  53.        PURPOSE  AND  NONINFRINGEMENT.   IN  NO  EVENT  SHALL  THE X
  54.        CONSORTIUM  BE  LIABLE  FOR  ANY  CLAIM,  DAMAGES  OR  OTHER
  55.        LIABILITY,  WHETHER  IN  AN  ACTION  OF  CONTRACT,  TORT  OR
  56.        OTHERWISE, ARISING FROM, OUT OF OR IN  CONNECTION  WITH  THE
  57.        SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  58.  
  59.        Except  as  contained  in  this  notice,  the  name of the X
  60.        Consortium shall not be used in advertising or otherwise  to
  61.        promote  the  sale,  use  or other dealings in this Software
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.        without prior written authorization from the X Consortium.
  75.  
  76.        X Window System is a trademark of X Consortium, Inc.
  77.  
  78.        Designed by Stuart Anderson (NCR) with help from  Ralph  Mor
  79.        (X Consortium)
  80.  
  81.                             _D_r_a_f_t _V_e_r_s_i_o_n _0_._6
  82.  
  83.        NOTE:  This  documentation  does  not  completely  match the
  84.        implementation in R6 (as a result of some late changes  made
  85.        in  the  code).   Specifically,  support  was added for font
  86.        server cloning, and conditional compliation  was  introduced
  87.        for client vs. server code.
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.        _1_.  _P_u_r_p_o_s_e_s _a_n_d _G_o_a_l_s
  141.  
  142.        The  X Transport Interface is intended to combine all system
  143.        and transport specific code  into  a  single  place  in  the
  144.        source  tree.  This  API  should  be  used by all libraries,
  145.        clients and servers of the X Window System. Use of this  API
  146.        should  allow  the  addition  of new types of transports and
  147.        support for new platforms without making any changes to  the
  148.        source except in the X Transport Interface code.
  149.  
  150.        This  interface  should solve the problem of multiple #ifdef
  151.        TRANSPORT   and   #ifdef   PLATFORM   statements   scattered
  152.        throughout the source tree.
  153.  
  154.        This   interface  should  provide  enough  functionality  to
  155.        support  all  types  of  protocols,   including   connection
  156.        oriented  protocols  such as X11 and FS, and connection-less
  157.        oriented protocols such as XDMCP.
  158.        _2_.  _O_v_e_r_v_i_e_w _o_f _t_h_e _i_n_t_e_r_f_a_c_e
  159.  
  160.        The interface provides an API for use by  applications.  The
  161.        functions  in  this  API  perform work that is common to all
  162.        transports and systems, such as parsing an  address  into  a
  163.        host  and  port  number.  The  functions  in  this  API call
  164.        transport specific functions that are contained in  a  table
  165.        whose  contents  are  defined  at  compile  time. This table
  166.        contains an entry for each type of transport. Each entry  is
  167.        a   record  containing  mostly  pointers  to  function  that
  168.        implements the interface for the given transport.
  169.  
  170.        This API does not provide an  abstraction  for  select()  or
  171.        poll().     These    function   are   themselves   transport
  172.        independent, so an additional interface is  not  needed  for
  173.        these  functions.   It is also unclear how such an interface
  174.        would affect performance.
  175.        _3_.  _D_e_f_i_n_i_t_i_o_n _o_f _A_d_d_r_e_s_s _S_p_e_c_i_f_i_c_a_t_i_o_n _F_o_r_m_a_t
  176.  
  177.        Addresses are specified in the following syntax,
  178.  
  179.        _p_r_o_t_o_c_o_l_/_h_o_s_t_:_p_o_r_t
  180.  
  181.        where _p_r_o_t_o_c_o_l specifies a protocol family or an alias for a
  182.        protocol family. A definition of common protocol families is
  183.        given in a later section.
  184.  
  185.        The _h_o_s_t  part  specifies  the  name  of  a  host  or  other
  186.        transport  dependent  entity  that could be interpreted as a
  187.        Network Service Access Point (NSAP).
  188.  
  189.        The _p_o_r_t part specifies the  name  of  a  Transport  Service
  190.        Access  Point  (TSAP).  The format of the TSAP is defined by
  191.        the  underlying  transport   implementation,   but   it   is
  192.        represented  using  a  string  format  when it is part of an
  193.        address.
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.        _4_.  _I_n_t_e_r_n_a_l _D_a_t_a _S_t_r_u_c_t_u_r_e_s
  207.  
  208.        There are two major  data  structures  associated  with  the
  209.        transport independent portion of this interface.  Additional
  210.        data structures may be used internally by each transport.
  211.        _4_._1  _X_t_r_a_n_s_p_o_r_t
  212.  
  213.        Each transport supported  has  an  entry  in  the  transport
  214.        table.   The  transport  table  is  an  array  of _X_t_r_a_n_s_p_o_r_t
  215.        records. Each record contains all the  entry  points  for  a
  216.        single transport. This record is defined as:
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.        typedef struct _Xtransport {
  273.  
  274.            char *TransName;
  275.            int  flags;
  276.  
  277.            XtransConnInfo (*OpenCOTSClient)(
  278.             struct _Xtransport *,    /* transport */
  279.             char *,             /* protocol */
  280.             char *,             /* host */
  281.             char *              /* port */
  282.            );
  283.  
  284.            XtransConnInfo (*OpenCOTSServer)(
  285.             struct _Xtransport *,    /* transport */
  286.             char *,             /* protocol */
  287.             char *,             /* host */
  288.             char *              /* port */
  289.            );
  290.  
  291.            XtransConnInfo (*OpenCLTSClient)(
  292.             struct _Xtransport *,    /* transport */
  293.             char *,             /* protocol */
  294.             char *,             /* host */
  295.             char *              /* port */
  296.            );
  297.  
  298.            XtransConnInfo (*OpenCLTSServer)(
  299.             struct _Xtransport *,    /* transport */
  300.             char *,             /* protocol */
  301.             char *,             /* host */
  302.             char *              /* port */
  303.            );
  304.  
  305.            int   (*SetOption)(
  306.             XtransConnInfo,          /* connection */
  307.             int,           /* option */
  308.             int            /* arg */
  309.            );
  310.  
  311.            int   (*CreateListener)(
  312.             XtransConnInfo,          /* connection */
  313.             char *              /* port */
  314.            );
  315.  
  316.            int   (*ResetListener)(
  317.             XtransConnInfo      /* connection */
  318.            );
  319.  
  320.            XtransConnInfo (*Accept)(
  321.             XtransConnInfo      /* connection */
  322.            );
  323.  
  324.            int   (*Connect)(
  325.             XtransConnInfo,          /* connection */
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.             char *,             /* host */
  339.             char *              /* port */
  340.            );
  341.  
  342.            int   (*BytesReadable)(
  343.             XtransConnInfo,          /* connection */
  344.             BytesReadable_t *   /* pend */
  345.            );
  346.  
  347.            int   (*Read)(
  348.             XtransConnInfo,          /* connection */
  349.             char *,             /* buf */
  350.             int            /* size */
  351.            );
  352.  
  353.            int   (*Write)(
  354.             XtransConnInfo,          /* connection */
  355.             char *,             /* buf */
  356.             int            /* size */
  357.            );
  358.  
  359.            int   (*Readv)(
  360.             XtransConnInfo,          /* connection */
  361.             struct iovec *,          /* buf */
  362.             int            /* size */
  363.            );
  364.  
  365.            int   (*Writev)(
  366.             XtransConnInfo,          /* connection */
  367.             struct iovec *,          /* buf */
  368.             int            /* size */
  369.            );
  370.  
  371.            int   (*Disconnect)(
  372.             XtransConnInfo      /* connection */
  373.            );
  374.  
  375.            int   (*Close)(
  376.             XtransConnInfo      /* connection */
  377.            );
  378.  
  379.        } Xtransport;
  380.  
  381.  
  382.        The _f_l_a_g_s field can contain an OR of the following masks:
  383.  
  384.        _T_R_A_N_S___A_L_I_A_S:  indicates  that  this  record  is providing an
  385.        alias, and should not be used to create a listner.
  386.  
  387.        _T_R_A_N_S___L_O_C_A_L: indicates that this is a LOCALCONN transport.
  388.  
  389.        _4_._2  _X_t_r_a_n_s_C_o_n_n_I_n_f_o
  390.  
  391.        Each connection will have an opaque _X_t_r_a_n_s_C_o_n_n_I_n_f_o transport
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.        connection  object  allocated  for  it. This record contains
  405.        information  specific  to  the  connection.  The  record  is
  406.        defined as:
  407.  
  408.        typedef struct _XtransConnInfo *XtransConnInfo;
  409.  
  410.        struct _XtransConnInfo {
  411.            struct _Xtransport     *transptr;
  412.            char  *priv;
  413.            int        flags;
  414.            int        fd;
  415.            int        family;
  416.            char  *addr;
  417.            int        addrlen;
  418.            char  *peeraddr;
  419.            int        peeraddrlen;
  420.        };
  421.  
  422.        _5_.  _E_x_p_o_s_e_d _T_r_a_n_s_p_o_r_t _I_n_d_e_p_e_n_d_e_n_t _A_P_I
  423.  
  424.        This  API  is  included in each library and server that uses
  425.        it. The API may be used by the library, but it is not  added
  426.        to  the  public  API  for  that  library.  This interface is
  427.        simply an implementation facilitator. This  API  contains  a
  428.        low  level  set  of  core  primitives,  and  a  few  utility
  429.        functions that are built  on  top  of  the  primitives.  The
  430.        utility functions exist to provide a more familiar interface
  431.        that can be used to port existing code.
  432.  
  433.        A macro is defined in Xtrans.h for TRANS(func) that  creates
  434.        a  unique  function  name  depending  on  where  the code is
  435.        compiled.   For    example,    when    built    for    Xlib,
  436.        TRANS(OpenCOTSClient) becomes _X11TransOpenCOTSClient.
  437.  
  438.        All failures are considered fatal, and the connection should
  439.        be closed and re-established  if  desired.  In  most  cases,
  440.        however,  the value of errno will be available for debugging
  441.        purposes.
  442.        _5_._1  _C_o_r_e _I_n_t_e_r_f_a_c_e _A_P_I
  443.  
  444.           +o XtransConnInfo TRANS(OpenCOTSClient)(char *address)
  445.  
  446.             This function creates a  Connection-Oriented  Transport
  447.             that  is  suitable  for use by a client.  The parameter
  448.             _a_d_d_r_e_s_s contains the full  address  of  the  server  to
  449.             which  this endpoint will be connected.  This functions
  450.             returns  an  opaque  transport  connection  object   on
  451.             success, or NULL on failure.
  452.  
  453.           +o XtransConnInfo TRANS(OpenCOTSServer)(char *address)
  454.  
  455.             This  function  creates a Connection-Oriented Transport
  456.             that is suitable for use by a  server.   The  parameter
  457.             _a_d_d_r_e_s_s  contains the full address to which this server
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.             will  be  bound.   This  functions  returns  an  opaque
  471.             transport  connection  object  on  success,  or NULL on
  472.             failure.
  473.  
  474.           +o XtransConnInfo TRANS(OpenCLTSClient)(char *address)
  475.  
  476.             This function creates a Connection-Less Transport  that
  477.             is suitable for use by a client.  The parameter _a_d_d_r_e_s_s
  478.             contains the full address of the server to  which  this
  479.             endpoint  will be connected.  This functions returns an
  480.             opaque transport connection object on success, or  NULL
  481.             on failure.
  482.  
  483.           +o XtransConnInfo TRANS(OpenCLTSServer)(char *address)
  484.  
  485.             This  function creates a Connection-Less Transport that
  486.             is suitable for use by a server.  The parameter _a_d_d_r_e_s_s
  487.             contains  the full address to which this server will be
  488.             bound.  This  functions  returns  an  opaque  transport
  489.             connection object on success, or NULL on failure.
  490.  
  491.           +o int   TRANS(SetOption)(XtransConnInfo  connection,  int
  492.             option, int arg)
  493.  
  494.             This function sets transport options,  similar  to  the
  495.             way  setsockopt()  and  ioctl()  work.   The  parameter
  496.             _c_o_n_n_e_c_t_i_o_n  is  an  endpoint  that  was  obtained  from
  497.             _XTransOpen*()   functions.    The   parameter   _o_p_t_i_o_n
  498.             contains the option that will be set. The actual values
  499.             for  _o_p_t_i_o_n  are  defined  in  a  later  section.   The
  500.             parameter _a_r_g can be used  to  pass  in  an  additional
  501.             value  that  may  be  required  by  some options.  This
  502.             function return 0 on success and -1 on failure.
  503.  
  504.             Note:  Based  on  current  usage,   the   complimentary
  505.             function TRANS(GetOption)() is not necessary.
  506.  
  507.           +o int   TRANS(CreateListener)(XtransConnInfo  connection,
  508.             char *port)
  509.  
  510.             This  function  sets  up  the   server   endpoint   for
  511.             listening.   The  parameter  _c_o_n_n_e_c_t_i_o_n  is an endpoint
  512.             that  was  obtained  from  TRANS(OpenCOTSServer)()   or
  513.             TRANS(OpenCLTSServer)().   The parameter _p_o_r_t specifies
  514.             the port to which this endpoint  should  be  bound  for
  515.             listening.   If  _p_o_r_t  is  NULL, then the transport may
  516.             attempt  to  allocate  any  available  TSAP  for   this
  517.             connection.  If the transport cannot support this, then
  518.             this function will return  a  failure.   This  function
  519.             return 0 on success and -1 on failure.
  520.  
  521.           +o int TRANS(ResetListener)(XtransConnInfo connection)
  522.  
  523.             When  a  server  is restarted, certain listen ports may
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.             need to be reset.  For example, unix  domain  needs  to
  537.             check that the file used for communication has not been
  538.             deleted.   If  it  has,  it  must  be  recreated.   The
  539.             parameter  _c_o_n_n_e_c_t_i_o_n  is  an opened and bound endpoint
  540.             that  was  obtained  from  TRANS(OpenCOTSServer)()  and
  541.             passed  to TRANS(CreateListener)().  This function will
  542.             return one of the following  values:  TRANS_RESET_NOOP,
  543.             TRANS_RESET_NEW_FD, or TRANS_RESET_FAILURE.
  544.  
  545.           +o XtransConnInfo TRANS(Accept)(XtransConnInfo connection)
  546.  
  547.             Once a connection indication is received, this function
  548.             can  be called to accept the connection.  The parameter
  549.             _c_o_n_n_e_c_t_i_o_n is an opened and  bound  endpoint  that  was
  550.             obtained  from  TRANS(OpenCOTSServer)()  and  passed to
  551.             TRANS(CreateListener)().  This function will  return  a
  552.             new  opaque  transport  connection object upon success,
  553.             NULL otherwise.
  554.  
  555.           +o int  TRANS(Connect)(XtransConnInfo   connection,   char
  556.             *address)
  557.  
  558.             This  function  creates  a connection to a server.  The
  559.             parameter _c_o_n_n_e_c_t_i_o_n is an endpoint that  was  obtained
  560.             from  TRANS(OpenCOTSClient)().   The parameters _a_d_d_r_e_s_s
  561.             specify the TSAP to which this endpoint should connect.
  562.             If  the protocol is included in the address, it will be
  563.             ignored.  This function return 0 on success and  -1  on
  564.             failure.
  565.  
  566.           +o int   TRANS(BytesReadable)(XtransConnInfo   connection,
  567.             BytesReadable_t *pend);
  568.  
  569.             This function provides the same  functionality  as  the
  570.             BytesReadable macro.
  571.  
  572.           +o int  TRANS(Read)(XtransConnInfo  connection, char *buf,
  573.             int size)
  574.  
  575.             This function will return the number of bytes requested
  576.             on  a  COTS  connection, and will return the minimum of
  577.             the number bytes requested or the size of the  incoming
  578.             packet on a CLTS connection.
  579.  
  580.           +o int  TRANS(Write)(XtransConnInfo connection, char *buf,
  581.             int size)
  582.  
  583.             This function will write the requested number of  bytes
  584.             on  a  COTS  connection,  and will send a packet of the
  585.             requested size on a CLTS connection.
  586.  
  587.           +o int  TRANS(Readv)(XtransConnInfo   connection,   struct
  588.             iovec *buf, int size)
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.             Similar to TRANS(Read)().
  603.  
  604.           +o int   TRANS(Writev)(XtransConnInfo  connection,  struct
  605.             iovec *buf, int size)
  606.  
  607.             Similar to TRANS(Write)().
  608.  
  609.           +o int TRANS(Disconnect)(XtransConnInfo connection)
  610.  
  611.             This function is used when  an  orderly  disconnect  is
  612.             desired.  This  function  breaks  the connection on the
  613.             transport.  It  is  similar  to  the  socket   function
  614.             shutdown().
  615.  
  616.           +o int TRANS(Close)(XtransConnInfo connection)
  617.  
  618.             This  function  closes  the  transport, unbinds it, and
  619.             frees  all  resources  that  was  associated  with  the
  620.             transport.  If a TRANS(Disconnect) call was not made on
  621.             the connection, a disorderly disconnect may occur.
  622.  
  623.           +o int TRANS(IsLocal)(XtransConnInfo connection)
  624.  
  625.             Returns TRUE if it is a local transport.
  626.  
  627.           +o int TRANS(GetMyAddr)(XtransConnInfo connection,
  628.                  int *familyp, int *addrlenp, Xtransaddr **addrp)
  629.  
  630.             This  function  is  similar  to   getsockname().   This
  631.             function  will  allocate  space  for the address, so it
  632.             must be freed by the caller.  Not all  transports  will
  633.             have a valid address until a connection is established.
  634.             This function should not be used until  the  connection
  635.             is established with Connect() or Accept().
  636.  
  637.           +o int TRANS(GetPeerAddr)(XtransConnInfo connection,
  638.                  int *familyp, int *addrlenp, Xtransaddr **addrp)
  639.  
  640.             This   function  is  similar  to  getpeername().   This
  641.             function will allocate space for  the  address,  so  it
  642.             must  be  freed by the caller.  Not all transports will
  643.             have a valid address until a connection is established.
  644.             This  function  should not be used until the connection
  645.             is established with Connect() or Accept().
  646.  
  647.           +o int           TRANS(GetConnectionNumber)(XtransConnInfo
  648.             connection)
  649.  
  650.             Returns   the  file  descriptor  associated  with  this
  651.             transport.
  652.  
  653.           +o int TRANS(MakeAllCOTSServerListeners)(
  654.                  char  *port,  int  *partial_ret,  int  *count_ret,
  655.             XtransConnInfo **connections_ret)
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.             This  function  should be used by most servers. It will
  669.             try to  establish  a  COTS  server  endpoint  for  each
  670.             transport  listed  in the transport table.  _p_a_r_t_i_a_l___r_e_t
  671.             will be set to True if only a partial network could  be
  672.             created.    _c_o_u_n_t___r_e_t   is  the  number  of  transports
  673.             returns, and _c_o_n_n_e_c_t_i_o_n_s___r_e_t is the list of transports.
  674.  
  675.           +o int TRANS(MakeAllCLTSServerListeners)(
  676.                  char  *port,  int  *partial_ret,  int  *count_ret,
  677.             XtransConnInfo **connections_ret)
  678.  
  679.             This function should be used by most servers.  It  will
  680.             try  to  establish  a  CLTS  server  endpoint  for each
  681.             transport listed in the transport  table.   _p_a_r_t_i_a_l___r_e_t
  682.             will  be set to True if only a partial network could be
  683.             created.   _c_o_u_n_t___r_e_t  is  the  number   of   transports
  684.             returns, and _c_o_n_n_e_c_t_i_o_n_s___r_e_t is the list of transports.
  685.        _5_._2  _U_t_i_l_i_t_y _A_P_I
  686.  
  687.        This section describes a few useful functions that have been
  688.        implemented   on  top  of  the  Core  Interface  API.  These
  689.        functions are being provided as a convenience.
  690.  
  691.           +o int TRANS(ConvertAddress)(int *familyp, int  *addrlenp,
  692.             Xtransaddr *addrp)
  693.  
  694.             This function converts a sockaddr based address to an X
  695.             authorization based address (ie AF_INET, AF_UNIX to the
  696.             X     protocol     definition    (ie    FamilyInternet,
  697.             FamilyLocal)).
  698.  
  699.        _6_.  _T_r_a_n_s_p_o_r_t _O_p_t_i_o_n _D_e_f_i_n_i_t_i_o_n
  700.  
  701.        The following options are defined for the TRANS(SetOption)()
  702.        function.  If  an  OS  or  transport does not support any of
  703.        these options, then it will silently ignore the option.
  704.  
  705.           +o TRANS_NONBLOCKING
  706.  
  707.             This  option  controls  the  blocking   mode   of   the
  708.             connection.  If  the  argument  is  set  to 1, then the
  709.             connection will be set to blocking. If the argument  is
  710.             set  to  0,  then  the  connection  will be set to non-
  711.             blocking.
  712.  
  713.           +o TRANS_CLOSEONEXEC
  714.  
  715.             This  option  determines  what  will  happen   to   the
  716.             connection when an exec is encountered. If the argument
  717.             is set to 1, then the connection will be closed when an
  718.             exec  occurs.  If  the  argument  is set to 0, then the
  719.             connection will not be closed when an exec occurs.
  720.        _7_.  _H_i_d_d_e_n _T_r_a_n_s_p_o_r_t _D_e_p_e_n_d_e_n_t _A_P_I
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.        The hidden transport dependent functions are placed  in  the
  735.        Xtransport  record.   These  function  are  similar  to  the
  736.        Exposed  Transport  Independent  API,  but   some   of   the
  737.        parameters  and return values are slightly different.  Stuff
  738.        like the #ifdef  SUNSYSV  should  be  handled  inside  these
  739.        functions.
  740.  
  741.           +o XtransConnInfo *OpenCOTSClient (
  742.                  struct  _Xtransport  *thistrans,  char  *protocol,
  743.             char *host, char *port)
  744.  
  745.             This function creates a Connection-Oriented  Transport.
  746.             The  parameter  _t_h_i_s_t_r_a_n_s points to an Xtransport entry
  747.             in the transport table. The parameters _p_r_o_t_o_c_o_l,  _h_o_s_t,
  748.             and  _p_o_r_t point to strings containing the corresponding
  749.             parts   of   the   address   that   was   passed   into
  750.             TRANS(OpenCOTSClient)().
  751.  
  752.             This function must allocate and initialize the contents
  753.             of the XtransConnInfo structure  that  is  returned  by
  754.             this  function.  This function will open the transport,
  755.             and bind it into the transport namespace if applicable.
  756.             The   local   address  portion  of  the  XtransConnInfo
  757.             structure will also be filled in by this function.
  758.  
  759.           +o XtransConnInfo *OpenCOTSServer (
  760.                  struct  _Xtransport  *thistrans,  char  *protocol,
  761.             char *host, char *port)
  762.  
  763.             This  function creates a Connection-Oriented Transport.
  764.             The parameter _t_h_i_s_t_r_a_n_s points to an  Xtransport  entry
  765.             in  the transport table. The parameters _p_r_o_t_o_c_o_l, _h_o_s_t,
  766.             and _p_o_r_t point to strings containing the  corresponding
  767.             parts   of   the   address   that   was   passed   into
  768.             TRANS(OpenCOTSClient)().
  769.  
  770.             This function must allocate and initialize the contents
  771.             of  the  XtransConnInfo  structure  that is returned by
  772.             this function. This function will open the transport.
  773.  
  774.           +o XtransConnInfo *OpenCLTSClient (
  775.                  struct  _Xtransport  *thistrans,  char  *protocol,
  776.             char *host, char *port)
  777.  
  778.             This  function creates a Connection-Less Transport. The
  779.             parameter _t_h_i_s_t_r_a_n_s points to an  Xtransport  entry  in
  780.             the transport table. The parameters _p_r_o_t_o_c_o_l, _h_o_s_t, and
  781.             _p_o_r_t point  to  strings  containing  the  corresponding
  782.             parts   of   the   address   that   was   passed   into
  783.             TRANS(OpenCOTSClient)().
  784.  
  785.             This function must allocate and initialize the contents
  786.             of  the  XtransConnInfo  structure  that is returned by
  787.             this function. This function will open  the  transport,
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.             and bind it into the transport namespace if applicable.
  801.             The  local  address  portion  of   the   XtransConnInfo
  802.             structure will also be filled in by this function.
  803.  
  804.           +o XtransConnInfo *OpenCLTSServer (
  805.                  struct  _Xtransport  *thistrans,  char  *protocol,
  806.             char *host, char *port)
  807.  
  808.             This function creates a Connection-Less Transport.  The
  809.             parameter  _t_h_i_s_t_r_a_n_s  points  to an Xtransport entry in
  810.             the transport table. The parameters _p_r_o_t_o_c_o_l, _h_o_s_t, and
  811.             _p_o_r_t  point  to  strings  containing  the corresponding
  812.             parts   of   the   address   that   was   passed   into
  813.             TRANS(OpenCOTSClient)().
  814.  
  815.             This function must allocate and initialize the contents
  816.             of the XtransConnInfo structure  that  is  returned  by
  817.             this function. This function will open the transport.
  818.  
  819.           +o int   SetOption  (struct  _Xtransport  *thistrans,  int
  820.             option, int arg)
  821.  
  822.             This function provides a  transport  dependent  way  of
  823.             implementing  the  options  defined  by the X Transport
  824.             Interface. In the current prototype, this  function  is
  825.             not  being  used,  because all of the option defined so
  826.             far, are transport independent. This function will have
  827.             to  be  used if a radically different transport type is
  828.             added, or a transport dependent option is defined.
  829.  
  830.           +o int CreateListener (struct _Xtransport *thistrans, char
  831.             *port )
  832.  
  833.             This  function  takes a transport endpoint opened for a
  834.             server,  and  sets  it  up  to  listen   for   incoming
  835.             connection  requests. The parameter _p_o_r_t should contain
  836.             the port portion of the address that was passed to  the
  837.             Open function.
  838.  
  839.             This   function   will  bind  the  transport  into  the
  840.             transport name space if applicable,  and  fill  in  the
  841.             local  address portion of the XtransConnInfo structure.
  842.             The transport endpoint will then be set to  listen  for
  843.             incoming connection requests.
  844.  
  845.           +o int ResetListener (struct _Xtransport *thistrans)
  846.  
  847.             This function resets the transport for listening.
  848.  
  849.           +o XtransConnInfo Accept(struct _Xtransport *thistrans)
  850.  
  851.             This  function  creates  a  new transport endpoint as a
  852.             result of an incoming connection request. The parameter
  853.             _t_h_i_s_t_r_a_n_s is the endpoint that was opened for listening
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.             by the server. The new endpoint  is  opened  and  bound
  867.             into   the   transport's  namespace.  A  XtransConnInfo
  868.             structure describing the new endpoint is returned  from
  869.             this function
  870.  
  871.           +o int  Connect(struct _Xtransport *thistrans, char *host,
  872.             char *port )
  873.  
  874.             This function establishes a connection to a server. The
  875.             parameters  _h_o_s_t  and _p_o_r_t describe the server to which
  876.             the connection should be  established.  The  connection
  877.             will be established so that Read() and Write() call can
  878.             be made.
  879.  
  880.           +o int   BytesReadable(struct   _Xtransport    *thistrans,
  881.             BytesReadable_t *pend )
  882.  
  883.             This  function replaces the BytesReadable() macro. This
  884.             allows each transport to have it's  own  mechanism  for
  885.             determining how much data is ready to be read.
  886.  
  887.           +o int  Read(struct _Xtransport *thistrans, char *buf, int
  888.             size )
  889.  
  890.             This function  reads  _s_i_z_e  bytes  into  _b_u_f  from  the
  891.             connection.
  892.  
  893.           +o int Write(struct _Xtransport *thistrans, char *buf, int
  894.             size )
  895.  
  896.             This  function  writes  _s_i_z_e  bytes  from  _b_u_f  to  the
  897.             connection.
  898.  
  899.           +o int  Readv(struct  _Xtransport *thistrans, struct iovec
  900.             *buf, int size )
  901.  
  902.             This function performs a readv() on the connection.
  903.  
  904.           +o int Writev(struct _Xtransport *thistrans, struct  iovec
  905.             *buf, int size )
  906.  
  907.             This function performs a writev() on the connection.
  908.  
  909.           +o int Disconnect(struct _Xtransport *thistrans)
  910.  
  911.             This  function  initiates  an  orderly  shutdown  of  a
  912.             connection. If a transport does not distinguish between
  913.             orderly and disorderly disconnects, then a call to this
  914.             function will have no affect.
  915.  
  916.           +o int Close(struct _Xtransport *thistrans)
  917.  
  918.             This function will break the connection, and close  the
  919.             endpoint.
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.        _8_.  _C_o_n_f_i_g_u_r_a_t_i_o_n
  933.  
  934.        The   implementation  of  each  transport  can  be  platform
  935.        specific. It is expected that existing connection types such
  936.        as  TCPCONN,  UNIXCONN,  LOCALCONN  and  STREAMSCONN will be
  937.        replaced with flags for each possible transport type.
  938.  
  939.        Below are the flags that can be set  in  _C_o_n_n_e_c_t_i_o_n_F_l_a_g_s  in
  940.        the vendor.cf or site.def config files.
  941.  
  942.        TCPCONN       Enables the INET Domain Socket based transport
  943.        UNIXCONN      Enables the UNIX Domain Sokcet based transport
  944.        STREAMSCONN   Enables the TLI based transports
  945.        LOCALCONN     Enables the SYSV Local connection transports
  946.        DNETCONN      Enables the DECnet transports
  947.        _9_.  _T_r_a_n_s_p_o_r_t _S_p_e_c_i_f_i_c _D_e_f_i_n_i_t_i_o_n_s
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.        +---------+------------------------------------------------------------------+
  999.        |PPrroottooccooll |                        AAddddrreessss CCoommppoonneenntt                         |
  1000.        |         +----------+--------------------------------------+----------------+
  1001.        |FFaammiillyy   | pprroottooccooll |                 hhoosstt                 |      ppoorrtt      |
  1002.        +---------+----------+--------------------------------------+----------------+
  1003.        |Internet | inet     | name of an internet addressable host | string         |
  1004.        |         | tcp      |                                      | containing     |
  1005.        |         | udp      |                                      | the  name of   |
  1006.        |         |          |                                      | a service or   |
  1007.        |         |          |                                      | a valid port   |
  1008.        |         |          |                                      | number.        |
  1009.        |         |          |                                      | Example:       |
  1010.        |         |          |                                      | "xserver0",    |
  1011.        |         |          |                                      | "7100"         |
  1012.        +---------+----------+--------------------------------------+----------------+
  1013.        |DECnet   | decnet   | name of a DECnet addressable host    | string         |
  1014.        |         |          |                                      | containing     |
  1015.        |         |          |                                      | the complete   |
  1016.        |         |          |                                      | name  of the   |
  1017.        |         |          |                                      | object.        |
  1018.        |         |          |                                      | Example:       |
  1019.        |         |          |                                      | "X$X0"         |
  1020.        +---------+----------+--------------------------------------+----------------+
  1021.        |NETware  | ipx      | name of a NETware addressable host   | Not  sure of   |
  1022.        |         |          |                                      | the            |
  1023.        |         |          |                                      | specifics      |
  1024.        |         |          |                                      | yet.           |
  1025.        +---------+----------+--------------------------------------+----------------+
  1026.        |OSI      | osi      | name of an OSI addressable host      | Not sure  of   |
  1027.        |         |          |                                      | the            |
  1028.        |         |          |                                      | specifics      |
  1029.        |         |          |                                      | yet.           |
  1030.        +---------+----------+--------------------------------------+----------------+
  1031.        |Local    | local    | (ignored)                            | String         |
  1032.        |         | pts      |                                      | containing     |
  1033.        |         | named    |                                      | the     port   |
  1034.        |         | sco      |                                      | name,     ie   |
  1035.        |         | isc      |                                      | "xserver0",    |
  1036.        |         |          |                                      | "fontserver0". |
  1037.        +_1-_0-_.---_I-_m-_p-_l-_e+_m-_e-_n-_t-_a-_t-_i-_o-_n--_N+_o-_t-_e-_s-----------------------------------+----------------+
  1038.  
  1039.        This  section refers to the prototype implementation that is
  1040.        being  developed  concurrently  with  this  document.   This
  1041.        prototype  has  been  able  to  flush  out  many details and
  1042.        problems as the specification was being developed.
  1043.  
  1044.        All of the source code for  this  interface  is  located  in
  1045.        xc/lib/xtrans.
  1046.  
  1047.        All  functions  names  in  the  source  are  of  the  format
  1048.        TRANS(func)(). The TRANS() macro is defined as
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.        #if (__STDC__ && !defined(UNIXCPP)) || defined(ANSICPP)
  1065.        #define TRANS(func) _PROTOCOLTrans##func
  1066.        #else
  1067.        #define TRANS(func) _PROTOCOLTrans/**/func
  1068.        #endif
  1069.  
  1070.  
  1071.        PROTOCOL will be uniquely defined in  each  directory  where
  1072.        this  code  is  compiled. PROTOCOL will be defined to be the
  1073.        name of the protocol that is implemented by the  library  or
  1074.        server, such as X11, FS, and ICE.
  1075.  
  1076.        All libraries and servers that use the X Transport Interface
  1077.        should have a new file called transport.c.  This  file  will
  1078.        include  the  transports  based  on  the configuration flags
  1079.        _C_o_n_n_e_c_t_i_o_n_F_l_a_g_s. Below is an example transport.c.
  1080.  
  1081.        #include "Xtransint.h"
  1082.  
  1083.        #ifdef DNETCONN
  1084.        #include "Xtransdnet.c"
  1085.        #endif
  1086.        #ifdef LOCALCONN
  1087.        #include "Xtranslocal.c"
  1088.        #endif
  1089.        #ifdef TCPCONN
  1090.        #include "Xtranssock.c"
  1091.        #endif
  1092.        #ifdef STREAMSCONN
  1093.        #include "Xtranstli.c"
  1094.        #endif
  1095.        #include "Xtrans.c"
  1096.        #include "Xtransutil.c"
  1097.  
  1098.        The source files for this interface are listed below.
  1099.  
  1100.        Xtrans.h        Function prototypes and defines for
  1101.                        the Transport Independent API.
  1102.        Xtransint.h     Used by the interface implementation only.
  1103.                        Contains the internal data structures.
  1104.        Xtranssock.c    Socket implementation of the Transport Dependent API.
  1105.        Xtranstli.c     TLI implementation of the Transport Dependent API.
  1106.        Xtransdnet.c    DECnet implementation of the Transport Dependent API.
  1107.        Xtranslocal.c   Implementation of the Transport Dependent API for
  1108.                        SYSV Local connections.
  1109.        Xtrans.c        Exposed Transport Independent API Functions.
  1110.        Xtransutil.c    Collection of Utility functions that use the
  1111.                        X Transport Interface.
  1112.  
  1113.        The file _X_t_r_a_n_s_i_n_t_._h contains much of the transport  related
  1114.        code  that  previously in Xlibint.h and Xlibnet.h. This will
  1115.        make the definitions available for all transport users. This
  1116.        should also obsolete the equivilent code in other libraries.
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.