DRIVER_CANCEL fonction de rappel (wdm.h)

Article
02/27/2024

La routine Annuler annule une opération d’E/S.

Syntaxe

DRIVER_CANCEL DriverCancel;

void DriverCancel(
  [in, out] _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp
)
{...}

Paramètres

[in, out] DeviceObject

Pointeur fourni par l’appelant vers une structure DEVICE_OBJECT . Il s’agit de l’objet d’appareil pour l’appareil cible, précédemment créé par la routine AddDevice du pilote.

[in, out] Irp

Pointeur fourni par l’appelant vers une structure IRP qui décrit l’opération d’E/S à annuler.

Valeur de retour

None

Remarques

Lorsqu’un pilote ou un autre composant système appelle IoCancelIrp, le gestionnaire d’E/S appelle la routine Cancel de l’IRP, si elle a été inscrite pour l’IRP.

Pour inscrire une routine Cancel pour un IRP, un pilote peut utiliser l’une des deux méthodes suivantes :

Un pilote qui fournit une routine StartIo et utilise la file d’attente d’appareils fournie par le gestionnaire d’E/S peut spécifier une routine Annuler lors de l’appel de IoStartPacket.
Un pilote qui crée et gère des files d’attente d’appareils supplémentaires peut inscrire une routine Annuler en appelant IoSetCancelRoutine.

Une seule routine Cancel peut être inscrite pour une IRP à la fois.

Le gestionnaire d’E/S appelle IoAcquireCancelSpinLock avant d’appeler la routine Cancel d’un pilote. La routine Cancel doit donc appeler IoReleaseCancelSpinLock à un moment donné. La routine ne doit pas maintenir le verrou de rotation plus longtemps que nécessaire.

La routine Cancel s’exécute dans un contexte de thread arbitraire à IRQL = DISPATCH_LEVEL jusqu’à ce qu’elle appelle IoReleaseCancelSpinLock, ce qui remplace l’IRQL par une valeur fournie par l’appelant. Le pilote doit spécifier Irp-CancelIrql> pour cette valeur.

La routine Cancel doit définir le membre Status du bloc d’E/S status sur STATUS_CANCELLED et définir son membre Information sur zéro. La routine doit ensuite terminer l’IRP spécifiée en appelant IoCompleteRequest.

Pour plus d’informations sur l’implémentation de la routine Cancel d’un pilote, consultez Annulation des irps.

Exemples

Pour définir une routine annuler le rappel, vous devez d’abord fournir une déclaration de fonction qui identifie le type de routine de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction de rappel permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une routine de rappel Cancel nommée MyCancel, utilisez le type DRIVER_CANCEL comme indiqué dans cet exemple de code :

DRIVER_CANCEL MyCancel;

Ensuite, implémentez votre routine de rappel comme suit :

_Use_decl_annotations_
VOID
  MyCancel(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

Le type de fonction DRIVER_CANCEL est défini dans le fichier d’en-tête Wdm.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation _Use_decl_annotations_ à votre définition de fonction. L’annotation _Use_decl_annotations_ garantit que les annotations appliquées au type de fonction DRIVER_CANCEL dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes WDM. Pour plus d’informations sur _Use_decl_annotations_, consultez Annotating Function Behavior.

Configuration requise

Condition requise	Valeur
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Appelé à DISPATCH_LEVEL (voir la section Remarques).

Partager via