WSAEnumProtocolsW, fonction (winsock2.h)
La fonction WSAEnumProtocols récupère des informations sur les protocoles de transport disponibles.
Syntaxe
int WSAAPI WSAEnumProtocolsW(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOW lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength
);
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_INFO .
[in, out] lpdwBufferLength
En entrée, nombre d’octets dans la mémoire tampon lpProtocolBuffer passée à WSAEnumProtocols. En sortie, la taille de mémoire tampon minimale qui peut être transmise à WSAEnumProtocols pour récupérer toutes les informations demandées. Cette routine n’a pas la possibilité d’énumérer plusieurs appels ; la mémoire tampon transmise doit être suffisamment grande pour contenir toutes les entrées pour que la routine réussisse. Cela réduit la complexité de l’API et ne devrait pas poser de problème, car le nombre de protocoles chargés sur un ordinateur est généralement faible.
Valeur retournée
Si aucune erreur ne se produit, WSAEnumProtocols retourne le nombre de protocoles à signaler. Sinon, une valeur de SOCKET_ERROR est retournée et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError.
| Code d'erreur | Signification |
|---|---|
| Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction. | |
| Le sous-système réseau a échoué. | |
| Un appel bloquant Windows Sockets 1.1 est en cours. | |
| Indique que l’un des paramètres spécifiés n’était pas valide. | |
| La longueur de la mémoire tampon était trop petite 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. | |
| Un ou plusieurs des paramètres lpiProtocols, lpProtocolBuffer ou lpdwBufferLength ne font pas partie de l’espace d’adressage utilisateur. |
Remarques
La fonction WSAEnumProtocols est utilisée pour découvrir des informations sur la collection de protocoles de transport installés sur l’ordinateur local. Les protocoles en couches sont utilisables uniquement par les applications lorsqu’ils sont installés dans des chaînes de protocoles. Les informations sur les protocoles en couches ne sont pas retournées, sauf pour les fournisseurs de services factices en couches (LSP) installés avec une longueur de chaîne de zéro dans le lpProtocolBuffer.
La fonction WSAEnumProtocols diffère des fonctions WSCEnumProtocols et WSCEnumProtocols32 en ce que la fonction WSAEnumProtocols ne retourne pas WSAPROTOCOL_INFO structures pour tous les protocoles installés. La fonction WSAEnumProtocols exclut les protocoles que le fournisseur de services a définis avec l’indicateur PFL_HIDDEN dans le membre dwProviderFlags de la structure WSAPROTOCOL_INFO pour indiquer au Ws2_32.dll que ce protocole ne doit pas être retourné dans la mémoire tampon de résultat générée par la fonction WSAEnumProtocols . En outre, la fonction WSAEnumProtocols ne retourne pas de données pour les structures WSAPROTOCOL_INFO qui ont une longueur de chaîne supérieure ou égale à un (fournisseur LSP). 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_INFO est fournie dans la mémoire tampon pointée par lpProtocolBuffer pour chaque protocole demandé. Si la mémoire tampon spécifiée n’est pas assez 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. L’application doit ensuite obtenir une mémoire tampon suffisamment grande et appeler à nouveau WSAEnumProtocols .
L’ordre dans lequel les structures WSAPROTOCOL_INFO 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 à l’aide de l'WS2_32.DLL, ou avec toute réorganisation ultérieure qui s’est produite via l’application Windows Sockets ou la DLL fournie pour établir des fournisseurs TCP/IP par défaut.
Windows Phone 8 : la fonction WSAEnumProtocolsW est prise en charge pour les applications du Store Windows Phone Windows Phone 8 et versions ultérieures.
Windows 8.1 et Windows Server 2012 R2 : la fonction WSAEnumProtocolsW est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.
Exemples
L’exemple suivant illustre l’utilisation de la fonction WSAEnumProtocols pour récupérer un tableau de structures WSAPROTOCOL_INFO pour les protocoles de transport disponibles.
#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;
}
Notes
L’en-tête winsock2.h définit WSAEnumProtocols comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Configuration requise
| Client minimal pris en charge | Windows 8.1, Windows Vista [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | winsock2.h |
| Bibliothèque | Ws2_32.lib |
| DLL | Ws2_32.dll |