WdfIoQueueDrain, fonction (wdfio.h)

[S’applique à KMDF et UMDF]

La méthode WdfIoQueueDrain entraîne l’arrêt de la mise en file d’attente des E/S dans une file d’attente d’E/S, tout en autorisant la remise et le traitement des requêtes déjà mises en file d’attente.

Syntaxe

void WdfIoQueueDrain(
  [in]           WDFQUEUE               Queue,
  [in, optional] PFN_WDF_IO_QUEUE_STATE DrainComplete,
  [in, optional] WDFCONTEXT             Context
);

Paramètres

[in] Queue

Handle vers un objet de file d’attente framework.

[in, optional] DrainComplete

Pointeur vers une fonction de rappel fournie par le pilote EvtIoQueueState. Ce paramètre est facultatif et peut être NULL.

[in, optional] Context

Pointeur non typé vers les informations de contexte fournies par le pilote que l’infrastructure transmet à la fonction de rappel EvtIoQueueState. Ce paramètre est facultatif et peut être NULL.

Valeur de retour

Aucun

Remarques

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Après qu’un pilote appelle WdfIoQueueDrain, l’infrastructure cesse d’ajouter des requêtes d’E/S à la file d’attente spécifiée. Si l’infrastructure reçoit des demandes supplémentaires pour la file d’attente, elle les termine avec une valeur d’état d’achèvement de STATUS_INVALID_DEVICE_STATE.

Si le pilote fournit une EvtIoQueueState fonction de rappel, l’infrastructure l’appelle une fois toutes les demandes remises au pilote terminées ou annulées. Vous pouvez modifier le runtime d’intégration au niveau duquel le rappel s’exécute en spécifiant ExecutionLevel dans WDF_OBJECT_ATTRIBUTES au moment de la création de la file d’attente. Pour plus d’informations, consultez la section Remarques deEVT_WDF_IO_QUEUE_STATE.

Le pilote ne doit pas appeler une autre méthode qui modifie l’état de file d’attente, par exemple WdfIoQueuePurge ou WdfIoQueueStart, avant que l’infrastructure ait appelé EvtIoQueueState.

Si un pilote spécifie NULL pour drainComplete, le pilote peut appeler une autre opération de modification d’état avant la fin des requêtes.

En guise de meilleure pratique, vous devez uniquement appeler WdfIoQueueDrain lorsque vous êtes certain que les demandes d’E/S en attente de la file d’attente se terminent en temps opportun. Sinon, utilisez WdfIoQueuePurge. Pour plus d’informations, consultez Gestion des files d’attente d’E/S.

Une fois qu’un pilote a vidé une file d’attente d’E/S, il peut redémarrer la file d’attente en appelant WdfIoQueueStart.

Exemples

L’exemple de code suivant draine une file d’attente d’E/S et appelle la fonction EvtIoQueueDrainComplete d’un pilote lorsque toutes les demandes remises au pilote ont été terminées ou annulées.

WdfIoQueueDrain(
                Queue,
                EvtIoQueueDrainComplete,
                (WDFCONTEXT) myQueueContext
                );

Spécifications

Besoin	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
En-tête	wdfio.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
règles de conformité DDI	ChangeQueueState(kmdf), DriverCreate(kmdf), EvtSurpriseRemoveNoSuspendQueue(kmdf), KmdfIrql (kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), NoCancelFromEvtSurpriseRemove(kmdf)

Voir aussi

EvtIoQueueState

WdfIoQueueDrainSynchronously

WdfIoQueuePurge