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 terminé par 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. Sinon, 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
Lors de l’entrée, nombre d’octets dans la mémoire tampon lpProtocolBuffer passé à WSAEnumProtocols. En sortie, taille de mémoire tampon minimale qui peut être passée à 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 passée 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 doit 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 Windows Sockets 1.1 bloquant 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 de WSAPROTOCOL_INFO pertinentes et les informations associées. Transmettez une mémoire tampon au moins aussi grande que la valeur retournée dans lpdwBufferLength. | |
| Une ou plusieurs des paramètres lpiProtocols, lpProtocolBuffer ou lpdwBufferLength ne sont pas une partie valide 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, à l’exception des fournisseurs de services en couche (LSP) factices installés avec une longueur de chaîne de zéro dans l’objet 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ésultats 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 ou supérieure (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 égale à 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 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. 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 la 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 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;
}
Notes
L’en-tête winsock2.h définit WSAEnumProtocols en tant qu’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. La combinaison 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
| Condition requise | Valeur |
|---|---|
| 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 |