PCANCEL_ADAPTER_CHANNEL fonction de rappel (wdm.h)

Article
02/27/2024

La routine CancelAdapterChannel tente d’annuler une demande en attente d’allocation d’un canal DMA.

Syntaxe

PCANCEL_ADAPTER_CHANNEL PcancelAdapterChannel;

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

Paramètres

[in] DmaAdapter

Pointeur vers une structure DMA_ADAPTER . Cette structure est l’objet adaptateur qui attend l’octroi de la demande d’allocation de ressources en attente. L’appelant a obtenu ce pointeur à partir d’un appel précédent à la routine IoGetDmaAdapter , et l’appelant a passé ce pointeur à l’appel AllocateAdapterChannelEx, GetScatterGatherListEx ou BuildScatterGatherListEx qui demandait l’allocation de ressource.

[in] DeviceObject

Pointeur vers une structure DEVICE_OBJECT . Cette structure est l’objet d’appareil physique (PDO) qui représente l’appareil cible pour l’opération DMA pour laquelle le canal DMA a été demandé.

[in] DmaTransferContext

Pointeur vers un contexte de transfert DMA. Cette valeur de paramètre doit correspondre au même contexte de transfert DMA qui a été passé à l’appel AllocateAdapterChannelEx, GetScatterGatherListEx ou BuildScatterGatherListEx qui a demandé l’allocation du canal de l’adaptateur.

Valeur retournée

CancelAdapterChannel retourne TRUE si la demande d’allocation en attente est annulée avec succès. La routine retourne FALSE si la demande n’a pas pu être annulée (par exemple, parce que le canal DMA a été alloué avant l’annulation de la demande).

Remarques

CancelAdapterChannel n’est pas une routine système qui peut être appelée directement par nom. Cette routine peut être appelée uniquement par un pointeur à partir de l’adresse retournée dans une structure DMA_OPERATIONS. Les pilotes obtiennent l’adresse de cette routine en appelant IoGetDmaAdapter avec le membre Version du paramètre DeviceDescription défini sur DEVICE_DESCRIPTION_VERSION3. Si IoGetDmaAdapter retourne NULL, la routine n’est pas disponible sur votre plateforme.

CancelAdapterChannel tente d’annuler une demande d’allocation en attente qui a été effectuée par un appel asynchrone à une routine d’allocation telle que AllocateAdapterChannelEx, GetScatterGatherListEx ou BuildScatterGatherListEx. Lorsqu’elle est appelée de manière asynchrone, la routine d’allocation peut retourner tant que la demande d’allocation est toujours en attente et avant l’appel de la routine d’exécution fournie par le pilote (AdapterControl ou AdapterListControl). Si CancelAdapterChannel annule correctement la demande d’allocation en attente, les ressources ne sont pas allouées et la routine d’exécution n’est pas appelée.

Si un pilote appelle AllocateAdapterChannelEx pour demander des ressources pour une routine AdapterControl fournie par le pilote, puis appelle CancelAdapterChannel pour annuler la demande, CancelAdapterChannel peut retourner l’une des valeurs suivantes :

TRUE, si l’objet adaptateur attend l’allocation demandée lorsque l’appel CancelAdapterChannel se produit. Dans ce cas, CancelAdapterChannel annule la demande d’allocation en attente et la routine AdapterControl du pilote n’est pas appelée.
FALSE, si la routine AdapterControl a déjà été appelée ou est sur le point d’être appelée.

De même, si un pilote appelle GetScatterGatherListEx ou BuildScatterGatherListEx pour demander des ressources pour une routine AdapterListControl fournie par le pilote, puis appelle CancelAdapterChannel pour annuler la demande, CancelAdapterChannel peut retourner l’une des valeurs suivantes :

TRUE, si l’objet adaptateur attend l’allocation demandée lorsque l’appel CancelAdapterChannel se produit. Dans ce cas, CancelAdapterChannel annule la demande d’allocation en attente et la routine AdapterListControl du pilote n’est pas appelée.
FALSE, si la routine AdapterListControl a déjà été appelée ou est sur le point d’être appelée.

CancelAdapterChannel peut annuler de manière préventive les demandes d’allocation de canal futures qui utilisent le contexte de transfert DMA spécifié. Par exemple, si l’appelant fournit le même contexte de transfert DMA à CancelAdapterChannel et AllocateAdapterChannelEx, et si l’appel CancelAdapterChannelEx réussit et se produit avant l’appel AllocateAdapterChannelEx , l’allocation demandée par l’appel AllocateAdapterChannelEx est automatiquement annulée.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 8.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL