WdfRequestStopAcknowledge-Funktion (wdfrequest.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfRequestStopAcknowledge-Methode informiert das Framework darüber, dass der Treiber die Verarbeitung einer angegebenen E/A-Anforderung beendet hat.

Syntax

void WdfRequestStopAcknowledge(
  [in] WDFREQUEST Request,
  [in] BOOLEAN    Requeue
);

Parameter

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt.

[in] Requeue

Ein boolescher Wert, der bei TRUE dazu führt, dass das Framework die Anforderung erneut in die Warteschlange eingibt, sodass das Framework sie erneut an den Treiber übermittelt. Bei FALSE stellt das Framework die Anforderung nicht erneut zurück. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

Keine

Bemerkungen

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Wenn ein Treiber eine EvtIoStop-Rückruffunktion für eine E/A-Warteschlange registriert, ruft das Framework sie auf, wenn das der Warteschlange zugrunde liegende Gerät seinen Arbeitszustand (D0) verlässt. Das Framework ruft die EvtIoStop-Rückruffunktion für jede E/A-Anforderung auf, die der Treiber nicht abgeschlossen hat, einschließlich Anforderungen, die der Treiber besitzt und die er an ein E/A-Ziel weitergeleitet hat. Der Treiber muss die Verarbeitung jeder Anforderung abschließen, abbrechen oder verschieben, indem er eine der folgenden Schritte ausführt:

Wenn der Treiber besitzer der Anforderung ist, kann er WdfRequestComplete aufrufen, um die Anforderung abzuschließen oder abzubrechen.
Wenn der Treiber die Anforderung an ein E/A-Ziel weitergeleitet hat, kann er WdfRequestCancelSentRequest aufrufen, um zu versuchen, die Anforderung abzubrechen.
Wenn der Treiber die Verarbeitung der Anforderung verschiebt, muss er WdfRequestStopAcknowledge aufrufen.

Wenn Ihr Treiber WdfRequestStopAcknowledge aufruft, muss er diese Methode innerhalb seiner EvtIoStop-Rückruffunktion aufrufen.

Das Framework erlaubt es dem Gerät nicht, seinen Arbeitszustand (D0) zu verlassen, bis der Treiber jede Anforderung abgeschlossen, abgebrochen oder verschoben hat, die eine EvtIoStop-Rückruffunktion empfängt . Möglicherweise kann diese Untätigkeit verhindern, dass ein System in seinen Ruhezustand oder einen anderen niedrigen Systemleistungszustand wechselt.

Wenn die EvtIoStop-Rückruffunktion eines Treibers WdfRequestStopAcknowledge aufruft, kann der Requeue-Parameter auf TRUE oder FALSE festgelegt werden:

Das Festlegen von Requeue auf TRUE führt dazu, dass das Framework die Anforderung wieder in die E/A-Warteschlange zurückgibt.
Wenn das zugrunde liegende Gerät in seinen Arbeitszustand (D0) zurückkehrt, sendet das Framework die Anforderung an den Treiber weiter.
Das Festlegen von Requeue auf FALSE führt dazu, dass das Framework die Anforderung nicht erneut quescht. Wenn der Treiber im Besitz der Anforderung ist, verbleibt der Besitz beim Treiber. Wenn der Treiber die Anforderung weitergeleitet hat, ist der Fahrer für die Bearbeitung der Anforderung verantwortlich, wenn sie abgeschlossen ist. Der Treiber muss die E/A-Verarbeitung beenden, die Hardwarezugriff erfordert.
Wenn das zugrunde liegende Gerät in den Funktionszustand (D0) zurückkehrt, ruft das Framework die Rückruffunktion EvtIoResume des Treibers auf, damit der Treiber die Verarbeitung der Anforderung fortsetzen kann.

Wenn der Treiber zuvor WdfRequestMarkCancelable oder WdfRequestMarkCancelableEx aufgerufen hatte, muss er WdfRequestUnmarkCancelable aufrufen, bevor WdfRequestStopAcknowledge mit Requeue auf TRUE festgelegt ist.

Vor dem Aufrufen von WdfRequestStopAcknowledge muss die EvtIoStop-Rückruffunktion des Treibers die gesamte Verarbeitung der E/A-Anforderung beenden, die den Zugriff auf das zugrunde liegende Gerät erfordert, da das Gerät in einen Energiesparzustand versetzt wird.

Weitere Informationen zur WdfRequestStopAcknowledge-Methode finden Sie unter Verwenden Power-Managed E/A-Warteschlangen.

Beispiele

Wenn ein Treiber WdfRequestStopAcknowledge aufruft und Requeue auf TRUE festgelegt ist, muss er zuvor WdfRequestUnmarkCancelable aufrufen.

Im folgenden Codebeispiel handelt es sich um eine EvtIoStop-Rückruffunktion , die überprüft, ob eine empfangene Anforderung abgebrochen werden kann, und wenn dies der Grund ist, WdfRequestUnmarkCancelable aufruft. Wenn WdfRequestUnmarkCancelable STATUS_CANCELLED zurückgibt, wird im Beispiel einfach zurückgegeben, da die Rückruffunktion EvtRequestCancel des Treibers die Anforderung verarbeitet. Andernfalls ruft das Beispiel WdfRequestStopAcknowledge auf und gibt TRUE an, sodass das Framework die Anforderung erneut ausgibt, wenn das zugrunde liegende Gerät in seinen Arbeitszustand (D0) zurückkehrt.

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);
}

Wenn ein Treiber WdfRequestStopAcknowledge aufruft und Requeue auf FALSE festgelegt ist, kann die Anforderung in der Regel abgebrochen werden.

Das folgende Codebeispiel ist eine EvtIoStop-Rückruffunktion , die WdfRequestStopAcknowledge aufruft und FALSE angibt, sodass das Framework schließlich die EvtIoResume-Rückruffunktion des Treibers aufruft, wobei der Treiber die Verarbeitung der Anforderung fortsetzen kann.

Sie können code wie diesen verwenden, wenn es akzeptabel ist, die Verarbeitung einer bestimmten Anforderung anzuhalten und später fortzusetzen, anstatt die Anforderung von Anfang anzuen und neu zu starten.

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);
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfrequest.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), EvtIoStopCancel(kmdf), EvtIoStopCompleteOrStopAck(kmdf), EvtIoStopResume(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), StopAckWithinEvtIoStop(kmdf)

Weitere Informationen

EvtIoStop

EvtRequestCancel

WdfRequestComplete

Freigeben über