EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE fonction de rappel (wdfio.h)

  • Article

[S’applique à KMDF et UMDF]

La fonction de rappel d’événement EvtIoCanceledOnQueue d’un pilote informe le pilote qu’il doit effectuer une demande d’E/S que l’infrastructure a supprimée d’une file d’attente d’E/S.

Syntaxe

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE EvtWdfIoQueueIoCanceledOnQueue;

void EvtWdfIoQueueIoCanceledOnQueue(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request
)
{...}

Paramètres

[in] Queue

Handle pour un objet file d’attente d’E/S.

[in] Request

Handle pour un objet de requête.

Valeur de retour

None

Remarques

Un pilote inscrit une fonction de rappel EvtIoCanceledOnQueue lorsqu’il appelle la méthode WdfIoQueueCreate . Pour plus d’informations sur l’appel de WdfIoQueueCreate, consultez Création de files d’attente d’E/S.

Si un pilote inscrit une fonction de rappel EvtIoCanceledOnQueue pour une file d’attente d’E/S, l’infrastructure appelle la fonction de rappel dans les situations suivantes :

  • Un gestionnaire de requêtes reçoit une demande d’E/S d’une file d’attente d’E/S, le pilote appelle WdfRequestForwardToIoQueue, WdfRequestForwardToParentDeviceIoQueue ou WdfRequestRequeue pour renvoyer la demande à la file d’attente d’E/S pour laquelle la fonction de rappel EvtIoCanceledOnQueue est inscrite et l’opération d’E/S associée est ensuite annulée.
  • La fonction de rappel EvtIoInCallerContext du pilote reçoit une demande d’E/S, le pilote appelle WdfDeviceEnqueueRequest pour renvoyer la demande au framework, l’infrastructure place ensuite la demande dans la file d’attente d’E/S pour laquelle la fonction de rappel EvtIoCanceledOnQueue est inscrite et l’opération d’E/S associée est ensuite annulée.
Une fois que l’infrastructure a appelé la fonction de rappel EvtIoCanceledOnQueue, le pilote est propriétaire de l’objet de requête et doit terminer la requête avec un code status approprié, soit dans EvtIoCanceledOnQueue, soit dans une version ultérieure. Lorsque l’infrastructure appelle EvtIoCanceledOnQueue, la requête est toujours associée à la file d’attente d’E/S, mais le pilote ne peut pas mettre la demande en file d’attente. La propriété de la demande reste du côté du pilote, même si le pilote ne termine pas la demande dans EvtIoCanceledOnQueue. Si le pilote termine la requête après le retour de EvtIoCanceledOnQueue , il ne peut pas appeler WdfIoQueueFindRequest et WdfIoQueueRetrieveFoundRequest pour réacquire la propriété de la demande, car le pilote possède déjà la propriété de la requête.

En règle générale, dans EvtIoCanceledOnQueue, le pilote effectue la demande d’E/S avec une status d’achèvement de STATUS_CANCELLED.

Dans certains cas, le pilote peut avoir précédemment relégué une demande d’E/S dans une file d’attente manuelle, peut-être pour attendre des informations. Par exemple, dans l’un de ses gestionnaires de requêtes, un pilote peut placer une demande d’E/S associée à une transaction DMA en attente dans une file d’attente manuelle. Dans ce cas, le pilote tente d’annuler la transaction DMA dans son rappel EvtIoCanceledOnQueue . Selon les résultats de l’opération d’annulation, le pilote termine la demande avec un status approprié, soit dans EvtIoCanceledOnQueue, soit une version ultérieure.

L’infrastructure n’appelle pas la fonction de rappel EvtIoCanceledOnQueue du pilote pour les demandes d’E/S que l’infrastructure n’a jamais remises au pilote.

L’infrastructure appelle une fonction de rappel EvtIoCanceledOnQueue dès qu’elle détermine qu’une demande d’E/S a été annulée, quelle que soit la méthode de distribution définie par le pilote pour la file d’attente d’E/S. Par conséquent, l’infrastructure peut appeler une fonction de rappel EvtIoCanceledOnQueue pour :

  • Requête dans une file d’attente qui utilise la répartition séquentielle, même si le pilote possède actuellement une autre requête de la file d’attente.
  • Requête dans une file d’attente pour laquelle le pilote a défini NumberOfPresentedRequests, même si le pilote possède actuellement le nombre maximal de requêtes.
Pour plus d’informations sur la fonction de rappel EvtIoCanceledOnQueue , consultez Annulation des demandes d’E/S.

La fonction de rappel EvtIoCanceledOnQueue peut être appelée dans IRQL <= DISPATCH_LEVEL, sauf si le membre ExecutionLevel de la structure de WDF_OBJECT_ATTRIBUTES du périphérique ou du pilote est défini sur WdfExecutionLevelPassive.

Si l’IRQL est PASSIVE_LEVEL, l’infrastructure appelle la fonction de rappel dans une région critique.

Exemples

Pour définir une fonction de rappel EvtIoCanceledOnQueue , vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction 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.

Pour définir une fonction de rappel EvtIoCanceledOnQueue , vous devez d’abord fournir une déclaration de fonction requise par SDV et d’autres outils de vérification. L’exemple suivant est tiré de l’exemple de pilote de carte à puce PCMCIA .

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;

Dans l’exemple de pilote de carte à puce PCMCIA, le pilote utilise une file d’attente manuelle pour stocker les demandes de notification de carte intelligentes en attente. Le pilote fournit une fonction de rappel EvtIoCanceledOnQueue dans laquelle le pilote efface le champ de notification et termine la requête.

_Use_decl_annotations_
VOID
PscrEvtIoCanceledOnQueue(
    WDFQUEUE  Queue,
    WDFREQUEST  Request
    )

{
    PDEVICE_EXTENSION DeviceExtension;
    PSMARTCARD_EXTENSION smartcardExtension;

    DeviceExtension = GetDeviceExtension(WdfIoQueueGetDevice(Queue));
    smartcardExtension = (PSMARTCARD_EXTENSION) &DeviceExtension->SmartcardExtension;

    //KdPrint(("Cancelled on queue 0x%x\n", WdfRequestWdmGetIrp(Request)));

    InterlockedExchangePointer(
                             &(smartcardExtension->OsData->NotificationIrp),
                             NULL
                             );

    WdfRequestComplete(Request, STATUS_CANCELLED);
}

Le type de fonction EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE est défini dans le fichier d’en-tête Wdfio.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 EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE 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 KMDF. Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.

Configuration requise

Condition requise Valeur
Plateforme cible Universal
Version KMDF minimale 1.0
Version UMDF minimale 2.0
En-tête wdfio.h (inclure Wdf.h)
IRQL <= DISPATCH_LEVEL (voir la section Notes)

Voir aussi

WdfIoQueueCreate

WdfRequestForwardToIoQueue