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 |
|---|---|
| L’un des autres arguments ne se trouve pas dans une partie valide de l’espace d’adressage utilisateur. | |
| Indique que l’un des paramètres spécifiés n’était pas valide. | |
| 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.
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 |