Функция AccessCheckByTypeResultList (securitybaseapi.h)

Статья
08/25/2023

Функция AccessCheckByTypeResultList определяет, предоставляет ли дескриптор безопасности указанный набор прав доступа клиенту, определенному маркером доступа. Функция может проверка доступ клиента к иерархии объектов, таких как объект, его наборы свойств и свойства. Функция сообщает о правах доступа, предоставленных или запрещенных каждому типу объектов в иерархии. Как правило, серверные приложения используют эту функцию для проверка доступа к частному объекту.

Синтаксис

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
);

Параметры

[in] pSecurityDescriptor

Указатель на структуру SECURITY_DESCRIPTOR , для которой проверяется доступ.

[in, optional] PrincipalSelfSid

Указатель на идентификатор безопасности (SID). Если дескриптор безопасности связан с объектом, представляющим субъект (например, объект пользователя), параметр PrincipalSelfSid должен быть идентификатором безопасности объекта. При оценке доступа этот идентификатор безопасности логически заменяет идентификатор безопасности в любой записи управления доступом (ACE), содержащей известный идентификатор безопасности PRINCIPAL_SELF (S-1-5-10). Сведения об известных идентификаторах безопасности см. в разделе Известные идентификаторы БЕЗОПАСНОСТИ.

Если защищенный объект не представляет участника, задайте для этого параметра значение NULL.

[in] ClientToken

Дескриптор маркера олицетворения , который представляет клиент, пытающийся получить доступ. Дескриптор должен иметь TOKEN_QUERY доступ к маркеру; В противном случае функция завершается сбоем с ERROR_ACCESS_DENIED.

[in] DesiredAccess

Маска доступа, указывающая права доступа для проверка. Эта маска должна быть сопоставлена функцией MapGenericMask , чтобы она не содержала универсальных прав доступа.

Если этот параметр MAXIMUM_ALLOWED, функция задает маски доступа в массиве GrantedAccess , чтобы указать максимальные права доступа клиента к каждому элементу в списке типов объектов.

[in, out, optional] ObjectTypeList

Указатель на массив OBJECT_TYPE_LIST структур, определяющих иерархию типов объектов, к которым проверка доступ. Каждый элемент в массиве задает GUID, определяющий тип объекта, и значение, указывающее уровень типа объекта в иерархии типов объектов. Массив не должен содержать два элемента с одинаковым ИДЕНТИФИКАТОРом GUID.

Массив должен содержать по крайней мере один элемент. Первый элемент в массиве должен находиться на нулевом уровне и определять сам объект. Массив может иметь только один нулевой элемент уровня. Второй элемент является подобъектом, например набором свойств, на уровне 1. После каждой записи уровня 1 находятся подчиненные записи для подобъектов уровня 2–4. Таким образом, уровни для элементов в массиве могут быть {0, 1, 2, 2, 1, 2, 3}. Если список типов объектов не по порядку, AccessCheckByTypeResultList завершается ошибкой и GetLastError возвращает ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

Количество элементов в массиве ObjectTypeList . Это также количество элементов в массивах, на которые указывают параметры GrantedAccessList и AccessStatusList .

[out] GenericMapping

Указатель на структуру GENERIC_MAPPING , связанную с объектом, для которого проверяется доступ.

[out, optional] PrivilegeSet

Указатель на структуру PRIVILEGE_SET , которая получает привилегии , используемые для проверки доступа. Если привилегии не использовались, функция устанавливает для элемента PrivilegeCount нулевое значение.

[in, out] PrivilegeSetLength

Размер (в байтах) буфера, на который указывает параметр PrivilegeSet .

[out] GrantedAccessList

Указатель на массив масок доступа. Функция задает каждую маску доступа, чтобы указать права доступа, предоставленные соответствующему элементу в списке типов объектов. Если функция завершается сбоем, маски доступа не задаются.

[out] AccessStatusList

Указатель на массив кодов состояния для соответствующих элементов в списке типов объектов. Функция задает элементу нулевое значение, чтобы указать успешное выполнение, или ненулевое значение, указывающее на конкретную ошибку во время проверка доступа. Если функция завершается сбоем, она не задает ни один из элементов в массиве.

Возвращаемое значение

Если функция выполнена успешно, функция возвращает ненулевое значение.

Если функция завершается сбоем, она возвращает ноль. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Функция AccessCheckByTypeResultList сравнивает указанный дескриптор безопасности с указанным маркером доступа и указывает в параметре AccessStatusList , предоставлен или запрещен доступ для каждого элемента в списке типов объектов.

Массив ObjectTypeList не обязательно представляет весь определенный объект. Скорее, он представляет подмножество объекта, для которого проверка доступ. Например, чтобы проверка доступ к двум свойствам в наборе свойств, укажите список типов объектов с четырьмя элементами: сам объект на нулевом уровне, свойство, заданное на уровне 1, и два свойства на уровне 2.

Функция AccessCheckByTypeResultList вычисляет ACE, которые применяются к самому объекту и объектам ACE для типов объектов, перечисленных в массиве ObjectTypeList . Функция игнорирует объекты ACE для типов объектов, не перечисленных в массиве ObjectTypeList . Таким образом, результаты, возвращаемые для нулевого элемента в параметре AccessStatusList , указывают доступ, разрешенный для подмножества объекта, определенного параметром ObjectTypeList , а не ко всему объекту.

Дополнительные сведения о том, как иерархия ACE управляет доступом к объекту и его подобъектам, см. в разделе ACE для управления доступом к свойствам объекта.

Если список управления доступом (DACL) дескриптора безопасности имеет значение NULL, функция предоставляет запрошенный доступ ко всем элементам в списке типов объектов.

Если дескриптор безопасности не содержит идентификаторы безопасности владельца и группы, AccessCheckByTypeResultList завершается сбоем с ERROR_INVALID_SECURITY_DESCR.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	securitybaseapi.h (включая Windows.h)
Библиотека	Advapi32.lib
DLL	Advapi32.dll