WdfIoTargetFormatRequestForWrite-Funktion (wdfiotarget.h)

2025-03-22

[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
);

Die Parameter

[in] IoTarget

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

[in] Request

Ein Handle zu einem Framework-Anforderungsobjekt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] InputBuffer

Ein Handle für ein Framework-Speicherobjekt. 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-werden. Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] InputBufferOffset

Ein Zeiger auf eine vom Aufrufer zugewiesene WDFMEMORY_OFFSET Struktur, die optionale Byteoffset- und Längenwerte bereitstellt. Das Framework verwendet diese Werte, um die Anfangsadresse und -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 ist die 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ächste niedrigere 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 in der Parameters.Write.DeviceOffset Mitglied 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 E/A-Anforderungspaket (IRP-), das der parameter Request darstellt, stellt nicht genügend IO_STACK_LOCATION Strukturen bereit, damit der Treiber die Anforderung weiterleiten kann.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

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 erhalten hat, oder Sie können eine neue Anforderung erstellen und senden. In beiden Fällen erfordert das Framework ein Anforderungsobjekt und einen Pufferraum.

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

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

Weitere Informationen zum Weiterleiten einer E/A-Anforderung finden Sie unter Weiterleitung 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 WdfIoTargetFormatRequestForWrite Method's Request Parameter an.
Rufen Sie WdfRequestCreate auf, um mindestens ein Anforderungsobjekt vorab zu verwenden. Sie können diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuseaufrufen. Die EvtDriverDeviceAdd Rückruffunktion Ihres Treibers kann Anforderungsobjekte für ein Gerät vorab allocatieren.
Stellen Sie Pufferraum bereit, und geben Sie den Handle des Puffers für den WdfIoTargetFormatRequestForWrite InputBuffer Parameter der Methode an.
Der Treiber muss diesen Pufferspeicher als WDFMEMORY-Handle für vom Framework verwalteten Speicher 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, muss der Treiber die empfangene E/A-Anforderung erst abschließen, nachdem der Treiber das neue anforderungsobjekt vom Treiber gelöscht, wiederverwendet oder neu erstellt hat. (WdfIoTargetFormatRequestForWrite erhöht die Referenzanzahl des Speicherobjekts. Beim Löschen, Erneuten Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts erhöht.)

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

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

Mehrere Aufrufe an WdfIoTargetFormatRequestForWrite, die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuordnungen. Um die Chance zu verringern, dass WdfRequestCreate- STATUS_INSUFFICIENT_RESOURCES zurückgibt, kann die EvtDriverDeviceAdd- Rückruffunktion WdfRequestCreate aufrufen, um mindestens ein Anforderungsobjekt für ein Gerät vorab bereitzustellen. Der Treiber kann anschließend wiederverwendet werden (aufruf WdfRequestReuse), neu formatieren (Aufrufen WdfIoTargetFormatRequestForWrite) und erneut senden (Aufruf WdfRequestSend) jedes Anforderungsobjekt ohne Risiko eines STATUS_INSUFFICIENT_RESOURCES Rückgabewerts von einem späteren Aufruf an WdfRequestCreate. Alle nachfolgenden Aufrufe von WdfIoTargetFormatRequestForWrite für das wiederverwendete Anforderungsobjekt geben STATUS_SUCCESS zurück, wenn Parameterwerte nicht geändert werden. (Wenn der Treiber nicht jedes Mal dieselbe Anforderungsformatierungsmethode aufruft, werden möglicherweise zusätzliche Ressourcen zugeordnet.)

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

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

Weitere Informationen zu E/A-Zielen finden Sie unter Using I/O Targets.

Beispiele

Im folgenden Codebeispiel wird ein Framework-Speicherobjekt 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
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	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)