X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d56f17d882e365addf168c8aae9a64754a9500a2..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/socket.h diff --git a/interface/wx/socket.h b/interface/wx/socket.h index 3efa425a6c..e78e484abd 100644 --- a/interface/wx/socket.h +++ b/interface/wx/socket.h @@ -2,16 +2,117 @@ // Name: socket.h // 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 A class for working with IPv4 network addresses. - @library{wxbase} + @library{wxnet} @category{net} */ class wxIPV4address : public wxIPaddress @@ -70,12 +171,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 +219,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 +275,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 +305,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, @@ -401,7 +409,7 @@ public: You are unlikely to need to use this class: only wxSocketBase uses it. - @library{wxbase} + @library{wxnet} @category{net} @see wxSocketBase, wxIPaddress, wxIPV4address @@ -428,6 +436,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 +464,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} @@ -551,7 +581,32 @@ enum wxSocketEventFlags 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. + 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 @@ -559,7 +614,32 @@ enum wxSocketEventFlags 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. + 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 @@ -575,7 +655,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 +675,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,11 +684,15 @@ 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 + 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. }; @@ -623,7 +707,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 +742,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 +773,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 +786,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 +813,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 +842,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. @@ -778,9 +867,42 @@ public: 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(). + + @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; + /** + 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(). + + @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; + /** Returns the last wxSocket error. See @ref wxSocketError . @@ -838,7 +960,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. @@ -910,7 +1032,7 @@ public: /** Read up to the given number of bytes from the socket. - Use LastCount() to verify the number of bytes actually read. + Use LastReadCount() to verify the number of bytes actually read. Use Error() to determine if the operation succeeded. @param buffer @@ -924,7 +1046,7 @@ public: The exact behaviour of Read() depends on the combination of flags being used. For a detailed explanation, see SetFlags() - @see Error(), LastError(), LastCount(), + @see Error(), LastError(), LastReadCount(), SetFlags() */ wxSocketBase& Read(void* buffer, wxUint32 nbytes); @@ -936,7 +1058,7 @@ public: 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. + Use LastReadCount() to verify the number of bytes actually read. Use Error() to determine if the operation succeeded. @@ -952,8 +1074,15 @@ public: 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 Error(), LastError(), LastCount(), SetFlags(), WriteMsg() + @see Error(), LastError(), LastReadCount(), SetFlags(), WriteMsg() */ wxSocketBase& ReadMsg(void* buffer, wxUint32 nbytes); @@ -1003,7 +1132,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 +1141,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. @@ -1137,7 +1266,7 @@ public: /** Write up to the given number of bytes to the socket. - Use LastCount() to verify the number of bytes actually written. + Use LastWriteCount() to verify the number of bytes actually written. Use Error() to determine if the operation succeeded. @@ -1153,7 +1282,7 @@ public: The exact behaviour of Write() depends on the combination of flags being used. For a detailed explanation, see SetFlags(). - @see Error(), LastError(), LastCount(), SetFlags() + @see Error(), LastError(), LastWriteCount(), SetFlags() */ wxSocketBase& Write(const void* buffer, wxUint32 nbytes); @@ -1166,7 +1295,7 @@ public: 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. + Use LastWriteCount() to verify the number of bytes actually written. Use Error() to determine if the operation succeeded. @@ -1183,8 +1312,15 @@ public: 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(), LastCount(), SetFlags(), ReadMsg() + @see Error(), LastError(), LastWriteCount(), SetFlags(), ReadMsg() */ wxSocketBase& WriteMsg(const void* buffer, wxUint32 nbytes); @@ -1260,6 +1396,25 @@ public: */ 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; + //@} }; @@ -1295,7 +1450,7 @@ public: /** Write a buffer of @a nbytes bytes to the socket. - Use wxSocketBase::LastCount() to verify the number of bytes actually wrote. + Use wxSocketBase::LastWriteCount() to verify the number of bytes actually wrote. Use wxSocketBase::Error() to determine if the operation succeeded. @param address