AddAuditAccessObjectAce 函数 (securitybaseapi.h)

项目
08/25/2023

AddAuditAccessObjectAce 函数将系统审核访问控制项 (ACE) 添加到系统访问控制列表的末尾， (SACL) 。新的 ACE 可以审核对对象或对象上属性集或属性的访问。还可以使用 AddAuditAccessObjectAce 添加只有指定类型的子对象才能继承的 ACE。

语法

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

参数

[in, out] pAcl

指向 SACL 的指针。 AddAuditAccessObjectAce 函数在此 SACL 的末尾添加系统审核 ACE。 ACE 采用 SYSTEM_AUDIT_OBJECT_ACE 结构的形式。

[in] dwAceRevision

指定要修改的 SACL 的修订级别。此值必须ACL_REVISION_DS。如果 SACL 的修订级别低于 ACL_REVISION_DS，则函数将其更改为 ACL_REVISION_DS。

[in] AceFlags

控制 ACE 继承和尝试审核的访问类型的一组位标志。函数在新 ACE 的 ACE_HEADER 结构的 AceFlags 成员中设置这些标志。此参数可以是以下值的组合。

值	含义
CONTAINER_INHERIT_ACE	ACE 由容器对象继承。
FAILED_ACCESS_ACE_FLAG	如果设置此标志或为 bAuditFailure 参数指定 TRUE，则尝试使用指定的访问权限失败会导致系统在安全事件日志中生成审核记录。
INHERIT_ONLY_ACE	ACE 不适用于将访问控制列表 (ACL) 分配到的对象，但它可由子对象继承。
INHERITED_ACE	指示继承的 ACE。此标志允许更改对象树上的安全性的操作修改继承的 ACE，同时不更改直接应用于对象的 ACE。
NO_PROPAGATE_INHERIT_ACE	OBJECT_INHERIT_ACE位和CONTAINER_INHERIT_ACE位不会传播到继承的 ACE。
OBJECT_INHERIT_ACE	ACE 由非容器对象继承。
SUCCESSFUL_ACCESS_ACE_FLAG	如果设置此标志或为 bAuditSuccess 参数指定 TRUE，则成功使用指定的访问权限会导致系统在安全事件日志中生成审核记录。

[in] AccessMask

一个ACCESS_MASK，指定新 ACE 审核指定安全标识符 (SID) 的访问权限。

[in, optional] ObjectTypeGuid

指向 GUID 结构的指针，该结构标识受新 ACE 保护的对象、属性集或属性的类型。如果此参数为 NULL，则新的 ACE 将保护分配 ACL 的对象。

[in, optional] InheritedObjectTypeGuid

指向 GUID 结构的指针，该结构标识可以继承新 ACE 的对象的类型。如果此参数为非 NULL，则只有指定的对象类型可以继承 ACE。如果 为 NULL，则任何类型的子对象都可以继承 ACE。在任一情况下，继承也由 AceFlags 参数的值以及针对子对象上放置的继承的任何保护进行控制。

[in] pSid

指向 SID 的指针，用于标识新 ACE 审核访问的用户、组或登录会话。

[in] bAuditSuccess

指定成功使用指定的访问权限是否导致系统在安全事件日志中生成审核记录。如果此标志为 TRUE ，或者 AceFlags 参数指定SUCCESSFUL_ACCESS_ACE_FLAG标志，则系统会记录成功的访问尝试;否则，它不会。

[in] bAuditFailure

指定使用指定访问权限的失败尝试是否导致系统在安全事件日志中生成审核记录。如果此标志为 TRUE ，或者 AceFlags 参数指定FAILED_ACCESS_ACE_FLAG标志，则系统会记录失败的访问尝试;否则，它不会。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。下面是可能的错误值。

返回代码	说明
ERROR_ALLOTTED_SPACE_EXCEEDED	新的 ACE 不适合 ACL。需要更大的 ACL 缓冲区。
ERROR_INVALID_ACL	指定的 ACL 格式不正确。
ERROR_INVALID_FLAGS	AceFlags 参数无效。
ERROR_INVALID_SID	指定的 SID 在结构上无效。
ERROR_REVISION_MISMATCH	指定的修订未知或与 ACL 的修订不兼容。
ERROR_SUCCESS	已成功添加 ACE。

注解

如果 ObjectTypeGuid 和 InheritedObjectTypeGuid 均为 NULL，请使用 AddAuditAccessAceEx 函数，而不是 AddAuditAccessObjectAce。建议这样做是因为 SYSTEM_AUDIT_ACE 比 SYSTEM_AUDIT_OBJECT_ACE更小、更高效。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	securitybaseapi.h (包括 Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll