AddAccessDeniedObjectAce-Funktion (securitybaseapi.h)

Artikel
08/25/2023

Die AddAccessDeniedObjectAce-Funktion fügt einen Zugriffssteuerungseintrag (Access Denied Access Control Entry, ACE) am Ende einer daCL (Discretionary Access Control List ) hinzu. Der neue ACE kann den Zugriff auf ein Objekt oder einen Eigenschaftssatz oder eine Eigenschaft für ein Objekt verweigern. Sie können auch AddAccessDeniedObjectAce verwenden, um ein ACE hinzuzufügen, das nur ein angegebener Typ von untergeordneten Objekten erben kann.

Syntax

BOOL AddAccessDeniedObjectAce(
  [in, out]      PACL  pAcl,
  [in]           DWORD dwAceRevision,
  [in]           DWORD AceFlags,
  [in]           DWORD AccessMask,
  [in, optional] GUID  *ObjectTypeGuid,
  [in, optional] GUID  *InheritedObjectTypeGuid,
  [in]           PSID  pSid
);

Parameter

[in, out] pAcl

Ein Zeiger auf eine DACL. Die AddAccessDeniedObjectAce-Funktion fügt am Ende dieser DACL eine zugriffsverwehrte ACE hinzu. Der ACE ist in Form einer ACCESS_DENIED_OBJECT_ACE-Struktur .

[in] dwAceRevision

Gibt die Revisionsebene der DACL an, die geändert wird. Dieser Wert muss ACL_REVISION_DS sein. Wenn die Revisionsebene der DACL niedriger als ACL_REVISION_DS ist, ändert die Funktion sie in ACL_REVISION_DS.

[in] AceFlags

Eine Reihe von Bitflags, die die ACE-Vererbung steuern. Die Funktion legt diese Flags im AceFlags-Member der ACE_HEADER-Struktur des neuen ACE fest. Für diesen Parameter ist eine Kombination der folgenden Werte gültig.

Wert	Bedeutung
CONTAINER_INHERIT_ACE	Der ACE wird von Containerobjekten geerbt.
INHERIT_ONLY_ACE	Der ACE gilt nicht für das Objekt, dem die Zugriffssteuerungsliste (Access Control List , ACL) zugewiesen ist, aber es kann von untergeordneten Objekten geerbt werden.
INHERITED_ACE	Gibt einen geerbten ACE an. Dieses Flag ermöglicht Es Vorgängen, die die Sicherheit für eine Struktur von Objekten ändern, geerbte ACEs zu ändern, während acEs, die direkt auf das Objekt angewendet wurden, nicht geändert werden.
NO_PROPAGATE_INHERIT_ACE	Die OBJECT_INHERIT_ACE und CONTAINER_INHERIT_ACE Bits werden nicht an eine geerbte ACE weitergegeben.
OBJECT_INHERIT_ACE	Der ACE wird von Nichtcontainerobjekten geerbt.

[in] AccessMask

Eine Reihe von Bitflags, die das ACCESS_MASK Format verwenden, um die Zugriffsrechte anzugeben, die der neue ACE der angegebenen Sicherheits-ID (SID) verweigert.

[in, optional] ObjectTypeGuid

Ein Zeiger auf eine GUID-Struktur , die den Typ des Objekts, des Eigenschaftensatzes oder der Eigenschaft identifiziert, der durch den neuen ACE geschützt wird. Wenn dieser Parameter NULL ist, schützt der neue ACE das Objekt, dem die ACL zugewiesen ist.

[in, optional] InheritedObjectTypeGuid

Ein Zeiger auf eine GUID-Struktur , die den Typ des Objekts angibt, das den neuen ACE erben kann. Wenn dieser Parameter nicht NULL ist, kann nur der angegebene Objekttyp den ACE erben. Wenn NULL, kann jeder Typ von untergeordneten Objekten den ACE erben. In beiden Fällen wird die Vererbung auch durch den Wert des AceFlags-Parameters sowie durch jeglichen Schutz vor Vererbung gesteuert, der auf die untergeordneten Objekte gesetzt wird.

[in] pSid

Ein Zeiger auf eine SID, die den Benutzer, die Gruppe oder die Anmeldesitzung identifiziert, auf die der neue ACE Zugriff zulässt.

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_ALLOTTED_SPACE_EXCEEDED	Der neue ACE passt nicht in die ACL. Ein größerer ACL-Puffer ist erforderlich.
ERROR_INVALID_ACL	Die angegebene ACL ist nicht ordnungsgemäß gebildet.
ERROR_INVALID_FLAGS	Der AceFlags-Parameter ist ungültig.
ERROR_INVALID_SID	Die angegebene SID ist strukturell ungültig.
ERROR_REVISION_MISMATCH	Die angegebene Revision ist nicht bekannt oder nicht mit der der ACL kompatibel.
ERROR_SUCCESS	Der ACE wurde erfolgreich hinzugefügt.

Hinweise

Wenn sowohl ObjectTypeGuid als auch InheritedObjectTypeGuidNULL sind, verwenden Sie die AddAccessDeniedAceEx-Funktion anstelle von AddAccessDeniedObjectAce. Dies wird empfohlen, da ein ACCESS_DENIED_ACE kleiner und effizienter ist als ein ACCESS_DENIED_OBJECT_ACE.

Obwohl die AddAccessDeniedObjectAce-Funktion den neuen ACE am Ende der ACL hinzufügt, sollten Zugriffsverweigerungs-ACEs am Anfang einer ACL angezeigt werden. Der Aufrufer muss sicherstellen, dass ACEs der DACL in der richtigen Reihenfolge hinzugefügt werden. Weitere Informationen finden Sie unter Reihenfolge von ACEs in einer DACL.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	securitybaseapi.h (Einschließen von Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll