Funzione WSCEnumProtocols (ws2spi.h)
La funzione WSCEnumProtocols recupera informazioni sui protocolli di trasporto disponibili.
Sintassi
int WSCEnumProtocols(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOW lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength,
[out] LPINT lpErrno
);
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_INFOW .
[in, out] lpdwBufferLength
In input, le dimensioni del buffer lpProtocolBuffer passate a WSCEnumProtocols, in byte. In 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, WSCEnumProtocols restituisce il numero di protocolli da segnalare. In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico è disponibile in lpErrno.
| Codice di errore | Significato |
|---|---|
| Uno degli argomenti non è incluso in una parte valida dello spazio degli 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
La funzione WSCEnumProtocols viene usata per individuare informazioni sulla raccolta di protocolli di trasporto installati nel computer locale. Questa funzione differisce dalla controparte API (WSAEnumProtocols) in tale WSAPROTOCOL_INFOW strutture per tutti i protocolli installati vengono restituiti. Sono inclusi i protocolli che il provider di servizi ha impostato il flag PFL_HIDDEN nel membro dwProviderFlagsdella 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, WSCEnumProtocols restituisce anche i dati per le strutture WSAPROTOCOL_INFOW con lunghezza della catena pari a zero ( un provider LSP fittizio). 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_INFOW viene fornita nel buffer a cui punta lpProtocolBuffer per ogni protocollo richiesto. Se il buffer fornito 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. Il client SPI di Windows Sockets deve quindi ottenere un buffer sufficiente e chiamare di nuovo questa funzione. La funzione WSCEnumProtocols non può enumerare più chiamate; il buffer passato deve essere abbastanza grande per contenere tutte le voci previste in modo che 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 locale è in genere piccolo.
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 essere stato eseguito tramite l'applet di Windows Sockets fornito per stabilire i provider di trasporto predefiniti.
Esempio
Nell'esempio seguente viene illustrato l'uso della funzione WSCEnumProtocols per recuperare una matrice di strutture WSAPROTOCOL_INFOW per i protocolli installati nel computer locale.
#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 = WSCEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
if (iErrno != WSAENOBUFS) {
wprintf(L"WSCEnumProtocols failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
} else {
wprintf(L"WSCEnumProtocols 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 =
WSCEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
wprintf(L"WSCEnumProtocols failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
}
}
}
wprintf(L"WSCEnumProtocols 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 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | ws2spi.h |
| Libreria | Ws2_32.lib |
| DLL | Ws2_32.dll |