WdfIoTargetSendReadSynchronously-Funktion (wdfiotarget.h)
[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 aus einem vorherigen Aufruf von WdfDeviceGetIoTarget oder WdfIoTargetCreate oder von einer Methode abgerufen wurde, die von einem spezialisierten E/A-Ziel bereitgestellt wird.
[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 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 sein. Weitere Informationen zu diesem Parameter finden Sie im 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 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.
[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, wird WdfIoTargetSendReadSynchronously nach Abschluss der E/A-Anforderung zurückgegeben, und der Rückgabewert ist der Abschluss der Anforderung status Wert. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:
Rückgabecode | Beschreibung |
---|---|
|
Ein ungültiger Parameter wurde erkannt. |
|
Die Größe der WDF_REQUEST_SEND_OPTIONS-Struktur, auf die der RequestOptions-Parameter verweist, war falsch. |
|
Die E/A-Anforderung wurde bereits für ein E/A-Ziel in die Warteschlange gestellt. |
|
Das Framework konnte keine Systemressourcen (in der Regel Arbeitsspeicher) zuordnen. |
|
Der Treiber hat einen Timeoutwert angegeben, und die Anforderung wurde nicht innerhalb der zugewiesenen Zeit abgeschlossen. |
|
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 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 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 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 an .
-
Verwenden Sie den Ausgabepuffer der empfangenen Anforderung für den OutputBuffer-Parameter der WdfIoTargetSendReadSynchronously-Methode.
Der Treiber muss WdfRequestRetrieveOutputMemory aufrufen, um ein Handle für ein Frameworkspeicherobjekt 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.
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 WdfIoTargetSendReadSynchronously-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 ohne 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.
-
Stellen Sie Pufferspeicher für den OutputBuffer-Parameter der WdfIoTargetSendReadSynchronously-Methode bereit.
Ihr Treiber kann diesen Pufferspeicher 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.
Bei Bedarf konvertiert das Framework die Pufferbeschreibung in eine Pufferbeschreibung, die für die E/A-Zielmethode für den Zugriff auf Datenpuffer richtig ist.
Die folgenden Techniken zum Angeben des Pufferspeichers sind verfügbar:
-
Geben Sie einen lokalen Puffer an.
Da WdfIoTargetSendReadSynchronously E/A-Anforderungen synchron verarbeitet, kann der Treiber Anforderungspuffer erstellen, die für die aufrufende Routine lokal sind, wie das folgende Codebeispiel zeigt.
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 Arbeitsspeicher abzurufen, wie das folgende Codebeispiel zeigt.
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 übergibt. Der Treiber darf die empfangene E/A-Anforderung erst abschließen, wenn die neue Anforderung, die WdfIoTargetSendReadSynchronously an das E/A-Ziel sendet, gelöscht, wiederverwendet oder neu formatiert wurde. (WdfIoTargetSendReadSynchronously erhöht die Referenzanzahl des Speicherobjekts. Durch das Löschen, Erneutes Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Verweisanzahl des Speicherobjekts verringert.)
-
Geben Sie eine MDL an.
Treiber können die MDL abrufen, die einer empfangenen E/A-Anforderung zugeordnet ist, indem sie WdfRequestRetrieveOutputWdmMdl aufrufen.
-
Geben Sie einen lokalen Puffer an.
Informationen zum Abrufen status Informationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.
Weitere Informationen zu WdfIoTargetSendReadSynchronously 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 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 | 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 | PASSIVE_LEVEL |
DDI-Complianceregeln | DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), SyncReqSend(kmdf), WriteReqs(kmdf) |
Weitere Informationen
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE
WdfIoTargetFormatRequestForRead
WdfIoTargetSendWriteSynchronously
WdfRequestRetrieveOutputMemory
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für