WdfRequestReuse-Funktion (wdfrequest.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Mit der WdfRequestReuse Methode wird ein Framework-Anforderungsobjekt neu initialisiert, sodass es wiederverwendet werden kann.

Syntax

NTSTATUS WdfRequestReuse(
  [in] WDFREQUEST                Request,
  [in] PWDF_REQUEST_REUSE_PARAMS ReuseParams
);

Parameter

[in] Request

Ein Handle zu einem Framework-Anforderungsobjekt.

[in] ReuseParams

Ein Zeiger auf eine aufrufergeteilte WDF_REQUEST_REUSE_PARAMS Struktur.

Rückgabewert

WdfRequestReuse gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein Eingabeparameter ist ungültig.
STATUS_WDF_REQUEST_INVALID_STATE	Der Treiber hat ein IRP in der WDF_REQUEST_REUSE_PARAMS-Struktur bereitgestellt, das angegebene Anforderungsobjekt wurde jedoch nicht aus WdfRequestCreateFromIrpabgerufen.

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

Bemerkungen

Ein frameworkbasierter Treiber kann Frameworkanforderungsobjekte wiederverwenden, die er durch vorherige Aufrufe von WdfRequestCreate oder WdfRequestCreateFromIrperstellt hat. Treiber können auch Anforderungsobjekte wiederverwenden, die sie vom Frameworkerhalten haben, aber sie können das WDF_REQUEST_REUSE_SET_NEW_IRP Flag für diese Anforderungsobjekte nicht festlegen.

Anmerkung

Treiber sollten beim erneuten Verwenden von Anforderungsobjekten, die vom Framework empfangen wurden, Vorsicht walten lassen. Durch die erneute Nutzung einer solchen Anforderung wird die Abbruchkennzeichnung des zugrunde liegenden IRP zurückgesetzt und möglicherweise verhindert, dass ein Anruftreiber die Anforderung abbricht.

Ein Treiber kann ein Anforderungsobjekt wiederverwenden, nachdem die ursprüngliche Anforderung abgeschlossen wurde. Nachdem ein Treiber WdfRequestReuseaufgerufen hat, muss der Inhalt der Anforderung erneut initialisiert werden. Der Treiber kann einige Anforderungsparameter in der WDF_REQUEST_REUSE_PARAMS Struktur angeben.

Wenn die wiederverwendete Anforderung über eine CompletionRoutine Rückruffunktion verfügen soll, muss der Treiber WdfRequestSetCompletionRoutine aufrufen, nachdem WdfRequestReuseaufgerufen wurde.

Weitere Informationen zu WdfRequestReuse-finden Sie unter Reusing Framework Request Objects.

Beispiele

Das folgende Codebeispiel ist Teil einer CompletionRoutine- Rückruffunktion, die WdfRequestReuse- aufruft, damit der Treiber eine vom Treiber zugewiesene Anforderung wiederverwenden kann.

VOID
MyRequestCompletionRoutine(
    IN WDFREQUEST  Request,
    IN WDFIOTARGET  Target,
    PWDF_REQUEST_COMPLETION_PARAMS  CompletionParams,
    IN WDFCONTEXT  Context
    )
{
    WDF_REQUEST_REUSE_PARAMS  params;
    NTSTATUS  status;
...
    WDF_REQUEST_REUSE_PARAMS_INIT(
                                  &params,
                                  WDF_REQUEST_REUSE_NO_FLAGS,
                                  STATUS_SUCCESS
                                  );

    status = WdfRequestReuse(
                             Request,
                             &params
                             );
    ASSERT(NT_SUCCESS(status));
...
}

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	DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql (kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReqSendFail(kmdf)