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

指定 DMA 傳輸方向的WDF_DMA_DIRECTION型別值。

傳回值

WdfDmaTransactionInitializeUsingRequest 會在作業成功時傳回STATUS_SUCCESS。否則，方法可能會傳回 WdfDmaTransactionInitialize 的 Return values 區段中所述的其中一個值。

這個方法也可能傳回其他 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。

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.0
標頭	wdfdmatransaction.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DeferredRequestCompleted (kmdf) ， DriverCreate (kmdf ) ， KmdfIrql (kmdf) ， KmdfIrql2 () ， KmdfIrqlExplicit (kmdf) ， RequestCompleted (kmdf) 、RequestCompletedLocal (kmdf)