AddAuditAccessAceEx

[This is preliminary documentation and subject to change.]

The AddAuditAccessAceEx function adds a system-audit ACE to the end of a SACL. This function is identical to the AddAuditAccessAce function, except that it allows you to also specify flags that control whether the new ACE can be inherited by child objects.

BOOL AddAuditAccessAceEx(
  PACL pAcl,            // pointer to an ACL
  DWORD dwAceRevision,  // ACL revision level
  DWORD AceFlags,       // flags for ACE inheritance and audit type
  DWORD dwAccessMask,   // access mask for the new ACE
  PSID pSid,            // SID of the trustee for the new ACE
  BOOL bAuditSuccess,   // audit successful access attempts
  BOOL bAuditFailure    // audit unsuccessful access attempts
);
 

Parameters

pAcl

Pointer to a SACL. The AddAuditAccessAceEx function adds a system-audit ACE to this SACL. The ACE is in the form of a SYSTEM_AUDIT_ACE structure.

dwAceRevision

Specifies the revision level of the ACL being modified. This value can be ACL_REVISION or ACL_REVISION_DS. Use ACL_REVISION unless you are sure the SACL contains object type ACEs.

AceFlags

A set of bit flags that control ACE inheritance and the type of access attempts to audit. The function sets these flags in the AceFlags member of the ACE_HEADER structure of the new ACE. This parameter can be a combination of the following values.

Value	Meaning
CONTAINER_INHERIT_ACE
	The ACE is inherited by container objects.
FAILED_ACCESS_ACE_FLAG
	If you set this flag or specify TRUE for the bAuditFailure parameter, failed attempts to use the specified access rights cause the system to generate an audit record in the security event log.
INHERIT_ONLY_ACE
	The ACE does not apply to the object to which the ACL is assigned, but it can be inherited by child objects.
INHERITED_ACE
	Indicates an inherited ACE. This flag allows operations that change the security on a tree of objects to modify inherited ACEs, while not changing ACEs that were directly applied to the object.
NO_PROPAGATE_INHERIT_ACE
	The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE bits are not propagated to an inherited ACE.
OBJECT_INHERIT_ACE
	The ACE is inherited by noncontainer objects.
SUCCESSFUL_ACCESS_ACE_FLAG
	If you set this flag or specify TRUE for the bAuditSuccess parameter, successful uses of the specified access rights cause the system to generate an audit record in the security event log.

AccessMask

A set of bit flags that use the ACCESS_MASK format to specify the access rights that the new ACE audits for the specified SID. This mask must use the Windows NT access mask format, not the provider-independent access-mask format.

pSid

Pointer to a SID structure that identifies the user, group, or logon session for which the new ACE audits access.

bAuditSuccess

Specifies whether successful uses of the specified access rights cause the system to generate an audit record in the security event log. If this flag is TRUE or if the AceFlags parameter specifies the SUCCESSFUL_ACCESS_ACE_FLAG flag, the system records successful access attempts; otherwise, it does not.

bAuditFailure

Specifies whether failed attempts to use the specified access rights cause the system to generate an audit record in the security event log. If this flag is TRUE or if the AceFlags parameter specifies the FAILED_ACCESS_ACE_FLAG flag, the system records failed access attempts; otherwise, it does not.

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. If the AceFlags parameter specifies invalid flags, GetLastError returns ERROR_INVALID_FLAGS.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use advapi32.lib.

See Also

Low-Level Access-Control Overview, Low-Level Access Control Functions, ACE_HEADER, ACL, AddAccessAllowedAceEx, AddAccessDeniedAceEx, AddAuditAccessAce, SYSTEM_AUDIT_ACE