TreeResetNamedSecurityInfoW 函数 (aclapi.h)

TreeResetNamedSecurityInfo 函数在指定对象的 安全描述符 中重置指定的安全信息。 此函数允许在整个树中传播 系统访问控制列表(SACL)中的指定 自由访问控制列表(DACL)或任何元素。 此函数支持回调函数来跟踪树操作的进度。

语法

DWORD TreeResetNamedSecurityInfoW(
  [in]           LPWSTR               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]           BOOL                 KeepExplicit,
  [in, optional] FN_PROGRESS          fnProgress,
  [in]           PROG_INVOKE_SETTING  ProgressInvokeSetting,
  [in, optional] PVOID                Args
);

参数

[in] pObjectName

指向 null-terminated 字符串的指针,该字符串指定要接收更新安全信息的对象的根节点对象的名称。 支持的对象是注册表项和文件对象。 有关不同对象类型的字符串格式的说明,请参阅 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] KeepExplicit

用于定义是否保留或删除子树显式定义的 ACE 的布尔值。 如果 KeepExplicit为 TRUE,则为每个子树 DACL 和 SACL 保留显式定义的 ACE,并且继承的 ACE 将替换为从 pDaclpSacl继承的 ACE。 如果 KeepExplicit为 FALSE,则在继承的 ACE 替换为从 pDaclpSacl之前,将删除每个子树 DACL 和 SACL 的显式定义的 ACE。

[in, optional] fnProgress

指向用于跟踪 TreeResetNamedSecurityInfo 函数进度的函数的指针。 进度函数的原型为:

#include <windows.h>
#include <Aclapi.h>

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
);

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

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

[in] ProgressInvokeSetting

指定进度函数的初始设置的 PROG_INVOKE_SETTING 枚举的值。

[in, optional] Args

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

返回值

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

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

言论

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

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

此函数类似于 TreeSetNamedSecurityInfo 函数:

  • 如果 TreeResetNamedSecurityInfoKeepExplicit 参数设置为 TRUE,则该函数等效于 TreeSetNamedSecurityInfodwAction 参数设置为TREE_SEC_INFO_RESET_KEEP_EXPLICIT。
  • 如果 TreeResetNamedSecurityInfoKeepExplicit 参数设置为 FALSE,则该函数等效于将 TreeSetNamedSecurityInfo,并将 dwAction 参数设置为TREE_SEC_INFO_RESET。

注意

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

要求

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