Méthode IWDFIoRequest ::MarkCancelable (wudfddi.h)

Article
03/05/2024

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.]

La méthode MarkCancelable permet l’annulation de la demande d’E/S.

Syntaxe

void MarkCancelable(
  [in] IRequestCallbackCancel *pCancelCallback
);

Paramètres

[in] pCancelCallback

Pointeur vers l’interface IRequestCallbackCancel dont l’infrastructure appelle la méthode après l’annulation de la demande d’E/S.

Valeur de retour

None

Remarques

Une fois qu’un pilote reçoit une demande d’E/S en entrée dans une fonction de rappel d’événement IQueueCallbackRead ::OnRead, IQueueCallbackWrite ::OnWrite ou IQueueCallbackDeviceIoControl ::OnDeviceIoControl , le pilote peut appeler la méthode MarkCancelable pour activer l’annulation de la demande. Plus tard, le pilote peut appeler la méthode IWDFIoRequest ::UnmarkCancelable pour désactiver l’annulation de la requête.

Avant qu’un pilote appelle MarkCancelable, il doit implémenter la méthode IRequestCallbackCancel ::OnCancel .

L’infrastructure de pilote en mode utilisateur (UMDF) n’autorise qu’une seule méthode IRequestCallbackCancel ::OnCancel par file d’attente. Par conséquent, lorsqu’un pilote appelle MarkCancelable pour les demandes associées à une file d’attente particulière pour permettre à l’infrastructure d’annuler ces demandes, le pilote doit passer un pointeur vers l’interface IRequestCallbackCancel pour le même objet request-callback. Plus tard, pour annuler chaque requête, l’infrastructure transmet un pointeur vers l’interface IWDFIoRequest pour la requête dans un appel à la méthode IRequestCallbackCancel ::OnCancel de cet objet de rappel de requête.

Le pilote doit appeler IWDFIoRequest ::Complete, soit à partir de la méthode IRequestCallbackCancel ::OnCancel , soit à partir de son chemin d’achèvement d’E/S normal.

Une fois qu’un pilote a appelé MarkCancelable pour activer l’annulation, la demande reste annulable tant que le pilote a la possession de l’objet de requête, sauf si le pilote appelle UnmarkCancelable pour désactiver l’annulation.

Si le pilote appelle la méthode IWDFIoRequest ::ForwardToIoQueue pour transférer la requête vers une autre file d’attente, les règles suivantes s’appliquent :

L’annulation des demandes d’E/S ne peut pas être activée lorsque le pilote transfère les demandes à une autre file d’attente.
En règle générale, le pilote ne doit pas appeler MarkCancelable pour activer l’annulation d’une demande avant d’appeler IWDFIoRequest ::ForwardToIoQueue. Le pilote peut également rendre la requête annulable. Toutefois, le pilote doit ensuite appeler UnmarkCancelable pour désactiver l’annulation de la demande avant d’appeler IWDFIoRequest ::ForwardToIoQueue.
Lorsque la requête se trouve dans une deuxième file d’attente, le framework en est propriétaire et peut l’annuler sans en informer le pilote.
Une fois que l’infrastructure a retiré la demande de la deuxième file d’attente et remise la demande au pilote, le pilote peut appeler MarkCancelable pour activer l’annulation.

Exemples

L’exemple de code suivant configure une requête afin que l’infrastructure puisse l’annuler.

    //
    // The QueryInteraface should not fail.
    //
    (VOID)this->QueryInterface(_uuidof(IRequestCallbackCancel),
                               (PVOID *)&cancelCallback);

    pWdfRequest->MarkCancelable(cancelCallback);

Configuration requise

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1.5
En-tête	wudfddi.h (inclure Wudfddi.h)
DLL	WUDFx.dll