AddAce-Funktion (securitybaseapi.h)

Artikel
08/25/2023

Die AddAce-Funktion fügt einer angegebenen Zugriffssteuerungsliste (Access Control List, ACL) einen oder mehrere Zugriffssteuerungseinträge (Access Control List, ACEs) hinzu.

Syntax

BOOL AddAce(
  [in, out] PACL   pAcl,
  [in]      DWORD  dwAceRevision,
  [in]      DWORD  dwStartingAceIndex,
  [in]      LPVOID pAceList,
  [in]      DWORD  nAceListLength
);

Parameter

[in, out] pAcl

Ein Zeiger auf eine ACL. Diese Funktion fügt dieser ACL einen ACE hinzu.

[in] dwAceRevision

Gibt die Revisionsebene der ACL an, die geändert wird.

Dieser Wert kann ACL_REVISION oder ACL_REVISION_DS sein. Verwenden Sie ACL_REVISION_DS, wenn die ACL objektspezifische ACEs enthält. Dieser Wert muss mit dem AceType-Feld aller ACEs in pAceList kompatibel sein. Andernfalls schlägt die Funktion fehl, und der letzte Fehler wird auf ERROR_INVALID_PARAMETER festgelegt.

[in] dwStartingAceIndex

Gibt die Position in der ACL-Liste der ACEs an, an der neue ACEs hinzugefügt werden sollen. Der Wert 0 (null) fügt die ACEs am Anfang der Liste ein. Der Wert MAXDWORD fügt die ACEs am Ende der Liste an.

[in] pAceList

Ein Zeiger auf eine Liste von mindestens einem ACEs, das der angegebenen ACL hinzugefügt werden soll. Die ACEs in der Liste müssen zusammenhängend gespeichert werden.

[in] nAceListLength

Gibt die Größe des Eingabepuffers in Bytes an, auf den der pAceList-Parameter verweist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. Im Folgenden sind mögliche Fehlerwerte aufgeführt.

Rückgabecode	Beschreibung
ERROR_INSUFFICIENT_BUFFER	Der neue ACE passt nicht in die ACL. Ein größerer ACL-Puffer ist erforderlich.
ERROR_INVALID_PARAMETER	Die angegebene ACL ist nicht ordnungsgemäß gebildet.
ERROR_SUCCESS	Der ACE wurde erfolgreich hinzugefügt.

Hinweise

Anwendungen verwenden häufig die Funktionen FindFirstFreeAce und GetAce , wenn sie die AddAce-Funktion zum Bearbeiten einer ACL verwenden. Darüber hinaus enthält die von der GetAclInformation-Funktion abgerufene ACL_SIZE_INFORMATION-Struktur die Größe der ACL und die Anzahl der darin enthaltenen ACEs.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Starten eines interaktiven Clientprozesses.

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	securitybaseapi.h (Einschließen von Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll