Edit

Share via

AddResourceAttributeAce function (securitybaseapi.h)

  • Article

The AddResourceAttributeAce function adds a SYSTEM_RESOURCE_ATTRIBUTE_ACE access control entry (ACE) to the end of a system access control list (SACL). A SYSTEM_RESOURCE_ATTRIBUTE_ACE structure specifies an attribute name and a value-ordered list of elements that is associated with a resource and potentially used during access checks. The set of standard access rights are defined in the Standard Access Rights topic.

Syntax

BOOL AddResourceAttributeAce(
  [in, out] PACL                                   pAcl,
  [in]      DWORD                                  dwAceRevision,
  [in]      DWORD                                  AceFlags,
  [in]      DWORD                                  AccessMask,
  [in]      PSID                                   pSid,
  [in]      PCLAIM_SECURITY_ATTRIBUTES_INFORMATION pAttributeInfo,
  [out]     PDWORD                                 pReturnLength
);

Parameters

[in, out] pAcl

A pointer to an access control list (ACL). This function adds an ACE to this ACL. The value of this parameter cannot be NULL. The ACE is in the form of a SYSTEM_RESOURCE_ATTRIBUTE_ACE structure.

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

For consistency with the Windows 8 Advanced File Permissions UI, applications should specify the CONTAINER_INHERIT_ACE and OBJECT_INHERIT_ACE flags in the AceFlags parameter.

This parameter can be a combination of the following values.

Value Meaning
CONTAINER_INHERIT_ACE
2 (0x2)
 The ACE is inherited by the container objects.
INHERIT_ONLY_ACE
8 (0x8)
 The ACE does not apply to the object the ACE is assigned to, but it can be inherited by child objects.
INHERITED_ACE
16 (0x10)
 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
4 (0x4)
 The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE bits are not propagated to an inherited ACE.
OBJECT_INHERIT_ACE
1 (0x1)
 The ACE is inherited by non-container objects.

[in] AccessMask

Must be zero for Windows 8 and Windows Server 2012.

[in] pSid

Must be the Everyone SID (S-1-1-0) for Windows 8 and Windows Server 2012.

[in] pAttributeInfo

Specifies the attribute information that will be appended after the SID in the ACE.

[out] pReturnLength

The size, in bytes, of the actual ACL buffer used. If the buffer specified by the pAcl parameter is not big enough, the value of this parameter is the total size required for the ACL buffer.

Return value

If the function succeeds, it returns TRUE.

If the function fails, it returns FALSE. To get extended error information, call GetLastError.

Requirements

Requirement Value
Minimum supported client Windows 8 [desktop apps only]
Minimum supported server Windows Server 2012 [desktop apps only]
Target Platform Windows
Header securitybaseapi.h (include Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

See also

Standard Access Rights