The X Transport Interface is intended to combine all system and transport specific code into a single place in the source tree. This API should be used by all libraries, clients and servers of the X Window System. Use of this API should allow the addition of new types of transports and support for new platforms without making any changes to the source except in the X Transport Interface code.

This interface should solve the problem of multiple #ifdef TRANSPORT and #ifdef PLATFORM statements scattered throughout the source tree.

This interface should provide enough functionality to support all types of protocols, including connection oriented protocols such as X11 and FS, and connection-less oriented protocols such as XDMCP.

The interface provides an API for use by applications. The functions in this API perform work that is common to all transports and systems, such as parsing an address into a host and port number. The functions in this API call transport specific functions that are contained in a table whose contents are defined at compile time. This table contains an entry for each type of transport. Each entry is a record containing mostly pointers to function that implements the interface for the given transport.

This API does not provide an abstraction for select() or poll(). These functions are themselves transport independent, so an additional interface is not needed for these functions. It is also unclear how such an interface would affect performance.

Addresses are specified in the following syntax,

protocol/host:port

where protocol specifies a protocol family or an alias for a protocol family. A definition of common protocol families is given in a later section.

The host part specifies the name of a host or other transport dependent entity that could be interpreted as a Network Service Access Point (NSAP).

The port part specifies the name of a Transport Service Access Point (TSAP). The format of the TSAP is defined by the underlying transport implementation, but it is represented using a string format when it is part of an address.

There are two major data structures associated with the transport independent portion of this interface. Additional data structures may be used internally by each transport.

typedef struct _Xtransport {

    const char *TransName;
    int  flags;

    XtransConnInfo (*OpenCOTSClient)(
     struct _Xtransport *,    /* transport */
     const char *,            /* protocol */
     const char *,            /* host */
     const char *             /* port */
    );

    XtransConnInfo (*OpenCOTSServer)(
     struct _Xtransport *,    /* transport */
     const char *,            /* protocol */
     const char *,            /* host */
     const char *             /* port */
    );

    int     (*SetOption)(
     XtransConnInfo,          /* connection */
     int,               /* option */
     int               /* arg */
    );

    int     (*CreateListener)(
     XtransConnInfo,          /* connection */
     const char *,            /* port */
     int                      /* flags */
    );

    int     (*ResetListener)(
     XtransConnInfo          /* connection */
    );

    XtransConnInfo (*Accept)(
     XtransConnInfo          /* connection */
    );

    int     (*Connect)(
     XtransConnInfo,          /* connection */
     const char *,            /* host */
     const char *             /* port */
    );

    int     (*BytesReadable)(
     XtransConnInfo,          /* connection */
     BytesReadable_t *     /* pend */
    );

    int     (*Read)(
     XtransConnInfo,          /* connection */
     char *,               /* buf */
     int               /* size */
    );

    int     (*Write)(
     XtransConnInfo,          /* connection */
     char *,               /* buf */
     int               /* size */
    );

    int     (*Readv)(
     XtransConnInfo,          /* connection */
     struct iovec *,          /* buf */
     int               /* size */
    );

    int     (*Writev)(
     XtransConnInfo,          /* connection */
     struct iovec *,          /* buf */
     int               /* size */
    );

    int     (*Disconnect)(
     XtransConnInfo          /* connection */
    );

    int     (*Close)(
     XtransConnInfo          /* connection */
    );

} Xtransport;

typedef struct _XtransConnInfo *XtransConnInfo;

struct _XtransConnInfo {
    struct _Xtransport     *transptr;
    char     *priv;
    int          flags;
    int          fd;
    int          family;
    char     *addr;
    int          addrlen;
    char     *peeraddr;
    int          peeraddrlen;
};

This API is included in each library and server that uses it. The API may be used by the library, but it is not added to the public API for that library. This interface is simply an implementation facilitator. This API contains a low level set of core primitives, and a few utility functions that are built on top of the primitives. The utility functions exist to provide a more familiar interface that can be used to port existing code.

A macro is defined in Xtrans.h for TRANS(func) that creates a unique function name depending on where the code is compiled. For example, when built for Xlib, TRANS(OpenCOTSClient) becomes _X11TransOpenCOTSClient.

All failures are considered fatal, and the connection should be closed and re-established if desired. In most cases, however, the value of errno will be available for debugging purposes.

The following options are defined for the TRANS(SetOption)() function. If an OS or transport does not support any of these options, then it will silently ignore the option.

The hidden transport dependent functions are placed in the Xtransport record. These function are similar to the Exposed Transport Independent API, but some of the parameters and return values are slightly different. Stuff like the #ifdef SUNSYSV should be handled inside these functions.

The implementation of each transport can be platform specific. It is expected that existing connection types such as TCPCONN, UNIXCONN, LOCALCONN, and STREAMSCONN will be replaced with flags for each possible transport type.

In X11R6, the below flags to enable transport types were set in ConnectionFlags in the vendor.cf or site.def config files.

In X11R7 modular releases, these flags are set when running configure scripts which include the XTRANS_CONNECTION_FLAGS macro from xtrans.m4.

This section refers to the prototype implementation that is being developed concurrently with this document. This prototype has been able to flush out many details and problems as the specification was being developed.

In X11R6, all of the source code for this interface was located in xc/lib/xtrans.

In X11R7, all of the source code for this interface is delivered via the lib/libxtrans modular package from X.Org, and is installed under ${prefix}/X11/Xtrans so that other modules may find it when they build.

All functions names in the source are of the format TRANS(func)(). The TRANS() macro is defined as

#define TRANS(func) _PROTOCOLTrans##func

PROTOCOL will be uniquely defined in each directory where this code is compiled. PROTOCOL will be defined to be the name of the protocol that is implemented by the library or server, such as X11, FS, and ICE.

All libraries and servers that use the X Transport Interface should have a new file called TRANSPORTtrans.c. This file will include the transports based on the configuration flags provided by the configure script. Below is an example xfstrans.c for the font server.

#include "config.h"

#define FONT_t 1
#define TRANS_REOPEN 1
#define TRANS_SERVER 1

#include <X11/Xtrans/transport.c>

The source files for this interface are listed below.

The file Xtransint.h contains much of the transport related code that was previously in Xlibint.h and Xlibnet.h. This will make the definitions available for all transport users. This should also obsolete the equivalent code in other libraries.