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:	3389
Committed:	Fri Apr 25 14:12:15 2014 UTC (9 years, 11 months ago) by michael
Content type:	text/x-chdr
File size:	8604 byte(s)
Log Message:	- Imported ircservices-5.1.24
#	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	*/