WdfDmaTransactionInitializeUsingRequest 関数 (wdfdmatransaction.h)

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

[KMDF にのみ適用]

WdfDmaTransactionInitializeUsingRequest メソッドは、指定した I/O 要求のパラメーターを使用して、指定された DMA トランザクションを初期化します。

構文

NTSTATUS WdfDmaTransactionInitializeUsingRequest(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDFREQUEST          Request,
  [in] PFN_WDF_PROGRAM_DMA EvtProgramDmaFunction,
  [in] WDF_DMA_DIRECTION   DmaDirection
);

パラメーター

[in] DmaTransaction

ドライバーが WdfDmaTransactionCreate の以前の呼び出しから取得した DMA トランザクションオブジェクトへのハンドル。

[in] Request

フレームワーク要求オブジェクトへのハンドル。

[in] EvtProgramDmaFunction

ドライバーの EvtProgramDma イベントコールバック関数へのポインター。

[in] DmaDirection

DMA 転送の方向を指定する WDF_DMA_DIRECTION型指定された値。

戻り値

操作が成功した場合、WdfDmaTransactionInitializeUsingRequest はSTATUS_SUCCESSを返します。それ以外の場合、メソッドは WdfDmaTransactionInitialize の戻り値セクションで説明されている値のいずれかを返す可能性があります。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクトハンドルを提供すると、バグチェックが発生します。

注釈

WdfDmaTransactionInitializeUsingRequest メソッドは、トランザクションの散布/収集リストの設定などの初期化操作を実行することで、DMA 操作を実行用に準備します。ドライバーが WdfDmaTransactionInitializeUsingRequest を呼び出した後、ドライバーは WdfDmaTransactionExecute を呼び出す必要があります。

ドライバーは WdfRequestGetParameters を呼び出して、要求の種類を取得できます。 ドライバーが DmaDirection パラメーターに指定する値は、次のように要求の種類に適している必要があります。

DmaDirection 値は、次の場合に WdfDmaDirectionReadFromDevice である必要があります。
- 要求の種類は WdfRequestTypeRead です
- 要求の種類は WdfRequestTypeDeviceControl または WdfRequestTypeDeviceControlInternal であり、I/O コントロールコードは転送の種類を指定METHOD_OUT_DIRECT
次の場合、DmaDirection 値は WdfDmaDirectionWriteToDevice である必要があります。
- 要求の種類は WdfRequestTypeWrite です
- 要求の種類は WdfRequestTypeDeviceControl または WdfRequestTypeDeviceControlInternal であり、I/O コントロールコードは転送の種類を指定METHOD_IN_DIRECT

I/O 制御コードの転送タイプの詳細については、「 I/O 制御コードの定義」を参照してください。

フレームワークベースのドライバーは、通常、I/O キューイベントコールバック関数内から WdfDmaTransactionInitializeUsingRequest を呼び出します。

フレームワーク要求オブジェクトに含まれる情報に基づいて DMA トランザクションを作成する場合、ドライバーは WdfDmaTransactionInitializeUsingRequest を呼び出す必要があります。要求オブジェクトに基づいていない DMA トランザクションを作成する場合は、 WdfDmaTransactionInitialize を使用します。

要求オブジェクトが記述するバッファーが、ドライバーが WdfDmaEnablerCreate または WdfDmaTransactionSetMaximumLength を呼び出したときに指定した転送の最大長よりも大きい場合、フレームワークはトランザクションを複数の転送に分割します。

DMA トランザクションの詳細については、「DMA トランザクションの作成と初期化」を参照してください。

例

WdfDmaTransactionInitializeUsingRequest を使用するコード例については、「WdfDmaTransactionExecute」を参照してください。

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
Header	wdfdmatransaction.h (Wdf.h を含む)
Library	Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DeferredRequestCompleted(kmdf)、 DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 RequestCompleted(kmdf)、 RequestCompletedLocal(kmdf)