X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d56f17d882e365addf168c8aae9a64754a9500a2..4d98817cfab2654773755cb5c540057c5f3d4fd6:/interface/wx/socket.h diff --git a/interface/wx/socket.h b/interface/wx/socket.h index 3efa425a6c..43d3c753c2 100644 --- a/interface/wx/socket.h +++ b/interface/wx/socket.h @@ -3,9 +3,101 @@ // Purpose: interface of wxIP*address, wxSocket* classes // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + +/** + @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{wxbase} + @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 @@ -70,12 +162,12 @@ public: @return @true on success, @false if something goes wrong (invalid @a service). */ - bool Service(unsigned short service) = 0; + bool Service(unsigned short service); /** Returns the current service. */ - unsigned short Service() const = 0; + unsigned short Service() const; }; @@ -118,7 +210,7 @@ public: accepted, it will wait for the next incoming connection to arrive. - @warning: This method will block the GUI. + @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 @@ -174,99 +266,6 @@ public: }; - -/** - @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{wxbase} - @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). - */ - virtual bool Hostname(const wxString& hostname) = 0; - - /** - Returns the hostname which matches the IP address. - */ - virtual wxString Hostname() const = 0; - - /** - 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). - */ - virtual bool Service(const wxString& service) = 0; - - /** - Set the port to that corresponding to the specified service. - - @return @true on success, @false if something goes wrong (invalid @a service). - */ - virtual bool Service(unsigned short service) = 0; - - /** - Returns the current service. - */ - virtual unsigned short Service() const = 0; -}; - - - /** @class wxSocketClient @@ -297,7 +296,7 @@ public: If @a wait is @true, Connect() will wait until the connection completes. - @warning: This method will block the GUI. + @warning This method 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, @@ -428,6 +427,26 @@ public: 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; }; @@ -436,10 +455,12 @@ public: @class wxSocketEvent 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. + Process a socket event, supplying the member function. @endEventTable @library{wxnet} @@ -575,7 +596,7 @@ enum wxSocketEventFlags @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 behavior, so check the + 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 @@ -595,7 +616,7 @@ enum wxSocketEventFlags 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 + - @b wxSOCKET_REUSEADDR controls special platform-specific behaviour for reusing local addresses/ports. */ enum @@ -604,7 +625,7 @@ enum 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 (wxServerSocket only) + 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 @@ -623,7 +644,7 @@ enum wxFTP or wxHTTP in another thread) you must initialize the sockets from the main thread by calling Initialize() before creating the other ones. - @beginEventTable{wxSocketEvent} + @beginEventEmissionTable{wxSocketEvent} @event{EVT_SOCKET(id, func)} Process a @c wxEVT_SOCKET event. See @ref wxSocketEventFlags and @ref wxSocketFlags for more info. @@ -658,7 +679,7 @@ public: Do not destroy a socket using the delete operator directly; use Destroy() instead. Also, do not create socket objects in the stack. */ - ~wxSocketBase(); + virtual ~wxSocketBase(); /** Destroys the socket safely. @@ -689,6 +710,8 @@ public: does anything) but you must call Shutdown() exactly once for every call to Initialize(). + This function should only be called from the main thread. + @return @true if the sockets can be used, @false if the initialization failed and sockets are not available at all. @@ -700,6 +723,9 @@ public: This function undoes the call to Initialize() and must be called after every successful call to Initialize(). + + This function should only be called from the main thread, just as + Initialize(). */ static void Shutdown(); @@ -724,14 +750,14 @@ public: @return @true if no error happened, @false otherwise. */ - bool GetLocal(wxSockAddress& addr) const; + virtual bool GetLocal(wxSockAddress& addr) const; /** Return the peer address field of the socket. @return @true if no error happened, @false otherwise. */ - bool GetPeer(wxSockAddress& addr) const; + virtual bool GetPeer(wxSockAddress& addr) const; /** Return the socket timeout in seconds. @@ -753,7 +779,7 @@ public: complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag is set, in which case the operation might still block). */ - bool IsData() const; + bool IsData(); /** Returns @true if the socket is not connected. @@ -838,7 +864,7 @@ public: The application must therefore be prepared to handle socket event messages even after calling Close(). */ - void Close(); + virtual bool Close(); /** Shuts down the writing end of the socket. @@ -1003,7 +1029,7 @@ public: be called for client sockets, if it is, @b bind() is called before @b connect(). */ - bool SetLocal(const wxIPV4address& local); + virtual bool SetLocal(const wxIPV4address& local); /** Set the default socket timeout in seconds. @@ -1012,7 +1038,7 @@ public: functions if you don't specify a wait interval. Initially, the default timeout is 10 minutes. */ - void SetTimeout(int seconds); + void SetTimeout(long seconds); /** Put the specified data into the input queue.