]> git.saurik.com Git - wxWidgets.git/blob - include/wx/private/socket.h
Implement GetSelectedHTML for the ie and gtk webkit backends and document.
[wxWidgets.git] / include / wx / private / socket.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/private/socket.h
3 // Purpose: wxSocketImpl and related declarations
4 // Authors: Guilhem Lavaux, Vadim Zeitlin
5 // Created: April 1997
6 // RCS-ID: $Id$
7 // Copyright: (c) 1997 Guilhem Lavaux
8 // (c) 2008 Vadim Zeitlin
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
11
12 /*
13 Brief overview of different socket classes:
14
15 - wxSocketBase is the public class representing a socket ("Base" here
16 refers to the fact that wxSocketClient and wxSocketServer are derived
17 from it and predates the convention of using "Base" for common base
18 classes for platform-specific classes in wxWidgets) with implementation
19 common to all platforms and forwarding methods whose implementation
20 differs between platforms to wxSocketImpl which it contains.
21
22 - wxSocketImpl is actually just an abstract base class having only code
23 common to all platforms, the concrete implementation classes derive from
24 it and are created by wxSocketImpl::Create().
25
26 - Some socket operations have different implementations in console-mode and
27 GUI applications. wxSocketManager class exists to abstract this in such
28 way that console applications (using wxBase) don't depend on wxNet. An
29 object of this class is made available via wxApp and GUI applications set
30 up a different kind of global socket manager from console ones.
31
32 TODO: it looks like wxSocketManager could be eliminated by providing
33 methods for registering/unregistering sockets directly in
34 wxEventLoop.
35 */
36
37 #ifndef _WX_PRIVATE_SOCKET_H_
38 #define _WX_PRIVATE_SOCKET_H_
39
40 #include "wx/defs.h"
41
42 #if wxUSE_SOCKETS
43
44 #include "wx/socket.h"
45 #include "wx/private/sckaddr.h"
46
47 #include <stddef.h>
48
49 /*
50 Including sys/types.h under Cygwin results in the warnings about "fd_set
51 having been defined in sys/types.h" when winsock.h is included later and
52 doesn't seem to be necessary anyhow. It's not needed under Mac neither.
53 */
54 #if !defined(__WXMAC__) && !defined(__CYGWIN__) && !defined(__WXWINCE__)
55 #include <sys/types.h>
56 #endif
57
58 #ifdef __WXWINCE__
59 #include <stdlib.h>
60 #endif
61
62 // include the header defining timeval: under Windows this struct is used only
63 // with sockets so we need to include winsock.h which we do via windows.h
64 #ifdef __WXMSW__
65 #include "wx/msw/wrapwin.h"
66 #else
67 #include <sys/time.h> // for timeval
68 #endif
69
70 // these definitions are for MSW when we don't use configure, otherwise these
71 // symbols are defined by configure
72 #ifndef WX_SOCKLEN_T
73 #define WX_SOCKLEN_T int
74 #endif
75
76 #ifndef SOCKOPTLEN_T
77 #define SOCKOPTLEN_T int
78 #endif
79
80 // define some symbols which winsock.h defines but traditional BSD headers
81 // don't
82 #ifndef __WXMSW__
83 #define SOCKET int
84 #endif
85
86 #ifndef INVALID_SOCKET
87 #define INVALID_SOCKET (-1)
88 #endif
89
90 #ifndef SOCKET_ERROR
91 #define SOCKET_ERROR (-1)
92 #endif
93
94 typedef int wxSocketEventFlags;
95
96 class wxSocketImpl;
97
98 /*
99 Class providing hooks abstracting the differences between console and GUI
100 applications for socket code.
101
102 We also have different implementations of this class for different platforms
103 allowing us to keep more things in the common code but the main reason for
104 its existence is that we want the same socket code work differently
105 depending on whether it's used from a console or a GUI program. This is
106 achieved by implementing the virtual methods of this class differently in
107 the objects returned by wxConsoleAppTraits::GetSocketManager() and the same
108 method in wxGUIAppTraits.
109 */
110 class wxSocketManager
111 {
112 public:
113 // set the manager to use, we don't take ownership of it
114 //
115 // this should be called before creating the first wxSocket object,
116 // otherwise the manager returned by wxAppTraits::GetSocketManager() will
117 // be used
118 static void Set(wxSocketManager *manager);
119
120 // return the manager to use
121 //
122 // this initializes the manager at first use
123 static wxSocketManager *Get()
124 {
125 if ( !ms_manager )
126 Init();
127
128 return ms_manager;
129 }
130
131 // called before the first wxSocket is created and should do the
132 // initializations needed in order to use the network
133 //
134 // return true if initialized successfully; if this returns false sockets
135 // can't be used at all
136 virtual bool OnInit() = 0;
137
138 // undo the initializations of OnInit()
139 virtual void OnExit() = 0;
140
141
142 // create the socket implementation object matching this manager
143 virtual wxSocketImpl *CreateSocket(wxSocketBase& wxsocket) = 0;
144
145 // these functions enable or disable monitoring of the given socket for the
146 // specified events inside the currently running event loop (but notice
147 // that both BSD and Winsock implementations actually use socket->m_server
148 // value to determine what exactly should be monitored so it needs to be
149 // set before calling these functions)
150 //
151 // the default event value is used just for the convenience of wxMSW
152 // implementation which doesn't use this parameter anyhow, it doesn't make
153 // sense to pass wxSOCKET_LOST for the Unix implementation which does use
154 // this parameter
155 virtual void Install_Callback(wxSocketImpl *socket,
156 wxSocketNotify event = wxSOCKET_LOST) = 0;
157 virtual void Uninstall_Callback(wxSocketImpl *socket,
158 wxSocketNotify event = wxSOCKET_LOST) = 0;
159
160 virtual ~wxSocketManager() { }
161
162 private:
163 // get the manager to use if we don't have it yet
164 static void Init();
165
166 static wxSocketManager *ms_manager;
167 };
168
169 /*
170 Base class for all socket implementations providing functionality common to
171 BSD and Winsock sockets.
172
173 Objects of this class are not created directly but only via the factory
174 function wxSocketManager::CreateSocket().
175 */
176 class wxSocketImpl
177 {
178 public:
179 virtual ~wxSocketImpl();
180
181 // set various socket properties: all of those can only be called before
182 // creating the socket
183 void SetTimeout(unsigned long millisec);
184 void SetReusable() { m_reusable = true; }
185 void SetBroadcast() { m_broadcast = true; }
186 void DontDoBind() { m_dobind = false; }
187 void SetInitialSocketBuffers(int recv, int send)
188 {
189 m_initialRecvBufferSize = recv;
190 m_initialSendBufferSize = send;
191 }
192
193 wxSocketError SetLocal(const wxSockAddressImpl& address);
194 wxSocketError SetPeer(const wxSockAddressImpl& address);
195
196 // accessors
197 // ---------
198
199 bool IsServer() const { return m_server; }
200
201 const wxSockAddressImpl& GetLocal(); // non const as may update m_local
202 const wxSockAddressImpl& GetPeer() const { return m_peer; }
203
204 wxSocketError GetError() const { return m_error; }
205 bool IsOk() const { return m_error == wxSOCKET_NOERROR; }
206
207 // get the error code corresponding to the last operation
208 virtual wxSocketError GetLastError() const = 0;
209
210
211 // creating/closing the socket
212 // --------------------------
213
214 // notice that SetLocal() must be called before creating the socket using
215 // any of the functions below
216 //
217 // all of Create() functions return wxSOCKET_NOERROR if the operation
218 // completed successfully or one of:
219 // wxSOCKET_INVSOCK - the socket is in use.
220 // wxSOCKET_INVADDR - the local (server) or peer (client) address has not
221 // been set.
222 // wxSOCKET_IOERR - any other error.
223
224 // create a socket listening on the local address specified by SetLocal()
225 // (notice that DontDoBind() is ignored by this function)
226 wxSocketError CreateServer();
227
228 // create a socket connected to the peer address specified by SetPeer()
229 // (notice that DontDoBind() is ignored by this function)
230 //
231 // this function may return wxSOCKET_WOULDBLOCK in addition to the return
232 // values listed above if wait is false
233 wxSocketError CreateClient(bool wait);
234
235 // create (and bind unless DontDoBind() had been called) an UDP socket
236 // associated with the given local address
237 wxSocketError CreateUDP();
238
239 // may be called whether the socket was created or not, calls DoClose() if
240 // it was indeed created
241 void Close();
242
243 // shuts down the writing end of the socket and closes it, this is a more
244 // graceful way to close
245 //
246 // does nothing if the socket wasn't created
247 void Shutdown();
248
249
250 // IO operations
251 // -------------
252
253 // basic IO, work for both TCP and UDP sockets
254 //
255 // return the number of bytes read/written (possibly 0) or -1 on error
256 int Read(void *buffer, int size);
257 int Write(const void *buffer, int size);
258
259 // basically a wrapper for select(): returns the condition of the socket,
260 // blocking for not longer than timeout if it is specified (otherwise just
261 // poll without blocking at all)
262 //
263 // flags defines what kind of conditions we're interested in, the return
264 // value is composed of a (possibly empty) subset of the bits set in flags
265 wxSocketEventFlags Select(wxSocketEventFlags flags,
266 const timeval *timeout = NULL);
267
268 // convenient wrapper calling Select() with our default timeout
269 wxSocketEventFlags SelectWithTimeout(wxSocketEventFlags flags)
270 {
271 return Select(flags, &m_timeout);
272 }
273
274 // just a wrapper for accept(): it is called to create a new wxSocketImpl
275 // corresponding to a new server connection represented by the given
276 // wxSocketBase, returns NULL on error (including immediately if there are
277 // no pending connections as our sockets are non-blocking)
278 wxSocketImpl *Accept(wxSocketBase& wxsocket);
279
280
281 // notifications
282 // -------------
283
284 // notify m_wxsocket about the given socket event by calling its (inaptly
285 // named) OnRequest() method
286 void NotifyOnStateChange(wxSocketNotify event);
287
288 // called after reading/writing the data from/to the socket and should
289 // enable back the wxSOCKET_INPUT/OUTPUT_FLAG notifications if they were
290 // turned off when this data was first detected
291 virtual void ReenableEvents(wxSocketEventFlags flags) = 0;
292
293 // TODO: make these fields protected and provide accessors for those of
294 // them that wxSocketBase really needs
295 //protected:
296 SOCKET m_fd;
297
298 int m_initialRecvBufferSize;
299 int m_initialSendBufferSize;
300
301 wxSockAddressImpl m_local,
302 m_peer;
303 wxSocketError m_error;
304
305 bool m_stream;
306 bool m_establishing;
307 bool m_reusable;
308 bool m_broadcast;
309 bool m_dobind;
310
311 struct timeval m_timeout;
312
313 protected:
314 wxSocketImpl(wxSocketBase& wxsocket);
315
316 // true if we're a listening stream socket
317 bool m_server;
318
319 private:
320 // called by Close() if we have a valid m_fd
321 virtual void DoClose() = 0;
322
323 // put this socket into non-blocking mode and enable monitoring this socket
324 // as part of the event loop
325 virtual void UnblockAndRegisterWithEventLoop() = 0;
326
327 // check that the socket wasn't created yet and that the given address
328 // (either m_local or m_peer depending on the socket kind) is valid and
329 // set m_error and return false if this is not the case
330 bool PreCreateCheck(const wxSockAddressImpl& addr);
331
332 // set the given socket option: this just wraps setsockopt(SOL_SOCKET)
333 int SetSocketOption(int optname, int optval)
334 {
335 // although modern Unix systems use "const void *" for the 4th
336 // parameter here, old systems and Winsock still use "const char *"
337 return setsockopt(m_fd, SOL_SOCKET, optname,
338 reinterpret_cast<const char *>(&optval),
339 sizeof(optval));
340 }
341
342 // set the given socket option to true value: this is an even simpler
343 // wrapper for setsockopt(SOL_SOCKET) for boolean options
344 int EnableSocketOption(int optname)
345 {
346 return SetSocketOption(optname, 1);
347 }
348
349 // apply the options to the (just created) socket and register it with the
350 // event loop by calling UnblockAndRegisterWithEventLoop()
351 void PostCreation();
352
353 // update local address after binding/connecting
354 wxSocketError UpdateLocalAddress();
355
356 // functions used to implement Read/Write()
357 int RecvStream(void *buffer, int size);
358 int RecvDgram(void *buffer, int size);
359 int SendStream(const void *buffer, int size);
360 int SendDgram(const void *buffer, int size);
361
362
363 // set in ctor and never changed except that it's reset to NULL when the
364 // socket is shut down
365 wxSocketBase *m_wxsocket;
366
367 wxDECLARE_NO_COPY_CLASS(wxSocketImpl);
368 };
369
370 #if defined(__WXMSW__)
371 #include "wx/msw/private/sockmsw.h"
372 #else
373 #include "wx/unix/private/sockunix.h"
374 #endif
375
376 #endif /* wxUSE_SOCKETS */
377
378 #endif /* _WX_PRIVATE_SOCKET_H_ */