Platform SDK: Access Control

AddAccessAllowedAceEx

The AddAccessAllowedAceEx function adds an access-allowed ACE to the end of a DACL.

BOOL AddAccessAllowedAceEx(
  PACL pAcl,            // access control list
  DWORD dwAceRevision,  // ACL revision level
  DWORD AceFlags,       // ACE inheritance flags
  DWORD AccessMask,     // access mask for the new ACE
  PSID pSid             // trustee SID for new ACE
);

Parameters

pAcl

[in/out] 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.

dwAceRevision

[in] 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.

AceFlags

[in] 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
CONTAINER_INHERIT_ACE	The ACE is inherited by container objects.
INHERIT_ONLY_ACE	The ACE does not apply to the object to which the ACL is assigned, but it can be inherited by child objects.
INHERITED_ACE	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.
NO_PROPAGATE_INHERIT_ACE	The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE bits are not propagated to an inherited ACE.
OBJECT_INHERIT_ACE	The ACE is inherited by noncontainer objects

AccessMask

[in] A set of bit flags that use the ACCESS_MASK format to specify the access rights that the new ACE allows to the specified SID.

pSid

[in] Pointer to a SID structure that identifies the user, group, or logon session to which the new ACE allows access.

Return Values

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.

Error value	Description
ERROR_ALLOTTED_SPACE_EXCEEDED	The new ACE does not fit into the ACL. A larger ACL buffer is required.
ERROR_INVALID_ACL	The specified ACL is not properly formed.
ERROR_INVALID_FLAGS	The AceFlags parameter is invalid.
ERROR_INVALID_SID	The specified SID is not structurally valid.
ERROR_REVISION_MISMATCH	The specified revision is not known or is incompatible with that of the ACL.
ERROR_SUCCESS	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

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Advapi32.lib.

AddAccessAllowedAceEx

Parameters

Return Values

Remarks

Requirements

See Also