[仅适用于 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 启用器对象后，驱动程序还可以从其 EvtDriverDeviceAdd 回调函数调用 WdfDmaTransactionAllocateResources。
使用散点/收集 DMA 启用器调用时，WdfDmaTransactionAllocateResources 会导致验证程序 bug 检查。
驱动程序必须在调用 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） |