]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/socket.h
Make wxDataObjectComposite::GetObject() public.
[wxWidgets.git] / interface / wx / socket.h
CommitLineData
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*/
20class wxIPaddress : public wxSockAddress
21{
22public:
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*/
109class wxIPV4address : public wxIPaddress
110{
111public:
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*/
183class wxSocketServer : public wxSocketBase
184{
185public:
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*/
277class wxSocketClient : public wxSocketBase
278{
279public:
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*/
408class wxSockAddress : public wxObject
409{
410public:
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*/
471class wxSocketEvent : public wxEvent
472{
473public:
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*/
501enum 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*/
545enum 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*/
622enum
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*/
659class wxSocketBase : public wxObject
660{
661public:
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*/
1302class wxDatagramSocket : public wxSocketBase
1303{
1304public:
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