Partager via


Fonction WSCEnumProtocols (ws2spi.h)

La fonction WSCEnumProtocols récupère des informations sur les protocoles de transport disponibles.

Syntaxe

int WSCEnumProtocols(
  [in]      LPINT               lpiProtocols,
  [out]     LPWSAPROTOCOL_INFOW lpProtocolBuffer,
  [in, out] LPDWORD             lpdwBufferLength,
  [out]     LPINT               lpErrno
);

Paramètres

[in] lpiProtocols

Tableau null de valeurs iProtocol . Ce paramètre est facultatif ; si lpiProtocols a la valeur NULL, des informations sur tous les protocoles disponibles sont retournées. Dans le cas contraire, les informations sont récupérées uniquement pour les protocoles répertoriés dans le tableau.

[out] lpProtocolBuffer

Pointeur vers une mémoire tampon remplie de structures WSAPROTOCOL_INFOW .

[in, out] lpdwBufferLength

En entrée, taille de la mémoire tampon lpProtocolBuffer passée à WSCEnumProtocols, en octets. En sortie, la taille minimale de la mémoire tampon, en octets, qui peut être transmise à WSCEnumProtocols pour récupérer toutes les informations demandées.

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

Si aucune erreur ne se produit, WSCEnumProtocols retourne le nombre de protocoles à signaler. Sinon, une valeur de SOCKET_ERROR est retournée et un code d’erreur spécifique est disponible dans lpErrno.

Code d'erreur Signification
WSAEFAULT
L’un des autres arguments ne se trouve pas dans une partie valide de l’espace d’adressage utilisateur.
WSAEINVAL
Indique que l’un des paramètres spécifiés n’était pas valide.
WSAENOBUFS
La longueur de la mémoire tampon était trop faible pour recevoir toutes les structures WSAProtocol_Info pertinentes et les informations associées. Transmettez une mémoire tampon d’au moins aussi grande que la valeur retournée dans lpdwBufferLength.

Remarques

La fonction WSCEnumProtocols est utilisée pour découvrir des informations sur la collection de protocoles de transport installés sur l’ordinateur local. Cette fonction diffère de son équivalent d’API (WSAEnumProtocols) en ce que WSAPROTOCOL_INFOW structures pour tous les protocoles installés sont retournées. Cela inclut les protocoles que le fournisseur de services a définis l’indicateur de PFL_HIDDEN dans le membre dwProviderFlags de la structure WSAPROTOCOL_INFOW pour indiquer au Ws2_32.dll que ce protocole ne doit pas être retourné dans la mémoire tampon de résultats générée par la fonction WSAEnumProtocols . En outre, WSCEnumProtocols retourne également des données pour les structures WSAPROTOCOL_INFOW qui ont une longueur de chaîne de zéro (un fournisseur LSP factice). WSAEnumProtocols retourne uniquement des informations sur les protocoles de base et les chaînes de protocole qui ne disposent pas de l’indicateur PFL_HIDDEN et qui n’ont pas de longueur de chaîne de protocole de zéro.

**Remarque** Les fournisseurs de services en couches sont déconseillés. À compter de Windows 8 et Windows Server 2012, utilisez la plateforme de filtrage Windows.
 
Le paramètre lpiProtocols peut être utilisé comme filtre pour limiter la quantité d’informations fournies. En règle générale, un pointeur null est fourni pour que la fonction retourne des informations sur tous les protocoles de transport disponibles.

Une structure WSAPROTOCOL_INFOW est fournie dans la mémoire tampon pointée par lpProtocolBuffer pour chaque protocole demandé. Si la mémoire tampon fournie n’est pas suffisamment grande (comme indiqué par la valeur d’entrée de lpdwBufferLength), la valeur pointée par lpdwBufferLength est mise à jour pour indiquer la taille de mémoire tampon requise. Le client SPI Windows Sockets doit alors obtenir une mémoire tampon suffisamment grande et appeler à nouveau cette fonction. La fonction WSCEnumProtocols ne peut pas énumérer plusieurs appels ; la mémoire tampon transmise doit être suffisamment grande pour contenir toutes les entrées attendues pour que la fonction réussisse. Cela réduit la complexité de la fonction et ne devrait pas poser de problème, car le nombre de protocoles chargés sur un ordinateur local est généralement faible.

L’ordre dans lequel les structures WSAPROTOCOL_INFOW apparaissent dans la mémoire tampon coïncide avec l’ordre dans lequel les entrées de protocole ont été enregistrées par le fournisseur de services auprès du WS2_32.dll, ou avec toute réorganisation ultérieure qui a pu se produire via l’applet Windows Sockets fournie pour l’établissement des fournisseurs de transport par défaut.

Exemples

L’exemple suivant illustre l’utilisation de la fonction WSCEnumProtocols pour récupérer un tableau de structures WSAPROTOCOL_INFOW pour les protocoles installés sur l’ordinateur local.

#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;
}


Spécifications

   
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête ws2spi.h
Bibliothèque Ws2_32.lib
DLL Ws2_32.dll

Voir aussi

WSAEnumProtocols

WSAPROTOCOL_INFOW

WSCEnumProtocols32