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.
| Wert | Bedeutung |
|---|---|
|
Gibt Servernamen und Plattforminformationen zurück. Der bufptr-Parameter verweist auf ein Array von SERVER_INFO_100 Strukturen. |
|
Gibt Servernamen, Typen und zugeordnete Daten zurück. Der bufptr-Parameter verweist auf ein Array von SERVER_INFO_101 Strukturen. |
[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:
| Rückgabecode/-wert | BESCHREIBUNG |
|---|---|
|
Der Zugriff wurde verweigert. |
|
„Der Parameter ist falsch.“ |
|
Weitere Einträge sind verfügbar. Geben Sie einen ausreichend großen Puffer an, um alle Einträge zu empfangen. |
|
Es wurden keine Browserserver gefunden. |
|
Die Anforderung wird nicht unterstützt. |
|
Es ist ein Remotefehler aufgetreten, bei dem keine Daten vom Server zurückgegeben wurden. |
|
Der Serverdienst wurde nicht gestartet. |
|
Der Dienst wurde nicht gestartet. |
|
Der Arbeitsstationsdienst wurde nicht gestartet. Der lokale Arbeitsstationsdienst wird verwendet, um mit einem Remoteserver auf Downlevel zu kommunizieren. |
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
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | lmserver.h (lm.h einschließen) |
| Bibliothek | Netapi32.lib |
| DLL | Netapi32.dll |