WdfRequestCreateFromIrp-Funktion (wdfrequest.h)

Artikel
02/27/2024

[Gilt nur für KMDF]

Die WdfRequestCreateFromIrp-Methode erstellt ein Frameworkanforderungsobjekt aus einem angegebenen WDM-IRP.

Syntax

NTSTATUS WdfRequestCreateFromIrp(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in]           PIRP                   Irp,
  [in]           BOOLEAN                RequestFreesIrp,
  [out]          WDFREQUEST             *Request
);

Parameter

[in, optional] RequestAttributes

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_OBJECT_ATTRIBUTES Struktur, die Objektattribute für das Anforderungsobjekt angibt. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[in] Irp

Ein Zeiger auf eine IRP-Struktur , die ein WDM-E/A-Anforderungspaket enthält.

[in] RequestFreesIrp

Ein boolescher Wert, der bei TRUE angibt, dass das Framework die IRP entfernt, wenn das Anforderungshandle zerstört wird. Wenn FALSE, muss der Treiber IoFreeIrp aufrufen, um die IRP zu entfernen, und zwar mit den Schritten, die im folgenden Abschnitt Beispiele veranschaulicht werden.

[out] Request

Ein Zeiger auf einen Speicherort, der ein Handle für ein Frameworkanforderungsobjekt empfängt.

Rückgabewert

WdfRequestCreateFromIrp gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Eine Liste mit zusätzlichen Rückgabewerten finden Sie unter Fehler beim Erstellen von Frameworkobjekten.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Hinweise

In der Regel rufen frameworkbasierte Treiber WdfRequestCreateFromIrp nur auf, wenn sie WDM-IRPs in einer WDM-Dispatchroutine empfangen und die Anforderungen dann an Framework-E/A-Ziele weiterleiten.

Wenn ein Treiber WdfRequestCreateFromIrp aufruft, um ein Anforderungsobjekt zu erstellen, darf er WdfRequestComplete nicht für das Anforderungsobjekt aufrufen. Stattdessen muss der Treiber WdfObjectDelete aufrufen, wenn er die Verwendung des Anforderungsobjekts abgeschlossen hat.

Darüber hinaus darf der Treiber WdfRequestRetrieveOutputMemory, WdfRequestRetrieveOutputBuffer, WdfRequestRetrieveInputBuffer oder WdfRequestRetrieveInputMemory nicht mit dem neuen Anforderungsobjekt aufrufen.

Standardmäßig ist das übergeordnete Element des neuen Anforderungsobjekts das Frameworktreiberobjekt, das von der WdfDriverCreate-Methode erstellt wurde. Sie können das ParentObject-Element der WDF_OBJECT_ATTRIBUTES-Struktur verwenden, um ein anderes übergeordnetes Element anzugeben. Das Framework löscht das Anforderungsobjekt, wenn es das übergeordnete Objekt löscht. Wenn Ihr Treiber das übergeordnete Standardobjekt nicht ändert, sollte der Treiber das Anforderungsobjekt löschen, wenn er das Objekt verwendet hat. Andernfalls bleibt das Anforderungsobjekt so lange erhalten, bis der E/A-Manager Ihren Treiber entladen hat.

Weitere Informationen zum Erstellen von Frameworkanforderungsobjekten finden Sie unter Erstellen von Framework-Anforderungsobjekten.

Frameworkbasierte Treiber dürfen nicht das Tail.Overlay.DriverContext-Member der IRP-Struktur verwenden, da das Framework diesen Member verwendet.

Beispiele

Beispiel 1

Im folgenden Codebeispiel wird ein Frameworkanforderungsobjekt aus einem angegebenen WDM-IRP erstellt und anschließend gelöscht. In diesem Beispiel wird der RequestFreesIrp-Parameter auf TRUE festgelegt, sodass das Framework den IRP entfernt, wenn das Anforderungshandle zerstört wird.

WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 TRUE,
                                 &request
                                 );
...
//Deletion
WdfObjectDelete(request);

Beispiel 2

Im folgenden Codebeispiel wird auch ein Frameworkanforderungsobjekt aus einem angegebenen WDM-IRP erstellt und anschließend gelöscht. In diesem Beispiel wird der RequestFreesIrp-Parameter auf FALSE festgelegt, sodass der Treiber IoFreeIrp aufrufen muss, um den IRP zu entfernen. Alle Funktionsaufrufe im Beispiel sind erforderlich.

WDF_REQUEST_REUSE_PARAMS params;
WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 FALSE,
                                 &request
                                 );
...
//Deletion
WDF_REQUEST_REUSE_PARAMS_INIT(
                              &params,
                              WDF_REQUEST_REUSE_NO_FLAGS,
                              STATUS_SUCCESS
                              );
WDF_REQUEST_REUSE_PARAMS_SET_NEW_IRP(
                                     &params,
                                     NULL
                                     );
status = WdfRequestReuse(
                         request,
                         &params
                         );
ASSERT(NT_SUCCESS(status));
IoFreeIrp(irp);
WdfObjectDelete(request);

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfrequest.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionierung der Frameworkbibliothek.)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)