IoAttachDevice 関数 (wdm.h)

[アーティクル]
02/27/2024

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 に次の下位オブジェクトの値と 1 を設定します。

警告

AttachedDevice は 、ドライバーのデバイス拡張機能などのグローバルメモリの場所を指す必要があります。 IoAttachDevice によって ターゲットデバイスのファイルオブジェクトが開き、 AttachedDevice が更新され、アタッチが実行され、ファイルオブジェクトが閉じられます。したがって、ソースデバイスは、IoAttachDevice が返される前に、ファイルオブジェクトのIRP_MJ_CLEANUP要求とIRP_MJ_CLOSE要求を受け取ります。ドライバーは、ターゲットデバイスにこれらの要求を転送する必要があります。 AttachedDevice は、ドライバーの DispatchCleanup ルーチンと DispatchClose ルーチンからアクセスできるメモリの場所である必要があります。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport), IrqlIoPassive1(wdm)