]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/socket.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxIP*address, wxSocket* classes
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
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.
20 class wxIPaddress
: public wxSockAddress
24 Internally, this is the same as setting the IP address to @b INADDR_ANY.
26 On IPV4 implementations, 0.0.0.0
28 On IPV6 implementations, ::
30 @return @true on success, @false if something went wrong.
35 Internally, this is the same as setting the IP address to @b INADDR_BROADCAST.
37 On IPV4 implementations, 255.255.255.255
39 @return @true on success, @false if something went wrong.
41 virtual bool BroadcastAddress() = 0;
44 Set the address to hostname, which can be a host name or an IP-style address
45 in a format dependent on implementation.
47 @return @true on success, @false if something goes wrong (invalid
48 hostname or invalid IP address).
50 bool Hostname(const wxString
& hostname
);
53 Returns the hostname which matches the IP address.
55 wxString
Hostname() const;
58 Returns a wxString containing the IP address.
60 virtual wxString
IPAddress() const = 0;
63 Determines if current address is set to localhost.
65 @return @true if address is localhost, @false if internet address.
67 virtual bool IsLocalHost() const = 0;
70 Set address to localhost.
72 On IPV4 implementations, 127.0.0.1
74 On IPV6 implementations, ::1
76 @return @true on success, @false if something went wrong.
81 Set the port to that corresponding to the specified service.
83 @return @true on success, @false if something goes wrong (invalid @a service).
85 bool Service(const wxString
& service
);
88 Set the port to that corresponding to the specified service.
90 @return @true on success, @false if something goes wrong (invalid @a service).
92 bool Service(unsigned short service
);
95 Returns the current service.
97 unsigned short Service() const;
104 A class for working with IPv4 network addresses.
109 class wxIPV4address
: public wxIPaddress
113 Set address to any of the addresses of the current machine.
115 Whenever possible, use this function instead of LocalHost(),
116 as this correctly handles multi-homed hosts and avoids other small
117 problems. Internally, this is the same as setting the IP address
120 @return @true on success, @false if something went wrong.
125 Set the address to hostname, which can be a host name or an IP-style address
126 in dot notation(<tt>a.b.c.d</tt>).
128 @return @true on success, @false if something goes wrong (invalid
129 hostname or invalid IP address).
131 bool Hostname(const wxString
& hostname
);
134 Returns the hostname which matches the IP address.
136 virtual wxString
Hostname() const;
139 Returns a wxString containing the IP address in dot quad (127.0.0.1) format.
141 virtual wxString
IPAddress() const;
144 Set address to localhost (127.0.0.1).
146 Whenever possible, use AnyAddress() instead of this one, as that one will
147 correctly handle multi-homed hosts and avoid other small problems.
149 @return @true on success, @false if something went wrong.
154 Set the port to that corresponding to the specified @a service.
156 @return @true on success, @false if something goes wrong (invalid @a service).
158 bool Service(const wxString
& service
);
161 Set the port to that corresponding to the specified @a service.
163 @return @true on success, @false if something goes wrong (invalid @a service).
165 bool Service(unsigned short service
);
168 Returns the current service.
170 unsigned short Service() const;
176 @class wxSocketServer
183 class wxSocketServer
: public wxSocketBase
187 Constructs a new server and tries to bind to the specified @e address.
189 Before trying to accept new connections, remember to test whether it succeeded
190 with wxSocketBase:IsOk().
193 Specifies the local address for the server (e.g. port number).
195 Socket flags (See wxSocketBase::SetFlags()).
197 wxSocketServer(const wxSockAddress
& address
,
198 wxSocketFlags flags
= wxSOCKET_NONE
);
201 Destructor (it doesn't close the accepted connections).
203 virtual ~wxSocketServer();
206 Accepts an incoming connection request, and creates a new wxSocketBase
207 object which represents the server-side of the connection.
209 If @a wait is @true and there are no pending connections to be
210 accepted, it will wait for the next incoming connection to
213 @warning This method will block the GUI.
215 If @a wait is @false, it will try to accept a pending connection
216 if there is one, but it will always return immediately without blocking
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
222 @return Returns an opened socket connection, or @NULL if an error
223 occurred or if the wait parameter was @false and there
224 were no pending connections.
226 @see WaitForAccept(), wxSocketBase::SetNotify(),
227 wxSocketBase::Notify(), AcceptWith()
229 wxSocketBase
* Accept(bool wait
= true);
232 Accept an incoming connection using the specified socket object.
235 Socket to be initialized
237 See Accept() for more info.
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
243 @see WaitForAccept(), wxSocketBase::SetNotify(),
244 wxSocketBase::Notify(), Accept()
246 bool AcceptWith(wxSocketBase
& socket
, bool wait
= true);
249 Wait for an incoming connection.
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.
255 Number of seconds to wait. If -1, it will wait for the default
256 timeout, as set with wxSocketBase::SetTimeout().
258 Number of milliseconds to wait.
260 @return @true if an incoming connection arrived, @false if the timeout
263 @see Accept(), AcceptWith(), wxSocketBase::InterruptWait()
265 bool WaitForAccept(long seconds
= -1, long millisecond
= 0);
270 @class wxSocketClient
277 class wxSocketClient
: public wxSocketBase
284 Socket flags (See wxSocketBase::SetFlags())
286 wxSocketClient(wxSocketFlags flags
= wxSOCKET_NONE
);
289 Destructor. Please see wxSocketBase::Destroy().
291 virtual ~wxSocketClient();
294 Connects to a server using the specified address.
296 If @a wait is @true, Connect() will wait until the connection
299 @warning This method will block the GUI.
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).
309 Address of the server.
311 If @true, waits for the connection to complete.
313 @return @true if the connection is established and no error occurs.
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.
321 @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
323 virtual bool Connect(const wxSockAddress
& address
, bool wait
= true);
326 Connects to a server using the specified address.
328 If @a wait is @true, Connect() will wait until the connection
329 completes. @b Warning: This will block the GUI.
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).
339 Address of the server.
341 Bind to the specified local address and port before connecting.
342 The local address and port can also be set using SetLocal(),
343 and then using the 2-parameter Connect() method.
345 If @true, waits for the connection to complete.
347 @return @true if the connection is established and no error occurs.
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.
355 @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
357 bool Connect(const wxSockAddress
& address
, const wxSockAddress
& local
,
361 Wait until a connection request completes, or until the specified timeout
362 elapses. Use this function after issuing a call to Connect() with
363 @e wait set to @false.
366 Number of seconds to wait.
367 If -1, it will wait for the default timeout, as set with wxSocketBase::SetTimeout().
369 Number of milliseconds to wait.
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:
380 // Issue the connection request
381 client->Connect(addr, false);
383 // Wait until the request completes or until we decide to give up
384 bool waitmore = true;
385 while ( !client->WaitOnConnect(seconds, millis) && waitmore )
387 // possibly give some feedback to the user,
388 // and update waitmore as needed.
390 bool success = client->IsConnected();
393 bool WaitOnConnect(long seconds
= -1, long milliseconds
= 0);
401 You are unlikely to need to use this class: only wxSocketBase uses it.
406 @see wxSocketBase, wxIPaddress, wxIPV4address
408 class wxSockAddress
: public wxObject
419 virtual ~wxSockAddress();
422 Delete all informations about the address.
424 virtual void Clear();
427 Returns the length of the socket address.
437 This event class contains information about socket events.
438 This kind of events are sent to the event handler specified with
439 wxSocketBase::SetEventHandler.
441 @beginEventTable{wxSocketEvent}
442 @event{EVT_SOCKET(id, func)}
443 Process a socket event, supplying the member function.
449 @see wxSocketBase, wxSocketClient, wxSocketServer
451 class wxSocketEvent
: public wxEvent
457 wxSocketEvent(int id
= 0);
460 Gets the client data of the socket which generated this event, as
461 set with wxSocketBase::SetClientData().
463 void* GetClientData() const;
466 Returns the socket object to which this event refers to.
467 This makes it possible to use the same event handler for different sockets.
469 wxSocketBase
* GetSocket() const;
472 Returns the socket event type.
474 wxSocketNotify
GetSocketEvent() const;
479 wxSocket error return values.
483 wxSOCKET_NOERROR
, ///< No error happened.
484 wxSOCKET_INVOP
, ///< Invalid operation.
485 wxSOCKET_IOERR
, ///< Input/Output error.
486 wxSOCKET_INVADDR
, ///< Invalid address passed to wxSocket.
487 wxSOCKET_INVSOCK
, ///< Invalid socket (uninitialized).
488 wxSOCKET_NOHOST
, ///< No corresponding host.
489 wxSOCKET_INVPORT
, ///< Invalid port.
490 wxSOCKET_WOULDBLOCK
, ///< The socket is non-blocking and the operation would block.
491 wxSOCKET_TIMEDOUT
, ///< The timeout for this operation expired.
492 wxSOCKET_MEMERR
///< Memory exhausted.
497 @anchor wxSocketEventFlags
499 wxSocket Event Flags.
501 A brief note on how to use these events:
503 The @b wxSOCKET_INPUT event will be issued whenever there is data available
504 for reading. This will be the case if the input queue was empty and new data
505 arrives, or if the application has read some data yet there is still more data
506 available. This means that the application does not need to read all available
507 data in response to a @b wxSOCKET_INPUT event, as more events will be produced
510 The @b wxSOCKET_OUTPUT event is issued when a socket is first connected with
511 Connect() or accepted with Accept(). After that, new events will be generated
512 only after an output operation fails with @b wxSOCKET_WOULDBLOCK and buffer space
513 becomes available again. This means that the application should assume that it can
514 write data to the socket until an @b wxSOCKET_WOULDBLOCK error occurs; after this,
515 whenever the socket becomes writable again the application will be notified with
516 another @b wxSOCKET_OUTPUT event.
518 The @b wxSOCKET_CONNECTION event is issued when a delayed connection request completes
519 successfully (client) or when a new connection arrives at the incoming queue (server).
521 The @b wxSOCKET_LOST event is issued when a close indication is received for the socket.
522 This means that the connection broke down or that it was closed by the peer. Also, this
523 event will be issued if a connection request fails.
525 enum wxSocketEventFlags
527 wxSOCKET_INPUT
, ///< There is data available for reading.
528 wxSOCKET_OUTPUT
, ///< The socket is ready to be written to.
529 wxSOCKET_CONNECTION
, ///< Incoming connection request (server), or
530 ///< successful connection establishment (client).
531 wxSOCKET_LOST
///< The connection has been closed.
536 @anchor wxSocketFlags
540 A brief overview on how to use these flags follows.
542 If no flag is specified (this is the same as @b wxSOCKET_NONE),
543 IO calls will return after some data has been read or written, even
544 when the transfer might not be complete. This is the same as issuing
545 exactly one blocking low-level call to @b recv() or @b send(). Note
546 that @e blocking here refers to when the function returns, not
547 to whether the GUI blocks during this time.
549 If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately.
550 Read operations will retrieve only available data. Write operations will
551 write as much data as possible, depending on how much space is available
552 in the output buffer. This is the same as issuing exactly one nonblocking
553 low-level call to @b recv() or @b send(). Note that @e nonblocking here
554 refers to when the function returns, not to whether the GUI blocks during
557 If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL
558 the data has been read or written (or until an error occurs), blocking if
559 necessary, and issuing several low level calls if necessary. This is the
560 same as having a loop which makes as many blocking low-level calls to
561 @b recv() or @b send() as needed so as to transfer all the data. Note
562 that @e blocking here refers to when the function returns, not
563 to whether the GUI blocks during this time.
565 The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during
566 IO operations. If this flag is specified, the socket will not yield
567 during IO calls, so the GUI will remain blocked until the operation
568 completes. If it is not used, then the application must take extra
569 care to avoid unwanted reentrance.
571 The @b wxSOCKET_REUSEADDR flag controls the use of the @b SO_REUSEADDR standard
572 @b setsockopt() flag. This flag allows the socket to bind to a port that is
573 already in use. This is mostly used on UNIX-based systems to allow rapid starting
574 and stopping of a server, otherwise you may have to wait several minutes for the
575 port to become available.
577 @b wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a
578 particular local port for an outgoing connection.
579 This option can have surprising platform dependent behavior, so check the
580 documentation for your platform's implementation of setsockopt().
582 Note that on BSD-based systems(e.g. Mac OS X), use of
583 @b wxSOCKET_REUSEADDR implies @b SO_REUSEPORT in addition to
584 @b SO_REUSEADDR to be consistent with Windows.
586 The @b wxSOCKET_BROADCAST flag controls the use of the @b SO_BROADCAST standard
587 @b setsockopt() flag. This flag allows the socket to use the broadcast address,
588 and is generally used in conjunction with @b wxSOCKET_NOBIND and
589 wxIPaddress::BroadcastAddress().
592 - @b wxSOCKET_NONE will try to read at least SOME data, no matter how much.
593 - @b wxSOCKET_NOWAIT will always return immediately, even if it cannot
594 read or write ANY data.
595 - @b wxSOCKET_WAITALL will only return when it has read or written ALL
597 - @b wxSOCKET_BLOCK has nothing to do with the previous flags and
598 it controls whether the GUI blocks.
599 - @b wxSOCKET_REUSEADDR controls special platform-specific behavior for
600 reusing local addresses/ports.
604 wxSOCKET_NONE
= 0, ///< Normal functionality.
605 wxSOCKET_NOWAIT
= 1, ///< Read/write as much data as possible and return immediately.
606 wxSOCKET_WAITALL
= 2, ///< Wait for all required data to be read/written unless an error occurs.
607 wxSOCKET_BLOCK
= 4, ///< Block the GUI (do not yield) while reading/writing data.
608 wxSOCKET_REUSEADDR
= 8, ///< Allows the use of an in-use port (wxServerSocket only)
609 wxSOCKET_BROADCAST
= 16, ///< Switches the socket to broadcast mode
610 wxSOCKET_NOBIND
= 32 ///< Stops the socket from being bound to a specific
611 ///< adapter (normally used in conjunction with
612 ///< @b wxSOCKET_BROADCAST)
619 wxSocketBase is the base class for all socket-related objects, and it
620 defines all basic IO functionality.
623 When using wxSocket from multiple threads, even implicitly (e.g. by using
624 wxFTP or wxHTTP in another thread) you must initialize the sockets from the
625 main thread by calling Initialize() before creating the other ones.
627 @beginEventEmissionTable{wxSocketEvent}
628 @event{EVT_SOCKET(id, func)}
629 Process a @c wxEVT_SOCKET event.
630 See @ref wxSocketEventFlags and @ref wxSocketFlags for more info.
636 @see wxSocketEvent, wxSocketClient, wxSocketServer, @sample{sockets},
637 @ref wxSocketFlags, ::wxSocketEventFlags, ::wxSocketError
639 class wxSocketBase
: public wxObject
644 @name Construction and Destruction
651 Don't use it directly; instead, use wxSocketClient to construct a socket client,
652 or wxSocketServer to construct a socket server.
659 Do not destroy a socket using the delete operator directly;
660 use Destroy() instead. Also, do not create socket objects in the stack.
662 virtual ~wxSocketBase();
665 Destroys the socket safely.
667 Use this function instead of the delete operator, since otherwise socket events
668 could reach the application even after the socket has been destroyed. To prevent
669 this problem, this function appends the wxSocket to a list of object to be deleted
670 on idle time, after all events have been processed. For the same reason, you should
671 avoid creating socket objects in the stack.
673 Destroy() calls Close() automatically.
675 @return Always @true.
680 Perform the initialization needed in order to use the sockets.
682 This function is called from wxSocket constructor implicitly and so
683 normally doesn't need to be called explicitly. There is however one
684 important exception: as this function must be called from the main
685 (UI) thread, if you use wxSocket from multiple threads you must call
686 Initialize() from the main thread before creating wxSocket objects in
689 It is safe to call this function multiple times (only the first call
690 does anything) but you must call Shutdown() exactly once for every call
694 @true if the sockets can be used, @false if the initialization
695 failed and sockets are not available at all.
697 static bool Initialize();
700 Shut down the sockets.
702 This function undoes the call to Initialize() and must be called after
703 every successful call to Initialize().
705 static void Shutdown();
716 Returns @true if an error occurred in the last IO operation.
718 Use this function to check for an error condition after one of the
719 following calls: Discard(), Peek(), Read(), ReadMsg(), Unread(), Write(), WriteMsg().
724 Return the local address of the socket.
726 @return @true if no error happened, @false otherwise.
728 virtual bool GetLocal(wxSockAddress
& addr
) const;
731 Return the peer address field of the socket.
733 @return @true if no error happened, @false otherwise.
735 virtual bool GetPeer(wxSockAddress
& addr
) const;
738 Return the socket timeout in seconds.
740 The timeout can be set using SetTimeout() and is 10 minutes by default.
742 long GetTimeout() const;
745 Returns @true if the socket is connected.
747 bool IsConnected() const;
750 Check if the socket can be currently read or written.
752 This might mean that queued data is available for reading or, for streamed
753 sockets, that the connection has been closed, so that a read operation will
754 complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag
755 is set, in which case the operation might still block).
760 Returns @true if the socket is not connected.
762 bool IsDisconnected() const;
765 Returns @true if the socket is initialized and ready and @false in other
769 For wxSocketClient, IsOk() won't return @true unless the client is connected to a server.
770 For wxSocketServer, IsOk() will return @true if the server could bind to the specified address
771 and is already listening for new connections.
772 IsOk() does not check for IO errors; use Error() instead for that purpose.
777 Returns the number of bytes read or written by the last IO call.
779 Use this function to get the number of bytes actually transferred
780 after using one of the following IO calls: Discard(), Peek(), Read(),
781 ReadMsg(), Unread(), Write(), WriteMsg().
783 wxUint32
LastCount() const;
786 Returns the last wxSocket error. See @ref wxSocketError .
789 This function merely returns the last error code,
790 but it should not be used to determine if an error has occurred (this
791 is because successful operations do not change the LastError value).
792 Use Error() first, in order to determine if the last IO call failed.
793 If this returns @true, use LastError() to discover the cause of the error.
795 wxSocketError
LastError() const;
798 Restore the previous state of the socket, as saved with SaveState().
800 Calls to SaveState() and RestoreState() can be nested.
807 Save the current state of the socket in a stack.
809 Socket state includes flags, as set with SetFlags(), event mask, as set
810 with SetNotify() and Notify(), user data, as set with SetClientData().
811 Calls to SaveState and RestoreState can be nested.
823 See also: wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
828 Shut down the socket, disabling further transmission and reception of
829 data and disable events for the socket and frees the associated system
832 Upon socket destruction, Close() is automatically called, so in most cases
833 you won't need to do it yourself, unless you explicitly want to shut down
834 the socket, typically to notify the peer that you are closing the connection.
837 Although Close() immediately disables events for the socket, it is possible
838 that event messages may be waiting in the application's event queue.
839 The application must therefore be prepared to handle socket event messages even
840 after calling Close().
842 virtual bool Close();
845 Shuts down the writing end of the socket.
847 This function simply calls the standard shutdown() function on the
848 underlying socket, indicating that nothing will be written to this
851 void ShutdownOutput();
854 Delete all bytes in the incoming queue.
856 This function always returns immediately and its operation is not
857 affected by IO flags.
859 Use LastCount() to verify the number of bytes actually discarded.
861 If you use Error(), it will always return @false.
863 wxSocketBase
& Discard();
866 Returns current IO flags, as set with SetFlags()
868 wxSocketFlags
GetFlags() const;
871 Use this function to interrupt any wait operation currently in progress.
873 Note that this is not intended as a regular way to interrupt a Wait call,
874 but only as an escape mechanism for exceptional situations where it is
875 absolutely necessary to use it, for example to abort an operation due to
876 some exception or abnormal problem. InterruptWait is automatically called
877 when you Close() a socket (and thus also upon
878 socket destruction), so you don't need to use it in these cases.
880 @see Wait(), WaitForLost(), WaitForRead(), WaitForWrite(),
881 wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
883 void InterruptWait();
886 Peek into the socket by copying the next bytes which would be read by
887 Read() into the provided buffer.
889 Peeking a buffer doesn't delete it from the socket input queue, i.e.
890 calling Read() will return the same data.
892 Use LastCount() to verify the number of bytes actually peeked.
894 Use Error() to determine if the operation succeeded.
897 Buffer where to put peeked data.
901 @return Returns a reference to the current object.
904 The exact behaviour of Peek() depends on the combination of flags being used.
905 For a detailed explanation, see SetFlags()
907 @see Error(), LastError(), LastCount(), SetFlags()
909 wxSocketBase
& Peek(void* buffer
, wxUint32 nbytes
);
912 Read up to the given number of bytes from the socket.
914 Use LastCount() to verify the number of bytes actually read.
915 Use Error() to determine if the operation succeeded.
918 Buffer where to put read data.
922 @return Returns a reference to the current object.
925 The exact behaviour of Read() depends on the combination of flags being used.
926 For a detailed explanation, see SetFlags()
928 @see Error(), LastError(), LastCount(),
931 wxSocketBase
& Read(void* buffer
, wxUint32 nbytes
);
934 Receive a message sent by WriteMsg().
936 If the buffer passed to the function isn't big enough, the remaining
937 bytes will be discarded. This function always waits for the buffer to
938 be entirely filled, unless an error occurs.
940 Use LastCount() to verify the number of bytes actually read.
942 Use Error() to determine if the operation succeeded.
945 Buffer where to put read data.
949 @return Returns a reference to the current object.
952 ReadMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set
953 and it will always ignore the @b wxSOCKET_NOWAIT flag.
954 The exact behaviour of ReadMsg() depends on the @b wxSOCKET_BLOCK flag.
955 For a detailed explanation, see SetFlags().
957 @see Error(), LastError(), LastCount(), SetFlags(), WriteMsg()
959 wxSocketBase
& ReadMsg(void* buffer
, wxUint32 nbytes
);
962 Use SetFlags to customize IO operation for this socket.
964 The @a flags parameter may be a combination of flags ORed together.
965 Notice that not all combinations of flags affecting the IO calls
966 (Read() and Write()) make sense, e.g. @b wxSOCKET_NOWAIT can't be
967 combined with @b wxSOCKET_WAITALL nor with @b wxSOCKET_BLOCK.
969 The following flags can be used:
972 Default mode: the socket will read some data in the IO calls and
973 will process events to avoid blocking UI while waiting for the data
975 @flag{wxSOCKET_NOWAIT}
976 Don't wait for the socket to become ready in IO calls, read as much
977 data as is available -- potentially 0 bytes -- and return
979 @flag{wxSOCKET_WAITALL}
980 Don't return before the entire amount of data specified in IO calls
981 is read or written unless an error occurs. If this flag is not
982 specified, the IO calls return as soon as any amount of data, even
983 less than the total number of bytes, is processed.
984 @flag{wxSOCKET_BLOCK}
985 Don't process the UI events while waiting for the socket to become
986 ready. This means that UI will be unresponsive during socket IO.
987 @flag{wxSOCKET_REUSEADDR}
988 Allows the use of an in-use port (wxServerSocket only).
989 @flag{wxSOCKET_BROADCAST}
990 Switches the socket to broadcast mode.
991 @flag{wxSOCKET_NOBIND}
992 Stops the socket from being bound to a specific adapter (normally
993 used in conjunction with @b wxSOCKET_BROADCAST).
996 For more information on socket events see @ref wxSocketFlags .
998 void SetFlags(wxSocketFlags flags
);
1001 Set the local address and port to use.
1003 This function must always be called for the server sockets but may also
1004 be called for client sockets, if it is, @b bind() is called before @b
1007 virtual bool SetLocal(const wxIPV4address
& local
);
1010 Set the default socket timeout in seconds.
1012 This timeout applies to all IO calls, and also to the Wait() family of
1013 functions if you don't specify a wait interval. Initially, the default
1014 timeout is 10 minutes.
1016 void SetTimeout(long seconds
);
1019 Put the specified data into the input queue.
1021 The data in the buffer will be returned by the next call to Read().
1023 This function is not affected by wxSocket flags.
1025 If you use LastCount(), it will always return @a nbytes.
1027 If you use Error(), it will always return @false.
1030 Buffer to be unread.
1034 @return Returns a reference to the current object.
1036 @see Error(), LastCount(), LastError()
1038 wxSocketBase
& Unread(const void* buffer
, wxUint32 nbytes
);
1041 Wait for any socket event.
1043 Possible socket events are:
1044 @li The socket becomes readable.
1045 @li The socket becomes writable.
1046 @li An ongoing connection request has completed (wxSocketClient only)
1047 @li An incoming connection request has arrived (wxSocketServer only)
1048 @li The connection has been closed.
1050 Note that it is recommended to use the individual @b WaitForXXX()
1051 functions to wait for the required condition, instead of this one.
1054 Number of seconds to wait.
1055 If -1, it will wait for the default timeout,
1056 as set with SetTimeout().
1058 Number of milliseconds to wait.
1061 @true when any of the above conditions is satisfied or @false if the
1062 timeout was reached.
1064 @see InterruptWait(), wxSocketServer::WaitForAccept(),
1065 WaitForLost(), WaitForRead(),
1066 WaitForWrite(), wxSocketClient::WaitOnConnect()
1068 bool Wait(long seconds
= -1, long millisecond
= 0);
1071 Wait until the connection is lost.
1073 This may happen if the peer gracefully closes the connection or if the
1077 Number of seconds to wait.
1078 If -1, it will wait for the default timeout,
1079 as set with SetTimeout().
1081 Number of milliseconds to wait.
1083 @return Returns @true if the connection was lost, @false if the timeout
1086 @see InterruptWait(), Wait()
1088 bool WaitForLost(long seconds
= -1, long millisecond
= 0);
1091 Wait until the socket is readable.
1093 This might mean that queued data is available for reading or, for streamed
1094 sockets, that the connection has been closed, so that a read operation will
1095 complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag
1096 is set, in which case the operation might still block).
1098 Notice that this function should not be called if there is already data
1099 available for reading on the socket.
1102 Number of seconds to wait.
1103 If -1, it will wait for the default timeout,
1104 as set with SetTimeout().
1106 Number of milliseconds to wait.
1108 @return Returns @true if the socket becomes readable, @false on timeout.
1110 @see InterruptWait(), Wait()
1112 bool WaitForRead(long seconds
= -1, long millisecond
= 0);
1115 Wait until the socket becomes writable.
1117 This might mean that the socket is ready to send new data, or for streamed
1118 sockets, that the connection has been closed, so that a write operation is
1119 guaranteed to complete immediately (unless the @b wxSOCKET_WAITALL flag is set,
1120 in which case the operation might still block).
1122 Notice that this function should not be called if the socket is already
1126 Number of seconds to wait.
1127 If -1, it will wait for the default timeout,
1128 as set with SetTimeout().
1130 Number of milliseconds to wait.
1132 @return Returns @true if the socket becomes writable, @false on timeout.
1134 @see InterruptWait(), Wait()
1136 bool WaitForWrite(long seconds
= -1, long millisecond
= 0);
1139 Write up to the given number of bytes to the socket.
1141 Use LastCount() to verify the number of bytes actually written.
1143 Use Error() to determine if the operation succeeded.
1146 Buffer with the data to be sent.
1150 @return Returns a reference to the current object.
1154 The exact behaviour of Write() depends on the combination of flags being used.
1155 For a detailed explanation, see SetFlags().
1157 @see Error(), LastError(), LastCount(), SetFlags()
1159 wxSocketBase
& Write(const void* buffer
, wxUint32 nbytes
);
1162 Sends a buffer which can be read using ReadMsg().
1164 WriteMsg() sends a short header before the data so that ReadMsg()
1165 knows how much data should be actually read.
1167 This function always waits for the entire buffer to be sent, unless an
1170 Use LastCount() to verify the number of bytes actually written.
1172 Use Error() to determine if the operation succeeded.
1175 Buffer with the data to be sent.
1177 Number of bytes to send.
1179 @return Returns a reference to the current object.
1183 WriteMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set and
1184 it will always ignore the @b wxSOCKET_NOWAIT flag. The exact behaviour of
1185 WriteMsg() depends on the @b wxSOCKET_BLOCK flag. For a detailed explanation,
1188 @see Error(), LastError(), LastCount(), SetFlags(), ReadMsg()
1191 wxSocketBase
& WriteMsg(const void* buffer
, wxUint32 nbytes
);
1197 @name Handling Socket Events
1202 Returns a pointer of the client data for this socket, as set with
1205 void* GetClientData() const;
1208 According to the @a notify value, this function enables
1209 or disables socket events. If @a notify is @true, the events
1210 configured with SetNotify() will
1211 be sent to the application. If @a notify is @false; no events
1214 void Notify(bool notify
);
1217 Sets user-supplied client data for this socket. All socket events will
1218 contain a pointer to this data, which can be retrieved with
1219 the wxSocketEvent::GetClientData() function.
1221 void SetClientData(void* data
);
1224 Sets an event handler to be called when a socket event occurs. The
1225 handler will be called for those events for which notification is
1226 enabled with SetNotify() and
1230 Specifies the event handler you want to use.
1232 The id of socket event.
1234 @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler
1236 void SetEventHandler(wxEvtHandler
& handler
, int id
= -1);
1239 Specifies which socket events are to be sent to the event handler.
1240 The @a flags parameter may be combination of flags ORed together. The
1241 following flags can be used:
1244 @flag{wxSOCKET_INPUT_FLAG} to receive @b wxSOCKET_INPUT.
1245 @flag{wxSOCKET_OUTPUT_FLAG} to receive @b wxSOCKET_OUTPUT.
1246 @flag{wxSOCKET_CONNECTION_FLAG} to receive @b wxSOCKET_CONNECTION.
1247 @flag{wxSOCKET_LOST_FLAG} to receive @b wxSOCKET_LOST.
1253 sock.SetNotify(wxSOCKET_INPUT_FLAG | wxSOCKET_LOST_FLAG);
1257 In this example, the user will be notified about incoming socket data and
1258 whenever the connection is closed.
1260 For more information on socket events see @ref wxSocketEventFlags .
1262 void SetNotify(wxSocketEventFlags flags
);
1270 @class wxDatagramSocket
1277 class wxDatagramSocket
: public wxSocketBase
1286 Socket flags (See wxSocketBase::SetFlags()).
1288 wxDatagramSocket(const wxSockAddress
& addr
,
1289 wxSocketFlags flags
= wxSOCKET_NONE
);
1292 Destructor. Please see wxSocketBase::Destroy().
1294 virtual ~wxDatagramSocket();
1297 Write a buffer of @a nbytes bytes to the socket.
1299 Use wxSocketBase::LastCount() to verify the number of bytes actually wrote.
1300 Use wxSocketBase::Error() to determine if the operation succeeded.
1303 The address of the destination peer for this data.
1305 Buffer where read data is.
1309 @return Returns a reference to the current object.
1311 @see wxSocketBase::LastError(), wxSocketBase::SetFlags()
1313 wxDatagramSocket
& SendTo(const wxSockAddress
& address
,
1314 const void* buffer
, wxUint32 nbytes
);