WSAEnumNameSpaceProvidersA, fonction (winsock2.h)

  • Article

La fonction WSAEnumNameSpaceProviders récupère des informations sur les fournisseurs d’espaces de noms disponibles.

Syntaxe

INT WSAAPI WSAEnumNameSpaceProvidersA(
  [in, out] LPDWORD              lpdwBufferLength,
  [out]     LPWSANAMESPACE_INFOA lpnspBuffer
);

Paramètres

[in, out] lpdwBufferLength

Lors de l’entrée, nombre d’octets contenus dans la mémoire tampon pointée par lpnspBuffer. En sortie (si la fonction échoue et que l’erreur est WSAEFAULT), nombre minimal d’octets à passer pour que l’objet lpnspBuffer récupère toutes les informations demandées. La mémoire tampon passée à WSAEnumNameSpaceProviders doit être suffisante pour contenir toutes les informations d’espace de noms.

[out] lpnspBuffer

Mémoire tampon remplie de structures WSANAMESPACE_INFO . Les structures retournées sont situées consécutivement en tête de la mémoire tampon. Les informations de taille variable référencées par des pointeurs dans les structures pointent vers des emplacements dans la mémoire tampon situés entre la fin des structures de taille fixe et la fin de la mémoire tampon. Le nombre de structures renseignées est la valeur de retour de WSAEnumNameSpaceProviders.

Valeur retournée

La fonction WSAEnumNameSpaceProviders retourne le nombre de structures WSANAMESPACE_INFO copiées dans lpnspBuffer. Sinon, la valeur SOCKET_ERROR est retournée et un numéro d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Code d'erreur Signification
WSAEFAULT
 Le paramètre lpnspBuffer était un pointeur NULL ou la longueur de la mémoire tampon, lpdwBufferLength, était trop petite pour recevoir toutes les structures de WSANAMESPACE_INFO pertinentes et les informations associées. Lorsque cette erreur est retournée, la longueur de la mémoire tampon requise est retournée dans le paramètre lpdwBufferLength .
WSANOTINITIALISED
 Le WS2_32.DLL n’a pas été initialisé. L’application doit d’abord appeler WSAStartup avant d’appeler les fonctions Windows Sockets.
WSA_NOT_ENOUGH_MEMORY
 La mémoire était insuffisante pour effectuer l’opération.

Remarques

La fonction WSAEnumNameSpaceProviders retourne des informations sur les fournisseurs d’espaces de noms disponibles dans la mémoire tampon vers laquelle pointe le paramètre lpnspBuffer . La mémoire tampon retournée contient un tableau de structures WSANAMESPACE_INFO situées consécutivement en tête de la mémoire tampon. Les informations de taille variable référencées par des pointeurs dans les structures WSANAMESPACE_INFO pointent vers des emplacements dans la mémoire tampon situées entre la fin des structures WSANAMESPACE_INFO fixes et la fin de la mémoire tampon. Le nombre de structures WSANAMESPACE_INFO renseignées est retourné par le
Fonction WSAEnumNameSpaceProviders .

Chaque entrée de structure WSANAMESPACE_INFO contient les informations spécifiques au fournisseur sur l’entrée d’espace de noms transmise aux fonctions WSCInstallNameSpace et WSCInstallNameSpace32 lors de l’installation du fournisseur d’espaces de noms.

La fonction WSAEnumNameSpaceProvidersEx est une version améliorée de la fonction WSAEnumNameSpaceProviders . La fonction WSCEnumNameSpaceProvidersEx32 est une version améliorée de la fonction WSAEnumNameSpaceProviders qui retourne des informations sur les fournisseurs d’espaces de noms 32 bits disponibles pour une utilisation sur les plateformes 64 bits.

Exemple de code

L’exemple suivant illustre l’utilisation de la fonction WSAEnumNameSpaceProviders pour récupérer des informations sur les fournisseurs d’espaces de noms 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;
    int iError = 0;

    INT iNuminfo = 0;

    int i;
    

    // Allocate a 4K buffer to retrieve all the namespace providers
    DWORD dwInitialBufferLen = 4096;
    DWORD dwBufferLen;
    LPWSANAMESPACE_INFO lpProviderInfo;
    
    
    // variables needed for converting provider GUID to a string
    int iRet = 0;
    WCHAR GuidString[40] = {0};

    // Set dwBufferLen to the initial buffer length
    dwBufferLen = dwInitialBufferLen;
    
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        wprintf(L"WSAStartup failed: %d\n", iResult);
        return 1;
    }
    
    lpProviderInfo = (LPWSANAMESPACE_INFO) MALLOC(dwBufferLen);
    if (lpProviderInfo == NULL) {
        wprintf(L"Memory allocation for providers buffer failed\n");
        WSACleanup();
        return 1;
    }
    
    iNuminfo = WSAEnumNameSpaceProviders(&dwBufferLen, lpProviderInfo);
    if (iNuminfo == SOCKET_ERROR) {
        iError = WSAGetLastError();
        if (iError == WSAEFAULT && dwBufferLen != dwInitialBufferLen) {
            wprintf(L"WSAEnumNameSpaceProviders failed with too small a buffer\n");
            wprintf(L"  Increasing the buffer to %u\n\n", dwBufferLen);
            if (lpProviderInfo) {
               FREE(lpProviderInfo);
               lpProviderInfo = NULL;
            }        

            lpProviderInfo = (LPWSANAMESPACE_INFO) MALLOC(dwBufferLen);
            if (lpProviderInfo == NULL) {
                wprintf(L"Memory allocation for providers buffer failed\n");
                WSACleanup();
               return 1;
            }

            iNuminfo = WSAEnumNameSpaceProviders(&dwBufferLen, lpProviderInfo);
            if (iNuminfo == SOCKET_ERROR) {
               wprintf(L"WSAEnumNameSpaceProviders failed with error: %d\n",
                  WSAGetLastError() );
               if (lpProviderInfo) {
                  FREE(lpProviderInfo);
                  lpProviderInfo = NULL;
               }        
               WSACleanup();
               return 1;
            }
            else
                wprintf(L"\n");   
        } 
        else {   
            wprintf(L"WSAEnumNameSpaceProviders failed with error: %d\n",
               WSAGetLastError() );
            if (lpProviderInfo) {
               FREE(lpProviderInfo);
               lpProviderInfo = NULL;
            }        
           WSACleanup();
           return 1;
        } 
     }

       wprintf(L"WSAEnumNameSpaceProviders succeeded with provider data count = %d\n\n",
           iNuminfo);
       for (i= 0; i < iNuminfo; i++) {
            iRet = StringFromGUID2(lpProviderInfo[i].NSProviderId, (LPOLESTR) &GuidString, 39); 
            if (iRet == 0)
                wprintf(L"StringFromGUID2 failed\n");
            else 
                wprintf(L"NameSpace ProviderId[%u] = %ws\n",i, GuidString);

           wprintf(L"NameSpace[%u] = ", i);
           switch (lpProviderInfo[i].dwNameSpace) {
           case NS_DNS:
               wprintf(L"Domain Name System (NS_DNS)\n");
               break;
           case NS_WINS:
               wprintf(L"Windows Internet Naming Service (NS_WINS)\n");
               break;
           case NS_NETBT:
               wprintf(L"NetBIOS (NS_NETBT)\n");
               break;
           case NS_NTDS:
               wprintf(L"Windows NT Directory Services (NS_NTDS)\n");
               break;
           case NS_NLA:
               wprintf(L"Network Location Awareness (NS_NLA)\n");
               break;
           // following values only defined on Vista and later
#if(_WIN32_WINNT >= 0x0600)
           case NS_BTH:
               wprintf(L"Bluetooth (NS_BTH)\n");
               break;
           case NS_EMAIL:
               wprintf(L"Email (NS_EMAIL)\n");
               break;
           case NS_PNRPNAME:
               wprintf(L"Peer-to-peer (NS_PNRPNAME)\n");
               break;
           case NS_PNRPCLOUD:
               wprintf(L"Peer-to-peer collection (NS_PNRPCLOUD)\n");
               break;
#endif
           default:
               wprintf(L"Other value (%u)\n", lpProviderInfo[i].dwNameSpace);             
               break;
           }    

           if (lpProviderInfo[i].fActive)
               wprintf(L"Namespace[%u] is active\n", i);
           else    
               wprintf(L"Namespace[%u] is inactive\n", i);

           wprintf(L"NameSpace Version[%u] = %u\n", i, lpProviderInfo[i].dwVersion);

           wprintf(L"Namespace Identifier[%u] = %ws\n\n", i, lpProviderInfo[i].lpszIdentifier);
       }           

    if (lpProviderInfo) {
        FREE(lpProviderInfo);
        lpProviderInfo = NULL;
    }        
    WSACleanup();
    
    return 0;
}

Windows Phone 8 : La fonction WSAEnumNameSpaceProvidersW 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 WSAEnumNameSpaceProvidersW est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Notes

L’en-tête winsock2.h définit WSAEnumNameSpaceProviders 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. 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

   
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

Voir aussi

WSAEnumNameSpaceProvidersEx

WSAGetLastError

WSANAMESPACE_INFO

WSAStartup

WSCEnumNameSpaceProvidersEx32

WSCInstallNameSpace

WSCInstallNameSpaceEx

Winsock Functions

Référence Winsock