NetUserEnum-Funktion (lmaccess.h)

Artikel
03/01/2024

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
0	Gibt Benutzerkontonamen zurück. Der bufptr-Parameter verweist auf ein Array von USER_INFO_0 Strukturen.
1	Gibt detaillierte Informationen zu Benutzerkonten zurück. Der bufptr-Parameter verweist auf ein Array von USER_INFO_1 Strukturen.
2	Gibt detaillierte Informationen zu Benutzerkonten zurück, einschließlich Autorisierungsstufen und Anmeldeinformationen. Der bufptr-Parameter verweist auf ein Array von USER_INFO_2 Strukturen.
3	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.
10	Gibt Benutzer- und Kontonamen und Kommentare zurück. Der bufptr-Parameter verweist auf ein Array von USER_INFO_10 Strukturen.
11	Gibt detaillierte Informationen zu Benutzerkonten zurück. Der bufptr-Parameter verweist auf ein Array von USER_INFO_11 Strukturen.
20	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.

Wert	Bedeutung
FILTER_TEMP_DUPLICATE_ACCOUNT	Listet Kontodaten für Benutzer auf, deren primäres Konto sich in einer anderen Domäne befindet. Dieser Kontotyp bietet Benutzern Zugriff auf diese Domäne, aber nicht auf eine Domäne, die dieser Domäne vertraut. Der Benutzer-Manager verweist auf diesen Kontotyp als lokales Benutzerkonto.
FILTER_NORMAL_ACCOUNT	Listet normale Benutzerkontodaten auf. Dieser Kontotyp ist einem typischen Benutzer zugeordnet.
FILTER_INTERDOMAIN_TRUST_ACCOUNT	Listet Zwischendomänenvertrauenskontodaten auf. Dieser Kontotyp ist einem Vertrauenskonto für eine Domäne zugeordnet, die anderen Domänen vertraut.
FILTER_WORKSTATION_TRUST_ACCOUNT	Listet Arbeitsstations- oder Mitgliedsserver-Vertrauensstellungskontodaten auf. Dieser Kontotyp ist einem Computerkonto für einen Computer zugeordnet, der Mitglied der Domäne ist.
FILTER_SERVER_TRUST_ACCOUNT	Listet Die Computerkontodaten des Mitgliedsservers auf. Dieser Kontotyp ist einem Computerkonto für einen Sicherungsdomänencontroller zugeordnet, der Mitglied der Domäne ist.

[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
ERROR_ACCESS_DENIED	Der Benutzer besitzt keinen Zugriff auf die angeforderten Informationen.
ERROR_INVALID_LEVEL	Die Ebene des Systemaufrufs ist falsch. Dieser Fehler wird zurückgegeben, wenn der Levelparameter auf einen Wert festgelegt ist, der nicht unterstützt wird.
NERR_BufTooSmall	Der Puffer ist zu klein, um einen Eintrag zu enthalten. Es wurden keine Informationen in den Puffer geschrieben.
NERR_InvalidComputer	Der Computername ist ungültig.
ERROR_MORE_DATA	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