cctools
Data Structures | Defines | Enumerations | Functions
link.h File Reference

A high level TCP connection library. More...

#include "int_sizes.h"
#include <time.h>
#include <limits.h>
#include <stdio.h>
#include <stdarg.h>
#include <sys/types.h>

Go to the source code of this file.

Data Structures

struct  link_info
 Activity structure passed to link_poll. More...

Defines

#define LINK_ADDRESS_MAX   48
 Maximum number of characters in the text representation of a link address.
#define LINK_PORT_ANY   0
 Value to usewhen any listen port is acceptable.
#define LINK_FOREVER   ((time_t)INT_MAX)
 Stoptime to give when you wish to wait forever.
#define LINK_READ   1
 Indicates a link is ready to read via link_poll.
#define LINK_WRITE   2
 Indicates a link is ready to write via link_poll.

Enumerations

enum  link_tune_t {
  LINK_TUNE_INTERACTIVE,
  LINK_TUNE_BULK
}
 Options for link performance tuning. More...

Functions

struct link * link_connect (const char *addr, int port, time_t stoptime)
 Connect to a remote host.
struct link * link_serve (int port)
 Prepare to accept connections.
struct link * link_serve_address (const char *addr, int port)
 Prepare to accept connections on one network interface.
struct link * link_accept (struct link *master, time_t stoptime)
 Accept one connection.
int link_read (struct link *link, char *data, size_t length, time_t stoptime)
 Read data from a connection.
int link_read_avail (struct link *link, char *data, size_t length, time_t stoptime)
 Read available data from a connection.
int link_write (struct link *link, const char *data, size_t length, time_t stoptime)
 Write data to a connection.
int link_putfstring (struct link *link, const char *fmt, time_t stoptime,...)
 Write formatted data to a connection.
int link_putvfstring (struct link *link, const char *fmt, time_t stoptime, va_list va)
 Write formatted data to a connection.
int link_usleep (struct link *link, int usec, int reading, int writing)
 Block until a link is readable or writable.
void link_close (struct link *link)
 Close a connection.
void link_window_set (int send_window, int recv_window)
 Set the TCP window size to be used for all links.
void link_window_get (struct link *link, int *send_window, int *recv_window)
 Get the TCP window size actually allocated for this link.
int link_readline (struct link *link, char *line, size_t length, time_t stoptime)
 Read a line of text from a link.
int link_fd (struct link *link)
 Get the underlying file descriptor of a link.
int link_address_local (struct link *link, char *addr, int *port)
 Return the local address of the link in text format.
int link_address_remote (struct link *link, char *addr, int *port)
 Return the remote address of the link in text format.
int link_tune (struct link *link, link_tune_t mode)
 Tune a link for interactive or bulk performance.
int link_poll (struct link_info *array, int nlinks, int msec)
 Wait for a activity on a an array of links.

Detailed Description

A high level TCP connection library.

A link is a TCP connection to a process on another machine. This module works at a higher level of abstraction than the socket library, with an easier-to-use API and explicit support for timeouts.

Timeouts are specified using an absolute stoptime. For example, if you want a connection to be attempted for sixty seconds, specify time(0)+60. The operation will be tried and retried until that absolute limit, giving the caller much greater control over program behavior.

Note that this library manipulates IP addresses in the form of strings. To convert a hostname into a string IP address, call domain_name_cache_lookup. For example, here is how to make a simple HTTP request:

struct link *link;
time_t stoptime = time(0)+300;
char addr[LINK_ADDRESS_MAX];
int result;
const char *request = "GET / HTTP/1.0\n\n";
result = domain_name_cache_lookup("www.google.com",addr);
if(!result) fatal("could not lookup name");
link = link_connect(addr,80,stoptime);
if(!link) fatal("could not connect");
result = link_write(link,request,strlen(request),stoptime);
if(result<0) fatal("could not send request");
link_stream_to_file(link,stdout,1000000,stoptime);
link_close(link);

Define Documentation

#define LINK_ADDRESS_MAX   48

Maximum number of characters in the text representation of a link address.

This must be large enough to accomodate ipv6 in the future.

#define LINK_PORT_ANY   0

Value to usewhen any listen port is acceptable.

#define LINK_FOREVER   ((time_t)INT_MAX)

Stoptime to give when you wish to wait forever.

#define LINK_READ   1

Indicates a link is ready to read via link_poll.

#define LINK_WRITE   2

Indicates a link is ready to write via link_poll.


Enumeration Type Documentation

Options for link performance tuning.

Enumerator:
LINK_TUNE_INTERACTIVE 

Data is sent immediately to optimze interactive latency.

LINK_TUNE_BULK 

Data may be buffered to improve throughput of large transfers.


Function Documentation

struct link* link_connect ( const char *  addr,
int  port,
time_t  stoptime 
) [read]

Connect to a remote host.

Parameters:
addrIP address of server in string form.
portPort of server.
stoptimeAbsolute time at which to abort.
Returns:
On success, returns a pointer to a link object. On failure, returns a null pointer with errno set appropriately.
struct link* link_serve ( int  port) [read]

Prepare to accept connections.

link_serve will accept connections on any network interface, which is usually what you want.

Parameters:
portThe port number to listen on.
Returns:
link A server endpoint that can be passed to link_accept, or null on failure.
struct link* link_serve_address ( const char *  addr,
int  port 
) [read]

Prepare to accept connections on one network interface.

Functions like link_serve, except that the server will only be visible on the given network interface.

Parameters:
addrIP address of the network interface.
portThe port number to listen on.
Returns:
link A server endpoint that can be passed to link_accept, or null on failure.
struct link* link_accept ( struct link *  master,
time_t  stoptime 
) [read]

Accept one connection.

Parameters:
masterA link returned from link_serve or link_serve_address.
stoptimeThe time at which to abort.
Returns:
link A connection to a client, or null on failure.
int link_read ( struct link *  link,
char *  data,
size_t  length,
time_t  stoptime 
)

Read data from a connection.

This call will block until the given number of bytes have been read, or the connection is dropped.

Parameters:
linkThe link from which to read.
dataA buffer to hold the data.
lengthThe number of bytes to read.
stoptimeThe time at which to abort.
Returns:
The number of bytes actually read, or zero if the connection is closed, or less than zero on error.
int link_read_avail ( struct link *  link,
char *  data,
size_t  length,
time_t  stoptime 
)

Read available data from a connection.

This call will read whatever data is immediately available, and then return without blocking.

Parameters:
linkThe link from which to read.
dataA buffer to hold the data.
lengthThe number of bytes to read.
stoptimeThe time at which to abort.
Returns:
The number of bytes actually read, or zero if the connection is closed, or less than zero on error.
int link_write ( struct link *  link,
const char *  data,
size_t  length,
time_t  stoptime 
)

Write data to a connection.

Parameters:
linkThe link to write.
dataA pointer to the data.
lengthThe number of bytes to write.
stoptimeThe time at which to abort.
Returns:
The number of bytes actually written, or less than zero on error.
int link_putfstring ( struct link *  link,
const char *  fmt,
time_t  stoptime,
  ... 
)

Write formatted data to a connection.

All data is written until finished or an error is encountered.

Parameters:
linkThe link to write.
fmtA pointer to the data.
stoptimeThe time at which to abort.
...Format arguments.
Returns:
The number of bytes actually written, or less than zero on error.
int link_putvfstring ( struct link *  link,
const char *  fmt,
time_t  stoptime,
va_list  va 
)

Write formatted data to a connection.

All data is written until finished or an error is encountered.

Parameters:
linkThe link to write.
fmtA pointer to the data.
stoptimeThe time at which to abort.
vaFormat arguments.
Returns:
The number of bytes actually written, or less than zero on error.
int link_usleep ( struct link *  link,
int  usec,
int  reading,
int  writing 
)

Block until a link is readable or writable.

Parameters:
linkThe link to wait on.
usecThe maximum number of microseconds to wait.
readingWait for the link to become readable.
writingWait for the link to become writable.
Returns:
One if the link becomes readable or writable before the timeout expires, zero otherwise.
void link_close ( struct link *  link)

Close a connection.

Parameters:
linkThe connection to close.
void link_window_set ( int  send_window,
int  recv_window 
)

Set the TCP window size to be used for all links.

Takes effect on future calls to link_connect or link_accept. Default value is set by the system or by the environment variable TCP_WINDOW_SIZE. Note that the operating system may place limits on the buffer sizes actually allocated. Use link_window_get to retrieve the buffer actually allocated for a given link.

Parameters:
send_windowThe size of the send window, in bytes.
recv_windowThe size of the recv window, in bytes.
void link_window_get ( struct link *  link,
int *  send_window,
int *  recv_window 
)

Get the TCP window size actually allocated for this link.

Parameters:
linkThe link to examine.
send_windowA pointer where to store the send window.
recv_windowA pointer where to store the receive window.
int link_readline ( struct link *  link,
char *  line,
size_t  length,
time_t  stoptime 
)

Read a line of text from a link.

Reads a line of text, up to and including a newline, interpreted as either LF or CR followed by LF. The line actually returned is null terminated and does not contain the newline indicator. An internal buffer is used so that readline can usually complete with zero or one system calls.

Parameters:
linkThe link to read from.
lineA pointer to a buffer to fill with data.
lengthThe length of the buffer in bytes.
stoptimeThe absolute time at which to abort.
Returns:
If greater than zero, a line was read, and the return value indicates the length in bytes. If equal to zero, end of stream was reached. If less than zero, an error occurred.
int link_fd ( struct link *  link)

Get the underlying file descriptor of a link.

Parameters:
linkThe link to examine.
Returns:
The integer file descriptor of the link.
int link_address_local ( struct link *  link,
char *  addr,
int *  port 
)

Return the local address of the link in text format.

Parameters:
linkThe link to examine.
addrPointer to a string of at least LINK_ADDRESS_MAX bytes, which will be filled with a text representation of the local IP address.
portPointer to an integer, which will be filled with the TCP port number.
Returns:
Positive on success, zero on failure.
int link_address_remote ( struct link *  link,
char *  addr,
int *  port 
)

Return the remote address of the link in text format.

Parameters:
linkThe link to examine.
addrPointer to a string of at least LINK_ADDRESS_MAX bytes, which will be filled with a text representation of the remote IP address.
portPointer to an integer, which will be filled with the TCP port number.
Returns:
Positive on success, zero on failure.
int link_tune ( struct link *  link,
link_tune_t  mode 
)

Tune a link for interactive or bulk performance.

A link may be tuned at any point in its lifecycle. LINK_TUNE_INTERACTIVE is best used for building latency-sensitive interactive or RPC applications. LINK_TUNE_BULK is best used to large data transfers.

Parameters:
linkThe link to be tuned.
modeThe desired tuning mode.
int link_poll ( struct link_info array,
int  nlinks,
int  msec 
)

Wait for a activity on a an array of links.

Parameters:
arrayPointer to an array of link_info structures. Each one should contain a pointer to a valid link and have the events field set to the events (LINK_READ or LINK_WRITE) of interest. Upon return, each one will have the revents field filled with the events that actually occurred.
nlinksThe length of the array.
msecThe number of milliseconds to wait for activity. Zero indicates do not wait at all, while -1 indicates wait forever.
Returns:
The number of links available to read or write.