RsopAccessCheckByType function (userenv.h)

Article
10/13/2021

The RSoPAccessCheckByType function determines whether a security descriptor grants a specified set of access rights to the client identified by an RSOPTOKEN.

Syntax

USERENVAPI HRESULT RsopAccessCheckByType(
  [in]  PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]  PSID                 pPrincipalSelfSid,
  [in]  PRSOPTOKEN           pRsopToken,
  [in]  DWORD                dwDesiredAccessMask,
  [in]  POBJECT_TYPE_LIST    pObjectTypeList,
  [in]  DWORD                ObjectTypeListLength,
  [in]  PGENERIC_MAPPING     pGenericMapping,
  [in]  PPRIVILEGE_SET       pPrivilegeSet,
  [in]  LPDWORD              pdwPrivilegeSetLength,
  [out] LPDWORD              pdwGrantedAccessMask,
  [out] LPBOOL               pbAccessStatus
);

Parameters

[in] pSecurityDescriptor

Pointer to a SECURITY_DESCRIPTOR against which access on the object is checked.

[in] pPrincipalSelfSid

Pointer to a SID. If the security descriptor is associated with an object that represents a principal (for example, a user object), this parameter should be the SID of the object. When evaluating access, this SID logically replaces the SID in any ACE containing the well-known PRINCIPAL_SELF SID ("S-1-5-10"). For more information, see Security Identifiers and Well-Known SIDs.

This parameter should be NULL if the protected object does not represent a principal.

[in] pRsopToken

Pointer to a valid RSOPTOKEN representing the client attempting to gain access to the object.

[in] dwDesiredAccessMask

Specifies an access mask that indicates the access rights to check. This mask can contain a combination of generic, standard and specific access rights. For more information, see Access Rights and Access Masks.

[in] pObjectTypeList

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 indicating 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, RSoPAccessCheckByType fails and GetLastError returns ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

Specifies the number of elements in the pObjectTypeList array.

[in] pGenericMapping

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

[in] pPrivilegeSet

This parameter is currently unused.

[in] pdwPrivilegeSetLength

This parameter is currently unused.

[out] pdwGrantedAccessMask

Pointer to an access mask that receives the granted access rights.

If the function succeeds, the pbAccessStatus parameter is set to TRUE, and the mask is updated to contain the standard and specific rights granted. If pbAccessStatus is set to FALSE, this parameter is set to zero. If the function fails, the mask is not modified.

[out] pbAccessStatus

Pointer to a variable that receives the results of the access check.

If the function succeeds, and the requested set of access rights are granted, this parameter is set to TRUE. Otherwise, this parameter is set to FALSE. If the function fails, the status is not modified.

Return value

If the function succeeds, the return value is S_OK. Otherwise, the function returns one of the COM error codes defined in the Platform SDK header file WinError.h.

Remarks

The RSoPAccessCheckByType function compares the specified security descriptor with the specified RSOPTOKEN and indicates, in the pbAccessStatus parameter, whether access is granted or denied.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	userenv.h
Library	Userenv.lib
DLL	Userenv.dll