IoBuildAsynchronousFsdRequest 関数 (wdm.h)
IoBuildAsynchronousFsdRequest ルーチンは、下位レベルのドライバーに送信される IRP を割り当てて設定します。
構文
__drv_aliasesMem PIRP IoBuildAsynchronousFsdRequest(
[in] ULONG MajorFunction,
[in] PDEVICE_OBJECT DeviceObject,
[in, out] PVOID Buffer,
[in, optional] ULONG Length,
[in, optional] PLARGE_INTEGER StartingOffset,
[in, optional] PIO_STATUS_BLOCK IoStatusBlock
);
パラメーター
[in] MajorFunction
IRP で設定する主要な関数コード。 このコードは、IRP_MJ_PNP、IRP_MJ_READ、IRP_MJ_WRITE、IRP_MJ_FLUSH_BUFFERS、または IRP_MJ_SHUTDOWNできます。
[in] DeviceObject
次の下位ドライバーのデバイス オブジェクトへのポインター。 このオブジェクトは、読み取り、書き込み、フラッシュ、またはシャットダウン操作のターゲット デバイスを表します。
[in, out] Buffer
データの読み取り先または書き込み元のバッファーへのポインター。 この引数の値は、フラッシュ要求とシャットダウン要求 NULL です。
[in, optional] Length
Bufferが指すバッファーの長さ (バイト単位)。 ディスクなどのデバイスの場合、この値はセクター サイズの整数倍数である必要があります。 Windows 8 以降では、セクター サイズは 4,096 バイトまたは 512 バイトです。 以前のバージョンの Windows では、セクター サイズは常に 512 バイトです。 このパラメーターは読み取り要求と書き込み要求に必要ですが、フラッシュ要求とシャットダウン要求ではゼロにする必要があります。
[in, optional] StartingOffset
入力/出力メディアの開始オフセットへのポインター。 フラッシュ要求とシャットダウン要求の場合、この引数の値は 0 です。
[in, optional] IoStatusBlock
to-beと呼ばれるドライバーが要求された操作に関する最終的な状態を返す I/O 状態ブロックのアドレスへのポインター。
戻り値
IoBuildAsynchronousFsdRequest は IRP へのポインターを返します。IRP を割り当てることができない場合は、NULL ポインターを返します。
備考
中間レベルまたは最上位レベルのドライバーは、IoBuildAsynchronousFsdRequest を呼び出して、下位レベルのドライバーに送信される要求の IRP を設定できます。 呼び出し元のドライバーは、IRP の IoCompletion ルーチンを提供する必要があります。そのため、IRP は IoFreeIrp 割り当てを解除できます。 IRP の割り当て解除の詳細については、「例」を参照してください。
ビルドされる IRP には、操作を開始して IRP を完了するのに十分な情報のみが含まれています。 非同期要求はコンテキストに依存しないため、他のコンテキスト情報は追跡されません。
下位レベルのドライバーは、このルーチンに指定されたパラメーターに制限を課す可能性があります。 たとえば、ディスク ドライバーでは、Length と startingOffset に指定された値 デバイスのセクター サイズの整数倍数であることが必要になる場合があります。
中間または最上位レベルのドライバーは、IoBuildDeviceIoControlRequest、IoAllocateIrp、または IoBuildSynchronousFsdRequest を呼び出して、下位レベルのドライバーに送信する要求を設定することもできます。 IoMakeAssociatedIrp 呼び出すことができるのは最上位ドライバーだけです。
IoBuildAsynchronousFsdRequest 呼び出し中に、I/O マネージャーは、呼び出し元のスレッド オブジェクトを指す IRP 構造体の Tail.Overlay.Thread メンバーを設定しますが、呼び出し元の代わりにスレッド オブジェクトへのカウントされた参照は取得しません。 呼び出し元がターゲット デバイスのドライバーに IRP を送信した後、このドライバーは、スレッド オブジェクトにアクセスする Tail.Overlay.Thread メンバーを使用する可能性があります。 たとえば、ストレージ ドライバーは、IoSetHardErrorOrVerifyDevice ルーチンを呼び出し、IRP へのポインターを入力パラメーターとして指定できます。 この呼び出し中、IoSetHardErrorOrVerifyDevice は、Tail.Overlay.Thread メンバーを使用してスレッド オブジェクトにアクセスします。 この方法でスレッド オブジェクトにアクセスする場合、IRP を割り当てるため IoBuildAsynchronousFsdRequest を呼び出したドライバーは、IRP の処理中にスレッド オブジェクトが有効なままであることを確認します。
スレッド オブジェクトを有効な状態に保つために、IoBuildAsynchronousFsdRequest を呼び出すドライバーは、IRP を送信する前にスレッド オブジェクトのカウントされた参照を取得できます。 たとえば、このドライバーは、ObReferenceObjectByPointerWithTag ルーチンを呼び出して、オブジェクト パラメーターとして、IRP 構造体の Tail.Overlay.Thread メンバーからのオブジェクト ポインターを指定できます。 後で、このドライバーの完了ルーチンは、obDereferenceObjectWithTag などのルーチン呼び出すことによって、オブジェクトを逆参照できます。
ドライバーは、あるスレッド IoBuildAsynchronousFsdRequest を呼び出し、この呼び出しによって割り当てられた IRP を別のスレッドで送信する場合があります。 IRP を送信する前に、このドライバーは、送信スレッドのスレッド オブジェクトを指す IRP の Tail.Overlay.Thread メンバーを設定する必要があります。 通常、ドライバーは、PsGetCurrentThread ルーチンを呼び出して、スレッド オブジェクト ポインターを取得します。
IRP を割り当てるために IoBuildAsynchronousFsdRequest を呼び出すドライバーは、IRP の Tail.Overlay.Thread メンバーが指すスレッド オブジェクトに対してカウントされた参照を取得する必要はありません。 ドライバーは、代わりに別の手法を使用して、IRP が処理されている間、このスレッド オブジェクトが有効なままであることを保証する場合があります。 たとえば、ドライバーがスレッドを作成した場合、スレッドは IRP が完了して終了するまで待機できます。
例
IoFreeIrp 呼び出す前に、IoBuildAsynchronousFsdRe quest によってビルドされた IRP のバッファーを解放する追加の手順が必要です (以下がすべて該当する場合)。
バッファーはシステム メモリ プールから割り当てられています。
ターゲット デバイスのデバイス オブジェクトでは、DO_DIRECT_IO フラグが DeviceObject->Flags フィールドに設定されます。
Irp->MdlAddress フィールドは NULL 以外です。
この IRP のバッファーを解放する前に、パラメーター値として Irp->MdlAddress を使用して、MmUnlockPages ルーチンを呼び出します。 この呼び出しにより、IoBuildAsynchronousFsdRequest MDL 内のプール ページに追加される追加の参照カウントがデクリメントされます。 それ以外の場合、IoFreeMdl を する後続の呼び出しでは、これらのプール ページの参照カウントが 1 ではなく 2 になるため、バグ チェックが行われます。 次のコード例は、MmUnlockPages、ioFreeMdl 、このケースの IoFreeIrp 呼び出し を示しています。
if (((DeviceObject->Flags & DO_DIRECT_IO) == DO_DIRECT_IO) &&
(Irp->MdlAddress != NULL))
{
MmUnlockPages(Irp->MdlAddress);
}
IoFreeMdl(Irp->MdlAddress);
IoFreeIrp(Irp);
必要条件
要件 | 価値 |
---|---|
ターゲット プラットフォーム の | 万国 |
ヘッダー | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
ライブラリ | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | IRQL <= APC_LEVEL |
DDI コンプライアンス規則 を する | ForwardedAtBadIrqlFsdAsync(wdm), HwStorPortProhibitedDDDIs (storport), IoBuildFsdComplete(wdm), IoBuildFsdForward(wdm), IoBuildFsdFree(wdm) |
関連項目
IoAllocateIrp の
IoBuildDeviceIoControlRequest の
IoBuildSynchronousFsdRequest の
IoCallDriver の
IoFreeIrp の
IoFreeMdl の
IoMakeAssociatedIrp の
IoSetHardErrorOrVerifyDevice の
ObDereferenceObjectWithTag の
ObReferenceObjectByPointerWithTag
PsGetCurrentThread の