EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE fonction de rappel (wdfio.h)
[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.
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.
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) |