AddAce function (securitybaseapi.h)

The AddAce function adds one or more access control entries (ACEs) to a specified access control list (ACL).

Syntax

BOOL AddAce(
  [in, out] PACL   pAcl,
  [in]      DWORD  dwAceRevision,
  [in]      DWORD  dwStartingAceIndex,
  [in]      LPVOID pAceList,
  [in]      DWORD  nAceListLength
);

Parameters

[in, out] pAcl

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

[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. This value must be compatible with the AceType field of all ACEs in pAceList. Otherwise, the function will fail and set the last error to ERROR_INVALID_PARAMETER.

[in] dwStartingAceIndex

Specifies the position in the ACL's list of ACEs at which to add new ACEs. A value of zero inserts the ACEs at the beginning of the list. A value of MAXDWORD appends the ACEs to the end of the list.

[in] pAceList

A pointer to a list of one or more ACEs to be added to the specified ACL. The ACEs in the list must be stored contiguously.

[in] nAceListLength

Specifies the size, in bytes, of the input buffer pointed to by the pAceList parameter.

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
ERROR_INSUFFICIENT_BUFFER
The new ACE does not fit into the ACL. A larger ACL buffer is required.
ERROR_INVALID_PARAMETER
The specified ACL is not properly formed.
ERROR_SUCCESS
The ACE was successfully added.

Remarks

Applications frequently use the FindFirstFreeAce and GetAce functions when using the AddAce function to manipulate an ACL. In addition, the ACL_SIZE_INFORMATION structure retrieved by the GetAclInformation function contains the size of the ACL and the number of ACEs it contains.

Examples

For an example that uses this function, see Starting an Interactive Client Process.

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

See also

ACL_SIZE_INFORMATION

AddAccessAllowedAce

AddAccessDeniedAce

AddAuditAccessAce

DeleteAce

FindFirstFreeAce

GetAce

GetAclInformation

Low-level Access Control

Low-level Access Control Functions