NetLocalGroupAdd-Funktion (lmaccess.h)

Artikel
08/24/2023

Die NetLocalGroupAdd-Funktion erstellt eine lokale Gruppe in der Sicherheitsdatenbank, 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 NetLocalGroupAdd(
  [in]  LPCWSTR servername,
  [in]  DWORD   level,
  [in]  LPBYTE  buf,
  [out] LPDWORD parm_err
);

Parameter

[in] servername

Ein Zeiger auf eine 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

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

Wert	Bedeutung
0	Ein lokaler Gruppenname. Der buf-Parameter verweist auf eine LOCALGROUP_INFO_0 Struktur.
1	Ein lokaler Gruppenname und ein Kommentar, der der Gruppe zugeordnet werden soll. Der buf-Parameter verweist auf eine LOCALGROUP_INFO_1-Struktur .

[in] buf

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

[out] parm_err

Ein Zeiger auf einen Wert, der den Index des ersten Elements der lokalen Gruppeninformationsstruktur empfängt, um den ERROR_INVALID_PARAMETER Fehler zu verursachen. Wenn dieser Parameter NULL ist, wird der Index nicht bei einem Fehler zurückgegeben. Weitere Informationen finden Sie im Abschnitt Hinweise im Thema NetLocalGroupSetInfo .

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 Aufrufer verfügt nicht über den entsprechenden Zugriff, um den Vorgang abzuschließen.
ERROR_ALIAS_EXISTS	Die angegebene lokale Gruppe ist bereits vorhanden. Dieser Fehler wird zurückgegeben, wenn das Gruppennamenselement in der Struktur, auf das vom buf-Parameter verwiesen wird, bereits als Alias verwendet wird.
ERROR_INVALID_LEVEL	Ein Levelparameter ist ungültig.
ERROR_INVALID_PARAMETER	Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn mindestens eines der Member in der Struktur, auf die vom buf-Parameter verwiesen wird, ungültig ist.
NERR_GroupExists	Der Gruppenname ist vorhanden. Dieser Fehler wird zurückgegeben, wenn das Gruppennamenselement in der Struktur, auf das vom buf-Parameter verwiesen wird, bereits als Gruppenname verwendet wird.
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_UserExists	Der Benutzername ist vorhanden. Dieser Fehler wird zurückgegeben, wenn das Gruppennamenselement in der Struktur, auf das vom buf-Parameter verwiesen wird, bereits als Benutzername verwendet wird.

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 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 Benutzercontainers wird verwendet, um die Zugriffsprüfung für diese Funktion durchzuführen. Der Aufrufer muss in der Lage sein, untergeordnete Objekte der Gruppenklasse zu erstellen.

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 die NetLocalGroupAdd-FunktionERROR_INVALID_PARAMETER zurückgibt und ein NULL-Zeiger in parm_err Parameter nicht übergeben wurde, gibt der parm_err-Parameter das erste Element der lokalen Gruppeninformationsstruktur an, das ungültig ist. Das Format der lokalen Gruppeninformationsstruktur wird im Levelparameter angegeben. Ein Zeiger auf die lokale Gruppeninformationsstruktur wird im buf-Parameter übergeben. In der folgenden Tabelle sind die Werte aufgeführt, die im parameter parm_err und dem entsprechenden Strukturmember zurückgegeben werden können.

Wert	Member
LOCALGROUP_NAME_PARMNUM	Wenn der Levelparameter 0 war, war der lgrpi0_name Member der LOCALGROUP_INFO_0-Struktur ungültig. Wenn der Levelparameter 1 war, war das lgrpi1_name Member der LOCALGROUP_INFO_1-Struktur ungültig.
LOCALGROUP_COMMENT_PARMNUM	Wenn der Levelparameter 1 war, war der lgrpi1_comment Member der LOCALGROUP_INFO_1-Struktur ungültig.

Wenn Sie Anforderungen an einen Domänencontroller und Active Directory stellen, können Sie möglicherweise bestimmte ADSI-Methoden (Active Directory Service Interface) aufrufen, um die gleichen Ergebnisse wie die lokalen Gruppenfunktionen der Netzwerkverwaltung zu erzielen. 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