+/**
+ 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.
+};
+
projects / wxWidgets.git / blobdiff