WdfRequestCreate-Funktion (wdfrequest.h)
[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 |
|---|---|
|
Ein Eingabeparameter ist ungültig. |
|
Es sind nicht genügend Systemressourcen vorhanden, um den Vorgang abzuschließen. |
|
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) |