WdfRequestCreate-Funktion (wdfrequest.h)

Artikel
02/29/2024

[Gilt für KMDF und UMDF]

Die WdfRequestCreate-Methode erstellt ein leeres Frameworkanforderungsobjekt.

Syntax

NTSTATUS WdfRequestCreate(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in, optional] WDFIOTARGET            IoTarget,
  [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, optional] IoTarget

Ein Handle für ein Framework-E/A-Zielobjekt. Dieser Parameter ist optional und kann NULL sein. Wenn nicht NULL, überprüft WdfRequestCreate , ob der Treiber die Anforderung schließlich an das angegebene E/A-Ziel senden kann.

[out] Request

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

Rückgabewert

WdfRequestCreate 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_INSUFFICIENT_RESOURCES	Es sind nicht genügend Systemressourcen vorhanden, um den Vorgang abzuschließen.
STATUS_REQUEST_NOT_ACCEPTED	Das Array der E/A-Stapelspeicherorte der Anforderung ist nicht groß genug, damit der Treiber die Anforderung an das angegebene E/A-Ziel senden kann.

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

Ein frameworkbasierter Treiber kann WdfRequestCreate aufrufen, um eine neue Anforderung zu erstellen, die der Treiber anschließend zur Initialisierung an andere Frameworkfunktionen übergibt. Beispielsweise kann ein Treiber für ein USB-Gerät WdfUsbTargetPipeFormatRequestForRead aufrufen, um eine neue Leseanforderung zu formatieren.

Ein frameworkbasierter Treiber, der mit WDM-Treibern kommuniziert, kann den Inhalt einer Anforderung angeben, indem WdfRequestCreateFromIrp aufgerufen wird.

Wenn ein Treiber WdfRequestCreate aufruft, um ein Anforderungsobjekt zu erstellen, darf er nicht WdfRequestComplete für das Anforderungsobjekt aufrufen. Stattdessen muss der Treiber WdfObjectDelete aufrufen, wenn er die Verwendung des Anforderungsobjekts abgeschlossen hat. Weitere Informationen finden Sie unter Abschließen von E/A-Anforderungen.

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 Aufrufen von WdfRequestCreate finden Sie unter Erstellen von Framework-Anforderungsobjekten.

Beispiele

Im folgenden Codebeispiel wird ein E/A-Zielobjekt erstellt, eine WDF_OBJECT_ATTRIBUTES-Struktur initialisiert und WdfRequestCreate aufgerufen. Das übergeordnete Objekt des neuen Anforderungsobjekts ist das E/A-Zielobjekt.

WDF_OBJECT_ATTRIBUTES  attributes;
WDFREQUEST newRequest;
WDFIOTARGET ioTarget;
...
status = WdfIoTargetCreate(
                           Device,
                           WDF_NO_OBJECT_ATTRIBUTES,
                           &ioTarget
                           );
  ...
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = ioTarget;

status = WdfRequestCreate(
                          &attributes,
                          ioTarget,
                          &newRequest
                          );

if (!NT_SUCCESS(status)) {
    return 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), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReqDelete(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting2(kmdf)