X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/382f12e41917abf78fb7f00d786c7ead112e4df4..38534f596974042130716a26276e9564b0b72295:/interface/wx/socket.h diff --git a/interface/wx/socket.h b/interface/wx/socket.h index 88d0071a4f..6c2f80060d 100644 --- a/interface/wx/socket.h +++ b/interface/wx/socket.h @@ -3,10 +3,20 @@ // 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 @@ -14,7 +24,7 @@ objects. Currently, only wxIPV4address is implemented. An experimental implementation for IPV6, wxIPV6address, is being developed. - @library{wxbase} + @library{wxnet} @category{net} */ class wxIPaddress : public wxSockAddress @@ -103,7 +113,7 @@ public: A class for working with IPv4 network addresses. - @library{wxbase} + @library{wxnet} @category{net} */ class wxIPV4address : public wxIPaddress @@ -210,7 +220,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 @@ -296,7 +306,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, @@ -400,7 +410,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 @@ -427,6 +437,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; }; @@ -435,10 +465,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} @@ -550,7 +582,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 @@ -558,7 +615,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 @@ -574,7 +656,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 @@ -594,7 +676,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 @@ -603,11 +685,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. }; @@ -622,7 +708,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. @@ -688,6 +774,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. @@ -699,6 +787,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(); @@ -777,9 +868,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 . @@ -909,7 +1033,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 @@ -923,7 +1047,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); @@ -935,7 +1059,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. @@ -951,8 +1075,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); @@ -1136,7 +1267,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. @@ -1152,7 +1283,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); @@ -1165,7 +1296,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. @@ -1182,8 +1313,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); @@ -1259,6 +1397,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; + //@} }; @@ -1294,7 +1451,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