WdfRequestCreateFromIrp-Funktion (wdfrequest.h)

Artikel
02/07/2025

[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, wenn TRUE, angibt, dass das Framework das IRP entfernt, wenn der Anforderungshandle zerstört wird. Wenn FALSE-, muss der Treiber IoFreeIrp- aufrufen, um das IRP zu entfernen, indem die schritte verwendet werden, die im folgenden Abschnitt "Beispiele" veranschaulicht werden.

[out] Request

Ein Zeiger auf eine Position, die ein Handle zu einem Framework-Anforderungsobjekt 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 Framework Object Creation Errors.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Bemerkungen

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

Wenn ein Treiber WdfRequestCreateFromIrp- aufruft, um ein Anforderungsobjekt zu erstellen, darf er nicht WdfRequestComplete- für das Anforderungsobjekt aufrufen. Stattdessen muss der Treiber WdfObjectDelete aufrufen, wenn er das Anforderungsobjekt verwendet hat.

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

Standardmäßig ist das übergeordnete Objekt des neuen Anforderungsobjekts das Frameworktreiberobjekt, das vom 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 die Verwendung des Objekts abgeschlossen hat. andernfalls bleibt das Anforderungsobjekt erhalten, bis der E/A-Manager den Treiber entlädt.

Weitere Informationen zum Erstellen von Framework-Anforderungsobjekten finden Sie unter Creating Framework Request Objects.

Frameworkbasierte Treiber dürfen nicht die Tail.Overlay.DriverContext Member der IRP--Struktur verwenden, da das Framework dieses 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 parameter RequestFreesIrp auf TRUEfestgelegt, sodass das Framework das IRP entfernt, wenn der 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 parameter RequestFreesIrp auf FALSEfestgelegt, sodass der Treiber IoFreeIrp- aufrufen muss, um das 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-	Universal
Minimale KMDF-Version	1.0
Header-	wdfrequest.h (include Wdf.h)
Library	Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.)
IRQL-	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)