| Platform SDK: Access Control |
The AccessCheckByTypeResultListAndAuditAlarmByHandle function determines whether a security descriptor grants a specified set of access rights to the client that the calling thread is impersonating. The difference between this function and AccessCheckByTypeResultListAndAuditAlarm is that this function allows the calling thread to perform the access check before impersonating the client.
The function can check 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. If the security descriptor has a SACL with ACEs that apply to the client, the function generates any necessary audit messages in the security event log. Alarms are not currently supported.
BOOL AccessCheckByTypeResultListAndAuditAlarmByHandle( LPCTSTR SubsystemName, // subsystem name LPVOID HandleId, // object's handle identifier HANDLE ClientToken // token object handle LPCTSTR ObjectTypeName, // object type LPCTSTR ObjectName, // object name PSECURITY_DESCRIPTOR pSecurityDescriptor, // SD PSID PrincipalSelfSid, // SID DWORD DesiredAccess, // requested access rights AUDIT_EVENT_TYPE AuditType, // type of audit DWORD Flags, // access check options POBJECT_TYPE_LIST ObjectTypeList, // array of object types DWORD ObjectTypeListLength, // number of object types PGENERIC_MAPPING GenericMapping, // mapping BOOL ObjectCreation, // creation status LPDWORD GrantedAccess, // granted rights LPDWORD AccessStatusList // array of results LPBOOL pfGenerateOnClose // audit generation );
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 mask in GrantedAccess to indicate the maximum access rights the security descriptor allows the client.
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, AccessCheckByTypeResultListAndAuditAlarmByHandle 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.
Like AccessCheckByTypeResultListAndAuditAlarm, the AccessCheckByTypeResultListAndAuditAlarmByHandle function is a combination of the AccessCheckByTypeResultList and AccessCheckAndAuditAlarm functions. However, AccessCheckByTypeResultListAndAuditAlarmByHandle also requires a client token handle to provide security information on the client.
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 AccessCheckByTypeResultListAndAuditAlarmByHandle 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.
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.
To generate audit messages in the security event log, the calling process must have the SE_AUDIT_NAME privilege enabled. The system checks for this privilege in the primary token of the calling process, not the impersonation token of the thread. If the Flags parameter includes the AUDIT_ALLOW_NO_PRIVILEGE flag, the function performs the access check without generating audit messages when the privilege is not enabled.
The AccessCheckByTypeResultListAndAuditAlarmByHandle function fails if the calling thread is not impersonating a client.
If the security descriptor does not contain owner and group SIDs, AccessCheckByTypeResultListAndAuditAlarmByHandle fails with ERROR_INVALID_SECURITY_DESCR.
Windows NT/2000: Requires Windows 2000.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Advapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.
Client/Server Access Control Overview, Client/Server Access Control Functions, AccessCheck, AccessCheckAndAuditAlarm, AccessCheckByType, AccessCheckByTypeResultList, AccessCheckByTypeResultListAndAuditAlarm, GENERIC_MAPPING, MakeAbsoluteSD, MapGenericMask, PRIVILEGE_SET, SECURITY_DESCRIPTOR