Функция ObReferenceObjectByHandle (wdm.h)
Подпрограмма 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 не является допустимым дескриптором объекта. |
Комментарии
Указатель на тело объекта извлекается из записи таблицы объектов и возвращается вызывающей объекту с помощью параметра Object .
Если 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) |