WdfIoTargetSendWriteSynchronously-Funktion (wdfiotarget.h)

Artikel
02/29/2024

[Gilt für KMDF und UMDF]

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

Syntax

NTSTATUS WdfIoTargetSendWriteSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    InputBuffer,
  [in, optional]  PLONGLONG                 DeviceOffset,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesWritten
);

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, optional] Request

Ein Handle für ein Frameworkanforderungsobjekt. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt hinweise.

[in, optional] InputBuffer

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_MEMORY_DESCRIPTOR Struktur, die den Puffer beschreibt, der Daten enthält, die auf das Gerät geschrieben werden. Dieser Parameter ist optional und kann NULL sein. 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ä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.

[in, optional] RequestOptions

Ein Zeiger auf eine vom Aufrufer zugeordnete WDF_REQUEST_SEND_OPTIONS Struktur, die Optionen für die Anforderung angibt. Dieser Zeiger ist optional und kann NULL sein. Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt hinweise.

[out, optional] BytesWritten

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

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt WdfIoTargetSendWriteSynchronously nach Abschluss der E/A-Anforderung zurück, und der Rückgabewert ist der Abschluss status Wert 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 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 WdfIoTargetSendWriteSynchronously-Methode , um Schreibanforderungen synchron zu senden. Verwenden Sie zum asynchronen Senden von Schreibanforderungen die WdfIoTargetFormatRequestForWrite-Methode , gefolgt von der WdfRequestSend-Methode .

WdfIoTargetSendWriteSynchronously wird erst zurückgegeben, wenn die Anforderung abgeschlossen ist, es sei denn, der Treiber stellt einen Timeoutwert in der WDF_REQUEST_SEND_OPTIONS-Struktur des RequestOptions-Parameters bereit, oder es wird kein Fehler erkannt.

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 WdfIoTargetSendWriteSynchronously-Methode an.
Verwenden Sie den Eingabepuffer der empfangenen Anforderung für den InputBuffer-Parameter der WdfIoTargetSendWriteSynchronously-Methode.
Der Treiber muss WdfRequestRetrieveInputMemory aufrufen, um ein Handle für ein Frameworkspeicherobjekt abzurufen, das den Eingabepuffer der Anforderung darstellt, und dieses Handle dann in der WDF_MEMORY_DESCRIPTOR Struktur platzieren, die der Treiber für den InputBuffer-Parameter bereitstellt.

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:

Geben Sie ein NULL-Anforderungshandle für den Request-Parameter der WdfIoTargetSendWriteSynchronously-Methode 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 WdfRequestReuse aufrufen. Mit dieser Technik kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers Anforderungsobjekte für ein Gerät vorab zugeordnet werden. Darüber hinaus kann ein anderer Treiberthread WdfRequestCancelSentRequest aufrufen, um die Anforderung bei Bedarf abzubrechen.
Ihr Treiber kann einen RequestOptions-Parameter ungleich NULL angeben, unabhängig davon, ob der Treiber einen Nicht-NULL- oder null-Anforderungsparameter bereitstellt. Sie können beispielsweise den Parameter RequestOptions verwenden, um einen Timeoutwert anzugeben.
Geben Sie Pufferraum für den InputBuffer-Parameter der WdfIoTargetSendWriteSynchronously-Methode an.
Ihr Treiber kann diesen Pufferbereich als lokal zugeordneten Puffer, als WDFMEMORY-Handle oder als Speicherdeskriptorliste (Memory Descriptor List, MDL) angeben. Sie können die methode verwenden, die am bequemsten ist.

Falls erforderlich, konvertiert das Framework die Pufferbeschreibung in eine , die für die E/A-Zielmethode für den Zugriff auf Datenpuffer korrekt ist.

Die folgenden Techniken zum Angeben des Pufferspeichers sind verfügbar:
- Geben Sie einen lokalen Puffer an.
  Da WdfIoTargetSendWriteSynchronously E/A-Anforderungen synchron verarbeitet, kann der Treiber Anforderungspuffer erstellen, die für die aufrufende Routine lokal 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 ein WDFMEMORY-Handle an.
  Rufen Sie WdfMemoryCreate oder WdfMemoryCreatePreallocated auf, um ein Handle für den vom Framework verwalteten Speicher zu erhalten, 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 WdfRequestRetrieveInputMemory aufrufen, um ein Handle für ein Frameworkspeicherobjekt abzurufen, das den Eingabepuffer 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 WdfIoTargetSendWriteSynchronously an das E/A-Ziel sendet, gelöscht, wiederverwendet oder neu formatiert wurde. (WdfIoTargetSendWriteSynchronously erhöht die Referenzanzahl des Speicherobjekts. Durch das Löschen, Wiederverwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts verringert.)
- Geben Sie eine MDL an.
  Treiber können die MDL abrufen, die einer empfangenen E/A-Anforderung zugeordnet ist, indem sie WdfRequestRetrieveInputWdmMdl aufrufen.

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.

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

Weitere Informationen zu WdfIoTargetSendWriteSynchronously 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 erstellt, eine WDF_MEMORY_DESCRIPTOR-Struktur initialisiert und die Struktur an WdfIoTargetSendWriteSynchronously ü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  bytesWritten = NULL;

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

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	<=PASSIVE_LEVEL
DDI-Complianceregeln	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), SyncReqSend(kmdf)