nf-aclapi-buildexplicitaccesswithnamew.md

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.BuildExplicitAccessWithNameW	BuildExplicitAccessWithNameW function (aclapi.h)	Initializes an EXPLICIT_ACCESS structure with data specified by the caller. The trustee is identified by a name string. (Unicode)	BuildExplicitAccessWithName BuildExplicitAccessWithName function [Security] BuildExplicitAccessWithNameW CONTAINER_INHERIT_ACE INHERIT_ONLY_ACE MultipleTrusteeOperation NO_PROPAGATE_INHERIT_ACE OBJECT_INHERIT_ACE SUB_CONTAINERS_AND_OBJECTS_INHERIT SUB_CONTAINERS_ONLY_INHERIT SUB_OBJECTS_ONLY_INHERIT TrusteeForm TrusteeType _win32_buildexplicitaccesswithname aclapi/BuildExplicitAccessWithName aclapi/BuildExplicitAccessWithNameW pMultipleTrustee security.buildexplicitaccesswithname	security\buildexplicitaccesswithname.htm	security	5f12db19-63cf-4be6-9450-3c36e425967b	12/05/2018	BuildExplicitAccessWithName, BuildExplicitAccessWithName function [Security], BuildExplicitAccessWithNameA, BuildExplicitAccessWithNameW, CONTAINER_INHERIT_ACE, INHERIT_ONLY_ACE, MultipleTrusteeOperation, NO_PROPAGATE_INHERIT_ACE, OBJECT_INHERIT_ACE, SUB_CONTAINERS_AND_OBJECTS_INHERIT, SUB_CONTAINERS_ONLY_INHERIT, SUB_OBJECTS_ONLY_INHERIT, TrusteeForm, TrusteeType, _win32_buildexplicitaccesswithname, aclapi/BuildExplicitAccessWithName, aclapi/BuildExplicitAccessWithNameA, aclapi/BuildExplicitAccessWithNameW, pMultipleTrustee, security.buildexplicitaccesswithname	aclapi.h		Windows	Windows XP [desktop apps only]	Windows Server 2003 [desktop apps only]				BuildExplicitAccessWithNameW (Unicode) and BuildExplicitAccessWithNameA (ANSI)						Advapi32.lib	Advapi32.dll		Windows			19H1	BuildExplicitAccessWithNameW aclapi/BuildExplicitAccessWithNameW	c++	APIRef kbSyntax	DllExport	Advapi32.dll API-MS-Win-security-trustee-l1-1-1.dll advapi32legacy.dll	BuildExplicitAccessWithName BuildExplicitAccessWithNameA BuildExplicitAccessWithNameW

BuildExplicitAccessWithNameW function

-description

The BuildExplicitAccessWithName function initializes an EXPLICIT_ACCESS structure with data specified by the caller. The trustee is identified by a name string.

-parameters

-param pExplicitAccess [in, out]

A pointer to an EXPLICIT_ACCESS structure to initialize. The BuildExplicitAccessWithName function does not allocate any memory. This parameter cannot be NULL.

-param pTrusteeName [in, optional]

A pointer to a null-terminated string that contains the name of the trustee for the ptstrName member of the TRUSTEE structure. The BuildExplicitAccessWithName function sets the other members of the TRUSTEE structure as follows.

Value	Meaning
pMultipleTrustee	NULL
MultipleTrusteeOperation	NO_MULTIPLE_TRUSTEE
TrusteeForm	TRUSTEE_IS_NAME
TrusteeType	TRUSTEE_IS_UNKNOWN

-param AccessPermissions [in]

Specifies an access mask for the grfAccessPermissions member of the EXPLICIT_ACCESS structure. The mask is a set of bit flags that use the ACCESS_MASK format to specify the access rights that an ACE allows, denies, or audits for the trustee. The functions that use the EXPLICIT_ACCESS structure do not convert, interpret, or validate the bits in this mask.

-param AccessMode [in]

Specifies an access mode for the grfAccessMode member of the EXPLICIT_ACCESS structure. The access mode indicates whether the access control entry (ACE) allows, denies, or audits the specified rights. For a discretionary access control list (DACL), this parameter can be one of the values from the ACCESS_MODE enumeration. For a system access control list (SACL), this parameter can be a combination of ACCESS_MODE values.

-param Inheritance [in]

Specifies an inheritance type for the grfInheritance member of the EXPLICIT_ACCESS structure. This value is a set of bit flags that determine whether other containers or objects can inherit the ACE from the primary object to which the ACL is attached. The value of this member corresponds to the inheritance portion (low-order byte) of the AceFlags member of the ACE_HEADER structure. This parameter can be NO_INHERITANCE to indicate that the ACE is not inheritable, or it can be a combination of the following values.

Value	Meaning
CONTAINER_INHERIT_ACE	Other containers that are contained by the primary object inherit the ACE.
INHERIT_ONLY_ACE	The ACE does not apply to the primary object to which the ACL is attached, but objects contained by the primary object inherit the ACE.
NO_PROPAGATE_INHERIT_ACE	The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE flags are not propagated to an inherited ACE.
OBJECT_INHERIT_ACE	Noncontainer objects contained by the primary object inherit the ACE.
SUB_CONTAINERS_AND_OBJECTS_INHERIT	Both containers and noncontainer objects that are contained by the primary object inherit the ACE. This flag corresponds to the combination of the CONTAINER_INHERIT_ACE and OBJECT_INHERIT_ACE flags.
SUB_CONTAINERS_ONLY_INHERIT	Other containers that are contained by the primary object inherit the ACE. This flag corresponds to the combination of the CONTAINER_INHERIT_ACE and INHERIT_ONLY_ACE flags.
SUB_OBJECTS_ONLY_INHERIT	Noncontainer objects contained by the primary object inherit the ACE. This flag corresponds to the combination of the OBJECT_INHERIT_ACE and INHERIT_ONLY_ACE flags.

-see-also

ACE

ACL

Access Control Overview

Basic Access Control Functions

EXPLICIT_ACCESS

GetExplicitEntriesFromAcl

SetEntriesInAcl

TRUSTEE

-remarks

Note

The aclapi.h header defines BuildExplicitAccessWithName 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.