PCANCEL_ADAPTER_CHANNEL回呼函式 (wdm.h)

發行項
03/01/2024

CancelAdapterChannel 例程會嘗試取消擱置的要求來配置 DMA 通道。

語法

PCANCEL_ADAPTER_CHANNEL PcancelAdapterChannel;

BOOLEAN PcancelAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PVOID DmaTransferContext
)
{...}

參數

[in] DmaAdapter

DMA_ADAPTER 結構的指標。此結構是等候授與擱置資源配置要求的配接器物件。呼叫端從先前呼叫IoGetDmaAdapter例程取得此指標，而呼叫端會將此指標傳遞給要求資源配置的AllocateAdapterChannelEx、GetScatterGatherListEx 或 BuildScatterGatherListEx 呼叫。

[in] DeviceObject

DEVICE_OBJECT 結構的指標。此結構是 PDO) (實體裝置物件，代表要求 DMA 通道之 DMA 作業的目標裝置。

[in] DmaTransferContext

DMA 傳輸內容的指標。此參數值必須是傳遞至 AllocateAdapterChannelEx、GetScatterGatherListEx 或 BuildScatterGatherListEx 呼叫的相同 DMA 傳輸內容，而該內容要求配接器通道配置。

傳回值

如果成功取消擱置的配置要求，CancelAdapterChannel 會傳回 TRUE。例如，如果無法取消要求 (，則例程會傳回 FALSE ，例如，因為已配置 DMA 通道，才能取消要求) 。

備註

CancelAdapterChannel 不是可直接依名稱呼叫的系統例程。這個例程只能由DMA_OPERATIONS結構中傳回之位址的指標呼叫。驅動程式會呼叫IoGetDmaAdapter，並將DeviceDescription參數的Version成員設定為 DEVICE_DESCRIPTION_VERSION3，以取得此例程的位址。如果 IoGetDmaAdapter 傳回 NULL，則您的平台上無法使用例程。

CancelAdapterChannel 會嘗試取消異步呼叫配置例程所發出的擱置配置要求，例如 AllocateAdapterChannelEx、GetScatterGatherListEx 或 BuildScatterGatherListEx。以異步方式呼叫時，配置例程可以在配置要求仍在擱置時傳回，並在呼叫 AdapterControl 或 AdapterListControl () 驅動程式提供執行例程之前傳回。如果 CancelAdapterChannel 成功取消擱置的配置要求，就不會配置資源，而且不會呼叫執行例程。

如果驅動程式呼叫 AllocateAdapterChannelEx 來要求驅動程式提供 AdapterControl 例程的資源，然後呼叫 CancelAdapterChannel 來取消要求， CancelAdapterChannel 可以傳回下列其中一個值：

TRUE 是表示如果配接器物件正在等候 CancelAdapterChannel 呼叫時所要求的配置。在此情況下， CancelAdapterChannel 會取消擱置的配置要求，而且不會呼叫驅動程式的 AdapterControl 例程。
FALSE，如果 AdapterControl 例程已經呼叫或即將呼叫。

同樣地，如果驅動程式呼叫 GetScatterGatherListEx 或 BuildScatterGatherListEx 來要求驅動程式提供的 AdapterListControl 例程的資源，然後呼叫 CancelAdapterChannel 來取消要求，CancelAdapterChannel 可以傳回下列其中一個值：

TRUE 是表示如果配接器物件正在等候 CancelAdapterChannel 呼叫時所要求的配置。在此情況下， CancelAdapterChannel 會取消擱置的配置要求，而且不會呼叫驅動程式的 AdapterListControl 例程。
FALSE，如果 AdapterListControl 例程已經呼叫或即將呼叫。

CancelAdapterChannel 可以先佔式取消未來使用指定 DMA 傳輸內容的通道配置要求。例如，如果呼叫端提供相同的 DMA 傳輸內容給 CancelAdapterChannel 和 AllocateAdapterChannelEx，而且 CancelAdapterChannel 呼叫成功，而且會在 AllocateAdapterChannelEx 呼叫之前發生，則 AllocateAdapterChannelEx 呼叫所要求的配置會自動取消。

規格需求

需求	值
最低支援的用戶端	從 Windows 8 開始提供。
目標平台	桌面
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
IRQL	<= DISPATCH_LEVEL