[僅適用於 KMDF]
WdfDmaTransactionAllocateResources 方法會保留單一封包或系統模式的 DMA 啟用器，以便搭配指定的交易物件使用。 驅動程式可以在保留保留資源時多次初始化和起始交易。
語法
NTSTATUS WdfDmaTransactionAllocateResources(
[in] WDFDMATRANSACTION DmaTransaction,
[in] WDF_DMA_DIRECTION DmaDirection,
[in] ULONG RequiredMapRegisters,
[in] PFN_WDF_RESERVE_DMA EvtReserveDmaFunction,
[in] PVOID EvtReserveDmaContext
);
參數
[in] DmaTransaction
應該保留 DMA 資源的 DMA 交易物件的句柄。
[in] DmaDirection
WDF_DMA_DIRECTION型別值，指定保留資源的 DMA 傳輸方向。 如果驅動程式未指定雙工配置檔，架構會忽略此值。
[in] RequiredMapRegisters
驅動程式想要保留的地圖緩存器數目。 如果為零，架構會從初始化的交易衍生必要的對應緩存器數目。
[in] EvtReserveDmaFunction
驅動程式 EvtReserveDma 事件回呼函式的指標。
[in] EvtReserveDmaContext
緩衝區的指標，其中包含要提供給驅動程式 EvtReserveDma 事件回呼函式的內容。
返回值
如果作業成功，WdfDmaTransactionAllocateResources 會傳回STATUS_SUCCESS。 否則，這個方法會傳回下列其中一個值。
| 回傳碼 | 說明 |
|---|---|
|
DmaDirection 參數包含無效的值。 |
|
對應緩存器要求數目超過指派給啟用者的數目，或先前稱為 WdfDmaTransactionSetImmediateExecution 的驅動程式數目，且要求所需的資源無法使用。 |
|
DMA 第 3 版或更新版本未啟用，或針對散佈圖收集 DMA 啟用程式呼叫這個方法的驅動程式。 |
備註
WdfDmaTransactionAllocateResources 將對應緩存器的要求傳送至系統 DMA 引擎。 當要求完成時，架構會呼叫驅動程式的 EvtReserveDma 事件回呼函式。 如需保留資源的詳細資訊，請參閱 保留 DMA 資源。
架構型驅動程式通常會從 I/O 要求處理程式內呼叫 WdfDmaTransactionAllocateResources。 驅動程式也可以在建立 DMA enabler 對象之後，從其 EvtDriverDeviceAdd 回呼函式呼叫 WdfDmaTransactionAllocateResources。
使用散佈圖/收集 DMA 啟用程式呼叫時，WdfDmaTransactionAllocateResources 會導致驗證程序錯誤檢查。
驅動程式必須在呼叫 WdfDmaTransactionAllocateResources之前，先建立 DmaTransaction 所指定的交易。 呼叫 WdfDmaTransactionAllocateResources之後，驅動程式會初始化並起始交易。 驅動程式可以多次重新初始化和重新初始化相同的交易物件，避免在交易之間發生的延遲，因為對應緩存器已釋放回 HAL，然後重新配置。
在下列情況下，驅動程式可以呼叫 WdfDmaTransactionAllocateResources：
- 驅動程式會在其 EvtDevicePrepareHardware 回呼函式中接收一組 DMA 通道。 在 EvtDevicePrepareHardware中，驅動程式會初始化 DMA 交易，並呼叫 WdfDmaTransactionAllocateResources 來保留啟用器以便與此交易獨佔使用。 或者，驅動程式可以從 要求處理程式 呼叫 WdfDmaTransactionAllocateResources，然後多次起始交易。
- 驅動程式必須在啟用程式上執行一系列交易。 驅動程式會保留啟用程式、使用相同交易物件初始化和起始多個交易，然後釋放啟用程式。
呼叫 WdfDmaTransactionAllocateResources時，驅動程式不應該要求比建立啟用程式時要求的對應緩存器多。
若要以非封鎖方式呼叫 WdfDmaTransactionAllocateResources，驅動程式應該先呼叫 WdfDmaTransactionSetImmediateExecution。
WdfDmaTransactionAllocateResources 需要 DMA 第 3 版。 若要選取 DMA 第 3 版，請將 WdmDmaVersionOverrideWDF_DMA_ENABLER_CONFIG 成員設為 3。
需求
| 要求 | 價值 |
|---|---|
| 目標平臺 | 普遍 |
| 最低 KMDF 版本 | 1.11 |
| 標題 | wdfdmatransaction.h （包括 Wdf.h） |
| 程式庫 | Wdf01000.sys （請參閱架構連結庫版本控制。） |
| IRQL | <=DISPATCH_LEVEL |
| DDI 合規性規則 | DriverCreate（kmdf） |