WdfIoTargetSendReadSynchronously-Funktion (wdfiotarget.h)

Artikel
07/16/2024

[Gilt für KMDF und UMDF]

Die WdfIoTargetSendReadSynchronously Methode erstellt eine Leseanforderung und sendet sie synchron an ein E/A-Ziel.

Syntax

NTSTATUS WdfIoTargetSendReadSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OutputBuffer,
  [in, optional]  PLONGLONG                 DeviceOffset,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesRead
);

Parameter

[in] IoTarget

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

[in, optional] Request

Ein Handle zu einem Framework-Anforderungsobjekt. Dieser Parameter ist optional und kann NULL-werden. Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] OutputBuffer

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_MEMORY_DESCRIPTOR Struktur, die den Puffer beschreibt, der Daten vom Gerät empfängt. Dieser Parameter ist optional und kann NULL-werden. Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt "Hinweise".

[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.Read.DeviceOffset Mitglied der WDF_REQUEST_PARAMETERS Struktur der Anforderung ab. Dieser Zeiger ist optional. Die meisten Treiber legen diesen Zeiger auf NULL-fest.

[in, optional] RequestOptions

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_REQUEST_SEND_OPTIONS Struktur, die Optionen für die Leseanforderung angibt. Dieser Zeiger ist optional und kann NULL-sein.

[out, optional] BytesRead

Ein Zeiger auf einen Speicherort, der die Anzahl der gelesenen Bytes empfängt, wenn der Vorgang erfolgreich ist. Dieser Zeiger ist optional und kann NULL-sein.

Rückgabewert

Wenn der Vorgang erfolgreich ist, WdfIoTargetSendReadSynchronously zurück, nachdem die E/A-Anforderung abgeschlossen ist, und der Rückgabewert ist der Fertigstellungsstatuswert der Anforderung. 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_INFO_LENGTH_MISMATCH	Die Größe der WDF_REQUEST_SEND_OPTIONS Struktur, auf die der RequestOptions Parameter verweist, war falsch.
STATUS_INVALID_DEVICE_REQUEST	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_IO_TIMEOUT	Der Treiber hat einen Timeoutwert angegeben, und die Anforderung wurde nicht innerhalb der zugewiesenen Zeit abgeschlossen.
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 WdfIoTargetSendReadSynchronously Methode, um Leseanforderungen synchron zu senden. Verwenden Sie zum asynchronen Senden von Leseanforderungen die WdfIoTargetFormatRequestForRead--Methode, gefolgt von der WdfRequestSend--Methode.

WdfIoTargetSendReadSynchronously wird erst zurückgegeben, wenn die Anforderung abgeschlossen wurde, es sei denn, der Treiber stellt einen Timeoutwert in der RequestOptionsWDF_REQUEST_SEND_OPTIONS-Struktur des Parameters oder sofern kein Fehler erkannt wird.

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 Parameter Request an.
Verwenden Sie den Ausgabepuffer der empfangenen Anforderung für den WdfIoTargetSendReadSynchronouslyOutputBuffer Parameter der Methode.
Der Treiber muss WdfRequestRetrieveOutputMemory- aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Ausgabepuffer der Anforderung darstellt. Anschließend muss der Treiber dieses Handle in der WDF_MEMORY_DESCRIPTOR Struktur platzieren, die der Treiber für den OutputBuffer Parameter bereitstellt.

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:

Geben Sie einen NULL- Anforderungshandle für den WdfIoTargetSendReadSynchronously Parameter der Methode Request an, oder erstellen Sie ein neues Anforderungsobjekt, und geben Sie dessen Handle an:
- Wenn Sie ein NULL- Anforderungshandle bereitstellen, verwendet das Framework ein internes Anforderungsobjekt. Diese Technik ist einfach zu verwenden, aber der Treiber kann die Anforderung nicht abbrechen.
- Wenn Sie WdfRequestCreate aufrufen, um ein oder mehrere Anforderungsobjekte zu erstellen, können Sie diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuseaufrufen. Mit dieser Technik können Sie die EvtDriverDeviceAdd Rückruffunktion Ihres Treibers vorschreiben, um Anforderungsobjekte für ein Gerät vorab zu verwenden. Darüber hinaus kann ein anderer Treiberthread WdfRequestCancelSentRequest- aufrufen, um die Anforderung bei Bedarf abzubrechen.
Der Treiber kann einen Parameter ohneNULL-RequestOptions- angeben, unabhängig davon, ob der Treiber ein nicht-NULL- oder ein NULL-Request Parameter bereitstellt. Sie können z. B. den parameter RequestOptions verwenden, um einen Timeoutwert anzugeben.
Stellen Sie Pufferraum für den WdfIoTargetSendReadSynchronouslyOutputBuffer-Parameter Methode bereit.
Der Treiber kann diesen Pufferspeicher als lokal zugewiesenen Puffer, als WDFMEMORY-Handle oder als Speicherdeskriptorliste (MDL) angeben. Sie können verwenden, welche Methode am bequemsten ist.

Bei Bedarf konvertiert das Framework die Pufferbeschreibung in eine, die für die -Methode des E/A-Ziels für den Zugriff auf Datenpufferkorrekt ist.

Die folgenden Techniken zum Angeben des Pufferraums stehen zur Verfügung:
- Geben Sie einen lokalen Puffer an.
  Da WdfIoTargetSendReadSynchronously E/A-Anforderungen synchron verarbeitet, kann der Treiber Anforderungspuffer erstellen, die lokal für die aufrufende Routine sind, wie im folgenden Codebeispiel gezeigt.
```
WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
MY_BUFFER_TYPE  MyBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                  (PVOID) &MyBuffer,
                                  sizeof(MyBuffer));
```
- Geben Sie einen WDFMEMORY-Handle an.
  Rufen Sie WdfMemoryCreate oder WdfMemoryCreatePreallocated auf, um ein Handle für vom Framework verwalteten Speicher abzurufen, wie im folgenden Codebeispiel gezeigt.
```
WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
status = WdfMemoryCreate(NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&MemoryDescriptor,
                                  MemoryHandle,
                                  NULL);
```
  Alternativ kann der Treiber WdfRequestRetrieveOutputMemory- aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Ausgabepuffer einer empfangenen E/A-Anforderung darstellt, wenn der Treiber den Inhalt dieses Puffers an das E/A-Ziel übergeben soll. Der Treiber darf die empfangene E/A-Anforderung erst abschließen, wenn die neue Anforderung, die WdfIoTargetSendReadSynchronously sendet, an das E/A-Ziel gesendet wurde, gelöscht, wiederverwendet oder neu formatiert wurde. (WdfIoTargetSendReadSynchronously erhöht die Referenzanzahl des Speicherobjekts. Beim Löschen, Erneuten Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts erhöht.)
- Geben Sie eine MDL an.
  Treiber können die MDL abrufen, die einer empfangenen E/A-Anforderung zugeordnet ist, indem sie WdfRequestRetrieveOutputWdmMdlaufrufen.

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.

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

Weitere Informationen zu WdfIoTargetSendReadSynchronouslyfinden 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 erstellt, eine WDF_MEMORY_DESCRIPTOR Struktur initialisiert und die Struktur an WdfIoTargetSendReadSynchronouslyübergeben. In diesem Beispiel wird NULL- für das Anforderungsobjekthandle angegeben, sodass das Framework ein neues Anforderungsobjekt für das E/A-Ziel erstellt.

WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
ULONG_PTR  bytesRead = NULL;

status = WdfMemoryCreate(
                         NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL
                         );
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(
                                  &MemoryDescriptor,
                                  MemoryHandle,
                                  NULL
                                  );
status = WdfIoTargetSendReadSynchronously(
                                          ioTarget,
                                          NULL,
                                          &MemoryDescriptor,
                                          NULL,
                                          NULL,
                                          &bytesRead
                                          );

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfiotarget.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), SyncReqSend(kmdf), WriteReqs(kmdf)