WSPEnumNetworkEvents function

Artikel
06/19/2017

WSPEnumNetworkEvents reports occurrences of network events for a socket.

Syntax

int WSPEnumNetworkEvents(
  _In_  SOCKET             s,
  _In_  WSAEVENT           hEventObject,
  _Out_ LPWSANETWORKEVENTS lpNetworkEvents,
  _Out_ LPINT              lpErrno
);

Parameters

s [in]
Descriptor that identifies the socket.
hEventObject [in]
Handle to the event object that the SAN service provider subsequently resets.
lpNetworkEvents [out]
Pointer to a WSANETWORKEVENTS structure that receives a record of network events that occurred and any associated error codes.
lpErrno [out]
Pointer to a variable that receives the error code.

Return value

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

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

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

Remarks

WSANETWORKEVENTS

The WSANETWORKEVENTS structure is defined as:

typedef struct _WSANETWORKEVENTS {
    long lNetworkEvents;
    int iErrorCode[FD_MAX_EVENTS];
} WSANETWORKEVENTS, FAR * LPWSANETWORKEVENTS;

The members of this structure contain the following information:

lNetworkEvent
Bitmask that specifies the combination of FD_XXX network events that occurred. For a list of possible network events, see the Remarks section.
iErrorCode
Array of error codes that are associated with network events in lNetworkEvent. The index of each array element corresponds to the bit position of its associated network event in lNetworkEvent.

The Windows Sockets switch calls a SAN service provider's WSPEnumNetworkEvents function to obtain a report of network events that have occurred since the switch's last WSPEnumNetworkEvents call. Because the switch previously called the SAN service provider's WSPEventSelect function to register the occurrence of incoming-connection (FD_ACCEPT) and connection-completed (FD_CONNECT) events with a specific event object, only those events are reported to the switch.

After one or more of the registered events occurs, the SAN service provider can call the Win32 SetEvent function to signal the event object. The switch then calls the SAN service provider's WSPEnumNetworkEvents function to determine the type of events that occurred. The SAN service provider supplies the event information in a WSANETWORKEVENTS structure. The SAN service provider indicates event types in the lNetworkEvent member and any associated error codes in the iErrorCode array member. The index of an element in the error code array corresponds to the position of event bits in the lNetworkEvent member. That is, network events such as FD_CONNECT and FD_ACCEPT can be used to index the error code array. Note that only elements of the error code array that correspond to the bits set in lNetworkEvent are set; other elements are not modified.

The SAN service provider must internally record network events for a socket in a WSANETWORKEVENTS structure. Immediately after completing a WSPEnumNetworkEvents call, the SAN service provider must clear the previously recorded network events from WSANETWORKEVENTS. The SAN service provider can also call the Win32 ResetEvent function to reset the previously signaled event object. In other words, the SAN service provider performs the following operations in the following order to guarantee that subsequent occurrences of network events cause the event object to become signaled:

Records network events.
Clears network events after WSPEnumNetworkEvents call.
Resets the associated event object.

If WSPEnumNetworkEvents fails for some reason (returns SOCKET_ERROR), the SAN service provider neither clears the previously recorded network events from WSANETWORKEVENTS nor resets the previously signaled event object.

The following error codes can be returned along with the corresponding network event:

FD_CONNECT
- WSAECONNREFUSED
  Attempt to connect was forcefully rejected by the peer.
- WSAENETUNREACH
  Network cannot be currently reached from this host.
- WSAENOBUFS
  No buffer space available; the socket cannot be connected.
- WSAETIMEDOUT
  Attempt to connect timed out without establishing a connection.
FD_ACCEPT
- WSAENETDOWN
  Network subsystem failed.

For more information about ResetEvent and SetEvent, see the Microsoft Windows SDK documentation.

Requirements

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

Freigeben über