AddAccessAllowedAceEx function (securitybaseapi.h)
The AddAccessAllowedAceEx function adds an access-allowed access control entry (ACE) to the end of a discretionary access control list (DACL).
Syntax
BOOL AddAccessAllowedAceEx(
[in, out] PACL pAcl,
[in] DWORD dwAceRevision,
[in] DWORD AceFlags,
[in] DWORD AccessMask,
[in] PSID pSid
);
Parameters
[in, out] pAcl
A pointer to a DACL. The AddAccessAllowedAceEx function adds an access-allowed ACE to the end of this DACL. The ACE is in the form of an ACCESS_ALLOWED_ACE structure.
[in] dwAceRevision
Specifies the revision level of the DACL being modified. This value can be ACL_REVISION or ACL_REVISION_DS. Use ACL_REVISION_DS if the DACL contains object-specific ACEs.
[in] AceFlags
A set of bit flags that control ACE inheritance. The function sets these flags in the AceFlags member of the ACE_HEADER structure of the new ACE. This parameter can be a combination of the following values.
| Value | Meaning |
|---|---|
|
The ACE is inherited by container objects. |
|
The ACE does not apply to the object to which the access control list (ACL) is assigned, but it can be inherited by child objects. |
|
Indicates an inherited ACE. This flag allows operations that change the security on a tree of objects to modify inherited ACEs while not changing ACEs that were directly applied to the object. |
|
The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE bits are not propagated to an inherited ACE. |
|
The ACE is inherited by noncontainer objects. |
[in] AccessMask
A set of bit flags that use the ACCESS_MASK format. These flags specify the access rights that the new ACE allows for the specified security identifier (SID).
[in] pSid
A pointer to a SID that identifies the user, group, or logon session to which the new ACE allows access.
Return value
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError. The following are possible error values.
| Return code | Description |
|---|---|
|
The new ACE does not fit into the ACL. A larger ACL buffer is required. |
|
The specified ACL is not properly formed. |
|
The AceFlags parameter is not valid. |
|
The specified SID is not structurally valid. |
|
The specified revision is not known or is incompatible with that of the ACL. |
|
The ACE was successfully added. |
Remarks
The caller must ensure that ACEs are added to the DACL in the correct order. For more information, see Order of ACEs in a DACL.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | securitybaseapi.h (include Windows.h) |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |