PCANCEL_MAPPED_TRANSFER callback function (wdm.h)

Article
02/25/2022

The CancelMappedTransfer routine cancels a system DMA transfer that is currently mapped to an adapter.

Syntax

PCANCEL_MAPPED_TRANSFER PcancelMappedTransfer;

NTSTATUS PcancelMappedTransfer(
  [in] PDMA_ADAPTER DmaAdapter,
  [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 DMA transfer to complete. The caller obtained this pointer from a previous call to the IoGetDmaAdapter routine, and the caller passed this pointer to the MapTransferEx call that set up the map registers for the DMA transfer.

[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 call that requested the adapter channel allocation.

Return value

CancelMappedTransfer returns STATUS_SUCCESS if the call is successful. Otherwise, it returns an appropriate error code.

Remarks

CancelMappedTransfer 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.

This routine marks the associated transfer context as canceled, which prevents any further transfers under this context. After a transfer is canceled, its completion routine is called, but the status for the transfer might be set to DmaCancelled.

Regardless of whether a system DMA transfer is canceled or completed, the FlushAdapterBuffers or FlushAdapterBuffersEx routine must always be called to flush any data that remains in the system DMA controller's internal cache at the end of a DMA transfer operation. After the transfer is canceled or completed, the FlushAdapterBuffersXxx call must occur before either the DMA channel is released or the MapTransferEx routine is called to set up the map registers for a new DMA transfer.

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