WdfUsbTargetPipeReadSynchronously-Funktion (wdfusb.h)
[Gilt für KMDF und UMDF]
Die WdfUsbTargetPipeReadSynchronously Methode erstellt eine Leseanforderung und sendet sie synchron an eine angegebene USB-Eingabepipeline.
Syntax
NTSTATUS WdfUsbTargetPipeReadSynchronously(
[in] WDFUSBPIPE Pipe,
[in, optional] WDFREQUEST Request,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in, optional] PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional] PULONG BytesRead
);
Parameter
[in] Pipe
Ein Handle zu einem Framework-Pipeobjekt, das durch Aufrufen WdfUsbInterfaceGetConfiguredPipeabgerufen wurde.
[in, optional] Request
Ein Handle zu einem Framework-Anforderungsobjekt. Dieser Parameter ist optional und kann NULL-werden. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[in, optional] RequestOptions
Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_REQUEST_SEND_OPTIONS Struktur, die Optionen für die Anforderung angibt. Dieser Zeiger ist optional und kann NULL-sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[in, optional] MemoryDescriptor
Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_MEMORY_DESCRIPTOR Struktur, die den Puffer beschreibt, der Daten vom Gerät empfängt. Die Puffergröße muss ein Vielfaches der maximalen Paketgröße der Pipe sein, es sei denn, der Treiber hat WdfUsbTargetPipeSetNoMaximumPacketSizeCheckaufgerufen. Weitere Informationen zu diesem Puffer finden Sie im folgenden Abschnitt "Hinweise".
[out, optional] BytesRead
Ein Zeiger auf einen Speicherort, der die Anzahl der gelesenen Bytes empfängt, wenn der Vorgang erfolgreich ausgeführt wird. Dieser Parameter ist optional und kann NULL-werden.
Rückgabewert
WdfUsbTargetPipeReadSynchronously gibt den Fertigstellungsstatuswert des E/A-Ziels zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:
| Rückgabecode | Beschreibung |
|---|---|
|
Die Größe der WDF_REQUEST_SEND_OPTIONS Struktur, auf die von RequestOptions verwiesen wurde, war falsch. |
|
Ein ungültiger Parameter wurde erkannt. |
|
Nicht genügend Arbeitsspeicher verfügbar. |
|
Die IRQL des Aufrufers wurde nicht PASSIVE_LEVEL, ein ungültiger Speicherdeskriptor angegeben, der Typ der Pipe war ungültig, die Übertragungsrichtung ungültig, oder die angegebene E/A-Anforderung wurde bereits an ein E/A-Ziel in die Warteschlange gestellt. |
|
Die Puffergröße war kein Vielfaches der maximalen Paketgröße der Pipe. |
|
Der Treiber hat einen Timeoutwert angegeben, und die Anforderung wurde nicht innerhalb der zugewiesenen Zeit abgeschlossen. |
|
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 WdfUsbTargetPipeReadSynchronously Methode, um Leseanforderungen synchron zu senden. Verwenden Sie zum asynchronen Senden von Leseanforderungen WdfUsbTargetPipeFormatRequestForRead-gefolgt von WdfRequestSend-.
Die pipe, die der parameter Pipe angibt, muss eine Eingabepipe sein, und der Typ der Pfeife mussWdfUsbPipeTypeBulk oder WdfUsbPipeTypeInterruptsein.
Die WdfUsbTargetPipeReadSynchronously-Methode wird erst zurückgegeben, wenn die Anforderung abgeschlossen ist, es sei denn, der Treiber stellt einen Timeoutwert in der WDF_REQUEST_SEND_OPTIONS-Struktur bereit, auf die der RequestOptions Parameter verweist, oder es sei denn, ein Fehler wird 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 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 WdfUsbTargetPipeReadSynchronouslyMemoryDescriptor Parameter der Methode.
Der Treiber muss WdfRequestRetrieveOutputMemory- aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Ausgabepuffer der Anforderung darstellt, und diese dann in der WDF_MEMORY_DESCRIPTOR Struktur platzieren, auf die MemoryDescriptor verweist.
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 im WdfUsbTargetPipeReadSynchronously Parameter der Request-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 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.
-
Bereitstellen von Pufferraum für den
WdfUsbTargetPipeReadSynchronously MemoryDescriptor Parameter derMethode. Der Treiber kann diesen Pufferspeicher als lokal zugewiesenen Puffer, als WDFMEMORY-Handle oder als 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 sind verfügbar:
-
Bereitstellen eines lokalen Puffers
Da WdfUsbTargetPipeReadSynchronously 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)); -
Bereitstellen eines WDFMEMORY-Handles
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 WdfUsbTargetPipeReadSynchronously sendet, an das E/A-Ziel gesendet wurde, gelöscht, wiederverwendet oder neu formatiert wurde. (WdfUsbTargetPipeReadSynchronously erhöht die Referenzanzahl des Speicherobjekts. Beim Löschen, Erneuten Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts erhöht.)
-
Bereitstellen einer MDL
Treiber können die MDL abrufen, die einer empfangenen E/A-Anforderung zugeordnet ist, indem sie WdfRequestRetrieveOutputWdmMdlaufrufen.
-
Bereitstellen eines lokalen Puffers
Ein Treiber kann nicht WdfUsbTargetPipeReadSynchronously aufrufen, wenn ein fortlaufender Reader für die Pipe konfiguriert wurde.
Informationen zum Abrufen von Statusinformationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.
Weitere Informationen zur WdfUsbTargetPipeReadSynchronously Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.
Beispiele
Im folgenden Codebeispiel wird ein Framework-Speicherobjekt erstellt, eine WDF_MEMORY_DESCRIPTOR Struktur initialisiert und die Struktur an WdfUsbTargetPipeReadSynchronouslyübergeben. In diesem Beispiel wird NULL- für das Anforderungsobjekthandle angegeben, sodass das Framework ein neues Anforderungsobjekt für das E/A-Ziel erstellt.
WDFMEMORY wdfMemory;
WDF_MEMORY_DESCRIPTOR readBufDesc;
ULONG BytesRead;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
readSize,
&wdfMemory,
NULL
);
if (!NT_SUCCESS(status)){
return ;
}
buffer = WdfMemoryGetBuffer(
wdfMemory,
NULL
);
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&readBufDesc,
buffer,
readSize
);
status = WdfUsbTargetPipeReadSynchronously(
Pipe,
NULL,
NULL,
&readBufDesc,
&BytesRead
);
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Universal |
| Minimale KMDF-Version | 1.0 |
| Mindest-UMDF-Version | 2.0 |
| Header- | wdfusb.h (include Wdfusb.h) |
| Library | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL- | PASSIVE_LEVEL |
| DDI-Complianceregeln | DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf), WriteReqs(kmdf) |