|
Version: 3.1.0 |
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 |
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.
| enum wxSocketError |
wxSocket error return values.
| enum wxSocketEventFlags |
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.