AddAce function (securitybaseapi.h)

Article
10/13/2021

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

Share via