BuildExplicitAccessWithName

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

VOID BuildExplicitAccessWithName(
  PEXPLICIT_ACCESS pExplicitAccess,
                        // pointer to the structure to initialize
  LPTSTR pTrusteeName,  // name of the trustee to put in the 
                        // structure
  DWORD AccessPermissions,  // access mask to put in the structure
  ACCESS_MODE AccessMode,  // access mode to put in the structure
  DWORD Inheritance     // inheritance type to put in the structure
);
 

Parameters

pExplicitAccess
Pointer to an EXPLICIT_ACCESS structure to initialize. BuildExplicitAccessWithName does not allocate any memory. If this parameter is NULL, the function does nothing.
pTrusteeName
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:
Member Value
pMultipleTrustee NULL
MultipleTrusteeOperation NO_MULTIPLE_TRUSTEE
TrusteeForm TRUSTEE_IS_NAME
TrusteeType TRUSTEE_IS_UNKNOWN

AccessPermissions
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
Specifies an access mode for the grfAccessMode member of the EXPLICIT_ACCESS structure. The access mode indicates whether the ACE allows, denies, or audits the specified rights. This parameter contains values from the ACCESS_MODE enumeration.
Inheritance
Specifies an inheritance type for the grfInheritance member of the EXPLICIT_ACCESS structure. This value is a set of bit flags that determines 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_ONLY_INHERIT
Other containers that are contained by the primary object inherit the ACE. This flag corresponds to the CONTAINER_INHERIT_ACE flag.
SUB_OBJECTS_ONLY_INHERIT
Noncontainer objects contained by the primary object inherit the ACE. This flag corresponds to the OBJECT_INHERIT_ACE flag.
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.

Return Values

None.

QuickInfo

  Windows NT: Requires version 4.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in aclapi.h.
  Import Library: Use advapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Windows NT 4.0 Access Control Overview, Windows NT 4.0 Access-Control Functions, ACE, ACL, EXPLICIT_ACCESS, GetExplicitEntriesFromAcl, SetEntriesInAcl, TRUSTEE