/[svn]/vendor/ircservices-5.1.24/sockets.h
ViewVC logotype

Contents of /vendor/ircservices-5.1.24/sockets.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1171 - (show annotations)
Fri Aug 12 20:00:46 2011 UTC (10 years, 3 months ago) by michael
File MIME type: text/x-csrc
File size: 8604 byte(s)
- 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.

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 */

svnadmin@ircd-hybrid.org
ViewVC Help
Powered by ViewVC 1.1.28