IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion-Methode (wudfusb.h)

Artikel
02/27/2024

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 in neueren Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]

Die OnReaderCompletion-Ereignisrückruffunktion eines Treibers informiert den Treiber darüber, dass ein fortlaufender Reader eine Leseanforderung erfolgreich abgeschlossen hat.

Syntax

void OnReaderCompletion(
  [in] IWDFUsbTargetPipe *pPipe,
  [in] IWDFMemory        *pMemory,
  [in] SIZE_T            NumBytesTransferred,
  [in] PVOID             Context
);

Parameter

[in] pPipe

Ein Zeiger auf die IWDFUsbTargetPipe-Schnittstelle für die USB-Pipe, für die der Treiber einen fortlaufenden Reader aktiviert hat.

[in] pMemory

Ein Zeiger auf die IWDFMemory-Schnittstelle für einen Lesepuffer, der Daten enthält, die aus der USB-Pipe gelesen wurden.

[in] NumBytesTransferred

Die Anzahl der Bytes, die der Lesepuffer enthält.

[in] Context

Ein Zeiger auf vom Treiber bereitgestellte Kontextinformationen, die der Treiber bereitgestellt hat, als er zuvor IWDFUsbTargetPipe2::ConfigureContinuousReader aufgerufen hat.

Rückgabewert

Keine

Bemerkungen

Um eine IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion-Rückruffunktion zu registrieren, muss Ihr Treiber einen Zeiger auf die IUsbTargetPipeContinuousReaderCallbackReadComplete-Schnittstelle des Treibers bereitstellen, wenn er IWDFUsbTargetPipe2::ConfigureContinuousReader aufruft.

Wenn ein Treiber einen fortlaufenden Reader für eine USB-Pipe erstellt hat, ruft das Framework jedes Mal die OnReaderCompletion-Rückruffunktion des Treibers auf, wenn das E/A-Ziel des Treibers eine Leseanforderung erfolgreich abgeschlossen hat. Wenn das E/A-Ziel eine Anforderung nicht erfolgreich abschließt, ruft das Framework die IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure-Rückruffunktion des Treibers auf.

Um auf den Puffer zuzugreifen, der Daten enthält, die vom Gerät gelesen wurden, kann der Treiber IWDFMemory::GetDataBuffer aufrufen. Das Framework schreibt die Daten in den Puffer nach dem Header, der durch den HeaderLength-Parameter von IWDFUsbTargetPipe2::ConfigureContinuousReader definiert wird. Beachten Sie, dass der Zeiger, den IWDFMemory::GetDataBuffer zurückgibt, auf den Anfang des Headers verweist, aber der NumBytesTransferred-Parameter der OnReaderCompletion-Rückruffunktion enthält nicht die Länge des Headers.

Standardmäßig löscht das Framework das Speicherobjekt des Puffers, nachdem die OnReaderCompletion-Rückruffunktion zurückgegeben wurde. Möglicherweise möchten Sie jedoch, dass das Speicherobjekt nach der Rückgabe der Rückruffunktion gültig bleibt. Beispielsweise können Sie möchten, dass Der Treiber den Schnittstellenzeiger des Speicherobjekts im Kontextbereich des Frameworkpipeobjekts speichert, damit der Treiber den Inhalt des Speicherobjekts verarbeiten kann, nachdem die Rückruffunktion zurückgegeben wurde. Um die Lebensdauer des Speicherobjekts zu verlängern, muss die Rückruffunktion die IWDFMemory::AddRef-Methode des Puffers aufrufen. Anschließend muss der Treiber die IWDFMemory::Release-Methode des Puffers aufrufen, damit das Framework das Objekt löschen kann.

Das Framework synchronisiert Aufrufe der Rückruffunktionen OnReaderCompletion und IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure gemäß den folgenden Regeln:

Diese Rückruffunktionen werden für eine einzelne USB-Pipe nicht gleichzeitig ausgeführt.
Wenn der Treiber mehrere fortlaufende Reader für mehrere USB-Pipes mit mehreren OnReaderCompletion - und OnReaderFailure-Rückruffunktionen erstellt, können die mehrere Rückruffunktionen gleichzeitig ausgeführt werden.
Wenn der Treiber beim Aufrufen von IWDFUsbTargetPipe2::ConfigureContinuousReader den Standardwert NumPendingReads angegeben hat (oder wenn er einen NumPendingReads-Wert angibt, der größer als 1 ist), und wenn eine Leseanforderung abgeschlossen wird, während die Rückruffunktion OnReaderCompletion ausgeführt wird, kann das Framework die OnReaderCompletion-Rückruffunktion erneut aufrufen, bevor die Rückruffunktion zurückgegeben wird.
Das Framework synchronisiert diese Rückruffunktionen nicht mit anderen Rückruffunktionen.

Wenn Ihr Treiber IWDFUsbTargetPipe2::ConfigureContinuousReader aufruft, kann er eine IObjectCleanup::OnCleanup-Rückruffunktion angeben. Das Framework ruft diese Rückruffunktion auf, wenn versucht wird, das Speicherobjekt zu löschen, nachdem die Rückruffunktion OnReaderCompletion zurückgegeben wurde.

Weitere Informationen zur OnReaderCompletion-Rückruffunktion und USB-E/A-Zielen finden Sie unter Behandeln eines USB-E/A-Ziels.

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform	Desktop
UMDF-Mindestversion	1.9
Kopfzeile	wudfusb.h (schließen Sie Wudfusb.h ein)

Weitere Informationen

IUsbTargetPipeContinuousReaderCallbackReadComplete

IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure

Freigeben über