X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/socket.h?ds=sidebyside diff --git a/interface/wx/socket.h b/interface/wx/socket.h index 2312cf26e0..e78e484abd 100644 --- a/interface/wx/socket.h +++ b/interface/wx/socket.h @@ -1,89 +1,207 @@ ///////////////////////////////////////////////////////////////////////////// // Name: socket.h -// Purpose: interface of wxIPV4address +// Purpose: interface of wxIP*address, wxSocket* classes // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + +/** + The type of the native socket. + + Notice that the definition below is simplified and this type is not always + int, e.g. it is a 64 bit integer type under Win64. + + @since 2.9.5 + */ +typedef int wxSOCKET_T; + +/** + @class wxIPaddress + + wxIPaddress is an abstract base class for all internet protocol address + objects. Currently, only wxIPV4address is implemented. An experimental + implementation for IPV6, wxIPV6address, is being developed. + + @library{wxnet} + @category{net} +*/ +class wxIPaddress : public wxSockAddress +{ +public: + /** + Internally, this is the same as setting the IP address to @b INADDR_ANY. + + On IPV4 implementations, 0.0.0.0 + + On IPV6 implementations, :: + + @return @true on success, @false if something went wrong. + */ + bool AnyAddress(); + + /** + Internally, this is the same as setting the IP address to @b INADDR_BROADCAST. + + On IPV4 implementations, 255.255.255.255 + + @return @true on success, @false if something went wrong. + */ + virtual bool BroadcastAddress() = 0; + + /** + Set the address to hostname, which can be a host name or an IP-style address + in a format dependent on implementation. + + @return @true on success, @false if something goes wrong (invalid + hostname or invalid IP address). + */ + bool Hostname(const wxString& hostname); + + /** + Returns the hostname which matches the IP address. + */ + wxString Hostname() const; + + /** + Returns a wxString containing the IP address. + */ + virtual wxString IPAddress() const = 0; + + /** + Determines if current address is set to localhost. + + @return @true if address is localhost, @false if internet address. + */ + virtual bool IsLocalHost() const = 0; + + /** + Set address to localhost. + + On IPV4 implementations, 127.0.0.1 + + On IPV6 implementations, ::1 + + @return @true on success, @false if something went wrong. + */ + bool LocalHost(); + + /** + Set the port to that corresponding to the specified service. + + @return @true on success, @false if something goes wrong (invalid @a service). + */ + bool Service(const wxString& service); + + /** + Set the port to that corresponding to the specified service. + + @return @true on success, @false if something goes wrong (invalid @a service). + */ + bool Service(unsigned short service); + + /** + Returns the current service. + */ + unsigned short Service() const; +}; + + /** @class wxIPV4address - @wxheader{socket.h} + A class for working with IPv4 network addresses. - @library{wxbase} + @library{wxnet} @category{net} */ class wxIPV4address : public wxIPaddress { public: /** - Set address to any of the addresses of the current machine. Whenever - possible, use this function instead of LocalHost(), + Set address to any of the addresses of the current machine. + + Whenever possible, use this function instead of LocalHost(), as this correctly handles multi-homed hosts and avoids other small problems. Internally, this is the same as setting the IP address to @b INADDR_ANY. - @return Returns @true on success, @false if something went wrong. + @return @true on success, @false if something went wrong. */ bool AnyAddress(); - //@{ /** - Returns the hostname which matches the IP address. + Set the address to hostname, which can be a host name or an IP-style address + in dot notation(a.b.c.d). + + @return @true on success, @false if something goes wrong (invalid + hostname or invalid IP address). */ bool Hostname(const wxString& hostname); - Return value wxString Hostname(); - //@} + + /** + Returns the hostname which matches the IP address. + */ + virtual wxString Hostname() const; /** Returns a wxString containing the IP address in dot quad (127.0.0.1) format. */ - wxString IPAddress(); + virtual wxString IPAddress() const; /** - Set address to localhost (127.0.0.1). Whenever possible, use the - AnyAddress(), - function instead of this one, as this will correctly handle multi-homed - hosts and avoid other small problems. + Set address to localhost (127.0.0.1). + + Whenever possible, use AnyAddress() instead of this one, as that one will + correctly handle multi-homed hosts and avoid other small problems. + + @return @true on success, @false if something went wrong. */ bool LocalHost(); - //@{ /** - Returns the current service. + Set the port to that corresponding to the specified @a service. + + @return @true on success, @false if something goes wrong (invalid @a service). */ bool Service(const wxString& service); - Return value bool Service(unsigned short service); - Return value unsigned short Service(); - //@} + + /** + Set the port to that corresponding to the specified @a service. + + @return @true on success, @false if something goes wrong (invalid @a service). + */ + bool Service(unsigned short service); + + /** + Returns the current service. + */ + unsigned short Service() const; }; /** @class wxSocketServer - @wxheader{socket.h} + @todo describe me. @library{wxnet} @category{net} - - @see wxSocketServer::WaitForAccept, wxSocketBase::SetNotify, - wxSocketBase::Notify, wxSocketServer::AcceptWith */ class wxSocketServer : public wxSocketBase { public: /** Constructs a new server and tries to bind to the specified @e address. - Before trying to accept new connections, test whether it succeeded with - @ref wxSocketBase::isok wxSocketBase:IsOk. + + Before trying to accept new connections, remember to test whether it succeeded + with wxSocketBase:IsOk(). @param address Specifies the local address for the server (e.g. port number). @param flags - Socket flags (See wxSocketBase::SetFlags) + Socket flags (See wxSocketBase::SetFlags()). */ wxSocketServer(const wxSockAddress& address, wxSocketFlags flags = wxSOCKET_NONE); @@ -91,28 +209,31 @@ public: /** Destructor (it doesn't close the accepted connections). */ - ~wxSocketServer(); + virtual ~wxSocketServer(); /** - Accepts an incoming connection request, and creates a new - wxSocketBase object which represents - the server-side of the connection. + Accepts an incoming connection request, and creates a new wxSocketBase + object which represents the server-side of the connection. + If @a wait is @true and there are no pending connections to be accepted, it will wait for the next incoming connection to - arrive. @b Warning: This will block the GUI. + arrive. + + @warning This method will block the GUI. + If @a wait is @false, it will try to accept a pending connection if there is one, but it will always return immediately without blocking - the GUI. If you want to use Accept in this way, you can either check for - incoming connections with WaitForAccept() - or catch @b wxSOCKET_CONNECTION events, then call Accept once you know - that there is an incoming connection waiting to be accepted. + the GUI. If you want to use Accept() in this way, you can either check for + incoming connections with WaitForAccept() or catch @b wxSOCKET_CONNECTION events, + then call Accept() once you know that there is an incoming connection waiting + to be accepted. @return Returns an opened socket connection, or @NULL if an error - occurred or if the wait parameter was @false and there - were no pending connections. + occurred or if the wait parameter was @false and there + were no pending connections. - @see WaitForAccept(), wxSocketBase::SetNotify, - wxSocketBase::Notify, AcceptWith() + @see WaitForAccept(), wxSocketBase::SetNotify(), + wxSocketBase::Notify(), AcceptWith() */ wxSocketBase* Accept(bool wait = true); @@ -121,183 +242,162 @@ public: @param socket Socket to be initialized + @param wait + See Accept() for more info. + + @return Returns @true on success, or @false if an error occurred or + if the wait parameter was @false and there were no pending + connections. - @return Returns @true on success, or @false if an error occurred or if the - wait parameter was @false and there were no pending - connections. + @see WaitForAccept(), wxSocketBase::SetNotify(), + wxSocketBase::Notify(), Accept() */ bool AcceptWith(wxSocketBase& socket, bool wait = true); /** - This function waits for an incoming connection. Use it if you want to call - Accept() or AcceptWith() - with @e wait set to @false, to detect when an incoming connection is waiting - to be accepted. + Wait for an incoming connection. + + Use it if you want to call Accept() or AcceptWith() with @e wait set + to @false, to detect when an incoming connection is waiting to be accepted. @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. + Number of seconds to wait. If -1, it will wait for the default + timeout, as set with wxSocketBase::SetTimeout(). @param millisecond Number of milliseconds to wait. - @return Returns @true if an incoming connection arrived, @false if the - timeout elapsed. + @return @true if an incoming connection arrived, @false if the timeout + elapsed. + + @see Accept(), AcceptWith(), wxSocketBase::InterruptWait() */ bool WaitForAccept(long seconds = -1, long millisecond = 0); }; - /** - @class wxIPaddress - @wxheader{socket.h} + @class wxSocketClient - wxIPaddress is an abstract base class for all internet protocol address - objects. Currently, only wxIPV4address - is implemented. An experimental implementation for IPV6, wxIPV6address, - is being developed. + @todo describe me. - @library{wxbase} + @library{wxnet} @category{net} */ -class wxIPaddress : public wxSockAddress +class wxSocketClient : public wxSocketBase { public: /** - Internally, this is the same as setting the IP address - to @b INADDR_ANY. - On IPV4 implementations, 0.0.0.0 - On IPV6 implementations, :: - - @return Returns @true on success, @false if something went wrong. - */ - virtual bool AnyAddress(); - - /** - Internally, this is the same as setting the IP address - to @b INADDR_BROADCAST. - On IPV4 implementations, 255.255.255.255 - - @return Returns @true on success, @false if something went wrong. - */ - virtual bool BroadcastAddress(); - - //@{ - /** - Returns the hostname which matches the IP address. - */ - virtual bool Hostname(const wxString& hostname); - Return value virtual wxString Hostname(); - //@} - - /** - Returns a wxString containing the IP address. - */ - virtual wxString IPAddress(); + Constructor. - /** - Determines if current address is set to localhost. + @param flags + Socket flags (See wxSocketBase::SetFlags()) */ - virtual bool IsLocalHost(); + wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE); /** - Set address to localhost. - On IPV4 implementations, 127.0.0.1 - On IPV6 implementations, ::1 - - @return Returns @true on success, @false if something went wrong. + Destructor. Please see wxSocketBase::Destroy(). */ - virtual bool LocalHost(); + virtual ~wxSocketClient(); - //@{ /** - Returns the current service. - */ - virtual bool Service(const wxString& service); - Return value virtual bool Service(unsigned short service); - Return value virtual unsigned short Service(); - //@} -}; - - + Connects to a server using the specified address. -/** - @class wxSocketClient - @wxheader{socket.h} + If @a wait is @true, Connect() will wait until the connection + completes. + @warning This method will block the GUI. - @library{wxnet} - @category{net} + If @a wait is @false, Connect() will try to establish the connection + and return immediately, without blocking the GUI. When used this way, + even if Connect() returns @false, the connection request can be + completed later. To detect this, use WaitOnConnect(), or catch + @b wxSOCKET_CONNECTION events (for successful establishment) and + @b wxSOCKET_LOST events (for connection failure). - @see wxSocketClient::WaitOnConnect, wxSocketBase::SetNotify, - wxSocketBase::Notify -*/ -class wxSocketClient : public wxSocketBase -{ -public: - /** - Constructor. + @param address + Address of the server. + @param wait + If @true, waits for the connection to complete. - @param flags - Socket flags (See wxSocketBase::SetFlags) - */ - wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE); + @return @true if the connection is established and no error occurs. + If @a wait was true, and Connect() returns @false, an error + occurred and the connection failed. + If @a wait was @false, and Connect() returns @false, you should + still be prepared to handle the completion of this connection request, + either with WaitOnConnect() or by watching wxSOCKET_CONNECTION + and wxSOCKET_LOST events. - /** - Destructor. Please see wxSocketBase::Destroy. + @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify() */ - ~wxSocketClient(); + virtual bool Connect(const wxSockAddress& address, bool wait = true); - //@{ /** Connects to a server using the specified address. - If @a wait is @true, Connect will wait until the connection + + If @a wait is @true, Connect() will wait until the connection completes. @b Warning: This will block the GUI. - If @a wait is @false, Connect will try to establish the connection and - return immediately, without blocking the GUI. When used this way, even if - Connect returns @false, the connection request can be completed later. - To detect this, use WaitOnConnect(), - or catch @b wxSOCKET_CONNECTION events (for successful establishment) - and @b wxSOCKET_LOST events (for connection failure). + + If @a wait is @false, Connect() will try to establish the connection + and return immediately, without blocking the GUI. When used this way, + even if Connect() returns @false, the connection request can be + completed later. To detect this, use WaitOnConnect(), or catch + @b wxSOCKET_CONNECTION events (for successful establishment) and + @b wxSOCKET_LOST events (for connection failure). @param address Address of the server. @param local Bind to the specified local address and port before connecting. - The local address and port can also be set using SetLocal, - and then using the 2-parameter Connect method. + The local address and port can also be set using SetLocal(), + and then using the 2-parameter Connect() method. @param wait If @true, waits for the connection to complete. - @return Returns @true if the connection is established and no error - occurs. + @return @true if the connection is established and no error occurs. + If @a wait was true, and Connect() returns @false, an error + occurred and the connection failed. + If @a wait was @false, and Connect() returns @false, you should + still be prepared to handle the completion of this connection request, + either with WaitOnConnect() or by watching wxSOCKET_CONNECTION + and wxSOCKET_LOST events. - @see WaitOnConnect(), wxSocketBase::SetNotify, - wxSocketBase::Notify + @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify() */ - bool Connect(wxSockAddress& address, bool wait = true); - bool Connect(wxSockAddress& address, wxSockAddress& local, + bool Connect(const wxSockAddress& address, const wxSockAddress& local, bool wait = true); - //@} /** Wait until a connection request completes, or until the specified timeout - elapses. Use this function after issuing a call - to Connect() with @e wait set to @false. + elapses. Use this function after issuing a call to Connect() with + @e wait set to @false. @param seconds Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - @param millisecond + If -1, it will wait for the default timeout, as set with wxSocketBase::SetTimeout(). + @param milliseconds Number of milliseconds to wait. - @return WaitOnConnect returns @true if the connection request completes. - This does not necessarily mean that the connection was - successfully established; it might also happen that the - connection was refused by the peer. Use IsConnected to - distinguish between these two situations. + @return + WaitOnConnect() returns @true if the connection request completes. + This does not necessarily mean that the connection was + successfully established; it might also happen that the + connection was refused by the peer. Use wxSocketBase::IsConnected() + to distinguish between these two situations. + @n @n If the timeout elapses, WaitOnConnect() returns @false. + @n @n These semantics allow code like this: + @code + // Issue the connection request + client->Connect(addr, false); + + // Wait until the request completes or until we decide to give up + bool waitmore = true; + while ( !client->WaitOnConnect(seconds, millis) && waitmore ) + { + // possibly give some feedback to the user, + // and update waitmore as needed. + } + bool success = client->IsConnected(); + @endcode */ bool WaitOnConnect(long seconds = -1, long milliseconds = 0); }; @@ -306,12 +406,11 @@ public: /** @class wxSockAddress - @wxheader{socket.h} You are unlikely to need to use this class: only wxSocketBase uses it. - @library{wxbase} - @category{FIXME} + @library{wxnet} + @category{net} @see wxSocketBase, wxIPaddress, wxIPV4address */ @@ -326,26 +425,52 @@ public: /** Default destructor. */ - ~wxSockAddress(); + virtual ~wxSockAddress(); /** Delete all informations about the address. */ - void Clear(); + virtual void Clear(); /** Returns the length of the socket address. */ int SockAddrLen(); + + /** + Returns the pointer to the low-level representation of the address. + + This can be used to pass socket address information to a 3rd party + library. + + @return + Pointer to a sockaddr-derived struct. + */ + const sockaddr *GetAddressData() const; + + /** + Returns the length of the buffer retrieved by GetAddressData(). + + @return + The size of the sockaddr-derived struct corresponding to this + address. + */ + int GetAddressDataLen() const; }; /** @class wxSocketEvent - @wxheader{socket.h} This event class contains information about socket events. + This kind of events are sent to the event handler specified with + wxSocketBase::SetEventHandler. + + @beginEventTable{wxSocketEvent} + @event{EVT_SOCKET(id, func)} + Process a socket event, supplying the member function. + @endEventTable @library{wxnet} @category{net} @@ -362,13 +487,13 @@ public: /** Gets the client data of the socket which generated this event, as - set with wxSocketBase::SetClientData. + set with wxSocketBase::SetClientData(). */ - void* GetClientData(); + void* GetClientData() const; /** - Returns the socket object to which this event refers to. This makes - it possible to use the same event handler for different sockets. + Returns the socket object to which this event refers to. + This makes it possible to use the same event handler for different sockets. */ wxSocketBase* GetSocket() const; @@ -379,254 +504,514 @@ public: }; +/** + wxSocket error return values. +*/ +enum wxSocketError +{ + wxSOCKET_NOERROR, ///< No error happened. + wxSOCKET_INVOP, ///< Invalid operation. + wxSOCKET_IOERR, ///< Input/Output error. + wxSOCKET_INVADDR, ///< Invalid address passed to wxSocket. + wxSOCKET_INVSOCK, ///< Invalid socket (uninitialized). + wxSOCKET_NOHOST, ///< No corresponding host. + wxSOCKET_INVPORT, ///< Invalid port. + wxSOCKET_WOULDBLOCK, ///< The socket is non-blocking and the operation would block. + wxSOCKET_TIMEDOUT, ///< The timeout for this operation expired. + wxSOCKET_MEMERR ///< Memory exhausted. +}; + + +/** + @anchor wxSocketEventFlags + + wxSocket Event Flags. + + A brief note on how to use these events: + + The @b wxSOCKET_INPUT event will be issued whenever there is data available + for reading. This will be the case if the input queue was empty and new data + arrives, or if the application has read some data yet there is still more data + available. This means that the application does not need to read all available + data in response to a @b wxSOCKET_INPUT event, as more events will be produced + as necessary. + + The @b wxSOCKET_OUTPUT event is issued when a socket is first connected with + Connect() or accepted with Accept(). After that, new events will be generated + only after an output operation fails with @b wxSOCKET_WOULDBLOCK and buffer space + becomes available again. This means that the application should assume that it can + write data to the socket until an @b wxSOCKET_WOULDBLOCK error occurs; after this, + whenever the socket becomes writable again the application will be notified with + another @b wxSOCKET_OUTPUT event. + + The @b wxSOCKET_CONNECTION event is issued when a delayed connection request completes + successfully (client) or when a new connection arrives at the incoming queue (server). + + The @b wxSOCKET_LOST event is issued when a close indication is received for the socket. + This means that the connection broke down or that it was closed by the peer. Also, this + event will be issued if a connection request fails. +*/ +enum wxSocketEventFlags +{ + wxSOCKET_INPUT, ///< There is data available for reading. + wxSOCKET_OUTPUT, ///< The socket is ready to be written to. + wxSOCKET_CONNECTION, ///< Incoming connection request (server), or + ///< successful connection establishment (client). + wxSOCKET_LOST ///< The connection has been closed. +}; + + +/** + @anchor wxSocketFlags + + wxSocket Flags. + + A brief overview on how to use these flags follows. + + If no flag is specified (this is the same as @b wxSOCKET_NONE), + IO calls will return after some data has been read or written, even + when the transfer might not be complete. This is the same as issuing + exactly one blocking low-level call to @b recv() or @b send(). Note + that @e blocking here refers to when the function returns, not + to whether the GUI blocks during this time. + + If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately. + Read operations will retrieve only available data. Write operations will + write as much data as possible, depending on how much space is available + in the output buffer. This is the same as issuing exactly one nonblocking + low-level call to @b recv() or @b send(). Note that @e nonblocking here + refers to when the function returns, not to whether the GUI blocks during + this time. Also note that this flag impacts both Read and Write + operations. If it is desired to control Read independently of Write, for + example you want no wait on Read(), but you do want to wait on Write(), then + use wxSOCKET_NOWAIT_READ and wxSOCKET_NOWAIT_WRITE. + + If @b wxSOCKET_NOWAIT_READ (this flag is new since wxWidgets 2.9.5) is + specified, Read operations will return immediately. Read operations will + retrieve only available data. This is the same as issuing exactly one + nonblocking low-level call to @b recv(). Note that @e nonblocking here + refers to when the function returns, not to whether the GUI blocks during + this time. This flag should not be enabled if ReadMsg() is going to be + used (it will be ignored), if you do then thread-safety may be at risk. + Note that wxSOCKET_NOWAIT_READ impacts only Read operations and does not + impact Write operations, allowing Read and Write operations to be set + differently. + + If @b wxSOCKET_NOWAIT_WRITE (this flag is new since wxWidgets 2.9.5) is + specified, Write operations will return immediately. Write operations will + write as much data as possible, depending on how much space is available in + the output buffer. This is the same as issuing exactly one nonblocking + low-level call to @b send(). Note that @e nonblocking here refers to when + the function returns, not to whether the GUI blocks during this time. This + flag should not be enabled if WriteMsg() is going to be used (it will be + ignored), if you use it then thread safety may be at risk. Note that + wxSOCKET_NOWAIT_WRITE impacts only Write operations and does not impact + Write operations, allowing Read and Write operations to be set differently. + + If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL + the data has been read or written (or until an error occurs), blocking if + necessary, and issuing several low level calls if necessary. This is the + same as having a loop which makes as many blocking low-level calls to + @b recv() or @b send() as needed so as to transfer all the data. Note + that @e blocking here refers to when the function returns, not + to whether the GUI blocks during this time. Note that wxSOCKET_WAITALL + impacts both Read and Write operations. If you desire to wait + for all on just Read operations, but not on Write operations, (or vice versa), + use wxSOCKET_WAITALL_READ or wxSOCKET_WAITALL_WRITE. + + If @b wxSOCKET_WAITALL_READ (this flag is new since wxWidgets 2.9.5) is + specified, Read operations won't return until ALL the data has been read + (or until an error occurs), blocking if necessary, and issuing several low + level calls if necessary. This is the same as having a loop which makes as + many blocking low-level calls to @b recv() as needed so as to transfer all + the data. Note that @e blocking here refers to when the function returns, + not to whether the GUI blocks during this time. Note that + wxSOCKET_WAITALL_READ only has an impact on Read operations, and has no + impact on Write operations, allowing Read and Write operations to have + different settings. + + If @b wxSOCKET_WAITALL_WRITE (this flag is new since wxWidgets 2.9.5) is + specified, Write() and WriteMsg() calls won't return until ALL the data has + been written (or until an error occurs), blocking if necessary, and issuing + several low level calls if necessary. This is the same as having a loop + which makes as many blocking low-level calls to @b send() as needed so as + to transfer all the data. Note that @e blocking here refers to when the + function returns, not to whether the GUI blocks during this time. Note + that wxSOCKET_WAITALL_WRITE only has an impact on Write operations, and has + no impact on Read operations, allowing Read and Write operations to have + different settings. + + The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during + IO operations. If this flag is specified, the socket will not yield + during IO calls, so the GUI will remain blocked until the operation + completes. If it is not used, then the application must take extra + care to avoid unwanted reentrance. + + The @b wxSOCKET_REUSEADDR flag controls the use of the @b SO_REUSEADDR standard + @b setsockopt() flag. This flag allows the socket to bind to a port that is + already in use. This is mostly used on UNIX-based systems to allow rapid starting + and stopping of a server, otherwise you may have to wait several minutes for the + port to become available. + + @b wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a + particular local port for an outgoing connection. + This option can have surprising platform dependent behaviour, so check the + documentation for your platform's implementation of setsockopt(). + + Note that on BSD-based systems(e.g. Mac OS X), use of + @b wxSOCKET_REUSEADDR implies @b SO_REUSEPORT in addition to + @b SO_REUSEADDR to be consistent with Windows. + + The @b wxSOCKET_BROADCAST flag controls the use of the @b SO_BROADCAST standard + @b setsockopt() flag. This flag allows the socket to use the broadcast address, + and is generally used in conjunction with @b wxSOCKET_NOBIND and + wxIPaddress::BroadcastAddress(). + + So: + - @b wxSOCKET_NONE will try to read at least SOME data, no matter how much. + - @b wxSOCKET_NOWAIT will always return immediately, even if it cannot + read or write ANY data. + - @b wxSOCKET_WAITALL will only return when it has read or written ALL + the data. + - @b wxSOCKET_BLOCK has nothing to do with the previous flags and + it controls whether the GUI blocks. + - @b wxSOCKET_REUSEADDR controls special platform-specific behaviour for + reusing local addresses/ports. +*/ +enum +{ + wxSOCKET_NONE = 0, ///< Normal functionality. + wxSOCKET_NOWAIT = 1, ///< Read/write as much data as possible and return immediately. + wxSOCKET_WAITALL = 2, ///< Wait for all required data to be read/written unless an error occurs. + wxSOCKET_BLOCK = 4, ///< Block the GUI (do not yield) while reading/writing data. + wxSOCKET_REUSEADDR = 8, ///< Allows the use of an in-use port. + wxSOCKET_BROADCAST = 16, ///< Switches the socket to broadcast mode + wxSOCKET_NOBIND = 32, ///< Stops the socket from being bound to a specific + ///< adapter (normally used in conjunction with + ///< @b wxSOCKET_BROADCAST) + wxSOCKET_NOWAIT_READ = 64, ///< Read as much data as possible and return immediately + wxSOCKET_WAITALL_READ = 128, ///< Wait for all required data to be read unless an error occurs. + wxSOCKET_NOWAIT_WRITE = 256, ///< Write as much data as possible and return immediately + wxSOCKET_WAITALL_WRITE = 512 ///< Wait for all required data to be written unless an error occurs. +}; + /** @class wxSocketBase - @wxheader{socket.h} wxSocketBase is the base class for all socket-related objects, and it defines all basic IO functionality. - Note: (Workaround for implementation limitation for wxWidgets up to 2.5.x) - If you want to use sockets or derived classes such as wxFTP in a secondary - thread, - call wxSocketBase::Initialize() (undocumented) from the main thread before - creating - any sockets - in wxApp::OnInit for example. - See http://wiki.wxwidgets.org/wiki.pl?WxSocket or - http://www.litwindow.com/knowhow/knowhow.html for more details. + @note + When using wxSocket from multiple threads, even implicitly (e.g. by using + wxFTP or wxHTTP in another thread) you must initialize the sockets from the + main thread by calling Initialize() before creating the other ones. + + @beginEventEmissionTable{wxSocketEvent} + @event{EVT_SOCKET(id, func)} + Process a @c wxEVT_SOCKET event. + See @ref wxSocketEventFlags and @ref wxSocketFlags for more info. + @endEventTable @library{wxnet} @category{net} - @see wxSocketEvent, wxSocketClient, wxSocketServer, @ref overview_samplesockets - "Sockets sample" + @see wxSocketEvent, wxSocketClient, wxSocketServer, @sample{sockets}, + @ref wxSocketFlags, ::wxSocketEventFlags, ::wxSocketError */ class wxSocketBase : public wxObject { public: - /** - Default constructor. Don't use it directly; instead, use - wxSocketClient to construct a socket client, or - wxSocketServer to construct a socket server. - */ - wxSocketBase(); /** - Destructor. Do not destroy a socket using the delete operator directly; - use Destroy() instead. Also, do not create - socket objects in the stack. + @name Construction and Destruction */ - ~wxSocketBase(); + //@{ /** - Functions that perform basic IO functionality. - Close() + Default constructor. - Discard() + Don't use it directly; instead, use wxSocketClient to construct a socket client, + or wxSocketServer to construct a socket server. + */ + wxSocketBase(); - Peek() + /** + Destructor. - Read() + Do not destroy a socket using the delete operator directly; + use Destroy() instead. Also, do not create socket objects in the stack. + */ + virtual ~wxSocketBase(); - ReadMsg() + /** + Destroys the socket safely. - Unread() + Use this function instead of the delete operator, since otherwise socket events + could reach the application even after the socket has been destroyed. To prevent + this problem, this function appends the wxSocket to a list of object to be deleted + on idle time, after all events have been processed. For the same reason, you should + avoid creating socket objects in the stack. - Write() + Destroy() calls Close() automatically. - WriteMsg() - Functions that perform a timed wait on a certain IO condition. - InterruptWait() + @return Always @true. + */ + bool Destroy(); - Wait() + /** + Perform the initialization needed in order to use the sockets. - WaitForLost() + This function is called from wxSocket constructor implicitly and so + normally doesn't need to be called explicitly. There is however one + important exception: as this function must be called from the main + (UI) thread, if you use wxSocket from multiple threads you must call + Initialize() from the main thread before creating wxSocket objects in + the other ones. - WaitForRead() + It is safe to call this function multiple times (only the first call + does anything) but you must call Shutdown() exactly once for every call + to Initialize(). - WaitForWrite() + This function should only be called from the main thread. - and also: - wxSocketServer::WaitForAccept + @return + @true if the sockets can be used, @false if the initialization + failed and sockets are not available at all. + */ + static bool Initialize(); - wxSocketClient::WaitOnConnect - Functions that allow applications to customize socket IO as needed. - GetFlags() + /** + Shut down the sockets. - SetFlags() + This function undoes the call to Initialize() and must be called after + every successful call to Initialize(). - SetTimeout() + This function should only be called from the main thread, just as + Initialize(). + */ + static void Shutdown(); - SetLocal() - */ + //@} /** - This function shuts down the socket, disabling further transmission and - reception of data; it also disables events for the socket and frees the - associated system resources. Upon socket destruction, Close is automatically - called, so in most cases you won't need to do it yourself, unless you - explicitly want to shut down the socket, typically to notify the peer - that you are closing the connection. + @name Socket State */ - void Close(); + //@{ /** - @ref construct() wxSocketBase - - @ref destruct() ~wxSocketBase + Returns @true if an error occurred in the last IO operation. - Destroy() + Use this function to check for an error condition after one of the + following calls: Discard(), Peek(), Read(), ReadMsg(), Unread(), Write(), WriteMsg(). */ - + bool Error() const; /** - Destroys the socket safely. Use this function instead of the delete operator, - since otherwise socket events could reach the application even after the - socket has been destroyed. To prevent this problem, this function appends - the wxSocket to a list of object to be deleted on idle time, after all - events have been processed. For the same reason, you should avoid creating - socket objects in the stack. - Destroy calls Close() automatically. + Return the local address of the socket. - @return Always @true. + @return @true if no error happened, @false otherwise. */ - bool Destroy(); + virtual bool GetLocal(wxSockAddress& addr) const; /** - This function simply deletes all bytes in the incoming queue. This function - always returns immediately and its operation is not affected by IO flags. - Use LastCount() to verify the number of bytes actually discarded. - If you use Error(), it will always return @false. + Return the peer address field of the socket. + + @return @true if no error happened, @false otherwise. */ - wxSocketBase Discard(); + virtual bool GetPeer(wxSockAddress& addr) const; /** - Returns @true if an error occurred in the last IO operation. - Use this function to check for an error condition after one of the - following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg. - */ - bool Error() const; + Return the socket timeout in seconds. + + The timeout can be set using SetTimeout() and is 10 minutes by default. + */ + long GetTimeout() const; /** - Returns a pointer of the client data for this socket, as set with - SetClientData() + Returns @true if the socket is connected. */ - void* GetClientData() const; + bool IsConnected() const; /** - Returns current IO flags, as set with SetFlags() + Check if the socket can be currently read or written. + + This might mean that queued data is available for reading or, for streamed + sockets, that the connection has been closed, so that a read operation will + complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag + is set, in which case the operation might still block). */ - wxSocketFlags GetFlags() const; + bool IsData(); /** - This function returns the local address field of the socket. The local - address field contains the complete local address of the socket (local - address, local port, ...). - - @return @true if no error happened, @false otherwise. + Returns @true if the socket is not connected. */ - bool GetLocal(wxSockAddress& addr) const; + bool IsDisconnected() const; /** - This function returns the peer address field of the socket. The peer - address field contains the complete peer host address of the socket - (address, port, ...). + Returns @true if the socket is initialized and ready and @false in other + cases. - @return @true if no error happened, @false otherwise. + @remarks + For wxSocketClient, IsOk() won't return @true unless the client is connected to a server. + For wxSocketServer, IsOk() will return @true if the server could bind to the specified address + and is already listening for new connections. + IsOk() does not check for IO errors; use Error() instead for that purpose. */ - bool GetPeer(wxSockAddress& addr) const; + bool IsOk() const; /** - Functions that allow applications to receive socket events. - Notify() + Returns the number of bytes read or written by the last IO call. - SetNotify() + Use this function to get the number of bytes actually transferred + after using one of the following IO calls: Discard(), Peek(), Read(), + ReadMsg(), Unread(), Write(), WriteMsg(). - GetClientData() + @deprecated + This function is kept mostly for backwards compatibility. Use + LastReadCount() or LastWriteCount() instead. LastCount() is still + needed for use with less commonly used functions: Discard(), + Peek(), and Unread(). + */ + wxUint32 LastCount() const; - SetClientData() + /** + Returns the number of bytes read by the last Read() or ReadMsg() + call (receive direction only). + + This function is thread-safe, in case Read() is executed in a + different thread than Write(). Use LastReadCount() instead of + LastCount() for this reason. + + Unlike LastCount(), the functions Discard(), Peek(), and Unread() + are currently not supported by LastReadCount(). - SetEventHandler() + @since 2.9.5 */ + wxUint32 LastReadCount() const; + + /** + Returns the number of bytes written by the last Write() or WriteMsg() + call (transmit direction only). + This function is thread-safe, in case Write() is executed in a + different thread than Read(). Use LastWriteCount() instead of + LastCount() for this reason. + + @since 2.9.5 + */ + wxUint32 LastWriteCount() const; /** - Use this function to interrupt any wait operation currently in progress. - Note that this is not intended as a regular way to interrupt a Wait call, - but only as an escape mechanism for exceptional situations where it is - absolutely necessary to use it, for example to abort an operation due to - some exception or abnormal problem. InterruptWait is automatically called - when you Close() a socket (and thus also upon - socket destruction), so you don't need to use it in these cases. - Wait(), - wxSocketServer::WaitForAccept, - WaitForLost(), - WaitForRead(), - WaitForWrite(), - wxSocketClient::WaitOnConnect + Returns the last wxSocket error. See @ref wxSocketError . + + @note + This function merely returns the last error code, + but it should not be used to determine if an error has occurred (this + is because successful operations do not change the LastError value). + Use Error() first, in order to determine if the last IO call failed. + If this returns @true, use LastError() to discover the cause of the error. */ - void InterruptWait(); + wxSocketError LastError() const; /** - Returns @true if the socket is connected. + Restore the previous state of the socket, as saved with SaveState(). + + Calls to SaveState() and RestoreState() can be nested. + + @see SaveState() */ - bool IsConnected() const; + void RestoreState(); /** - This function waits until the socket is readable. This might mean that - queued data is available for reading or, for streamed sockets, that - the connection has been closed, so that a read operation will complete - immediately without blocking (unless the @b wxSOCKET_WAITALL flag - is set, in which case the operation might still block). + Save the current state of the socket in a stack. + + Socket state includes flags, as set with SetFlags(), event mask, as set + with SetNotify() and Notify(), user data, as set with SetClientData(). + Calls to SaveState and RestoreState can be nested. + + @see RestoreState() */ - bool IsData() const; + void SaveState(); + + //@} + /** - Returns @true if the socket is not connected. + @name Basic I/O + + See also: wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect() */ - bool IsDisconnected() const; + //@{ /** - Returns @true if the socket is initialized and ready and @false in other - cases. + Shut down the socket, disabling further transmission and reception of + data and disable events for the socket and frees the associated system + resources. + + Upon socket destruction, Close() is automatically called, so in most cases + you won't need to do it yourself, unless you explicitly want to shut down + the socket, typically to notify the peer that you are closing the connection. + + @remarks + Although Close() immediately disables events for the socket, it is possible + that event messages may be waiting in the application's event queue. + The application must therefore be prepared to handle socket event messages even + after calling Close(). */ - bool IsOk() const; + virtual bool Close(); /** - Returns the number of bytes read or written by the last IO call. - Use this function to get the number of bytes actually transferred - after using one of the following IO calls: Discard, Peek, Read, - ReadMsg, Unread, Write, WriteMsg. + Shuts down the writing end of the socket. + + This function simply calls the standard shutdown() function on the + underlying socket, indicating that nothing will be written to this + socket any more. + */ + void ShutdownOutput(); + + /** + Delete all bytes in the incoming queue. + + This function always returns immediately and its operation is not + affected by IO flags. + + Use LastCount() to verify the number of bytes actually discarded. + + If you use Error(), it will always return @false. */ - wxUint32 LastCount() const; + wxSocketBase& Discard(); /** - Returns the last wxSocket error. See @ref overview_wxsocketbase "wxSocket - errors". - Please note that this function merely returns the last error code, - but it should not be used to determine if an error has occurred (this - is because successful operations do not change the LastError value). - Use Error() first, in order to determine - if the last IO call failed. If this returns @true, use LastError - to discover the cause of the error. + Returns current IO flags, as set with SetFlags() */ - wxSocketError LastError() const; + wxSocketFlags GetFlags() const; /** - According to the @a notify value, this function enables - or disables socket events. If @a notify is @true, the events - configured with SetNotify() will - be sent to the application. If @a notify is @false; no events - will be sent. + Use this function to interrupt any wait operation currently in progress. + + Note that this is not intended as a regular way to interrupt a Wait call, + but only as an escape mechanism for exceptional situations where it is + absolutely necessary to use it, for example to abort an operation due to + some exception or abnormal problem. InterruptWait is automatically called + when you Close() a socket (and thus also upon + socket destruction), so you don't need to use it in these cases. + + @see Wait(), WaitForLost(), WaitForRead(), WaitForWrite(), + wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect() */ - void Notify(bool notify); + void InterruptWait(); /** - This function peeks a buffer of @a nbytes bytes from the socket. - Peeking a buffer doesn't delete it from the socket input queue. + Peek into the socket by copying the next bytes which would be read by + Read() into the provided buffer. + + Peeking a buffer doesn't delete it from the socket input queue, i.e. + calling Read() will return the same data. + Use LastCount() to verify the number of bytes actually peeked. + Use Error() to determine if the operation succeeded. @param buffer @@ -636,14 +1021,18 @@ public: @return Returns a reference to the current object. - @see Error(), LastError(), LastCount(), - SetFlags() + @remarks + The exact behaviour of Peek() depends on the combination of flags being used. + For a detailed explanation, see SetFlags() + + @see Error(), LastError(), LastCount(), SetFlags() */ - wxSocketBase Peek(void* buffer, wxUint32 nbytes); + wxSocketBase& Peek(void* buffer, wxUint32 nbytes); /** - This function reads a buffer of @a nbytes bytes from the socket. - Use LastCount() to verify the number of bytes actually read. + Read up to the given number of bytes from the socket. + + Use LastReadCount() to verify the number of bytes actually read. Use Error() to determine if the operation succeeded. @param buffer @@ -653,17 +1042,24 @@ public: @return Returns a reference to the current object. - @see Error(), LastError(), LastCount(), + @remarks + The exact behaviour of Read() depends on the combination of flags being used. + For a detailed explanation, see SetFlags() + + @see Error(), LastError(), LastReadCount(), SetFlags() */ - wxSocketBase Read(void* buffer, wxUint32 nbytes); + wxSocketBase& Read(void* buffer, wxUint32 nbytes); /** - This function reads a buffer sent by WriteMsg() - on a socket. If the buffer passed to the function isn't big enough, the - remaining bytes will be discarded. This function always waits for the - buffer to be entirely filled, unless an error occurs. - Use LastCount() to verify the number of bytes actually read. + Receive a message sent by WriteMsg(). + + If the buffer passed to the function isn't big enough, the remaining + bytes will be discarded. This function always waits for the buffer to + be entirely filled, unless an error occurs. + + Use LastReadCount() to verify the number of bytes actually read. + Use Error() to determine if the operation succeeded. @param buffer @@ -673,222 +1069,89 @@ public: @return Returns a reference to the current object. - @see Error(), LastError(), LastCount(), - SetFlags(), WriteMsg() - */ - wxSocketBase ReadMsg(void* buffer, wxUint32 nbytes); - - /** - This function restores the previous state of the socket, as saved - with SaveState() - Calls to SaveState and RestoreState can be nested. - - @see SaveState() - */ - void RestoreState(); - - /** - This function saves the current state of the socket in a stack. Socket - state includes flags, as set with SetFlags(), - event mask, as set with SetNotify() and - Notify(), user data, as set with - SetClientData(). - Calls to SaveState and RestoreState can be nested. - - @see RestoreState() - */ - void SaveState(); - - /** - Sets user-supplied client data for this socket. All socket events will - contain a pointer to this data, which can be retrieved with - the wxSocketEvent::GetClientData function. - */ - void SetClientData(void* data); - - /** - Sets an event handler to be called when a socket event occurs. The - handler will be called for those events for which notification is - enabled with SetNotify() and - Notify(). - - @param handler - Specifies the event handler you want to use. - @param id - The id of socket event. + @remarks + ReadMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set + and it will always ignore the @b wxSOCKET_NOWAIT flag. + The exact behaviour of ReadMsg() depends on the @b wxSOCKET_BLOCK flag. + For a detailed explanation, see SetFlags(). + For thread safety, in case ReadMsg() and WriteMsg() are called in + different threads, it is a good idea to call + SetFlags(wxSOCKET_WAITALL|wx_SOCKET_BLOCK) before the first calls + to ReadMsg() and WriteMsg() in different threads, as each of these + functions will call SetFlags() which performs read/modify/write. By + setting these flags before the multi-threading, it will ensure that + they don't get reset by thread race conditions. - @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler + @see Error(), LastError(), LastReadCount(), SetFlags(), WriteMsg() */ - void SetEventHandler(wxEvtHandler& handler, int id = -1); + wxSocketBase& ReadMsg(void* buffer, wxUint32 nbytes); /** Use SetFlags to customize IO operation for this socket. + The @a flags parameter may be a combination of flags ORed together. - The following flags can be used: + Notice that not all combinations of flags affecting the IO calls + (Read() and Write()) make sense, e.g. @b wxSOCKET_NOWAIT can't be + combined with @b wxSOCKET_WAITALL nor with @b wxSOCKET_BLOCK. - @b wxSOCKET_NONE - - Normal functionality. - - @b wxSOCKET_NOWAIT - - Read/write as much data as possible and return immediately. - - @b wxSOCKET_WAITALL - - Wait for all required data to be read/written unless an error occurs. - - @b wxSOCKET_BLOCK - - Block the GUI (do not yield) while reading/writing data. - - @b wxSOCKET_REUSEADDR - - Allows the use of an in-use port (wxServerSocket only) - - @b wxSOCKET_BROADCAST - - Switches the socket to broadcast mode - - @b wxSOCKET_NOBIND - - Stops the socket from being bound to a specific adapter (normally used in - conjunction with @b wxSOCKET_BROADCAST) - - A brief overview on how to use these flags follows. - If no flag is specified (this is the same as @b wxSOCKET_NONE), - IO calls will return after some data has been read or written, even - when the transfer might not be complete. This is the same as issuing - exactly one blocking low-level call to recv() or send(). Note - that @e blocking here refers to when the function returns, not - to whether the GUI blocks during this time. - If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately. - Read operations will retrieve only available data. Write operations will - write as much data as possible, depending on how much space is available - in the output buffer. This is the same as issuing exactly one nonblocking - low-level call to recv() or send(). Note that @e nonblocking here - refers to when the function returns, not to whether the GUI blocks during - this time. - If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL - the data has been read or written (or until an error occurs), blocking if - necessary, and issuing several low level calls if necessary. This is the - same as having a loop which makes as many blocking low-level calls to - recv() or send() as needed so as to transfer all the data. Note - that @e blocking here refers to when the function returns, not - to whether the GUI blocks during this time. - The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during - IO operations. If this flag is specified, the socket will not yield - during IO calls, so the GUI will remain blocked until the operation - completes. If it is not used, then the application must take extra - care to avoid unwanted reentrance. - The @b wxSOCKET_REUSEADDR flag controls the use of the SO_REUSEADDR standard - setsockopt() flag. This flag allows the socket to bind to a port that is - already in use. - This is mostly used on UNIX-based systems to allow rapid starting and stopping - of a server - - otherwise you may have to wait several minutes for the port to become available. - wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a - particular local port - for an outgoing connection. - This option can have surprising platform dependent behavior, so check the - documentation for - your platform's implementation of setsockopt(). Note that on BSD-based systems - (e.g. Mac OS X), - use of wxSOCKET_REUSEADDR implies SO_REUSEPORT in addition to SO_REUSEADDR to - be consistent - with Windows. - The @b wxSOCKET_BROADCAST flag controls the use of the SO_BROADCAST standard - setsockopt() flag. This flag allows the socket to use the broadcast address, - and is generally - used in conjunction with @b wxSOCKET_NOBIND and wxIPaddress::BroadcastAddress. - So: - @b wxSOCKET_NONE will try to read at least SOME data, no matter how much. - @b wxSOCKET_NOWAIT will always return immediately, even if it cannot - read or write ANY data. - @b wxSOCKET_WAITALL will only return when it has read or written ALL - the data. - @b wxSOCKET_BLOCK has nothing to do with the previous flags and - it controls whether the GUI blocks. - @b wxSOCKET_REUSEADDR controls special platform-specific behavior for - reusing local addresses/ports. + The following flags can be used: + @beginFlagTable + @flag{wxSOCKET_NONE} + Default mode: the socket will read some data in the IO calls and + will process events to avoid blocking UI while waiting for the data + to become available. + @flag{wxSOCKET_NOWAIT} + Don't wait for the socket to become ready in IO calls, read as much + data as is available -- potentially 0 bytes -- and return + immediately. + @flag{wxSOCKET_WAITALL} + Don't return before the entire amount of data specified in IO calls + is read or written unless an error occurs. If this flag is not + specified, the IO calls return as soon as any amount of data, even + less than the total number of bytes, is processed. + @flag{wxSOCKET_BLOCK} + Don't process the UI events while waiting for the socket to become + ready. This means that UI will be unresponsive during socket IO. + @flag{wxSOCKET_REUSEADDR} + Allows the use of an in-use port (wxServerSocket only). + @flag{wxSOCKET_BROADCAST} + Switches the socket to broadcast mode. + @flag{wxSOCKET_NOBIND} + Stops the socket from being bound to a specific adapter (normally + used in conjunction with @b wxSOCKET_BROADCAST). + @endFlagTable + + For more information on socket events see @ref wxSocketFlags . */ void SetFlags(wxSocketFlags flags); /** - This function allows you to set the local address and port, - useful when an application needs to reuse a particular port. When - a local port is set for a wxSocketClient, - @b bind will be called before @b connect. - */ - bool SetLocal(wxIPV4address& local); - - /** - SetNotify specifies which socket events are to be sent to the event handler. - The @a flags parameter may be combination of flags ORed together. The - following flags can be used: - - @b wxSOCKET_INPUT_FLAG - - to receive wxSOCKET_INPUT - - @b wxSOCKET_OUTPUT_FLAG - - to receive wxSOCKET_OUTPUT - - @b wxSOCKET_CONNECTION_FLAG - - to receive wxSOCKET_CONNECTION + Set the local address and port to use. - @b wxSOCKET_LOST_FLAG - - to receive wxSOCKET_LOST - - For example: - - In this example, the user will be notified about incoming socket data and - whenever the connection is closed. - For more information on socket events see @ref overview_wxsocketbase "wxSocket - events". + This function must always be called for the server sockets but may also + be called for client sockets, if it is, @b bind() is called before @b + connect(). */ - void SetNotify(wxSocketEventFlags flags); + virtual bool SetLocal(const wxIPV4address& local); /** - This function sets the default socket timeout in seconds. This timeout - applies to all IO calls, and also to the Wait() family - of functions if you don't specify a wait interval. Initially, the default + Set the default socket timeout in seconds. + + This timeout applies to all IO calls, and also to the Wait() family of + functions if you don't specify a wait interval. Initially, the default timeout is 10 minutes. */ - void SetTimeout(int seconds); + void SetTimeout(long seconds); /** - Functions to retrieve current state and miscellaneous info. - Error() - - GetLocal() + Put the specified data into the input queue. - GetPeer() - IsConnected() + The data in the buffer will be returned by the next call to Read(). - IsData() + This function is not affected by wxSocket flags. - IsDisconnected() + If you use LastCount(), it will always return @a nbytes. - LastCount() - - LastError() - - IsOk() - - SaveState() - - RestoreState() - */ - - - /** - This function unreads a buffer. That is, the data in the buffer is put back - in the incoming queue. This function is not affected by wxSocket flags. - If you use LastCount(), it will always return @e nbytes. If you use Error(), it will always return @false. @param buffer @@ -900,64 +1163,73 @@ public: @see Error(), LastCount(), LastError() */ - wxSocketBase Unread(const void* buffer, wxUint32 nbytes); + wxSocketBase& Unread(const void* buffer, wxUint32 nbytes); /** - This function waits until any of the following conditions is @true: + Wait for any socket event. - The socket becomes readable. - The socket becomes writable. - An ongoing connection request has completed (wxSocketClient only) - An incoming connection request has arrived (wxSocketServer only) - The connection has been closed. - Note that it is recommended to use the individual Wait functions - to wait for the required condition, instead of this one. + Possible socket events are: + @li The socket becomes readable. + @li The socket becomes writable. + @li An ongoing connection request has completed (wxSocketClient only) + @li An incoming connection request has arrived (wxSocketServer only) + @li The connection has been closed. + + Note that it is recommended to use the individual @b WaitForXXX() + functions to wait for the required condition, instead of this one. @param seconds Number of seconds to wait. If -1, it will wait for the default timeout, - as set with SetTimeout. + as set with SetTimeout(). @param millisecond Number of milliseconds to wait. - @return Returns @true when any of the above conditions is satisfied, - @false if the timeout was reached. + @return + @true when any of the above conditions is satisfied or @false if the + timeout was reached. - @see InterruptWait(), wxSocketServer::WaitForAccept, + @see InterruptWait(), wxSocketServer::WaitForAccept(), WaitForLost(), WaitForRead(), - WaitForWrite(), wxSocketClient::WaitOnConnect + WaitForWrite(), wxSocketClient::WaitOnConnect() */ bool Wait(long seconds = -1, long millisecond = 0); /** - This function waits until the connection is lost. This may happen if - the peer gracefully closes the connection or if the connection breaks. + Wait until the connection is lost. + + This may happen if the peer gracefully closes the connection or if the + connection breaks. @param seconds Number of seconds to wait. If -1, it will wait for the default timeout, - as set with SetTimeout. + as set with SetTimeout(). @param millisecond Number of milliseconds to wait. @return Returns @true if the connection was lost, @false if the timeout - was reached. + was reached. @see InterruptWait(), Wait() */ bool WaitForLost(long seconds = -1, long millisecond = 0); /** - This function waits until the socket is readable. This might mean that - queued data is available for reading or, for streamed sockets, that - the connection has been closed, so that a read operation will complete - immediately without blocking (unless the @b wxSOCKET_WAITALL flag + Wait until the socket is readable. + + This might mean that queued data is available for reading or, for streamed + sockets, that the connection has been closed, so that a read operation will + complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag is set, in which case the operation might still block). + Notice that this function should not be called if there is already data + available for reading on the socket. + @param seconds Number of seconds to wait. If -1, it will wait for the default timeout, - as set with SetTimeout. + as set with SetTimeout(). @param millisecond Number of milliseconds to wait. @@ -968,16 +1240,20 @@ public: bool WaitForRead(long seconds = -1, long millisecond = 0); /** - This function waits until the socket becomes writable. This might mean that - the socket is ready to send new data, or for streamed sockets, that the - connection has been closed, so that a write operation is guaranteed to - complete immediately (unless the @b wxSOCKET_WAITALL flag is set, + Wait until the socket becomes writable. + + This might mean that the socket is ready to send new data, or for streamed + sockets, that the connection has been closed, so that a write operation is + guaranteed to complete immediately (unless the @b wxSOCKET_WAITALL flag is set, in which case the operation might still block). + Notice that this function should not be called if the socket is already + writable. + @param seconds Number of seconds to wait. If -1, it will wait for the default timeout, - as set with SetTimeout. + as set with SetTimeout(). @param millisecond Number of milliseconds to wait. @@ -988,8 +1264,10 @@ public: bool WaitForWrite(long seconds = -1, long millisecond = 0); /** - This function writes a buffer of @a nbytes bytes to the socket. - Use LastCount() to verify the number of bytes actually written. + Write up to the given number of bytes to the socket. + + Use LastWriteCount() to verify the number of bytes actually written. + Use Error() to determine if the operation succeeded. @param buffer @@ -999,18 +1277,26 @@ public: @return Returns a reference to the current object. - @see Error(), LastError(), LastCount(), - SetFlags() + @remarks + + The exact behaviour of Write() depends on the combination of flags being used. + For a detailed explanation, see SetFlags(). + + @see Error(), LastError(), LastWriteCount(), SetFlags() */ - wxSocketBase Write(const void* buffer, wxUint32 nbytes); + wxSocketBase& Write(const void* buffer, wxUint32 nbytes); /** - This function writes a buffer of @a nbytes bytes from the socket, but it - writes a short header before so that ReadMsg() - knows how much data should it actually read. So, a buffer sent with WriteMsg - @b must be read with ReadMsg. This function always waits for the entire - buffer to be sent, unless an error occurs. - Use LastCount() to verify the number of bytes actually written. + Sends a buffer which can be read using ReadMsg(). + + WriteMsg() sends a short header before the data so that ReadMsg() + knows how much data should be actually read. + + This function always waits for the entire buffer to be sent, unless an + error occurs. + + Use LastWriteCount() to verify the number of bytes actually written. + Use Error() to determine if the operation succeeded. @param buffer @@ -1019,22 +1305,128 @@ public: Number of bytes to send. @return Returns a reference to the current object. + + @remarks + + WriteMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set and + it will always ignore the @b wxSOCKET_NOWAIT flag. The exact behaviour of + WriteMsg() depends on the @b wxSOCKET_BLOCK flag. For a detailed explanation, + see SetFlags(). + For thread safety, in case ReadMsg() and WriteMsg() are called in + different threads, it is a good idea to call + @code SetFlags(wxSOCKET_WAITALL|wx_SOCKET_BLOCK) @endcode before the + first calls to ReadMsg() and WriteMsg() in different threads, as each + of these functions calls SetFlags() which performs read/modify/write. + By setting these flags before the multi-threading, it will ensure that + they don't get reset by thread race conditions. + + @see Error(), LastError(), LastWriteCount(), SetFlags(), ReadMsg() + + */ + wxSocketBase& WriteMsg(const void* buffer, wxUint32 nbytes); + + //@} + + + /** + @name Handling Socket Events */ - wxSocketBase WriteMsg(const void* buffer, wxUint32 nbytes); + //@{ + + /** + Returns a pointer of the client data for this socket, as set with + SetClientData() + */ + void* GetClientData() const; + + /** + According to the @a notify value, this function enables + or disables socket events. If @a notify is @true, the events + configured with SetNotify() will + be sent to the application. If @a notify is @false; no events + will be sent. + */ + void Notify(bool notify); + + /** + Sets user-supplied client data for this socket. All socket events will + contain a pointer to this data, which can be retrieved with + the wxSocketEvent::GetClientData() function. + */ + void SetClientData(void* data); + + /** + Sets an event handler to be called when a socket event occurs. The + handler will be called for those events for which notification is + enabled with SetNotify() and + Notify(). + + @param handler + Specifies the event handler you want to use. + @param id + The id of socket event. + + @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler + */ + void SetEventHandler(wxEvtHandler& handler, int id = -1); + + /** + Specifies which socket events are to be sent to the event handler. + The @a flags parameter may be combination of flags ORed together. The + following flags can be used: + + @beginFlagTable + @flag{wxSOCKET_INPUT_FLAG} to receive @b wxSOCKET_INPUT. + @flag{wxSOCKET_OUTPUT_FLAG} to receive @b wxSOCKET_OUTPUT. + @flag{wxSOCKET_CONNECTION_FLAG} to receive @b wxSOCKET_CONNECTION. + @flag{wxSOCKET_LOST_FLAG} to receive @b wxSOCKET_LOST. + @endFlagTable + + For example: + + @code + sock.SetNotify(wxSOCKET_INPUT_FLAG | wxSOCKET_LOST_FLAG); + sock.Notify(true); + @endcode + + In this example, the user will be notified about incoming socket data and + whenever the connection is closed. + + For more information on socket events see @ref wxSocketEventFlags . + */ + void SetNotify(wxSocketEventFlags flags); + + /** + Returns the native socket descriptor. + + This is intended to use with rarely used specific platform features + that can only be accessed via the actual socket descriptor. + + Do not use this for reading or writing data from or to the socket as + this would almost surely interfere with wxSocket code logic and result + in unexpected behaviour. + + The socket must be successfully initialized, e.g. connected for client + sockets, before this method can be called. + + @return Returns the native socket descriptor. + + @since 2.9.5 + */ + wxSOCKET_T GetSocket() const; + + //@} }; /** @class wxDatagramSocket - @wxheader{socket.h} + @todo docme @library{wxnet} - @category{FIXME} - - @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, - wxSocketBase::SetFlags, + @category{net} */ class wxDatagramSocket : public wxSocketBase { @@ -1042,43 +1434,24 @@ public: /** Constructor. + @param addr + The socket address. @param flags - Socket flags (See wxSocketBase::SetFlags) + Socket flags (See wxSocketBase::SetFlags()). */ - wxDatagramSocket(wxSocketFlags flags = wxSOCKET_NONE); + wxDatagramSocket(const wxSockAddress& addr, + wxSocketFlags flags = wxSOCKET_NONE); /** - Destructor. Please see wxSocketBase::Destroy. + Destructor. Please see wxSocketBase::Destroy(). */ - ~wxDatagramSocket(); + virtual ~wxDatagramSocket(); /** - This function reads a buffer of @a nbytes bytes from the socket. - Use wxSocketBase::LastCount to verify the number of bytes actually read. - Use wxSocketBase::Error to determine if the operation succeeded. - - @param address - Any address - will be overwritten with the address of the peer that sent - that data. - @param buffer - Buffer where to put read data. - @param nbytes - Number of bytes. - - @return Returns a reference to the current object, and the address of - the peer that sent the data on address param. + Write a buffer of @a nbytes bytes to the socket. - @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, - wxSocketBase::SetFlags, - */ - wxDatagramSocket ReceiveFrom(wxSockAddress& address, - void* buffer, - wxUint32 nbytes); - - /** - This function writes a buffer of @a nbytes bytes to the socket. - Use wxSocketBase::LastCount to verify the number of bytes actually wrote. - Use wxSocketBase::Error to determine if the operation succeeded. + Use wxSocketBase::LastWriteCount() to verify the number of bytes actually wrote. + Use wxSocketBase::Error() to determine if the operation succeeded. @param address The address of the destination peer for this data. @@ -1088,9 +1461,10 @@ public: Number of bytes. @return Returns a reference to the current object. + + @see wxSocketBase::LastError(), wxSocketBase::SetFlags() */ - wxDatagramSocket SendTo(const wxSockAddress& address, - const void* buffer, - wxUint32 nbytes); + wxDatagramSocket& SendTo(const wxSockAddress& address, + const void* buffer, wxUint32 nbytes); };