NetLocalGroupEnum-Funktion (lmaccess.h)

Artikel
08/24/2023

Die NetLocalGroupEnum-Funktion gibt Informationen zu jedem lokalen Gruppenkonto auf dem angegebenen Server zurück.

Syntax

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

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 lokale Gruppennamen zurück. Der parameter bufptr verweist auf ein Array von LOCALGROUP_INFO_0 Strukturen.
1	Gibt lokale Gruppennamen und den Kommentar zurück, der jeder Gruppe zugeordnet ist. Der parameter bufptr verweist auf ein Array von LOCALGROUP_INFO_1 Strukturen.

[out] bufptr

Zeiger auf die Adresse des Puffers, der die Informationsstruktur 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

Gibt die bevorzugte maximale Länge der zurückgegebenen Daten in Bytes an. 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

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

[out] totalentries

Zeiger auf einen Wert, der die ungefähre Gesamtzahl der Einträge empfängt, die von 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] resumehandle

Zeiger auf einen Wert, der ein Resume-Handle enthält, das zum Fortsetzen einer vorhandenen lokalen Gruppensuche 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. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

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_MORE_DATA	Weitere Einträge sind verfügbar. Geben Sie einen ausreichend großen Puffer an, um alle Einträge zu empfangen.
NERR_InvalidComputer	Der Computername ist ungültig.
NERR_BufTooSmall	Der Rückgabepuffer ist zu klein.

Hinweise

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 Gesamtzahl der lokalen Gruppen zu ermitteln, müssen Sie die gesamte Struktur auflisten, was zu einem kostspieligen Vorgang führen kann. Um die gesamte Struktur aufzulisten, verwenden Sie den resumehandle-Parameter , um die Enumeration für aufeinanderfolgende Aufrufe fortzusetzen, und verwenden Sie den Entriesread-Parameter , um die Gesamtanzahl lokaler Gruppen zu akkumulieren. 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.

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 lokalen Netzwerkverwaltungsgruppenfunktionen erreichen können. Weitere Informationen finden Sie unter IADsGroup.

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