Edit

Share via

AddConditionalAce function (winbase.h)

  • Article

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