TreeSetNamedSecurityInfoA 函数 (aclapi.h)

项目
02/23/2024

不支持此函数的此版本。支持此函数的宽字符版本 TreeSetNamedSecurityInfoW。

语法

DWORD TreeSetNamedSecurityInfoA(
  [in]           LPSTR                pObjectName,
  [in]           SE_OBJECT_TYPE       ObjectType,
  [in]           SECURITY_INFORMATION SecurityInfo,
  [in, optional] PSID                 pOwner,
  [in, optional] PSID                 pGroup,
  [in, optional] PACL                 pDacl,
  [in, optional] PACL                 pSacl,
  [in]           DWORD                dwAction,
  [in]           FN_PROGRESS          fnProgress,
  [in]           PROG_INVOKE_SETTING  ProgressInvokeSetting,
  [in, optional] PVOID                Args
);

参数

[in] pObjectName

指向 以 null 结尾的字符串的指针，该字符串指定要接收更新的安全信息的对象的根节点对象的名称。支持的对象是注册表项和文件对象。有关不同对象类型的字符串格式的说明，请参阅 SE_OBJECT_TYPE。

[in] ObjectType

SE_OBJECT_TYPE枚举的值，指示由 pObjectName 参数命名的对象的类型。支持的值分别为注册表项和文件对象的SE_REGISTRY_KEY和SE_FILE_OBJECT。

[in] SecurityInfo

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

[in, optional] pOwner

指向标识对象所有者的 SID 结构的指针。 SID 必须是可以分配为安全描述符的所有者 SID 的 SID。 SecurityInfo 参数必须包含 OWNER_SECURITY_INFORMATION 标志。若要设置所有者，调用方必须具有对每个对象（包括根对象）WRITE_OWNER访问权限。如果未设置所有者 SID，则此参数可以为 NULL。

[in, optional] pGroup

指向标识对象的主要组的 SID 结构的指针。 SecurityInfo 参数必须包含 GROUP_SECURITY_INFORMATION 标志。若要设置组，调用方必须具有对每个对象（包括根对象）WRITE_OWNER访问权限。如果未设置主组 SID，则此参数可以为 NULL。

[in, optional] pDacl

指向访问控制列表的指针 (ACL) 结构，该结构表示要重置的对象的新 DACL。 SecurityInfo 参数必须包含 DACL_SECURITY_INFORMATION 标志。调用方必须具有对每个对象（包括根对象）READ_CONTROL和WRITE_DAC访问权限。如果未设置 DACL，则此参数可以为 NULL。

[in, optional] pSacl

指向 ACL 结构的指针，该结构表示要重置的对象的新 SACL。 SecurityInfo 参数必须包含以下任何标志：SACL_SECURITY_INFORMATION、LABEL_SECURITY_INFORMATION、ATTRIBUTE_SECURITY_INFORMATION、SCOPE_SECURITY_INFORMATION或BACKUP_SECURITY_INFORMATION。如果设置SACL_SECURITY_INFORMATION或SCOPE_SECURITY_INFORMATION，则调用方必须启用SE_SECURITY_NAME特权。如果未设置 SACL，则此参数可以为 NULL。

[in] dwAction

指定此函数的行为。必须将其设置为在 AccCtrl.h 中定义的以下值之一。

值	含义
TREE_SEC_INFO_SET 0x00000001	安全信息由 pObjectName 参数和该对象的子对象树指定。如果在 pDacl 或 pSacl 参数中指定 ACL，则安全描述符与对象相关联。安全描述符根据子对象的继承属性传播到子对象的树。
TREE_SEC_INFO_RESET 0x00000002	安全信息在 pObjectName 参数和该对象的子对象的树上重置。将从树上的所有对象中删除任何现有安全信息。如果树中的任何对象未向调用方授予修改对象上的安全描述符的适当权限，则会跳过树中该特定节点上的安全信息传播及其对象。操作在 pObjectName 参数指定的对象下的树的其余部分继续执行。
TREE_SEC_INFO_RESET_KEEP_EXPLICIT 0x00000003	安全信息在 pObjectName 参数和该对象的子对象的树上重置。将从树上的所有对象中删除任何现有的继承安全信息。在树中的对象上显式设置的安全信息保持不变。如果树中的任何对象未向调用方授予修改对象上的安全描述符的适当权限，则会跳过树中该特定节点上的安全信息传播及其对象。操作在 pObjectName 参数指定的对象下的树的其余部分继续执行。

[in] fnProgress

指向用于跟踪 TreeSetNamedSecurityInfo 函数进度的函数的指针。进度函数的原型是：

#include <windows.h>
#include <Aclapi.h>
#pragma comment(lib, "Advapi32.lib")

typedef VOID (*FN_PROGRESS) (
  IN LPWSTR pObjectName,              // Name of object just processed
  IN DWORD Status,                    // Status of operation on object
  IN OUT PPROG_INVOKE_SETTING
                      pInvokeSetting, // When to set
  IN PVOID Args,                      // Caller specific data
  IN BOOL SecuritySet                 // Whether security was set
);

处理节点时，progress 函数为调用方提供进度和错误信息。调用方在 fnProgress 中指定进度函数，在树操作期间， TreeSetNamedSecurityInfo 会传递上次处理的对象的名称、该操作的错误状态以及当前PROG_INVOKE_SETTING值。调用方可以使用 pInvokeSetting 更改PROG_INVOKE_SETTING值。

如果未使用任何进度函数，请将此参数设置为 NULL。

[in] ProgressInvokeSetting

PROG_INVOKE_SETTING枚举的值，该值指定 progress 函数的初始设置。

[in, optional] Args

指向由调用方指定的进度函数参数 的 VOID 的指针。

返回值

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

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

注解

此函数不支持设置 NULL 所有者、组、DACL 或 SACL。

如果调用方不包含支持所请求的所有者、组、DACL 和 SACL 更新的适当特权和权限，则不会执行任何更新。

当 dwAction 参数的值设置为 TREE_SEC_INFO_SET 时，此函数提供与 SetNamedSecurityInfo 函数相同的功能，ProgressInvokeSetting 参数的值设置为 ProgressInvokePrePostError，fnProgress 参数指向的函数将其 pInvokeSetting 参数的值设置为 ProgressInvokePrePostError。

此函数类似于 TreeResetNamedSecurityInfo 函数：

如果将 TreeSetNamedSecurityInfo 的 dwAction 参数设置为 TREE_SEC_INFO_RESET_KEEP_EXPLICIT，则该函数等效于将 KeepExplicit 参数设置为 TRUE 的 TreeResetNamedSecurityInfo。
如果将 TreeSetNamedSecurityInfo 的 dwAction 参数设置为 TREE_SEC_INFO_RESET，则该函数等效于将 KeepExplicit 参数设置为 FALSE 的 TreeResetNamedSecurityInfo。

注意

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

要求

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

通过

TreeSetNamedSecurityInfoA 函数 (aclapi.h)

语法

参数

返回值

注解

要求

反馈

其他资源