Docs

Appearance

Chapter 5. Exposed Transport Independent API

Table of Contents

Core Interface API
Utility API

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.

Core Interface API

  • XtransConnInfo TRANS(OpenCOTSClient)(char *address)

    This function creates a Connection-Oriented Transport that is suitable for use by a client. The parameter address contains the full address of the server to which this endpoint will be connected. This functions returns an opaque transport connection object on success, or NULL on failure.

  • XtransConnInfo TRANS(OpenCOTSServer)(char *address)

    This function creates a Connection-Oriented Transport that is suitable for use by a server. The parameter address contains the full address to which this server will be bound. This functions returns an opaque transport connection object on success, or NULL on failure.

  • XtransConnInfo TRANS(OpenCLTSClient)(char *address)

    This function creates a Connection-Less Transport that is suitable for use by a client. The parameter address contains the full address of the server to which this endpoint will be connected. This functions returns an opaque transport connection object on success, or NULL on failure.

  • XtransConnInfo TRANS(OpenCLTSServer)(char *address)

    This function creates a Connection-Less Transport that is suitable for use by a server. The parameter address contains the full address to which this server will be bound. This functions returns an opaque transport connection object on success, or NULL on failure.

  • int TRANS(SetOption)(XtransConnInfo connection, int option, int arg)

    This function sets transport options, similar to the way setsockopt() and ioctl() work. The parameter connection is an endpoint that was obtained from _XTransOpen*() functions. The parameter option contains the option that will be set. The actual values for option are defined in a later section. The parameter arg can be used to pass in an additional value that may be required by some options. This function return 0 on success and -1 on failure.

    Note

    Based on current usage, the complimentary function TRANS(GetOption) is not necessary.

  • int TRANS(CreateListener)(XtransConnInfo connection, char *port, int flags)

    This function sets up the server endpoint for listening. The parameter connection is an endpoint that was obtained from TRANS(OpenCOTSServer)() or TRANS(OpenCLTSServer)(). The parameter port specifies the port to which this endpoint should be bound for listening. If port is NULL, then the transport may attempt to allocate any available TSAP for this connection. If the transport cannot support this, then this function will return a failure. The flags parameter can be set to ADDR_IN_USE_ALLOWED to allow the call to the underlying binding function to fail with a EADDRINUSE error without causing the TRANS(CreateListener) function itself to fail. This function return 0 on success and -1 on failure.

  • int TRANS(ResetListener)(XtransConnInfo connection)

    When a server is restarted, certain listen ports may need to be reset. For example, unix domain needs to check that the file used for communication has not been deleted. If it has, it must be recreated. The parameter connection is an opened and bound endpoint that was obtained from TRANS(OpenCOTSServer)() and passed to TRANS(CreateListener)(). This function will return one of the following values: TRANS_RESET_NOOP, TRANS_RESET_NEW_FD, or TRANS_RESET_FAILURE.

  • XtransConnInfo TRANS(Accept)(XtransConnInfo connection)

    Once a connection indication is received, this function can be called to accept the connection. The parameter connection is an opened and bound endpoint that was obtained from TRANS(OpenCOTSServer)() and passed to TRANS(CreateListener)(). This function will return a new opaque transport connection object upon success, NULL otherwise.

  • int TRANS(Connect)(XtransConnInfo connection, char *address)

    This function creates a connection to a server. The parameter connection is an endpoint that was obtained from TRANS(OpenCOTSClient)(). The parameter address specifies the TSAP to which this endpoint should connect. If the protocol is included in the address, it will be ignored. This function return 0 on success and -1 on failure.

  • int TRANS(BytesReadable)(XtransConnInfo connection, BytesReadable_t *pend);

    This function provides the same functionality as the BytesReadable macro.

  • int TRANS(Read)(XtransConnInfo connection, char *buf, int size)

    This function will return the number of bytes requested on a COTS connection, and will return the minimum of the number bytes requested or the size of the incoming packet on a CLTS connection.

  • int TRANS(Write)(XtransConnInfo connection, char *buf, int size)

    This function will write the requested number of bytes on a COTS connection, and will send a packet of the requested size on a CLTS connection.

  • int TRANS(Readv)(XtransConnInfo connection, struct iovec *buf, int size)

    Similar to TRANS(Read)().

  • int TRANS(Writev)(XtransConnInfo connection, struct iovec *buf, int size)

    Similar to TRANS(Write)().

  • int TRANS(Disconnect)(XtransConnInfo connection)

    This function is used when an orderly disconnect is desired. This function breaks the connection on the transport. It is similar to the socket function shutdown().

  • int TRANS(Close)(XtransConnInfo connection)

    This function closes the transport, unbinds it, and frees all resources that was associated with the transport. If a TRANS(Disconnect) call was not made on the connection, a disorderly disconnect may occur.

  • int TRANS(IsLocal)(XtransConnInfo connection)

    Returns TRUE if it is a local transport.

  • int TRANS(GetMyAddr)(XtransConnInfo connection, int *familyp, int *addrlenp, Xtransaddr **addrp)

    This function is similar to getsockname(). This function will allocate space for the address, so it must be freed by the caller. Not all transports will have a valid address until a connection is established. This function should not be used until the connection is established with Connect() or Accept().

  • int TRANS(GetPeerAddr)(XtransConnInfo connection, int *familyp, int *addrlenp, Xtransaddr **addrp)

    This function is similar to getpeername(). This function will allocate space for the address, so it must be freed by the caller. Not all transports will have a valid address until a connection is established. This function should not be used until the connection is established with Connect() or Accept().

  • int TRANS(GetConnectionNumber)(XtransConnInfo connection)

    Returns the file descriptor associated with this transport.

  • int TRANS(MakeAllCOTSServerListeners)(char *port, int *partial_ret, int *count_ret, XtransConnInfo **connections_ret)

    This function should be used by most servers. It will try to establish a COTS server endpoint for each transport listed in the transport table. partial_ret will be set to True if only a partial network could be created. count_ret is the number of transports returned, and connections_ret is the list of transports.

  • int TRANS(MakeAllCLTSServerListeners)( char *port, int *partial_ret, int *count_ret, XtransConnInfo **connections_ret)

    This function should be used by most servers. It will try to establish a CLTS server endpoint for each transport listed in the transport table. partial_ret will be set to True if only a partial network could be created. count_ret is the number of transports returned, and connections_ret is the list of transports.

Utility API

This section describes a few useful functions that have been implemented on top of the Core Interface API. These functions are being provided as a convenience.

  • int TRANS(ConvertAddress)(int *familyp, int *addrlenp, Xtransaddr *addrp)

    This function converts a sockaddr based address to an X authorization based address (ie AF_INET, AF_UNIX to the X protocol definition (ie FamilyInternet, FamilyLocal)).