GetAuditedPermissionsFromAcl

The GetAuditedPermissionsFromAcl function retrieves the audited access rights for a specified trustee. The audited rights are based on the access-control entries (ACEs) of a specified access-control list (ACL). The audited access rights indicate the types of access attempts that cause the system to generate an audit record in the system event log. The audited rights include those that the ACL specifies for the trustee or for any groups of which the trustee is a member. In determining the audited rights, the function does not consider the security privileges held by the trustee.

DWORD GetAuditedPermissionsFromAcl(
  PACL pacl,                             // source ACL
  PTRUSTEE pTrustee,                     // trustee
  PACCESS_MASK pSuccessfulAuditedRights, // access rights
  PACCESS_MASK pFailedAuditRights        // failed access rights
);

Parameters

pacl

[in] Pointer to an ACL structure from which to get the trustee's audited access rights.

pTrustee

[in] Pointer to a TRUSTEE structure that identifies the trustee. A trustee can be a user, group, or program (such as a Win32 service). You can use a name or a security identifier (SID) to identify a trustee.

pSuccessfulAuditedRights

[out] Pointer to an ACCESS_MASK structure that receives a set of access rights. The system generates an audit record when the trustee successfully uses any of these access rights.

pFailedAuditRights

[out] Pointer to an ACCESS_MASK structure that receives a set of access rights based on the access-control entries in the specified ACL. The system generates an audit record when the trustee fails in an attempt to use any of these rights.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in Winerror.h.

Remarks

The GetAuditedPermissionsFromAcl function checks all system-audit ACEs in the ACL to determine the audited rights for the trustee. For all ACEs that specify audited rights for a group, GetAuditedPermissionsFromAcl enumerates the members of the group to determine whether the trustee is a member. The function returns an error if it cannot enumerate the members of a group.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Header: Declared in Aclapi.h.
  Library: Use Advapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Access Control Overview, Access Control Functions, ACCESS_MASK, ACE, ACL, GetEffectiveRightsFromAcl, SID, SYSTEM_AUDIT_ACE, TRUSTEE