Função WSAEnumNetworkEvents (winsock2.h)

Artigo
08/27/2023

A função WSAEnumNetworkEvents descobre ocorrências de eventos de rede para o soquete indicado, limpar registros de eventos de rede internos e redefinir objetos de evento (opcional).

Sintaxe

int WSAAPI WSAEnumNetworkEvents(
  [in]  SOCKET             s,
  [in]  WSAEVENT           hEventObject,
  [out] LPWSANETWORKEVENTS lpNetworkEvents
);

Parâmetros

[in] s

Um descritor que identifica o soquete.

[in] hEventObject

Um identificador opcional que identifica um objeto de evento associado a ser redefinido.

[out] lpNetworkEvents

Um ponteiro para uma estrutura WSANETWORKEVENTS que é preenchida com um registro de eventos de rede que ocorreram e quaisquer códigos de erro associados.

Retornar valor

O valor retornado será zero se a operação tiver sido bem-sucedida. Caso contrário, o valor SOCKET_ERROR será retornado e um número de erro específico poderá ser recuperado chamando WSAGetLastError.

Código do erro	Significado
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSAENETDOWN	O subsistema de rede falhou.
WSAEINVAL	Um dos parâmetros especificados era inválido.
WSAEINPROGRESS	Uma chamada de bloqueio do Windows Sockets 1.1 está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAENOTSOCK	O descritor não é um soquete.
WSAEFAULT	O parâmetro lpNetworkEvents não é uma parte válida do espaço de endereço do usuário.

Comentários

A função WSAEnumNetworkEvents é usada para descobrir quais eventos de rede ocorreram para o soquete indicado desde a última invocação dessa função. Ele destina-se ao uso em conjunto com WSAEventSelect, que associa um objeto de evento a um ou mais eventos de rede. A gravação de eventos de rede começa quando WSAEventSelect é chamado com um parâmetro lNetworkEvents diferente de zero e permanece em vigor até que outra chamada seja feita para WSAEventSelect com o parâmetro lNetworkEvents definido como zero ou até que uma chamada seja feita para WSAAsyncSelect.

O WSAEnumNetworkEvents relata apenas a atividade de rede e os erros indicados por meio de WSAEventSelect. Confira as descrições de select e WSAAsyncSelect para descobrir como essas funções relatam erros e atividades de rede.

O registro interno do soquete de eventos de rede é copiado para a estrutura referenciada por lpNetworkEvents, após a qual o registro de eventos de rede interna é limpo. Se o parâmetro hEventObject não for NULL, o objeto de evento indicado também será redefinido. O provedor do Windows Sockets garante que as operações de copiar o registro de evento de rede, limpá-lo e redefinir qualquer objeto de evento associado sejam atômicas, de modo que a próxima ocorrência de um evento de rede indicado faça com que o objeto de evento seja definido. No caso dessa função retornar SOCKET_ERROR, o objeto de evento associado não é redefinido e o registro de eventos de rede não é limpo.

O membro lNetworkEvents da estrutura WSANETWORKEVENTS indica qual dos eventos de rede FD_XXX ocorreram. A matriz iErrorCode é usada para conter quaisquer códigos de erro associados com o índice de matriz correspondente à posição dos bits de evento em lNetworkEvents. Identificadores como FD_READ_BIT e FD_WRITE_BIT podem ser usados para indexar a matriz iErrorCode . Observe que somente os elementos da matriz iErrorCode são definidos que correspondem aos bits definidos no parâmetro lNetworkEvents . Outros parâmetros não são modificados (isso é importante para compatibilidade com versões anteriores com os aplicativos que não estão cientes de novos eventos de FD_ROUTING_INTERFACE_CHANGE e FD_ADDRESS_LIST_CHANGE).

Os códigos de erro a seguir podem ser retornados junto com o evento de rede correspondente.

Evento: FD_CONNECT

Código do erro	Significado
WSAEAFNOSUPPORT	Os endereços na família especificada não podem ser usados com este soquete.
WSAECONNREFUSED	A tentativa de conexão foi rejeitada de modo forçado.
WSAENETUNREACH	A rede não pode ser alcançada através deste host neste momento.
WSAENOBUFS	Nenhum espaço de buffer disponível. O soquete não pode ser conectado.
WSAETIMEDOUT	Uma tentativa de conexão atingiu o tempo limite sem estabelecer uma conexão

Evento: FD_CLOSE

Código do erro	Significado
WSAENETDOWN	O subsistema de rede falhou.
WSAECONNRESET	A conexão foi redefinida pelo lado remoto.
WSAECONNABORTED	A conexão foi encerrada devido a um tempo limite ou outra falha.

Evento: FD_ACCEPT

Evento: FD_ADDRESS_LIST_CHANGE

Evento: FD_GROUP_QOS

Evento: FD_QOS

Evento: FD_OOB

Evento: FD_READ

Evento: FD_WRITE

Código do erro	Significado
WSAENETDOWN	O subsistema de rede falhou.

Evento: FD_ROUTING_INTERFACE_CHANGE

Código do erro	Significado
WSAENETUNREACH	O destino especificado não é mais acessível.
WSAENETDOWN	O subsistema de rede falhou.

Código de exemplo

O exemplo a seguir demonstra o uso da função WSAEnumNetworkEvents.

#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);
    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: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8.1, Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winsock2.h
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll

Confira também

Wsaeventselect

Funções Winsock

Referência de Winsock

Compartilhar via

Função WSAEnumNetworkEvents (winsock2.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Código de exemplo

Requisitos

Confira também

Comentários

Recursos adicionais