WdfIoQueueReadyNotify, fonction (wdfio.h)

[S’applique à KMDF et UMDF]

La méthode WdfIoQueueReadyNotify inscrit (ou déregisters) une fonction de rappel d’événement que l’infrastructure appelle chaque fois qu’une file d’attente d’E/S spécifiée qui était précédemment vide reçoit une ou plusieurs demandes d’E/S.

Syntaxe

NTSTATUS WdfIoQueueReadyNotify(
  [in]           WDFQUEUE               Queue,
  [in, optional] PFN_WDF_IO_QUEUE_STATE QueueReady,
  [in, optional] WDFCONTEXT             Context
);

Paramètres

[in] Queue

Handle vers un objet de file d’attente d’infrastructure.

[in, optional] QueueReady

Pointeur vers une fonction de rappel EvtIoQueueState fournie par le pilote, si le pilote s’inscrit pour une notification prête ou NULL si le pilote est déregistré.

[in, optional] Context

Pointeur non typé vers les informations de contexte fournies par le pilote que l’infrastructure transmet à la fonction de rappel EvtIoQueueState , si le pilote s’inscrit pour une notification prête ou NULL si le pilote est déregistré.

Valeur retournée

WdfIoQueueReadyNotify retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut renvoyer l’une des valeurs suivantes :

Code de retour Description
STATUS_INVALID_PARAMETER
Le pilote a fourni un handle non valide.
STATUS_INVALID_DEVICE_REQUEST
Cette valeur est retournée si l’une des opérations suivantes se produit :

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

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

Remarques

Une fois qu’un pilote a appelé WdfIoQueueReadyNotify pour inscrire une fonction de rappel EvtIoQueueState , l’infrastructure appelle la fonction de rappel chaque fois que l’état de la file d’attente spécifiée passe de vide à non vide. Plus précisément, l’infrastructure appelle EvtIoQueueState lorsqu’une requête arrive sur une file d’attente vide, même si le pilote possède toujours des demandes précédemment remises à partir de la file d’attente qu’elle n’a pas encore terminée. Vous pouvez modifier l’IRQL à laquelle 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 de EVT_WDF_IO_QUEUE_STATE.

L’infrastructure n’appelle pas EvtIoQueueState pendant que la file d’attente spécifiée est arrêtée. Lorsque la file d’attente démarre, l’infrastructure appelle EvtIoQueueState si la file d’attente n’est pas vide.

Votre pilote peut appeler WdfIoQueueReadyNotify uniquement pour les files d’attente d’E/S qui utilisent la méthode de répartition manuelle .

La fonction de rappel EvtIoQueueState appelle généralement WdfIoQueueRetrieveNextRequest ou WdfIoQueueRetrieveRequestByFileObject dans une boucle pour récupérer toutes les demandes qui sont arrivées depuis la dernière exécution de la fonction de rappel.

Pour empêcher l’infrastructure d’appeler la fonction de rappel EvtIoQueueState , le pilote doit appeler de nouveau WdfIoQueueReadyNotify avec le paramètre QueueReady défini sur NULL. Toutefois, le pilote doit d’abord appeler WdfIoQueueStop ou WdfIoQueueStopSynchronously pour arrêter la file d’attente d’E/S. Le pilote peut ensuite appeler WdfIoQueueStart pour redémarrer la file d’attente.

Lorsqu’un pilote appelle WdfIoQueueReadyNotify pour inscrire une fonction de rappel EvtIoQueueState , il est possible que l’infrastructure appelle la fonction de rappel avant que WdfIoQueueReadyNotify ne retourne.

Pour plus d’informations sur la méthode WdfIoQueueReadyNotify , consultez Méthodes de répartition des demandes d’E/S.

Exemples

L’exemple de code suivant inscrit la fonction EvtIoQueueReady d’un pilote afin que cette fonction soit appelée lorsque la file d’attente d’E/S spécifiée reçoit une requête d’E/S.

Status = WdfIoQueueReadyNotify(
                               ReadQueue,
                               EvtIoQueueReady,
                               myQueueContext
                               );

Spécifications

   
Plateforme cible Universal
Version KMDF minimale 1.0
Version UMDF minimale 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 DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

EvtIoQueueState

WDF_IO_QUEUE_CONFIG

WdfIoQueueRetrieveNextRequest

WdfIoQueueRetrieveRequestByFileObject