Функция IoGetDeviceObjectPointer (wdm.h)
Подпрограмма 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 из подпрограммы выгрузки, передав указатель объекта файла, возвращенный IoGetDeviceObjectPointer. Сбой разыменования объекта устройства в подпрограмме выгрузки драйвера предотвращает выгрузку следующего ниже драйвера. Однако драйверы, закрывающие объект файла перед процессом выгрузки, должны извлечь дополнительную ссылку на объект устройства перед отменой ссылки на объект файла. В противном случае удаление объекта файла может привести к преждевременному удалению объекта устройства.
Чтобы получить указатель на драйвер верхнего уровня в стеке драйверов файловой системы, драйвер должен убедиться, что файловая система подключена; Если это не так, эта подпрограмма проходит по стеку устройств хранилища. Чтобы убедиться, что файловая система подключена на устройстве хранения, драйвер должен указать соответствующую маску доступа, например FILE_READ_DATA или FILE_WRITE_ATTRIBUTES, в параметре DesiredAccess. Указание FILE_READ_ATTRIBUTES не приводит к подключению файловой системы.
После успешного вызова этой процедуры драйвер более высокого уровня должен задать поле StackSize в объекте устройства следующего нижнего уровня драйвера плюс один.
Вызывающие IoGetDeviceObjectPointer должны работать в IRQL = PASSIVE_LEVEL.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Доступно начиная с Windows 2000. |
| целевая платформа | Всеобщий |
| заголовка | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| библиотеки | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| правил соответствия DDI | HwStorPortProhibitedDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm) |