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