Export (0) Print
Expand All
Expand Minimize

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 codeDescription
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

See also

Low-level Access Control
Low-level Access Control Functions
ACL_SIZE_INFORMATION
AddAccessAllowedAce
AddAccessDeniedAce
AddAuditAccessAce
DeleteAce
FindFirstFreeAce
GetAce
GetAclInformation

 

 

Community Additions

ADD
Show:
© 2014 Microsoft