GetAuditedPermissionsFromAclA function (aclapi.h)
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.
Syntax
DWORD GetAuditedPermissionsFromAclA(
[in] PACL pacl,
[in] PTRUSTEE_A pTrustee,
[out] PACCESS_MASK pSuccessfulAuditedRights,
[out] PACCESS_MASK pFailedAuditRights
);
Parameters
[in] pacl
A pointer to an ACL structure from which to get the trustee's audited access rights.
[in] pTrustee
A pointer to a TRUSTEE structure that identifies the trustee. A trustee can be a user, group, or program (such as a Windows service). You can use a name or a security identifier (SID) to identify a trustee. For information about SID structures, see SID.
[out] pSuccessfulAuditedRights
A pointer to an ACCESS_MASK structure that receives the successful audit mask for rights audited for the trustee specified by the pTrustee parameter. The system generates an audit record when the trustee successfully uses any of these access rights.
[out] pFailedAuditRights
A pointer to an ACCESS_MASK structure that receives the failed audit mask for rights audited for the trustee specified by the pTrustee parameter. The system generates an audit record when the trustee fails in an attempt to use any of these rights.
Return value
If the function succeeds, the function returns ERROR_SUCCESS.
If the function fails, it returns 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.
Note
The aclapi.h header defines GetAuditedPermissionsFromAcl as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | aclapi.h |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |