NetGroupEnum-Funktion (lmaccess.h)

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.

[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.

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

Weitere Informationen

GROUP_INFO_0

GROUP_INFO_1

GROUP_INFO_3

Gruppenfunktionen

NetApiBufferFree

NetGroupGetInfo

NetGroupGetUsers

NetQueryDisplayInformation

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung