]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: socket.h | |
e54c96f1 | 3 | // Purpose: interface of wxIPV4address |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxIPV4address | |
7c913512 | 11 | |
3d7548cb | 12 | A class for working with IPv4 network addresses. |
7c913512 | 13 | |
23324ae1 FM |
14 | @library{wxbase} |
15 | @category{net} | |
16 | */ | |
17 | class wxIPV4address : public wxIPaddress | |
18 | { | |
19 | public: | |
20 | /** | |
3d7548cb BP |
21 | Set address to any of the addresses of the current machine. |
22 | ||
23 | Whenever possible, use this function instead of LocalHost(), | |
23324ae1 FM |
24 | as this correctly handles multi-homed hosts and avoids other small |
25 | problems. Internally, this is the same as setting the IP address | |
26 | to @b INADDR_ANY. | |
3c4f71cc | 27 | |
3d7548cb | 28 | @return @true on success, @false if something went wrong. |
23324ae1 FM |
29 | */ |
30 | bool AnyAddress(); | |
31 | ||
23324ae1 | 32 | /** |
3d7548cb BP |
33 | Set the address to hostname, which can be a host name or an IP-style address |
34 | in dot notation(<tt>a.b.c.d</tt>) | |
35 | ||
36 | @return @true on success, @false if something goes wrong (invalid hostname or | |
37 | invalid IP address). | |
23324ae1 FM |
38 | */ |
39 | bool Hostname(const wxString& hostname); | |
3d7548cb BP |
40 | |
41 | /** | |
42 | Returns the hostname which matches the IP address. | |
43 | */ | |
44 | wxString Hostname(); | |
23324ae1 FM |
45 | |
46 | /** | |
47 | Returns a wxString containing the IP address in dot quad (127.0.0.1) format. | |
48 | */ | |
49 | wxString IPAddress(); | |
50 | ||
51 | /** | |
3d7548cb BP |
52 | Set address to localhost (127.0.0.1). |
53 | ||
54 | Whenever possible, use AnyAddress() instead of this one, as that one will | |
55 | correctly handle multi-homed hosts and avoid other small problems. | |
56 | ||
57 | @return @true on success, @false if something went wrong. | |
58 | ||
23324ae1 FM |
59 | */ |
60 | bool LocalHost(); | |
61 | ||
23324ae1 | 62 | /** |
3d7548cb BP |
63 | Set the port to that corresponding to the specified @a service. |
64 | ||
65 | @return @true on success, @false if something goes wrong (invalid @a service). | |
66 | ||
23324ae1 FM |
67 | */ |
68 | bool Service(const wxString& service); | |
3d7548cb BP |
69 | |
70 | /** | |
71 | Set the port to that corresponding to the specified @a service. | |
72 | ||
73 | @return @true on success, @false if something goes wrong (invalid @a service). | |
74 | */ | |
75 | bool Service(unsigned short service); | |
76 | ||
77 | /** | |
78 | Returns the current service. | |
79 | */ | |
80 | unsigned short Service(); | |
23324ae1 FM |
81 | }; |
82 | ||
83 | ||
e54c96f1 | 84 | |
23324ae1 FM |
85 | /** |
86 | @class wxSocketServer | |
7c913512 | 87 | |
23324ae1 FM |
88 | @library{wxnet} |
89 | @category{net} | |
23324ae1 FM |
90 | */ |
91 | class wxSocketServer : public wxSocketBase | |
92 | { | |
93 | public: | |
94 | /** | |
95 | Constructs a new server and tries to bind to the specified @e address. | |
3d7548cb BP |
96 | |
97 | Before trying to accept new connections, remember to test whether it succeeded | |
98 | with wxSocketBase:IsOk(). | |
3c4f71cc | 99 | |
7c913512 | 100 | @param address |
4cc4bfaf | 101 | Specifies the local address for the server (e.g. port number). |
7c913512 | 102 | @param flags |
3d7548cb | 103 | Socket flags (See wxSocketBase::SetFlags()) |
23324ae1 FM |
104 | */ |
105 | wxSocketServer(const wxSockAddress& address, | |
106 | wxSocketFlags flags = wxSOCKET_NONE); | |
107 | ||
108 | /** | |
109 | Destructor (it doesn't close the accepted connections). | |
110 | */ | |
111 | ~wxSocketServer(); | |
112 | ||
113 | /** | |
3d7548cb BP |
114 | Accepts an incoming connection request, and creates a new wxSocketBase object |
115 | which represents the server-side of the connection. | |
116 | ||
4cc4bfaf | 117 | If @a wait is @true and there are no pending connections to be |
23324ae1 FM |
118 | accepted, it will wait for the next incoming connection to |
119 | arrive. @b Warning: This will block the GUI. | |
3d7548cb | 120 | |
4cc4bfaf | 121 | If @a wait is @false, it will try to accept a pending connection |
23324ae1 | 122 | if there is one, but it will always return immediately without blocking |
3d7548cb BP |
123 | the GUI. If you want to use Accept() in this way, you can either check for |
124 | incoming connections with WaitForAccept() or catch @b wxSOCKET_CONNECTION events, | |
125 | then call Accept() once you know that there is an incoming connection waiting | |
126 | to be accepted. | |
3c4f71cc | 127 | |
d29a9a8a | 128 | @return Returns an opened socket connection, or @NULL if an error |
3d7548cb BP |
129 | occurred or if the wait parameter was @false and there |
130 | were no pending connections. | |
3c4f71cc | 131 | |
3d7548cb BP |
132 | @see WaitForAccept(), wxSocketBase::SetNotify(), |
133 | wxSocketBase::Notify(), AcceptWith() | |
23324ae1 | 134 | */ |
4cc4bfaf | 135 | wxSocketBase* Accept(bool wait = true); |
23324ae1 FM |
136 | |
137 | /** | |
138 | Accept an incoming connection using the specified socket object. | |
3c4f71cc | 139 | |
7c913512 | 140 | @param socket |
4cc4bfaf | 141 | Socket to be initialized |
3c4f71cc | 142 | |
d29a9a8a | 143 | @return Returns @true on success, or @false if an error occurred or if the |
4cc4bfaf FM |
144 | wait parameter was @false and there were no pending |
145 | connections. | |
3d7548cb BP |
146 | |
147 | @see WaitForAccept(), wxSocketBase::SetNotify(), | |
148 | wxSocketBase::Notify(), Accept() | |
23324ae1 | 149 | */ |
4cc4bfaf | 150 | bool AcceptWith(wxSocketBase& socket, bool wait = true); |
23324ae1 FM |
151 | |
152 | /** | |
7c913512 FM |
153 | This function waits for an incoming connection. Use it if you want to call |
154 | Accept() or AcceptWith() | |
23324ae1 FM |
155 | with @e wait set to @false, to detect when an incoming connection is waiting |
156 | to be accepted. | |
3c4f71cc | 157 | |
7c913512 | 158 | @param seconds |
3d7548cb BP |
159 | Number of seconds to wait. If -1, it will wait for the default |
160 | timeout, as set with wxSocketBase::SetTimeout(). | |
7c913512 | 161 | @param millisecond |
4cc4bfaf | 162 | Number of milliseconds to wait. |
3c4f71cc | 163 | |
3d7548cb BP |
164 | @return @true if an incoming connection arrived, @false if the timeout |
165 | elapsed. | |
166 | ||
167 | @see Accept(), AcceptWith(), wxSocketBase::InterruptWait() | |
23324ae1 FM |
168 | */ |
169 | bool WaitForAccept(long seconds = -1, long millisecond = 0); | |
170 | }; | |
171 | ||
172 | ||
e54c96f1 | 173 | |
23324ae1 FM |
174 | /** |
175 | @class wxIPaddress | |
7c913512 FM |
176 | |
177 | wxIPaddress is an abstract base class for all internet protocol address | |
3d7548cb BP |
178 | objects. Currently, only wxIPV4address is implemented. An experimental |
179 | implementation for IPV6, wxIPV6address, is being developed. | |
7c913512 | 180 | |
23324ae1 FM |
181 | @library{wxbase} |
182 | @category{net} | |
183 | */ | |
184 | class wxIPaddress : public wxSockAddress | |
185 | { | |
186 | public: | |
187 | /** | |
3d7548cb BP |
188 | Internally, this is the same as setting the IP address to @b INADDR_ANY. |
189 | ||
23324ae1 | 190 | On IPV4 implementations, 0.0.0.0 |
3d7548cb | 191 | |
23324ae1 | 192 | On IPV6 implementations, :: |
3c4f71cc | 193 | |
3d7548cb | 194 | @return @true on success, @false if something went wrong. |
23324ae1 FM |
195 | */ |
196 | virtual bool AnyAddress(); | |
197 | ||
198 | /** | |
3d7548cb BP |
199 | Internally, this is the same as setting the IP address to @b INADDR_BROADCAST. |
200 | ||
23324ae1 | 201 | On IPV4 implementations, 255.255.255.255 |
3c4f71cc | 202 | |
3d7548cb | 203 | @return @true on success, @false if something went wrong. |
23324ae1 FM |
204 | */ |
205 | virtual bool BroadcastAddress(); | |
206 | ||
23324ae1 | 207 | /** |
3d7548cb BP |
208 | Set the address to hostname, which can be a host name or an IP-style address |
209 | in a format dependent on implementation. | |
210 | ||
211 | @return @true on success, @false if something goes wrong (invalid | |
212 | hostname or invalid IP address). | |
23324ae1 FM |
213 | */ |
214 | virtual bool Hostname(const wxString& hostname); | |
3d7548cb BP |
215 | |
216 | /** | |
217 | Returns the hostname which matches the IP address. | |
218 | */ | |
219 | virtual wxString Hostname(); | |
23324ae1 FM |
220 | |
221 | /** | |
222 | Returns a wxString containing the IP address. | |
223 | */ | |
224 | virtual wxString IPAddress(); | |
225 | ||
226 | /** | |
227 | Determines if current address is set to localhost. | |
3d7548cb BP |
228 | |
229 | @return @true if address is localhost, @false if internet address. | |
23324ae1 FM |
230 | */ |
231 | virtual bool IsLocalHost(); | |
232 | ||
233 | /** | |
7c913512 | 234 | Set address to localhost. |
3d7548cb | 235 | |
23324ae1 | 236 | On IPV4 implementations, 127.0.0.1 |
3d7548cb | 237 | |
23324ae1 | 238 | On IPV6 implementations, ::1 |
3c4f71cc | 239 | |
3d7548cb | 240 | @return @true on success, @false if something went wrong. |
23324ae1 FM |
241 | */ |
242 | virtual bool LocalHost(); | |
243 | ||
23324ae1 | 244 | /** |
3d7548cb BP |
245 | Set the port to that corresponding to the specified service. |
246 | ||
247 | @return @true on success, @false if something goes wrong (invalid @a service). | |
23324ae1 FM |
248 | */ |
249 | virtual bool Service(const wxString& service); | |
3d7548cb BP |
250 | |
251 | /** | |
252 | Set the port to that corresponding to the specified service. | |
253 | ||
254 | @return @true on success, @false if something goes wrong (invalid @a service). | |
255 | */ | |
256 | virtual bool Service(unsigned short service); | |
257 | ||
258 | /** | |
259 | Returns the current service. | |
260 | */ | |
261 | virtual unsigned short Service(); | |
23324ae1 FM |
262 | }; |
263 | ||
264 | ||
e54c96f1 | 265 | |
23324ae1 FM |
266 | /** |
267 | @class wxSocketClient | |
7c913512 | 268 | |
23324ae1 FM |
269 | @library{wxnet} |
270 | @category{net} | |
23324ae1 FM |
271 | */ |
272 | class wxSocketClient : public wxSocketBase | |
273 | { | |
274 | public: | |
275 | /** | |
276 | Constructor. | |
3c4f71cc | 277 | |
7c913512 | 278 | @param flags |
3d7548cb | 279 | Socket flags (See wxSocketBase::SetFlags()) |
23324ae1 FM |
280 | */ |
281 | wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE); | |
282 | ||
283 | /** | |
3d7548cb | 284 | Destructor. Please see wxSocketBase::Destroy(). |
23324ae1 FM |
285 | */ |
286 | ~wxSocketClient(); | |
287 | ||
23324ae1 FM |
288 | /** |
289 | Connects to a server using the specified address. | |
3d7548cb BP |
290 | |
291 | If @a wait is @true, Connect() will wait until the connection | |
23324ae1 | 292 | completes. @b Warning: This will block the GUI. |
3d7548cb BP |
293 | |
294 | If @a wait is @false, Connect() will try to establish the connection | |
295 | and return immediately, without blocking the GUI. When used this way, | |
296 | even if Connect() returns @false, the connection request can be | |
297 | completed later. To detect this, use WaitOnConnect(), or catch | |
298 | @b wxSOCKET_CONNECTION events (for successful establishment) and | |
299 | @b wxSOCKET_LOST events (for connection failure). | |
300 | ||
301 | @param address | |
302 | Address of the server. | |
303 | @param wait | |
304 | If @true, waits for the connection to complete. | |
305 | ||
306 | @return @true if the connection is established and no error occurs. | |
307 | ||
308 | @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify() | |
309 | */ | |
310 | bool Connect(const wxSockAddress& address, bool wait = true); | |
311 | ||
312 | /** | |
313 | Connects to a server using the specified address. | |
314 | ||
315 | If @a wait is @true, Connect() will wait until the connection | |
316 | completes. @b Warning: This will block the GUI. | |
317 | ||
318 | If @a wait is @false, Connect() will try to establish the connection | |
319 | and return immediately, without blocking the GUI. When used this way, | |
320 | even if Connect() returns @false, the connection request can be | |
321 | completed later. To detect this, use WaitOnConnect(), or catch | |
322 | @b wxSOCKET_CONNECTION events (for successful establishment) and | |
323 | @b wxSOCKET_LOST events (for connection failure). | |
3c4f71cc | 324 | |
7c913512 | 325 | @param address |
4cc4bfaf | 326 | Address of the server. |
7c913512 | 327 | @param local |
4cc4bfaf | 328 | Bind to the specified local address and port before connecting. |
3d7548cb BP |
329 | The local address and port can also be set using SetLocal(), |
330 | and then using the 2-parameter Connect() method. | |
7c913512 | 331 | @param wait |
4cc4bfaf | 332 | If @true, waits for the connection to complete. |
3c4f71cc | 333 | |
3d7548cb | 334 | @return @true if the connection is established and no error occurs. |
3c4f71cc | 335 | |
3d7548cb | 336 | @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify() |
23324ae1 | 337 | */ |
72ac4e88 | 338 | bool Connect(const wxSockAddress& address, const wxSockAddress& local, |
4cc4bfaf | 339 | bool wait = true); |
23324ae1 FM |
340 | |
341 | /** | |
342 | Wait until a connection request completes, or until the specified timeout | |
343 | elapses. Use this function after issuing a call | |
344 | to Connect() with @e wait set to @false. | |
3c4f71cc | 345 | |
7c913512 | 346 | @param seconds |
4cc4bfaf FM |
347 | Number of seconds to wait. |
348 | If -1, it will wait for the default timeout, | |
3d7548cb | 349 | as set with wxSocketBase::SetTimeout(). |
7c913512 | 350 | @param millisecond |
4cc4bfaf | 351 | Number of milliseconds to wait. |
3c4f71cc | 352 | |
3d7548cb BP |
353 | @return WaitOnConnect() returns @true if the connection request completes. |
354 | This does not necessarily mean that the connection was | |
355 | successfully established; it might also happen that the | |
356 | connection was refused by the peer. Use wxSocketBase::IsConnected() | |
357 | to distinguish between these two situations. | |
358 | @n @n If the timeout elapses, WaitOnConnect() returns @false. | |
359 | @n @n These semantics allow code like this: | |
360 | @code | |
361 | // Issue the connection request | |
362 | client->Connect(addr, false); | |
363 | ||
364 | // Wait until the request completes or until we decide to give up | |
365 | bool waitmore = true; | |
366 | while ( !client->WaitOnConnect(seconds, millis) && waitmore ) | |
367 | { | |
368 | // possibly give some feedback to the user, | |
369 | // and update waitmore as needed. | |
370 | } | |
371 | bool success = client->IsConnected(); | |
372 | @endcode | |
23324ae1 FM |
373 | */ |
374 | bool WaitOnConnect(long seconds = -1, long milliseconds = 0); | |
375 | }; | |
376 | ||
377 | ||
e54c96f1 | 378 | |
23324ae1 FM |
379 | /** |
380 | @class wxSockAddress | |
7c913512 | 381 | |
23324ae1 | 382 | You are unlikely to need to use this class: only wxSocketBase uses it. |
7c913512 | 383 | |
23324ae1 | 384 | @library{wxbase} |
3d7548cb | 385 | @category{net} |
7c913512 | 386 | |
e54c96f1 | 387 | @see wxSocketBase, wxIPaddress, wxIPV4address |
23324ae1 FM |
388 | */ |
389 | class wxSockAddress : public wxObject | |
390 | { | |
391 | public: | |
392 | /** | |
393 | Default constructor. | |
394 | */ | |
395 | wxSockAddress(); | |
396 | ||
397 | /** | |
398 | Default destructor. | |
399 | */ | |
400 | ~wxSockAddress(); | |
401 | ||
402 | /** | |
403 | Delete all informations about the address. | |
404 | */ | |
405 | void Clear(); | |
406 | ||
407 | /** | |
408 | Returns the length of the socket address. | |
409 | */ | |
410 | int SockAddrLen(); | |
411 | }; | |
412 | ||
413 | ||
e54c96f1 | 414 | |
23324ae1 FM |
415 | /** |
416 | @class wxSocketEvent | |
7c913512 | 417 | |
23324ae1 | 418 | This event class contains information about socket events. |
7c913512 | 419 | |
3d7548cb BP |
420 | @beginEventTable{wxSocketEvent} |
421 | @event{EVT_SOCKET(id, func)} | |
422 | Process a socket event, supplying the member function. | |
423 | @endEventTable | |
424 | ||
23324ae1 FM |
425 | @library{wxnet} |
426 | @category{net} | |
7c913512 | 427 | |
e54c96f1 | 428 | @see wxSocketBase, wxSocketClient, wxSocketServer |
23324ae1 FM |
429 | */ |
430 | class wxSocketEvent : public wxEvent | |
431 | { | |
432 | public: | |
433 | /** | |
434 | Constructor. | |
435 | */ | |
436 | wxSocketEvent(int id = 0); | |
437 | ||
438 | /** | |
439 | Gets the client data of the socket which generated this event, as | |
3d7548cb | 440 | set with wxSocketBase::SetClientData(). |
23324ae1 | 441 | */ |
4cc4bfaf | 442 | void* GetClientData(); |
23324ae1 FM |
443 | |
444 | /** | |
445 | Returns the socket object to which this event refers to. This makes | |
446 | it possible to use the same event handler for different sockets. | |
447 | */ | |
328f5751 | 448 | wxSocketBase* GetSocket() const; |
23324ae1 FM |
449 | |
450 | /** | |
451 | Returns the socket event type. | |
452 | */ | |
328f5751 | 453 | wxSocketNotify GetSocketEvent() const; |
23324ae1 FM |
454 | }; |
455 | ||
456 | ||
3d7548cb BP |
457 | /** |
458 | wxSocket error return values. | |
459 | */ | |
460 | enum wxSocketError | |
461 | { | |
462 | wxSOCKET_NOERROR, ///< No error happened. | |
463 | wxSOCKET_INVOP, ///< Invalid operation. | |
464 | wxSOCKET_IOERR, ///< Input/Output error. | |
465 | wxSOCKET_INVADDR, ///< Invalid address passed to wxSocket. | |
466 | wxSOCKET_INVSOCK, ///< Invalid socket (uninitialized). | |
467 | wxSOCKET_NOHOST, ///< No corresponding host. | |
468 | wxSOCKET_INVPORT, ///< Invalid port. | |
469 | wxSOCKET_WOULDBLOCK, ///< The socket is non-blocking and the operation would block. | |
470 | wxSOCKET_TIMEDOUT, ///< The timeout for this operation expired. | |
471 | wxSOCKET_MEMERR ///< Memory exhausted. | |
472 | }; | |
473 | ||
474 | ||
475 | /** | |
476 | wxSocket Event Flags. | |
477 | ||
478 | A brief note on how to use these events: | |
479 | ||
480 | The @b wxSOCKET_INPUT event will be issued whenever there is data available | |
481 | for reading. This will be the case if the input queue was empty and new data | |
482 | arrives, or if the application has read some data yet there is still more data | |
483 | available. This means that the application does not need to read all available | |
484 | data in response to a @b wxSOCKET_INPUT event, as more events will be produced | |
485 | as necessary. | |
486 | ||
487 | The @b wxSOCKET_OUTPUT event is issued when a socket is first connected with | |
488 | Connect() or accepted with Accept(). After that, new events will be generated | |
489 | only after an output operation fails with @b wxSOCKET_WOULDBLOCK and buffer space | |
490 | becomes available again. This means that the application should assume that it can | |
491 | write data to the socket until an @b wxSOCKET_WOULDBLOCK error occurs; after this, | |
492 | whenever the socket becomes writable again the application will be notified with | |
493 | another @b wxSOCKET_OUTPUT event. | |
494 | ||
495 | The @b wxSOCKET_CONNECTION event is issued when a delayed connection request completes | |
496 | successfully (client) or when a new connection arrives at the incoming queue (server). | |
497 | ||
498 | The @b wxSOCKET_LOST event is issued when a close indication is received for the socket. | |
499 | This means that the connection broke down or that it was closed by the peer. Also, this | |
500 | event will be issued if a connection request fails. | |
501 | */ | |
502 | enum wxSocketEventFlags | |
503 | { | |
504 | wxSOCKET_INPUT, ///< There is data available for reading. | |
505 | wxSOCKET_OUTPUT, ///< The socket is ready to be written to. | |
506 | wxSOCKET_CONNECTION, ///< Incoming connection request (server), or | |
507 | ///< successful connection establishment (client). | |
508 | wxSOCKET_LOST ///< The connection has been closed. | |
509 | }; | |
510 | ||
511 | ||
512 | /** | |
513 | @anchor wxSocketFlags | |
514 | ||
515 | wxSocket Flags. | |
516 | ||
517 | A brief overview on how to use these flags follows. | |
518 | ||
519 | If no flag is specified (this is the same as @b wxSOCKET_NONE), | |
520 | IO calls will return after some data has been read or written, even | |
521 | when the transfer might not be complete. This is the same as issuing | |
522 | exactly one blocking low-level call to @b recv() or @b send(). Note | |
523 | that @e blocking here refers to when the function returns, not | |
524 | to whether the GUI blocks during this time. | |
525 | ||
526 | If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately. | |
527 | Read operations will retrieve only available data. Write operations will | |
528 | write as much data as possible, depending on how much space is available | |
529 | in the output buffer. This is the same as issuing exactly one nonblocking | |
530 | low-level call to @b recv() or @b send(). Note that @e nonblocking here | |
531 | refers to when the function returns, not to whether the GUI blocks during | |
532 | this time. | |
533 | ||
534 | If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL | |
535 | the data has been read or written (or until an error occurs), blocking if | |
536 | necessary, and issuing several low level calls if necessary. This is the | |
537 | same as having a loop which makes as many blocking low-level calls to | |
538 | @b recv() or @b send() as needed so as to transfer all the data. Note | |
539 | that @e blocking here refers to when the function returns, not | |
540 | to whether the GUI blocks during this time. | |
541 | ||
542 | The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during | |
543 | IO operations. If this flag is specified, the socket will not yield | |
544 | during IO calls, so the GUI will remain blocked until the operation | |
545 | completes. If it is not used, then the application must take extra | |
546 | care to avoid unwanted reentrance. | |
547 | ||
548 | The @b wxSOCKET_REUSEADDR flag controls the use of the @b SO_REUSEADDR standard | |
549 | @b setsockopt() flag. This flag allows the socket to bind to a port that is | |
550 | already in use. This is mostly used on UNIX-based systems to allow rapid starting | |
551 | and stopping of a server, otherwise you may have to wait several minutes for the | |
552 | port to become available. | |
553 | ||
554 | @b wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a | |
555 | particular local port for an outgoing connection. | |
556 | This option can have surprising platform dependent behavior, so check the | |
557 | documentation for your platform's implementation of setsockopt(). | |
558 | ||
559 | Note that on BSD-based systems(e.g. Mac OS X), use of | |
560 | @b wxSOCKET_REUSEADDR implies @b SO_REUSEPORT in addition to | |
561 | @b SO_REUSEADDR to be consistent with Windows. | |
562 | ||
563 | The @b wxSOCKET_BROADCAST flag controls the use of the @b SO_BROADCAST standard | |
564 | @b setsockopt() flag. This flag allows the socket to use the broadcast address, | |
565 | and is generally used in conjunction with @b wxSOCKET_NOBIND and | |
566 | wxIPaddress::BroadcastAddress(). | |
567 | ||
568 | So: | |
569 | @b wxSOCKET_NONE will try to read at least SOME data, no matter how much. | |
570 | @b wxSOCKET_NOWAIT will always return immediately, even if it cannot | |
571 | read or write ANY data. | |
572 | @b wxSOCKET_WAITALL will only return when it has read or written ALL | |
573 | the data. | |
574 | @b wxSOCKET_BLOCK has nothing to do with the previous flags and | |
575 | it controls whether the GUI blocks. | |
576 | @b wxSOCKET_REUSEADDR controls special platform-specific behavior for | |
577 | reusing local addresses/ports. | |
578 | */ | |
579 | enum | |
580 | { | |
581 | wxSOCKET_NONE = 0, ///< Normal functionality. | |
582 | wxSOCKET_NOWAIT = 1, ///< Read/write as much data as possible and return immediately. | |
583 | wxSOCKET_WAITALL = 2, ///< Wait for all required data to be read/written unless an error occurs. | |
584 | wxSOCKET_BLOCK = 4, ///< Block the GUI (do not yield) while reading/writing data. | |
585 | wxSOCKET_REUSEADDR = 8, ///< Allows the use of an in-use port (wxServerSocket only) | |
586 | wxSOCKET_BROADCAST = 16, ///< Switches the socket to broadcast mode | |
587 | wxSOCKET_NOBIND = 32 ///< Stops the socket from being bound to a specific | |
588 | ///< adapter (normally used in conjunction with | |
589 | ///< @b wxSOCKET_BROADCAST) | |
590 | }; | |
591 | ||
e54c96f1 | 592 | |
23324ae1 FM |
593 | /** |
594 | @class wxSocketBase | |
7c913512 | 595 | |
3d7548cb | 596 | |
23324ae1 FM |
597 | wxSocketBase is the base class for all socket-related objects, and it |
598 | defines all basic IO functionality. | |
7c913512 | 599 | |
3d7548cb | 600 | @b Note: (Workaround for implementation limitation for wxWidgets up to 2.5.x) |
23324ae1 FM |
601 | If you want to use sockets or derived classes such as wxFTP in a secondary |
602 | thread, | |
3d7548cb BP |
603 | call @b wxSocketBase::Initialize() (undocumented) from the main thread before |
604 | creating any sockets - in wxApp::OnInit() for example. | |
23324ae1 FM |
605 | See http://wiki.wxwidgets.org/wiki.pl?WxSocket or |
606 | http://www.litwindow.com/knowhow/knowhow.html for more details. | |
7c913512 | 607 | |
23324ae1 FM |
608 | @library{wxnet} |
609 | @category{net} | |
7c913512 | 610 | |
3d7548cb BP |
611 | <b>wxSocket events:</b> |
612 | @beginFlagTable | |
613 | @flag{wxSOCKET_INPUT} | |
614 | There is data available for reading. | |
615 | @flag{wxSOCKET_OUTPUT} | |
616 | The socket is ready to be written to. | |
617 | @flag{wxSOCKET_CONNECTION} | |
618 | Incoming connection request (server), or successful connection | |
619 | establishment (client). | |
620 | @flag{wxSOCKET_LOST} | |
621 | The connection has been closed. | |
622 | @endFlagTable | |
623 | ||
624 | @beginEventTable{wxSocketEvent} | |
625 | @event{EVT_SOCKET(id, func)} | |
626 | Process a @c wxEVT_SOCKET event. | |
627 | @endEventTable | |
628 | ||
629 | @see wxSocketEvent, wxSocketClient, wxSocketServer, @sample{sockets}, | |
630 | @ref wxSocketFlags, ::wxSocketEventFlags, ::wxSocketError | |
23324ae1 FM |
631 | */ |
632 | class wxSocketBase : public wxObject | |
633 | { | |
634 | public: | |
23324ae1 FM |
635 | |
636 | /** | |
3d7548cb | 637 | @name Construction and Destruction |
23324ae1 | 638 | */ |
3d7548cb | 639 | //@{ |
23324ae1 FM |
640 | |
641 | /** | |
3d7548cb | 642 | Default constructor. |
3c4f71cc | 643 | |
3d7548cb BP |
644 | Don't use it directly; instead, use wxSocketClient to construct a socket client, |
645 | or wxSocketServer to construct a socket server. | |
23324ae1 | 646 | */ |
3d7548cb | 647 | wxSocketBase(); |
23324ae1 FM |
648 | |
649 | /** | |
3d7548cb BP |
650 | Destructor. |
651 | ||
652 | Do not destroy a socket using the delete operator directly; | |
653 | use Destroy() instead. Also, do not create socket objects in the stack. | |
23324ae1 | 654 | */ |
3d7548cb | 655 | ~wxSocketBase(); |
23324ae1 FM |
656 | |
657 | /** | |
3d7548cb | 658 | Destroys the socket safely. |
3c4f71cc | 659 | |
3d7548cb BP |
660 | Use this function instead of the delete operator, since otherwise socket events |
661 | could reach the application even after the socket has been destroyed. To prevent | |
662 | this problem, this function appends the wxSocket to a list of object to be deleted | |
663 | on idle time, after all events have been processed. For the same reason, you should | |
664 | avoid creating socket objects in the stack. | |
3c4f71cc | 665 | |
3d7548cb | 666 | Destroy() calls Close() automatically. |
3c4f71cc | 667 | |
d29a9a8a | 668 | @return Always @true. |
23324ae1 FM |
669 | */ |
670 | bool Destroy(); | |
671 | ||
3d7548cb BP |
672 | //@} |
673 | ||
674 | ||
23324ae1 | 675 | /** |
3d7548cb | 676 | @name Socket State |
23324ae1 | 677 | */ |
3d7548cb | 678 | //@{ |
23324ae1 FM |
679 | |
680 | /** | |
681 | Returns @true if an error occurred in the last IO operation. | |
c9157492 | 682 | |
3d7548cb BP |
683 | Use this function to check for an error condition after one of the |
684 | following calls: Discard(), Peek(), Read(), ReadMsg(), Unread(), Write(), WriteMsg(). | |
23324ae1 | 685 | */ |
328f5751 | 686 | bool Error() const; |
23324ae1 | 687 | |
23324ae1 FM |
688 | /** |
689 | This function returns the local address field of the socket. The local | |
690 | address field contains the complete local address of the socket (local | |
691 | address, local port, ...). | |
3c4f71cc | 692 | |
d29a9a8a | 693 | @return @true if no error happened, @false otherwise. |
23324ae1 | 694 | */ |
328f5751 | 695 | bool GetLocal(wxSockAddress& addr) const; |
23324ae1 FM |
696 | |
697 | /** | |
7c913512 | 698 | This function returns the peer address field of the socket. The peer |
23324ae1 FM |
699 | address field contains the complete peer host address of the socket |
700 | (address, port, ...). | |
3c4f71cc | 701 | |
d29a9a8a | 702 | @return @true if no error happened, @false otherwise. |
23324ae1 | 703 | */ |
328f5751 | 704 | bool GetPeer(wxSockAddress& addr) const; |
23324ae1 | 705 | |
23324ae1 FM |
706 | /** |
707 | Returns @true if the socket is connected. | |
708 | */ | |
328f5751 | 709 | bool IsConnected() const; |
23324ae1 | 710 | |
c9157492 | 711 | /** |
3d7548cb | 712 | This function waits until the socket is readable. |
c9157492 | 713 | |
3d7548cb BP |
714 | This might mean that queued data is available for reading or, for streamed |
715 | sockets, that the connection has been closed, so that a read operation will | |
716 | complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag | |
23324ae1 FM |
717 | is set, in which case the operation might still block). |
718 | */ | |
328f5751 | 719 | bool IsData() const; |
23324ae1 FM |
720 | |
721 | /** | |
722 | Returns @true if the socket is not connected. | |
723 | */ | |
328f5751 | 724 | bool IsDisconnected() const; |
23324ae1 FM |
725 | |
726 | /** | |
727 | Returns @true if the socket is initialized and ready and @false in other | |
728 | cases. | |
3d7548cb BP |
729 | |
730 | @remarks | |
731 | ||
732 | For wxSocketClient, IsOk() won't return @true unless the client is connected to a server. | |
733 | ||
734 | For wxSocketServer, IsOk() will return @true if the server could bind to the specified address | |
735 | and is already listening for new connections. | |
736 | ||
737 | IsOk() does not check for IO errors; use Error() instead for that purpose. | |
738 | ||
23324ae1 | 739 | */ |
328f5751 | 740 | bool IsOk() const; |
23324ae1 FM |
741 | |
742 | /** | |
743 | Returns the number of bytes read or written by the last IO call. | |
3d7548cb | 744 | |
23324ae1 | 745 | Use this function to get the number of bytes actually transferred |
3d7548cb BP |
746 | after using one of the following IO calls: Discard(), Peek(), Read(), |
747 | ReadMsg(), Unread(), Write(), WriteMsg(). | |
23324ae1 | 748 | */ |
328f5751 | 749 | wxUint32 LastCount() const; |
23324ae1 FM |
750 | |
751 | /** | |
3d7548cb BP |
752 | Returns the last wxSocket error. See @ref wxSocketError . |
753 | ||
754 | @note | |
755 | ||
756 | This function merely returns the last error code, | |
23324ae1 FM |
757 | but it should not be used to determine if an error has occurred (this |
758 | is because successful operations do not change the LastError value). | |
3d7548cb BP |
759 | Use Error() first, in order to determine if the last IO call failed. |
760 | If this returns @true, use LastError() to discover the cause of the error. | |
23324ae1 | 761 | */ |
328f5751 | 762 | wxSocketError LastError() const; |
23324ae1 FM |
763 | |
764 | /** | |
3d7548cb BP |
765 | This function restores the previous state of the socket, as saved |
766 | with SaveState(). | |
767 | ||
768 | Calls to SaveState() and RestoreState() can be nested. | |
769 | ||
770 | @see SaveState() | |
23324ae1 | 771 | */ |
3d7548cb BP |
772 | void RestoreState(); |
773 | ||
774 | /** | |
775 | This function saves the current state of the socket in a stack. Socket | |
776 | state includes flags, as set with SetFlags(), | |
777 | event mask, as set with SetNotify() and | |
778 | Notify(), user data, as set with | |
779 | SetClientData(). | |
780 | Calls to SaveState and RestoreState can be nested. | |
781 | ||
782 | @see RestoreState() | |
783 | */ | |
784 | void SaveState(); | |
785 | ||
786 | //@} | |
787 | ||
788 | ||
789 | /** | |
790 | @name Basic I/O | |
791 | ||
792 | See also: wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect() | |
793 | */ | |
794 | //@{ | |
795 | ||
796 | /** | |
797 | This function shuts down the socket, disabling further transmission and | |
798 | reception of data; it also disables events for the socket and frees the | |
799 | associated system resources. | |
800 | ||
801 | Upon socket destruction, Close() is automatically called, so in most cases | |
802 | you won't need to do it yourself, unless you explicitly want to shut down | |
803 | the socket, typically to notify the peer that you are closing the connection. | |
804 | ||
805 | @remarks | |
806 | ||
807 | Although Close() immediately disables events for the socket, it is possible | |
808 | that event messages may be waiting in the application's event queue. | |
809 | The application must therefore be prepared to handle socket event messages even | |
810 | after calling Close(). | |
811 | */ | |
812 | void Close(); | |
813 | ||
814 | /** | |
815 | This function simply deletes all bytes in the incoming queue. This function | |
816 | always returns immediately and its operation is not affected by IO flags. | |
817 | ||
818 | Use LastCount() to verify the number of bytes actually discarded. | |
819 | ||
820 | If you use Error(), it will always return @false. | |
821 | */ | |
822 | wxSocketBase Discard(); | |
823 | ||
824 | /** | |
825 | Returns current IO flags, as set with SetFlags() | |
826 | */ | |
827 | wxSocketFlags GetFlags() const; | |
828 | ||
829 | /** | |
830 | Use this function to interrupt any wait operation currently in progress. | |
831 | ||
832 | Note that this is not intended as a regular way to interrupt a Wait call, | |
833 | but only as an escape mechanism for exceptional situations where it is | |
834 | absolutely necessary to use it, for example to abort an operation due to | |
835 | some exception or abnormal problem. InterruptWait is automatically called | |
836 | when you Close() a socket (and thus also upon | |
837 | socket destruction), so you don't need to use it in these cases. | |
838 | ||
839 | @see Wait(), WaitForLost(), WaitForRead(), WaitForWrite(), | |
840 | wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect() | |
841 | */ | |
842 | void InterruptWait(); | |
23324ae1 FM |
843 | |
844 | /** | |
4cc4bfaf | 845 | This function peeks a buffer of @a nbytes bytes from the socket. |
3d7548cb | 846 | |
23324ae1 | 847 | Peeking a buffer doesn't delete it from the socket input queue. |
3d7548cb | 848 | |
23324ae1 | 849 | Use LastCount() to verify the number of bytes actually peeked. |
3d7548cb | 850 | |
23324ae1 | 851 | Use Error() to determine if the operation succeeded. |
3c4f71cc | 852 | |
7c913512 | 853 | @param buffer |
4cc4bfaf | 854 | Buffer where to put peeked data. |
7c913512 | 855 | @param nbytes |
4cc4bfaf | 856 | Number of bytes. |
3c4f71cc | 857 | |
d29a9a8a | 858 | @return Returns a reference to the current object. |
3c4f71cc | 859 | |
3d7548cb BP |
860 | @remarks |
861 | ||
862 | The exact behaviour of Peek() depends on the combination of flags being used. | |
863 | For a detailed explanation, see SetFlags() | |
864 | ||
865 | @see Error(), LastError(), LastCount(), SetFlags() | |
23324ae1 | 866 | */ |
4cc4bfaf | 867 | wxSocketBase Peek(void* buffer, wxUint32 nbytes); |
23324ae1 FM |
868 | |
869 | /** | |
4cc4bfaf | 870 | This function reads a buffer of @a nbytes bytes from the socket. |
23324ae1 | 871 | Use LastCount() to verify the number of bytes actually read. |
23324ae1 | 872 | Use Error() to determine if the operation succeeded. |
3c4f71cc | 873 | |
7c913512 | 874 | @param buffer |
4cc4bfaf | 875 | Buffer where to put read data. |
7c913512 | 876 | @param nbytes |
4cc4bfaf | 877 | Number of bytes. |
3c4f71cc | 878 | |
d29a9a8a | 879 | @return Returns a reference to the current object. |
3c4f71cc | 880 | |
3d7548cb BP |
881 | @remarks |
882 | ||
883 | The exact behaviour of Read() depends on the combination of flags being used. | |
884 | For a detailed explanation, see SetFlags() | |
885 | ||
4cc4bfaf FM |
886 | @see Error(), LastError(), LastCount(), |
887 | SetFlags() | |
23324ae1 | 888 | */ |
4cc4bfaf | 889 | wxSocketBase Read(void* buffer, wxUint32 nbytes); |
23324ae1 FM |
890 | |
891 | /** | |
7c913512 | 892 | This function reads a buffer sent by WriteMsg() |
23324ae1 FM |
893 | on a socket. If the buffer passed to the function isn't big enough, the |
894 | remaining bytes will be discarded. This function always waits for the | |
895 | buffer to be entirely filled, unless an error occurs. | |
3d7548cb | 896 | |
23324ae1 | 897 | Use LastCount() to verify the number of bytes actually read. |
3d7548cb | 898 | |
23324ae1 | 899 | Use Error() to determine if the operation succeeded. |
3c4f71cc | 900 | |
7c913512 | 901 | @param buffer |
4cc4bfaf | 902 | Buffer where to put read data. |
7c913512 | 903 | @param nbytes |
4cc4bfaf | 904 | Size of the buffer. |
3c4f71cc | 905 | |
d29a9a8a | 906 | @return Returns a reference to the current object. |
3c4f71cc | 907 | |
3d7548cb | 908 | @remarks |
23324ae1 | 909 | |
3d7548cb BP |
910 | ReadMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set |
911 | and it will always ignore the @b wxSOCKET_NOWAIT flag. The exact behaviour | |
912 | of ReadMsg() depends on the @b wxSOCKET_BLOCK flag. | |
913 | For a detailed explanation, see SetFlags(). | |
3c4f71cc | 914 | |
3d7548cb | 915 | @see Error(), LastError(), LastCount(), SetFlags(), WriteMsg() |
23324ae1 | 916 | */ |
3d7548cb | 917 | wxSocketBase ReadMsg(void* buffer, wxUint32 nbytes); |
23324ae1 FM |
918 | |
919 | /** | |
920 | Use SetFlags to customize IO operation for this socket. | |
4cc4bfaf | 921 | The @a flags parameter may be a combination of flags ORed together. |
23324ae1 | 922 | The following flags can be used: |
3c4f71cc | 923 | |
3d7548cb BP |
924 | @beginFlagTable |
925 | @flag{wxSOCKET_NONE} | |
926 | Normal functionality. | |
927 | @flag{wxSOCKET_NOWAIT} | |
928 | Read/write as much data as possible and return immediately. | |
929 | @flag{wxSOCKET_WAITALL} | |
930 | Wait for all required data to be read/written unless an error occurs. | |
931 | @flag{wxSOCKET_BLOCK} | |
932 | Block the GUI (do not yield) while reading/writing data. | |
933 | @flag{wxSOCKET_REUSEADDR} | |
934 | Allows the use of an in-use port (wxServerSocket only). | |
935 | @flag{wxSOCKET_BROADCAST} | |
936 | Switches the socket to broadcast mode. | |
937 | @flag{wxSOCKET_NOBIND} | |
938 | Stops the socket from being bound to a specific adapter (normally | |
939 | used in conjunction with @b wxSOCKET_BROADCAST). | |
940 | @endFlagTable | |
941 | ||
942 | For more information on socket events see @ref wxSocketFlags . | |
23324ae1 FM |
943 | */ |
944 | void SetFlags(wxSocketFlags flags); | |
945 | ||
946 | /** | |
947 | This function allows you to set the local address and port, | |
948 | useful when an application needs to reuse a particular port. When | |
949 | a local port is set for a wxSocketClient, | |
3d7548cb | 950 | @b bind() will be called before @b connect(). |
23324ae1 | 951 | */ |
72ac4e88 | 952 | bool SetLocal(const wxIPV4address& local); |
23324ae1 | 953 | |
23324ae1 FM |
954 | /** |
955 | This function sets the default socket timeout in seconds. This timeout | |
956 | applies to all IO calls, and also to the Wait() family | |
957 | of functions if you don't specify a wait interval. Initially, the default | |
958 | timeout is 10 minutes. | |
959 | */ | |
960 | void SetTimeout(int seconds); | |
961 | ||
23324ae1 FM |
962 | /** |
963 | This function unreads a buffer. That is, the data in the buffer is put back | |
964 | in the incoming queue. This function is not affected by wxSocket flags. | |
3d7548cb BP |
965 | |
966 | If you use LastCount(), it will always return @a nbytes. | |
967 | ||
23324ae1 | 968 | If you use Error(), it will always return @false. |
3c4f71cc | 969 | |
7c913512 | 970 | @param buffer |
4cc4bfaf | 971 | Buffer to be unread. |
7c913512 | 972 | @param nbytes |
4cc4bfaf | 973 | Number of bytes. |
3c4f71cc | 974 | |
d29a9a8a | 975 | @return Returns a reference to the current object. |
3c4f71cc | 976 | |
4cc4bfaf | 977 | @see Error(), LastCount(), LastError() |
23324ae1 | 978 | */ |
4cc4bfaf | 979 | wxSocketBase Unread(const void* buffer, wxUint32 nbytes); |
23324ae1 FM |
980 | |
981 | /** | |
982 | This function waits until any of the following conditions is @true: | |
3c4f71cc | 983 | |
3d7548cb BP |
984 | @li The socket becomes readable. |
985 | @li The socket becomes writable. | |
986 | @li An ongoing connection request has completed (wxSocketClient only) | |
987 | @li An incoming connection request has arrived (wxSocketServer only) | |
988 | @li The connection has been closed. | |
989 | ||
23324ae1 FM |
990 | Note that it is recommended to use the individual Wait functions |
991 | to wait for the required condition, instead of this one. | |
3c4f71cc | 992 | |
7c913512 | 993 | @param seconds |
4cc4bfaf FM |
994 | Number of seconds to wait. |
995 | If -1, it will wait for the default timeout, | |
3d7548cb | 996 | as set with SetTimeout(). |
7c913512 | 997 | @param millisecond |
4cc4bfaf | 998 | Number of milliseconds to wait. |
3c4f71cc | 999 | |
d29a9a8a | 1000 | @return Returns @true when any of the above conditions is satisfied, |
4cc4bfaf | 1001 | @false if the timeout was reached. |
3c4f71cc | 1002 | |
3d7548cb | 1003 | @see InterruptWait(), wxSocketServer::WaitForAccept(), |
4cc4bfaf | 1004 | WaitForLost(), WaitForRead(), |
3d7548cb | 1005 | WaitForWrite(), wxSocketClient::WaitOnConnect() |
23324ae1 FM |
1006 | */ |
1007 | bool Wait(long seconds = -1, long millisecond = 0); | |
1008 | ||
1009 | /** | |
1010 | This function waits until the connection is lost. This may happen if | |
1011 | the peer gracefully closes the connection or if the connection breaks. | |
3c4f71cc | 1012 | |
7c913512 | 1013 | @param seconds |
4cc4bfaf FM |
1014 | Number of seconds to wait. |
1015 | If -1, it will wait for the default timeout, | |
3d7548cb | 1016 | as set with SetTimeout(). |
7c913512 | 1017 | @param millisecond |
4cc4bfaf | 1018 | Number of milliseconds to wait. |
3c4f71cc | 1019 | |
d29a9a8a | 1020 | @return Returns @true if the connection was lost, @false if the timeout |
4cc4bfaf | 1021 | was reached. |
3c4f71cc | 1022 | |
4cc4bfaf | 1023 | @see InterruptWait(), Wait() |
23324ae1 | 1024 | */ |
fc377125 | 1025 | bool WaitForLost(long seconds = -1, long millisecond = 0); |
23324ae1 FM |
1026 | |
1027 | /** | |
3d7548cb BP |
1028 | This function waits until the socket is readable. |
1029 | ||
1030 | This might mean that queued data is available for reading or, for streamed | |
1031 | sockets, that the connection has been closed, so that a read operation will | |
1032 | complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag | |
23324ae1 | 1033 | is set, in which case the operation might still block). |
3c4f71cc | 1034 | |
7c913512 | 1035 | @param seconds |
4cc4bfaf FM |
1036 | Number of seconds to wait. |
1037 | If -1, it will wait for the default timeout, | |
3d7548cb | 1038 | as set with SetTimeout(). |
7c913512 | 1039 | @param millisecond |
4cc4bfaf | 1040 | Number of milliseconds to wait. |
3c4f71cc | 1041 | |
d29a9a8a | 1042 | @return Returns @true if the socket becomes readable, @false on timeout. |
3c4f71cc | 1043 | |
4cc4bfaf | 1044 | @see InterruptWait(), Wait() |
23324ae1 FM |
1045 | */ |
1046 | bool WaitForRead(long seconds = -1, long millisecond = 0); | |
1047 | ||
1048 | /** | |
3d7548cb BP |
1049 | This function waits until the socket becomes writable. |
1050 | ||
1051 | This might mean that the socket is ready to send new data, or for streamed | |
1052 | sockets, that the connection has been closed, so that a write operation is | |
1053 | guaranteed to complete immediately (unless the @b wxSOCKET_WAITALL flag is set, | |
23324ae1 | 1054 | in which case the operation might still block). |
3c4f71cc | 1055 | |
7c913512 | 1056 | @param seconds |
4cc4bfaf FM |
1057 | Number of seconds to wait. |
1058 | If -1, it will wait for the default timeout, | |
3d7548cb | 1059 | as set with SetTimeout(). |
7c913512 | 1060 | @param millisecond |
4cc4bfaf | 1061 | Number of milliseconds to wait. |
3c4f71cc | 1062 | |
d29a9a8a | 1063 | @return Returns @true if the socket becomes writable, @false on timeout. |
3c4f71cc | 1064 | |
4cc4bfaf | 1065 | @see InterruptWait(), Wait() |
23324ae1 FM |
1066 | */ |
1067 | bool WaitForWrite(long seconds = -1, long millisecond = 0); | |
1068 | ||
1069 | /** | |
4cc4bfaf | 1070 | This function writes a buffer of @a nbytes bytes to the socket. |
3d7548cb | 1071 | |
23324ae1 | 1072 | Use LastCount() to verify the number of bytes actually written. |
3d7548cb | 1073 | |
23324ae1 | 1074 | Use Error() to determine if the operation succeeded. |
3c4f71cc | 1075 | |
7c913512 | 1076 | @param buffer |
4cc4bfaf | 1077 | Buffer with the data to be sent. |
7c913512 | 1078 | @param nbytes |
4cc4bfaf | 1079 | Number of bytes. |
3c4f71cc | 1080 | |
d29a9a8a | 1081 | @return Returns a reference to the current object. |
3c4f71cc | 1082 | |
3d7548cb BP |
1083 | @remarks |
1084 | ||
1085 | The exact behaviour of Write() depends on the combination of flags being used. | |
1086 | For a detailed explanation, see SetFlags(). | |
1087 | ||
1088 | @see Error(), LastError(), LastCount(), SetFlags() | |
23324ae1 | 1089 | */ |
4cc4bfaf | 1090 | wxSocketBase Write(const void* buffer, wxUint32 nbytes); |
23324ae1 FM |
1091 | |
1092 | /** | |
4cc4bfaf | 1093 | This function writes a buffer of @a nbytes bytes from the socket, but it |
3d7548cb BP |
1094 | writes a short header before so that ReadMsg() knows how much data should |
1095 | it actually read. So, a buffer sent with WriteMsg() MUST be read with ReadMsg(). | |
1096 | ||
1097 | This function always waits for the entire buffer to be sent, unless an error occurs. | |
1098 | ||
23324ae1 | 1099 | Use LastCount() to verify the number of bytes actually written. |
3d7548cb | 1100 | |
23324ae1 | 1101 | Use Error() to determine if the operation succeeded. |
3c4f71cc | 1102 | |
7c913512 | 1103 | @param buffer |
4cc4bfaf | 1104 | Buffer with the data to be sent. |
7c913512 | 1105 | @param nbytes |
4cc4bfaf | 1106 | Number of bytes to send. |
3c4f71cc | 1107 | |
d29a9a8a | 1108 | @return Returns a reference to the current object. |
3d7548cb BP |
1109 | |
1110 | @remarks | |
1111 | ||
1112 | WriteMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set and | |
1113 | it will always ignore the @b wxSOCKET_NOWAIT flag. The exact behaviour of | |
1114 | WriteMsg() depends on the @b wxSOCKET_BLOCK flag. For a detailed explanation, | |
1115 | see SetFlags(). | |
1116 | ||
1117 | @see Error(), LastError(), LastCount(), SetFlags(), ReadMsg() | |
1118 | ||
23324ae1 | 1119 | */ |
4cc4bfaf | 1120 | wxSocketBase WriteMsg(const void* buffer, wxUint32 nbytes); |
3d7548cb BP |
1121 | |
1122 | //@} | |
1123 | ||
1124 | ||
1125 | /** | |
1126 | @name Handling Socket Events | |
1127 | */ | |
1128 | //@{ | |
1129 | ||
1130 | /** | |
1131 | Returns a pointer of the client data for this socket, as set with | |
1132 | SetClientData() | |
1133 | */ | |
1134 | void* GetClientData() const; | |
1135 | ||
1136 | /** | |
1137 | According to the @a notify value, this function enables | |
1138 | or disables socket events. If @a notify is @true, the events | |
1139 | configured with SetNotify() will | |
1140 | be sent to the application. If @a notify is @false; no events | |
1141 | will be sent. | |
1142 | */ | |
1143 | void Notify(bool notify); | |
1144 | ||
1145 | /** | |
1146 | Sets user-supplied client data for this socket. All socket events will | |
1147 | contain a pointer to this data, which can be retrieved with | |
1148 | the wxSocketEvent::GetClientData() function. | |
1149 | */ | |
1150 | void SetClientData(void* data); | |
1151 | ||
1152 | /** | |
1153 | Sets an event handler to be called when a socket event occurs. The | |
1154 | handler will be called for those events for which notification is | |
1155 | enabled with SetNotify() and | |
1156 | Notify(). | |
1157 | ||
1158 | @param handler | |
1159 | Specifies the event handler you want to use. | |
1160 | @param id | |
1161 | The id of socket event. | |
1162 | ||
1163 | @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler | |
1164 | */ | |
1165 | void SetEventHandler(wxEvtHandler& handler, int id = -1); | |
1166 | ||
1167 | /** | |
1168 | Specifies which socket events are to be sent to the event handler. | |
1169 | The @a flags parameter may be combination of flags ORed together. The | |
1170 | following flags can be used: | |
1171 | ||
1172 | @beginFlagTable | |
1173 | @flag{wxSOCKET_INPUT_FLAG} to receive @b wxSOCKET_INPUT. | |
1174 | @flag{wxSOCKET_OUTPUT_FLAG} to receive @b wxSOCKET_OUTPUT. | |
1175 | @flag{wxSOCKET_CONNECTION_FLAG} to receive @b wxSOCKET_CONNECTION. | |
1176 | @flag{wxSOCKET_LOST_FLAG} to receive @b wxSOCKET_LOST. | |
1177 | @endFlagTable | |
1178 | ||
1179 | For example: | |
1180 | ||
1181 | @code | |
1182 | sock.SetNotify(wxSOCKET_INPUT_FLAG | wxSOCKET_LOST_FLAG); | |
1183 | sock.Notify(true); | |
1184 | @endcode | |
1185 | ||
1186 | In this example, the user will be notified about incoming socket data and | |
1187 | whenever the connection is closed. | |
1188 | ||
1189 | For more information on socket events see @ref wxSocketEventFlags . | |
1190 | */ | |
1191 | void SetNotify(wxSocketEventFlags flags); | |
1192 | ||
1193 | //@} | |
23324ae1 FM |
1194 | }; |
1195 | ||
1196 | ||
e54c96f1 | 1197 | |
23324ae1 FM |
1198 | /** |
1199 | @class wxDatagramSocket | |
7c913512 | 1200 | |
23324ae1 | 1201 | @library{wxnet} |
3d7548cb | 1202 | @category{net} |
23324ae1 FM |
1203 | */ |
1204 | class wxDatagramSocket : public wxSocketBase | |
1205 | { | |
1206 | public: | |
1207 | /** | |
1208 | Constructor. | |
3c4f71cc | 1209 | |
7c913512 | 1210 | @param flags |
3d7548cb | 1211 | Socket flags (See wxSocketBase::SetFlags()) |
23324ae1 FM |
1212 | */ |
1213 | wxDatagramSocket(wxSocketFlags flags = wxSOCKET_NONE); | |
1214 | ||
1215 | /** | |
3d7548cb | 1216 | Destructor. Please see wxSocketBase::Destroy(). |
23324ae1 FM |
1217 | */ |
1218 | ~wxDatagramSocket(); | |
1219 | ||
1220 | /** | |
4cc4bfaf | 1221 | This function reads a buffer of @a nbytes bytes from the socket. |
3d7548cb BP |
1222 | Use wxSocketBase::LastCount() to verify the number of bytes actually read. |
1223 | Use wxSocketBase::Error() to determine if the operation succeeded. | |
3c4f71cc | 1224 | |
7c913512 | 1225 | @param address |
4cc4bfaf | 1226 | Any address - will be overwritten with the address of the peer that sent |
3d7548cb | 1227 | that data. |
7c913512 | 1228 | @param buffer |
4cc4bfaf | 1229 | Buffer where to put read data. |
7c913512 | 1230 | @param nbytes |
4cc4bfaf | 1231 | Number of bytes. |
3c4f71cc | 1232 | |
d29a9a8a | 1233 | @return Returns a reference to the current object, and the address of |
4cc4bfaf | 1234 | the peer that sent the data on address param. |
3c4f71cc | 1235 | |
3d7548cb | 1236 | @see wxSocketBase::LastError(), wxSocketBase::SetFlags() |
23324ae1 FM |
1237 | */ |
1238 | wxDatagramSocket ReceiveFrom(wxSockAddress& address, | |
3d7548cb | 1239 | void* buffer, wxUint32 nbytes); |
23324ae1 FM |
1240 | |
1241 | /** | |
4cc4bfaf | 1242 | This function writes a buffer of @a nbytes bytes to the socket. |
3d7548cb BP |
1243 | Use wxSocketBase::LastCount() to verify the number of bytes actually wrote. |
1244 | Use wxSocketBase::Error() to determine if the operation succeeded. | |
3c4f71cc | 1245 | |
7c913512 | 1246 | @param address |
4cc4bfaf | 1247 | The address of the destination peer for this data. |
7c913512 | 1248 | @param buffer |
4cc4bfaf | 1249 | Buffer where read data is. |
7c913512 | 1250 | @param nbytes |
4cc4bfaf | 1251 | Number of bytes. |
3c4f71cc | 1252 | |
d29a9a8a | 1253 | @return Returns a reference to the current object. |
3d7548cb BP |
1254 | |
1255 | @see wxSocketBase::LastError(), wxSocketBase::SetFlags() | |
23324ae1 FM |
1256 | */ |
1257 | wxDatagramSocket SendTo(const wxSockAddress& address, | |
3d7548cb | 1258 | const void* buffer, wxUint32 nbytes); |
23324ae1 | 1259 | }; |
e54c96f1 | 1260 |