PCANCEL_ADAPTER_CHANNEL função de retorno de chamada (wdm.h)

Artigo
03/08/2023

A rotina CancelAdapterChannel tenta cancelar uma solicitação pendente para alocar um canal DMA.

Sintaxe

PCANCEL_ADAPTER_CHANNEL PcancelAdapterChannel;

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

Parâmetros

[in] DmaAdapter

Um ponteiro para uma estrutura DMA_ADAPTER . Essa estrutura é o objeto do adaptador que está aguardando a concessão da solicitação de alocação de recursos pendente. O chamador obteve esse ponteiro de uma chamada anterior para a rotina IoGetDmaAdapter e o chamador passou esse ponteiro para a chamada AllocateAdapterChannelEx, GetScatterGatherListEx ou BuildScatterGatherListEx que solicitou a alocação de recursos.

[in] DeviceObject

Um ponteiro para uma estrutura DEVICE_OBJECT . Essa estrutura é o PDO (objeto de dispositivo físico) que representa o dispositivo de destino para a operação de DMA para a qual o canal DMA foi solicitado.

[in] DmaTransferContext

Um ponteiro para um contexto de transferência de DMA. Esse valor de parâmetro deve ser o mesmo contexto de transferência de DMA que foi passado para a chamada AllocateAdapterChannelEx, GetScatterGatherListEx ou BuildScatterGatherListEx que solicitou a alocação do canal do adaptador.

Retornar valor

CancelAdapterChannel retornará TRUE se a solicitação de alocação pendente for cancelada com êxito. A rotina retornará FALSE se a solicitação não puder ser cancelada (por exemplo, porque o canal DMA foi alocado antes que a solicitação pudesse ser cancelada).

Comentários

CancelAdapterChannel não é uma rotina do sistema que pode ser chamada diretamente pelo nome. Essa rotina só pode ser chamada por ponteiro do endereço retornado em uma estrutura DMA_OPERATIONS. Os drivers obtêm o endereço dessa rotina chamando IoGetDmaAdapter com o membro Version do parâmetro DeviceDescription definido como DEVICE_DESCRIPTION_VERSION3. Se IoGetDmaAdapter retornar NULL, a rotina não estará disponível em sua plataforma.

CancelAdapterChannel tenta cancelar uma solicitação de alocação pendente que foi feita por uma chamada assíncrona para uma rotina de alocação, como AllocateAdapterChannelEx, GetScatterGatherListEx ou BuildScatterGatherListEx. Quando chamada de forma assíncrona, a rotina de alocação pode retornar enquanto a solicitação de alocação ainda está pendente e antes que a rotina de execução fornecida pelo driver (AdapterControl ou AdapterListControl) seja chamada. Se CancelAdapterChannel cancelar com êxito a solicitação de alocação pendente, os recursos não serão alocados e a rotina de execução não será chamada.

Se um driver chamar AllocateAdapterChannelEx para solicitar recursos para uma rotina adapterControl fornecida pelo driver e, em seguida, chamar CancelAdapterChannel para cancelar a solicitação, CancelAdapterChannel poderá retornar um dos seguintes valores:

TRUE, se o objeto do adaptador estiver aguardando a alocação solicitada quando ocorrer a chamada CancelAdapterChannel . Nesse caso, CancelAdapterChannel cancela a solicitação de alocação pendente e a rotina AdapterControl do driver não é chamada.
FALSE, se a rotina AdapterControl já foi chamada ou está prestes a ser chamada.

Da mesma forma, se um driver chamar GetScatterGatherListEx ou BuildScatterGatherListEx para solicitar recursos para uma rotina AdapterListControl fornecida pelo driver e, em seguida, chamar CancelAdapterChannel para cancelar a solicitação, CancelAdapterChannel poderá retornar um dos seguintes valores:

TRUE, se o objeto do adaptador estiver aguardando a alocação solicitada quando ocorrer a chamada CancelAdapterChannel . Nesse caso, CancelAdapterChannel cancela a solicitação de alocação pendente e a rotina AdapterListControl do driver não é chamada.
FALSE, se a rotina AdapterListControl já foi chamada ou está prestes a ser chamada.

CancelAdapterChannel pode cancelar preventivamente solicitações futuras de alocação de canal que usam o contexto de transferência de DMA especificado. Por exemplo, se o chamador fornecer o mesmo contexto de transferência de DMA para CancelAdapterChannel e AllocateAdapterChannelEx e a chamada CancelAdapterChannel for bem-sucedida e ocorrer antes da chamada AllocateAdapterChannelEx , a alocação solicitada pela chamada AllocateAdapterChannelEx será cancelada automaticamente.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 8.
Plataforma de Destino	Área de Trabalho
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL