WSAEnumNetworkEvents-Funktion (winsock2.h)

Artikel
03/04/2024

Die WSAEnumNetworkEvents-Funktion ermittelt Vorkommen von Netzwerkereignissen für den angegebenen Socket, löscht interne Netzwerkereignisdatensätze und setzt Ereignisobjekte zurück (optional).

Syntax

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

Parameter

[in] s

Ein Deskriptor, der den Socket identifiziert.

[in] hEventObject

Ein optionales Handle, das ein zugeordnetes Ereignisobjekt identifiziert, das zurückgesetzt werden soll.

[out] lpNetworkEvents

Ein Zeiger auf eine WSANETWORKEVENTS-Struktur , die mit einem Datensatz der aufgetretenen Netzwerkereignisse und allen zugeordneten Fehlercodes gefüllt ist.

Rückgabewert

Der Rückgabewert ist null, wenn der Vorgang erfolgreich war. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und eine bestimmte Fehlernummer kann durch Aufrufen von WSAGetLastError abgerufen werden.

Fehlercode	Bedeutung
WSANOTINITIALISIERT	Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.
WSAENETDOWN	Fehler beim Netzwerksubsystem.
WSAEINVAL	Einer der angegebenen Parameter war ungültig.
WSAEINPROGRESS	Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet noch eine Rückruffunktion.
WSAENOTSOCK	Der Deskriptor ist kein Socket.
WSAEFAULT	Der parameter lpNetworkEvents ist kein gültiger Teil des Benutzeradressraums.

Hinweise

Die WSAEnumNetworkEvents-Funktion wird verwendet, um zu ermitteln, welche Netzwerkereignisse seit dem letzten Aufruf dieser Funktion für den angegebenen Socket aufgetreten sind. Es ist für die Verwendung in Verbindung mit WSAEventSelect vorgesehen, das ein Ereignisobjekt einem oder mehreren Netzwerkereignissen zuordnet. Die Aufzeichnung von Netzwerkereignissen beginnt, wenn WSAEventSelect mit einem lNetworkEvents-Parameter ungleich null aufgerufen wird, und bleibt wirksam, bis ein weiterer Aufruf von WSAEventSelect erfolgt, wobei der lNetworkEvents-Parameter auf null festgelegt ist, oder bis ein Aufruf von WSAAsyncSelect erfolgt.

WSAEnumNetworkEvents meldet nur Netzwerkaktivitäten und Fehler, die über WSAEventSelect benannt wurden. In den Beschreibungen von select und WSAAsyncSelect erfahren Sie, wie diese Funktionen Netzwerkaktivitäten und Fehler melden.

Der interne Datensatz der Netzwerkereignisse des Sockets wird in die Struktur kopiert, auf die von lpNetworkEvents verwiesen wird, worauf der interne Netzwerkereignisdatensatz gelöscht wird. Wenn der hEventObject-Parameter nicht NULL ist, wird auch das angegebene Ereignisobjekt zurückgesetzt. Der Windows Sockets-Anbieter garantiert, dass die Vorgänge zum Kopieren des Netzwerkereignisdatensatzes, Zum Löschen und Zurücksetzen eines zugeordneten Ereignisobjekts atomar sind, sodass das nächste Vorkommen eines nominierten Netzwerkereignisses dazu führt, dass das Ereignisobjekt festgelegt wird. Im Fall, dass diese Funktion SOCKET_ERROR zurückgibt, wird das zugeordnete Ereignisobjekt nicht zurückgesetzt, und der Datensatz der Netzwerkereignisse wird nicht gelöscht.

Das lNetworkEvents-Element der WSANETWORKEVENTS-Struktur gibt an, welche der FD_XXX Netzwerkereignisse aufgetreten sind. Das iErrorCode-Array wird verwendet, um alle zugeordneten Fehlercodes mit dem Arrayindex zu enthalten, der der Position der Ereignisbits in lNetworkEvents entspricht. Bezeichner wie FD_READ_BIT und FD_WRITE_BIT können zum Indizieren des iErrorCode-Arrays verwendet werden. Beachten Sie, dass nur die Elemente des iErrorCode-Arrays festgelegt sind, die den im lNetworkEvents-Parameter festgelegten Bits entsprechen. Andere Parameter werden nicht geändert (dies ist wichtig für die Abwärtskompatibilität mit anwendungen, die keine neuen FD_ROUTING_INTERFACE_CHANGE und FD_ADDRESS_LIST_CHANGE Ereignisse kennen).

Die folgenden Fehlercodes können zusammen mit dem entsprechenden Netzwerkereignis zurückgegeben werden.

Ereignis: FD_CONNECT

Fehlercode	Bedeutung
WSAEAFNOSUPPORT	Adressen in der angegebenen Adressfamilie können nicht mit diesem Socket verwendet werden.
WSAECONNREFUSED	Die Zurückweisung des Verbindungsversuchs wurde erzwungen.
WSAENETUNREACH	Das Netzwerk kann von diesem Host zurzeit nicht erreicht werden.
WSAENOBUFS	Es ist kein Pufferplatz verfügbar. Der Socket kann nicht verbunden werden.
WSAETIMEDOUT	Zeitüberschreitung beim Verbindungsversuch, ohne eine Verbindung herzustellen

Ereignis: FD_CLOSE

Fehlercode	Bedeutung
WSAENETDOWN	Fehler beim Netzwerksubsystem.
WSAECONNRESET	Die Verbindung wurde von der Remoteseite zurückgesetzt.
WSAECONNABORTED	Die Verbindung wurde aufgrund eines Timeouts oder eines anderen Fehlers beendet.

Ereignis: FD_ACCEPT

Ereignis: FD_ADDRESS_LIST_CHANGE

Ereignis: FD_GROUP_QOS

Ereignis: FD_QOS

Ereignis: FD_OOB

Ereignis: FD_READ

Ereignis: FD_WRITE

Fehlercode	Bedeutung
WSAENETDOWN	Fehler beim Netzwerksubsystem.

Ereignis: FD_ROUTING_INTERFACE_CHANGE

Fehlercode	Bedeutung
WSAENETUNREACH	Das angegebene Ziel ist nicht mehr erreichbar.
WSAENETDOWN	Fehler beim Netzwerksubsystem.

Beispielcode

Im folgenden Beispiel wird die Verwendung der WSAEnumNetworkEvents-Funktion veranschaulicht.

#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: Diese Funktion wird für Windows Phone Store-Apps ab Windows Phone 8 unterstützt.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winsock2.h
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll

Weitere Informationen

WSAEventSelect

Winsock-Funktionen

Winsock-Referenz

Freigeben über