AddAuditAccessAce

The AddAuditAccessAce function adds a system-audit ACE to a system ACL. The access of a specified SID is audited.

To control whether the new ACE can be inherited by child objects, use the AddAuditAccessAceEx function.

BOOL AddAuditAccessAce(
  PACL pAcl,           // access-control list
  DWORD dwAceRevision, // ACL revision level
  DWORD dwAccessMask,  // access mask
  PSID pSid,           // security identifier
  BOOL bAuditSuccess,  // auditing successful access
  BOOL bAuditFailure   // auditing unsuccessful access 
);

Parameters

pAcl

[in/out] Pointer to an ACL structure. This function adds a system-audit ACE to this ACL. The ACE is in the form of an SYSTEM_AUDIT_ACE structure.

dwAceRevision

[in] Specifies the revision level of the ACL being modified.

Windows NT 4.0 and earlier: This value must be ACL_REVISION.

Windows 2000: This value can be ACL_REVISION or ACL_REVISION_DS. Use ACL_REVISION_DS if the ACL contains object-specific ACEs.

dwAccessMask

[in] Specifies the mask of access rights to be audited for the specified SID.

pSid

[in] Pointer to the SID structure representing the process whose access is being audited.

bAuditSuccess

[in] Specifies whether successful access attempts are to be audited. Set this flag to TRUE to enable auditing; otherwise, set it to FALSE.

bAuditFailure

[in] Specifies whether unsuccessful access attempts are to be audited. Set this flag to TRUE to enable auditing; otherwise, set it to FALSE.

Return Values

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.

Remarks

An ACE is an access-control entry. An ACL is an access-control list. A SID is a security identifier.

The ACE_HEADER structure placed in the ACE by the AddAuditAccessAce function specifies a type and size, but provides no ACE flags.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Advapi32.lib.

See Also

Low-Level Access-Control Overview, Low-Level Access Control Functions, ACE_HEADER, ACL, AddAccessAllowedAce, AddAccessDeniedAce, AddAce, AddAuditAccessAceEx, DeleteAce, GetAce, SID, SYSTEM_AUDIT_ACE