Funzione NetServerEnum (lmserver.h)

La funzione NetServerEnum elenca tutti i server del tipo specificato visibili in un dominio.

Sintassi

NET_API_STATUS NET_API_FUNCTION NetServerEnum(
  [in, optional]      LMCSTR  servername,
  [in]                DWORD   level,
  [out]               LPBYTE  *bufptr,
  [in]                DWORD   prefmaxlen,
  [out]               LPDWORD entriesread,
  [out]               LPDWORD totalentries,
  [in]                DWORD   servertype,
  [in, optional]      LMCSTR  domain,
  [in, out, optional] LPDWORD resume_handle
);

Parametri

[in, optional] servername

Riservati; deve essere NULL.

[in] level

Livello di informazioni dei dati richiesti. Questo parametro può avere uno dei valori seguenti.

[out] bufptr

Puntatore al buffer che riceve i dati. Il formato di questi dati dipende dal valore del parametro di livello . Questo buffer viene allocato dal sistema e deve essere liberato usando la funzione NetApiBufferFree . Si noti che è necessario liberare il buffer anche se la funzione ha esito negativo con ERROR_MORE_DATA.

[in] prefmaxlen

Lunghezza massima preferita dei dati restituiti, in byte. Se si specifica MAX_PREFERRED_LENGTH, la funzione alloca la quantità di memoria necessaria per i dati. Se si specifica un altro valore in questo parametro, può limitare il numero di byte restituiti dalla funzione. Se le dimensioni del buffer non sono sufficienti per contenere tutte le voci, la funzione restituisce ERROR_MORE_DATA. Per altre informazioni, vedere Buffer delle funzioni di gestione della rete e lunghezze del buffer delle funzioni di gestione della rete.

[out] entriesread

Puntatore a un valore che riceve il conteggio degli elementi effettivamente enumerati.

[out] totalentries

Puntatore a un valore che riceve il numero totale di server e workstation visibili nella rete. Si noti che le applicazioni devono considerare questo valore solo come hint.

[in] servertype

Valore che filtra le voci del server da restituire dall'enumerazione. Questo parametro può essere una combinazione dei valori seguenti definiti nel file di intestazione Lmserver.h .

[in, optional] domain

Puntatore a una stringa costante che specifica il nome del dominio per il quale deve essere restituito un elenco di server. Il nome di dominio deve essere un nome di dominio NetBIOS ,ad esempio Microsoft. La funzione NetServerEnum non supporta nomi in stile DNS, ad esempio microsoft.com.

Se questo parametro è NULL, il dominio primario è implicito.

[in, out, optional] resume_handle

Riservati; deve essere impostato su zero.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene NERR_Success.

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti:

Commenti

La funzione NetServerEnum viene utilizzata per elencare tutti i server del tipo specificato visibili in un dominio. Ad esempio, un'applicazione può chiamare NetServerEnum per elencare solo tutti i controller di dominio o tutti i server che eseguono solo istanze di SQL Server.

Un'applicazione combina le maschere di bit per vari tipi di server nel parametro servertype per elencare diversi tipi. Ad esempio, un valore di SV_TYPE_WORKSTATION | SVTYPE_SERVER (0x00000003) combina le maschere di bit per SV_TYPE_WORKSTATION (0x00000001) e SV_TYPE_SERVER (0x00000002).

Se sono necessarie altre informazioni per un server specifico, chiamare la funzione WNetEnumResource .

Per eseguire correttamente la funzione NetServerEnum non è necessaria alcuna appartenenza a gruppi speciali.

Se si specifica il valore SV_TYPE_LOCAL_LIST_ONLY, la funzione NetServerEnum restituisce l'elenco di server gestiti internamente dal browser. Questo significa solo nel master browser (o in un computer che è stato il master browser in passato). Il master browser è il computer che dispone attualmente dei diritti per determinare quali computer possono essere server o workstation nella rete.

Se non sono presenti server che corrispondono ai tipi specificati nel parametro servertype , la funzione NetServerEnum restituisce il parametro bufptr come valori NULL e DWORD a cui puntano i parametri vociread e totalentries vengono impostati su zero.

La funzione NetServerEnum dipende dal servizio browser in esecuzione e installato. Se non viene trovato alcun server browser, NetServerEnum ha esito negativo con ERROR_NO_BROWSER_SERVERS_FOUND.

Se si esegue la programmazione per Active Directory, è possibile chiamare determinati metodi ADSI (Active Directory Service Interface) per ottenere la stessa funzione che è possibile ottenere chiamando le funzioni del server di gestione di rete. Per altre informazioni, vedere IADsComputer.

Esempio

Nell'esempio di codice seguente viene illustrato come elencare tutti i server visibili in un dominio con una chiamata alla funzione NetServerEnum . L'esempio chiama NetServerEnum, specificando il livello di informazioni 101 ( SERVER_INFO_101). Se vengono trovati server, il codice di esempio scorre le voci e stampa i dati recuperati. Se il server è un controller di dominio, identifica il server come controller di dominio primario (PDC) o un controller di dominio di backup. L'esempio stampa anche il numero totale di voci disponibili e un suggerimento sul numero di voci effettivamente enumerate, avvisando l'utente se tutte le voci non sono state enumerate. Infine, l'esempio libera la memoria allocata per il buffer delle informazioni.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t * argv[])
{
    LPSERVER_INFO_101 pBuf = NULL;
    LPSERVER_INFO_101 pTmpBuf;
    DWORD dwLevel = 101;
    DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
    DWORD dwEntriesRead = 0;
    DWORD dwTotalEntries = 0;
    DWORD dwTotalCount = 0;
    DWORD dwServerType = SV_TYPE_SERVER;        // all servers
    DWORD dwResumeHandle = 0;
    NET_API_STATUS nStatus;
    LPWSTR pszServerName = NULL;
    LPWSTR pszDomainName = NULL;
    DWORD i;

    if (argc > 2) 
    {
        fwprintf(stderr, L"Usage: %s [DomainName]\n", argv[0]);
        exit(1);
    }
    // The request is not for the primary domain.
    //
    if (argc == 2)
        pszDomainName = argv[1];
    //
    // Call the NetServerEnum function to retrieve information
    //  for all servers, specifying information level 101.
    //
    nStatus = NetServerEnum(pszServerName,
                            dwLevel,
                            (LPBYTE *) & pBuf,
                            dwPrefMaxLen,
                            &dwEntriesRead,
                            &dwTotalEntries,
                            dwServerType, 
                            pszDomainName, 
                            &dwResumeHandle);
    //
    // If the call succeeds,
    //
    if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA)) {
        if ((pTmpBuf = pBuf) != NULL) {
            //
            // Loop through the entries and 
            //  print the data for all server types.
            //
            for (i = 0; i < dwEntriesRead; i++) {
                assert(pTmpBuf != NULL);

                if (pTmpBuf == NULL) {
                    fprintf(stderr, "An access violation has occurred\n");
                    break;
                }

                printf("\tPlatform: %d\n", pTmpBuf->sv101_platform_id);
                wprintf(L"\tName:     %s\n", pTmpBuf->sv101_name);
                printf("\tVersion:  %d.%d\n",
                       pTmpBuf->sv101_version_major,
                       pTmpBuf->sv101_version_minor);
                printf("\tType:     %d", pTmpBuf->sv101_type);
                //
                // Check to see if the server is a domain controller;
                //  if so, identify it as a PDC or a BDC.
                //
                if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_CTRL)
                    wprintf(L" (PDC)");
                else if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_BAKCTRL)
                    wprintf(L" (BDC)");

                printf("\n");
                //
                // Also print the comment associated with the server.
                //
                wprintf(L"\tComment:  %s\n\n", pTmpBuf->sv101_comment);

                pTmpBuf++;
                dwTotalCount++;
            }
            // Display a warning if all available entries were
            //  not enumerated, print the number actually 
            //  enumerated, and the total number available.

            if (nStatus == ERROR_MORE_DATA) {
                fprintf(stderr, "\nMore entries available!!!\n");
                fprintf(stderr, "Total entries: %d", dwTotalEntries);
            }

            printf("\nEntries enumerated: %d\n", dwTotalCount);

        } else {
            printf("No servers were found\n");
            printf("The buffer (bufptr) returned was NULL\n");
            printf("  entriesread: %d\n", dwEntriesRead);
            printf("  totalentries: %d\n", dwEntriesRead);
        }

    } else
        fprintf(stderr, "NetServerEnum failed with error: %d\n", nStatus);
    //
    // Free the allocated buffer.
    //
    if (pBuf != NULL)
        NetApiBufferFree(pBuf);

    return 0;
}

Requisiti

Vedi anche

NetQueryDisplayInformation

NetServerDiskEnum

Funzioni di gestione di rete

Panoramica della gestione della rete

SERVER_INFO_100

SERVER_INFO_101

Funzioni del server