Funzione WSAEnumNameSpaceProvidersA (winsock2.h)

Articolo
11/20/2024

La funzione WSAEnumNameSpaceProviders recupera informazioni sui provider di spazi dei nomi disponibili.

Sintassi

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

Parametri

[in, out] lpdwBufferLength

In caso di input, il numero di byte contenuti nel buffer a cui punta lpnspBuffer. Nell'output (se la funzione ha esito negativo e l'errore è WSAEFAULT), il numero minimo di byte da passare per il lpnspBuffer per recuperare tutte le informazioni richieste. Il buffer passato a WSAEnumNameSpaceProviders deve essere sufficiente per contenere tutte le informazioni sullo spazio dei nomi.

[out] lpnspBuffer

Buffer riempito con strutture WSANAMESPACE_INFO. Le strutture restituite si trovano consecutivamente all'inizio del buffer. Le informazioni sulle dimensioni delle variabili a cui fanno riferimento i puntatori nelle strutture puntano alle posizioni all'interno del buffer che si trovano tra la fine delle strutture a dimensione fissa e la fine del buffer. Il numero di strutture compilate è il valore restituito di WSAEnumNameSpaceProviders.

Valore restituito

La funzione WSAEnumNameSpaceProviders restituisce il numero di strutture WSANAMESPACE_INFO copiate in lpnspBuffer. In caso contrario, viene restituito il valore SOCKET_ERROR e un numero di errore specifico può essere recuperato chiamando WSAGetLastError.

Codice di errore	Significato
WSAEFAULT	Il parametro lpnspBuffer era un puntatore NULL null o la lunghezza del buffer, lpdwBufferLength, era troppo piccolo per ricevere tutte le strutture WSANAMESPACE_INFO pertinenti e le informazioni associate. Quando viene restituito questo errore, la lunghezza del buffer richiesta viene restituita nel parametro lpdwBufferLength.
WSANOTINITIALISED	Il WS2_32.DLL non è stato inizializzato. L'applicazione deve prima chiamare WSAStartup prima di chiamare qualsiasi funzione Windows Sockets.
WSA_NOT_ENOUGH_MEMORY	Memoria insufficiente per eseguire l'operazione.

Osservazioni

La funzione WSAEnumNameSpaceProviders restituisce informazioni sui provider di spazi dei nomi disponibili nel buffer a cui punta il parametro lpnspBuffer. Il buffer restituito contiene una matrice di strutture WSANAMESPACE_INFO che si trovano consecutivamente all'inizio del buffer. Le informazioni sulle dimensioni delle variabili a cui fanno riferimento i puntatori nelle strutture WSANAMESPACE_INFO puntano alle posizioni all'interno del buffer che si trovano tra la fine delle strutture WSANAMESPACE_INFO fisse e la fine del buffer. Il numero di strutture WSANAMESPACE_INFO riempite viene restituito dal
funzione WSAEnumNameSpaceProviders.

Ogni voce della struttura WSANAMESPACE_INFO contiene le informazioni specifiche del provider sulla voce dello spazio dei nomi passata al WSCInstallNameSpace e WSCInstallNameSpace32 funzioni quando è stato installato il provider di spazi dei nomi.

La funzione WSAEnumNameSpaceProvidersEx è una versione avanzata della funzione WSAEnumNameSpaceProviders. La funzione WSCEnumNameSpaceProvidersEx32 è una versione avanzata del WSAEnumNameSpaceProviders funzione che restituisce informazioni sui provider di spazi dei nomi a 32 bit disponibili per l'uso su piattaforme a 64 bit.

codice di esempio

Nell'esempio seguente viene illustrato l'uso della funzione di WSAEnumNameSpaceProviders per recuperare informazioni sui provider di spazi dei nomi disponibili.

#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 funzione di WSAEnumNameSpaceProvidersW è supportata per le app di Windows Phone Store in Windows Phone 8 e versioni successive.

windows 8.1 e Windows Server 2012 R2: la funzione di WSAEnumNameSpaceProvidersW è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Nota

L'intestazione winsock2.h definisce WSAEnumNameSpaceProviders come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	winsock2.h
libreria	Ws2_32.lib
dll	Ws2_32.dll