AddAce 函数 (securitybaseapi.h)

项目
03/01/2024

AddAce 函数将一个或多个访问控制条目 (ACE) 添加到指定的访问控制列表 (ACL) 。

语法

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

参数

[in, out] pAcl

指向 ACL 的指针。此函数将 ACE 添加到此 ACL。

[in] dwAceRevision

指定要修改的 ACL 的修订级别。

此值可以是ACL_REVISION或ACL_REVISION_DS。如果 ACL 包含特定于对象的 ACE，请使用 ACL_REVISION_DS。此值必须与 pAceList 中所有 ACE 的 AceType 字段兼容。否则，函数将失败，并将最后一个错误设置为ERROR_INVALID_PARAMETER。

[in] dwStartingAceIndex

指定 ACL 的 ACE 列表中要添加新 ACE 的位置。值为零会将 ACE 插入到列表的开头。 MAXDWORD 的值会将 ACE 追加到列表的末尾。

[in] pAceList

指向要添加到指定 ACL 的一个或多个 ACE 列表的指针。列表中的 ACE 必须连续存储。

[in] nAceListLength

指定 pAceList 参数指向的输入缓冲区的大小（以字节为单位）。

返回值

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

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

返回代码	说明
ERROR_INSUFFICIENT_BUFFER	新的 ACE 不适合 ACL。需要更大的 ACL 缓冲区。
ERROR_INVALID_PARAMETER	指定的 ACL 格式不正确。
ERROR_SUCCESS	已成功添加 ACE。

注解

使用 AddAce 函数操作 ACL 时，应用程序经常使用 FindFirstFreeAce 和 GetAce 函数。此外，GetAclInformation 函数检索的ACL_SIZE_INFORMATION结构包含 ACL 的大小及其包含的 ACE 数。

示例

有关使用此函数的示例，请参阅启动交互式客户端进程。

要求

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