WdfIoTargetFormatRequestForWrite-Funktion (wdfiotarget.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfIoTargetFormatRequestForWrite-Methode erstellt eine Schreibanforderung für ein E/A-Ziel, sendet die Anforderung jedoch nicht.

Syntax

NTSTATUS WdfIoTargetFormatRequestForWrite(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         InputBuffer,
  [in, optional] PWDFMEMORY_OFFSET InputBufferOffset,
  [in, optional] PLONGLONG         DeviceOffset
);

Parameter

[in] IoTarget

Ein Handle für ein lokales oder Remote-E/A-Zielobjekt, das aus einem vorherigen Aufruf von WdfDeviceGetIoTarget oder WdfIoTargetCreate oder von einer Methode abgerufen wurde, die ein spezialisiertes E/A-Ziel bereitstellt.

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] InputBuffer

Ein Handle für ein Frameworkspeicherobjekt. Dieses Objekt stellt einen Puffer dar, der Daten enthält, die an das E/A-Ziel gesendet werden. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt hinweise.

[in, optional] InputBufferOffset

Ein Zeiger auf eine aufruferseitig zugeordnete WDFMEMORY_OFFSET-Struktur , die optionale Byteoffset- und Längenwerte bereitstellt. Das Framework verwendet diese Werte, um die Anfangsadresse und die Länge innerhalb des Eingabepuffers für die Datenübertragung zu bestimmen. Wenn dieser Zeiger NULL ist, beginnt die Datenübertragung am Anfang des Eingabepuffers, und die Übertragungsgröße entspricht der Puffergröße.

[in, optional] DeviceOffset

Ein Zeiger auf eine Position, die einen Startoffset für die Übertragung angibt. Das E/A-Ziel (d. h. der nächstniedrige Treiber) definiert, wie dieser Wert verwendet wird. Beispielsweise können die Treiber im Treiberstapel eines Datenträgers einen Offset vom Anfang des Datenträgers angeben. Das E/A-Ziel ruft diese Informationen im Parameters.Write.DeviceOffset-Element der WDF_REQUEST_PARAMETERS-Struktur der Anforderung ab. Dieser Zeiger ist optional. Die meisten Treiber legen diesen Zeiger auf NULL fest.

Rückgabewert

WdfIoTargetFormatRequestForWrite 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 ungültiger Parameter wurde erkannt.
STATUS_INVALID_DEVICE_REQUEST	Die Übertragungslänge war größer als die Pufferlänge, oder die E/A-Anforderung wurde bereits an ein E/A-Ziel in die Warteschlange gestellt.
STATUS_INSUFFICIENT_RESOURCES	Das Framework konnte keine Systemressourcen (in der Regel Arbeitsspeicher) zuordnen.
STATUS_REQUEST_NOT_ACCEPTED	Das vom Request-Parameter dargestellte E/A-Anforderungspaket (IRP) bietet nicht genügend IO_STACK_LOCATION Strukturen, damit der Treiber die Anforderung weiterleiten kann.

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

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Verwenden Sie die WdfIoTargetFormatRequestForWrite-Methode gefolgt von der WdfRequestSend-Methode , um Schreibanforderungen entweder synchron oder asynchron zu senden. Alternativ können Sie die WdfIoTargetSendWriteSynchronously-Methode verwenden, um Schreibanforderungen synchron zu senden.

Sie können eine E/A-Anforderung weiterleiten, die Ihr Treiber in einer E/A-Warteschlange empfangen hat, oder Sie können eine neue Anforderung erstellen und senden. In beiden Fällen erfordert das Framework ein Anforderungsobjekt und etwas Pufferspeicherplatz.

So leiten Sie eine E/A-Anforderung weiter, die Ihr Treiber in einer E/A-Warteschlange empfangen hat:

Geben Sie das Handle der empfangenen Anforderung für den Request-Parameter der WdfIoTargetFormatRequestForWrite-Methode an.
Verwenden Sie den Eingabepuffer der empfangenen Anforderung für den InputBuffer-Parameter der WdfIoTargetFormatRequestForWrite-Methode.
Der Treiber muss WdfRequestRetrieveInputMemory aufrufen, um ein Handle für ein Frameworkspeicherobjekt abzurufen, das den Eingabepuffer der Anforderung darstellt, und dieses Handle als Wert für InputBuffer verwenden.

Weitere Informationen zum Weiterleiten einer E/A-Anforderung finden Sie unter Weiterleiten von E/A-Anforderungen.

Treiber teilen empfangene E/A-Anforderungen häufig in kleinere Anforderungen auf, die sie an ein E/A-Ziel senden, sodass Ihr Treiber möglicherweise neue Anforderungen erstellt.

So erstellen Sie eine neue E/A-Anforderung:

Erstellen Sie ein neues Anforderungsobjekt, und geben Sie dessen Handle für den Request-Parameter der WdfIoTargetFormatRequestForWrite-Methode an.
Rufen Sie WdfRequestCreate auf , um mindestens ein Anforderungsobjekt vorab zu verwenden. Sie können diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuse aufrufen. Die Rückruffunktion EvtDriverDeviceAdd Ihres Treibers kann Anforderungsobjekte für ein Gerät vorab zuweisungen.
Geben Sie Pufferspeicher an, und geben Sie das Handle des Puffers für den InputBuffer-Parameter der WdfIoTargetFormatRequestForWrite-Methode an.
Ihr Treiber muss diesen Pufferspeicher als WDFMEMORY-Handle für vom Framework verwalteten Arbeitsspeicher angeben. Ihr Treiber kann eine der folgenden Aktionen ausführen:
- Rufen Sie WdfMemoryCreate oder WdfMemoryCreatePreallocated auf, um einen neuen Speicherpuffer zu erstellen, wenn der Treiber einen neuen Puffer an das E/A-Ziel übergeben soll.
- Rufen Sie WdfRequestRetrieveInputMemory auf, um ein Handle für das Speicherobjekt abzurufen, das den Puffer einer empfangenen E/A-Anforderung darstellt, wenn der Treiber den Inhalt dieses Puffers an das E/A-Ziel übergeben soll.
Wenn Ihr Treiber WdfRequestRetrieveInputMemory aufruft und das Speicherhandle an WdfIoTargetFormatRequestForWrite übergibt, darf der Treiber die empfangene E/A-Anforderung erst abschließen, nachdem der Treiber das neue, vom Treiber erstellte Anforderungsobjekt gelöscht, wiederverwendet oder neu erstellt hat. (WdfIoTargetFormatRequestForWrite erhöht die Referenzanzahl des Speicherobjekts. Durch das Löschen, Wiederverwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts verringert.)

Einige E/A-Ziele akzeptieren Schreibanforderungen, die über einen Puffer der Länge Null verfügen. Für solche E/A-Ziele kann Der Treiber NULL für den InputBuffer-Parameter angeben.

Nachdem ein Treiber WdfIoTargetFormatRequestForWrite zum Formatieren einer E/A-Anforderung aufgerufen hat, muss er WdfRequestSend aufrufen, um die Anforderung (synchron oder asynchron) an ein E/A-Ziel zu senden.

Mehrere Aufrufe von WdfIoTargetFormatRequestForWrite , die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuordnungen. Aus diesem Grund kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers WdfRequestCreate aufrufen, um die Chance zu verringern, dass WdfRequestCreate zurückgegeben STATUS_INSUFFICIENT_RESOURCES wird, um ein oder mehrere Anforderungsobjekte für ein Gerät vorab zu verwenden. Der Treiber kann jedes Anforderungsobjekt anschließend wiederverwenden ( WdfRequestReuse aufrufen), neu formatieren ( WdfIoTargetFormatRequestForWrite aufrufen) und erneut senden ( WdfRequestSend aufrufen), ohne einen STATUS_INSUFFICIENT_RESOURCES Rückgabewert aus einem späteren Aufruf von WdfRequestCreate zu riskieren. Alle nachfolgenden Aufrufe von WdfIoTargetFormatRequestForWrite für das wiederverwendete Anforderungsobjekt geben STATUS_SUCCESS zurück, wenn sich die Parameterwerte nicht ändern. (Wenn der Treiber nicht jedes Mal dieselbe Methode zur Anforderungsformatierung aufruft, werden möglicherweise zusätzliche Ressourcen zugeordnet.)

Informationen zum Abrufen status Informationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.

Weitere Informationen zu WdfIoTargetFormatRequestForWrite finden Sie unter Senden von E/A-Anforderungen an allgemeine E/A-Ziele.

Weitere Informationen zu E/A-Zielen finden Sie unter Verwenden von E/A-Zielen.

Beispiele

Im folgenden Codebeispiel wird ein Frameworkspeicherobjekt für den Eingabepuffer einer Schreibanforderung erstellt, die Schreibanforderung formatiert, eine CompletionRoutine-Rückruffunktion registriert und die Schreibanforderung an ein E/A-Ziel gesendet.

WDFREQUEST  request;
NTSTATUS  status;
WDFMEMORY  memory;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         DRIVER_TAG,
                         WRITE_BUF_SIZE,
                         &memory,
                         NULL
                         );

if (!NT_SUCCESS(status)) {
    return status;
}

status = WdfIoTargetFormatRequestForWrite(
                                          IoTarget,
                                          request,
                                          memory,
                                          NULL,
                                          NULL
                                          );
if (!NT_SUCCESS(status)) {
        return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyReadRequestCompletionRoutine,
                               targetInfo
                               );
if (WdfRequestSend(
                   request,
                   IoTarget,
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
        status = WdfRequestGetStatus(request);
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfiotarget.h (include Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)