PCANCEL_ADAPTER_CHANNEL callback function (wdm.h)

Article
02/25/2022

The CancelAdapterChannel routine tries to cancel a pending request to allocate a DMA channel.

Syntax

PCANCEL_ADAPTER_CHANNEL PcancelAdapterChannel;

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

Parameters

[in] DmaAdapter

A pointer to a DMA_ADAPTER structure. This structure is the adapter object that is waiting for the pending resource allocation request to be granted. The caller obtained this pointer from a previous call to the IoGetDmaAdapter routine, and the caller passed this pointer to the AllocateAdapterChannelEx, GetScatterGatherListEx, or BuildScatterGatherListEx call that requested the resource allocation.

[in] DeviceObject

A pointer to a DEVICE_OBJECT structure. This structure is the physical device object (PDO) that represents the target device for the DMA operation for which the DMA channel was requested.

[in] DmaTransferContext

A pointer to a DMA transfer context. This parameter value must be the same DMA transfer context that was passed to the AllocateAdapterChannelEx, GetScatterGatherListEx, or BuildScatterGatherListEx call that requested the adapter channel allocation.

Return value

CancelAdapterChannel returns TRUE if the pending allocation request is successfully canceled. The routine returns FALSE if the request could not be canceled (for example, because the DMA channel was allocated before the request could be canceled).

Remarks

CancelAdapterChannel is not a system routine that can be called directly by name. This routine can be called only by pointer from the address returned in a DMA_OPERATIONS structure. Drivers obtain the address of this routine by calling IoGetDmaAdapter with the Version member of the DeviceDescription parameter set to DEVICE_DESCRIPTION_VERSION3. If IoGetDmaAdapter returns NULL, the routine is not available on your platform.

CancelAdapterChannel tries to cancel a pending allocation request that was made by an asynchronous call to an allocation routine such as AllocateAdapterChannelEx, GetScatterGatherListEx, or BuildScatterGatherListEx. When called asynchronously, the allocation routine can return while the allocation request is still pending and before the driver-supplied execution routine (AdapterControl or AdapterListControl) is called. If CancelAdapterChannel successfully cancels the pending allocation request, the resources are not allocated and the execution routine is not called.

If a driver calls AllocateAdapterChannelEx to request resources for a driver-supplied AdapterControl routine, and then calls CancelAdapterChannel to cancel the request, CancelAdapterChannel can return one of the following values:

TRUE, if the adapter object is waiting for the requested allocation when the CancelAdapterChannel call occurs. In this case, CancelAdapterChannel cancels the pending allocation request, and the driver's AdapterControl routine is not called.
FALSE, if the AdapterControl routine was already called or is about to be called.

Similarly, if a driver calls GetScatterGatherListEx or BuildScatterGatherListEx to request resources for a driver-supplied AdapterListControl routine, and then calls CancelAdapterChannel to cancel the request, CancelAdapterChannel can return one of the following values:

TRUE, if the adapter object is waiting for the requested allocation when the CancelAdapterChannel call occurs. In this case, CancelAdapterChannel cancels the pending allocation request, and the driver's AdapterListControl routine is not called.
FALSE, if the AdapterListControl routine was already called or is about to be called.

CancelAdapterChannel can preemptively cancel future channel allocation requests that use the specified DMA transfer context. For example, if the caller supplies the same DMA transfer context to CancelAdapterChannel and AllocateAdapterChannelEx, and the CancelAdapterChannel call is successful and occurs before the AllocateAdapterChannelEx call, the allocation requested by the AllocateAdapterChannelEx call is automatically canceled.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.
Target Platform	Desktop
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL