PCANCEL_ADAPTER_CHANNEL回调函数 (wdm.h)

项目
08/08/2023

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）发出的挂起的分配请求。异步调用时，分配例程可以在分配请求仍处于挂起状态时返回，并在调用 driver 提供的执行例程 (AdapterControl 或 AdapterListControl) 之前返回。如果 CancelAdapterChannel 成功取消挂起的分配请求，则不会分配资源，也不会调用执行例程。

如果驱动程序调用 AllocateAdapterChannelEx 为驱动程序提供的 AdapterControl 例程请求资源，然后调用 CancelAdapterChannel 以取消请求， 则 CancelAdapterChannel 可以返回以下值之一：

如果适配器对象在 CancelAdapterChannel 调用发生时等待请求的分配，则为 TRUE。在这种情况下， CancelAdapterChannel 取消挂起的分配请求，并且不调用驱动程序的 AdapterControl 例程。
如果AdapterControl 例程已调用或即将调用，则为 FALSE。

同样，如果驱动程序调用 GetScatterGatherListEx 或 BuildScatterGatherListEx 来请求驱动程序提供的 AdapterListControl 例程的资源，然后调用 CancelAdapterChannel 来取消请求， CancelAdapterChannel 可以返回以下值之一：

如果适配器对象在 CancelAdapterChannel 调用发生时等待请求的分配，则为 TRUE。在这种情况下， CancelAdapterChannel 取消挂起的分配请求，并且不调用驱动程序的 AdapterListControl 例程。
如果AdapterListControl 例程已调用或即将调用，则为 FALSE。

CancelAdapterChannel 可以提前取消将来使用指定 DMA 传输上下文的通道分配请求。例如，如果调用方向 CancelAdapterChannel 和 AllocateAdapterChannelEx 提供相同的 DMA 传输上下文，并且 CancelAdapterChannel 调用成功且发生在 AllocateAdapterChannelEx 调用之前，则 AllocateAdapterChannelEx 调用请求的分配将自动取消。

要求

要求	值
最低受支持的客户端	从Windows 8开始可用。
目标平台	桌面
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
IRQL	<= DISPATCH_LEVEL