WSAEnumProtocolsA, fonction (winsock2.h)
La fonction WSAEnumProtocols récupère des informations sur les protocoles de transport disponibles.
Syntaxe
int WSAAPI WSAEnumProtocolsA(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOA lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength
);
Paramètres
[in] lpiProtocols
Tableau NULL-terminated de valeurs iProtocol. Ce paramètre est facultatif ; si lpiProtocols est NULL, les informations sur tous les protocoles disponibles sont retournées. Sinon, les informations sont récupérées uniquement pour ces protocoles répertoriés dans le tableau.
[out] lpProtocolBuffer
Pointeur vers une mémoire tampon remplie de structures WSAPROTOCOL_INFO.
[in, out] lpdwBufferLength
Lors de l’entrée, nombre d’octets dans la mémoire tampon lpProtocolBuffer passée à WSAEnumProtocols. En sortie, la taille minimale de la mémoire tampon 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 afin que la routine réussisse. Cela réduit la complexité de l’API et ne doit pas poser de problème, car le nombre de protocoles chargés sur un ordinateur est généralement petit.
Valeur de retour
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 Windows Sockets 1.1 bloquant est en cours. | |
| Indique qu’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 au moins aussi grande que la valeur retournée dans lpdwBufferLength. | |
|
Un ou plusieurs deslpiProtocols |
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’elles sont installées dans des chaînes de protocole. Les informations sur les protocoles en couches ne sont pas retournées, à l’exception des fournisseurs de services en couches factices (LSP) installés avec une longueur de chaîne de zéro dans le lpProtocolBuffer.
La fonction WSAEnumProtocols diffère de la fonction WSCEnumProtocols et WSCEnumProtocols32 dans laquelle la fonction WSAEnumProtocols ne retourne pas de structures WSAPROTOCOL_INFO pour tous les protocoles installés. La fonction WSAEnumProtocols exclut les protocoles que le fournisseur de services a définis avec l’indicateur de PFL_HIDDEN dans le dwProviderFlags membre 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 WSAEnumProtocols fonction. En outre, la fonction WSAEnumProtocols ne retourne pas de données pour les structures WSAPROTOCOL_INFO qui ont une longueur de chaîne d’une ou plusieurs (un fournisseur LSP). Les WSAEnumProtocols retourne uniquement des informations sur les protocoles de base et les chaînes de protocole qui n’ont pas l’indicateur PFL_HIDDEN et n’ont pas de longueur de chaîne de protocole nulle.
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 suffisamment grande (comme indiqué par la valeur d’entrée de lpdwBufferLength), la valeur pointée par lpdwBufferLength sera mise à jour pour indiquer la taille de mémoire tampon requise. L’application doit ensuite obtenir une mémoire tampon suffisante et appeler WSAEnumProtocols à nouveau.
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é inscrites 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 Windows Phone Store sur 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;
}
Note
L’en-tête winsock2.h définit WSAEnumProtocols comme 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 8.1, Windows Vista [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | winsock2.h |
| bibliothèque | Ws2_32.lib |
| DLL | Ws2_32.dll |