/* Definitions/declarations for socket utility routines. * * IRC Services is copyright (c) 1996-2007 Andrew Church. * E-mail: * Parts written by Andrew Kempe and others. * This program is free but copyrighted software; see the file COPYING for * details. */ #ifndef SOCKETS_H #define SOCKETS_H #include /* for struct sockaddr */ /*************************************************************************/ /* Services implements an event-based socket management system using * callbacks for socket-related events (connect, disconnect, read). * Sockets are created using sock_new() and freed using sock_free(); * callbacks are registered using sock_setcb(SCB_*,function). The * check_sockets() function does the actual checking for socket activity, * and should be called by the program's main loop. * * By default, sockets are non-blocking; if a socket is not ready for * writing and no more buffer space is available, write attempts will stop * at that point, setting errno to EAGAIN. sock_set_blocking() allows * sockets to be set to blocking mode, which causes write attempts to wait * until either buffer space becomes available or a hard error (such as the * connection being broken) occurs. sock_get_blocking() returns whether * the socket is set to blocking mode (nonzero return value, but not -1) or * not (zero). * * When a callback function is called, it is passed two parameters: a * pointer to the socket structure (Socket *) for the socket on which the * event occurred, and a void * parameter whose meaning depends on the * particular callback (see below). Callbacks will never be called nested * unless a callback explicitly calls check_sockets(), which is not * recommended; thus it is safe to set new callbacks for a socket inside of * a callback function. * * There are currently four callbacks implemented: * * SCB_CONNECT * Called when a connection initiated with conn() completes. The * void * parameter is not used. * * SCB_DISCONNECT * Called when a connection is broken, either by the remote end or as * a result of calling disconn(). Also called when a connection * initiated with conn() fails. The void * parameter is set to either * DISCONN_LOCAL, DISCONN_REMOTE, or DISCONN_CONNFAIL to indicate the * cause of the disconnection. For DISCONN_REMOTE or DISCONN_CONNFAIL, * the `errno' variable will contain the cause of disconnection if * known, zero otherwise. * * SCB_ACCEPT * Called when a listener socket receives a connection. The void * * parameter, cast to Socket *, is the new socket created for the * incoming connection; the address of the remote connection can be * retrieved with sock_remote(). NOTE: a listener socket will not * accept any connections unless this callback is set. * * SCB_READ * Called when data is available for reading. The void * parameter, * cast to uint32, indicates the number of bytes available for reading. * If some, but not all, of the data is read by the routine (using * sread(), sgetc(), etc.), the remainder will be kept in the read * buffer and the callback will be called again immediately. * * SCB_READLINE * Like SCB_READ, called when data is available for reading; however, * this callback is only called when at least one full line of data is * available for reading. The void * parameter, cast to uint32, * indicates the number of bytes available for reading. If both * SCB_READ and SCB_READLINE are set, SCB_READ will be called first, * and if it leaves any data (including a newline) in the buffer, * SCB_READLINE will then be called. Likewise, if SCB_READLINE leaves * data in the buffer--which may include a partial line, if a * fractional number of lines was received--SCB_READ will be called * immediately following. */ /*************************************************************************/ /* Structure for socket data. This structure is not actually defined here * in order to hide it from the user. */ struct socket_; /* Typedef for socket structure. */ typedef struct socket_ Socket; /* Type of socket callback functions. */ typedef void (*SocketCallback)(Socket *s, void *param); /* Identifiers for callback functions (used with sock_setcb()). */ #define SCB_CONNECT 0 #define SCB_DISCONNECT 1 #define SCB_ACCEPT 2 #define SCB_READ 3 #define SCB_READLINE 4 /* Values of parameter to disconnect callback. */ #define DISCONN_LOCAL ((void *)1) /* disconn() function called */ #define DISCONN_REMOTE ((void *)2) /* Transmission error */ #define DISCONN_CONNFAIL ((void *)3) /* Connection attempt failed */ /*************************************************************************/ extern Socket *sock_new(void); extern void sock_free(Socket *s); extern void sock_setcb(Socket *s, int which, SocketCallback func); extern int sock_isconn(const Socket *s); extern int sock_remote(const Socket *s, struct sockaddr *sa, int *lenptr); extern void sock_set_blocking(Socket *s, int blocking); extern int sock_get_blocking(Socket *s); extern uint32 read_buffer_len(const Socket *s); extern uint32 write_buffer_len(const Socket *s); extern void sock_rwstat(const Socket *s, uint32 *readkb_ret, uint32 *writekb_ret); extern int sock_bufstat(const Socket *s, uint32 *socksize_ret, uint32 *totalsize_ret, int *ratio1_ret, int *ratio2_ret); extern void check_sockets(void); extern int conn(Socket *s, const char *host, int port, const char *lhost, int lport); extern int disconn(Socket *s); extern int open_listener(Socket *s, const char *host, int port, int backlog); extern int close_listener(Socket *s); extern int32 sread(Socket *s, char *buf, int32 len); extern int32 swrite(Socket *s, const char *buf, int32 len); extern int sgetc(Socket *s); extern char *sgets(char *buf, int32 len, Socket *s); extern char *sgets2(char *buf, int32 len, Socket *s); extern int sputs(char *str, Socket *s); extern int sockprintf(Socket *s, const char *fmt,...); extern int vsockprintf(Socket *s, const char *fmt, va_list args); extern const char *hstrerror(int h_errnum); /*************************************************************************/ #endif /* SOCKETS_H */