WSPEventSelect (Compact 2013)
3/26/2014
This function specifies an event object to be associated with the supplied set of network events.
Syntax
int WSPEventSelect(
SOCKET s,
WSAEVENT hEventObject,
long lNetworkEvents,
LPINT lpErrno
);
Parameters
- s
[in] Descriptor identifying the socket.
- hEventObject
[in] Handle identifying the event object to be associated with the supplied set of network events.
- lNetworkEvents
[in] Bitmask that specifies the combination of network events in which the Windows Sockets SPI client has interest.
- lpErrno
[out] Pointer to the error code.
Return Value
The return value is zero if the Windows Sockets SPI client's specification of the network events and the associated event object was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number is available in lpErrno.
The following table shows the possible error codes.
Error value |
Description |
|---|---|
WSAENETDOWN |
Network subsystem has failed. |
WSAEINVAL |
Indicates that one of the specified parameters was invalid, or the specified socket is in an invalid state. |
WSAEINPROGRESS |
Blocking Windows Sockets call is in progress or the service provider is still processing a callback function. |
WSAENOTSOCK |
Descriptor is not a socket. |
Remarks
This function is used to specify an event object, hEventObject, to be associated with the selected network events, lNetworkEvents. The socket for which an event object is specified is identified by s. The event object is set when any of the nominated network events occur.
This function is the only function that causes network activity and errors to be recorded and retrievable through WSPEnumNetworkEvents. See the description of WSPSelect to find out how this function reports network activity and errors.
This function automatically sets socket s to nonblocking mode, regardless of the value of lNetworkEvents.
The following table shows the values that can be used to construct the lNetworkEvents parameter using the bitwise OR operator.
Value |
Description |
|---|---|
FD_READ |
Issues notification of readiness for reading. |
FD_WRITE |
Issues notification of readiness for writing. |
FD_OOB |
Issues notification of the arrival of OOB data. |
FD_ACCEPT |
Issues notification of incoming connections. |
FD_CONNECT |
Issues notification of completed connection. |
FD_CLOSE |
Issues notification of socket closure. |
FD_ROUTING_ INTERFACE_CHANGE |
Issues notification of routing interface changes for the specified destination(s). |
FD_ADDRESS_ LIST_CHANGE |
Issues notification of local address list changes for the socket's address family. |
Issuing a WSPEventSelect for a socket cancels any previous WSPEventSelect for the same socket and clears the internal network event record. For example, to associate an event object with both reading and writing network events, the Windows Sockets SPI client must call WSPEventSelect with both FD_READ and FD_WRITE, as shown in the following code sample.
rc = WSPEventSelect(s, hEventObject, FD_READ|FD_WRITE);
It is not possible to specify different event objects for different network events. The following code sample will not work; the second call will cancel the effects of the first, and only FD_WRITE network event will be associated with hEventObject2.
rc = WSPEventSelect(s, hEventObject1, FD_READ);
rc = WSPEventSelect(s, hEventObject2, FD_WRITE); //bad
To cancel the association and selection of network events on a socket, lNetworkEvents should be set to zero, in which case the hEventObject parameter will be ignored.
rc = WSPEventSelect(s, hEventObject, 0);
Closing a socket with WSPCloseSocket also cancels the association and selection of network events specified in WSPEventSelect for the socket. The Windows Sockets SPI client, however, still must call WSACloseEvent to explicitly close the event object and free any resources.
Because an accepted (WSPAccept) socket has the same properties as the listening socket used to accept it, any WSPEventSelect association and network events selection set for the listening socket apply to the accepted socket. For example, if a listening socket has WSPEventSelect association of hEventOject with FD_ACCEPT, FD_READ, and FD_WRITE, then any socket accepted on that listening socket will also have FD_ACCEPT, FD_READ, and FD_WRITE network events associated with the same hEventObject. If a different hEventObject or network events are needed, the Windows Sockets SPI client should call WSPEventSelect, passing the accepted socket and the new information.
Having successfully recorded the occurrence of the network event and signaled the associated event object, no further actions are taken for that network event until the Windows Sockets SPI client makes the function call that implicitly re-enables the setting of that network event and the signaling of the associated event object.
Network event |
Re-enabling function |
|---|---|
FD_READ |
|
FD_WRITE |
|
FD_OOB |
WSPRecv or WSPRecvFrom |
FD_ACCEPT |
WSPAccept unless the error code returned is WSATRY_AGAIN indicating that the condition function returned CF_DEFER |
FD_CONNECT |
None |
FD_CLOSE |
None |
FD_ROUTING_INTERFACE_CHANGE |
WSPIoctl with command SIO_ROUTING_INTERFACE_CHANGE |
FD_ADDRESS_LIST_CHANGE |
WSPIoctl with command SIO_ADDRESS_LIST_CHANGE |
Any call to the re-enabling routine, even one that fails, results in re-enabling of recording and signaling for the relevant network event and event object, respectively.
For FD_READ, FD_OOB, and FD_ACCEPT network events, network event recording and event object signaling are level-triggered. This means that if the re-enabling routine is called and the relevant network condition is still valid after the call, the network event is recorded and the associated event object is signaled. This allows a Windows Sockets SPI client to be event-driven and not be concerned with the amount of data that arrives at any one time. This is illustrated by the following sequence.
- Service provider receives 100 bytes of data on socket s, records the FD_READ network event and signals the associated event object.
- The Windows Sockets SPI client issues WSPRecv( s, buffptr, 50, 0) to read 50 bytes.
- The service provider records the FD_READ network event and signals the associated event object again because there is still data to be read.
With these semantics, a Windows Sockets SPI client need not read all available data in response to an FD_READ network eventa single WSPRecv in response to each FD_READ network event is appropriate.
The FD_ROUTING_INTERFACE_CHANGE and FD_ADDRESS_LIST_CHANGE events are considered edge triggered as well. A message will be posted exactly once when a change occurs AFTER the Windows Socket SPI client has requested the notification by issuing WSAIoctl with SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE correspondingly. Further messages will not be forthcoming until the SPI client reissues the IOCTL and another change is detected since the IOCTL has been issued.
If a network event has already occurred when the Windows Sockets SPI client calls WSPEventSelect or when the re-enabling function is called, then a network event is recorded and the associated event object is signaled as appropriate. This is illustrated in the following sequence.
- A Windows Sockets SPI client calls WSPListen.
- A connect request is received but not yet accepted.
- The Windows Sockets SPI client calls WSPEventSelect specifying that it is interested in the FD_ACCEPT network event for the socket. The service provider records the FD_ACCEPT network event and signals the associated event object immediately.
The FD_WRITE network event is handled slightly differently. An FD_WRITE network event is recorded when a socket is first connected with WSPConnect or accepted with WSPAccept, and then after a WSPSend or WSPSendTo fails with WSAEWOULDBLOCK and buffer space becomes available. Therefore, a Windows Sockets SPI client can assume that sends are possible starting from the first FD_WRITE network event setting and lasting until a send returns WSAEWOULDBLOCK. After such a failure the Windows Sockets SPI client will find out that sends are again possible when an FD_WRITE network event is recorded and the associated event object is signaled.
The FD_OOB network event is used only when a socket is configured to receive OOB data separately. If the socket is configured to receive OOB data inline, the OOB (expedited) data is treated as typical data and the Windows Sockets SPI client should register an interest in, and will get, FD_READ network event, not FD_OOB network event. A Windows Sockets SPI client can set or inspect the way in which OOB data is to be handled by using WSPSetSockOpt or WSPGetSockOpt for the SO_OOBINLINE option.
The error code in an FD_CLOSE network event indicates whether the socket close was graceful or abortive. If the error code is zero, then the close was graceful; if the error code is WSAECONNRESET, then the socket's virtual circuit was reset. This only applies to connection-oriented sockets such as SOCK_STREAM.
The FD_CLOSE network event is recorded when a close indication is received for the virtual circuit corresponding to the socket. In TCP terms, this means that the FD_CLOSE is recorded when the connection goes into the FIN WAIT or CLOSE WAIT states. This results from the remote end performing a WSPShutdown on the send side or a WSPCloseSocket.
Service providers shall record only an FD_CLOSE network event to indicate closure of a virtual circuit, they must not record an FD_READ network event to indicate this condition.
The FD_ROUTING_INTERFACE_CHANGE network event is recorded when the local interface that should be used to reach the destination specified in WSAIoctl with SIO_ROUTING_INTERFACE_CHANGE changes AFTER such IOCTL has been issued.
The FD_ADDRESS_LIST_CHANGE network event is recorded when the list of addresses of socket's protocol family to which the Windows Socket SPI client can bind changes after WSAIoctl with SIO_ADDRESS_LIST_CHANGE has been issued.
Requirements
Header |
ws2spi.h |
Library |
Ws2.lib |