Skip to content

Latest commit

 

History

History
150 lines (105 loc) · 8.81 KB

nf-aclapi-treeresetnamedsecurityinfow.md

File metadata and controls

150 lines (105 loc) · 8.81 KB
Raw
UID title description helpviewer_keywords old-location tech.root ms.assetid ms.date ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames req.redist ms.custom f1_keywords dev_langs topic_type api_type api_location api_name
NF:aclapi.TreeResetNamedSecurityInfoW
TreeResetNamedSecurityInfoW function (aclapi.h)
Resets specified security information in the security descriptor of a specified tree of objects. (Unicode)
TreeResetNamedSecurityInfo
TreeResetNamedSecurityInfo function [Security]
TreeResetNamedSecurityInfoW
aclapi/TreeResetNamedSecurityInfo
aclapi/TreeResetNamedSecurityInfoW
security.treeresetnamedsecurityinfo
security\treeresetnamedsecurityinfo.htm
security
adae7d07-a452-409e-b1a1-e9f86f873e39
12/05/2018
TreeResetNamedSecurityInfo, TreeResetNamedSecurityInfo function [Security], TreeResetNamedSecurityInfoA, TreeResetNamedSecurityInfoW, aclapi/TreeResetNamedSecurityInfo, aclapi/TreeResetNamedSecurityInfoA, aclapi/TreeResetNamedSecurityInfoW, security.treeresetnamedsecurityinfo
aclapi.h
Windows
Windows XP [desktop apps only]
Windows Server 2003 [desktop apps only]
TreeResetNamedSecurityInfoW (Unicode) and TreeResetNamedSecurityInfoA (ANSI)
Advapi32.lib
Advapi32.dll
Windows
19H1
TreeResetNamedSecurityInfoW
aclapi/TreeResetNamedSecurityInfoW
c++
APIRef
kbSyntax
DllExport
Advapi32.dll
Ext-MS-Win-AdvAPI32-ntmarta-l1-1-0.dll
advapi32legacy.dll
TreeResetNamedSecurityInfo
TreeResetNamedSecurityInfoA
TreeResetNamedSecurityInfoW

TreeResetNamedSecurityInfoW function

-description

The TreeResetNamedSecurityInfo function resets specified security information in the security descriptor of a specified tree of objects. This function allows a specified discretionary access control list (DACL) or any elements in the system access control list (SACL) to be propagated throughout an entire tree. This function supports a callback function to track the progress of the tree operation.

-parameters

-param pObjectName [in]

		Pointer to a <b>null</b>-terminated string that specifies the name of the root node object for the objects  that are to receive updated security information. Supported objects are registry keys and file objects. For descriptions of the string formats for the different object types, see

SE_OBJECT_TYPE.

-param ObjectType [in]

A value of the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName parameter. The supported values are SE_REGISTRY_KEY and SE_FILE_OBJECT, for registry keys and file objects, respectively.

-param SecurityInfo [in]

A set of bit flags that indicate the type of security information to reset. This parameter can be a combination of the SECURITY_INFORMATION bit flags.

-param pOwner [in, optional]

A pointer to a SID structure that identifies the owner of the object. The SID must be one that can be assigned as the owner SID of a security descriptor. The SecurityInfo parameter must include the OWNER_SECURITY_INFORMATION flag. To set the owner, the caller must have WRITE_OWNER access to each object, including the root object. If you are not setting the owner SID, this parameter can be NULL.

-param pGroup [in, optional]

A pointer to a SID structure that identifies the primary group of the object. The SecurityInfo parameter must include the GROUP_SECURITY_INFORMATION flag. To set the group, the caller must have WRITE_OWNER access to each object, including the root object. If you are not setting the primary group SID, this parameter can be NULL.

-param pDacl [in, optional]

A pointer to an access control list (ACL) structure that represents the new DACL for the objects being reset. The SecurityInfo parameter must include the DACL_SECURITY_INFORMATION flag. The caller must have READ_CONTROL and WRITE_DAC access to each object, including the root object. If you are not setting the DACL, this parameter can be NULL.

-param pSacl [in, optional]

A pointer to an ACL structure that represents the new SACL for the objects being reset. The SecurityInfo parameter must include any of the following flags: SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION, or BACKUP_SECURITY_INFORMATION. If setting SACL_SECURITY_INFORMATION or SCOPE_SECURITY_INFORMATION, the caller must have the SE_SECURITY_NAME privilege enabled. If you are not setting the SACL, this parameter can be NULL.

-param KeepExplicit [in]

Boolean value that defines whether explicitly defined ACEs are kept or deleted for the sub-tree. If KeepExplicit is TRUE, then explicitly defined ACEs are kept for each subtree DACL and SACL, and inherited ACEs are replaced by the inherited ACEs from pDacl and pSacl. If KeepExplicit is FALSE, then explicitly defined ACEs for each subtree DACL and SACL are deleted before the inherited ACEs are replaced by the inherited ACEs from pDacl and pSacl.

-param fnProgress [in, optional]

A pointer to the function used to track the progress of the TreeResetNamedSecurityInfo function. The prototype of the progress function is:

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

The progress function provides the caller with progress and error information when nodes are processed. The caller specifies the progress function in fnProgress, and during the tree operation, TreeResetNamedSecurityInfo passes the name of the last object processed, the error status of that operation, and the current PROG_INVOKE_SETTING value. The caller can change the PROG_INVOKE_SETTING value by using pInvokeSetting.

If no progress function is to be used, set this parameter to NULL.

-param ProgressInvokeSetting [in]

A value of the PROG_INVOKE_SETTING enumeration that specifies the initial setting for the progress function.

-param Args [in, optional]

A pointer to a VOID for progress function arguments specified by the caller.

-returns

If the function succeeds, the function returns ERROR_SUCCESS.

If the function fails, it returns an error code defined in WinError.h.

-remarks

Setting a NULL owner, group, DACL, or SACL is not supported by this function.

If the caller does not contain the proper privileges and permissions to support the requested owner, group, DACL, and SACL updates, then none of the updates are performed.

This function is similar to the TreeSetNamedSecurityInfo function:

  • If the KeepExplicit parameter of TreeResetNamedSecurityInfo is set to TRUE, then the function is equivalent to TreeSetNamedSecurityInfo with the dwAction parameter set to TREE_SEC_INFO_RESET_KEEP_EXPLICIT.
  • If the KeepExplicit parameter of TreeResetNamedSecurityInfo is set to FALSE, then the function is equivalent to TreeSetNamedSecurityInfo with the dwAction parameter set to TREE_SEC_INFO_RESET.

Note

The aclapi.h header defines TreeResetNamedSecurityInfo as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.