WSAEnumNetworkEvents

WSAEnumNetworkEvents function

The WSAEnumNetworkEvents function discovers occurrences of network events for the indicated socket, clear internal network event records, and reset event objects (optional).这个函数为指定的套接字查看已发生的网络事件，清理网络事件的记录，然后重置事件对象（可选）。

Syntax

C++

int WSAEnumNetworkEvents(
  _In_   SOCKET s,
  _In_   WSAEVENT hEventObject,
  _Out_  LPWSANETWORKEVENTS lpNetworkEvents
);

Parameters

s [in]

A descriptor identifying the socket.套接字。

hEventObject [in]

An optional handle identifying an associated event object to be reset.一个想要被重置的相关事件句柄，这个参数是可选的。

lpNetworkEvents [out]

A pointer to a WSANETWORKEVENTS structure that is filled with a record of network events that occurred and any associated error codes.一个指向WSANETWORKEVENTS结构体的指针，里面填充了已发生的网络事件和相关的错误码。

Return value

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by callingWSAGetLastError.成功返回0。否则返回SOCKET_ERROR，通过调用WSAGetLastError可以得到具体的错误码。

Error code	Meaning
WSANOTINITIALISED	A successful WSAStartup call must occur before using this function.未初始化。
WSAENETDOWN	The network subsystem has failed.网络子系统失败。
WSAEINVAL	One of the specified parameters was invalid.参数错误。
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.调用了一个属于1.1版的阻塞函数，或者服务提供者仍旧在处理回调函数。
WSAENOTSOCK	The descriptor is not a socket.非套接字。
WSAEFAULT	The lpNetworkEvents parameter is not a valid part of the user address space.lpNetworkEvents参数不在用户的地址空间内。

 

Remarks

The WSAEnumNetworkEvents 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 withWSAEventSelect, which associates an event object with one or more network events. The recording of network events commences whenWSAEventSelect is called with a nonzerolNetworkEvents parameter and remains in effect until another call is made toWSAEventSelect with the lNetworkEvents parameter set to zero, or until a call is made to WSAAsyncSelect.这个函数用于发现自上次调用本函数后，关联的套接字已发生的网络事件。本函数的目的是配合WSAEventSelect使用，后者将一个事件对象同一个或者多个网络事件关联在一起。当以一个非0的lNetworkEvents参数调用WSAEventSelect函数时，就会开始记录网络事件，并且一直有效，除非再次以0为参数调用WSAEventSelect，或者调用WSAAsyncSelect。

WSAEnumNetworkEvents only reports network activity and errors nominated throughWSAEventSelect. See the descriptions of select and WSAAsyncSelect to find out how those functions report network activity and errors.本函数仅报告由WSAEventSelect函数指定的网络活动和错误。具体参数见select和WSAAsyncSelect函数的描述。

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 thehEventObject parameter 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 atomic, 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.当内部网络事件记录被清除的时候，套接字的内部网络事件记录被复制在lpNetworkEvents中。如果hEventObject参数不为NULL，指定的事件对象会被重置。Windows Sockets提供者确保复制及清理网络事件记录、重置相关的事件对象都是原子操作，所以，接下来发生的网络事件会设置事件对象。假如函数返回的是SOCKET_ERROR，那么相关的事件对象不会被重置，记录也不会清除。

The lNetworkEvents member of the WSANETWORKEVENTS structure indicates which of the FD_XXX network events have occurred. The iErrorCode array 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 iErrorCode array. Note that only those elements of the iErrorCode array are set that correspond to the bits set  in lNetworkEvents parameter. Other parameters are not modified (this is important for backward compatibility with the applications that are not aware of new FD_ROUTING_INTERFACE_CHANGE and FD_ADDRESS_LIST_CHANGE events).WSANETWORKEVENTS结构体的lNetworkEvents成员，表示已发生的FD_XXX事件。iErrorCode数组用于存储对应到lNetworkEvents比特位相关位置的错误码。类似于FD_READ和FD_WRITE_BIT的标识符可以用于表示iErrorCode数组的下标。请注意，iErrorCode数组中，只有那些在关联的lNetworkEvents的比特位中已经设置的那些元素才会被设置。（大致就是只有在A中设置过的，才会在B中设置。）

The following error codes can be returned along with the corresponding network event.下面是相关的网络事件会返回的错误码。

Event: FD_CONNECT

Error code	Meaning
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	An attempt to connect timed out without establishing a connection

 

Event: FD_CLOSE

Error code	Meaning
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_ACCEPT

Event: FD_ADDRESS_LIST_CHANGE

Event: FD_GROUP_QOS

Event: FD_QOS

Event: FD_OOB

Event: FD_READ

Event: FD_WRITE

Error code	Meaning
WSAENETDOWN	The network subsystem has failed.

 

Event: FD_ROUTING_INTERFACE_CHANGE

Error code	Meaning
WSAENETUNREACH	The specified destination is no longer reachable.
WSAENETDOWN	The network subsystem has failed.

 

Example Code

The following example demonstrates the use of the WSAEnumNetworkEvents function.下面的例子展示了函数的用法。

C++

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <windows.h>

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

int main()
{
//-------------------------
// Declare and initialize variables
    WSADATA wsaData;
    int iResult;

    SOCKET SocketArray[WSA_MAXIMUM_WAIT_EVENTS], ListenSocket;
    WSAEVENT EventArray[WSA_MAXIMUM_WAIT_EVENTS];
    WSANETWORKEVENTS NetworkEvents;
    sockaddr_in InetAddr;
    DWORD EventTotal = 0;
    DWORD Index;
    DWORD i;
    
    HANDLE NewEvent = NULL; 

    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        wprintf(L"WSAStartup failed with error: %d\n", iResult);
        return 1;
    }

//-------------------------
// Create a listening socket
    ListenSocket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (ListenSocket == INVALID_SOCKET) {
        wprintf(L"socket function failed with error: %d\n", WSAGetLastError() );
        return 1;
    }
    
    InetAddr.sin_family = AF_INET;
    InetAddr.sin_addr.s_addr = htonl(INADDR_ANY);
    InetAddr.sin_port = htons(27015);

//-------------------------
// Bind the listening socket
    iResult = bind(ListenSocket, (SOCKADDR *) & InetAddr, sizeof (InetAddr));
    if (iResult != 0) {
        wprintf(L"bind failed with error: %d\n", WSAGetLastError() );
        return 1;
    }

//-------------------------
// Create a new event
    NewEvent = WSACreateEvent();
    if (NewEvent == NULL) {
        wprintf(L"WSACreateEvent failed with error: %d\n", GetLastError() );
        return 1;
    }    

//-------------------------
// Associate event types FD_ACCEPT and FD_CLOSE
// with the listening socket and NewEvent
    iResult = WSAEventSelect(ListenSocket, NewEvent, FD_ACCEPT | FD_CLOSE);
    if (iResult != 0) {
        wprintf(L"WSAEventSelect failed with error: %d\n", WSAGetLastError() );
        return 1;
    }

//-------------------------
// Start listening on the socket
    iResult = listen(ListenSocket, 10);
    if (iResult != 0) {
        wprintf(L"listen failed with error: %d\n", WSAGetLastError() );
        return 1;
    }

//-------------------------
// Add the socket and event to the arrays, increment number of events
    SocketArray[EventTotal] = ListenSocket;
    EventArray[EventTotal] = NewEvent;
    EventTotal++;

//-------------------------
// Wait for network events on all sockets
    Index = WSAWaitForMultipleEvents(EventTotal, EventArray, FALSE, WSA_INFINITE, FALSE);//看API解释，返回的是众多中最小的那一个
    Index = Index - WSA_WAIT_EVENT_0;

//-------------------------
// Iterate through all events and enumerate
// if the wait does not fail.
    for (i = Index; i < EventTotal; i++) {
        Index = WSAWaitForMultipleEvents(1, &EventArray[i], TRUE, 1000, FALSE);
        if ((Index != WSA_WAIT_FAILED) && (Index != WSA_WAIT_TIMEOUT)) {
            WSAEnumNetworkEvents(SocketArray[i], EventArray[i], &NetworkEvents);
        }
    }

//...
    return 0;

Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Requirements

Minimum supported client	Windows 8.1, Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Minimum supported phone	Windows Phone 8
Header	Winsock2.h
Library	Ws2_32.lib
DLL	Ws2_32.dll

See also

Winsock Reference

Winsock Functions

WSAEventSelect