WdfIoTargetFormatRequestForRead-Funktion (wdfiotarget.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

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

Syntax

NTSTATUS WdfIoTargetFormatRequestForRead(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         OutputBuffer,
  [in, optional] PWDFMEMORY_OFFSET OutputBufferOffset,
  [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 von einem spezialisierten E/A-Ziel bereitgestellt wird.

[in] Request

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

[in, optional] OutputBuffer

Ein Handle für ein Frameworkspeicherobjekt. Dieses Objekt stellt einen Puffer dar, der Daten vom E/A-Ziel empfängt. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen zu diesem Parameter finden Sie im abschnitt Hinweise.

[in, optional] OutputBufferOffset

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 Ausgabepuffers für die Datenübertragung zu bestimmen. Wenn dieser Zeiger NULL ist, beginnt die Datenübertragung am Anfang des Ausgabepuffers, und die Übertragungsgröße entspricht der Puffergröße.

[in, optional] DeviceOffset

Ein Zeiger auf eine Variable, der einen Startoffset für die Übertragung angibt. Das E/A-Ziel (d. h. der nächstniedrige Treiber) definiert, wie dieser Wert verwendet werden soll. 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 Parameter.Read.DeviceOffset-Member der WDF_REQUEST_PARAMETERS Struktur der Anforderung ab. Dieser Zeiger ist optional. Die meisten Treiber legen diesen Zeiger auf NULL fest.

Rückgabewert

WdfIoTargetFormatRequestForRead 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) stellt nicht genügend IO_STACK_LOCATION Strukturen bereit, 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 WdfIoTargetFormatRequestForRead-Methode gefolgt von der WdfRequestSend-Methode , um Leseanforderungen synchron oder asynchron zu senden. Alternativ können Sie die WdfIoTargetSendReadSynchronously-Methode verwenden, um Leseanforderungen 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 etwas Pufferspeicher.

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 WdfIoTargetFormatRequestForRead-Methode an.
Verwenden Sie den Ausgabepuffer der empfangenen Anforderung für den OutputBuffer-Parameter der WdfIoTargetFormatRequestForRead-Methode.
Der Treiber muss WdfRequestRetrieveOutputMemory aufrufen, um ein Handle für ein Frameworkspeicherobjekt abzurufen, das den Ausgabepuffer der Anforderung darstellt, und dieses Handle als Wert für OutputBuffer 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 WdfIoTargetFormatRequestForRead-Methode an.
Rufen Sie WdfRequestCreate auf , um ein oder mehrere Anforderungsobjekte vorab zuzulisten. 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.
Stellen Sie Pufferraum bereit, und geben Sie das Handle des Puffers für den OutputBuffer-Parameter der WdfIoTargetFormatRequestForRead-Methode an.
Ihr Treiber muss diesen Pufferspeicher als WDFMEMORY-Handle für den 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 WdfRequestRetrieveOutputMemory 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 WdfRequestRetrieveOutputMemory aufruft und das Speicherhandle an WdfIoTargetFormatRequestForRead ü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. (WdfIoTargetFormatRequestForRead erhöht die Referenzanzahl des Speicherobjekts. Durch das Löschen, Erneutes Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Verweisanzahl des Speicherobjekts verringert.)

Einige E/A-Ziele akzeptieren Leseanforderungen, die über einen Puffer der Länge null verfügen. Für solche E/A-Ziele kann Ihr Treiber NULL für den OutputBuffer-Parameter angeben.

Nachdem ein Treiber WdfIoTargetFormatRequestForRead 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 WdfIoTargetFormatRequestForRead , die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuordnungen. Daher kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers WdfRequestCreate aufrufen, um die Möglichkeit zu verringern, dass WdfRequestCreate zurückgegeben STATUS_INSUFFICIENT_RESOURCES wird, um ein oder mehrere Anforderungsobjekte für ein Gerät vorab zuordnen. Der Treiber kann jedes Anforderungsobjekt anschließend wiederverwenden ( aufrufen WdfRequestReuse), neu formatieren (aufrufen von WdfIoTargetFormatRequestForRead) und erneut senden (aufrufen WdfRequestSend), ohne einen STATUS_INSUFFICIENT_RESOURCES Rückgabewert aus einem späteren Aufruf von WdfRequestCreate zu riskieren. Alle nachfolgenden Aufrufe von WdfIoTargetFormatRequestForRead 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 zugewiesen.)

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

Weitere Informationen zu WdfIoTargetFormatRequestForRead 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 Ausgabepuffer einer Leseanforderung erstellt, die Leseanforderung formatiert, eine CompletionRoutine-Rückruffunktion registriert und die Leseanforderung 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,
                         READ_BUF_SIZE,
                         &memory,
                         NULL
                         );

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

status = WdfIoTargetFormatRequestForRead(
                                         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 (einschließen von 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)