Version: 3.1.1
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. More...
 

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

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.

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.