Condividi tramite


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
WSANOTINITIALISED
Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita.
WSAENETDOWN
Il sottosistema di rete non è riuscito.
WSAEINPROGRESS
Una chiamata windows Sockets 1.1 bloccata è in corso.
WSAEINVAL
Indica che uno dei parametri specificati non è valido.
WSAENOBUFS
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.
WSAEFAULT
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.

Nota I provider di servizi a livelli sono deprecati. A partire da Windows 8 e Windows Server 2012, usare Windows Filtering Platform.
 
Il parametro lpiProtocols può essere usato come filtro per limitare la quantità di informazioni fornite. Spesso, lpiProtocols verrà specificato come puntatore NULL che causerà la funzione di restituire informazioni su tutti i protocolli di trasporto e le catene di protocollo disponibili.

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

Vedi anche

WSAPROTOCOL_INFO

WSCEnumProtocols

WSCEnumProtocols32

Funzioni Winsock

Informazioni di riferimento su Winsock