AllocateAdapterChannelEx 例程分配执行 DMA 传输所需的资源，然后调用驱动程序提供的 AdapterControl 例程来启动 DMA 传输。
Syntax
PALLOCATE_ADAPTER_CHANNEL_EX PallocateAdapterChannelEx;
NTSTATUS PallocateAdapterChannelEx(
[in] PDMA_ADAPTER DmaAdapter,
[in] PDEVICE_OBJECT DeviceObject,
[in] PVOID DmaTransferContext,
[in] ULONG NumberOfMapRegisters,
[in] ULONG Flags,
[in, optional] PDRIVER_CONTROL ExecutionRoutine,
[in, optional] PVOID ExecutionContext,
[out, optional] PVOID *MapRegisterBase
)
{...}
参数
[in] DmaAdapter
指向 DMA_ADAPTER 结构的指针。 此结构是表示驱动程序总线主 DMA 设备或系统 DMA 通道的适配器对象。 调用方从之前对 IoGetDmaAdapter 例程的调用中获取了此指针。
[in] DeviceObject
指向 DEVICE_OBJECT 结构的指针。 此结构是表示所请求 DMA作的目标设备的物理设备对象 （PDO）。
[in] DmaTransferContext
指向初始化的 DMA 传输上下文的指针。 此上下文是由对 InitializeDmaTransferContext 例程的上一次调用初始化的。 此上下文在所有适配器分配请求中必须是唯一的。 若要取消挂起的分配请求，调用方必须向 CancelAdapterChannel 例程提供请求的 DMA 传输上下文。
[in] NumberOfMapRegisters
在 DMA 传输中使用的映射寄存器数。 调用驱动程序应将此值设置为满足当前传输请求所需的映射寄存器数越少，以及可用的映射寄存器数。 驱动程序以前调用 GetDmaTransferInfo 例程以获取传输所需的映射寄存器数，并调用 IoGetDmaAdapter 例程以获取可用映射寄存器数。
[in] Flags
适配器通道分配标志。 支持以下标志。
| Flag | Meaning |
|---|---|
|
AllocateAdapterChannelEx 例程是同步调用的。 如果设置了此标志，并且所需的 DMA 资源无法立即可用，则调用将失败并返回STATUS_INSUFFICIENT_RESOURCES。 |
如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志， 则 ExecutionRoutine 参数是可选的，可以是 NULL。 有关此标志的详细信息，请参阅“备注”部分。
[in, optional] ExecutionRoutine
指向驱动程序提供的 AdapterControl 例程的指针，用于启动驱动程序的 DMA 传输。 I/O 管理器在为适配器对象分配所需的资源后调用 AdapterControl 例程。 AdapterControl 例程返回后，I/O 管理器会自动释放适配器对象。 I/O 管理器可能会额外释放为此对象分配的资源，具体取决于此例程返回的值。
如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志， 则 ExecutionRoutine 是可选的，可以为 NULL。 在这种情况下，调用方可以使用 AllocateAdapterChannelEx 分配的资源，稍后通过调用 FreeAdapterObject 例程释放这些资源。 有关详细信息，请参阅“备注”部分。
[in, optional] ExecutionContext
驱动程序确定的适配器控制上下文。 此上下文作为上下文参数传递给 AdapterControl 例程。
[out, optional] MapRegisterBase
指向例程将句柄写入到分配的映射寄存器的变量的指针。 调用方可以将此句柄作为参数提供给 FlushAdapterBuffersEx、 FlushAdapterBuffers、 FreeMapRegisters 或 MapTransferEx 例程。
如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志， 则 MapRegisterBase 必须是有效的非 NULL 指针。 如果 ExecutionRoutine 参数为非 NULL， 则 MapRegisterBase 必须为 NULL。 如果 MapRegisterBase 为非 NULL 且 未设置DMA_SYNCHRONOUS_CALLBACK 标志，或者 MapRegisterBase 和 ExecutionRoutine 均为 NULL，则调用将失败。
返回值
如果调用成功，AllocateAdapterChannelEx 将返回STATUS_SUCCESS。 可能的错误返回值包括以下状态代码。
| 返回代码 | Description |
|---|---|
|
由于调用方传递的参数值无效，例程失败。 |
|
例程未能分配 DMA 传输所需的资源。 |
注解
AllocateAdapterChannelEx 不是可以直接按名称调用的系统例程。只能通过从DMA_OPERATIONS结构中返回的地址的指针调用此例程 。 驱动程序通过调用设置为 DEVICE_DESCRIPTION_VERSION3 DeviceDescription 参数的版本成员调用 IoGetDmaAdapter 来获取此例程的地址。 如果 IoGetDmaAdapter 返回 NULL，则例程在平台上不可用。
AllocateAdapterChannelEx 分配执行 DMA作所需的资源。 这些资源包括 DMA 通道和映射寄存器。 分配所有必需的资源供 DMA 适配器使用后， AllocateAdapterChannelEx 调用调用方提供的 AdapterControl 例程来启动 DMA作。
默认情况下， AllocateAdapterChannelEx 以异步方式返回，而无需等待请求的资源分配完成。 此返回后，调用方可以通过调用 CancelAdapterChannel 例程来取消挂起的分配请求（ 如有必要）。
如果调用驱动程序设置 DMA_SYNCHRONOUS_CALLBACK 标志， 则 AllocateAdapterChannelEx 例程的行为如下所示：
- 如果请求的 DMA 资源无法立即可用， 则 AllocateAdapterChannelEx 不会等待资源，也不会调用 AdapterControl 例程。 而是 AllocateAdapterChannelEx 失败并返回STATUS_INSUFFICIENT_RESOURCES。
- 如果设置了 DMA_SYNCHRONOUS_CALLBACK 标志，则不需要驱动程序提供 AdapterControl 例程。
- 如果驱动程序提供 AdapterControl 例程， DMA_SYNCHRONOUS_CALLBACK 标志指示在 AllocateAdapterChannelEx 返回之前，将在调用线程的上下文中调用此例程。
- 如果驱动程序不提供 AdapterControl 例程，驱动程序可以在 AllocateAdapterChannelEx 返回后使用分配的资源。 在这种情况下，驱动程序在使用分配的资源完成后必须调用 FreeAdapterObject 。
要求
| Requirement | 价值 |
|---|---|
| 最低支持的客户端 | 从 Windows 8 开始可用。 |
| 目标平台 | 桌面 |
| Header | wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h） |
| IRQL | DISPATCH_LEVEL |