Platform SDK: Access Control |
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.
BOOL AccessCheckByTypeResultList( PSECURITY_DESCRIPTOR pSecurityDescriptor, // SD PSID PrincipalSelfSid, // object SID HANDLE ClientToken, // handle to client access token DWORD DesiredAccess, // requested access rights POBJECT_TYPE_LIST ObjectTypeList, // array of object types DWORD ObjectTypeListLength, // number of object types PGENERIC_MAPPING GenericMapping, // mapping PPRIVILEGE_SET PrivilegeSet, // privileges used LPDWORD PrivilegeSetLength, // size of privilege-set buffer LPDWORD GrantedAccessList, // array of granted rights LPDWORD AccessStatusList // array of results );
This parameter should be NULL if the protected object does not represent a principal.
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.
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.
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.
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 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.
Windows NT/2000: Requires Windows 2000.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Advapi32.lib.
Client/Server Access Control Overview, Client/Server Access Control Functions, AccessCheck, AccessCheckAndAuditAlarm, AccessCheckByType, AccessCheckByTypeAndAuditAlarm, AccessCheckByTypeResultListAndAuditAlarm, GENERIC_MAPPING, MakeAbsoluteSD, MapGenericMask, PRIVILEGE_SET, SECURITY_DESCRIPTOR