EVT_WDF_USB_READER_COMPLETION_ROUTINE Rückruffunktion (wdfusb.h)
[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.
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.) |