Export (0) Print
Expand All
Expand Minimize

BuildExplicitAccessWithName function

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

Syntax


VOID WINAPI BuildExplicitAccessWithName(
  _Inout_   PEXPLICIT_ACCESS pExplicitAccess,
  _In_opt_  LPTSTR pTrusteeName,
  _In_      DWORD AccessPermissions,
  _In_      ACCESS_MODE AccessMode,
  _In_      DWORD Inheritance
);

Parameters

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.

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.

ValueMeaning
pMultipleTrustee

NULL

MultipleTrusteeOperation

NO_MULTIPLE_TRUSTEE

TrusteeForm

TRUSTEE_IS_NAME

TrusteeType

TRUSTEE_IS_UNKNOWN

 

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.

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.

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.

ValueMeaning
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.

 

Return value

This function does not return a value.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Aclapi.h

Library

Advapi32.lib

DLL

Advapi32.dll

Unicode and ANSI names

BuildExplicitAccessWithNameW (Unicode) and BuildExplicitAccessWithNameA (ANSI)

See also

Access Control Overview
Basic Access Control Functions
ACE
ACL
EXPLICIT_ACCESS
GetExplicitEntriesFromAcl
SetEntriesInAcl
TRUSTEE

 

 

Community Additions

ADD
Show:
© 2014 Microsoft