PALLOCATE_ADAPTER_CHANNEL_EX回呼函式 （wdm.h）
AllocateAdapterChannelEx 例程會設定執行 DMA 傳輸所需的資源，然後呼叫驅動程式提供的 AdapterControl 例程來起始 DMA 傳輸。
語法
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 結構的指標。 此結構是實體裝置物件 （PDO），代表所要求 DMA 作業的目標裝置。
[in] DmaTransferContext
初始化之 DMA 傳輸內容的指標。 此內容是由先前呼叫 initializeDmaTransferContext 例程 初始化。 此內容在所有配接器配置要求中都必須是唯一的。 若要取消擱置的配置要求，呼叫端必須將要求的 DMA 傳輸內容提供給 CancelAdapterChannel 例程。
[in] NumberOfMapRegisters
要用於 DMA 傳輸的地圖緩存器數目。 呼叫驅動程式應該將此值設定為滿足目前傳輸要求所需的地圖緩存器數目，以及可用的地圖緩存器數目。 驅動程式先前稱為 GetDmaTransferInfo 例程，以取得傳輸所需的地圖緩存器數目，並呼叫 IoGetDmaAdapter 例程，以取得可用的地圖緩存器數目。
[in] Flags
配接器通道配置旗標。 支援下列旗標。
| 旗 | 意義 |
|---|---|
|
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所配置的資源，稍後呼叫 free FreeAdapterObject 例程來釋放這些資源。 如需詳細資訊，請參閱一節。
[in, optional] ExecutionContext
驅動程式決定的配接器控件內容。 此內容會傳遞至 AdapterControl 例程做為 Context 參數。
[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。 可能的錯誤傳回值包括下列狀態代碼。
| 傳回碼 | 描述 |
|---|---|
|
例程失敗，因為呼叫端傳遞的參數值無效。 |
|
例程無法配置 DMA 傳輸所需的資源。 |
言論
AllocateAdapterChannelEx 不是可以直接依名稱呼叫的系統例程。這個例程只能由 DMA_OPERATIONS 結構中傳回之位址的指標呼叫。驅動程式會呼叫 ioGetDmaAdapter ，並將 DeviceDescription 參數的 Version 成員 DEVICE_DESCRIPTION_VERSION3呼叫 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 例程，則驅動程式可以在傳回 AllocateAdapterChannel Ex 之後，使用已配置的資源。 在此情況下，驅動程式在使用已配置的資源完成之後，必須呼叫 FreeAdapterObject。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | 從 Windows 8 開始提供。 |
| 目標平臺 | 桌面 |
| 標頭 | wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h） |
| IRQL | DISPATCH_LEVEL |