SetEntriesInAclA 函数 (aclapi.h)

项目
08/22/2023

SetEntriesInAcl 函数通过将新的访问控制或审核控制信息合并到现有 ACL 结构 (ACL) 创建新的访问控制列表。

语法

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

参数

[in] cCountOfExplicitEntries

pListOfExplicitEntries 数组中的EXPLICIT_ACCESS结构数。

[in, optional] pListOfExplicitEntries

指向 EXPLICIT_ACCESS 结构的数组的指针，这些结构描述要合并到现有 ACL 中的访问控制信息。

[in, optional] OldAcl

指向现有 ACL 的指针。此参数可以为 NULL，在这种情况下，函数会基于 EXPLICIT_ACCESS 条目创建新的 ACL。

[out] NewAcl

指向变量的指针，该变量接收指向新 ACL 的指针。如果函数成功，则必须调用 LocalFree 函数以释放返回的缓冲区。

返回值

如果函数成功，该函数将返回ERROR_SUCCESS。

如果函数失败，它将返回 WinError.h 中定义的非零错误代码。

注解

EXPLICIT_ACCESS结构数组中的每个条目指定指定受托人的访问控制或审核控制信息。受托人可以是用户、组或其他安全标识符 (SID) 值，例如登录标识符或登录类型 (例如 Windows 服务或批处理作业) 。可以使用名称或 SID 来标识受托人。

可以使用 SetEntriesInAcl 函数修改访问控制项列表 (ACE) 任意访问控制列表 (DACL) 或系统访问控制列表 (SACL) 。请注意， SetEntriesInAcl 不会阻止你在同一 ACL 中混合访问控制和审核控制信息;但是，生成的 ACL 将包含无意义的条目。

对于 DACL，EXPLICIT_ACCESS结构的 grfAccessMode 成员指定是允许、拒绝还是撤销受托人的访问权限。此成员可以指定以下值之一：

GRANT_ACCESS
SET_ACCESS
DENY_ACCESS
REVOKE_ACCESS

有关这些值的信息，请参阅 ACCESS_MODE。

SetEntriesInAcl 函数将任何新的拒绝访问的 ACE 放置在新 ACL 的 ACE 列表的开头。此函数将任何新的允许访问的 ACE 置于任何允许访问的现有 ACE 之前。

对于 SACL，EXPLICIT_ACCESS 结构的 grfAccessMode 成员可以指定以下值：

REVOKE_ACCESS
SET_AUDIT_FAILURE
SET_AUDIT_SUCCESS

SET_AUDIT_FAILURE和SET_AUDIT_SUCCESS可以组合使用。有关这些值的信息，请参阅 ACCESS_MODE。

SetEntriesInAcl 函数将任何新的系统审核 ACE 置于新 ACL 的 ACE 列表的开头。

示例

有关使用此函数的示例，请参阅修改对象的 ACL 或为新对象创建安全描述符或获取对象所有权。

注意

aclapi.h 标头将 SetEntriesInAcl 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows XP [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	aclapi.h
Library	Advapi32.lib
DLL	Advapi32.dll