Méthode IWDFIoRequest2 ::StopAcknowledge (wudfddi.h)

Article
02/27/2024

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.]

La méthode StopAcknowledge informe l’infrastructure que le pilote a cessé de traiter une demande d’E/S spécifiée.

Syntaxe

void StopAcknowledge(
  [in] BOOL Requeue
);

Paramètres

[in] Requeue

Valeur booléenne qui, si elle est TRUE, oblige l’infrastructure à mettre la demande de nouveau en file d’attente afin que l’infrastructure la remet à 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

Si un pilote inscrit une fonction de rappel IQueueCallbackIoStop ::OnIoStop 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 cette fonction de rappel pour chaque demande d’E/S que le pilote possède au moment où la file d’attente est arrêtée. 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 IWDFIoRequest ::Complete pour terminer ou annuler la demande.
Si le pilote a transféré la demande à une cible d’E/S, il peut appeler IWDFIoRequest ::CancelSentRequest pour tenter d’annuler la demande.
Si le pilote reporte le traitement de la demande, il doit appeler StopAcknowledge.

Si votre pilote appelle StopAcknowledge, il doit appeler cette méthode à partir de sa fonction de rappel IQueueCallbackIoStop ::OnIoStop .

Si le pilote n’appelle pas IWDFIoRequest ::Complete ou StopAcknowledge pour chaque requête qu’une fonction de rappel IQueueCallbackIoStop ::OnIoStop reçoit, le framework n’autorise pas l’appareil à quitter son état opérationnel (D0). 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 IQueueCallbackIoStop ::OnIoStop d’un pilote appelle StopAcknowledge, elle peut définir le paramètre Requeue sur TRUE ou FALSE :

Si vous définissez Requeue sur TRUE , l’infrastructure replace la requête dans sa file d’attente d’E/S.
Lorsque l’appareil sous-jacent revient à son état opérationnel (D0), le framework réélise la demande au pilote.
Si vous définissez Requeue sur FALSE , la propriété de la demande reste au pilote. Le pilote doit cesser d’effectuer tout traitement d’E/S nécessitant un accès matériel.
Lorsque l’appareil sous-jacent revient à son état opérationnel (D0), l’infrastructure appelle la fonction de rappel IQueueCallbackIoResume ::OnIoResume du pilote, afin que le pilote puisse continuer à traiter la demande.

Si le pilote avait précédemment appelé IWDFIoRequest ::MarkCancelable, il doit appeler IWDFIoRequest ::UnmarkCancelable avant d’appeler StopAcknowledge avec requeue défini sur TRUE.

Avant d’appeler StopAcknowledge, la fonction de rappel IQueueCallbackIoStop ::OnIoStop du pilote doit arrêter tout le traitement de la demande d’E/S qui nécessite l’accès à l’appareil sous-jacent, car l’appareil est sur le point de passer à un état de faible consommation.

Exemples

L’exemple de code suivant est une fonction de rappel IQueueCallbackIoStop ::OnIoStop qui vérifie si une requête reçue est annulable et, si elle l’est, appelle IWDFIoRequest ::UnmarkCancelable. Si IWDFIoRequest ::UnmarkCancelable retourne HRESULT_FROM_WIN32(ERROR_OPERATION_ABORTED), l’exemple retourne simplement parce que la fonction de rappel IRequestCallbackCancel ::OnCancel du pilote gère la requête. Sinon, l’exemple appelle StopAcknowledge et spécifie FALSE afin que l’infrastructure appelle la fonction de rappel IQueueCallbackIoResume ::OnIoResume du pilote.

void
CMyReadWriteQueue::OnIoStop(
    __in IWDFIoQueue*  pWdfQueue,
    __in IWDFIoRequest*  pWdfRequest,
    __in ULONG  ActionFlags
    )
{ HRESULT status;

    if (ActionFlags & WdfRequestStopRequestCancelable) {
        status = pWdfRequest->UnmarkCancelable();
        if (status == HRESULT_FROM_WIN32(ERROR_OPERATION_ABORTED)) {
        return;
        }
    }
    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    r2->StopAcknowledge(FALSE);
}

Configuration requise

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1,9
En-tête	wudfddi.h (inclure Wudfddi.h)
DLL	WUDFx.dll

Voir aussi

IQueueCallbackIoResume ::OnIoResume

IQueueCallbackIostop ::OnIostop

IWDFIoRequest2

Partager via