Функция ObReferenceObjectByHandle (wdm.h)

Статья
08/08/2023

Подпрограмма ObReferenceObjectByHandle обеспечивает проверку доступа для дескриптора объекта и, если доступ может быть предоставлен, возвращает соответствующий указатель на тело объекта.

Синтаксис

NTSTATUS ObReferenceObjectByHandle(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [out]           PVOID                      *Object,
  [out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);

Параметры

[in] Handle

Указывает открытый дескриптор для объекта .

[in] DesiredAccess

Указывает запрошенные типы доступа к объекту . Интерпретация этого поля зависит от типа объекта . Не используйте универсальные права доступа. Дополнительные сведения см. в разделе ACCESS_MASK.

[in, optional] ObjectType

Указатель на тип объекта. ObjectType может иметь значение *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType или *TmTransactionObjectType.

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

[in] AccessMode

Указывает режим доступа, используемый для проверка доступа. Он должен иметь значение UserMode или KernelMode. Драйверы всегда должны указывать UserMode для дескрипторов, получаемых из адресного пространства пользователя.

[out] Object

Указатель на переменную, получающую указатель на тело объекта. В следующей таблице содержатся типы указателей.

Параметр ObjectType	Тип указателя объекта
*ExEventObjectType	PKEVENT
*ExSemaphoreObjectType	PKSEMAPHORE
*IoFileObjectType	PFILE_OBJECT
*PsProcessType	PEPROCESS или PKPROCESS
*PsThreadType	PETHREAD или PKTHREAD
*SeTokenObjectType	PACCESS_TOKEN
*TmEnlistmentObjectType	PKENLISTMENT
*TmResourceManagerObjectType	PKRESOURCEMANAGER
*TmTransactionManagerObjectType	PKTM
*TmTransactionObjectType	PKTRANSACTION

Структуры, на которые ссылаются типы указателей, являются непрозрачными, и драйверы не могут получить доступ к членам структуры. Поскольку структуры непрозрачны, PEPROCESS эквивалентен PKPROCESS, а PETHREAD — PKTHREAD.

[out, optional] HandleInformation

Драйверы устанавливают для этого параметра значение NULL.

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

ObReferenceObjectByHandle возвращает STATUS_SUCCESS, если вызов выполнен успешно. Возможные возвращаемые значения включают следующие коды ошибок:

Код возврата	Описание
STATUS_OBJECT_TYPE_MISMATCH	Параметр ObjectType указывает неправильный тип объекта для объекта, определяемого параметром Handle .
STATUS_ACCESS_DENIED	Вызывающему объекту не могут быть предоставлены запрошенные права доступа к объекту .
STATUS_INVALID_HANDLE	Параметр Handle не является допустимым дескриптором объекта.

Если AccessMode имеет значение UserMode, запрошенный доступ сравнивается с предоставленным доступом для объекта . Если accessMode имеет значение KernelMode, дескриптор должен поступать в адресное пространство ядра.

Начиная с Windows 7, если AccessMode имеет значение KernelMode и дескриптор получается из адресного пространства пользователя, средство проверки драйверов выдает проверку ошибок C4, подкод F6.

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

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 2000.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDIs(storport), IrqlObPassive(wdm), TargetRelationNeedsRef(wdm)

См. также раздел

ACCESS_MASK

ObDereferenceObject

ObReferenceObject

ObReferenceObjectByPointer