WdfRequestReuse-Funktion (wdfrequest.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfRequestReuse-Methode initialisiert ein Frameworkanforderungsobjekt neu, sodass es wiederverwendet werden kann.

Syntax

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

Parameter

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt.

[in] ReuseParams

Ein Zeiger auf eine aufruferseitig zugeordnete 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 eine IRP in der WDF_REQUEST_REUSE_PARAMS-Struktur bereitgestellt, aber das angegebene Anforderungsobjekt wurde nicht von WdfRequestCreateFromIrp abgerufen.

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

Hinweise

Ein frameworkbasierter Treiber kann Frameworkanforderungsobjekte wiederverwenden, die er durch vorherige Aufrufe von WdfRequestCreate oder WdfRequestCreateFromIrp erstellt hat. Treiber können auch Anforderungsobjekte wiederverwenden, die sie aus dem Framework erhalten haben, aber sie können das WDF_REQUEST_REUSE_SET_NEW_IRP-Flag für diese Anforderungsobjekte nicht festlegen.

Hinweis

Treiber sollten bei der Wiederverwendung von Anforderungsobjekten, die vom Framework empfangen wurden, vorsichtig sein. Durch die Wiederverwendung einer solchen Anforderung wird das Abbruchflag des zugrunde liegenden IRP zurückgesetzt und kann verhindern, dass ein aufrufender Treiber die Anforderung abbricht.

Ein Treiber kann ein Anforderungsobjekt wiederverwenden, nachdem die ursprüngliche Anforderung abgeschlossen wurde. Nachdem ein Treiber WdfRequestReuse aufgerufen hat, muss der Inhalt der Anforderung neu 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 WdfRequestReuse aufgerufen wurde.

Weitere Informationen zu WdfRequestReuse finden Sie unter Wiederverwenden von Framework-Anforderungsobjekten.

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