Funzione WSAEnumNetworkEvents (winsock2.h)

Articolo
08/27/2023

La funzione WSAEnumNetworkEvents individua le occorrenze degli eventi di rete per il socket indicato, cancella i record degli eventi di rete interni e reimposta gli oggetti evento (facoltativo).

Sintassi

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

Parametri

[in] s

Descrittore che identifica il socket.

[in] hEventObject

Handle facoltativo che identifica un oggetto evento associato da reimpostare.

[out] lpNetworkEvents

Puntatore a una struttura WSANETWORKEVENTS compilata con un record di eventi di rete che si sono verificati ed eventuali codici di errore associati.

Valore restituito

Il valore restituito è zero se l'operazione ha avuto esito positivo. In caso contrario, viene restituito il valore SOCKET_ERROR e è possibile recuperare un numero di errore specifico chiamando WSAGetLastError.

Codice di errore	Significato
WSANOTINITIALISED	Prima di usare questa funzione, è necessario che venga eseguita una chiamata WSAStartup riuscita.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEINVAL	Uno dei parametri specificati non è valido.
WSAEINPROGRESS	È in corso una chiamata di Windows Sockets 1.1 bloccante oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAENOTSOCK	Il descrittore non è un socket.
WSAEFAULT	Il parametro lpNetworkEvents non è una parte valida dello spazio indirizzi utente.

Commenti

La funzione WSAEnumNetworkEvents viene usata per individuare gli eventi di rete che si sono verificati per il socket indicato dall'ultima chiamata di questa funzione. È destinato all'uso in combinazione con WSAEventSelect, che associa un oggetto evento a uno o più eventi di rete. La registrazione degli eventi di rete inizia quando WSAEventSelect viene chiamato con un parametro nonzero lNetworkEvents e rimane attivo fino a quando non viene eseguita un'altra chiamata a WSAEventSelect con il parametro lNetworkEvents impostato su zero o fino a quando non viene effettuata una chiamata a WSAAsyncSelect.

WSAEnumNetworkEvents segnala solo le attività di rete e gli errori designati tramite WSAEventSelect. Vedere le descrizioni di select e WSAAsyncSelect per scoprire in che modo tali funzioni segnalano le attività e gli errori di rete.

Il record interno del socket degli eventi di rete viene copiato nella struttura a cui fa riferimento lpNetworkEvents, dopo il quale il record degli eventi di rete interna viene cancellato. Se il parametro hEventObject non è NULL, viene reimpostato anche l'oggetto evento indicato. Il provider Windows Sockets garantisce che le operazioni di copia del record dell'evento di rete, la cancellazione e la reimpostazione di qualsiasi oggetto evento associato siano atomiche, in modo che l'occorrenza successiva di un evento di rete designato provocherà l'impostazione dell'oggetto evento. Nel caso di questa funzione che restituisce SOCKET_ERROR, l'oggetto evento associato non viene reimpostato e il record degli eventi di rete non viene cancellato.

Il membro lNetworkEvents della struttura WSANETWORKEVENTS indica quale degli eventi di rete FD_XXX si sono verificati. La matrice iErrorCode viene usata per contenere eventuali codici di errore associati con l'indice di matrice corrispondente alla posizione dei bit dell'evento in lNetworkEvents. È possibile usare identificatori come FD_READ_BIT e FD_WRITE_BIT per indicizzare la matrice iErrorCode . Si noti che solo gli elementi della matrice iErrorCode sono impostati che corrispondono ai bit impostati nel parametro lNetworkEvents . Gli altri parametri non vengono modificati (questo è importante per la compatibilità con le versioni precedenti con le applicazioni che non sono a conoscenza di nuovi FD_ROUTING_INTERFACE_CHANGE e FD_ADDRESS_LIST_CHANGE eventi).

I codici di errore seguenti possono essere restituiti insieme all'evento di rete corrispondente.

Evento: FD_CONNECT

Codice di errore	Significato
WSAEAFNOSUPPORT	Impossibile utilizzare gli indirizzi della famiglia specificata con questo socket.
WSAECONNREFUSED	Il tentativo di connessione è stato respinto in modo forzato.
WSAENETUNREACH	Impossibile raggiungere la rete da questo host in questo momento.
WSAENOBUFS	Nessuno spazio di buffer disponibile. Il socket non può essere connesso.
WSAETIMEDOUT	Tentativo di connessione timeout senza stabilire una connessione

Evento: FD_CLOSE

Codice di errore	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAECONNRESET	La connessione è stata reimpostata dal lato remoto.
WSAECONNABORTED	La connessione è stata terminata a causa di un timeout o di un altro errore.

Evento: FD_ACCEPT

Evento: FD_ADDRESS_LIST_CHANGE

Evento: FD_GROUP_QOS

Evento: FD_QOS

Evento: FD_OOB

Evento: FD_READ

Evento: FD_WRITE

Codice di errore	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.

Evento: FD_ROUTING_INTERFACE_CHANGE

Codice di errore	Significato
WSAENETUNREACH	La destinazione specificata non è più raggiungibile.
WSAENETDOWN	Il sottosistema di rete non è riuscito.

Codice di esempio

Nell'esempio seguente viene illustrato l'uso della funzione 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: questa funzione è supportata per le app dello Store di Windows Phone in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock2.h
Libreria	Ws2_32.lib
DLL	Ws2_32.dll

Vedi anche

WSAEventSelect

Funzioni Winsock

Informazioni di riferimento su Winsock

Condividi tramite