SetEntriesInAclA-Funktion (aclapi.h)

Artikel
08/22/2023

Die SetEntriesInAcl-Funktion erstellt eine neue Zugriffssteuerungsliste (Access Control List , ACL), indem neue Zugriffssteuerungs- oder Überwachungssteuerungsinformationen in eine vorhandene ACL-Struktur zusammengeführt werden.

Syntax

DWORD SetEntriesInAclA(
  [in]           ULONG              cCountOfExplicitEntries,
  [in, optional] PEXPLICIT_ACCESS_A pListOfExplicitEntries,
  [in, optional] PACL               OldAcl,
  [out]          PACL               *NewAcl
);

Parameter

[in] cCountOfExplicitEntries

Die Anzahl der EXPLICIT_ACCESS Strukturen im pListOfExplicitEntries-Array .

[in, optional] pListOfExplicitEntries

Ein Zeiger auf ein Array von EXPLICIT_ACCESS Strukturen, die die Informationen zur Zugriffssteuerung beschreiben, die in die vorhandene ACL zusammengeführt werden sollen.

[in, optional] OldAcl

Ein Zeiger auf die vorhandene ACL. Dieser Parameter kann NULL sein. In diesem Fall erstellt die Funktion eine neue ACL basierend auf den EXPLICIT_ACCESS Einträgen.

[out] NewAcl

Ein Zeiger auf eine Variable, die einen Zeiger auf die neue ACL empfängt. Wenn die Funktion erfolgreich ist, müssen Sie die LocalFree-Funktion aufrufen, um den zurückgegebenen Puffer freizugeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion ERROR_SUCCESS zurück.

Wenn die Funktion fehlschlägt, gibt sie einen nichtzero-Fehlercode zurück, der in WinError.h definiert ist.

Hinweise

Jeder Eintrag im Array von EXPLICIT_ACCESS-Strukturen gibt Zugriffssteuerungs- oder Überwachungssteuerungsinformationen für einen angegebenen Treuhänder an. Ein Treuhänder kann ein Benutzer, eine Gruppe oder ein anderer Sid-Wert (Security Identifier) sein, z. B. ein Anmeldebezeichner oder Anmeldetyp (für instance, einen Windows-Dienst oder batch-Auftrag). Sie können einen Namen oder eine SID verwenden, um einen Treuhänder zu identifizieren.

Sie können die SetEntriesInAcl-Funktion verwenden, um die Liste der Zugriffssteuerungseinträge (AcEs) in einer diskretionären Zugriffssteuerungsliste (DACL) oder einer Systemzugriffssteuerungsliste (SACL ) zu ändern. Beachten Sie, dass SetEntriesInAcl nicht daran hindert , Zugriffssteuerungs- und Überwachungssteuerungsinformationen in derselben ACL zu mischen. die resultierende ACL enthält jedoch bedeutungslose Einträge.

Bei einer DACL gibt das grfAccessMode-Element der EXPLICIT_ACCESS-Struktur an, ob Zugriffsrechte für den Treuhänder zugelassen, verweigert oder widerrufen werden sollen. Dieses Member kann einen der folgenden Werte angeben:

GRANT_ACCESS
SET_ACCESS
DENY_ACCESS
REVOKE_ACCESS

Informationen zu diesen Werten finden Sie unter ACCESS_MODE.

Die SetEntriesInAcl-Funktion platziert alle neuen Zugriffsverweigerungs-ACEs am Anfang der Liste der ACEs für die neue ACL. Diese Funktion platziert alle neuen zugriffsberechtigten ACEs direkt vor vorhandenen zugriffsberechtigten ACEs.

Für eine SACL kann das grfAccessMode-Element der EXPLICIT_ACCESS-Struktur die folgenden Werte angeben:

REVOKE_ACCESS
SET_AUDIT_FAILURE
SET_AUDIT_SUCCESS

SET_AUDIT_FAILURE und SET_AUDIT_SUCCESS können kombiniert werden. Informationen zu diesen Werten finden Sie unter ACCESS_MODE.

Die SetEntriesInAcl-Funktion platziert alle neuen Systemüberwachungs-ACEs am Anfang der Liste der ACEs für die neue ACL.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Ändern der ACLs eines Objekts oder Erstellen eines Sicherheitsdeskriptors für ein neues Objekt oder Übernehmen des Objektbesitzes.

Hinweis

Der aclapi.h-Header definiert SetEntriesInAcl als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	aclapi.h
Bibliothek	Advapi32.lib
DLL	Advapi32.dll