/* Definitions/declarations for socket utility routines.
 *
 * IRC Services is copyright (c) 1996-2007 Andrew Church.
 *     E-mail: <achurch@achurch.org>
 * 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 <sys/socket.h>  /* 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 */