Export (0) Print
Expand All
Expand Minimize

SetEntriesInAcl function

The SetEntriesInAcl function creates a new access control list (ACL) by merging new access control or audit control information into an existing ACL structure.

Syntax


DWORD WINAPI SetEntriesInAcl(
  _In_      ULONG cCountOfExplicitEntries,
  _In_opt_  PEXPLICIT_ACCESS pListOfExplicitEntries,
  _In_opt_  PACL OldAcl,
  _Out_     PACL *NewAcl
);

Parameters

cCountOfExplicitEntries [in]

The number of EXPLICIT_ACCESS structures in the pListOfExplicitEntries array.

pListOfExplicitEntries [in, optional]

A pointer to an array of EXPLICIT_ACCESS structures that describe the access control information to merge into the existing ACL.

OldAcl [in, optional]

A pointer to the existing ACL. This parameter can be NULL, in which case, the function creates a new ACL based on the EXPLICIT_ACCESS entries.

NewAcl [out]

A pointer to a variable that receives a pointer to the new ACL. If the function succeeds, you must call the LocalFree function to free the returned buffer.

Return value

If the function succeeds, the function returns ERROR_SUCCESS.

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

Remarks

Each entry in the array of EXPLICIT_ACCESS structures specifies access control or audit control information for a specified trustee. A trustee can be a user, group, or other security identifier (SID) value, such as a logon identifier or logon type (for instance, a Windows service or batch job). You can use a name or a SID to identify a trustee.

You can use the SetEntriesInAcl function to modify the list of access control entries (ACEs) in a discretionary access control list (DACL) or a system access control list (SACL). Note that SetEntriesInAcl does not prevent you from mixing access control and audit control information in the same ACL; however, the resulting ACL will contain meaningless entries.

For a DACL, the grfAccessMode member of the EXPLICIT_ACCESS structure specifies whether to allow, deny, or revoke access rights for the trustee. This member can specify one of the following values:

  • GRANT_ACCESS
  • SET_ACCESS
  • DENY_ACCESS
  • REVOKE_ACCESS

For information about these values, see ACCESS_MODE.

The SetEntriesInAcl function places any new access-denied ACEs at the beginning of the list of ACEs for the new ACL. This function places any new access-allowed ACEs just before any existing access-allowed ACEs.

For a SACL, the grfAccessMode member of the EXPLICIT_ACCESS structure can specify the following values:

  • REVOKE_ACCESS
  • SET_AUDIT_FAILURE
  • SET_AUDIT_SUCCESS

SET_AUDIT_FAILURE and SET_AUDIT_SUCCESS can be combined. For information about these values, see ACCESS_MODE.

The SetEntriesInAcl function places any new system-audit ACEs at the beginning of the list of ACEs for the new ACL.

Examples

For an example that uses this function, see Modifying the ACLs of an Object or Creating a Security Descriptor for a New Object or Taking Object Ownership.

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

SetEntriesInAclW (Unicode) and SetEntriesInAclA (ANSI)

See also

Access Control
Basic Access Control Functions
ACCESS_ALLOWED_ACE
ACCESS_DENIED_ACE
ACL
EXPLICIT_ACCESS
LocalFree
SYSTEM_AUDIT_ACE

 

 

Community Additions

ADD
Show:
© 2014 Microsoft