AddAuditAccessObjectAce 函数 (securitybaseapi.h)
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 成员中设置这些标志。 此参数可以是以下值的组合。
值 | 含义 |
---|---|
|
ACE 由容器对象继承。 |
|
如果设置此标志或为 bAuditFailure 参数指定 TRUE,则尝试使用指定的访问权限失败会导致系统在安全事件日志中生成审核记录。 |
|
ACE 不适用于将 访问控制列表 (ACL) 分配到的对象,但它可由子对象继承。 |
|
指示继承的 ACE。 此标志允许更改对象树上的安全性的操作修改继承的 ACE,同时不更改直接应用于对象的 ACE。 |
|
OBJECT_INHERIT_ACE位和CONTAINER_INHERIT_ACE位不会传播到继承的 ACE。 |
|
ACE 由非容器对象继承。 |
|
如果设置此标志或为 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。 下面是可能的错误值。
返回代码 | 说明 |
---|---|
|
新的 ACE 不适合 ACL。 需要更大的 ACL 缓冲区。 |
|
指定的 ACL 格式不正确。 |
|
AceFlags 参数无效。 |
|
指定的 SID 在结构上无效。 |
|
指定的修订未知或与 ACL 的修订不兼容。 |
|
已成功添加 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 |