NetGroupSetInfo-Funktion (lmaccess.h)

Artikel
08/24/2023

Die NetGroupSetInfo-Funktion legt die Parameter einer globalen Gruppe in der Sicherheitsdatenbank fest, bei der 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 NetGroupSetInfo(
  [in]  LPCWSTR servername,
  [in]  LPCWSTR groupname,
  [in]  DWORD   level,
  [in]  LPBYTE  buf,
  [out] LPDWORD parm_err
);

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

Zeiger auf eine konstante Zeichenfolge, die den Namen der globalen Gruppe angibt, für die Informationen festgelegt werden sollen. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] level

Gibt die Informationsebene der Daten an. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
0	Gibt einen globalen Gruppennamen an. Der buf-Parameter verweist auf eine GROUP_INFO_0-Struktur .
1	Gibt einen globalen Gruppennamen und einen Kommentar an. Der buf-Parameter verweist auf eine GROUP_INFO_1-Struktur .
2	Gibt detaillierte Informationen zur globalen Gruppe an. Der buf-Parameter verweist auf eine GROUP_INFO_2-Struktur . Beachten Sie, dass Sie unter Windows XP und höher stattdessen GROUP_INFO_3 verwenden sollten.
3	Gibt detaillierte Informationen zur globalen Gruppe an. Der buf-Parameter verweist auf eine GROUP_INFO_3-Struktur . Windows 2000: Diese Ebene wird nicht unterstützt.
1002	Gibt nur einen Kommentar zur globalen Gruppe an. Der buf-Parameter verweist auf eine GROUP_INFO_1002-Struktur .
1005	Gibt globale Gruppenattribute an. Der buf-Parameter verweist auf eine GROUP_INFO_1005-Struktur .

Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] buf

Zeiger auf einen Puffer, der die Daten enthält. Das Format dieser Daten hängt vom Wert des Ebenenparameters ab. Weitere Informationen finden Sie unter Netzwerkverwaltungsfunktionspuffer.

[out] parm_err

Zeiger auf einen Wert, der nach einem ERROR_INVALID_PARAMETER Fehler den Index des ersten Mitglieds der Gruppeninformationsstruktur empfängt. Wenn dieser Parameter NULL ist, wird der Index nicht bei einem Fehler zurückgegeben. 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_INVALID_PARAMETER	Einer der Funktionsparameter ist ungültig. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
NERR_InvalidComputer	Der Computername ist ungültig.
NERR_NotPrimary	Der Vorgang ist nur auf dem primären Domänencontroller der Domäne zulässig.
NERR_GroupNotFound	Der globale Gruppenname konnte nicht gefunden werden.
NERR_SpeGroupOp	Der Vorgang ist für bestimmte spezielle Gruppen nicht zulässig. Zu diesen Gruppen gehören Benutzergruppen, Administratorgruppen, lokale Gruppen und Gastgruppen.

Hinweise

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.

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 erlaubt nur Domänenadministratoren und Kontooperatoren, diese Funktion aufzurufen. Auf einem Mitgliedsserver oder einer Arbeitsstation können nur Administratoren und Power Users diese Funktion aufrufen. Weitere Informationen 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. In der Regel müssen Aufrufer Schreibzugriff auf das gesamte Objekt haben, damit Aufrufe dieser Funktion erfolgreich sind.

Der richtige Weg zum Festlegen des neuen Namens einer globalen Gruppe besteht darin, die NetGroupSetInfo-Funktion mithilfe einer GROUP_INFO_0-Struktur aufzurufen. Geben Sie den neuen Wert im grpi0_name-Member an. Wenn Sie eine GROUP_INFO_1 Struktur verwenden und den Wert im grpi1_name-Member angeben, wird der neue Namewert ignoriert.

Wenn die NetGroupSetInfo-Funktion ERROR_INVALID_PARAMETER zurückgibt, können Sie den parameter parm_err verwenden, um das erste ungültige Element der Gruppeninformationsstruktur anzugeben. (Eine Gruppeninformationsstruktur beginnt mit GROUP_INFO_, und ihr Format wird durch den Levelparameter angegeben.) In der folgenden Tabelle sind die Werte aufgeführt, die im parm_err-Parameter zurückgegeben werden können, und dem entsprechenden Strukturmember, der fehlerhaft ist. (Das Präfix grpi*_ gibt an, dass das Element mit mehreren Präfixen beginnen kann, z. B. grpi1_ oder grpi2_.)

Wert	Member
GROUP_NAME_PARMNUM	grpi*_name
GROUP_COMMENT_PARMNUM	grpi*_comment
GROUP_ATTRIBUTES_PARMNUM	grpi*_attributes

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.

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