EVT_WDF_IO_QUEUE_IO_STOP fonction de rappel (wdfio.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La fonction de rappel d’événement EvtIoStop d’un pilote termine, met en file d’attente ou suspend le traitement d’une requête spécifiée, car la file d’attente d’E/S de la requête est arrêtée.

Syntaxe

EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;

void EvtWdfIoQueueIoStop(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request,
  [in] ULONG ActionFlags
)
{...}

Paramètres

[in] Queue

Handle de l’objet de file d’attente d’infrastructure associé à la demande d’E/S.

[in] Request

Handle pour un objet de requête d’infrastructure.

[in] ActionFlags

Or au niveau du bit d’un ou de plusieurs indicateurs WDF_REQUEST_STOP_ACTION_FLAGS typés qui identifient la raison pour laquelle la fonction de rappel est appelée et si la demande est annulable.

Valeur de retour

None

Remarques

Un pilote inscrit une fonction de rappel EvtIoStop lorsqu’il appelle 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 EvtIoStop pour une file d’attente d’E/S, l’infrastructure l’appelle lorsque l’appareil sous-jacent de la file d’attente quitte son état opérationnel (D0). L’infrastructure appelle la fonction de rappel EvtIoStop pour chaque demande d’E/S que le pilote n’a pas terminée, y compris les demandes que le pilote possède et celles qu’il a transférées à une cible d’E/S.

Dans la plupart des cas, la fonction de rappel EvtIoStoptermine, annule ou reporte le traitement ultérieur de la demande d’E/S.

En règle générale, le pilote effectue l’une des opérations suivantes :

Si le pilote est propriétaire de la requête d’E/S, il appelle WdfRequestUnmarkCancelable (si la requête est annulable) et appelle WdfRequestStopAcknowledge avec la valeur Requeue TRUE, ou il appelle WdfRequestComplete avec une valeur d’achèvement status STATUS_SUCCESS ou STATUS_CANCELLED.
Avant de pouvoir appeler des méthodes WdfRequestXxx en toute sécurité, le pilote doit s’assurer que son implémentation d’EvtIoStop dispose d’un accès exclusif à la requête.

Pour ce faire, le pilote doit synchroniser l’accès à la demande pour empêcher d’autres threads de manipuler la requête simultanément. La méthode de synchronisation que vous choisissez dépend de la conception de votre pilote.

Par exemple, si la demande est conservée dans une zone de contexte partagé, le rappel EvtIoStop peut acquérir un verrou de pilote interne, supprimer la demande du contexte partagé, puis libérer le verrou. À ce stade, le rappel EvtIoStop est propriétaire de la demande et peut terminer ou renvoyer la demande en toute sécurité.

Sinon, le pilote reporte le traitement ultérieur de la demande et appelle WdfRequestStopAcknowledge avec une valeur de mise en file d’attente FALSE.
Si le pilote a transféré la demande d’E/S à une cible d’E/S, il peut appeler WdfRequestCancelSentRequest pour tenter d’annuler la demande.
Ou, si le pilote a transféré la demande d’E/S à un pilote de niveau inférieur dans sa propre pile de pilotes, et que l’infrastructure appelle le rappel EvtIoStop du pilote avec une valeur ActionFlagsde WdfRequestStopActionSuspend, le pilote peut appeler WdfRequestStopAcknowledge avec une valeur De mise en file d’attente FALSE. Avant cela, le pilote doit vérifier que les conditions suivantes sont remplies :
- Le pilote inférieur cesse de traiter toutes les demandes d’E/S en attente en réponse à la réception d’un IRP défini sur l’alimentation (Dx).
- La fonction de rappel CompletionRoutine du pilote peut terminer les requêtes lorsque l’appareil est dans un état de faible consommation.

Un pilote peut choisir de n’effectuer aucune action dans EvtIoStop pour les demandes qui sont garanties de se terminer dans un court laps de temps.

Dans ce cas, l’infrastructure attend que la demande spécifiée soit terminée avant de déplacer l’appareil (ou le système) vers un état d’alimentation inférieur ou de le supprimer. Potentiellement, cette inaction peut empêcher un système d’entrer dans son état de mise en veille prolongée ou d’un autre état de faible alimentation du système. Dans les cas extrêmes, le système peut se bloquer avec le code de vérification d’erreur 9F.

Si l’indicateur WdfRequestStopRequestCancelable est défini dans le paramètre ActionFlags , le pilote doit appeler WdfRequestUnmarkCancelable avant d’appeler WdfRequestComplete pour terminer (ou annuler) la demande ou WdfRequestStopAcknowledge pour mettre la demande en file d’attente.

Si le pilote transfère une requête d’E/S à partir de l’un de ses gestionnaires de requêtes et spécifie l’indicateur WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET dans la structure WDF_REQUEST_SEND_OPTIONS de la requête, le framework n’appelle pas la fonction de rappel EvtIoStop du pilote pour cette requête. Toutefois, si le pilote transfère la même demande d’E/S à partir d’un autre thread, l’infrastructure peut appeler EvtIoStop pour cette requête.

Pour plus d’informations sur la fonction de rappel EvtIoStop , consultez Utilisation de Power-Managed files d’attente d’E/S.

Cette fonction de rappel 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.

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)