See Also
 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This function discovers occurrences of network events for the indicated socket, clear internal network event records, and reset event objects (optional).
Syntax
int WSAEnumNetworkEvents( SOCKET s, WSAEVENT hEventObject, LPWSANETWORKEVENTS lpNetworkEvents ); |
Parameters
- s
-
[in] Descriptor identifying the socket.
- hEventObject
-
[in] Optional handle identifying an associated event object to be reset.
- lpNetworkEvents
-
[out] Pointer to a WSANETWORKEVENTSstructure that is filled with a record of network events that occurred and any associated error codes.
Return Value
If no error occurs, this function returns zero. If an error occurs, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError. The following table shows a list of possible error codes.
| Error code | Description |
|---|---|
|
WSANOTINITIALISED |
A successful WSAStartupcall must occur before using this function. |
|
WSAENETDOWN |
The network subsystem has failed. |
|
WSAEINVAL |
One of the specified parameters was invalid. |
|
WSAEINPROGRESS |
A blocking Winsock call is in progress, or the service provider is still processing a callback function. |
|
WSAENOTSOCK |
The descriptor is not a socket. |
|
WSAEFAULT |
The lpNetworkEventsargument is not a valid part of the user address space. |
Remarks
This function is used to discover which network events have occurred for the indicated socket since the last invocation of this function. It is intended for use in conjunction with the WSAEventSelectfunction, which associates an event object with one or more network events. The recording of network events commences when WSAEventSelectis called with a nonzero lNetworkEventsparameter and remains in effect until another call is made to WSAEventSelectwith the lNetworkEventsparameter set to zero.
WSAEnumNetworkEventsonly reports network activity and errors nominated through WSAEventSelect. See the descriptions of selectto find out how those functions report network activity and errors.
The socket's internal record of network events is copied to the structure referenced by lpNetworkEvents, after which the internal network events record is cleared. If the hEventObjectparameter is not NULL, the indicated event object is also reset. The Windows Sockets provider guarantees that the operations of copying the network event record, clearing it and resetting any associated event object are automatic, such that the next occurrence of a nominated network event will cause the event object to become set. In the case of this function returning SOCKET_ERROR, the associated event object is not reset and the record of network events is not cleared.
The lNetworkEventsmember of the WSANETWORKEVENTSstructure indicates which of the FD_ XXXnetwork events have occurred. The iErrorCodearray is used to contain any associated error codes with the array index corresponding to the position of event bits in lNetworkEvents. Identifiers such as FD_READ_BIT and FD_WRITE_BIT can be used to index the iErrorCodearray. Note that only those elements of the iErrorCodearray are set that correspond to the bits set in lNetworkEventsparameter. Other parameters are not modified, which is important for backward compatibility with the applications that are not aware of new FD_ROUTING_INTERFACE_CHANGE and FD_ADDRESS_LIST_CHANGE events.
The following error codes can be returned along with the corresponding network event.
Event: FD_CONNECT
| Error | Description |
|---|---|
|
WSAEAFNOSUPPORT |
Addresses in the specified family cannot be used with this socket. |
|
WSAECONNREFUSED |
The attempt to connect was forcefully rejected. |
|
WSAENETUNREACH |
The network cannot be reached from this host at this time. |
|
WSAENOBUFS |
No buffer space is available. The socket cannot be connected. |
|
WSAETIMEDOUT |
Attempt to connecttimed out without establishing a connection |
Event: FD_CLOSE
| Error | Description |
|---|---|
|
WSAENETDOWN |
The network subsystem has failed. |
|
WSAECONNRESET |
The connection was reset by the remote side. |
|
WSAECONNABORTED |
The connection was terminated due to a time-out or other failure. |
Event: FD_READ
Event: FD_WRITE
Event: FD_OOB
Event: FD_ACCEPT
Event: FD_ADDRESS_LIST_CHANGE
| Error | Description |
|---|---|
|
WSAENETDOWN |
The network subsystem has failed. |
Event: FD_ROUTING_INTERFACE_CHANGE
| Error | Description |
|---|---|
|
WSAENETUNREACH |
The specified destination is no longer reachable. |
|
WSAENETDOWN |
The network subsystem has failed. |
Requirements
| Header | winsock2.h |
| Library | Ws2.lib |
| Windows Embedded CE | Windows CE .NET 4.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |