vendor/ircservices-5.1.24/sockets.h

/* Definitions/declarations for socket utility routines.
 *
 * IRC Services is copyright (c) 1996-2009 Andrew Church.
 *     E-mail: <achurch@achurch.org>
 * Parts written by Andrew Kempe and others.
 * This program is free but copyrighted software; see the file GPL.txt 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).
 *
 * Since ordinary writes are buffered, the caller has no easy way to check
 * how much of the data has actually been transferred, or, consequently,
 * whether the remote host is actually accepting data or just sitting
 * around doing nothing.  Since the latter case would cause socket slots to
 * be used up for long periods of time, the sock_set_wto() function allows
 * a write timeout to be set for a socket; if no data is accepted by the
 * remote side within the specified number of seconds, the socket will be
 * considered dead and processed as if the remote host had closed the
 * connection.  The write timeout is disabled by default, but if enabled,
 * it can be disabled again by setting a timeout value of zero.
 *
 * Likewise, the program may wish to perform some periodic actions even if
 * no socket activity is occurring.  The sock_set_rto() function can be
 * used to set a global read timeout in milliseconds; if no new data
 * arrives during this period, check_sockets() will return control to the
 * caller.  sock_set_rto(-1) will revert to the default behavior of waiting
 * indefinitely for socket activity.
 *
 * 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 six 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.
 *
 * SCB_TRIGGER
 *      Called when a "write trigger" is encountered.  These triggers are
 *      set with swrite_trigger(), and are called when all data written to
 *      the socket before the swrite_trigger() call has been sent to the
 *      remote host, but before any data written after the trigger is sent.
 *      The void * parameter is the parameter passed to swrite_trigger().
 */

/*************************************************************************/

/* Minimum (also initial) buffer size for socket; also serves as the
 * increment for buffer expansion. */
#define SOCK_MIN_BUFSIZE 4096

/* 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()). */
typedef enum {
    SCB_CONNECT = 1,
    SCB_DISCONNECT,
    SCB_ACCEPT,
    SCB_READ,
    SCB_READLINE,
    SCB_TRIGGER,
} SocketCallbackID;

/* 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 void sock_set_buflimits(uint32 per_conn, uint32 total);
extern void sock_set_rto(int msec);

extern Socket *sock_new(void);
extern void sock_free(Socket *s);
extern void sock_setcb(Socket *s, SocketCallbackID 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(const Socket *s);
extern void sock_set_wto(Socket *s, int seconds);
extern void sock_mute(Socket *s);
extern void sock_unmute(Socket *s);
extern uint32 read_buffer_len(const Socket *s);
extern uint32 write_buffer_len(const Socket *s);
extern int sock_rwstat(const Socket *s, uint64 *read_ret, uint64 *written_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 int32 swritemap(Socket *s, const char *buf, int32 len);
extern int swrite_trigger(Socket *s, void *param);
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(const char *str, Socket *s);
extern int sockprintf(Socket *s, const char *fmt,...);
extern int vsockprintf(Socket *s, const char *fmt, va_list args);

/*************************************************************************/

#endif  /* SOCKETS_H */

/*
 * Local variables:
 *   c-file-style: "stroustrup"
 *   c-file-offsets: ((case-label . *) (statement-case-intro . *))
 *   indent-tabs-mode: nil
 * End:
 *
 * vim: expandtab shiftwidth=4:
 */
Revision:	1171
Committed:	Fri Aug 12 20:00:46 2011 UTC (12 years, 8 months ago) by michael
Content type:	text/x-chdr
File size:	8604 byte(s)
Log Message:	- Import ircservices-5.1.24. Don't ever think about modifying anything in this folder! Since Andrew Church has discontinued his services project in April 2011, the ircd-hybrid team has been given permissions to officially continue and maintain the already mentioned project. The name of this project will be changed for the reason being that the current name "IRC Services" is way too generic these days. Remember: Don't ever modify anything in here. This folder is kept for reference.
#	Content
1	/* Definitions/declarations for socket utility routines.
2	*
3	* IRC Services is copyright (c) 1996-2009 Andrew Church.
4	* E-mail: <achurch@achurch.org>
5	* Parts written by Andrew Kempe and others.
6	* This program is free but copyrighted software; see the file GPL.txt for
7	* details.
8	*/
9
10	#ifndef SOCKETS_H
11	#define SOCKETS_H
12
13	#include <sys/socket.h> /* for struct sockaddr */
14
15	/*************************************************************************/
16
17	/* Services implements an event-based socket management system using
18	* callbacks for socket-related events (connect, disconnect, read).
19	* Sockets are created using sock_new() and freed using sock_free();
20	* callbacks are registered using sock_setcb(SCB_*,function). The
21	* check_sockets() function does the actual checking for socket activity,
22	* and should be called by the program's main loop.
23	*
24	* By default, sockets are non-blocking; if a socket is not ready for
25	* writing and no more buffer space is available, write attempts will stop
26	* at that point, setting errno to EAGAIN. sock_set_blocking() allows
27	* sockets to be set to blocking mode, which causes write attempts to wait
28	* until either buffer space becomes available or a hard error (such as the
29	* connection being broken) occurs. sock_get_blocking() returns whether
30	* the socket is set to blocking mode (nonzero return value, but not -1) or
31	* not (zero).
32	*
33	* Since ordinary writes are buffered, the caller has no easy way to check
34	* how much of the data has actually been transferred, or, consequently,
35	* whether the remote host is actually accepting data or just sitting
36	* around doing nothing. Since the latter case would cause socket slots to
37	* be used up for long periods of time, the sock_set_wto() function allows
38	* a write timeout to be set for a socket; if no data is accepted by the
39	* remote side within the specified number of seconds, the socket will be
40	* considered dead and processed as if the remote host had closed the
41	* connection. The write timeout is disabled by default, but if enabled,
42	* it can be disabled again by setting a timeout value of zero.
43	*
44	* Likewise, the program may wish to perform some periodic actions even if
45	* no socket activity is occurring. The sock_set_rto() function can be
46	* used to set a global read timeout in milliseconds; if no new data
47	* arrives during this period, check_sockets() will return control to the
48	* caller. sock_set_rto(-1) will revert to the default behavior of waiting
49	* indefinitely for socket activity.
50	*
51	* When a callback function is called, it is passed two parameters: a
52	* pointer to the socket structure (Socket *) for the socket on which the
53	* event occurred, and a void * parameter whose meaning depends on the
54	* particular callback (see below). Callbacks will never be called nested
55	* unless a callback explicitly calls check_sockets(), which is not
56	* recommended; thus it is safe to set new callbacks for a socket inside of
57	* a callback function.
58	*
59	* There are currently six callbacks implemented:
60	*
61	* SCB_CONNECT
62	* Called when a connection initiated with conn() completes. The
63	* void * parameter is not used.
64	*
65	* SCB_DISCONNECT
66	* Called when a connection is broken, either by the remote end or as
67	* a result of calling disconn(). Also called when a connection
68	* initiated with conn() fails. The void * parameter is set to either
69	* DISCONN_LOCAL, DISCONN_REMOTE, or DISCONN_CONNFAIL to indicate the
70	* cause of the disconnection. For DISCONN_REMOTE or DISCONN_CONNFAIL,
71	* the `errno' variable will contain the cause of disconnection if
72	* known, zero otherwise.
73	*
74	* SCB_ACCEPT
75	* Called when a listener socket receives a connection. The void *
76	* parameter, cast to Socket *, is the new socket created for the
77	* incoming connection; the address of the remote connection can be
78	* retrieved with sock_remote(). NOTE: a listener socket will not
79	* accept any connections unless this callback is set.
80	*
81	* SCB_READ
82	* Called when data is available for reading. The void * parameter,
83	* cast to uint32, indicates the number of bytes available for reading.
84	* If some, but not all, of the data is read by the routine (using
85	* sread(), sgetc(), etc.), the remainder will be kept in the read
86	* buffer and the callback will be called again immediately.
87	*
88	* SCB_READLINE
89	* Like SCB_READ, called when data is available for reading; however,
90	* this callback is only called when at least one full line of data is
91	* available for reading. The void * parameter, cast to uint32,
92	* indicates the number of bytes available for reading. If both
93	* SCB_READ and SCB_READLINE are set, SCB_READ will be called first,
94	* and if it leaves any data (including a newline) in the buffer,
95	* SCB_READLINE will then be called. Likewise, if SCB_READLINE leaves
96	* data in the buffer--which may include a partial line, if a
97	* fractional number of lines was received--SCB_READ will be called
98	* immediately following.
99	*
100	* SCB_TRIGGER
101	* Called when a "write trigger" is encountered. These triggers are
102	* set with swrite_trigger(), and are called when all data written to
103	* the socket before the swrite_trigger() call has been sent to the
104	* remote host, but before any data written after the trigger is sent.
105	* The void * parameter is the parameter passed to swrite_trigger().
106	*/
107
108	/*************************************************************************/
109
110	/* Minimum (also initial) buffer size for socket; also serves as the
111	* increment for buffer expansion. */
112	#define SOCK_MIN_BUFSIZE 4096
113
114	/* Structure for socket data. This structure is not actually defined here
115	* in order to hide it from the user. */
116	struct socket_;
117
118	/* Typedef for socket structure. */
119	typedef struct socket_ Socket;
120
121	/* Type of socket callback functions. */
122	typedef void (SocketCallback)(Socket s, void *param);
123
124	/* Identifiers for callback functions (used with sock_setcb()). */
125	typedef enum {
126	SCB_CONNECT = 1,
127	SCB_DISCONNECT,
128	SCB_ACCEPT,
129	SCB_READ,
130	SCB_READLINE,
131	SCB_TRIGGER,
132	} SocketCallbackID;
133
134	/* Values of parameter to disconnect callback. */
135	#define DISCONN_LOCAL ((void )1) / disconn() function called */
136	#define DISCONN_REMOTE ((void )2) / Transmission error */
137	#define DISCONN_CONNFAIL ((void )3) / Connection attempt failed */
138
139	/*************************************************************************/
140
141	extern void sock_set_buflimits(uint32 per_conn, uint32 total);
142	extern void sock_set_rto(int msec);
143
144	extern Socket *sock_new(void);
145	extern void sock_free(Socket *s);
146	extern void sock_setcb(Socket *s, SocketCallbackID which, SocketCallback func);
147	extern int sock_isconn(const Socket *s);
148	extern int sock_remote(const Socket s, struct sockaddr sa, int *lenptr);
149	extern void sock_set_blocking(Socket *s, int blocking);
150	extern int sock_get_blocking(const Socket *s);
151	extern void sock_set_wto(Socket *s, int seconds);
152	extern void sock_mute(Socket *s);
153	extern void sock_unmute(Socket *s);
154	extern uint32 read_buffer_len(const Socket *s);
155	extern uint32 write_buffer_len(const Socket *s);
156	extern int sock_rwstat(const Socket s, uint64 read_ret, uint64 *written_ret);
157	extern int sock_bufstat(const Socket s, uint32 socksize_ret,
158	uint32 totalsize_ret, int ratio1_ret,
159	int *ratio2_ret);
160
161	extern void check_sockets(void);
162
163	extern int conn(Socket s, const char host, int port, const char *lhost,
164	int lport);
165	extern int disconn(Socket *s);
166	extern int open_listener(Socket s, const char host, int port, int backlog);
167	extern int close_listener(Socket *s);
168	extern int32 sread(Socket s, char buf, int32 len);
169	extern int32 swrite(Socket s, const char buf, int32 len);
170	extern int32 swritemap(Socket s, const char buf, int32 len);
171	extern int swrite_trigger(Socket s, void param);
172	extern int sgetc(Socket *s);
173	extern char sgets(char buf, int32 len, Socket *s);
174	extern char sgets2(char buf, int32 len, Socket *s);
175	extern int sputs(const char str, Socket s);
176	extern int sockprintf(Socket s, const char fmt,...);
177	extern int vsockprintf(Socket s, const char fmt, va_list args);
178
179	/*************************************************************************/
180
181	#endif /* SOCKETS_H */
182
183	/*
184	* Local variables:
185	* c-file-style: "stroustrup"
186	* c-file-offsets: ((case-label . ) (statement-case-intro . ))
187	* indent-tabs-mode: nil
188	* End:
189	*
190	* vim: expandtab shiftwidth=4:
191	*/