]> git.netwichtig.de Git - user/henk/code/inspircd.git/blob - include/inspsocket.h
execinfo - backtrace() and backtrace_symbols() where available
[user/henk/code/inspircd.git] / include / inspsocket.h
1 /*       +------------------------------------+
2  *       | Inspire Internet Relay Chat Daemon |
3  *       +------------------------------------+
4  *
5  *  InspIRCd is copyright (C) 2002-2006 ChatSpike-Dev.
6  *                       E-mail:
7  *                <brain@chatspike.net>
8  *                <Craig@chatspike.net>
9  *     
10  * Written by Craig Edwards, Craig McLure, and others.
11  * This program is free but copyrighted software; see
12  *            the file COPYING for details.
13  *
14  * ---------------------------------------------------
15  */
16
17 #ifndef __INSP_SOCKET_H__
18 #define __INSP_SOCKET_H__
19
20 #include <sstream>
21 #include <string>
22 #include <deque>
23 #include "inspircd_config.h"
24 #include "dns.h"
25 #include "socket.h"
26
27 /**
28  * States which a socket may be in
29  */
30 enum InspSocketState { I_DISCONNECTED, I_RESOLVING, I_CONNECTING, I_CONNECTED, I_LISTENING, I_ERROR };
31
32 /**
33  * Error types which a socket may exhibit
34  */
35 enum InspSocketError { I_ERR_TIMEOUT, I_ERR_SOCKET, I_ERR_CONNECT, I_ERR_BIND, I_ERR_RESOLVE, I_ERR_WRITE };
36
37 /**
38  * InspSocket is an extendable socket class which modules
39  * can use for TCP socket support. It is fully integrated
40  * into InspIRCds socket loop and attaches its sockets to
41  * the core's instance of the SocketEngine class, meaning
42  * that any sockets you create have the same power and
43  * abilities as a socket created by the core itself.
44  * To use InspSocket, you must inherit a class from it,
45  * and use the InspSocket constructors to establish connections
46  * and bindings.
47  */
48 class InspSocket
49 {
50 private:
51
52         std::deque<std::string> outbuffer;
53
54         /**
55          * The file descriptor of this socket
56          */
57         int fd;
58
59         /**
60          * The resolver for this socket
61          */
62         DNS dns;
63
64         /**
65          * The hostname connected to
66          */
67         char host[MAXBUF];
68
69         /**
70          * The port connected to, or the port
71          * this socket is listening on
72          */
73         int port;
74
75         /**
76          * The state for this socket, either
77          * listening, connecting, connected
78          * or error.
79          */
80         InspSocketState state;
81
82         /**
83          * The host being connected to,
84          * in sockaddr form
85          */
86         insp_sockaddr addr;
87
88         /** 
89          * The host being connected to,
90          * in in_addr form
91          */
92         insp_inaddr addy;
93
94         /**
95          * When this time is reached,
96          * the socket times out if it is
97          * in the CONNECTING state
98          */
99         time_t timeout_end;
100
101         /**
102          * This value is true if the
103          * socket has timed out.
104          */
105         bool timeout;
106         
107         /**
108          * Socket input buffer, used by read(). The class which
109          * extends InspSocket is expected to implement an extendable
110          * buffer which can grow much larger than 64k,
111          * this buffer is just designed to be temporary storage.
112          * space.
113          */
114         char ibuf[65535];
115
116         /**
117          * The IP address being connected
118          * to stored in string form for
119          * easy retrieval by accessors.
120          */
121         char IP[MAXBUF];
122
123         /**
124          * Client sockaddr structure used
125          * by accept()
126          */
127         insp_sockaddr client;
128
129         /**
130          * Server sockaddr structure used
131          * by accept()
132          */
133         insp_sockaddr server;
134
135         /**
136          * Used by accept() to indicate the
137          * sizes of the sockaddr_in structures
138          */
139         socklen_t length;
140
141         /** Flushes the write buffer
142          */
143         bool FlushWriteBuffer();
144
145         /** Set the queue sizes
146          * This private method sets the operating system queue
147          * sizes for this socket to 65535 so that it can queue
148          * more information without application-level queueing
149          * which was required in older software.
150          */
151         void SetQueues(int nfd);
152
153         /** When the socket has been marked as closing, this flag
154          * will be set to true, then the next time the socket is
155          * examined, the socket is deleted and closed.
156          */
157         bool ClosePending;
158
159 public:
160
161         /**
162          * The default constructor does nothing
163          * and should not be used.
164          */
165         InspSocket();
166
167         /**
168          * This constructor is used to associate
169          * an existing connecting with an InspSocket
170          * class. The given file descriptor must be
171          * valid, and when initialized, the InspSocket
172          * will be set with the given IP address
173          * and placed in CONNECTED state.
174          */
175         InspSocket(int newfd, char* ip);
176
177         /**
178          * This constructor is used to create a new
179          * socket, either listening for connections, or an outbound connection to another host.
180          * Note that if you specify a hostname in the 'host' parameter, then there will be an extra
181          * step involved (a nonblocking DNS lookup) which will cause your connection to be established
182          * slower than if it was an IP. Therefore, use an IP address where it is available instead.
183          * @param host The hostname to connect to, or bind to
184          * @param port The port number to connect to, or bind to
185          * @param listening true to listen on the given host:port pair, or false to connect to them
186          * @param maxtime Number of seconds to wait, if connecting, before the connection times out and an OnTimeout() event is generated
187          */
188         InspSocket(const std::string &host, int port, bool listening, unsigned long maxtime);
189
190         /**
191          * This method is called when an outbound
192          * connection on your socket is completed.
193          * @return false to abort the connection, true to continue
194          */
195         virtual bool OnConnected();
196
197         /**
198          * This method is called when an error occurs.
199          * A closed socket in itself is not an error,
200          * however errors also generate close events.
201          * @param e The error type which occured
202          */
203         virtual void OnError(InspSocketError e);
204
205         /**
206          * When an established connection is terminated,
207          * the OnDisconnect method is triggered.
208          */
209         virtual int OnDisconnect();
210
211         /**
212          * When there is data waiting to be read on a
213          * socket, the OnDataReady() method is called.
214          * Within this method, you *MUST* call the Read()
215          * method to read any pending data. At its lowest
216          * level, this event is signalled by the core via
217          * the socket engine. If you return false from this
218          * function, the core removes your socket from its
219          * list and erases it from the socket engine, then
220          * calls InspSocket::Close() and deletes it.
221          * @return false to close the socket
222          */
223         virtual bool OnDataReady();
224
225         /**
226          * When an outbound connection fails, and the
227          * attempt times out, you will receive this event.
228          * The method will trigger once maxtime seconds are
229          * reached (as given in the constructor) just
230          * before the socket's descriptor is closed.
231          * A failed DNS lookup may cause this event if
232          * the DNS server is not responding, as well as
233          * a failed connect() call, because DNS lookups are
234          * nonblocking as implemented by this class.
235          */
236         virtual void OnTimeout();
237
238         /**
239          * Whenever close() is called, OnClose() will be
240          * called first. Please note that this means
241          * OnClose will be called alongside OnError(),
242          * OnTimeout(), and Close(), and also when
243          * cancelling a listening socket by calling
244          * the destructor indirectly.
245          */
246         virtual void OnClose();
247
248         /**
249          * Reads all pending bytes from the socket
250          * into a char* array which can be up to
251          * 16 kilobytes in length.
252          */
253         virtual char* Read();
254
255         /**
256          * Returns the IP address associated with
257          * this connection, or an empty string if
258          * no IP address exists.
259          */
260         std::string GetIP();
261
262         /**
263          * This function checks if the socket has
264          * timed out yet, given the current time
265          * in the parameter.
266          * @return true if timed out, false if not timed out
267          */
268         bool Timeout(time_t current);
269
270         /**
271          * Writes a std::string to the socket. No carriage
272          * returns or linefeeds are appended to the string.
273          * @param data The data to send
274          */
275         virtual int Write(const std::string &data);
276
277         /**
278          * If your socket is a listening socket, when a new
279          * connection comes in on the socket this method will
280          * be called. Given the new file descriptor in the
281          * parameters, and the IP, it is recommended you copy
282          * them to a new instance of your socket class,
283          * e.g.:
284          *
285          * MySocket* newsocket = new MySocket(newfd,ip);
286          *
287          * Once you have done this, you can then associate the
288          * new socket with the core using Server::AddSocket().
289          */
290         virtual int OnIncomingConnection(int newfd, char* ip);
291
292         /**
293          * Changes the socket's state. The core uses this
294          * to change socket states, and you should not call
295          * it directly.
296          */
297         void SetState(InspSocketState s);
298
299         /**
300          * Returns the current socket state.
301          */
302         InspSocketState GetState();
303
304         /**
305          * Only the core should call this function.
306          * When called, it is assumed the socket is ready
307          * to read data, and the method call routes the
308          * event to the various methods of InspSocket
309          * for you to handle. This can also cause the
310          * socket's state to change.
311          */
312         bool Poll();
313
314         /**
315          * This method returns the socket's file descriptor
316          * as assigned by the operating system, or -1
317          * if no descriptor has been assigned.
318          */
319         int GetFd();
320
321         /**
322          * This method causes the socket to close, and may
323          * also be triggered by other methods such as OnTimeout
324          * and OnError.
325          */
326         virtual void Close();
327
328         /**
329          * The destructor may implicitly call OnClose(), and
330          * will close() and shutdown() the file descriptor
331          * used for this socket.
332          */
333         virtual ~InspSocket();
334
335         /**
336          * This method attempts to resolve the hostname,
337          * if a hostname is given and not an IP,
338          * before a connection can occur. This method is
339          * asyncronous.
340          */
341         virtual bool DoResolve();
342
343         /**
344          * This method attempts to connect to a hostname.
345          * This only occurs on a non-listening socket. This
346          * method is asyncronous.
347          */
348         virtual bool DoConnect();
349
350         /**
351          * This method marks the socket closed.
352          * The next time the core examines a socket marked
353          * as closed, the socket will be closed and the 
354          * memory reclaimed.
355          */
356         void MarkAsClosed();
357 };
358
359 #endif