NetUserEnum-Funktion (lmaccess.h)
Die NetUserEnum-Funktion ruft Informationen zu allen Benutzerkonten auf einem Server ab.
Syntax
NET_API_STATUS NET_API_FUNCTION NetUserEnum(
[in] LPCWSTR servername,
[in] DWORD level,
[in] DWORD filter,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in, out] PDWORD resume_handle
);
Parameter
[in] servername
Ein Zeiger auf eine konstante Zeichenfolge, die den DNS- oder NetBIOS-Namen des Remoteservers angibt, auf dem die Funktion ausgeführt werden soll. Wenn dieser Parameter NULL ist, wird der lokale Computer verwendet.
[in] level
Gibt die Informationsebene der Daten an. Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
|
Gibt Benutzerkontonamen zurück. Der bufptr-Parameter verweist auf ein Array von USER_INFO_0 Strukturen. |
|
Gibt detaillierte Informationen zu Benutzerkonten zurück. Der bufptr-Parameter verweist auf ein Array von USER_INFO_1 Strukturen. |
|
Gibt detaillierte Informationen zu Benutzerkonten zurück, einschließlich Autorisierungsstufen und Anmeldeinformationen. Der bufptr-Parameter verweist auf ein Array von USER_INFO_2 Strukturen. |
|
Geben Sie detaillierte Informationen zu Benutzerkonten zurück, einschließlich Autorisierungsstufen, Anmeldeinformationen, RIDs für den Benutzer und die primäre Gruppe sowie Profilinformationen. Der bufptr-Parameter verweist auf ein Array von USER_INFO_3 Strukturen. |
|
Gibt Benutzer- und Kontonamen und Kommentare zurück. Der bufptr-Parameter verweist auf ein Array von USER_INFO_10 Strukturen. |
|
Gibt detaillierte Informationen zu Benutzerkonten zurück. Der bufptr-Parameter verweist auf ein Array von USER_INFO_11 Strukturen. |
|
Gibt den Namen und bezeichner des Benutzers sowie verschiedene Kontoattribute zurück. Der bufptr-Parameter verweist auf ein Array von USER_INFO_20 Strukturen. Beachten Sie, dass unter Windows XP und höher stattdessen empfohlen wird, USER_INFO_23 zu verwenden. |
[in] filter
Ein Wert, der die Benutzerkontotypen angibt, die in die Enumeration eingeschlossen werden sollen. Der Wert 0 gibt an, dass alle normalen Benutzer-, Vertrauens- und Computerkontodaten enthalten sein sollten.
Dieser Parameter kann auch eine Kombination der folgenden Werte sein.
[out] bufptr
Ein Zeiger auf den Puffer, der die Daten empfängt. Das Format dieser Daten hängt vom Wert des Ebenenparameters ab.
Der Puffer für diese Daten wird vom System zugewiesen, und die Anwendung muss die NetApiBufferFree-Funktion aufrufen, um den zugewiesenen Arbeitsspeicher freizugeben, wenn die zurückgegebenen Daten nicht mehr benötigt werden. Beachten Sie, dass Sie den Puffer auch dann freigeben müssen, wenn die NetUserEnum-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, weist die NetUserEnum-Funktion den für die Daten erforderlichen Arbeitsspeicher zu. Wenn Sie in diesem Parameter einen anderen Wert angeben, kann die Anzahl der Von der Funktion zurückgegebenen Bytes eingeschränkt werden. 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 aufgelisteten Elemente empfängt.
[out] totalentries
Ein Zeiger auf einen Wert, der die Gesamtanzahl von Einträgen empfängt, die aus der aktuellen Position des Fortsetzens hätten aufgezählt werden können. Beachten Sie, dass Anwendungen diesen Wert nur als Hinweis betrachten sollten. Wenn Ihre Anwendung mit einem Windows 2000- oder höher-Domänencontroller kommuniziert, sollten Sie den ADSI-LDAP-Anbieter in Betracht ziehen, um diese Art von Daten effizienter abzurufen. Der ADSI-LDAP-Anbieter implementiert eine Reihe von ADSI-Objekten, die verschiedene ADSI-Schnittstellen unterstützen. Weitere Informationen finden Sie unter ADSI-Dienstanbieter.
LAN-Manager: Wenn es sich bei dem Aufruf um einen Computer handelt, auf dem LAN Manager 2 ausgeführt wird. x, der totalentries-Parameter gibt immer die Gesamtzahl der Einträge in der Datenbank wider, unabhängig davon, wo er sich in der Fortsetzungssequenz befindet.
[in, out] resume_handle
Ein Zeiger auf einen Wert, der ein Lebenslaufhandle enthält, das zum Fortsetzen einer vorhandenen Benutzersuche verwendet wird. Das Handle sollte beim ersten Aufruf 0 sein und für nachfolgende Aufrufe unverändert bleiben. Wenn dieser Parameter NULL ist, wird kein Resume-Handle gespeichert.
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 | Beschreibung |
|---|---|
|
Der Benutzer besitzt keinen Zugriff auf die angeforderten Informationen. |
|
Die Ebene des Systemaufrufs ist falsch. Dieser Fehler wird zurückgegeben, wenn der Levelparameter auf einen Wert festgelegt ist, der nicht unterstützt wird. |
|
Der Puffer ist zu klein, um einen Eintrag zu enthalten. Es wurden keine Informationen in den Puffer geschrieben. |
|
Der Computername ist ungültig. |
|
Weitere Einträge sind verfügbar. Geben Sie einen ausreichend großen Puffer an, um alle Einträge zu empfangen. |
Hinweise
Die NetUserEnum-Funktion ruft Informationen zu allen Benutzerkonten auf einem angegebenen Remoteserver oder dem lokalen Computer ab.
Die NetQueryDisplayInformation-Funktion kann verwendet werden, um Benutzer-, Computer- oder globale Gruppenkontoinformationen für die Anzeige in Benutzeroberflächen schnell aufzulisten.
Wenn Sie für Active Directory programmieren, können Sie möglicherweise bestimmte ADSI-Methoden (Active Directory Service Interface) aufrufen, um dieselbe Funktionalität zu erzielen, die Sie durch aufrufen der Netzwerkverwaltungsbenutzerfunktionen erreichen können. Weitere Informationen finden Sie unter IADsUser und IADsComputer.
Wenn Sie die NetUserEnum-Funktion auf einem Domänencontroller aufrufen, auf dem Active Directory ausgeführt wird, wird der Zugriff basierend auf der Zugriffssteuerungsliste (Access Control List, ACL) für das sicherungsfähige Objekt zugelassen oder verweigert. Die Standard-ACL ermöglicht es allen authentifizierten Benutzern und Mitgliedern der Gruppe "Pre-Windows 2000-kompatibler Zugriff", die Informationen anzuzeigen. Wenn Sie diese Funktion auf einem Mitgliedsserver oder einer Arbeitsstation aufrufen, können alle authentifizierten Benutzer die Informationen anzeigen. Informationen zum anonymen Zugriff und zum Einschränken des anonymen Zugriffs auf diesen Plattformen finden Sie unter Sicherheitsanforderungen für die Netzwerkverwaltungsfunktionen. Weitere Informationen zu ACLs, ACEs und Zugriffstoken finden Sie unter Access Control Modell.
Die NetUserEnum-Funktion gibt nur Informationen zurück, auf die der Aufrufer Lesezugriff hat. Der Aufrufer muss über Listeninhaltszugriff auf das Domain-Objekt verfügen und den Gesamten SAM-Domänenzugriff auf das SAM Server-Objekt im Systemcontainer aufzählen.
Die Funktion LsaEnumerateTrustedDomains oder LsaEnumerateTrustedDomainsEx kann verwendet werden, um die Namen und SIDs von Domänen abzurufen, die von einem LSA-Richtlinienobjekt (Local Security Authority) vertrauenswürdig sind.
Die NetUserEnum-Funktion gibt nicht alle Systembenutzer zurück. Es gibt nur die Benutzer zurück, die mit einem Aufruf der NetUserAdd-Funktion hinzugefügt wurden. Es gibt keine Garantie, dass die Liste der Benutzer in sortierter Reihenfolge zurückgegeben wird.
Wenn Sie die NetUserEnum-Funktion aufrufen und die Informationsebene 1, 2 oder 3 für den Level-Parameter angeben, wird das Kennwortelement jeder abgerufenen Struktur auf NULL festgelegt, um die Kennwortsicherheit zu gewährleisten.
Benutzerkontonamen sind auf 20 Zeichen und Gruppennamen auf 256 Zeichen beschränkt. Darüber hinaus können Kontonamen nicht durch einen Punkt beendet werden und dürfen keine Kommas oder eines der folgenden druckbaren Zeichen enthalten: ", /, , [, ], :, |, <, , >, +, =, ;, ?, *. Namen dürfen auch keine Zeichen im Bereich 1-31 enthalten, die nicht druckbar sind.
Die NetUserEnum-Funktion unterstützt keinen Parameter der Ebene 4 und die USER_INFO_4 Struktur. Die NetUserGetInfo-Funktion unterstützt den Levelparameter 4 und die USER_INFO_4-Struktur .
Beispiele
Im folgenden Codebeispiel wird veranschaulicht, wie Informationen zu den Benutzerkonten auf einem Server mit einem Aufruf der NetUserEnum-Funktion abgerufen werden. Im Beispiel wird NetUserEnum aufgerufen, wobei die Informationsebene 0 (USER_INFO_0) angegeben wird, um nur globale Benutzerkonten aufzulisten. Wenn der Aufruf erfolgreich ist, durchläuft der Code die Einträge und gibt den Namen jedes Benutzerkontos aus. Schließlich gibt das Codebeispiel den Speicher frei, der für den Informationspuffer zugewiesen ist, und gibt eine Gesamtzahl der aufgezählten Benutzer aus.
#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[])
{
LPUSER_INFO_0 pBuf = NULL;
LPUSER_INFO_0 pTmpBuf;
DWORD dwLevel = 0;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwResumeHandle = 0;
DWORD i;
DWORD dwTotalCount = 0;
NET_API_STATUS nStatus;
LPTSTR pszServerName = NULL;
if (argc > 2)
{
fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
exit(1);
}
// The server is not the default local computer.
//
if (argc == 2)
pszServerName = (LPTSTR) argv[1];
wprintf(L"\nUser account on %s: \n", pszServerName);
//
// Call the NetUserEnum function, specifying level 0;
// enumerate global user account types only.
//
do // begin do
{
nStatus = NetUserEnum((LPCWSTR) pszServerName,
dwLevel,
FILTER_NORMAL_ACCOUNT, // global users
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
{
if ((pTmpBuf = pBuf) != NULL)
{
//
// Loop through the entries.
//
for (i = 0; (i < dwEntriesRead); i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
//
// Print the name of the user account.
//
wprintf(L"\t-- %s\n", pTmpBuf->usri0_name);
pTmpBuf++;
dwTotalCount++;
}
}
}
//
// Otherwise, print the system error.
//
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
{
NetApiBufferFree(pBuf);
pBuf = NULL;
}
}
// Continue to call NetUserEnum while
// there are more entries.
//
while (nStatus == ERROR_MORE_DATA); // end do
//
// Check again for allocated memory.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
//
// Print the final count of users enumerated.
//
fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);
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 | lmaccess.h (lm.h einschließen) |
| Bibliothek | Netapi32.lib |
| DLL | Netapi32.dll |