PCANCEL_ADAPTER_CHANNEL callback function (wdm.h)
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.
- 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.
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 |