WdfRequestCreate-Funktion (wdfrequest.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfRequestCreate-Methode erstellt ein leeres Framework-Anforderungsobjekt.

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 zu einem Framework-E/A-Zielobjekt. Dieser Parameter ist optional und kann NULL-werden. Wenn nicht-NULL-, WdfRequestCreate überprüft, ob der Treiber die Anforderung schließlich an das angegebene E/A-Ziel senden kann.

[out] Request

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

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Bemerkungen

Ein frameworkbasierter Treiber kann WdfRequestCreate aufrufen, um eine neue Anforderung zu erstellen, die der Treiber anschließend für die 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 WdfRequestCreateFromIrpaufgerufen 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 das Anforderungsobjekt verwendet hat. Weitere Informationen finden Sie unter Abschließen von E/A-Anforderungen.

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 Aufrufen WdfRequestCreatefinden Sie unter Creating Framework Request Objects.

Beispiele

Im folgenden Codebeispiel wird ein E/A-Zielobjekt erstellt, eine WDF_OBJECT_ATTRIBUTES Struktur initialisiert und WdfRequestCreateaufgerufen. 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-	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), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReqDelete(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting2(kmdf)