BuildSecurityDescriptorA 函数 (aclapi.h)

项目
02/23/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 结构的指针。如果结构使用 TRUSTEE_IS_NAME 窗体， 则 BuildSecurityDescriptor 将查找与指定受托人名称关联的 SID (安全标识符) 。

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

[in, optional] pGroup

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

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

[in] cCountOfAccessEntries

pListOfAccessEntries 数组中的EXPLICIT_ACCESS结构数。

[in, optional] pListOfAccessEntries

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

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

[in] cCountOfAuditEntries

pListOfAuditEntries 数组中的EXPLICIT_ACCESS结构数。

[in, optional] pListOfAuditEntries

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

如果 pListOfAuditEntries 为 NULL，则新的安全描述符将从 pOldSD 获取 SACL。在这种情况下，如果 pOldSD 为 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 [仅限桌面应用]
目标平台	Windows
标头	aclapi.h
Library	Advapi32.lib
DLL	Advapi32.dll