WSAEnumProtocolsA-Funktion (winsock2.h)

Artikel
03/06/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-beendetes 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 die Anzahl der Bytes im lpProtocolBuffer-Puffer , der an WSAEnumProtocols übergeben wird. Bei der Ausgabe die minimale Puffergröße, die an WSAEnumProtocols übergeben werden kann, um alle angeforderten Informationen abzurufen. Diese Routine ist nicht in der Lage, mehrere Aufrufe aufzulisten. Der übergebene Puffer muss groß genug sein, um alle Einträge zu enthalten, damit die Routine erfolgreich ist. Dies reduziert die Komplexität der API und sollte kein Problem darstellen, da die Anzahl der auf einem Computer geladenen Protokolle in der Regel gering ist.

Rückgabewert

Wenn kein Fehler auftritt, gibt WSAEnumProtocols die Anzahl der zu meldenden Protokolle zurück. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode 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.
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 zugehörigen Informationen zu empfangen. Übergeben Sie einen Puffer, der mindestens so groß ist wie der in lpdwBufferLength zurückgegebene Wert.
WSAEFAULT	Mindestens einer der Parameter lpiProtocols, lpProtocolBuffer oder lpdwBufferLength ist kein gültiger Teil des Benutzeradressraums.

Hinweise

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

Hinweis Mehrschichtige Dienstanbieter sind veraltet. Verwenden Sie ab Windows 8 und Windows Server 2012 die Windows-Filterplattform.

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

Die WSAEnumProtocols-Funktion unterscheidet sich von den Funktionen WSCEnumProtocols und WSCEnumProtocols32 darin, dass die WSAEnumProtocols-Funktion nicht WSAPROTOCOL_INFO Strukturen für alle installierten Protokolle zurückgibt. Die WSAEnumProtocols-Funktion schließt Protokolle aus, die der Dienstanbieter mit dem PFL_HIDDEN-Flag im dwProviderFlags-Member der WSAPROTOCOL_INFO-Struktur festgelegt hat, um dem Ws2_32.dll anzuzeigen, dass dieses Protokoll nicht im von der WSAEnumProtocols-Funktion generierten Ergebnispuffer zurückgegeben werden soll. Darüber hinaus gibt die WSAEnumProtocols-Funktion keine Daten für WSAPROTOCOL_INFO Strukturen zurück, die eine Kettenlänge von mindestens einem (LSP-Anbieter) aufweisen. WSAEnumProtocols gibt nur Informationen zu Basisprotokollen und Protokollketten zurück, denen das flag PFL_HIDDEN fehlt und die keine Protokollkettenlänge von 0 (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 jeder nachfolgenden Neuanordnung, die über die Windows Sockets-Anwendung oder DLL zum Einrichten von TCP/IP-Standardanbietern erfolgt ist.

Windows Phone 8: Die WSAEnumProtocolsW-Funktion wird für Windows Phone Store-Apps auf 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 auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Beispiele

Das folgende Beispiel veranschaulicht die Verwendung der WSAEnumProtocols-Funktion zum Abrufen eines Arrays von WSAPROTOCOL_INFO Strukturen für verfügbare Transportprotokolle.

#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;
}

Hinweis

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
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