BuildSecurityDescriptorA 函数（aclapi.h）

项目
11/20/2024

BuildSecurityDescriptor 函数分配并初始化新的安全描述符。此函数可以通过将指定的安全信息与现有安全描述符中的信息合并来初始化新的安全描述符。如果未指定现有的安全描述符，该函数将基于指定的安全信息初始化新的安全描述符。

BuildSecurityDescriptor 函数创建相对安全描述符。自相对格式使安全描述符适合存储在流中。

语法

DWORD BuildSecurityDescriptorA(
  [in, optional] PTRUSTEE_A           pOwner,
  [in, optional] PTRUSTEE_A           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAuditEntries,
  [in, optional] PSECURITY_DESCRIPTOR pOldSD,
  [out]          PULONG               pSizeNewSD,
  [out]          PSECURITY_DESCRIPTOR *pNewSD
);

参数

[in, optional] pOwner

指向受托人结构的指针，用于标识新安全描述符的所有者。如果结构使用TRUSTEE_IS_NAME形式，BuildSecurityDescriptor 查找与指定受托人名称关联的安全标识符（SID）。

如果此参数 NULL，则该函数使用由 pOldSD指向的原始安全描述符中的所有者 SID。如果 pOldSDNULL，或者如果 pOldSD 中的所有者 SID NULL，则所有者 SID 在新的安全描述符中 NULL。

[in, optional] pGroup

指向受托人结构的指针，用于标识新安全描述符的主组 SID。如果结构使用 TRUSTEE_IS_NAME 窗体，BuildSecurityDescriptor 查找与指定受托人名称关联的 SID。

如果此参数 NULL，则该函数将使用由 pOldSD指向的原始安全描述符中的组 SID。如果 pOldSDNULL，或者如果 pOldSD 中的组 SID NULL，则新安全描述符中的组 SID NULL。

[in] cCountOfAccessEntries

pListOfAccessEntries 数组中的 EXPLICIT_ACCESS 结构数。

[in, optional] pListOfAccessEntries

指向 EXPLICIT_ACCESS 结构的数组的指针，该数组描述新安全描述符的自由访问控制列表（DACL）的访问控制信息。该函数通过将数组中的信息与 pOldSD中的 DACL 合并，从而创建新的 DACL（如果有）。如果 pOldSDNULL，或者如果 pOldSD 中的 DACL NULL，则该函数将基于数组中的信息创建新的 DACL。有关从 EXPLICIT_ACCESS 结构数组创建 ACL 的规则的说明，请参阅 SetEntriesInAcl 函数。

如果 pListOfAccessEntriesNULL，则新的安全描述符将从 pOldSD获取 DACL。在这种情况下，如果 pOldSDNULL，或者如果 pOldSD 中的 DACL NULL，则新的 DACL NULL。

[in] cCountOfAuditEntries

pListOfAuditEntries 数组中的 EXPLICIT_ACCESS 结构数。

[in, optional] pListOfAuditEntries

指向 EXPLICIT_ACCESS 结构的数组的指针，该数组描述新安全描述符的 SACL 的审核控制信息。该函数通过将数组中的信息与 pOldSD中的 SACL 合并，从而创建新的 SACL（如果有）。如果 pOldSD 为 NULLNULL，或者 pOldSD 中的 SACL NULL，则该函数将基于数组中的信息创建新的 SACL。

如果 pListOfAuditEntriesNULL，则新的安全描述符将从 pOldSD获取 SACL。在本例中，如果 pOldSD 为 NULL NULL，或 pOldSD 中的 SACL NULL，则新的 SACL NULL。

[in, optional] pOldSD

指向现有自相对 SECURITY_DESCRIPTOR 结构的指针及其关联的安全信息。该函数通过将指定的所有者、组、访问控制和审核控制信息与此安全描述符中的信息合并来生成新的安全描述符。此参数可以 NULL。

[out] pSizeNewSD

指向接收安全描述符大小（以字节为单位）的变量的指针。

[out] pNewSD

指向接收指向新安全描述符的指针的变量的指针。该函数为新的安全描述符分配内存。必须调用 LocalFree 函数来释放返回的缓冲区。

返回值

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

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

言论

BuildSecurityDescriptor 函数适用于在其自己的对象上实现或公开安全性的受信任服务器。该函数使用适合序列化到流和存储到磁盘的自相对安全描述符，因为受信任的服务器可能需要。

注意

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

要求

要求	价值
最低支持的客户端	Windows XP [仅限桌面应用]
支持的最低服务器	Windows Server 2003 [仅限桌面应用]
目标平台	窗户
标头	aclapi.h
库	Advapi32.lib
DLL	Advapi32.dll