WSPEventSelect function

Article
06/19/2017

WSPEventSelect associates an event object with a socket and a set of network events.

Syntax

int WSPEventSelect(
  _In_  SOCKET   s,
  _In_  WSAEVENT hEventObject,
  _In_  long     lNetworkEvents,
  _Out_ LPINT    lpErrno
);

Parameters

s [in]
Descriptor that identifies the socket.
hEventObject [in]
Handle to the event object that becomes associated with the supplied set of network events.
lNetworkEvents [in]
Bitmask that specifies the combination of FD_XXX network events for the SAN service provider. For a list of possible network events, see the Remarks section.
lpErrno [out]
Pointer to a variable that receives the error code.

Return value

Returns zero if successful; otherwise, returns SOCKET_ERROR and, at lpErrno, one of the following error codes:

Return code	Description
WSAENETDOWN	Network subsystem failed.
WSAEINVAL	Indicates that one of the specified parameters was invalid, or the specified socket is in an invalid state.
WSAENOTSOCK	Descriptor is not a socket.

Note that a SAN service provider does not support the WSAEINPROGRESS error code for WSPEventSelect, because the switch never issues cancel blocking calls to a SAN service provider.

Remarks

The Windows Sockets switch calls a SAN service provider's WSPEventSelect function to associate an event object with a socket and a set of network events on which the switch requires notification. The switch specifies that it requires notification only when incoming-connection (FD_ACCEPT) and connection-completed (FD_CONNECT) events occur. That is, the switch uses the bitwise OR operator to combine the FD_ACCEPT and FD_CONNECT events before passing them to WSPEventSelect.

The SAN service provider must internally record the occurrence of the specified network events in a WSANETWORKEVENTS structure. After the SAN service provider calls the Win32 SetEvent function to signal the event object indicating that one or more network events occurred, the switch calls the WSPEnumNetworkEvents function to retrieve the contents of WSANETWORKEVENTS and, thereby, determine which network events occurred. For more information about SetEvent, see the Microsoft Windows SDK documentation.

The WSPEventSelect function automatically sets the specified socket to nonblocking mode.

Note After the SAN service provider successfully records the occurrence of a network event and signals the associated event object, the switch retrieves the state of that network event. After the SAN service provider clears that network event, the SAN service provider takes no further actions related to that network event until the switch implicitly reenables the setting of that network event and the signaling of the associated event object. To reenable the settings for the following network events, the switch makes the following function calls.

Network Event	Reenabling Function
FD_ACCEPT	The WSPAccept function..
FD_CONNECT	NONE

Note Any call to the reenabling routine--even one that fails--results in operations that cause the SAN service provider to record the relevant network event and signal the associated event object.

For the FD_ACCEPT network event, network event recording and event-object resetting are level triggered. Level triggered means that if the reenabling 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 reset. Using this approach, the switch is event driven rather than concerned with the amount of data that arrives at any given time.

If a network event occurred before the switch calls WSPEventSelect or the reenabling function, the SAN service provider still records the occurrence of that network event and signals the associated event object, as appropriate. For example, consider the following sequence:

The switch calls the WSPListen function.
An incoming-connection event is received, but not yet accepted.
The switch calls the WSPEventSelect function, specifying that it requires notification on incoming-connection (FD_ACCEPT) events for the specified socket. The SAN service provider records the previous FD_ACCEPT event and signals the associated event object immediately.

Requirements

Target platform	Desktop
Version	Requires Windows Sockets version 2.0.
Header	Ws2spi.h (include Ws2spi.h)

Partager via