Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / socket.h
index 286c05cd00000111e5bfd7b077523e2d4ba33834..e78e484abd167a19739b1a75a066bb6486cd873b 100644 (file)
@@ -2,11 +2,20 @@
 // 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
 
@@ -14,7 +23,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 +112,7 @@ public:
 
     A class for working with IPv4 network addresses.
 
-    @library{wxbase}
+    @library{wxnet}
     @category{net}
 */
 class wxIPV4address : public wxIPaddress
@@ -210,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
@@ -296,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,
@@ -400,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
@@ -427,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;
 };
 
 
@@ -435,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}
@@ -550,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
@@ -558,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
@@ -574,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
@@ -594,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
@@ -603,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.
 };
 
 
@@ -622,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.
@@ -657,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.
@@ -688,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.
@@ -699,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();
 
@@ -723,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.
@@ -752,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.
@@ -777,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 .
 
@@ -837,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.
@@ -909,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
@@ -923,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);
@@ -935,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.
 
@@ -951,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);
 
@@ -1002,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.
@@ -1011,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.
@@ -1136,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.
 
@@ -1152,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);
 
@@ -1165,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.
 
@@ -1182,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);
@@ -1259,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;
+
     //@}
 };
 
@@ -1294,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