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

Статья
02/27/2024

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

Синтаксис

NTSTATUS IoGetDeviceObjectPointer(
  [in]  PUNICODE_STRING ObjectName,
  [in]  ACCESS_MASK     DesiredAccess,
  [out] PFILE_OBJECT    *FileObject,
  [out] PDEVICE_OBJECT  *DeviceObject
);

Параметры

[in] ObjectName

Указатель на буфер, содержащий строку Юникода, которая является именем объекта устройства.

[in] DesiredAccess

Задает значение ACCESS_MASK , представляющее требуемый доступ. Обычно DesiredAccess FILE_READ_DATA. Редко указываются права доступа FILE_WRITE_DATA или FILE_ALL_ACCESS.

[out] FileObject

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

[out] DeviceObject

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

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

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

STATUS_OBJECT_TYPE_MISMATCH

STATUS_INVALID_PARAMETER

STATUS_PRIVILEGE_NOT_HELD

STATUS_INSUFFICIENT_RESOURCES

STATUS_OBJECT_NAME_INVALID

IoGetDeviceObjectPointer устанавливает "соединение" между вызывающим объектом и драйвером следующего нижнего уровня. Успешный вызывающий объект может использовать возвращенный указатель объекта устройства для инициализации собственных объектов устройства. Его также можно использовать в качестве аргумента для IoAttachDeviceToDeviceStack, IoCallDriver и любой процедуры, которая создает IRP для более низких драйверов. Возвращаемый указатель является обязательным аргументом для IoCallDriver.

Эта подпрограмма также возвращает указатель на соответствующий объект файла. При выгрузке драйвер может разыменовывание файлового объекта как средства косвенного разыменования объекта устройства. Для этого драйвер вызывает ObDereferenceObject из своей подпрограммы Unload, передав указатель на объект файла, возвращенный IoGetDeviceObjectPointer. Невозможность разыменования объекта устройства в подпрограмме выгрузки драйвера предотвращает выгрузку следующего ниже драйвера. Однако драйверы, закрывающие файловый объект перед процессом выгрузки, должны извлечь дополнительную ссылку на объект устройства перед разыменовыванием файлового объекта. В противном случае разыменовка файлового объекта может привести к преждевременному удалению объекта устройства.

Чтобы получить указатель на драйвер самого высокого уровня в стеке драйверов файловой системы, драйвер должен убедиться, что файловая система подключена; Если это не так, эта подпрограмма проходит через стек запоминающее устройство. Чтобы обеспечить подключение файловой системы на запоминающее устройство, драйвер должен указать соответствующую маску доступа, например FILE_READ_DATA или FILE_WRITE_ATTRIBUTES, в параметре DesiredAccess . Указание FILE_READ_ATTRIBUTES не приводит к подключению файловой системы.

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

Вызывающие объекты IoGetDeviceObjectPointer должны выполняться в IRQL = PASSIVE_LEVEL.

Требования

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