Connection Library [Library xconnect: include | src]

The overview for this chapter consists of the following topics:

• Introduction

• Chapter Outline

The NCBI C++ platform-independent connection library (src/connect and include/connect) consists of two parts:

• Lower-level library written in C (also used as a replacement of the existing connection library in the NCBI C Toolkit)

• Upper-level library written in C++ and using C++ streams

Functionality of the library includes:

• SOCK interface (sockets), which works interchangeably on most UNIX varieties, MS Windows, and Mac

• SERV interface, which provides mapping of symbolic service names into server addresses

• CONN interface, which allows the creation of a connection, the special object capable to do read, write, etc. I/O operations

• C++ streams built on top of the CONN interface

Note: The lowest level (SOCK) interface is not covered in this document. A well-commented API can be found in connect/ncbi_socket.h.

There are three simple types of connections: socket, file and http; and one hybrid type, service connection.

A connection is created with a call to CONN_Create(), declared in connect/ncbi_connection.h, and returned by a pointer to CONN passed as a second argument:

CONN conn; /* connection handle */
EIO_Status status = CONN_Create(connector, &conn);

The first argument of this function is a handle of a connector, a special object implementing functionality of the connection being built. Above, for each type of connection there is a special connector in the library. For each connector, one or more "constructors" are defined, each returning the connector's handle. Connectors' constructors are defined in individual header files, such as connect/ncbi_socket_connector.h, connect/ncbi_http_connector.h, connect/ncbi_service_connector.h, etc. CONN_Create() resets all timeouts to the default value kDefaultTimeout.

After successful creation with CONN_Create(), the following calls from CONN API connect/ncbi_connection.h become available. All calls (except CONN_GetTimeout() and CONN_GetType() ) return an I/O completion status of type EIO_Status. Normal completion has code eIO_Success.

Note: There is no means to "open" a connection: it is done automatically when actually needed, and in most cases at the first I/O operation. But the forming of an actual link between source and destination can be postponed even longer. These details are hidden and made transparent to the connection's user. The connection is seen as a two-way communication channel, which is clear for use immediately after a call to CONN_Create().

Note: If for some reason CONN_Create() failed to create a connection (return code differs from eIO_Success), then the connector passed to this function is left intact, that is, its handle can be used again. Otherwise, if the connection is created successfully, the passed connector handle becomes invalid and cannot be referenced anywhere else throughout the program (with one exception, however: it may be used as a replacing connector in a call to CONN_ReInit() for the same connection).

Note: There are no "destructors" on public connectors. A connector successfully put into connection is deleted automatically, along with that connection by CONN_Close(), or explicitly with a call to CONN_ReInit(), provided that the replacing connector is NULL or different from the original.

Read or peek data, depending on read method how, up to size bytes from connection to specified buffer buf, return (via pointer argument n_read) the number of bytes actually read. The last argument how can be one of the following:

• eIO_ReadPlain - to read data in a regular way, that is, extracting data from the connection;

• eIO_ReadPeek - to peek data from the connection, i.e., the next read operation will see the data again;

• eIO_ReadPersist - to read exactly (not less than) size bytes or until an error condition occurs.

A return value other than eIO_Success means trouble. Specifically, the return value eIO_Timeout indicates that the operation could not be completed within the allotted amount of time; but some data may, however, be available in the buffer (e.g., in case of persistent reading, as with eIO_ReadPersist), and this is actually the case for any return code.

Read up to size bytes from connection into the string buffer pointed to by line. Stop reading if either '\n' or an error is encountered. Replace '\n' with '\0'. Upon return *n_read contains the number of characters written to line, not including the terminating '\0'. If not enough space provided in line to accomodate the '\0'-terminated line, then all size bytes are used up and *n_read is equal to size upon return - this is the only case when line will not be '\0'-terminated.

Return code advises the caller whether another read can be attempted:

• eIO_Success -- read completed successfully, keep reading;

• other code -- an error occurred, and further attempt may fail.

This call utilizes eIO_Read timeout as set by CONN_SetTimeout().

Write up to size bytes from the buffer buf to the connection. Return the number of actually written bytes in n_written. It may not return eIO_Success if no data at all can be written before the write timeout expired or an error occurred. Parameter how modifies the write behavior:

• eIO_WritePlain - return immediately after having written as little as 1 byte of data, or if an error has occurred;

• eIO_WritePersist - return only after having written all of the data from buf (eIO_Success), or if an error has occurred (fewer bytes written, non-eIO_Success).

Note: See CONN_SetTimeout() for how to set the write timeout.

Push back size bytes from the buffer buf into connection. Return eIO_Success on success, other code on error.

Note 1: The data pushed back may not necessarily be the same as previously obtained from the connection.

Note 2: Upon a following read operation, the pushed back data are taken out first.

Get read (event == eIO_Read) or write (event == eIO_Write) position within the connection. Positions are advanced from 0 on, and only concerning I/O that has caused calling to the actual connector's "read" (i.e. pushbacks never considered, and peeks -- not always) and "write" methods. Special case: eIO_Open as event causes to clear both positions with 0, and to return 0.

Explicitly flush connection from any pending data written by CONN_Write().

Note 1: CONN_Flush() effectively opens connection (if it wasn't open yet).

Note 2: Connection considered open if underlying connector's "Open" method has successfully executed; an actual data link may not yet exist.

Note 3: CONN_Read() always calls CONN_Flush() before proceeding; so does CONN_Close() but only if the connection is already open.

Set the timeout on the specified I/O action, eIO_Read, eIO_Write, eIO_ReadWrite, eIO_Open, and eIO_Close. The latter two actions are used in a phase of opening and closing the link, respectively. If the connection cannot be read (written, established, closed) within the specified period, eIO_Timeout would result from connection I/O calls. A timeout can be passed as the NULL-pointer. This special case denotes an infinite value for that timeout. Also, a special value kDefaultTimeout may be used for any timeout. This value specifies the timeout set by default for the current connection type.

Obtain (via the return value of type const STimeout*) timeouts set by the CONN_SetTimeout() routine, or active by default (i.e., special value kDefaultTimeout).

Caution: The returned pointer is valid only for the time that the connection handle is valid, i.e., up to a call to CONN_Close().

This function clears the current contents of a connection and places ("immerse") a new connector into it. The previous connector (if any) is closed first (if open), then gets destroyed, and thus must not be referenced again in the program. As a special case, the new connector can be the same connector, which is currently active within the connection. It this case, the connector is not destroyed; instead, it will be effectively re-opened. If the connector passed as NULL, then the conn handle is kept existing but unusable (the old connector closed and destroyed) and can be CONN_ReInit()'ed later. None of the timeouts are touched by this call.

Suspend the program until the connection is ready to perform reading (event =eIO_Read) or writing (event = eIO_Write), or until the timeout (if non-NULL) expires. If the timeout is passed as NULL, then the wait time is indefinite.

Provide the information about recent low-level data exchange in the link. The operation direction has to be specified as either eIO_Read or eIO_Write. The necessity of this call arises from the fact that sometimes the return value of a CONN API function does not really tell that the problem has been detected: suppose, the user peeks data into a 100-byte buffer and gets 10 bytes. The return status eIO_Success signals that those 10 bytes were found in the connection okay. But how do you know whether the end-of-file condition occurred during the last operation? This is where CONN_Status() comes in handy. When inquired about the read operation, return value eIO_Closed denotes that EOF was actually hit while making the peek, and those 10 bytes are in fact the only data left untaken, no more are expected to come.

Close the connection by closing the link (if open), deleting underlying connector(s) (if any) and the connection itself. Regardless of the return status (which may indicate certain problems), the connection handle becomes invalid and cannot be reused.

Cancel the connection's I/O ability. This is not connection closure, but any data extraction or insertion (Read/Write) will be effectively rejected after this call (and eIO_Interrupt will result, same for CONN_Status()). CONN_Close() is still required to release internal connection structures.

Return character string (null-terminated), verbally representing the current connection type, such as "HTTP", "SOCKET", "SERVICE/HTTP", etc. The unknown connection type gets returned as NULL.

Return a human-readable description of the connection as a character '\0'-terminated string. The string is not guaranteed to have any particular format and is intended solely for something like logging and debugging. Return NULL if the connection cannot provide any description information (or if it is in a bad state). Application program must call free() to deallocate space occupied by the returned string when the description is no longer needed.

Set user callback function to be invoked upon an event specified by callback type. The old callback (if any) gets returned via the passed pointer old_cb (if not NULL). Callback structure SCONN_Callback has the following fields: callback function func and void* data. Callback function func should have the following prototype:

typedef void (*FCONN_Callback)(CONN conn, ECONN_Callback type, void* data)

When called, both type of callback and data pointer are supplied. The callback types defined at the time of this writing are:

• eCONN_OnClose

• eCONN_OnRead

• eCONN_OnWrite

• eCONN_OnCancel

The callback function is always called prior to the event happening, e.g., a close callback is called when the connection is about to close.

#include <connect/ncbi_socket_connector.h>

#include <connect/ncbi_socket_connector.h>
#include <connect/ncbi_connection.h>
#define MAX_TRY 3 /* Try to connect this many times before giving up */
unsigned short port = 1234;
CONNECTOR socket_connector = SOCK_CreateConnector("host.foo.com", port,
MAX_TRY);
if (!socket_connector)
    fprintf(stderr, "Cannot create SOCKET connector");
else {
    CONN conn;
    if (CONN_Create(socket_connector, &conn) != eIO_Success)
        fprintf(stderr, "CONN_Create failed");
    else {
        /* Connection created ok, use CONN_... function */
        /* to access the network */
        ...
        CONN_Close(conn);
    }
}

#include <connect/ncbi_file_connector.h>

CONNECTOR file_connector = FILE_CreateConnector("InFile", "OutFile");

/* Network connection related configurable info struct.
 * ATTENTION:  Do NOT fill out this structure (SConnNetInfo) "from scratch"!
 *             Instead, use ConnNetInfo_Create() described below to create
 *             it, and then fix (hard-code) some fields, if really necessary.
 * NOTE1:      Not every field may be fully utilized throughout the library.
 * NOTE2:      HTTP passwords can be either clear text or Base64 encoded values
 *             enclosed in square brackets [] (which are not Base-64 charset).
 *             For encoding / decoding, one can use command line open ssl:
 *             echo "password|base64value" | openssl enc {-e|-d} -base64
 *             or an online tool (search the Web for "base64 online").
 */
typedef struct {
    char            client_host[256]; /* effective client hostname ('\0'=def)*/
    EURLScheme      scheme;           /* only pre-defined types (limited)    */
    char            user[64];         /* username (if specified)             */
    char            pass[64];         /* password (if any)                   */
    char            host[256];        /* host to connect to                  */
    unsigned short  port;             /* port to connect to, host byte order */
    char            path[1024];       /* service: path(e.g. to  a CGI script)*/
    char            args[1024];       /* service: args(e.g. for a CGI script)*/
    EReqMethod      req_method;       /* method to use in the request (HTTP) */
    const STimeout* timeout;          /* ptr to i/o tmo (infinite if NULL)   */
    unsigned short  max_try;          /* max. # of attempts to connect (>= 1)*/
    char            http_proxy_host[256]; /* hostname of HTTP proxy server   */
    unsigned short  http_proxy_port;      /* port #   of HTTP proxy server   */
    char            http_proxy_user[64];  /* http proxy username             */
    char            http_proxy_pass[64];  /* http proxy password             */
    char            proxy_host[256];  /* CERN-like (non-transp) f/w proxy srv*/
    EDebugPrintout  debug_printout;   /* printout some debug info            */
    int/*bool*/     stateless;        /* to connect in HTTP-like fashion only*/
    int/*bool*/     firewall;         /* to use firewall/relay in connects   */
    int/*bool*/     lb_disable;       /* to disable local load-balancing     */
    const char*     http_user_header; /* user header to add to HTTP request  */
    const char*     http_referer;     /* default referrer (when not spec'd)  */

    /* the following field(s) are for the internal use only -- don't touch!  */
    STimeout        tmo;              /* default storage for finite timeout  */
    const char      svc[1];           /* service which this info created for */
} SConnNetInfo;

#include <connect/ncbi_http_connector.h>

CONNECTOR HTTP_CreateConnector(const SConnNetInfo* net_info,
                               const char*         user_header,
                               THCC_Flags          flags);

typedef int/*bool*/ (*FHTTP_ParseHeader)
(const char*         http_header,   /* HTTP header to parse, '\0'-terminated */
 void*               user_data,     /* supplemental user data                */
 int                 server_error   /* != 0 if HTTP error                    */
 );

typedef int/*bool*/ (*FHTTP_Adjust)
(SConnNetInfo*       net_info,      /* net_info to adjust (in place)         */
 void*               user_data,     /* supplemental user data                */
 unsigned int        failure_count  /* how many failures since open          */
 );

typedef void        (*FHTTP_Cleanup)
(void*               user_data      /* supplemental user data for cleanup    */
 );

CONNECTOR HTTP_CreateConnectorEx
(const SConnNetInfo* net_info,
 THTTP_Flags         flags,
 FHTTP_ParseHeader   parse_header,  /* may be NULL, then no addtl. parsing   */
 void*               user_data,     /* user data for HTTP callbacks (CBs)    */
 FHTTP_Adjust        adjust,        /* may be NULL, then no adjustments      */
 FHTTP_Cleanup       cleanup        /* may be NULL, then no cleanup          */
 );

#include <connect/ncbi_service_connector.h>

SERVICE_CreateConnector(const char* service_name);
SERVICE_CreateConnectorEx(/* The registered name of an NCBI service */
                          const                 char* service_name,
                          /* Accepted server types, bitmask */
                          TSERV_Type            types,
                          /* Connection parameters */
                          const SConnNetInfo*   net_info,
                          /* Additional set of parameters, may be NULL */
                          const SSERVICE_Extra* params);

/* Server types
 */
typedef enum {
  fSERV_Ncbid      = 0x01,
  fSERV_Standalone = 0x02,
  fSERV_HttpGet    = 0x04,
  fSERV_HttpPost   = 0x08,
  fSERV_Http       = fSERV_HttpGet | fSERV_HttpPost,
  fSERV_Firewall   = 0x10,
  fSERV_Dns        = 0x20
} ESERV_Type;

#define fSERV_Any           0
#define fSERV_StatelessOnly 0x80
typedef unsigned TSERV_Type;  /* bit-wise OR of "ESERV_Type" flags */

CONNECTOR c;
CONN conn;
if(!(c = SERVICE_CreateConnectorEx("io_bounce", fSERV_StatelessOnly, 0, 0))) {
    fprintf(stderr, "No such service available");
} else if (CONN_Create(c, &conn) != eIO_Success) {
    fprintf(stderr, "Failed to create connection");
} else {
    static const char buffer[] = "Data to pass to the server";
    size_t n_written;
    CONN_Write(conn, buffer, sizeof(buffer) - 1, &n_written);
    ...
}

Each connector (except for the FILE connector) provides a means to view data flow in the connection. In case of the SOCKET connector, debugging information can be turned on by the last argument in SOCK_CreateConnectorEx() or by using the global routine SOCK_SetDataLoggingAPI() (declared in connect/ncbi_socket.h)

Note: In the latter case, every socket (including sockets implicitly used by other connectors such as HTTP or SERVICE) will generate debug printouts.

In case of HTTP or SERVICE connectors, which use SConnNetInfo, debugging can be activated directly from the environment by setting CONN_DEBUG_PRINTOUT to TRUE or SOME. Similarly, a registry key DEBUG_PRINTOUT with a value of either TRUE or SOME found in the section [CONN] will have the same effect: it turns on logging of the connection parameters each time the link is established. When set to ALL, this variable (or key) also turns on debugging output on all underlying sockets ever created during the life of the connection. The value FALSE (default) turns debugging printouts off. Moreover, for the SERVICE connector, the debugging output option can be set on a per-service basis using <service>_CONN_DEBUG_PRINTOUT environment variables or individual registry sections [<service>] and the key CONN_DEBUG_PRINTOUT in them.

Note: Debugging printouts can only be controlled in a described way via environment or registry if and only if SConnNetInfo is always created with the use of convenience routines.

Debugging output is always sent to the same destination, the CORE log file, which is a C object shared between both C and C++ Toolkits. As said previously, the logger is an abstract object, i.e. it is empty and cannot produce any output if not populated accordingly. The library defines a few calls gathered in connect/ncbi_util.h, which allow the logger to output via the FILE file pointer, such as stderr: CORE_SetLOGFILE() for example, as shown in test_ncbi_service_connector.c, or to be a regular file on disk. Moreover, both Toolkits define interfaces to deal with registries, loggers, and locks that use native objects of each toolkit and use them as replacements for the objects of the corresponding abstract layers.

There is a common problem that has been reported several times and actually concerns network configuration rather than representing a malfunction in the library. If a test program, which connects to a named NCBI service, is not getting anything back from the NCBI site, one first has to check whether there is a transparent proxying/caching between the host and NCBI. Because the service dispatching is implemented on top of the ordinary HTTP protocol, the transparent proxying may latch unsuccessful service searches (which can happen and may not indicate a real problem) as error responses from the NCBI server. Afterwards, instead of actually connecting to NCBI, the proxy returns those cached errors (or sometimes just an empty document), which breaks the service dispatcher code. In most cases, there are configurable ways to exclude certain URLs from proxying and caching, and they are subject for discussion with a local network administrator.

Here is another tip: Make sure that all custom HTTP header tags (as passed, for example, in the SConnNetInfo::user_header field) have "\r\n" as tag separators (including the last tag). Many proxy servers (including transparent proxies, of which the user may not even be aware) are known to be sensitive to whether each and every HTTP tag is closed by "\r\n" (and not by a single "\n" character). Otherwise, the HTTP packet may be treated as a defective one and can be discarded.

Additional discussion on parameters of the service dispatcher as well as the trouble shooting tips can be found here.

Using connections and connectors (via the entirely procedural approach) in C++ programs overkills the power of the language. Therefore, we provide C++ users with the stream classes, all derived from a standard iostream class, and as a result, these can be used with all common stream I/O operators, manipulators, etc.

The declarations of the stream's constructors can be found in connect/ncbi_conn_stream.hpp. We tried to keep the same number and order of the constructor's parameters, as they appear in the corresponding connector's constructors in C.

The code below is a C++ style example from the previous section devoted to the service connector:

#include <connect/ncbi_conn_stream.hpp>
try {
    CConn_ServiceStream
    ios("io_bounce", fSERV_StatelessOnly, 0);
    ios << "Data to be passed to the server";
} STD_CATCH_ALL ("Connection problem");

Note: The stream constructor may show an exception if, for instance, the requested service is not found, or some other kind of problem arose. To see the actual reason, we used a standard toolkit macro STD_CATCH_ALL(), which prints the message and problem description into the log file (cerr, by default).

The API defined in connect/ncbi_service.h is designed to map the required service name into the server address. Internally, the mapping is done either directly or indirectly by means of the load-balancing daemon, running at the NCBI site. For the client, the mapping is seen as reading from an iterator created by a call to SERV_Open(), similar to the following fragment (for more examples, please refer to the test program test_ncbi_disp.c):

#include <connect/ncbi_service.h>
SERV_ITER iter = SERV_Open("my_service", fSERV_Any, SERV_ANYHOST, 0);
int n = 0;
if (iter != 0) {
    SSERV_Info * info = SERV_GetNextInfo(iter);
    while (info != 0) {
        char* str = SERV_WriteInfo(info);
        printf("Server = `%s'\n", str);
        free(str);
        n++;
    }
    SERV_Close(iter);
}
if (!iter || !n)
    printf("Service not found\n");

Note: Services can be redirected.

Note: A non-NULL iterator returned from SERV_Open() does not yet guarantee that the service is available, whereas the NULL iterator definitely means that the service does not exist.

As shown in the above example, a loop over reading from the iterator results in the sequence of successive structures (none of which is to be freed by the program!) that along with the conversion functions SERV_ReadInfo(), SERV_WriteInfo() and others are defined in connect/ncbi_server_info.h. Structure SSERV_Info describes a server that implements the requested service. NULL gets returned when no more servers (if any) could be found. The iterator returns servers in the order that the load-balancing algorithm arranges them. Each server has a rating, and the larger the rating the better the chance for the server to be coming out first (but not necessarily in the order of the rates).

Note: Servers returned from the iterator are all of the requested type, with only one exception: they can include servers of type fSERV_Firewall, even if this type has not been explicitly requested. Therefore, the application must sort these servers out. But if fSERV_Firewall is set in the types, then the search is done for whichever else types are requested, and with the assumption that the client has chosen a firewall connection mode, regardless of the network parameters supplied in SConnNetInfo or read out from either the registry or environment.

Note: A search for servers of type fSERV_Dns is not inclusive with fSERV_Any specified as a server type. That is, servers of type DNS are only returned if specifically requested in the server mask at the time the iterator was opened.

There is a simplified version of SERV_Open(), called SERV_OpenSimple(), as well as an advanced version, called SERV_OpenEx(). The former takes only one argument, the service name. The latter takes two more arguments, which describe the set of servers not to be returned from the iterator (server descriptors that to be excluded).

There is also an advanced version of SERV_GetNextInfo(), called SERV_GetNextInfoEx(), that, via its second argument, provides the ability to get many host parameters, among which is so-called host environment; a "\0"-terminated string, consisting of a set of lines separated by "\n" characters and specified in the configuration file of the load-balancing daemon of the host, where the returned server has been found. The typical line within the set has a form "name=value" and resembles very much the shell environment, where its name comes after. The host environment could be very handy for passing additional information to applications if the host has some limitations or requires special handling, should the server be selected and used on this host. The example below shall give an idea. At the time of writing, getting the host information is only implemented when the service is obtained via direct access to the load-balancing daemon. Unlike returned server descriptors, the returned host information handle is not a constant object and must be explicitly freed by the application when no longer needed. All operations (getter methods) that are defined on the host information handle are declared in connect/ncbi_host_info.h. If the server descriptor was obtained using dispatching CGI (indirect dispatching, see below), then the host information handle is always returned as NULL (no host information available).

The back end of the service mapping API is split into two independent parts: direct access to LBSMD, if the one is both available on the current host and is not disabled by parameter lb_disable at the iterator opening. If LBSMD is either unavailable or disabled, the second (indirect) part of the back-end API is used, which involves a connection to the dispatching CGI, which in turn connects to LBSMD to carry out the request. An attempt to use the CGI is done only if the net_info argument is provided as non-NULL in the calls to SERV_Open() or SERV_OpenEx().

Note: In a call to SERV_OpenSimple(), net_info gets created internally before an upcall to SERV_Open() and thus CGI dispatching is likely to happen, unless either net_info could not be constructed from the environment, or the environment variable CONN_LB_DISABLE (or a service-specific one, or either of the corresponding registry keys) is set to TRUE.

Note: In the above conditions, the network service name resolution is also undertaken if the service name could not be resolved (because the service could not be found or because of some other error) with the use of locally running LBSMD.

The following code example uses both a service connector and the service mapping API to access certain services using an alternate way (other than the connector's default) of choosing appropriate servers. By default, the service connector opens an internal service iterator and then tries to connect to the next server, which SERV_GetNextInfo() returns when given the iterator. That is, the server with a higher rate is tried first. If user provides a pointer to structure SSERVICE_Extra as the last parameter of the connector's constructor, then the user-supplied routine (if any) can be called instead to obtain the next server. The routine is also given a supplemental custom argument data taken from SSERVICE_Extra. The (intentionally simplified) example below tries to create a connector to an imaginary service "my_service" with the restriction that the server has to additionally have a certain (user-specified) database present. The database name is taken from the LBSMD host environment keyed by "my_service_env", the first word of which is assumed to be the required database name.

#include <connect/ncbi_service_connector.h>
#include <ctype.h>
#include <stdlib.h>
#include <string.h>
#define ENV_DB_KEY "my_service_env="
/* This routine gets called when connector is about to be destructed.
 */
static void s_CleanupData(void* data)
{
    free(data); /* we kept database name there */
}
/* This routine gets called on each internal close of the connector
 * (which may be followed by a subsequent internal open).
 */
static void s_Reset(void* data)
{
/* just see that reset happens by printing DB name */
    printf("Connection reset, DB: %s\n", (char*) data);
}
/* 'Data' is what we supplied among extra-parameters in connector's
 * constructor.
 * 'Iter' is an internal service iterator used by service connector;
 * it must remain open.
 */
static const SSERV_Info* s_GetNextInfo(void* data, SERV_ITER iter)
{
    const char* db_name = (const char*) data;
    size_t len = strlen(db_name);
    SSERV_Info* info;
    HOST_INFO hinfo;
    int reset = 0;
    for (;;) {
        while ((info = SERV_GetNextInfoEx(iter, &hinfo)) != 0) {
            const char* env = HINFO_Environment(hinfo);
            const char* c;
            for (c = env; c; c = strchr(c, '\n')) {
                if (strncmp(c == env ? c : ++c, ENV_DB_KEY,
                    sizeof(ENV_DB_KEY)-1) == 0) {
                    /* Our keyword has been detected in environment */
                    /* for this host */
                    c += sizeof(ENV_DB_KEY) - 1;
                    while (*c && isspace(*c))
                        c++;
                    if (strncmp(c, db_name, len) == 0 && !isalnum(c + len)) {
                        /* Database name match */
                        free(hinfo); /* must be freed explicitly */
                        return info;
                    }
                }
            }
            if (hinfo)
            free(hinfo); /* must be freed explicitly */
        }
        if (reset)
            break; /* coming to reset 2 times in a row means no server fit */
        SERV_Reset(iter);
        reset = 1;
    }
    return 0; /* no match found */
}
int main(int argc, char* argv[])
{
    char* db_name = strdup(argv[1]);
    SSERVICE_Extra params;
    CONNECTOR c;
    CONN conn;
    memset(&params, 0, sizeof(params));
    params.data = db_name; /* custom data, anything */
    params.reset = s_Reset; /* reset routine, may be NULL */
    params.cleanup = s_CleanupData; /* cleanup routine, may be NULL*/
    params.get_next_info = s_GetNextInfo; /* custom iterator routine */
    if (!(c = SERVICE_CreateConnectorEx("my_service",
        fSERV_Any, NULL, &params))) {
        fprintf(stderr, "Cannot create connector");
        exit(1);
    }
    if (CONN_Create(c, &conn) != eIO_Success) {
        fprintf(stderr, "Cannot create connection");
        exit(1);
    }
    /* Now we can use CONN_Read(),CONN_Write() etc to deal with
     * connection, and we are assured that the connection is made
     * only to the server on such a host which has "db_name"
     * specified in configuration file of LBSMD.
     */
    ...
    CONN_Close(conn);
    /* this also calls cleanup of user data provided in params */
    return 0;
}

Note: No network (indirect) mapping occurs in the above example because net_info is passed as NULL to the connector's constructor.

[CONN]
LOCAL_ENABLE=yes
LOCAL_SERVICES="MSSQL10 MSSQL14 MSSQL15 MSSQL16 MSSQL17"

[MSSQL10]
CONN_LOCAL_SERVER_6="DNS mssql10:1433 L=yes"

[MSSQL15]
CONN_LOCAL_SERVER_9="DNS mssql15:1433 L=yes"

CONN_LOCAL_ENABLE=yes
CONN_LOCAL_SERVICES="MSSQL10 MSSQL14 MSSQL15 MSSQL16 MSSQL17"
MSSQL10_CONN_LOCAL_SERVER_6="DNS mssql10:1433 L=yes"
MSSQL15_CONN_LOCAL_SERVER_9="DNS mssql15:1433 L=yes"

This library also provides CThreadedServer, an abstract base class for multithreaded network servers. Here is a demonstration of its use. Note that this class does not support multiplexing traffic over a single TCP connection; rather, each thread has an individual TCP connection created when a client connects to the server's listening port.