NetGroupGetUsers-Funktion (lmaccess.h)

Artikel
08/24/2023

Die NetGroupGetUsers-Funktion ruft eine Liste der Mitglieder einer bestimmten globalen Gruppe in der Sicherheitsdatenbank ab, wobei es sich um die SAM-Datenbank (Security Accounts Manager) oder im Fall von Domänencontrollern um active Directory handelt.

Syntax

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

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] groupname

Ein Zeiger auf eine konstante Zeichenfolge, die den Namen der globalen Gruppe angibt, deren Mitglieder aufgelistet werden sollen. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] level

Die Informationsebene der angeforderten Daten. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
0	Gibt die Mitgliedernamen der globalen Gruppe zurück. Der bufptr-Parameter verweist auf ein Array von GROUP_USERS_INFO_0 Strukturen.
1	Gibt die Mitgliedernamen und Attribute der globalen Gruppe zurück. Der bufptr-Parameter verweist auf ein Array von GROUP_USERS_INFO_1 Strukturen.

[out] bufptr

Ein Zeiger auf die Adresse des Puffers, der die Informationsstruktur empfängt. Das System weist den Speicher für diesen Puffer zu. Sie müssen die NetApiBufferFree-Funktion aufrufen, um die Speicherzuordnung zu beheben. Beachten Sie, dass Sie den Puffer auch dann freigeben müssen, wenn die 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, 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 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.

[in, out] ResumeHandle

Ein Zeiger auf eine Variable, die ein Resume-Handle enthält, das zum Fortsetzen einer vorhandenen Benutzeraufzählung verwendet wird. Das Handle sollte beim ersten Aufruf 0 sein und für nachfolgende Aufrufe unverändert bleiben. Wenn der ResumeHandle-ParameterNULL 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 als anderer Wert als 0 oder 1 angegeben wurde.
ERROR_MORE_DATA	Weitere Einträge sind verfügbar. Geben Sie einen ausreichend großen Puffer an, um alle Einträge zu empfangen.
ERROR_NOT_ENOUGH_MEMORY	Zum Abschließen des Vorgangs war nicht genügend Arbeitsspeicher verfügbar.
NERR_InvalidComputer	Der Computername ist ungültig.
NERR_GroupNotFound	Der globale Gruppenname in der Struktur, auf die der bufptr-Parameter verweist, konnte nicht gefunden werden.
NERR_InternalError	Interner Fehler.

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 Sicherheitsbeschreibung des Group-Objekts wird verwendet, um die Zugriffsprüfung für diese Funktion durchzuführen.

Um einem Benutzer die Mitgliedschaft in einer vorhandenen globalen Gruppe zu gewähren, können Sie die NetGroupAddUser-Funktion aufrufen. Um einen Benutzer aus einer globalen Gruppe zu entfernen, rufen Sie die NetGroupDelUser-Funktion auf. Informationen zum Ersetzen der Mitgliedschaft einer globalen Gruppe finden Sie unter NetGroupSetUsers.

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.

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