WSAEnumProtocolsA-Funktion (winsock2.h)
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 |
|---|---|
| Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen. | |
| Fehler beim Netzwerksubsystem. | |
| Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt. | |
| Gibt an, dass einer der angegebenen Parameter ungültig war. | |
| 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. | |
| 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.
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 |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für