getSecurityInfo 函数 (aclapi.h)

项目
08/22/2023

GetSecurityInfo 函数检索句柄指定的对象的安全描述符的副本。

语法

DWORD GetSecurityInfo(
  [in]            HANDLE               handle,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

参数

[in] handle

要从中检索安全信息的对象的句柄。

[in] ObjectType

SE_OBJECT_TYPE 枚举值，该值指示对象的类型。

[in] SecurityInfo

一组位标志，指示要检索的安全信息的类型。此参数可以是 SECURITY_INFORMATION 位标志的组合。

[out, optional] ppsidOwner

指向变量的指针，该变量接收指向 ppSecurityDescriptor 中返回的安全描述符中所有者 SID 的指针。仅当设置OWNER_SECURITY_INFORMATION标志时，返回的指针才有效。如果不需要所有者 SID，此参数可以为 NULL 。

[out, optional] ppsidGroup

指向变量的指针，该变量接收指向返回的安全描述符中主组 SID 的指针。仅当设置了GROUP_SECURITY_INFORMATION标志时，返回的指针才有效。如果不需要组 SID，此参数可以为 NULL 。

[out, optional] ppDacl

指向变量的指针，该变量接收指向返回的安全描述符中 DACL 的指针。仅当设置了DACL_SECURITY_INFORMATION标志时，返回的指针才有效。如果不需要 DACL，此参数可以为 NULL 。

[out, optional] ppSacl

指向变量的指针，该变量接收指向返回的安全描述符中 SACL 的指针。仅当设置SACL_SECURITY_INFORMATION标志时，返回的指针才有效。如果不需要 SACL，此参数可以为 NULL 。

[out, optional] ppSecurityDescriptor

指向变量的指针，该变量接收指向对象的安全描述符的指针。使用完指针后，通过调用 LocalFree 函数释放返回的缓冲区。

如果任何 ppsidOwner、ppsidGroup、ppDacl 或 ppSacl 参数不为 NULL，则此参数是必需的。

返回值

如果函数成功，则返回值为 ERROR_SUCCESS。

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

注解

如果 ppsidOwner、 ppsidGroup、 ppDacl 和 ppSacl 参数为非 NULL，并且 SecurityInfo 参数指定从对象中检索它们，则这些参数将指向 ppSecurityDescriptor 中返回的安全描述符中的相应参数。

若要从对象的安全描述符读取所有者、组或 DACL，必须在打开句柄时授予调用进程READ_CONTROL访问权限。若要获取READ_CONTROL访问权限，调用方必须是对象的所有者，或者对象的 DACL 必须授予访问权限。

若要从安全描述符读取 SACL，必须在打开句柄时授予调用进程ACCESS_SYSTEM_SECURITY访问权限。获取此访问权限的正确方法是在调用方当前令牌中启用SE_SECURITY_NAME特权，打开ACCESS_SYSTEM_SECURITY访问的句柄，然后禁用该权限。有关启用特权的安全隐患的信息，请参阅使用特殊特权运行。

可以将 GetSecurityInfo 函数与以下类型的对象一起使用：

NTFS 文件系统上的本地或远程文件或目录
Named pipes
本地或远程打印机
本地或远程 Windows 服务
网络共享
注册表项
信号灯、事件、互斥体和可等待计时器
进程、线程、作业和文件映射对象
交互式服务窗口工作站和桌面
目录服务对象

此函数不处理争用条件。如果线程在另一个线程更改对象的安全描述符的大致时间调用此函数，则此函数可能会失败。

示例

有关使用此函数的示例，请参阅查找文件对象的所有者。

要求

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