IoBuildSynchronousFsdRequest 関数 (wdm.h)

[アーティクル]
08/08/2023

IoBuildSynchronousFsdRequest ルーチンは、同期的に処理された I/O 要求の IRP を割り当てて設定します。

構文

__drv_aliasesMem PIRP IoBuildSynchronousFsdRequest(
  [in]           ULONG            MajorFunction,
  [in]           PDEVICE_OBJECT   DeviceObject,
  [in, out]      PVOID            Buffer,
  [in, optional] ULONG            Length,
  [in, optional] PLARGE_INTEGER   StartingOffset,
  [in]           PKEVENT          Event,
  [out]          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

ターゲットデバイスを表す、次の下位ドライバーのデバイスオブジェクトの DEVICE_OBJECT 構造体へのポインター。

[in, out] Buffer

データバッファーへのポインター。 MajorFunction がIRP_MJ_WRITEされている場合、バッファーには書き込まれるデータが含まれます。 MajorFunction がIRP_MJ_READ場合、バッファーはデータを受け取ります。 MajorFunction がIRP_MJ_FLUSH_BUFFERSまたはIRP_MJ_SHUTDOWN場合、このパラメーターは NULL である必要があります。

[in, optional] Length

Buffer が指すバッファーの長さ (バイト単位)。ディスクなどのデバイスの場合、この値はセクターサイズの整数倍である必要があります。 Windows 8以降、セクターサイズは 4,096 バイトまたは 512 バイトです。以前のバージョンの Windows では、セクターサイズは常に 512 バイトです。このパラメーターは、読み取り要求と書き込み要求では必須ですが、フラッシュ要求とシャットダウン要求ではゼロにする必要があります。

[in, optional] StartingOffset

読み取り要求と書き込み要求のディスク上のオフセットへのポインター。この値の単位と意味はドライバー固有です。このパラメーターは、読み取り要求と書き込み要求では必須ですが、フラッシュ要求とシャットダウン要求ではゼロにする必要があります。

[in] Event

呼び出し元によって割り当てられ、初期化されたイベントオブジェクトへのポインター。 I/O マネージャーは、下位レベルのドライバーが要求された操作を完了すると、イベントを Signaled 状態に設定します。 IoCallDriver を呼び出した後、ドライバーはイベントオブジェクトを待機できます。

[out] IoStatusBlock

下位レベルのドライバーによって IRP が完了したときに設定される I/O 状態ブロックを受け取る場所へのポインター。

戻り値

操作が成功した場合、 IoBuildSynchronousFsdRequest は初期化された IRP 構造体へのポインターを返します。次の下位ドライバーの I/O スタックの場所は、指定されたパラメーターから設定されます。それ以外の場合、ルーチンは NULL を返します。

注釈

ファイルシステムドライバー (FSD) またはその他の上位レベルのドライバーは 、IoBuildSynchronousFsdRequest を呼び出して、下位レベルのドライバーに同期的に送信する IRP を設定できます。

IoBuildSynchronousFsdRequest は、同期読み取り、書き込み、フラッシュ、またはシャットダウン操作を実行するために下位レベルのドライバーを要求する IRP を割り当てて設定します。 IRP には、操作を開始するための十分な情報が含まれています。

下位レベルのドライバーでは、このルーチンに指定されたパラメーターに制限が課される場合があります。たとえば、ディスクドライバーでは、 Length と StartingOffset に指定された値を、デバイスのセクターサイズの整数の倍数にする必要がある場合があります。

IoBuildSynchronousFsdRequest を呼び出して要求を作成した後、ドライバーは IoCallDriver を呼び出して、次の下位ドライバーに要求を送信する必要があります。 IoCallDriver がSTATUS_PENDINGを返す場合、ドライバーは、指定されたイベントで KeWaitForSingleObject を呼び出すことによって、IRP の完了を待機する必要があります。ほとんどのドライバーは、IRP の IoCompletion ルーチンを設定する必要はありません。

IoBuildSynchronousFsdRequest によって作成された IRP は、ドライバーによる IoCompleteRequest の呼び出しによって完了する必要があります。 IoBuildSynchronousFsdRequest を呼び出すドライバーは、IoCompleteRequest が呼び出された後に I/O マネージャーによってこれらの同期 IRP が解放されるため、IoFreeIrp を呼び出さないでください。

IoBuildSynchronousFsdRequest は、作成する IRP を、現在のスレッドに固有の IRP キューにキューに入れます。スレッドが終了すると、I/O マネージャーは IRP を取り消します。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	<= APC_LEVEL
DDI コンプライアンス規則	ForwardedAtBadIrqlFsdSync(wdm)、 HwStorPortProhibitedDDIs(storport)、 IoBuildSynchronousFsdRequestNoFree(wdm)、 IoBuildSynchronousFsdRequestWait(wdm)、 IoBuildSynchronousFsdRequestWaitTimeout(wdm)、 PowerIrpDDis(wdm)、 SignalEventInCompletion(wdm)