WdfRequestStopAcknowledge, fonction (wdfrequest.h)
[S’applique à KMDF et UMDF]
La méthode WdfRequestStopAcknowledge informe l’infrastructure que le pilote a cessé de traiter une demande d’E/S spécifiée.
Syntaxe
void WdfRequestStopAcknowledge(
[in] WDFREQUEST Request,
[in] BOOLEAN Requeue
);
Paramètres
[in] Request
Handle d’un objet de requête d’infrastructure.
[in] Requeue
Valeur booléenne qui, si TRUE, entraîne la mise en file d’attente de la requête dans la file d’attente pour que l’infrastructure la remette à nouveau au pilote. Si la valeur est FALSE, l’infrastructure ne met pas la demande en file d’attente. Pour plus d'informations, consultez la section Notes qui suit.
Valeur de retour
None
Remarques
Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.
Si un pilote inscrit une fonction de rappel EvtIoStop pour une file d’E/S, l’infrastructure l’appelle lorsque l’appareil sous-jacent de la file d’attente quitte son état de fonctionnement (D0). L’infrastructure appelle la fonction de rappel EvtIoStop pour chaque demande d’E/S que le pilote n’a pas effectuée, y compris les demandes que le pilote possède et celles qu’il a transférées à une cible d’E/S. Le pilote doit terminer, annuler ou reporter le traitement de chaque requête en effectuant l’une des opérations suivantes :
- Si le pilote est propriétaire de la demande, il peut appeler WdfRequestComplete pour terminer ou annuler la demande.
- Si le pilote a transféré la demande à une cible d’E/S, il peut appeler WdfRequestCancelSentRequest pour tenter d’annuler la demande.
- Si le pilote reporte le traitement de la demande, il doit appeler WdfRequestStopAcknowledge.
L’infrastructure ne permet pas à l’appareil de quitter son état de fonctionnement (D0) tant que le pilote n’a pas terminé, annulé ou reporté chaque requête qu’une fonction de rappel EvtIoStop reçoit. 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.
Quand la fonction de rappel EvtIoStop d’un pilote appelle WdfRequestStopAcknowledge, elle peut définir le paramètre Requeue sur TRUE ou FALSE :
-
Si vous définissez Requeue sur TRUE , l’infrastructure place la requête dans sa file d’attente d’E/S.
Lorsque l’appareil sous-jacent revient à son état de fonctionnement (D0), l’infrastructure réélivera la demande au pilote.
-
Si vous définissez Requeue sur FALSE , l’infrastructure ne met pas la requête en file d’attente. Si le pilote est propriétaire de la demande, la propriété reste avec le pilote. Si le pilote a transféré la demande, il est responsable de la gestion de la demande lorsqu’elle est terminée. Le pilote doit cesser d’effectuer tout traitement d’E/S qui nécessite un accès matériel.
Lorsque l’appareil sous-jacent revient à son état de fonctionnement (D0), l’infrastructure appelle la fonction de rappel EvtIoResume du pilote, afin que le pilote puisse continuer à traiter la demande.
Avant d’appeler WdfRequestStopAcknowledge, la fonction de rappel EvtIoStop du pilote doit arrêter tout traitement de la demande d’E/S qui nécessite l’accès à l’appareil sous-jacent, car l’appareil est sur le point d’entrer dans un état de faible consommation.
Pour plus d’informations sur la méthode WdfRequestStopAcknowledge , consultez Utilisation de Power-Managed files d’attente d’E/S.
Exemples
Si un pilote appelle WdfRequestStopAcknowledge avec Requeue défini sur TRUE, il doit précédemment appeler WdfRequestUnmarkCancelable.
L’exemple de code suivant est une fonction de rappel EvtIoStop qui vérifie si une demande reçue est annulable et, le cas échéant, appelle WdfRequestUnmarkCancelable. Si WdfRequestUnmarkCancelable retourne STATUS_CANCELLED, l’exemple est simplement retourné, car la fonction de rappel EvtRequestCancel du pilote gère la demande. Sinon, l’exemple appelle WdfRequestStopAcknowledge et spécifie TRUE afin que l’infrastructure requeue la requête lorsque l’appareil sous-jacent revient à son état de travail (D0).
VOID
MyEvtIoStop(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN ULONG ActionFlags
)
{
NTSTATUS status;
// TODO: Take steps here to suspend and, if necessary, roll back any processing that has already occurred on this request
if (ActionFlags & WdfRequestStopRequestCancelable) {
status = WdfRequestUnmarkCancelable(Request);
if (status == STATUS_CANCELLED) {
return;
}
}
// Inform framework that driver is postponing processing, cause framework to redeliver request when device returns to D0
WdfRequestStopAcknowledge(Request, TRUE);
}
En règle générale, si un pilote appelle WdfRequestStopAcknowledge avec Requeue défini sur FALSE, la requête est annulée.
L’exemple de code suivant est une fonction de rappel EvtIoStop qui appelle WdfRequestStopAcknowledge et spécifie FALSE afin que l’infrastructure appelle la fonction de rappel EvtIoResume du pilote, où le pilote reprend le traitement de la demande.
Vous pouvez utiliser du code comme celui-ci s’il est acceptable d’arrêter le traitement d’une requête spécifique et de la poursuivre ultérieurement, plutôt que d’avoir la requête redélivée et de redémarrer le traitement depuis le début.
VOID
MyEvtIoStop(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN ULONG ActionFlags
)
{
//TODO: Take steps here to suspend processing of the request so it can be resumed when power returns
// Acknowledge the stop, but leave the request under driver's ownership.
// Provide a corresponding EvtIoResume handler to resume processing when power returns
WdfRequestStopAcknowledge(Request, FALSE);
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| Version KMDF minimale | 1.0 |
| Version UMDF minimale | 2.0 |
| En-tête | wdfrequest.h (include Wdf.h) |
| Bibliothèque | Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Règles de conformité DDI | DeferredRequestCompleted(kmdf), DriverCreate(kmdf), EvtIoStopCancel(kmdf), EvtIoStopCompleteOrStopAck(kmdf),EvtIoStopResume(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), StopAckWithinEvtIoStop(kmdf) |