WdfRequestStopAcknowledge-Funktion (wdfrequest.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfRequestStopAcknowledge Methode informiert das Framework, 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 zu einem Framework-Anforderungsobjekt.

[in] Requeue

Ein boolescher Wert, der, wenn TRUE, bewirkt, dass das Framework die Anforderung in der Warteschlange erneut anfordert, sodass es vom Framework erneut an den Treiber übergeben wird. Wenn FALSE, wird die Anforderung vom Framework nicht erneut angefordert. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

Nichts

Bemerkungen

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Wenn ein Treiber eine EvtIoStop- Rückruffunktion für eine E/A-Warteschlange registriert, ruft das Framework sie auf, wenn das zugrunde liegende Gerät der Warteschlange den 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 diejenigen, die er an ein E/A-Ziel weitergeleitet hat. Der Treiber muss die Verarbeitung jeder Anforderung abschließen, abbrechen oder verschieben, indem eine der folgenden Aktionen ausgeführt wird:

Wenn der Treiber die Anforderung besitzt, 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 WdfRequestStopAcknowledgeaufrufen.

Wenn Ihr Treiber WdfRequestStopAcknowledgeaufruft, muss diese Methode innerhalb der EvtIoStop- Rückruffunktion aufgerufen werden.

Das Framework lässt es dem Gerät nicht zu, den Arbeitszustand (D0) zu verlassen, bis der Treiber alle Anforderungen abgeschlossen, abgebrochen oder verschoben hat, die eine EvtIoStop- Rückruffunktion empfängt. Potenziell kann diese Inaktion verhindern, dass ein System in den Ruhezustand oder einen anderen Energiesparmodus wechselt.

Wenn ein Treiber EvtIoStop- Rückruffunktion WdfRequestStopAcknowledge-aufruft, kann er den parameter Requeue auf TRUE oder FALSE-festlegen:

Wenn auf TRUE festgelegt wird, wird die Anforderung vom Framework wieder in die E/A-Warteschlange eingefügt.
Wenn das zugrunde liegende Gerät in den Arbeitszustand (D0) zurückkehrt, sendet das Framework die Anforderung an den Treiber neu.
Wenn sie auf FALSE zurücksetzen bewirkt, dass das Framework die Anforderung nicht erneut anfordert. Wenn der Treiber besitzer der Anforderung ist, verbleibt der Besitz beim Treiber. Wenn der Treiber die Anforderung weitergeleitet hat, ist der Treiber für die Verarbeitung der Anforderung verantwortlich, wenn er abgeschlossen ist. Der Treiber muss alle E/A-Verarbeitungen beenden, die hardwarebasierten Zugriff erfordern.
Wenn das zugrunde liegende Gerät in den Arbeitszustand (D0) zurückkehrt, ruft das Framework die EvtIoResume Rückruffunktion des Treibers auf, damit der Treiber die Verarbeitung der Anforderung fortsetzen kann.

Wenn der Treiber zuvor WdfRequestMarkCancelable oder WdfRequestMarkCancelableEx-aufgerufen hat, muss er WdfRequestUnmarkCancelable- aufrufen, bevor WdfRequestStopAcknowledge mit Requeue auf TRUEfestgelegt wird.

Vor dem Aufrufen WdfRequestStopAcknowledgemuss die EvtIoStop- Rückruffunktion 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 wechselt.

Weitere Informationen zur WdfRequestStopAcknowledge--Methode finden Sie unter Using Power-Managed I/O Queues.

Beispiele

Wenn ein Treiber WdfRequestStopAcknowledge aufruft, wobei Requeue auf TRUE-festgelegt ist, muss er zuvor WdfRequestUnmarkCancelableaufrufen.

Das folgende Codebeispiel ist eine EvtIoStop- Rückruffunktion, die überprüft, ob eine empfangene Anforderung abgebrochen werden kann, und ruft in diesem Beispiel WdfRequestUnmarkCancelableauf. Wenn WdfRequestUnmarkCancelable STATUS_CANCELLED zurückgibt, wird das Beispiel nur zurückgegeben, da die EvtRequestCancel Rückruffunktion die Anforderung verarbeitet. Andernfalls ruft das Beispiel WdfRequestStopAcknowledge auf und gibt TRUE- an, sodass das Framework die Anforderung erneut abfragt, wenn das zugrunde liegende Gerät in den 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 in der Regel WdfRequestStopAcknowledge aufruft, wobei Requeue auf FALSE-festgelegt ist, wird die Anforderung abgebrochen.

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

Sie können Code wie diesen verwenden, wenn die Verarbeitung einer bestimmten Anforderung angehalten und später fortgesetzt werden kann, anstatt die Anforderung von Anfang an neu zu bearbeiten 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-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfrequest.h (include Wdf.h)
Library	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)

Siehe auch

EvtIoStop

EvtRequestCancel

WdfRequestComplete-

Freigeben über