WdfDmaTransactionInitializeUsingRequest 函数 (wdfdmatransaction.h)

项目
02/27/2024

[仅适用于 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

一个WDF_DMA_DIRECTION类型的值，指定 DMA 传输的方向。

返回值

如果操作成功，WdfDmaTransactionInitializeUsingRequest 将返回STATUS_SUCCESS。否则，该方法可能会返回 WdfDmaTransactionInitialize 的 Return values 部分所述的值之一。

此方法还可能返回其他 NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

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
标头	wdfdmatransaction.h (包括 Wdf.h)
Library	Wdf01000.sys (请参阅框架库 Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	DeferredRequestCompleted (kmdf) 、 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf) ， RequestCompleted (kmdf) ， RequestCompletedLocal (kmdf)