Funzione WSCEnumProtocols32 (ws2spi.h)
La funzione WSCEnumProtocols32 recupera informazioni sui protocolli di trasporto disponibili.
Sintassi
int WSCEnumProtocols32(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOW lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength,
[out] LPINT lpErrno
);
Parametri
[in] lpiProtocols
Matrice con terminazione Null di valori iProtocol . Questo parametro è facoltativo; se lpiProtocols è Null, vengono restituite informazioni su tutti i protocolli disponibili. In caso contrario, le informazioni vengono recuperate solo per tali protocolli elencati nella matrice.
[out] lpProtocolBuffer
Buffer riempito con strutture WSAPROTOCOL_INFOW .
[in, out] lpdwBufferLength
In input, le dimensioni del buffer lpProtocolBuffer passate a WSCEnumProtocols, in byte. Nell'output, le dimensioni minime del buffer, in byte, che possono essere passate a WSCEnumProtocols per recuperare tutte le informazioni richieste.
[out] lpErrno
Puntatore al codice di errore.
Valore restituito
Se non si verifica alcun errore, WSCEnumProtocols32 restituisce il numero di protocolli da segnalare. In caso contrario, viene restituito un valore di SOCKET_ERROR e in lpErrno è disponibile un codice di errore specifico.
| Codice di errore | Significato |
|---|---|
| Uno degli argomenti non è incluso in una parte valida dello spazio indirizzi utente. | |
| Indica che uno dei parametri specificati non è valido. | |
| La lunghezza del buffer era troppo piccola per ricevere tutte le strutture WSAProtocol_Info pertinenti e le informazioni associate. Passare un buffer almeno pari al valore restituito in lpdwBufferLength. |
Commenti
WSCEnumProtocols32 è una versione rigorosa a 32 bit di WSCEnumProtocols. In un computer a 64 bit tutte le chiamate non sono specifiche a 32 bit (ad esempio, tutte le funzioni che non terminano in "32") operano sul catalogo nativo a 64 bit. I processi eseguiti in un computer a 64 bit devono usare le chiamate di funzione a 32 bit specifiche per operare su un catalogo a 32 bit e mantenere la compatibilità. Le definizioni e la semantica delle chiamate a 32 bit specifiche sono le stesse delle rispettive controparti native.
Questa funzione viene utilizzata per individuare informazioni sulla raccolta di protocolli di trasporto installati nel computer locale. Questa funzione è diversa dalla controparte API (WSAEnumProtocols) in quanto vengono restituite le strutture WSAPROTOCOL_INFOW per tutti i protocolli installati. Sono inclusi i protocolli che il provider di servizi ha impostato il flag PFL_HIDDEN nel membro dwProviderFlags della struttura WSAPROTOCOL_INFOW per indicare al Ws2_32.dll che questo protocollo non deve essere restituito nel buffer dei risultati generato dalla funzione WSAEnumProtocols . Inoltre, WSCEnumProtocols32 restituisce dati per WSAPROTOCOL_INFOW strutture con lunghezza della catena pari a zero ( provider LSP fittizio). WSAEnumProtocols restituisce solo informazioni sui protocolli di base e sulle catene di protocolli che non dispongono del flag PFL_HIDDEN e non hanno una lunghezza della catena di protocolli pari a zero.
Una struttura WSAPROTOCOL_INFOW viene fornita nel buffer a cui punta lpProtocolBuffer per ogni protocollo richiesto. Se il buffer fornito non è sufficientemente grande (come indicato dal valore di input di lpdwBufferLength), il valore a cui punta lpdwBufferLength verrà aggiornato per indicare le dimensioni del buffer necessarie. Il client SPI Windows Sockets dovrebbe quindi ottenere un buffer sufficientemente grande e chiamare di nuovo questa funzione. La funzione WSCEnumProtocols32 non può enumerare più chiamate; Il buffer passato deve essere sufficientemente grande per contenere tutte le voci previste affinché la funzione abbia esito positivo. Ciò riduce la complessità della funzione e non deve rappresentare un problema perché il numero di protocolli caricati in un computer è in genere ridotto.
L'ordine in cui le strutture WSAPROTOCOL_INFOW vengono visualizzate nel buffer coincide con l'ordine in cui le voci del protocollo sono state registrate dal provider di servizi con il WS2_32.dll o con qualsiasi riordinamento successivo che potrebbe essersi verificato tramite l'applet Windows Sockets fornito per stabilire provider di trasporto predefiniti.
Esempio
Nell'esempio seguente viene illustrato l'uso della funzione WSCEnumProtocols32 per l'uso su piattaforme a 64 bit per recuperare una matrice di strutture WSAPROTOCOL_INFOW per i protocolli installati nel computer locale nel catalogo a 32 bit.
#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;
}
Requisiti
| Client minimo supportato | Windows Vista, Windows XP Professional x64 Edition [solo app desktop] |
| Server minimo supportato | Windows Server 2008, Windows Server 2003 x64 Edition [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | ws2spi.h |
| Libreria | Ws2_32.lib |
| DLL | Ws2_32.dll |