WSCEnumProtocols-Funktion (ws2spi.h)
Die WSCEnumProtocols-Funktion ruft Informationen zu verfügbaren Transportprotokollen ab.
Syntax
int WSCEnumProtocols(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOW lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength,
[out] LPINT lpErrno
);
Parameter
[in] lpiProtocols
Ein NULL-beendetes Array von iProtocol-Werten . Dieser Parameter ist optional. Wenn lpiProtocols NULL 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_INFOW Strukturen gefüllt ist.
[in, out] lpdwBufferLength
Bei der Eingabe die Größe des an WSCEnumProtoProtocols übergebenen Puffers lpProtocols in Byte. Bei der Ausgabe die minimale Puffergröße in Bytes, die an WSCEnumProtocols übergeben werden kann, um alle angeforderten Informationen abzurufen.
[out] lpErrno
Ein Zeiger auf den Fehlercode.
Rückgabewert
Wenn kein Fehler auftritt, gibt WSCEnumProtocols die Anzahl der Protokolle zurück, für die gemeldet werden soll. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode ist in lpErrno verfügbar.
| Fehlercode | Bedeutung |
|---|---|
| Eines von mehreren Argumenten befindet sich nicht in einem gültigen Teil des Benutzeradressraums. | |
| 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 erhalten. Übergeben Sie einen Puffer, der mindestens so groß ist wie der in lpdwBufferLength zurückgegebene Wert. |
Hinweise
Die WSCEnumProtocols-Funktion wird verwendet, um Informationen zur Sammlung von Transportprotokollen zu ermitteln, die auf dem lokalen Computer installiert sind. Diese Funktion unterscheidet sich von ihrer API-Entsprechung (WSAEnumProtocols), da WSAPROTOCOL_INFOW Strukturen für alle installierten Protokolle zurückgegeben werden. Dies schließt Protokolle ein, in denen der Dienstanbieter das PFL_HIDDEN-Flag im dwProviderFlags-Member der WSAPROTOCOL_INFOW-Struktur festgelegt hat, um dem Ws2_32.dll anzugeben, dass dieses Protokoll nicht im von der WSAEnumProtocols-Funktion generierten Ergebnispuffer zurückgegeben werden soll. Darüber hinaus gibt WSCEnumProtocols auch Daten für WSAPROTOCOL_INFOW Strukturen mit einer Kettenlänge von 0 (einem Dummy-LSP-Anbieter) zurück. 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_INFOW-Struktur wird im Puffer bereitgestellt, auf den lpProtocolBuffer für jedes angeforderte Protokoll verweist. Wenn der bereitgestellte Puffer nicht groß genug ist (wie durch den Eingabewert von lpdwBufferLength angegeben), wird der Wert aktualisiert, auf den von lpdwBufferLength verwiesen wird, um die erforderliche Puffergröße anzugeben. Der SPI-Client von Windows Sockets sollte dann einen ausreichend großen Puffer abrufen und diese Funktion erneut aufrufen. Die WSCEnumProtocols-Funktion kann nicht über mehrere Aufrufe aufzählen. Der übergebene Puffer muss groß genug sein, um alle erwarteten Einträge zu enthalten, damit die Funktion erfolgreich ist. Dies reduziert die Komplexität der Funktion und sollte kein Problem darstellen, da die Anzahl der auf einem lokalen Computer geladenen Protokolle in der Regel gering ist.
Die Reihenfolge, in der die WSAPROTOCOL_INFOW-Strukturen im Puffer angezeigt werden, fällt mit der Reihenfolge zusammen, in der die Protokolleinträge vom Dienstanbieter mit dem WS2_32.dll registriert wurden, oder mit jeder nachfolgenden Neuanordnung, die möglicherweise über das Windows Sockets-Applet erfolgt ist, das zum Einrichten von Standardtransportanbietern bereitgestellt wurde.
Beispiele
Das folgende Beispiel veranschaulicht die Verwendung der WSCEnumProtocols-Funktion zum Abrufen eines Arrays von WSAPROTOCOL_INFOW Strukturen für Protokolle, die auf dem lokalen Computer installiert sind.
#ifndef UNICODE
#define UNICODE 1
#endif
#include <winsock2.h>
#include <ws2tcpip.h>
#include <ws2spi.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 iNuminfo = 0;
int i;
// Allocate a 16K buffer to retrieve all the protocol providers
DWORD dwBufferLen = 16384;
LPWSAPROTOCOL_INFOW lpProtocolInfo = NULL;
int iErrno = 0;
// 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_INFOW) MALLOC(dwBufferLen);
if (lpProtocolInfo == NULL) {
wprintf(L"Memory allocation for providers buffer failed\n");
WSACleanup();
return 1;
}
iNuminfo = WSCEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
if (iErrno != WSAENOBUFS) {
wprintf(L"WSCEnumProtocols failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
} else {
wprintf(L"WSCEnumProtocols failed with error: WSAENOBUFS (%d)\n",
iErrno);
wprintf(L" Increasing buffer size to %d\n\n", dwBufferLen);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
lpProtocolInfo = (LPWSAPROTOCOL_INFOW) MALLOC(dwBufferLen);
if (lpProtocolInfo == NULL) {
wprintf(L"Memory allocation increase for buffer failed\n");
WSACleanup();
return 1;
}
iNuminfo =
WSCEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
wprintf(L"WSCEnumProtocols failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
}
}
}
wprintf(L"WSCEnumProtocols 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;
}
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | ws2spi.h |
| Bibliothek | Ws2_32.lib |
| DLL | Ws2_32.dll |