AccessCheckByTypeResultList function (securitybaseapi.h)

Article
07/27/2022

The AccessCheckByTypeResultList function determines whether a security descriptor grants a specified set of access rights to the client identified by an access token. The function can check the client's access to a hierarchy of objects, such as an object, its property sets, and properties. The function reports the access rights granted or denied to each object type in the hierarchy. Typically, server applications use this function to check access to a private object.

Syntax

BOOL AccessCheckByTypeResultList(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [out]               PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccessList,
  [out]               LPDWORD              AccessStatusList
);

Parameters

[in] pSecurityDescriptor

A pointer to a SECURITY_DESCRIPTOR structure against which access is checked.

[in, optional] PrincipalSelfSid

A pointer to a security identifier (SID). If the security descriptor is associated with an object that represents a principal (for example, a user object), the PrincipalSelfSid parameter should be the SID of the object. When evaluating access, this SID logically replaces the SID in any access control entry (ACE) that contains the well-known PRINCIPAL_SELF SID (S-1-5-10). For information about well-known SIDs, see Well-known SIDs.

If the protected object does not represent a principal, set this parameter to NULL.

[in] ClientToken

A handle to an impersonation token that represents the client attempting to gain access. The handle must have TOKEN_QUERY access to the token; otherwise, the function fails with ERROR_ACCESS_DENIED.

[in] DesiredAccess

An access mask that specifies the access rights to check. This mask must have been mapped by the MapGenericMask function to contain no generic access rights.

If this parameter is MAXIMUM_ALLOWED, the function sets the access masks in the GrantedAccess array to indicate the client's maximum access rights to each element in the object type list.

[in, out, optional] ObjectTypeList

A pointer to an array of OBJECT_TYPE_LIST structures that identify the hierarchy of object types for which to check access. Each element in the array specifies a GUID that identifies the object type and a value that indicates the level of the object type in the hierarchy of object types. The array should not have two elements with the same GUID.

The array must have at least one element. The first element in the array must be at level zero and identify the object itself. The array can have only one level zero element. The second element is a subobject, such as a property set, at level 1. Following each level 1 entry are subordinate entries for the level 2 through 4 subobjects. Thus, the levels for the elements in the array might be {0, 1, 2, 2, 1, 2, 3}. If the object type list is out of order, AccessCheckByTypeResultList fails and GetLastError returns ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

The number of elements in the ObjectTypeList array. This is also the number of elements in the arrays pointed to by the GrantedAccessList and AccessStatusList parameters.

[out] GenericMapping

A pointer to the GENERIC_MAPPING structure associated with the object for which access is being checked.

[out, optional] PrivilegeSet

A pointer to a PRIVILEGE_SET structure that receives the privileges used to perform the access validation. If no privileges were used, the function sets the PrivilegeCount member to zero.

[in, out] PrivilegeSetLength

The size, in bytes, of the buffer pointed to by the PrivilegeSet parameter.

[out] GrantedAccessList

A pointer to an array of access masks. The function sets each access mask to indicate the access rights granted to the corresponding element in the object type list. If the function fails, it does not set the access masks.

[out] AccessStatusList

A pointer to an array of status codes for the corresponding elements in the object type list. The function sets an element to zero to indicate success or a nonzero value to indicate the specific error during the access check. If the function fails, it does not set any of the elements in the array.

Return value

If the function succeeds, the function returns nonzero.

If the function fails, it returns zero. To get extended error information, call GetLastError.

Remarks

For more information, see the How AccessCheck Works overview.

The AccessCheckByTypeResultList function compares the specified security descriptor with the specified access token and indicates, in the AccessStatusList parameter, whether access is granted or denied for each of the elements in the object types list.

The ObjectTypeList array does not necessarily represent the entire defined object. Rather, it represents that subset of the object for which to check access. For instance, to check access to two properties in a property set, specify an object type list with four elements: the object itself at level zero, the property set at level 1, and the two properties at level 2.

The AccessCheckByTypeResultList function evaluates ACEs that apply to the object itself and object-specific ACEs for the object types listed in the ObjectTypeList array. The function ignores object-specific ACEs for object types not listed in the ObjectTypeList array. Thus, the results returned for element zero in the AccessStatusList parameter indicate the access allowed to the subset of the object defined by the ObjectTypeList parameter, not to the entire object.

For more information about how a hierarchy of ACEs controls access to an object and its subobjects, see ACEs to Control Access to an Object's Properties.

If the security descriptor's discretionary access control list (DACL) is NULL, the function grants the requested access to all of the elements in the object type list.

If the security descriptor does not contain owner and group SIDs, AccessCheckByTypeResultList fails with ERROR_INVALID_SECURITY_DESCR.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	securitybaseapi.h (include Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll