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