getNamedSecurityInfoA 函数 (aclapi.h)

项目
08/22/2023

GetNamedSecurityInfo 函数检索由名称指定的对象的安全描述符的副本。

语法

DWORD GetNamedSecurityInfoA(
  [in]            LPCSTR               pObjectName,
  [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] pObjectName

指向以 null 结尾的字符串的指针，该字符串指定要从中检索安全信息的对象的名称。有关不同对象类型的字符串格式的说明，请参阅 SE_OBJECT_TYPE。

[in] ObjectType

指定 SE_OBJECT_TYPE 枚举中的值，该值指示 由 pObjectName 参数命名的对象的类型。

[in] SecurityInfo

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

[out, optional] ppsidOwner

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

[out, optional] ppsidGroup

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

[out, optional] ppDacl

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

[out, optional] ppSacl

指向变量的指针，该变量接收指向返回的安全描述符中 SACL 的指针;如果安全描述符没有 SACL，则为 NULL 。仅当设置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 中返回的安全描述符中的相应参数。如果安全描述符不包含请求的信息，则相应的参数将设置为 NULL。

若要从对象的安全描述符读取所有者、组或 DACL，对象的 DACL 必须授予对调用方READ_CONTROL访问权限，或者调用方必须是对象的所有者。

若要读取对象的系统访问控制列表，必须为调用进程启用SE_SECURITY_NAME权限。有关启用特权的安全隐患的信息，请参阅使用特殊特权运行。

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

NTFS 文件系统上的本地或远程文件或目录
本地或远程打印机
本地或远程 Windows 服务
网络共享
注册表项
信号灯、事件、互斥体和可等待计时器
文件映射对象
目录服务对象

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

此函数以纯文本形式传输信息。除非系统已关闭签名，但不会执行加密，否则此函数传输的信息已签名。

有关通过用户帐户、组帐户或登录会话控制对对象的访问的详细信息，请参阅 DACL 如何控制对对象的访问。

示例

有关使用 GetNamedSecurityInfo 的示例，请参阅修改对象的 ACL。

注意

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

要求

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