IoAttachDevice 函数 (wdm.h)

项目
03/08/2023

IoAttachDevice 例程将调用方的设备对象附加到命名的目标设备对象，以便首先将绑定到目标设备的 I/O 请求路由到调用方。

语法

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

参数

[in] SourceDevice

指向调用方创建的设备对象的指针。

[in] TargetDevice

指向缓冲区的指针，该缓冲区包含指定 SourceDevice 要附加到的设备对象的名称。

[out] AttachedDevice

指向指针的调用方分配存储的指针。返回时，如果附件成功，则包含指向目标设备对象的指针。

返回值

IoAttachDevice 可以返回以下 NTSTATUS 值之一：

注解

IoAttachDevice 在驱动程序之间建立分层，以便可以将相同的 IRP 发送到链中的每个驱动程序。

此例程由中间驱动程序在初始化期间使用。它允许此类驱动程序将其自己的设备对象附加到另一个设备，这样，对原始设备发出的任何请求都首先提供给中间驱动程序。

调用方只能在现有分层驱动程序链的顶部分层。 IoAttachDevice 搜索 在 TargetDevice 上分层的最高设备对象，并附加到该对象 (，该对象可以是 TargetDevice) 。因此，如果必须更高级别的驱动程序已在目标设备上分层，则不得调用此例程。

请注意，对于存储堆栈中的文件系统驱动程序和驱动程序， IoAttachDevice 使用 FILE_READ_ATTRIBUTES打开目标设备，然后调用 IoGetRelatedDeviceObject。这不会导致装载文件系统。因此，成功调用 IoAttachDevice 会返回存储驱动程序的设备对象，而不是文件系统驱动程序的设备对象。

此例程将 SourceDevice 中的 AlignmentRequirement 设置为下一个较低级别的设备对象中的值，并将 StackSize 设置为下一个较低对象中的值。

警告

AttachedDevice 必须指向全局内存位置，例如驱动程序的设备扩展。 IoAttachDevice 打开目标设备的文件对象，更新 AttachedDevice，执行附加，然后关闭文件对象。因此，在 IoAttachDevice 返回之前，源设备接收对文件对象的IRP_MJ_CLEANUP和IRP_MJ_CLOSE请求。驱动程序必须将这些请求转发到目标设备， 而 AttachedDevice 必须是驱动程序的 DispatchCleanup 和 DispatchClose 例程可访问的内存位置。

要求

要求	值
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 符合性规则	HwStorPortProhibitedDDI (storport) ， IrqlIoPassive1 (wdm)