AddAce function

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

Syntax


BOOL WINAPI AddAce(
  _Inout_ PACL   pAcl,
  _In_    DWORD  dwAceRevision,
  _In_    DWORD  dwStartingAceIndex,
  _In_    LPVOID pAceList,
  _In_    DWORD  nAceListLength
);

Parameters

pAcl [in, out]: A pointer to an ACL. This function adds an ACE to this ACL.
dwAceRevision [in]: 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.
dwStartingAceIndex [in]: 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.
pAceList [in]: 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.
nAceListLength [in]: 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

Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Header	Winbase.h (include Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll