Функция WSAEnumProtocolsA (winsock2.h)
Функция WSAEnumProtocols извлекает сведения о доступных транспортных протоколах.
Синтаксис
int WSAAPI WSAEnumProtocolsA(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOA lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength
);
Параметры
[in] lpiProtocols
Массив NULL--terminated массив значений iProtocol. Этот параметр является необязательным; Если lpiProtocols имеет значение NULL , возвращается информация обо всех доступных протоколах. В противном случае данные извлекаются только для этих протоколов, перечисленных в массиве.
[out] lpProtocolBuffer
Указатель на буфер, заполненный WSAPROTOCOL_INFO структурами.
[in, out] lpdwBufferLength
Количество байтов в буфере lpProtocolBuffer, переданное WSAEnumProtocols. В выходных данных минимальный размер буфера, который можно передать WSAEnumProtocols для получения всех запрошенных сведений. Эта подпрограмма не имеет возможности перечислять несколько вызовов; Буфер переданного файла должен быть достаточно большим, чтобы сохранить все записи, чтобы подпрограмма прошла успешно. Это снижает сложность API и не должно представлять проблемы, так как количество протоколов, загруженных на компьютер, обычно невелико.
Возвращаемое значение
Если ошибка не возникает, WSAEnumProtocols возвращает количество протоколов, которые необходимо сообщить. В противном случае возвращается значение SOCKET_ERROR, а определенный код ошибки можно получить путем вызова WSAGetLastError.
| Код ошибки | Значение |
|---|---|
| Перед использованием этой функции необходимо выполнить успешный вызов WSAStartup. | |
| Сбой сетевой подсистемы. | |
| Выполняется блокировка вызова сокетов Windows 1.1. | |
| Указывает, что один из указанных параметров недопустим. | |
| Длина буфера слишком мала, чтобы получить все соответствующие WSAPROTOCOL_INFO структуры и связанные сведения. Передайте буфер по крайней мере так же, как значение, возвращаемое в lpdwBufferLength. | |
| Один или несколько lpiProtocols, lpProtocolBufferили lpdwBufferLength не являются допустимой частью адресного пространства пользователя. |
Замечания
Функция WSAEnumProtocols используется для обнаружения сведений о коллекции транспортных протоколов, установленных на локальном компьютере. Многоуровневые протоколы доступны только приложениям при установке в цепочках протоколов. Сведения о многоуровневых протоколах не возвращаются, за исключением фиктивных поставщиков служб (LSPs) с длиной цепочки в lpProtocolBuffer.
Функция WSAEnumProtocols отличается от функции
Структура WSAPROTOCOL_INFO предоставляется в буфере, на который указывает lpProtocolBuffer для каждого запрошенного протокола. Если указанный буфер недостаточно велик (как указано входным значением lpdwBufferLength), значение, указываемое lpdwBufferLength будет обновлено, чтобы указать требуемый размер буфера. Затем приложение должно получить достаточно большой буфер и снова вызвать WSAEnumProtocols.
Порядок, в котором WSAPROTOCOL_INFO структуры отображаются в буфере, совпадает с порядком регистрации записей протокола поставщиком услуг с помощью WS2_32.DLL или с последующим изменением порядка, которое произошло через приложение сокетов Windows или библиотеку DLL, предоставляемую для установления поставщиков TCP/IP по умолчанию.
Windows Phone 8:функция WSAEnumProtocolsW поддерживается для приложений Магазина Windows Phone в Windows Phone 8 и более поздних версиях.
Windows 8.1 и Windows Server 2012 R2: функция WSAEnumProtocolsW поддерживается для приложений Магазина Windows в Windows 8.1, Windows Server 2012 R2 и более поздних версий.
Примеры
В следующем примере показано использование функции 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 определяет WSAEnumProtocols в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 8.1, Windows Vista [классические приложения | Приложения UWP] |
| минимальный поддерживаемый сервер | Windows Server 2003 [классические приложения | Приложения UWP] |
| целевая платформа | Виндоус |
| заголовка | winsock2.h |
| библиотеки |
Ws2_32.lib |
| DLL | Ws2_32.dll |
См. также
Справочник