InitializeAcl 函数 (securitybaseapi.h)

项目
03/13/2024

InitializeAcl 函数初始化新的 ACL 结构。

语法

BOOL InitializeAcl(
  [out] PACL  pAcl,
  [in]  DWORD nAclLength,
  [in]  DWORD dwAclRevision
);

参数

[out] pAcl

指向此函数要初始化的 ACL 结构的指针。在调用此函数之前为 pAcl 分配内存。

[in] nAclLength

pAcl 参数指向的缓冲区的长度（以字节为单位）。此值必须足够大，才能包含 ACL 标头和所有访问控制条目， (ACE) 存储在 ACL 中。此外，此值必须与 DWORD 对齐。有关计算 ACL 大小的详细信息，请参阅备注。

[in] dwAclRevision

正在创建的 ACL 结构的修订级别。

此值可以是ACL_REVISION或ACL_REVISION_DS。如果访问控制列表 (ACL) 支持特定于对象的 ACE，请使用 ACL_REVISION_DS。

返回值

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

如果函数失败，则返回零。要获得更多的错误信息，请调用 GetLastError。

注解

InitializeAcl 函数创建一个空的 ACL 结构;ACL 不包含 ACE。将空 ACL 应用于对象会拒绝对该对象的所有访问。

ACL 的初始大小取决于计划在使用 ACL 之前添加到 ACL 的 ACE 数量。例如，如果 ACL 要包含用户和组的 ACE，则基于两个 ACE 初始化 ACL 。有关修改现有 ACL 的详细信息，请参阅修改对象的 ACL。

若要计算 ACL 的初始大小，请将以下内容一起添加，然后将结果与最接近的 DWORD 对齐：

ACL 结构的大小。
ACL 要包含的每个 ACE 结构的大小减去 ACE 的 SidStart 成员 (DWORD) 。
每个 ACE 要包含的 SID 的长度。

示例

以下示例调用 InitializeAcl 函数。 ACL 的大小基于三个允许访问 ACE。可以选择使用安全描述符定义语言 (SDDL) 来创建 ACL。有关详细信息，请参阅创建 DACL。

该示例还省略了简化步骤。有关详细信息，请参阅获取对象所有权示例。由于调用 AllocateAndInitializeSid 函数，必须在示例代码末尾调用 FreeSid 函数。

#include <windows.h>
#include <Winbase.h>
#pragma comment(lib, "duser.lib")

#define NUM_OF_ACES 3

void main()
{
    PACL pAcl = NULL;
    DWORD cbAcl = 0;
    PSID psids[NUM_OF_ACES];

    // Allocate and initialize SIDs.
    // Step omitted - See Taking Object Ownership example.

    // Add the SID for each ACE to psids. 
    cbAcl = sizeof(ACL) + 
        ((sizeof(ACCESS_ALLOWED_ACE)) * NUM_OF_ACES);
    for (int i = 0; i < NUM_OF_ACES; i++)
    {
        cbAcl += GetLengthSid(psids[i]) - sizeof(DWORD);
    }

    // Align cbAcl to a DWORD.
    cbAcl = (cbAcl + (sizeof(DWORD) - 1)) & 0xfffffffc;

    pAcl = (ACL*)LocalAlloc(LPTR, cbAcl);
    if (pAcl)
    {
        if (InitializeAcl(pAcl, cbAcl, ACL_REVISION))
        {

            // Add the ACEs to the ACL.
            // Add the ACL to the object's security descriptor.
        }
        else
        {

            // Handle error.
        }
    }
    {

        // Handle error.
    }

    // Free pAcl when finished.
    // Call FreeSid when finished.
}

要求

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