WSAEnumProtocolsA 函式 (winsock2.h)
WSAEnumProtocols 函式會擷取可用傳輸通訊協議的相關信息。
語法
int WSAAPI WSAEnumProtocolsA(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOA lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength
);
參數
[in] lpiProtocols
iProtocol 值的 NULL 終止陣列。 此參數是選擇性的;如果 lpiProtocols 為 NULL，則會傳回所有可用通訊協議的相關信息。 否則，只會針對陣列出的通訊協定擷取資訊。
[out] lpProtocolBuffer
已填入 WSAPROTOCOL_INFO 結構的緩衝區指標。
[in, out] lpdwBufferLength
在輸入時，傳遞至 WSAEnumProtocols 之 lpProtocolBuffer 緩衝區中的位元組數目。 在輸出時，可以傳遞至 WSAEnumProtocols 的最小緩衝區大小，以擷取所有要求的資訊。 此例程無法列舉多個呼叫;傳入的緩衝區必須夠大，才能保存所有專案，才能讓例程成功。 這可減少 API 的複雜度，而且不應該造成問題，因為計算機上載入的通訊協定數目通常很小。
傳回值
如果未發生任何錯誤， WSAEnumProtocols 會 傳回要報告的通訊協議數目。 否則，會傳回SOCKET_ERROR的值，並呼叫 WSAGetLastError 來擷取特定的錯誤碼。
| 錯誤碼 | 意義 |
|---|---|
| 使用這個函式之前，必須先進行成功的 WSAStartup 呼叫。 | |
| 網路子系統失敗。 | |
| 正在封鎖 Windows Sockets 1.1 呼叫。 | |
| 表示其中一個指定的參數無效。 | |
| 緩衝區長度太小，無法接收所有相關 WSAPROTOCOL_INFO 結構和相關信息。 至少傳入緩衝區，與 lpdwBufferLength 中傳回的值一樣大。 | |
| 一或多個 lpiProtocols、 lpProtocolBuffer 或 lpdwBufferLength 參數不是使用者位址空間的有效部分。 |
備註
WSAEnumProtocols 函式可用來探索本機計算機上安裝之傳輸通訊協定集合的相關信息。 在通訊協定鏈結中安裝時，只有應用程式才能使用分層通訊協定。 除了 lpProtocolBuffer 中以零鏈結長度安裝之 LSP 的任何虛擬分層服務提供者 (以外，不會傳回分層通訊協議的資訊) 。
WSAEnumProtocols 函式與 WSCEnumProtocols 和 WSCEnumProtocols32 函式不同，WSAEnumProtocols 函式不會傳回所有已安裝通訊協定的WSAPROTOCOL_INFO結構。 WSAEnumProtocols 函式會排除服務提供者在 WSAPROTOCOL_INFO 結構的dwProviderFlags 成員中，使用 PFL_HIDDEN 旗標設定的通訊協定，以向 Ws2_32.dll 指出 WSAEnumProtocols 函式所產生的結果緩衝區中不應傳回此通訊協定。 此外， WSAEnumProtocols 函式不會傳回鏈結長度為一或更大 (LSP 提供者) 之 WSAPROTOCOL_INFO 結構的數據。 WSAEnumProtocols 只會傳回缺少PFL_HIDDEN旗標且沒有通訊協定鏈結長度為零的基礎通訊協定和通訊協定鏈結資訊。
每個要求通訊協定的 lpProtocolBuffer 指向的緩衝區中會提供WSAPROTOCOL_INFO結構。 如果指定的緩衝區不夠大， (，如 lpdwBufferLength ) 的輸入值所指示， 則會更新 lpdwBufferLength 所指向的值，以指出所需的緩衝區大小。 然後，應用程式應該會取得夠大的緩衝區，並再次呼叫 WSAEnumProtocols 。
緩衝區中 出現WSAPROTOCOL_INFO 結構的順序與服務提供者使用 WS2_32.DLL 註冊通訊協定專案的順序，或是透過 Windows Sockets 應用程式或為建立預設 TCP/IP 提供者所提供的任何後續重新排列順序一致。
Windows Phone 8：Windows Phone 8 和更新版本上的 Windows Phone Store 應用程式支援 WSAEnumProtocolsW 函式。
Windows 8.1 和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 和更新版本的 Windows 市集應用程式支援 WSAEnumProtocolsW 函式。
範例
下列範例示範如何使用 WSAEnumProtocols 函式來擷取可用傳輸通訊協定 的WSAPROTOCOL_INFO 結構數位。
#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;
}
注意
winsock2.h 標頭會根據 UNICODE 預處理器常數的定義，將 WSAEnumProtocols 定義為別名，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 8.1、Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | winsock2.h |
| 程式庫 | Ws2_32.lib |
| Dll | Ws2_32.dll |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應