socket.h File Reference

Classes
class	wxIPaddress
	wxIPaddress is an abstract base class for all internet protocol address objects. More...
class	wxIPV4address
	A class for working with IPv4 network addresses. More...
class	wxSocketServer
class	wxSocketClient
class	wxSockAddress
	You are unlikely to need to use this class: only wxSocketBase uses it. More...
class	wxSocketEvent
	This event class contains information about socket events. More...
class	wxSocketBase
	wxSocketBase is the base class for all socket-related objects, and it defines all basic IO functionality. More...
class	wxDatagramSocket

Typedefs
typedef int	wxSOCKET_T
	The type of the native socket.

Enumerations
enum	wxSocketError {   wxSOCKET_NOERROR,   wxSOCKET_INVOP,   wxSOCKET_IOERR,   wxSOCKET_INVADDR,   wxSOCKET_INVSOCK,   wxSOCKET_NOHOST,   wxSOCKET_INVPORT,   wxSOCKET_WOULDBLOCK,   wxSOCKET_TIMEDOUT,   wxSOCKET_MEMERR }
	wxSocket error return values. More...
enum	wxSocketEventFlags {   wxSOCKET_INPUT,   wxSOCKET_OUTPUT,   wxSOCKET_CONNECTION,   wxSOCKET_LOST }
enum	{   wxSOCKET_NONE = 0,   wxSOCKET_NOWAIT = 1,   wxSOCKET_WAITALL = 2,   wxSOCKET_BLOCK = 4,   wxSOCKET_REUSEADDR = 8,   wxSOCKET_BROADCAST = 16,   wxSOCKET_NOBIND = 32,   wxSOCKET_NOWAIT_READ = 64,   wxSOCKET_WAITALL_READ = 128,   wxSOCKET_NOWAIT_WRITE = 256,   wxSOCKET_WAITALL_WRITE = 512 }

Typedef Documentation

typedef int wxSOCKET_T

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

Enumeration Type Documentation

anonymous enum

wxSocket Flags.

A brief overview on how to use these flags follows.

If no flag is specified (this is the same as 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 recv() or send(). Note that blocking here refers to when the function returns, not to whether the GUI blocks during this time.

If 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 recv() or send(). Note that 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 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 recv(). Note that 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 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 send(). Note that 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 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 recv() or send() as needed so as to transfer all the data. Note that 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 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 recv() as needed so as to transfer all the data. Note that 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 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 send() as needed so as to transfer all the data. Note that 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 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 wxSOCKET_REUSEADDR flag controls the use of the SO_REUSEADDR standard 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.

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 wxSOCKET_REUSEADDR implies SO_REUSEPORT in addition to SO_REUSEADDR to be consistent with Windows.

The wxSOCKET_BROADCAST flag controls the use of the SO_BROADCAST standard setsockopt() flag. This flag allows the socket to use the broadcast address, and is generally used in conjunction with wxSOCKET_NOBIND and wxIPaddress::BroadcastAddress().

So:

• wxSOCKET_NONE will try to read at least SOME data, no matter how much.
• wxSOCKET_NOWAIT will always return immediately, even if it cannot read or write ANY data.
• wxSOCKET_WAITALL will only return when it has read or written ALL the data.
• wxSOCKET_BLOCK has nothing to do with the previous flags and it controls whether the GUI blocks.
• wxSOCKET_REUSEADDR controls special platform-specific behaviour for reusing local addresses/ports.

Enumerator:

wxSOCKET_NONE	Normal functionality.
wxSOCKET_NOWAIT	Read/write as much data as possible and return immediately.
wxSOCKET_WAITALL	Wait for all required data to be read/written unless an error occurs.
wxSOCKET_BLOCK	Block the GUI (do not yield) while reading/writing data.
wxSOCKET_REUSEADDR	Allows the use of an in-use port.
wxSOCKET_BROADCAST	Switches the socket to broadcast mode.
wxSOCKET_NOBIND	Stops the socket from being bound to a specific adapter (normally used in conjunction with wxSOCKET_BROADCAST)
wxSOCKET_NOWAIT_READ	Read as much data as possible and return immediately.
wxSOCKET_WAITALL_READ	Wait for all required data to be read unless an error occurs.
wxSOCKET_NOWAIT_WRITE	Write as much data as possible and return immediately.
wxSOCKET_WAITALL_WRITE	Wait for all required data to be written unless an error occurs.

enum wxSocketError

wxSocket error return values.

Enumerator:

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.

enum wxSocketEventFlags

wxSocket Event Flags.

A brief note on how to use these events:

The 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 wxSOCKET_INPUT event, as more events will be produced as necessary.

The 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 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 wxSOCKET_WOULDBLOCK error occurs; after this, whenever the socket becomes writable again the application will be notified with another wxSOCKET_OUTPUT event.

The 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 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.

Enumerator:

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.