1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxIP*address, wxSocket* classes
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
12 A class for working with IPv4 network addresses.
17 class wxIPV4address
: public wxIPaddress
21 Set address to any of the addresses of the current machine.
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
28 @return @true on success, @false if something went wrong.
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>).
36 @return @true on success, @false if something goes wrong (invalid
37 hostname or invalid IP address).
39 bool Hostname(const wxString
& hostname
);
42 Returns the hostname which matches the IP address.
44 virtual wxString
Hostname() const;
47 Returns a wxString containing the IP address in dot quad (127.0.0.1) format.
49 virtual wxString
IPAddress() const;
52 Set address to localhost (127.0.0.1).
54 Whenever possible, use AnyAddress() instead of this one, as that one will
55 correctly handle multi-homed hosts and avoid other small problems.
57 @return @true on success, @false if something went wrong.
62 Set the port to that corresponding to the specified @a service.
64 @return @true on success, @false if something goes wrong (invalid @a service).
66 bool Service(const wxString
& service
);
69 Set the port to that corresponding to the specified @a service.
71 @return @true on success, @false if something goes wrong (invalid @a service).
73 bool Service(unsigned short service
) = 0;
76 Returns the current service.
78 unsigned short Service() const = 0;
91 class wxSocketServer
: public wxSocketBase
95 Constructs a new server and tries to bind to the specified @e address.
97 Before trying to accept new connections, remember to test whether it succeeded
98 with wxSocketBase:IsOk().
101 Specifies the local address for the server (e.g. port number).
103 Socket flags (See wxSocketBase::SetFlags()).
105 wxSocketServer(const wxSockAddress
& address
,
106 wxSocketFlags flags
= wxSOCKET_NONE
);
109 Destructor (it doesn't close the accepted connections).
111 virtual ~wxSocketServer();
114 Accepts an incoming connection request, and creates a new wxSocketBase
115 object which represents the server-side of the connection.
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
121 @warning: This method will block the GUI.
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
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.
134 @see WaitForAccept(), wxSocketBase::SetNotify(),
135 wxSocketBase::Notify(), AcceptWith()
137 wxSocketBase
* Accept(bool wait
= true);
140 Accept an incoming connection using the specified socket object.
143 Socket to be initialized
145 See Accept() for more info.
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
151 @see WaitForAccept(), wxSocketBase::SetNotify(),
152 wxSocketBase::Notify(), Accept()
154 bool AcceptWith(wxSocketBase
& socket
, bool wait
= true);
157 This function waits for an incoming connection.
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.
163 Number of seconds to wait. If -1, it will wait for the default
164 timeout, as set with wxSocketBase::SetTimeout().
166 Number of milliseconds to wait.
168 @return @true if an incoming connection arrived, @false if the timeout
171 @see Accept(), AcceptWith(), wxSocketBase::InterruptWait()
173 bool WaitForAccept(long seconds
= -1, long millisecond
= 0);
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.
188 class wxIPaddress
: public wxSockAddress
192 Internally, this is the same as setting the IP address to @b INADDR_ANY.
194 On IPV4 implementations, 0.0.0.0
196 On IPV6 implementations, ::
198 @return @true on success, @false if something went wrong.
200 virtual bool AnyAddress() = 0;
203 Internally, this is the same as setting the IP address to @b INADDR_BROADCAST.
205 On IPV4 implementations, 255.255.255.255
207 @return @true on success, @false if something went wrong.
209 virtual bool BroadcastAddress() = 0;
212 Set the address to hostname, which can be a host name or an IP-style address
213 in a format dependent on implementation.
215 @return @true on success, @false if something goes wrong (invalid
216 hostname or invalid IP address).
218 virtual bool Hostname(const wxString
& hostname
) = 0;
221 Returns the hostname which matches the IP address.
223 virtual wxString
Hostname() const = 0;
226 Returns a wxString containing the IP address.
228 virtual wxString
IPAddress() const = 0;
231 Determines if current address is set to localhost.
233 @return @true if address is localhost, @false if internet address.
235 virtual bool IsLocalHost() const = 0;
238 Set address to localhost.
240 On IPV4 implementations, 127.0.0.1
242 On IPV6 implementations, ::1
244 @return @true on success, @false if something went wrong.
246 virtual bool LocalHost() = 0;
249 Set the port to that corresponding to the specified service.
251 @return @true on success, @false if something goes wrong (invalid @a service).
253 virtual bool Service(const wxString
& service
) = 0;
256 Set the port to that corresponding to the specified service.
258 @return @true on success, @false if something goes wrong (invalid @a service).
260 virtual bool Service(unsigned short service
) = 0;
263 Returns the current service.
265 virtual unsigned short Service() const = 0;
271 @class wxSocketClient
278 class wxSocketClient
: public wxSocketBase
285 Socket flags (See wxSocketBase::SetFlags())
287 wxSocketClient(wxSocketFlags flags
= wxSOCKET_NONE
);
290 Destructor. Please see wxSocketBase::Destroy().
292 virtual ~wxSocketClient();
295 Connects to a server using the specified address.
297 If @a wait is @true, Connect() will wait until the connection
300 @warning: This method will block the GUI.
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).
310 Address of the server.
312 If @true, waits for the connection to complete.
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.
322 @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
324 virtual bool Connect(const wxSockAddress
& address
, bool wait
= true);
327 Connects to a server using the specified address.
329 If @a wait is @true, Connect() will wait until the connection
330 completes. @b Warning: This will block the GUI.
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).
340 Address of the server.
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.
346 If @true, waits for the connection to complete.
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.
356 @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
358 bool Connect(const wxSockAddress
& address
, const wxSockAddress
& local
,
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.
367 Number of seconds to wait.
368 If -1, it will wait for the default timeout, as set with wxSocketBase::SetTimeout().
370 Number of milliseconds to wait.
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:
381 // Issue the connection request
382 client->Connect(addr, false);
384 // Wait until the request completes or until we decide to give up
385 bool waitmore = true;
386 while ( !client->WaitOnConnect(seconds, millis) && waitmore )
388 // possibly give some feedback to the user,
389 // and update waitmore as needed.
391 bool success = client->IsConnected();
394 bool WaitOnConnect(long seconds
= -1, long milliseconds
= 0);
402 You are unlikely to need to use this class: only wxSocketBase uses it.
407 @see wxSocketBase, wxIPaddress, wxIPV4address
409 class wxSockAddress
: public wxObject
420 virtual ~wxSockAddress();
423 Delete all informations about the address.
425 virtual void Clear();
428 Returns the length of the socket address.
438 This event class contains information about socket events.
440 @beginEventTable{wxSocketEvent}
441 @event{EVT_SOCKET(id, func)}
442 Process a socket event, supplying the member function.
448 @see wxSocketBase, wxSocketClient, wxSocketServer
450 class wxSocketEvent
: public wxEvent
456 wxSocketEvent(int id
= 0);
459 Gets the client data of the socket which generated this event, as
460 set with wxSocketBase::SetClientData().
462 void* GetClientData() const;
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.
468 wxSocketBase
* GetSocket() const;
471 Returns the socket event type.
473 wxSocketNotify
GetSocketEvent() const;
478 wxSocket error return values.
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.
496 @anchor wxSocketEventFlags
498 wxSocket Event Flags.
500 A brief note on how to use these events:
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
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.
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).
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.
524 enum wxSocketEventFlags
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.
535 @anchor wxSocketFlags
539 A brief overview on how to use these flags follows.
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.
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
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.
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.
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.
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().
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.
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().
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
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.
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)
618 wxSocketBase is the base class for all socket-related objects, and it
619 defines all basic IO functionality.
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.
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.
638 @see wxSocketEvent, wxSocketClient, wxSocketServer, @sample{sockets},
639 @ref wxSocketFlags, ::wxSocketEventFlags, ::wxSocketError
641 class wxSocketBase
: public wxObject
646 @name Construction and Destruction
653 Don't use it directly; instead, use wxSocketClient to construct a socket client,
654 or wxSocketServer to construct a socket server.
661 Do not destroy a socket using the delete operator directly;
662 use Destroy() instead. Also, do not create socket objects in the stack.
667 Destroys the socket safely.
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.
675 Destroy() calls Close() automatically.
677 @return Always @true.
690 Returns @true if an error occurred in the last IO operation.
692 Use this function to check for an error condition after one of the
693 following calls: Discard(), Peek(), Read(), ReadMsg(), Unread(), Write(), WriteMsg().
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, ...).
702 @return @true if no error happened, @false otherwise.
704 bool GetLocal(wxSockAddress
& addr
) const;
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, ...).
711 @return @true if no error happened, @false otherwise.
713 bool GetPeer(wxSockAddress
& addr
) const;
716 Return the socket timeout in seconds.
718 The timeout can be set using SetTimeout() and is 10 minutes by default.
720 long GetTimeout() const;
723 Returns @true if the socket is connected.
725 bool IsConnected() const;
728 This function waits until the socket is readable.
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).
738 Returns @true if the socket is not connected.
740 bool IsDisconnected() const;
743 Returns @true if the socket is initialized and ready and @false in other
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.
755 Returns the number of bytes read or written by the last IO call.
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().
761 wxUint32
LastCount() const;
764 Returns the last wxSocket error. See @ref wxSocketError .
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.
773 wxSocketError
LastError() const;
776 This function restores the previous state of the socket, as saved
779 Calls to SaveState() and RestoreState() can be nested.
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.
801 See also: wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
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.
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.
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().
823 Shuts down the writing end of the socket.
825 This function simply calls the standard shutdown() function on the
826 underlying socket, indicating that nothing will be written to this
829 void ShutdownOutput();
832 This function simply deletes all bytes in the incoming queue. This function
833 always returns immediately and its operation is not affected by IO flags.
835 Use LastCount() to verify the number of bytes actually discarded.
837 If you use Error(), it will always return @false.
839 wxSocketBase
Discard();
842 Returns current IO flags, as set with SetFlags()
844 wxSocketFlags
GetFlags() const;
847 Use this function to interrupt any wait operation currently in progress.
849 Note that this is not intended as a regular way to interrupt a Wait call,
850 but only as an escape mechanism for exceptional situations where it is
851 absolutely necessary to use it, for example to abort an operation due to
852 some exception or abnormal problem. InterruptWait is automatically called
853 when you Close() a socket (and thus also upon
854 socket destruction), so you don't need to use it in these cases.
856 @see Wait(), WaitForLost(), WaitForRead(), WaitForWrite(),
857 wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
859 void InterruptWait();
862 This function peeks a buffer of @a nbytes bytes from the socket.
864 Peeking a buffer doesn't delete it from the socket input queue.
866 Use LastCount() to verify the number of bytes actually peeked.
868 Use Error() to determine if the operation succeeded.
871 Buffer where to put peeked data.
875 @return Returns a reference to the current object.
878 The exact behaviour of Peek() depends on the combination of flags being used.
879 For a detailed explanation, see SetFlags()
881 @see Error(), LastError(), LastCount(), SetFlags()
883 wxSocketBase
Peek(void* buffer
, wxUint32 nbytes
);
886 This function reads a buffer of @a nbytes bytes from the socket.
887 Use LastCount() to verify the number of bytes actually read.
888 Use Error() to determine if the operation succeeded.
891 Buffer where to put read data.
895 @return Returns a reference to the current object.
898 The exact behaviour of Read() depends on the combination of flags being used.
899 For a detailed explanation, see SetFlags()
901 @see Error(), LastError(), LastCount(),
904 wxSocketBase
Read(void* buffer
, wxUint32 nbytes
);
907 This function reads a buffer sent by WriteMsg()
908 on a socket. If the buffer passed to the function isn't big enough, the
909 remaining bytes will be discarded. This function always waits for the
910 buffer to be entirely filled, unless an error occurs.
912 Use LastCount() to verify the number of bytes actually read.
914 Use Error() to determine if the operation succeeded.
917 Buffer where to put read data.
921 @return Returns a reference to the current object.
924 ReadMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set
925 and it will always ignore the @b wxSOCKET_NOWAIT flag.
926 The exact behaviour of ReadMsg() depends on the @b wxSOCKET_BLOCK flag.
927 For a detailed explanation, see SetFlags().
929 @see Error(), LastError(), LastCount(), SetFlags(), WriteMsg()
931 wxSocketBase
ReadMsg(void* buffer
, wxUint32 nbytes
);
934 Use SetFlags to customize IO operation for this socket.
935 The @a flags parameter may be a combination of flags ORed together.
936 The following flags can be used:
940 Normal functionality.
941 @flag{wxSOCKET_NOWAIT}
942 Read/write as much data as possible and return immediately.
943 @flag{wxSOCKET_WAITALL}
944 Wait for all required data to be read/written unless an error occurs.
945 @flag{wxSOCKET_BLOCK}
946 Block the GUI (do not yield) while reading/writing data.
947 @flag{wxSOCKET_REUSEADDR}
948 Allows the use of an in-use port (wxServerSocket only).
949 @flag{wxSOCKET_BROADCAST}
950 Switches the socket to broadcast mode.
951 @flag{wxSOCKET_NOBIND}
952 Stops the socket from being bound to a specific adapter (normally
953 used in conjunction with @b wxSOCKET_BROADCAST).
956 For more information on socket events see @ref wxSocketFlags .
958 void SetFlags(wxSocketFlags flags
);
961 This function allows you to set the local address and port,
962 useful when an application needs to reuse a particular port. When
963 a local port is set for a wxSocketClient,
964 @b bind() will be called before @b connect().
966 bool SetLocal(const wxIPV4address
& local
);
969 This function sets the default socket timeout in seconds. This timeout
970 applies to all IO calls, and also to the Wait() family
971 of functions if you don't specify a wait interval. Initially, the default
972 timeout is 10 minutes.
974 void SetTimeout(int seconds
);
977 This function unreads a buffer. That is, the data in the buffer is put back
978 in the incoming queue. This function is not affected by wxSocket flags.
980 If you use LastCount(), it will always return @a nbytes.
982 If you use Error(), it will always return @false.
989 @return Returns a reference to the current object.
991 @see Error(), LastCount(), LastError()
993 wxSocketBase
Unread(const void* buffer
, wxUint32 nbytes
);
996 This function waits until any of the following conditions is @true:
998 @li The socket becomes readable.
999 @li The socket becomes writable.
1000 @li An ongoing connection request has completed (wxSocketClient only)
1001 @li An incoming connection request has arrived (wxSocketServer only)
1002 @li The connection has been closed.
1004 Note that it is recommended to use the individual Wait functions
1005 to wait for the required condition, instead of this one.
1008 Number of seconds to wait.
1009 If -1, it will wait for the default timeout,
1010 as set with SetTimeout().
1012 Number of milliseconds to wait.
1014 @return Returns @true when any of the above conditions is satisfied,
1015 @false if the timeout was reached.
1017 @see InterruptWait(), wxSocketServer::WaitForAccept(),
1018 WaitForLost(), WaitForRead(),
1019 WaitForWrite(), wxSocketClient::WaitOnConnect()
1021 bool Wait(long seconds
= -1, long millisecond
= 0);
1024 This function waits until the connection is lost. This may happen if
1025 the peer gracefully closes the connection or if the connection breaks.
1028 Number of seconds to wait.
1029 If -1, it will wait for the default timeout,
1030 as set with SetTimeout().
1032 Number of milliseconds to wait.
1034 @return Returns @true if the connection was lost, @false if the timeout
1037 @see InterruptWait(), Wait()
1039 bool WaitForLost(long seconds
= -1, long millisecond
= 0);
1042 This function waits until the socket is readable.
1044 This might mean that queued data is available for reading or, for streamed
1045 sockets, that the connection has been closed, so that a read operation will
1046 complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag
1047 is set, in which case the operation might still block).
1050 Number of seconds to wait.
1051 If -1, it will wait for the default timeout,
1052 as set with SetTimeout().
1054 Number of milliseconds to wait.
1056 @return Returns @true if the socket becomes readable, @false on timeout.
1058 @see InterruptWait(), Wait()
1060 bool WaitForRead(long seconds
= -1, long millisecond
= 0);
1063 This function waits until the socket becomes writable.
1065 This might mean that the socket is ready to send new data, or for streamed
1066 sockets, that the connection has been closed, so that a write operation is
1067 guaranteed to complete immediately (unless the @b wxSOCKET_WAITALL flag is set,
1068 in which case the operation might still block).
1071 Number of seconds to wait.
1072 If -1, it will wait for the default timeout,
1073 as set with SetTimeout().
1075 Number of milliseconds to wait.
1077 @return Returns @true if the socket becomes writable, @false on timeout.
1079 @see InterruptWait(), Wait()
1081 bool WaitForWrite(long seconds
= -1, long millisecond
= 0);
1084 This function writes a buffer of @a nbytes bytes to the socket.
1086 Use LastCount() to verify the number of bytes actually written.
1088 Use Error() to determine if the operation succeeded.
1091 Buffer with the data to be sent.
1095 @return Returns a reference to the current object.
1099 The exact behaviour of Write() depends on the combination of flags being used.
1100 For a detailed explanation, see SetFlags().
1102 @see Error(), LastError(), LastCount(), SetFlags()
1104 wxSocketBase
Write(const void* buffer
, wxUint32 nbytes
);
1107 This function writes a buffer of @a nbytes bytes from the socket, but it
1108 writes a short header before so that ReadMsg() knows how much data should
1109 it actually read. So, a buffer sent with WriteMsg() MUST be read with ReadMsg().
1111 This function always waits for the entire buffer to be sent, unless an error occurs.
1113 Use LastCount() to verify the number of bytes actually written.
1115 Use Error() to determine if the operation succeeded.
1118 Buffer with the data to be sent.
1120 Number of bytes to send.
1122 @return Returns a reference to the current object.
1126 WriteMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set and
1127 it will always ignore the @b wxSOCKET_NOWAIT flag. The exact behaviour of
1128 WriteMsg() depends on the @b wxSOCKET_BLOCK flag. For a detailed explanation,
1131 @see Error(), LastError(), LastCount(), SetFlags(), ReadMsg()
1134 wxSocketBase
WriteMsg(const void* buffer
, wxUint32 nbytes
);
1140 @name Handling Socket Events
1145 Returns a pointer of the client data for this socket, as set with
1148 void* GetClientData() const;
1151 According to the @a notify value, this function enables
1152 or disables socket events. If @a notify is @true, the events
1153 configured with SetNotify() will
1154 be sent to the application. If @a notify is @false; no events
1157 void Notify(bool notify
);
1160 Sets user-supplied client data for this socket. All socket events will
1161 contain a pointer to this data, which can be retrieved with
1162 the wxSocketEvent::GetClientData() function.
1164 void SetClientData(void* data
);
1167 Sets an event handler to be called when a socket event occurs. The
1168 handler will be called for those events for which notification is
1169 enabled with SetNotify() and
1173 Specifies the event handler you want to use.
1175 The id of socket event.
1177 @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler
1179 void SetEventHandler(wxEvtHandler
& handler
, int id
= -1);
1182 Specifies which socket events are to be sent to the event handler.
1183 The @a flags parameter may be combination of flags ORed together. The
1184 following flags can be used:
1187 @flag{wxSOCKET_INPUT_FLAG} to receive @b wxSOCKET_INPUT.
1188 @flag{wxSOCKET_OUTPUT_FLAG} to receive @b wxSOCKET_OUTPUT.
1189 @flag{wxSOCKET_CONNECTION_FLAG} to receive @b wxSOCKET_CONNECTION.
1190 @flag{wxSOCKET_LOST_FLAG} to receive @b wxSOCKET_LOST.
1196 sock.SetNotify(wxSOCKET_INPUT_FLAG | wxSOCKET_LOST_FLAG);
1200 In this example, the user will be notified about incoming socket data and
1201 whenever the connection is closed.
1203 For more information on socket events see @ref wxSocketEventFlags .
1205 void SetNotify(wxSocketEventFlags flags
);
1213 @class wxDatagramSocket
1220 class wxDatagramSocket
: public wxSocketBase
1229 Socket flags (See wxSocketBase::SetFlags()).
1231 wxDatagramSocket(const wxSockAddress
& addr
,
1232 wxSocketFlags flags
= wxSOCKET_NONE
);
1235 Destructor. Please see wxSocketBase::Destroy().
1237 virtual ~wxDatagramSocket();
1240 This function writes a buffer of @a nbytes bytes to the socket.
1241 Use wxSocketBase::LastCount() to verify the number of bytes actually wrote.
1242 Use wxSocketBase::Error() to determine if the operation succeeded.
1245 The address of the destination peer for this data.
1247 Buffer where read data is.
1251 @return Returns a reference to the current object.
1253 @see wxSocketBase::LastError(), wxSocketBase::SetFlags()
1255 wxDatagramSocket
& SendTo(const wxSockAddress
& address
,
1256 const void* buffer
, wxUint32 nbytes
);