NetUserSetGroups-Funktion (lmaccess.h)
Die Funktion NetUserSetGroups legt globale Gruppenmitgliedschaften für ein angegebenes Benutzerkonto fest.
Syntax
NET_API_STATUS NET_API_FUNCTION NetUserSetGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[in] LPBYTE buf,
[in] DWORD num_entries
);
Parameter
[in] servername
Ein Zeiger auf eine Konstantenzeichenfolge, 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] username
Ein Zeiger auf eine Konstante Zeichenfolge, die den Namen des Benutzers angibt, für den globale Gruppenmitgliedschaften festgelegt werden sollen. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
[in] level
Die Informationsstufe der Daten. Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
|
Der buf-Parameter verweist auf ein Array von GROUP_USERS_INFO_0 Strukturen, die globale Gruppennamen angibt. |
|
Der buf-Parameter verweist auf ein Array von GROUP_USERS_INFO_1 Strukturen, die globale Gruppennamen mit Attributen angibt. |
[in] buf
Ein Zeiger auf den Puffer, der die Daten angibt. Weitere Informationen finden Sie unter Netzwerkverwaltungsfunktionenpuffer.
[in] num_entries
Die Anzahl der Einträge, die im Array enthalten sind, verweisen auf den Buf-Parameter .
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert NERR_Success.
Wenn die Funktion fehlschlägt, kann der Rückgabewert eine der folgenden Fehlercodes sein.
| Rückgabecode | Beschreibung |
|---|---|
|
Der Benutzer hat keinen Zugriff auf die angeforderten Informationen. |
|
Die Systemanrufebene ist nicht richtig. Dieser Fehler wird zurückgegeben, wenn der Levelparameter als anderer Wert als 0 oder 1 angegeben wurde. |
|
Ein übergebener Parameter war ungültig. Dieser Fehler wird zurückgegeben, wenn der num_entries Parameter ungültig war. |
|
Unzureichender Speicher war verfügbar, um den Vorgang abzuschließen. |
|
Der Computername ist ungültig. |
|
Der Vorgang ist nur auf dem primären Domänencontroller der Domäne zulässig. |
|
Der durch diegrui0_name in der GROUP_USERS_INFO_0 Struktur oder grui1_name Member in der GROUP_USERS_INFO_1 Struktur angegebene Gruppenname ist nicht vorhanden. |
|
Interner Fehler. |
|
Der Benutzername konnte nicht gefunden werden. |
Bemerkungen
Wenn Sie für Active Directory programmieren, können Sie möglicherweise bestimmte Active Directory-Dienstschnittstellen (ADSI) aufrufen, um dieselbe Funktionalität zu erreichen, die Sie erreichen können, indem Sie die Funktionen der Netzwerkverwaltung aufrufen. Weitere Informationen finden Sie unter IADsUser und IADsComputer.
Wenn Sie diese Funktion auf einem Domänencontroller aufrufen, der Active Directory ausführt, ist der Zugriff zulässig oder verweigert, basierend auf der Zugriffssteuerungsliste (ACL) für das sicherungsfähige Objekt. 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.
Der Sicherheitsdeskriptor des User-Objekts wird verwendet, um die Zugriffsüberprüfung für diese Funktion auszuführen.
Um eine Benutzermitgliedschaft in einer vorhandenen globalen Gruppe zu gewähren, können Sie die NetGroupAddUser-Funktion aufrufen.
Benutzernamen sind auf 20 Zeichen beschränkt und Gruppennamen sind auf 256 Zeichen beschränkt. Darüber hinaus können Kontonamen nicht durch einen Zeitraum beendet werden, und sie können keine Kommas oder eines der folgenden druckbaren Zeichen enthalten: ", /, [, ], ], :, |, <>, +, =, ;, ?, *. Namen können auch keine Zeichen im Bereich 1-31 enthalten, die nicht druckbar sind.
Beispiele
Im folgenden Codebeispiel wird veranschaulicht, wie globale Gruppenmitgliedschaften für ein Benutzerkonto mit einem Aufruf zur NetUserSetGroups-Funktion festgelegt werden. Das Codebeispiel füllt das grui0_name Member der GROUP_USERS_INFO_0 Struktur aus und ruft NetUserSetGroups auf, die Informationsstufe 0 angibt.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <stdio.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t *argv[])
{
DWORD dwLevel = 0;
GROUP_USERS_INFO_0 gi;
NET_API_STATUS nStatus;
if (argc != 4)
{
fwprintf(stderr, L"Usage: %s \\\\ServerName UserName GroupName\n", argv[0]);
exit(1);
}
//
// Fill in the GROUP_USERS_INFO_0 structure member.
//
gi.grui0_name = argv[3];
//
// Call the NetUserSetGroups function; specify level 0.
//
nStatus = NetUserSetGroups(argv[1],
argv[2],
dwLevel,
(LPBYTE)&gi,
1);
//
// If the call succeeds, inform the user.
//
if (nStatus == NERR_Success)
fwprintf(stderr, L"Group membership has been successful for %s\n", argv[2]);
//
// Otherwise, print the system error.
//
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
return 0;
}
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 (enthalten Lm.h) |
| Bibliothek | Netapi32.lib |
| DLL | Netapi32.dll |