PCANCEL_ADAPTER_CHANNEL fonction de rappel (wdm.h)

Article
02/07/2025

La routine CancelAdapterChannel tente d’annuler une demande en attente pour allouer 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 que la demande d’allocation de ressources en attente soit accordée. L’appelant a obtenu ce pointeur à partir d’un appel précédent à la routine IoGetDmaAdapter, et l’appelant a passé ce pointeur à l'AllocateAdapterChannelEx, GetScatterGatherListEx, ou 'appel BuildScatterGatherListEx qui a demandé l’allocation de ressources.

[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 être le même contexte de transfert DMA qui a été passé à l'd'AllocateAdapterChannelEx, GetScatterGatherListEx, ou 'appel BuildScatterGatherListEx qui a demandé l’allocation du canal d’adaptateur.

Valeur de retour

CancelAdapterChannel retourne TRUE si la demande d’allocation en attente a été annulée. La routine retourne FALSE si la requête 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 le pointeur de l’adresse retournée dans une structure DMA_OPERATIONS. Pilotes obtiennent l’adresse de cette routine en appelant IoGetDmaAdapter avec le membre version du paramètre DeviceDes cription 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 effectuée par un appel asynchrone à une routine d’allocation telle que AllocateAdapterChannelEx, GetScatterGatherListEx, ou BuildScatterGatherListEx. Lorsqu’elle est appelée de façon asynchrone, la routine d’allocation peut retourner pendant que la demande d’allocation est toujours en attente et avant que la routine d’exécution fournie par le pilote (AdapterControl ou AdapterListControl) soit appelée. 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 demander des ressources pour une routine AdapterControl fournie par le pilote, puis appelle CancelAdapterChannel pour annuler la requête, 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 demander des ressources pour une routine AdapterListControl fournie par le pilote, puis appelle CancelAdapterChannel pour annuler la requête, 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éemptive les futures demandes d’allocation de canal 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 que l’appel CancelAdapterChannel réussit et se produit avant l’appel AllocateAdapterChannelEx, l’allocation demandée par l’appel AllocateAdapterChannelEx est automatiquement annulée.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible à partir de Windows 8.
plateforme cible	Bureau
d’en-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL