Networking Library

Types

typedef int netsocket;

This is the value opaque handle through which networking operations occur. This is the basic type used to distinguish between the networking connections. Pointers to values of this type are passed around, Think of it like stdio's FILE *.

typedef void (*net_func_ptr) (netsocket);

net_func_ptr is the type of the functions used in calls to net_listen, net_on_read and net_on_close, etc. The functions used there should return void and take one argument, a netsocket.

typedef void (*net_funcbuf_ptr) (netsocket, char *, int);

Functions of this type are used in calls to net_read_into_buffer. When the buffer is full, the specified function will be called with arguments of the netsocket the buffer is full for, the buffer that was filled, and the size of the buffer.

typedef int error_t;

When error_t is specified, one of the values listed below in the Errors section will be returned. If one is returned, it may be wise to look at the global variable errno to determine if a system level error occured.

For reference, the contents of the structure of NETSOCKET:

struct {
    int              fd;
    long             user_storage;
    int              type;
    int              listen_port;
    net_func_ptr     on_read;
    net_func_ptr     on_accept;
    net_func_ptr     on_close;
    net_funcbuf_ptr  on_fullbuffer;
    FILE            *fileptr;
    char            *original_buffer;
    int              original_buffer_size;
    char            *buffer;
    int              buffer_size;
};

Signals

Errors

NET_SUCCESS
NET_EINVARG
NET_ENOMEM
NET_ENOTFOUND
NET_ENOTHOST
NET_EBADIOCTL
NET_ESOCKET
NET_ECONNECT
NET_ENOHOST
NET_ENOSERVICE
NET_EUNSUPPORT

Functions

void net_start()

This function should be called once to initialize the networking library.

void net_end()

This function should be called when you want to disable the use of this library. It is set to be executed upon program exit using the atexit() C library function. Calling this function will force all monitored connections closed, including those created with net_fdtonetsocket listed below.

error_t net_listen(int port, net_func_ptr accept_func)

Listens on the specified port. When a connection is accepted, the function accept_func is called.

error_t net_unlisten(int port)

Stops listening on the specified port.

int net_poll_listeners(int sec, int usec)

In the main event loop of your program, you should call this function periodicly in order to allow the library to accept new connections on the ports being listened on and call the on_accept functions. It returns the number of new connections which were accepted. sec and usec are the number of seconds and milliseconds to wait before returning if there is no activity. If there is activity, it will return sooner. If you have many things to do that are not network oriented, these should be small values.

error_t net_on_read(netsocket handle, net_func_ptr on_read_func)

When handle is ready to be read on, that is, it contains waiting data, the on_read_func function is called.

int net_poll_readers(int sec, int usec)

In the main event loop of your program, you should call this function periodicly in order to allow the library to determine which sockets need to be read from and call the on_read functions. It returns the number of on_read functions that were actually called. sec and usec are the number of seconds and milliseconds to wait before returning if there is no activity. If there is activity, it will return sooner. If you have many things to do that are not network oriented, these should be small values.

If you use net_read_into_buffer, then net_poll_readers must be called in order to actually read data into buffers. The function you specify to call when the buffer is full will not be called unless net_poll_readers is called.

error_t net_on_close(netsocket handle, net_func_ptr on_close_func)

When handle is closed either remotely or locally (using net_close), then the function on_close_func will be called.

error_t net_close(netsocket handle)

Closes handle. This will end up calling the function specified with net_on_close, if any.

error_t net_read(netsocket handle, char *buf, size_t bufsiz)

Reads bufsiz bytes from handle into *buf. Returns the number of bytes read or an error.

error_t net_write(netsocket handle, char *buf, size_t bufsiz)

Writes bufsiz bytes from *buf to the network connection handle. Returns the number of bytes written, or an error.

error_t net_open_connection(char *host, int port, netsocket *handle)

Initiates a new connection to host and port. *handle is assigned the netsocket to use with the other library functions.

error_t net_local_connection_info(netsocket handle, char *host, int *port)

Returns in *host and *port the Internet address in dotted decimal notation and the port number that handle is connected to on the local end. *host should point to a character array at least 16 bytes in length.

error_t net_remote_connection_info(netsocket handle, char *host, int *port)

Returns in *host and *port the Internet address in dotted decimal notation and the port number that handle is connected to on the remote end. *host should point to a character array at least 16 bytes in length.
This only works for handles created by net_listen or net_open_connection. Other types will return NET_EUNSUPPORT.

error_t net_host_lookup(char *hostname, char *host)

Returns in *host the Internet address in dotted decimal notation that has the machine and domain name of the machine in hostname. *host should point to a character array at least 16 bytes in length.
This only works for handles created by net_listen or net_open_connection. Other types will return NET_EUNSUPPORT.

error_t net_service_lookup(char *service, int *port)

Returns in *port the port number of the service named in service.

error_t net_read_into_buffer(netsocket handle, net_funcbuf_ptr bufferfunc, char *buf, size_t count)

This function configures buffer reading on handle. When data is avaiable, buf will be filled up. When count bytes have been read into buf, then bufferfunc will be called. When bufferfunc is called, you should call net_read_into_buffer again to reset and reconfigure the buffering read. The buffer gets filled on calls to net_poll_readers, so, as usual, net_poll_readers needs to be called periodicly.

int net_bytes_left_in_buffer(netsocket h)

Returns the number of bytes remaining to be filled before the function passed to net_read_info_buffer will be called.

error_t net_put_assoc_data(netsocketh, long data)

Associates the value in data with h. This data can be retreived by net_get_assoc_data.

error_t net_get_assoc_data(netsocketh, long *data)

Gets the value associated with h (using net_put_assoc_data) and stores it in *data.

FILE *net_tofile(netsocket h)

Returns a FILE * bound to h, which can be used in calls to fprintf and company. Keep in mind that the stdio functions buffer the output, so that after using stdio functions, you should call fflush(net_tofile(h)). It is probably not the wisest thing to intermix calls to stdio functions and net_read/net_write at the same time.

error_t net_fdtonetsocket(int fd, netsocket *newhandle)
error_t net_socktonetsocket(int fd, netsocket *newhan dle)

Takes any file descriptor and returns, in *newhandle, a netsocket, which can be used with net_on_read and company. Once net_on_read is called with the netsocket in *newhandle, then net_poll_readers takes care of calling an on-read function, just as if the netsocket was created with a call to net_listen or net_open_connection, etc. The only difference between net_fdtonetsocket and net_socktonetsocket is how data is read/written from/to the file descriptor. If net_fdtonetsocket is used, then read(2) and write(2) will be used. For net_socktonetsocket, recv(2) and send(2) will be used.

error_t net_ignorenetsocket(netsocket * i)

Essentially undoes the effect of net_fdtonetsocket and net_socktonetsocket, returning the file descriptor to it's previous, unmonitored state. The associated file descriptor remains open and can still be written to using regular library and system calls.