PCANCEL_ADAPTER_CHANNEL función de devolución de llamada (wdm.h)

Artículo
03/08/2023

La rutina CancelAdapterChannel intenta cancelar una solicitud pendiente para asignar un canal DMA.

Sintaxis

PCANCEL_ADAPTER_CHANNEL PcancelAdapterChannel;

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

Parámetros

[in] DmaAdapter

Puntero a una estructura DMA_ADAPTER . Esta estructura es el objeto de adaptador que está esperando a que se conceda la solicitud de asignación de recursos pendiente. El llamador obtuvo este puntero de una llamada anterior a la rutina IoGetDmaAdapter y el autor de la llamada pasó este puntero a la llamada AllocateAdapterChannelEx, GetScatterGatherListEx o BuildScatterGatherListEx que solicitó la asignación de recursos.

[in] DeviceObject

Puntero a una estructura de DEVICE_OBJECT . Esta estructura es el objeto de dispositivo físico (PDO) que representa el dispositivo de destino para la operación DMA para la que se solicitó el canal DMA.

[in] DmaTransferContext

Puntero a un contexto de transferencia de DMA. Este valor de parámetro debe ser el mismo contexto de transferencia de DMA que se pasó a la llamada AllocateAdapterChannelEx, GetScatterGatherListEx o BuildScatterGatherListEx que solicitó la asignación del canal de adaptador.

Valor devuelto

CancelAdapterChannel devuelve TRUE si la solicitud de asignación pendiente se cancela correctamente. La rutina devuelve FALSE si no se pudo cancelar la solicitud (por ejemplo, porque el canal DMA se asignó antes de que se pudiera cancelar la solicitud).

Comentarios

CancelAdapterChannel no es una rutina del sistema a la que se puede llamar directamente por nombre. Solo el puntero de la dirección devuelta en una estructura de DMA_OPERATIONS puede llamar a esta rutina . Los controladores obtienen la dirección de esta rutina llamando a IoGetDmaAdapter con el miembro Version del parámetro DeviceDescription establecido en DEVICE_DESCRIPTION_VERSION3. Si IoGetDmaAdapter devuelve NULL, la rutina no está disponible en la plataforma.

CancelAdapterChannel intenta cancelar una solicitud de asignación pendiente realizada por una llamada asincrónica a una rutina de asignación como AllocateAdapterChannelEx, GetScatterGatherListEx o BuildScatterGatherListEx. Cuando se llama de forma asincrónica, la rutina de asignación puede devolver mientras la solicitud de asignación sigue pendiente y antes de llamar a la rutina de ejecución proporcionada por el controlador (AdapterControl o AdapterListControl). Si CancelAdapterChannel cancela correctamente la solicitud de asignación pendiente, no se asignan los recursos y no se llama a la rutina de ejecución.

Si un controlador llama a AllocateAdapterChannelEx para solicitar recursos para una rutina AdapterControl proporcionada por el controlador y, a continuación, llama a CancelAdapterChannel para cancelar la solicitud, CancelAdapterChannel puede devolver uno de los siguientes valores:

TRUE, si el objeto de adaptador está esperando la asignación solicitada cuando se produce la llamada CancelAdapterChannel . En este caso, CancelAdapterChannel cancela la solicitud de asignación pendiente y no se llama a la rutina AdapterControl del controlador.
FALSE, si ya se llamó a la rutina AdapterControl o está a punto de llamarse.

Del mismo modo, si un controlador llama a GetScatterGatherListEx o BuildScatterGatherListEx para solicitar recursos para una rutina AdapterListControl proporcionada por el controlador y, a continuación, llama a CancelAdapterChannel para cancelar la solicitud, CancelAdapterChannel puede devolver uno de los siguientes valores:

TRUE, si el objeto de adaptador está esperando la asignación solicitada cuando se produce la llamada CancelAdapterChannel . En este caso, CancelAdapterChannel cancela la solicitud de asignación pendiente y no se llama a la rutina AdapterListControl del controlador.
FALSE, si ya se llamó a la rutina AdapterListControl o está a punto de llamarse.

CancelAdapterChannel puede cancelar de forma preferente solicitudes de asignación de canales futuras que usan el contexto de transferencia de DMA especificado. Por ejemplo, si el autor de la llamada proporciona el mismo contexto de transferencia de DMA a CancelAdapterChannel y AllocateAdapterChannelEx, y la llamada CancelAdapterChannel se realiza correctamente y se produce antes de la llamada AllocateAdapterChannelEx , se cancela automáticamente la asignación solicitada por la llamada AllocateAdapterChannelEx .

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 8.
Plataforma de destino	Escritorio
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL