функция обратного вызова PCANCEL_ADAPTER_CHANNEL (wdm.h)

Статья
02/27/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. Это значение параметра должно быть тем же контекстом передачи DMA, который был передан в вызов AllocateAdapterChannelEx, GetScatterGatherListEx или BuildScatterGatherListEx , который запросил выделение канала адаптера.

Возвращаемое значение

CancelAdapterChannel возвращает значение TRUE , если ожидающий запроса на выделение успешно отменен. Подпрограмма возвращает значение FALSE , если запрос не удалось отменить (например, потому, что канал DMA был выделен до того, как запрос можно было отменить).

CancelAdapterChannel не является системной подпрограммой, которую можно вызывать напрямую по имени. Эта подпрограмма может вызываться только указателем из адреса, возвращаемого в структуре DMA_OPERATIONS . Драйверы получают адрес этой подпрограммы, вызывая IoGetDmaAdapter с элементом Version параметра DeviceDescription , для 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