WSCEnumProtocols32, fonction (ws2spi.h)
La fonction WSCEnumProtocols32 récupère des informations sur les protocoles de transport disponibles.
Syntaxe
int WSCEnumProtocols32(
[in] LPINT lpiProtocols,
[out] LPWSAPROTOCOL_INFOW lpProtocolBuffer,
[in, out] LPDWORD lpdwBufferLength,
[out] LPINT lpErrno
);
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. Dans le cas contraire, les informations sont récupérées uniquement pour les protocoles répertoriés dans le tableau.
[out] lpProtocolBuffer
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, WSCEnumProtocols32 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
WSCEnumProtocols32 est une version strictement 32 bits de WSCEnumProtocols. Sur un ordinateur 64 bits, tous les appels ne sont pas spécifiquement 32 bits (par exemple, toutes les fonctions qui ne se terminent pas par « 32 ») fonctionnent sur le catalogue 64 bits natif. Les processus qui s’exécutent sur un ordinateur 64 bits doivent utiliser les appels de fonction 32 bits spécifiques pour fonctionner sur un catalogue strictement 32 bits et préserver la compatibilité. Les définitions et la sémantique des appels 32 bits spécifiques sont les mêmes que leurs équivalents natifs.
Cette fonction 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, WSCEnumProtocols32 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 WSCEnumProtocols32 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 doit pas poser de problème, car le nombre de protocoles chargés sur un ordinateur 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 WSCEnumProtocols32 pour une utilisation sur des plateformes 64 bits afin de récupérer un tableau de structures WSAPROTOCOL_INFOW pour les protocoles installés sur l’ordinateur local dans le catalogue 32 bits.
#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 = WSCEnumProtocols32(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
if (iErrno != WSAENOBUFS) {
wprintf(L"WSCEnumProtocols32 failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
} else {
wprintf(L"WSCEnumProtocols32 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 =
WSCEnumProtocols32(NULL, lpProtocolInfo, &dwBufferLen, &iErrno);
if (iNuminfo == SOCKET_ERROR) {
wprintf(L"WSCEnumProtocols32 failed with error: %d\n", iErrno);
if (lpProtocolInfo) {
FREE(lpProtocolInfo);
lpProtocolInfo = NULL;
}
WSACleanup();
return 1;
}
}
}
wprintf(L"WSCEnumProtocols32 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 Vista, Windows XP Professionnel Édition x64 [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008, Windows Server 2003 Édition x64 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | ws2spi.h |
| Bibliothèque | Ws2_32.lib |
| DLL | Ws2_32.dll |