AddConditionalAce function (winbase.h)

Article
10/13/2021

The AddConditionalAce function adds a conditional access control entry (ACE) to the specified access control list (ACL). A conditional ACE specifies a logical condition that is evaluated during access checks.

Syntax

BOOL AddConditionalAce(
  [in, out] PACL   pAcl,
  [in]      DWORD  dwAceRevision,
  [in]      DWORD  AceFlags,
  [in]      UCHAR  AceType,
  [in]      DWORD  AccessMask,
  [in]      PSID   pSid,
  [in]      PWCHAR ConditionStr,
  [out]     DWORD  *ReturnLength
);

Parameters

[in, out] pAcl

A pointer to an ACL. This function adds an ACE to this ACL.

The value of this parameter cannot be NULL.

[in] dwAceRevision

Specifies the revision level of the ACL being modified. This value can be ACL_REVISION or ACL_REVISION_DS. Use ACL_REVISION_DS if the ACL 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
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.

[in] AceType

The type of the ACE.

This can be one of the following values.

Value	Meaning
ACCESS_ALLOWED_CALLBACK_ACE_TYPE 0x9	Access-allowed callback ACE that uses the ACCESS_ALLOWED_CALLBACK_ACE structure.
ACCESS_DENIED_CALLBACK_ACE_TYPE 0xA	Access-denied callback ACE that uses the ACCESS_DENIED_CALLBACK_ACE structure.
SYSTEM_AUDIT_CALLBACK_ACE_TYPE 0xD	System audit callback ACE that uses the SYSTEM_AUDIT_CALLBACK_ACE structure.

[in] AccessMask

Specifies the mask of access rights to be granted to the specified SID.

[in] pSid

A pointer to the SID that represents a user, group, or logon account being granted access.

[in] ConditionStr

A string that specifies the conditional statement to be evaluated for the ACE.

[out] ReturnLength

The size, in bytes, of the ACL. If the buffer specified by the pACL parameter is not of sufficient size, the value of this parameter is the required size.

Return value

If the function succeeds, it returns TRUE.

If the function fails, it returns FALSE. For extended error information, call GetLastError. The following are possible error values.

Return code	Description
ERROR_INSUFFICIENT_BUFFER	The new ACE does not fit into the pAcl buffer.

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	winbase.h (include Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll