EVT_WDF_USB_READER_COMPLETION_ROUTINE Rückruffunktion (wdfusb.h)

  • Artikel

[Gilt für KMDF und UMDF]

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

Syntax

EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;

void EvtWdfUsbReaderCompletionRoutine(
  [in] WDFUSBPIPE Pipe,
  [in] WDFMEMORY Buffer,
  [in] size_t NumBytesTransferred,
  [in] WDFCONTEXT Context
)
{...}

Parameter

[in] Pipe

Ein Handle für ein Framework-Pipeobjekt.

[in] Buffer

Ein Handle für ein Frameworkspeicherobjekt, das einen Puffer darstellt, der Daten vom Gerät enthält.

[in] NumBytesTransferred

Die Anzahl der Bytes der Daten, die sich im Lesepuffer befinden.

[in] Context

Treiberdefinierte Kontextinformationen, die der treiber im Element EvtUsbTargetPipeReadCompleteContext der WDF_USB_CONTINUOUS_READER_CONFIG-Struktur der Pipe angegeben hat.

Rückgabewert

Keine

Bemerkungen

Um eine EvtUsbTargetPipeReadComplete-Rückruffunktion zu registrieren, muss der Treiber die Adresse der Funktion in einer WDF_USB_CONTINUOUS_READER_CONFIG-Struktur platzieren.

Wenn ein Treiber einen fortlaufenden Reader für eine USB-Pipe erstellt hat, ruft das Framework die EvtUsbTargetPipeReadComplete-Rückruffunktion des Treibers auf, wenn das E/A-Ziel des Treibers eine Leseanforderung erfolgreich abgeschlossen hat. Die Rückruffunktion wird an der IRQL aufgerufen, an der das E/A-Ziel die Leseanforderung abgeschlossen hat. Dies ist in der Regel IRQL = DISPATCH_LEVEL, aber nicht höher als DISPATCH_LEVEL. (Wenn das E/A-Ziel eine Anforderung nicht erfolgreich abschließt, ruft das Framework die Rückruffunktion EvtUsbTargetPipeReadersFailed des Treibers auf.)

Um auf den Puffer zuzugreifen, der Daten enthält, die vom Gerät gelesen wurden, kann der Treiber WdfMemoryGetBuffer aufrufen. Das Framework schreibt die Daten in den Puffer nach dem Header, der vom HeaderLength-Member der WDF_USB_CONTINUOUS_READER_CONFIG-Struktur definiert wird. Beachten Sie, dass der Zeiger, den WdfMemoryGetBuffer zurückgibt, auf den Anfang des Headers verweist, aber der NumBytesTransferred-Parameter der Rückruffunktion EvtUsbTargetPipeReadCompletenicht die Länge des Headers enthält.

Standardmäßig löscht das Framework das Speicherobjekt des Puffers, nachdem die Rückruffunktion EvtUsbTargetPipeReadComplete 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 Ihr Treiber das Objekthandle 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 das Handle des Speicherobjekts an WdfObjectReference übergeben. Anschließend muss der Treiber WdfObjectDereference aufrufen, damit das Framework das Objekt löschen kann.

Das Framework synchronisiert Aufrufe der Rückruffunktionen EvtUsbTargetPipeReadComplete und EvtUsbTargetPipeReadersFailed 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 Rückruffunktionen EvtUsbTargetPipeReadComplete und EvtUsbTargetPipeReadersFailed erstellt, können die mehrere Rückruffunktionen gleichzeitig ausgeführt werden.
  • Wenn der Treiber den Standardwert NumPendingReads oder einen Wert größer als 1 angegeben hat und eine Leseanforderung abgeschlossen wird, während die Rückruffunktion EvtUsbTargetPipeReadComplete ausgeführt wird, kann das Framework die Rückruffunktion EvtUsbTargetPipeReadComplete erneut aufrufen, bevor die Rückruffunktion zurückgegeben wird.
  • Das Framework synchronisiert diese Rückruffunktionen nicht mit anderen Rückruffunktionen.
Im BufferAttributes-Member der WDF_USB_CONTINUOUS_READER_CONFIG-Struktur kann Ihr Treiber die Rückruffunktionen EvtCleanupCallback und EvtDestroyCallback für das Speicherobjekt angeben. Wenn Sie eine EvtCleanupCallback-Rückruffunktion angeben, ruft das Framework diese Rückruffunktion auf, wenn versucht wird, das Speicherobjekt zu löschen, nachdem die Rückruffunktion EvtUsbTargetPipeReadComplete zurückgegeben wurde. Wenn die Rückruffunktion EvtUsbTargetPipeReadCompleteWdfObjectReference aufgerufen hat, darf die Rückruffunktion EvtCleanupCallback (sofern angegeben) WdfObjectDereference nicht aufrufen.

Der Treiber muss WdfObjectDereference aufrufen, wenn er die Verwendung des Speicherobjekts abgeschlossen hat. Das Framework kann dann die EvtDestroyCallback-Rückruffunktion des Treibers aufrufen (sofern angegeben) und das Speicherobjekt löschen.

Weitere Informationen zur EvtUsbTargetPipeReadComplete-Rückruffunktion und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.

Anforderungen

Anforderung Wert
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Kopfzeile wdfusb.h (einschließen von Wdf.h)
IRQL <=DISPATCH_LEVEL (siehe Abschnitt hinweise.)

Weitere Informationen

EvtUsbTargetPipeReadersFailed

WDF_USB_CONTINUOUS_READER_CONFIG

WdfMemoryGetBuffer