WSAEnumProtocolsA-Funktion (winsock2.h)

Artikel
11/20/2024

Die WSAEnumProtocols Funktion ruft Informationen zu verfügbaren Transportprotokollen ab.

Syntax

int WSAAPI WSAEnumProtocolsA(
  [in]      LPINT               lpiProtocols,
  [out]     LPWSAPROTOCOL_INFOA lpProtocolBuffer,
  [in, out] LPDWORD             lpdwBufferLength
);

Parameter

[in] lpiProtocols

Ein NULL--terminated array von iProtocol-Werten. Dieser Parameter ist optional; wenn lpiProtocolsNULL-ist, werden Informationen zu allen verfügbaren Protokollen zurückgegeben. Andernfalls werden Informationen nur für die im Array aufgeführten Protokolle abgerufen.

[out] lpProtocolBuffer

Ein Zeiger auf einen Puffer, der mit WSAPROTOCOL_INFO Strukturen gefüllt ist.

[in, out] lpdwBufferLength

Bei der Eingabe wird die Anzahl der Bytes im lpProtocolBuffer Puffer an WSAEnumProtocolsübergeben. Bei der Ausgabe kann die minimale Puffergröße, die an WSAEnumProtocols übergeben werden kann,, um alle angeforderten Informationen abzurufen. Diese Routine hat keine Möglichkeit, mehrere Anrufe aufzählen zu können; Der übergebene Puffer muss groß genug sein, um alle Einträge aufzunehmen, damit die Routine erfolgreich ausgeführt werden kann. Dies verringert die Komplexität der API und sollte kein Problem darstellen, da die Anzahl der auf einem Computer geladenen Protokolle in der Regel klein ist.

Rückgabewert

Wenn kein Fehler auftritt, gibt WSAEnumProtocols die Anzahl der zu meldenden Protokolle zurück. Andernfalls wird ein Wert von SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann abgerufen werden, indem WSAGetLastErroraufgerufen wird.

Fehlercode	Bedeutung
WSANOTINITIALISIERT	Ein erfolgreicher WSAStartup Aufrufs muss erfolgen, bevor diese Funktion verwendet wird.
WSAENETDOWN-	Fehler des Netzwerksubsystems.
WSAEINPROGRESS-	Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt.
WSAEINVAL-	Gibt an, dass einer der angegebenen Parameter ungültig war.
WSAENOBUFS	Die Pufferlänge war zu klein, um alle relevanten WSAPROTOCOL_INFO Strukturen und zugeordneten Informationen zu empfangen. Übergeben Sie einen Puffer mindestens so groß wie der in lpdwBufferLengthzurückgegebene Wert.
WSAEFAULT-	Mindestens einer der lpiProtocols, lpProtocolBufferoder lpdwBufferLength Parameter sind kein gültiger Teil des Benutzeradressraums.

Bemerkungen

Die WSAEnumProtocols--Funktion wird verwendet, um Informationen zur Sammlung der auf dem lokalen Computer installierten Transportprotokolle zu ermitteln. Layered-Protokolle können nur von Anwendungen verwendet werden, wenn sie in Protokollketten installiert werden. Informationen zu mehrschichtigen Protokollen werden nicht zurückgegeben, mit Ausnahme aller Dummy Layered Service Providers (LSPs), die mit einer Kettenlänge von Null in der lpProtocolBufferinstalliert sind.

Hinweis Anbieter von Layered Service Providers veraltet sind. Verwenden Sie ab Windows 8 und Windows Server 2012 Windows-Filterplattform.

Der lpiProtocols Parameter kann als Filter verwendet werden, um die menge der bereitgestellten Informationen einzuschränken. Häufig werden lpiProtocols als NULL- zeiger angegeben, der dazu führt, dass die Funktion Informationen zu allen verfügbaren Transportprotokollen und Protokollketten zurückgibt.

Die funktion WSAEnumProtocols unterscheidet sich von der WSCEnumProtocols und WSCEnumProtocols32 funktionen darin, dass die WSAEnumProtocols--Funktion keine WSAPROTOCOL_INFO Strukturen für alle installierten Protokolle zurückgibt. Die WSAEnumProtocols--Funktion schließt Protokolle aus, die der Dienstanbieter mit dem Flag PFL_HIDDEN im dwProviderFlags Member der WSAPROTOCOL_INFO Struktur festgelegt hat, um Ws2_32.dll anzugeben, dass dieses Protokoll nicht im Ergebnispuffer zurückgegeben werden sollte, der von WSAEnumProtocols Funktion generiert wurde. Darüber hinaus gibt die WSAEnumProtocols--Funktion keine Daten für WSAPROTOCOL_INFO Strukturen zurück, die eine Kettenlänge eines oder mehrerer (LSP-Anbieter) aufweisen. Die WSAEnumProtocols nur Informationen zu Basisprotokollen und Protokollketten zurück, die nicht das PFL_HIDDEN Flag aufweisen und keine Protokollkettenlänge von Null aufweisen.

Eine WSAPROTOCOL_INFO Struktur wird im Puffer bereitgestellt, auf den lpProtocolBuffer für jedes angeforderte Protokoll verweist. Wenn der angegebene Puffer nicht groß genug ist (wie durch den Eingabewert von lpdwBufferLength angegeben), wird der Wert aktualisiert, auf den lpdwBufferLength verweist, um die erforderliche Puffergröße anzugeben. Die Anwendung sollte dann einen ausreichend großen Puffer abrufen und WSAEnumProtocols erneut aufrufen.

Die Reihenfolge, in der die WSAPROTOCOL_INFO Strukturen im Puffer angezeigt werden, stimmt mit der Reihenfolge überein, in der die Protokolleinträge vom Dienstanbieter mithilfe der WS2_32.DLL registriert wurden, oder mit einer nachfolgenden Neuanordnung, die über die Windows Sockets-Anwendung oder DLL für die Einrichtung von Standard-TCP/IP-Anbietern bereitgestellt wurde.

Windows Phone 8: Die WSAEnumProtocolsW--Funktion wird für Windows Phone Store-Apps unter Windows Phone 8 und höher unterstützt.

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

Beispiele

Im folgenden Beispiel wird die Verwendung der WSAEnumProtocols Funktion veranschaulicht, um ein Array von WSAPROTOCOL_INFO Strukturen für verfügbare Transportprotokolle abzurufen.

#ifndef UNICODE
#define UNICODE 1
#endif

#include <winsock2.h>
#include <ws2tcpip.h>
#include <objbase.h>
#include <stdio.h>

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

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))
// Note: could also use malloc() and free()

int wmain()
{

    //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData;
    int iResult = 0;

    int iError = 0;
    INT iNuminfo = 0;

    int i;

    // Allocate a 16K buffer to retrieve all the protocol providers
    DWORD dwBufferLen = 16384;

    LPWSAPROTOCOL_INFO lpProtocolInfo = NULL;

    // variables needed for converting provider GUID to a string
    int iRet = 0;
    WCHAR GuidString[40] = { 0 };

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

    lpProtocolInfo = (LPWSAPROTOCOL_INFO) MALLOC(dwBufferLen);
    if (lpProtocolInfo == NULL) {
        wprintf(L"Memory allocation for providers buffer failed\n");
        WSACleanup();
        return 1;
    }

    iNuminfo = WSAEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen);
    if (iNuminfo == SOCKET_ERROR) {
        iError = WSAGetLastError();
        if (iError != WSAENOBUFS) {
            wprintf(L"WSAEnumProtocols failed with error: %d\n", iError);
            if (lpProtocolInfo) {
                FREE(lpProtocolInfo);
                lpProtocolInfo = NULL;
            }
            WSACleanup();
            return 1;
        } else {
            wprintf(L"WSAEnumProtocols failed with error: WSAENOBUFS (%d)\n",
                    iError);
            wprintf(L"  Increasing buffer size to %d\n\n", dwBufferLen);
            if (lpProtocolInfo) {
                FREE(lpProtocolInfo);
                lpProtocolInfo = NULL;
            }
            lpProtocolInfo = (LPWSAPROTOCOL_INFO) MALLOC(dwBufferLen);
            if (lpProtocolInfo == NULL) {
                wprintf(L"Memory allocation increase for buffer failed\n");
                WSACleanup();
                return 1;
            }
            iNuminfo = WSAEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen);
            if (iNuminfo == SOCKET_ERROR) {
                iError = WSAGetLastError();
                wprintf(L"WSAEnumProtocols failed with error: %d\n", iError);
                if (lpProtocolInfo) {
                    FREE(lpProtocolInfo);
                    lpProtocolInfo = NULL;
                }
                WSACleanup();
                return 1;
            }

        }
    }

    wprintf(L"WSAEnumProtocols succeeded with protocol count = %d\n\n",
            iNuminfo);
    for (i = 0; i < iNuminfo; i++) {
        wprintf(L"Winsock Catalog Provider Entry #%d\n", i);
        wprintf
            (L"----------------------------------------------------------\n");
        wprintf(L"Entry type:\t\t\t ");
        if (lpProtocolInfo[i].ProtocolChain.ChainLen == 1)
            wprintf(L"Base Service Provider\n");
        else
            wprintf(L"Layered Chain Entry\n");

        wprintf(L"Protocol:\t\t\t %ws\n", lpProtocolInfo[i].szProtocol);

        iRet =
            StringFromGUID2(lpProtocolInfo[i].ProviderId,
                            (LPOLESTR) & GuidString, 39);
        if (iRet == 0)
            wprintf(L"StringFromGUID2 failed\n");
        else
            wprintf(L"Provider ID:\t\t\t %ws\n", GuidString);

        wprintf(L"Catalog Entry ID:\t\t %u\n",
                lpProtocolInfo[i].dwCatalogEntryId);

        wprintf(L"Version:\t\t\t %d\n", lpProtocolInfo[i].iVersion);

        wprintf(L"Address Family:\t\t\t %d\n",
                lpProtocolInfo[i].iAddressFamily);
        wprintf(L"Max Socket Address Length:\t %d\n",
                lpProtocolInfo[i].iMaxSockAddr);
        wprintf(L"Min Socket Address Length:\t %d\n",
                lpProtocolInfo[i].iMinSockAddr);

        wprintf(L"Socket Type:\t\t\t %d\n", lpProtocolInfo[i].iSocketType);
        wprintf(L"Socket Protocol:\t\t %d\n", lpProtocolInfo[i].iProtocol);
        wprintf(L"Socket Protocol Max Offset:\t %d\n",
                lpProtocolInfo[i].iProtocolMaxOffset);

        wprintf(L"Network Byte Order:\t\t %d\n",
                lpProtocolInfo[i].iNetworkByteOrder);
        wprintf(L"Security Scheme:\t\t %d\n",
                lpProtocolInfo[i].iSecurityScheme);
        wprintf(L"Max Message Size:\t\t %u\n", lpProtocolInfo[i].dwMessageSize);

        wprintf(L"ServiceFlags1:\t\t\t 0x%x\n",
                lpProtocolInfo[i].dwServiceFlags1);
        wprintf(L"ServiceFlags2:\t\t\t 0x%x\n",
                lpProtocolInfo[i].dwServiceFlags2);
        wprintf(L"ServiceFlags3:\t\t\t 0x%x\n",
                lpProtocolInfo[i].dwServiceFlags3);
        wprintf(L"ServiceFlags4:\t\t\t 0x%x\n",
                lpProtocolInfo[i].dwServiceFlags4);
        wprintf(L"ProviderFlags:\t\t\t 0x%x\n",
                lpProtocolInfo[i].dwProviderFlags);

        wprintf(L"Protocol Chain length:\t\t %d\n",
                lpProtocolInfo[i].ProtocolChain.ChainLen);

        wprintf(L"\n");
    }

    if (lpProtocolInfo) {
        FREE(lpProtocolInfo);
        lpProtocolInfo = NULL;
    }
    WSACleanup();

    return 0;
}

Anmerkung

Der winsock2.h-Header definiert WSAEnumProtocols als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	winsock2.h
Library	Ws2_32.lib
DLL-	Ws2_32.dll