NetGroupEnum-Funktion (lmaccess.h)

Artikel
08/24/2023

Die NetGroupEnum-Funktion ruft Informationen zu jeder globalen Gruppe in der Sicherheitsdatenbank ab. Dabei handelt es sich um die SAM-Datenbank (Security Accounts Manager) oder im Fall von Domänencontrollern um die Active Directory-Datenbank.

Die NetQueryDisplayInformation-Funktion bietet einen effizienten Mechanismus zum Aufzählen globaler Gruppen. Wenn möglich, wird empfohlen, NetQueryDisplayInformation anstelle der NetGroupEnum-Funktion zu verwenden.

Syntax

NET_API_STATUS NET_API_FUNCTION NetGroupEnum(
  [in]      LPCWSTR    servername,
  [in]      DWORD      level,
  [out]     LPBYTE     *bufptr,
  [in]      DWORD      prefmaxlen,
  [out]     LPDWORD    entriesread,
  [out]     LPDWORD    totalentries,
  [in, out] PDWORD_PTR resume_handle
);

Parameter

[in] servername

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 den Namen der globalen Gruppe zurück. Der parameter bufptr verweist auf ein Array von GROUP_INFO_0 Strukturen.
1	Gibt den Namen der globalen Gruppe und einen Kommentar zurück. Der bufptr-Parameter verweist auf ein Array von GROUP_INFO_1 Strukturen.
2	Gibt detaillierte Informationen zur globalen Gruppe zurück. Der bufptr-Parameter verweist auf ein Array von GROUP_INFO_2 Strukturen. Beachten Sie, dass Unter Windows XP und höher empfohlen wird, stattdessen GROUP_INFO_3 zu verwenden.
3	Gibt detaillierte Informationen zur globalen Gruppe zurück. Der bufptr-Parameter verweist auf ein Array von GROUP_INFO_3 Strukturen. Windows 2000: Diese Ebene wird nicht unterstützt.

[out] bufptr

Zeiger auf den Puffer, um die globale Gruppeninformationsstruktur zu empfangen. Das Format dieser Daten hängt vom Wert des level-Parameters ab.

Das System weist den Speicher für diesen Puffer zu. Sie müssen die NetApiBufferFree-Funktion aufrufen, um die Zuordnung des Arbeitsspeichers aufzugeben. Beachten Sie, dass Sie den Puffer auch dann freigeben müssen, wenn die Funktion mit ERROR_MORE_DATA fehlschlägt.

[in] prefmaxlen

Gibt die bevorzugte maximale Länge der zurückgegebenen Daten in Bytes an. Wenn Sie MAX_PREFERRED_LENGTH angeben, ordnet die Funktion die Menge an Arbeitsspeicher zu, die zum Speichern der Daten erforderlich ist. 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

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

[out] totalentries

Zeiger auf einen Wert, der die Gesamtzahl der Einträge empfängt, die aus der aktuellen Position des Lebenslaufs hätten aufgezählt werden können. Die Gesamtzahl der Einträge ist nur ein Hinweis. Weitere Informationen zum Bestimmen der genauen Anzahl von Einträgen finden Sie im folgenden Abschnitt Hinweise.

[in, out] resume_handle

Zeiger auf eine Variable, die ein Resume-Handle enthält, das zum Fortsetzen der globalen Gruppenaufzählung verwendet wird. Das Handle sollte beim ersten Aufruf null 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.
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

Wenn Sie für Active Directory programmieren, können Sie möglicherweise bestimmte ADSI-Methoden (Active Directory Service Interface) aufrufen, um die gleiche Funktionalität zu erreichen, die Sie durch Aufrufen der Netzwerkverwaltungsgruppenfunktionen erreichen können. Weitere Informationen finden Sie unter IADsGroup.

Wenn Sie diese 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 Funktion gibt nur Informationen zurück, auf die der Aufrufer Lesezugriff hat. Der Aufrufer muss über Listeninhaltszugriff auf das Domain-Objekt und den Zugriff auf die gesamte SAM-Domäne auf das SAM Server-Objekt im Systemcontainer aufzählen.

Um die genaue Gesamtanzahl von Gruppen zu ermitteln, müssen Sie die gesamte Struktur aufzählen, was ein kostspieliger Vorgang sein kann. Um die gesamte Struktur aufzulisten, verwenden Sie den Parameter resume_handle , um die Enumeration für aufeinanderfolgende Aufrufe fortzusetzen, und verwenden Sie den Entriesread-Parameter , um die Gesamtzahl der Gruppen zu sammeln. Wenn Ihre Anwendung mit einem Domänencontroller kommuniziert, sollten Sie die Verwendung des ADSI-LDAP-Anbieters 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.

Benutzerkontennamen sind auf 20 Zeichen und Gruppennamen auf 256 Zeichen beschränkt. Darüber hinaus können Kontonamen nicht durch einen Punkt beendet werden, und sie dürfen keine Kommas oder eines der folgenden druckbaren Zeichen enthalten: ", /, , [, ], ], :, |, <, , >+, =, ;, ?, *. Namen können auch keine Zeichen im Bereich 1 bis 31 enthalten, die nicht druckbar sind.

Anforderungen


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