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

Artigo
02/07/2025

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 solicitação de alocação de recursos pendente ser concedida. O chamador obteve esse ponteiro de uma chamada anterior para a rotina de IoGetDmaAdapter e o chamador passou esse ponteiro para o AllocateAdapterChannelEx, GetScatterGatherListExou chamada BuildScatterGatherList Ex 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 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, GetScatterGatherListExou BuildScatterGatherListEx que solicitou a alocação do canal do adaptador.

Valor de retorno

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

Observações

CancelAdapterChannel não é uma rotina do sistema que pode ser chamada diretamente pelo nome. Essa rotina pode ser chamada apenas pelo ponteiro do endereço retornado em uma estrutura de DMA_OPERATIONS. Drivers obtêm o endereço dessa rotina chamando IoGetDmaAdapter com o membro de versão 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, GetScatterGatherListExou BuildScatterGatherListEx. Quando chamado de forma assíncrona, a rotina de alocação pode retornar enquanto a solicitação de alocação ainda estiver 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 de 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 a chamada CancelAdapterChannel ocorrer. Nesse caso, CancelAdapterChannel cancela a solicitação de alocação pendente e a rotina de adapterControl do do driver não é chamada.
FALSE, se a rotina AdapterControl já tiver sido chamada ou estiver prestes a ser chamada.

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

TRUE, se o objeto do adaptador estiver aguardando a alocação solicitada quando a chamada CancelAdapterChannel ocorrer. Nesse caso, CancelAdapterChannel cancela a solicitação de alocação pendente e a rotina de AdapterListControl do do driver não é chamada.
FALSE, se a rotina AdapterListControl já tiver sido chamada ou estiver 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 AllocateAdapterChannelExe a chamada CancelAdapterChannel for bem-sucedida e ocorrer antes da chamada AllocateAdapterChannelEx, a alocação solicitada pela chamada AllocateAdapterChannelEx é cancelada automaticamente.

Requisitos

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