Função WSCEnumProtocols32 (ws2spi.h)
A função WSCEnumProtocols32 recupera informações sobre protocolos de transporte disponíveis.
Sintaxe
int WSCEnumProtocols32(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOW lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength,
[out] LPINT lpErrno
);
Parâmetros
[in] lpiProtocols
Matriz terminada em nulo de valores iProtocol . Esse parâmetro é opcional; se lpiProtocols for nulo, as informações sobre todos os protocolos disponíveis serão retornadas. Caso contrário, as informações serão recuperadas apenas para os protocolos listados na matriz.
[out] lpProtocolBuffer
Buffer preenchido com estruturas de WSAPROTOCOL_INFOW .
[in, out] lpdwBufferLength
Na entrada, o tamanho do buffer lpProtocolBuffer passado para WSCEnumProtocols, em bytes. Na saída, o tamanho mínimo do buffer, em bytes, que pode ser passado para WSCEnumProtocols para recuperar todas as informações solicitadas.
[out] lpErrno
Ponteiro para o código de erro.
Valor retornado
Se nenhum erro ocorrer, WSCEnumProtocols32 retornará o número de protocolos em que serão relatados. Caso contrário, um valor de SOCKET_ERROR será retornado e um código de erro específico estará disponível no lpErrno.
| Código do erro | Significado |
|---|---|
| Um dos mais argumentos não está em uma parte válida do espaço de endereço do usuário. | |
| Indica que um dos parâmetros especificados era inválido. | |
| O comprimento do buffer era muito pequeno para receber todas as estruturas de WSAProtocol_Info relevantes e informações associadas. Passe um buffer pelo menos tão grande quanto o valor retornado em lpdwBufferLength. |
Comentários
WSCEnumProtocols32 é uma versão estritamente de 32 bits do WSCEnumProtocols. Em um computador de 64 bits, todas as chamadas não especificamente de 32 bits (por exemplo, todas as funções que não terminam em "32") operam no catálogo nativo de 64 bits. Os processos executados em um computador de 64 bits devem usar as chamadas específicas de função de 32 bits para operar em um catálogo estritamente de 32 bits e preservar a compatibilidade. As definições e a semântica das chamadas específicas de 32 bits são as mesmas que seus equivalentes nativos.
Essa função é usada para descobrir informações sobre a coleção de protocolos de transporte instalados no computador local. Essa função difere de seu equivalente de API (WSAEnumProtocols) na qual WSAPROTOCOL_INFOW estruturas para todos os protocolos instalados são retornadas. Isso inclui protocolos que o provedor de serviços definiu o sinalizador PFL_HIDDEN no membro dwProviderFlags da estrutura WSAPROTOCOL_INFOW para indicar ao Ws2_32.dll que esse protocolo não deve ser retornado no buffer de resultados gerado pela função WSAEnumProtocols . Além disso, o WSCEnumProtocols32 também retorna dados para estruturas WSAPROTOCOL_INFOW que têm um comprimento de cadeia zero (um provedor LSP fictício). O WSAEnumProtocols retorna apenas informações sobre protocolos base e cadeias de protocolo que não têm o sinalizador PFL_HIDDEN e não têm um comprimento de cadeia de protocolo igual a zero.
Uma estrutura WSAPROTOCOL_INFOW é fornecida no buffer apontado por lpProtocolBuffer para cada protocolo solicitado. Se o buffer fornecido não for grande o suficiente (conforme indicado pelo valor de entrada de lpdwBufferLength), o valor apontado por lpdwBufferLength será atualizado para indicar o tamanho do buffer necessário. Em seguida, o cliente SPI do Windows Sockets deve obter um buffer grande o suficiente e chamar essa função novamente. A função WSCEnumProtocols32 não pode enumerar em várias chamadas; o buffer passado deve ser grande o suficiente para manter todas as entradas esperadas para que a função tenha êxito. Isso reduz a complexidade da função e não deve representar um problema porque o número de protocolos carregados em um computador normalmente é pequeno.
A ordem na qual as estruturas WSAPROTOCOL_INFOW aparecem no buffer coincide com a ordem em que as entradas de protocolo foram registradas pelo provedor de serviços com o WS2_32.dll ou com qualquer reordenação subsequente que possa ter ocorrido por meio do applet Windows Sockets fornecido para estabelecer provedores de transporte padrão.
Exemplos
O exemplo a seguir demonstra o uso da função WSCEnumProtocols32 para uso em plataformas de 64 bits para recuperar uma matriz de estruturas de WSAPROTOCOL_INFOW para protocolos instalados no computador local no catálogo de 32 bits.
#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 = WSCEnumProtocols32(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
if (iErrno != WSAENOBUFS) {
wprintf(L"WSCEnumProtocols32 failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
} else {
wprintf(L"WSCEnumProtocols32 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 =
WSCEnumProtocols32(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
wprintf(L"WSCEnumProtocols32 failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
}
}
}
wprintf(L"WSCEnumProtocols32 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;
}
Requisitos
| Cliente mínimo com suporte | Windows Vista, Windows XP Professional x64 Edition [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008, Windows Server 2003 x64 Edition [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | ws2spi.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |