IoBuildAsynchronousFsdRequest 関数 (wdm.h)

[アーティクル]
02/07/2025

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)

次の方法で共有

IoBuildAsynchronousFsdRequest 関数 (wdm.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース