Funzione WSAEnumProtocolsA (winsock2.h)
La funzione WSAEnumProtocols recupera informazioni sui protocolli di trasporto disponibili.
Sintassi
int WSAAPI WSAEnumProtocolsA(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOA lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength
);
Parametri
[in] lpiProtocols
Matrice con terminazione NULL dei 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
Puntatore a un buffer riempito con strutture WSAPROTOCOL_INFO .
[in, out] lpdwBufferLength
In input, numero di byte nel buffer lpProtocolBuffer passato a WSAEnumProtocols. In output, le dimensioni minime del buffer che possono essere passate a WSAEnumProtocols per recuperare tutte le informazioni richieste. Questa routine non ha la possibilità di enumerare su più chiamate; il buffer passato deve essere abbastanza grande per contenere tutte le voci in modo che la routine abbia esito positivo. Ciò riduce la complessità dell'API e non deve rappresentare un problema perché il numero di protocolli caricati in un computer è in genere piccolo.
Valore restituito
Se non si verifica alcun errore, WSAEnumProtocols restituisce il numero di protocolli da segnalare. In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.
| Codice di errore | Significato |
|---|---|
| Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita. | |
| Il sottosistema di rete non è riuscito. | |
| Una chiamata windows Sockets 1.1 bloccata è in corso. | |
| 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. | |
| Uno o più parametri lpiProtocols, lpProtocolBuffer o lpdwBufferLength non sono una parte valida dello spazio degli indirizzi utente. |
Commenti
La funzione WSAEnumProtocols viene usata per individuare informazioni sulla raccolta di protocolli di trasporto installati nel computer locale. I protocolli a livelli sono utilizzabili solo dalle applicazioni quando sono installate nelle catene di protocolli. Le informazioni sui protocolli a livelli non vengono restituite, ad eccezione di eventuali provider di servizi a livelli fittizi installati con una lunghezza di catena pari a zero nell'oggetto lpProtocolBuffer.
La funzione WSAEnumProtocols differisce dalle funzioni WSCEnumProtocols e WSCEnumProtocols32 in cui la funzione WSAEnumProtocols non restituisce strutture WSAPROTOCOL_INFO per tutti i protocolli installati. La funzione WSAEnumProtocols esclude i protocolli impostati dal provider di servizi con il flag PFL_HIDDEN nel membro dwProviderFlagsdella struttura WSAPROTOCOL_INFO per indicare al Ws2_32.dll che questo protocollo non deve essere restituito nel buffer dei risultati generato dalla funzione WSAEnumProtocols. Inoltre, la funzione WSAEnumProtocols non restituisce i dati per le strutture WSAPROTOCOL_INFO con lunghezza della catena di uno o più (provider LSP). WSAEnumProtocols restituisce solo informazioni sui protocolli di base e sulle catene di protocolli che non dispongono del flag di PFL_HIDDEN e non hanno una lunghezza della catena di protocolli pari a zero.
Una struttura WSAPROTOCOL_INFO viene fornita nel buffer a cui punta lpProtocolBuffer per ogni protocollo richiesto. Se il buffer specificato non è sufficiente (come indicato dal valore di input di lpdwBufferLength), il valore a cui punta lpdwBufferLength verrà aggiornato per indicare le dimensioni del buffer necessarie. L'applicazione deve quindi ottenere un buffer sufficiente e chiamare di nuovo WSAEnumProtocols .
L'ordine in cui le strutture WSAPROTOCOL_INFO vengono visualizzate nel buffer coincide con l'ordine in cui le voci del protocollo sono state registrate dal provider di servizi usando il WS2_32.DLL o con qualsiasi riordinamento successivo che si è verificato tramite l'applicazione Windows Sockets o la DLL fornita per stabilire i provider TCP/IP predefiniti.
Windows Phone 8: la funzione WSAEnumProtocolsW è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.
Windows 8.1 e Windows Server 2012 R2: la funzione WSAEnumProtocolsW è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.
Esempio
Nell'esempio seguente viene illustrato l'uso della funzione WSAEnumProtocols per recuperare una matrice di strutture WSAPROTOCOL_INFO per i protocolli di trasporto disponibili.
#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;
}
Nota
L'intestazione winsock2.h definisce WSAEnumProtocols come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 8.1, Windows Vista [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | winsock2.h |
| Libreria | Ws2_32.lib |
| DLL | Ws2_32.dll |