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

Статья
03/08/2023

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

Синтаксис

NTSTATUS IoAttachDevice(
  [in]  PDEVICE_OBJECT  SourceDevice,
  [in]  PUNICODE_STRING TargetDevice,
  [out] PDEVICE_OBJECT  *AttachedDevice
);

Параметры

[in] SourceDevice

Указатель на созданный вызывающим объектом устройства.

[in] TargetDevice

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

[out] AttachedDevice

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

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

IoAttachDevice может возвращать одно из следующих значений NTSTATUS:

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

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

Обратите внимание, что для драйверов файловой системы и драйверов в стеке хранилища IoAttachDevice открывает целевое устройство с FILE_READ_ATTRIBUTES, а затем вызывает IoGetRelatedDeviceObject. Это не приводит к тому, что файловая система будет подключена. Таким образом, при успешном вызове IoAttachDevice возвращается объект устройства драйвера хранилища, а не драйвер файловой системы.

Эта подпрограмма задает для параметра AlignmentRequirement в SourceDevice значение в объекте устройства следующего уровня ниже, а для stackSize — значение в следующем и нижнем объекте плюс единица.

Предупреждение

AttachedDevice должен указывать на глобальное расположение памяти, например расширение устройства драйвера. IoAttachDevice открывает объект файла для целевого устройства, обновляет AttachedDevice, выполняет присоединение, а затем закрывает объект файла. Таким образом, исходное устройство получает IRP_MJ_CLEANUP и IRP_MJ_CLOSE запросы для объекта файла до возврата IoAttachDevice . Драйвер должен пересылать эти запросы на целевое устройство, а AttachedDevice должен быть расположением памяти, доступным для процедур DispatchCleanup и DispatchClose драйвера.

Требования

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