WdfIoTargetFormatRequestForRead-Funktion (wdfiotarget.h)

Artikel
2025-03-22

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

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] OutputBuffer

Ein Handle für ein Framework-Speicherobjekt. Dieses Objekt stellt einen Puffer dar, der Daten vom E/A-Ziel empfängt. Dieser Parameter ist optional und kann NULL-werden. Weitere Informationen zu diesem Parameter finden Sie im folgenden 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 ist die Puffergröße.

[in, optional] DeviceOffset

Ein Zeiger auf eine Variable, die einen Anfangsoffset 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.Read.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

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 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 WdfIoTargetFormatRequestForRead-Methode, gefolgt von der WdfRequestSend--Methode, um Leseanforderungen entweder 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 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 WdfIoTargetFormatRequestForRead- Methode Request Parameter an.
Verwenden Sie den Ausgabepuffer der empfangenen Anforderung für den WdfIoTargetFormatRequestForReadOutputBuffer Parameter der Methode.
Der Treiber muss WdfRequestRetrieveOutputMemory- aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Ausgabepuffer der Anforderung darstellt, und muss dieses Handle als Wert für OutputBuffer-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 WdfIoTargetFormatRequestForRead Parameter der Request Methode 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 WdfIoTargetFormatRequestForReadOutputBuffer 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 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, 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. (WdfIoTargetFormatRequestForRead 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 Leseanforderungen mit einem Puffer der Länge Null. Für solche E/A-Ziele kann Ihr Treiber NULL- für den parameter OutputBuffer angeben.

Nachdem ein Treiber WdfIoTargetFormatRequestForRead- 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 WdfIoTargetFormatRequestForRead, 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 WdfIoTargetFormatRequestForRead) 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 WdfIoTargetFormatRequestForRead 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 WdfIoTargetFormatRequestForReadfinden 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 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
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)