3.6 Application Programming Interface

The R connections internals are generally not available to package developers. The C symbols associated with the connections internals are protected by declarations and definitions in private headers, static declarations, and by setting the visibility attribute attribute_hidden, where available. However, several of the functions defined in src/main/connections.c are called in other places throughout the source code. In addition, comments in the source code hint at a possible public API in future versions of R. The following code exerpt from src/main/connections.c (added at revision r19005, 03/29/2002, by Luke Tierney of The University of Iowa) illustrates both points.

/* This function allows C code to call the write method of a
   connection.  It is mainly intended as a means for C code to do a
   buffered write to sockets, but could be the start of a more
   extensive C-level connection API.  LT */
size_t R_WriteConnection(Rconnection con, void *buf, size_t n)
{
    if(!con->isopen) error(_("connection is not open"));
    if(!con->canwrite) error(_("cannot write to this connection"));

    return con->write(buf, 1, n, con);
}

The R_WriteConnection function is declared and used only in src/main/serialize.c. The R serialization mechanism (save/load) is also the sole user of the two publicly (Rinternals.h) declared functions loosely associated with connections: R_InitConnOutPStream, and R_InitConnInPStream. However, each of these three functions requires an initialized Rconnection pointer.

The following snippet from src/include/Rinternals.h defines an opaque pointer to the struct Rconn structure.

/* The connection interface is not yet available to packages.  To
   allow limited use of connection pointers this defines the opaque
   pointer type. */
#ifndef HAVE_RCONNECTION_TYPEDEF
typedef struct Rconn  *Rconnection;
#define HAVE_RCONNECTION_TYPEDEF
#endif

However, in the absence of a public definition for struct Rconn, or another mechanism to obtain a reference to an initialized structure, the existing API functions are not usable by authors of extension packages.

A more complete connections API was proposed by Jeff Horner of Vanderbilt University in an series of R-devel messages (see "[Rd] Connections patch", 11/2/06). The proposed API was essentially a series of functions to compliment the R_WriteConnection function, including methods to read, open, close, and create new connections. However, these additions have not been adopted by the R core development team.