NetServerEnum-Funktion (lmserver.h)

Die NetServerEnum-Funktion listet alle Server des angegebenen Typs auf, die in einer Domäne sichtbar sind.

Syntax

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
);

Parameter

[in, optional] servername

Reserviert; muss NULL sein.

[in] level

Die Informationsebene der angeforderten Daten. Dieser Parameter kann einen der folgenden Werte annehmen.

[out] bufptr

Ein Zeiger auf den Puffer, der die Daten empfängt. Das Format dieser Daten hängt vom Wert des level-Parameters ab. Dieser Puffer wird vom System zugeordnet und muss mithilfe der NetApiBufferFree-Funktion freigegeben werden. Beachten Sie, dass Sie den Puffer auch dann freigeben müssen, wenn die Funktion mit ERROR_MORE_DATA fehlschlägt.

[in] prefmaxlen

Die bevorzugte maximale Länge der zurückgegebenen Daten in Bytes. Wenn Sie MAX_PREFERRED_LENGTH angeben, ordnet die Funktion den für die Daten erforderlichen Arbeitsspeicher zu. Wenn Sie in diesem Parameter einen anderen Wert angeben, kann er die Anzahl der Bytes einschränken, die die Funktion zurückgibt. Wenn die Puffergröße nicht ausreicht, um alle Einträge aufzunehmen, gibt die Funktion ERROR_MORE_DATA zurück. Weitere Informationen finden Sie unter Netzwerkverwaltungsfunktionspuffer und Netzwerkverwaltungsfunktionspufferlängen.

[out] entriesread

Ein Zeiger auf einen Wert, der die Anzahl der tatsächlich aufgezählten Elemente empfängt.

[out] totalentries

Ein Zeiger auf einen Wert, der die Gesamtzahl der sichtbaren Server und Arbeitsstationen im Netzwerk empfängt. Beachten Sie, dass Anwendungen diesen Wert nur als Hinweis betrachten sollten.

[in] servertype

Ein -Wert, der die Servereinträge filtert, die von der Enumeration zurückgegeben werden sollen. Dieser Parameter kann eine Kombination der folgenden Werte sein, die in der Lmserver.h-Headerdatei definiert sind.

[in, optional] domain

Ein Zeiger auf eine konstante Zeichenfolge, die den Namen der Domäne angibt, für die eine Liste von Servern zurückgegeben werden soll. Der Domänenname muss ein NetBIOS-Domänenname sein (z. B. microsoft). Die NetServerEnum-Funktion unterstützt keine DNS-Namen (z. B. microsoft.com).

Wenn dieser Parameter NULL ist, wird die primäre Domäne impliziert.

[in, out, optional] resume_handle

Reserviert; muss auf 0 festgelegt werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.

Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes sein:

Hinweise

Die NetServerEnum-Funktion wird verwendet, um alle Server des angegebenen Typs aufzulisten, die in einer Domäne sichtbar sind. Beispielsweise kann eine Anwendung NetServerEnum aufrufen, um nur alle Domänencontroller oder alle Server aufzulisten, auf denen nur Instanzen von SQL Server ausgeführt werden.

Eine Anwendung kombiniert die Bitmasken für verschiedene Servertypen im Servertype-Parameter , um mehrere Typen aufzulisten. Beispielsweise ein Wert von SV_TYPE_WORKSTATION | SVTYPE_SERVER (0x00000003) kombiniert die Bitmasken für SV_TYPE_WORKSTATION (0x00000001) und SV_TYPE_SERVER (0x00000002).

Wenn Sie weitere Informationen für einen bestimmten Server benötigen, rufen Sie die WNetEnumResource-Funktion auf.

Für die erfolgreiche Ausführung der NetServerEnum-Funktion ist keine spezielle Gruppenmitgliedschaft erforderlich.

Wenn Sie den Wert SV_TYPE_LOCAL_LIST_ONLY angeben, gibt die NetServerEnum-Funktion die Liste der Server zurück, die der Browser intern verwaltet. Dies hat nur eine Bedeutung für den master Browser (oder auf einem Computer, der in der Vergangenheit der master Browser war). Der master Browser ist der Computer, der derzeit über Die Rechte verfügt, um zu bestimmen, welche Computer Server oder Arbeitsstationen im Netzwerk sein können.

Wenn keine Server gefunden werden, die mit den im servertype-Parameter angegebenen Typen übereinstimmen, gibt die NetServerEnum-Funktion den bufptr-Parameter als NULL zurück, und DWORD-Werte, auf die von den Parametern "entriesread " und "totalentries " verwiesen werden, werden auf Null festgelegt.

Die NetServerEnum-Funktion hängt vom installierten und ausgeführten Browserdienst ab. Wenn keine Browserserver gefunden werden, schlägt NetServerEnum mit ERROR_NO_BROWSER_SERVERS_FOUND fehl.

Wenn Sie für Active Directory programmieren, können Sie möglicherweise bestimmte ADSI-Methoden (Active Directory Service Interface) aufrufen, um dieselbe Funktion zu erreichen, die Sie durch aufrufen der Netzwerkverwaltungsserverfunktionen erreichen können. Weitere Informationen finden Sie unter IADsComputer.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie alle Server aufgelistet werden, die in einer Domäne mit einem Aufruf der NetServerEnum-Funktion sichtbar sind. Im Beispiel wird NetServerEnum aufgerufen, wobei die Informationsebene 101 ( SERVER_INFO_101) angegeben wird. Wenn Server gefunden werden, durchläuft der Beispielcode die Einträge und gibt die abgerufenen Daten aus. Wenn der Server ein Domänencontroller ist, wird der Server entweder als primärer Domänencontroller (PDC) oder als Sicherungsdomänencontroller (Backup Domain Controller, BDC) identifiziert. Das Beispiel gibt auch die Gesamtzahl der verfügbaren Einträge und einen Hinweis auf die Anzahl der tatsächlich aufgezählten Einträge aus, und warnt den Benutzer, wenn nicht alle Einträge aufgelistet wurden. Schließlich gibt das Beispiel den für den Informationspuffer zugewiesenen Arbeitsspeicher frei.

#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;
}

Anforderungen

Weitere Informationen

NetQueryDisplayInformation

NetServerDiskEnum

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung

SERVER_INFO_100

SERVER_INFO_101

Serverfunktionen