IWDFUsbTargetPipe2::ConfigureContinuousReader-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 ConfigureContinuousReader-Methode konfiguriert das Framework so, dass es kontinuierlich aus einer USB-Pipe liest.

Syntax

HRESULT ConfigureContinuousReader(
  [in]           SIZE_T                                              TransferLength,
  [in]           SIZE_T                                              HeaderLength,
  [in]           SIZE_T                                              TrailerLength,
  [in]           UCHAR                                               NumPendingReads,
  [in, optional] IUnknown                                            *pMemoryCleanupCallbackInterface,
  [in]           IUsbTargetPipeContinuousReaderCallbackReadComplete  *pOnCompletion,
  [in, optional] PVOID                                               pCompletionContext,
  [in, optional] IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailure
);

Parameter

[in] TransferLength

Die maximale Länge der Daten in Bytes, die vom Gerät empfangen werden können.

[in] HeaderLength

Ein Offset in Bytes in den Puffer, der Daten vom Gerät empfängt. Das Framework speichert Daten vom Gerät in einem Lesepuffer, beginnend beim Offsetwert. Anders ausgedrückt: Dieser Bereich liegt vor dem Bereich TransferLength, in dem das Framework Daten vom Gerät speichert.

[in] TrailerLength

Die Länge eines nachgestellten Pufferbereichs in Bytes. Dieser Bereich folgt dem TransferLength-Bereich, in dem das Framework Daten vom Gerät speichert.

[in] NumPendingReads

Die Anzahl der Leseanforderungen, die das Framework in die Warteschlange stellt, um Daten vom E/A-Ziel zu empfangen. Wenn dieser Wert null ist, verwendet das Framework eine Standardanzahl von Leseanforderungen. Wenn der angegebene Wert größer als der zulässige Maximalwert ist, verwendet das Framework den zulässigen Maximalwert. Weitere Informationen zum NumPendingReads-Parameter finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] pMemoryCleanupCallbackInterface

Ein Zeiger auf eine vom Treiber bereitgestellte IUnkown-Schnittstelle , die das Framework verwendet, um auf eine optionale IObjectCleanup::OnCleanup-Rückruffunktion zuzugreifen. Das Framework ruft die Rückruffunktion auf, wenn die Zuordnung des Lesepuffers aufgehoben wird, den es zum Verarbeiten des fortlaufenden Lesevorgangs erstellt. Dieser Parameter ist optional und kann NULL sein.

[in] pOnCompletion

Ein Zeiger auf eine vom Treiber bereitgestellte IUsbTargetPipeContinuousReaderCallbackReadComplete-Schnittstelle , die eine OnReaderCompletion-Rückruffunktion bereitstellt.

[in, optional] pCompletionContext

Ein nicht typisierter Zeiger auf treiberdefinierte Kontextinformationen, die das Framework an die IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion-Rückruffunktion des Treibers übergibt.

[in, optional] pOnFailure

Ein Zeiger auf eine vom Treiber bereitgestellte IUsbTargetPipeContinuousReaderCallbackReadersFailed-Schnittstelle , die eine OnReaderFailure-Rückruffunktion bereitstellt.

Rückgabewert

ConfigureContinuousReader gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)	Der Treiber hat bereits einen fortlaufenden Reader für die USB-Pipe konfiguriert. Die USB-Pipe ist nicht für Massen- oder Unterbrechungseingabeübertragungen eingerichtet.
E_OUTOFMEMORY	Fehler beim Versuch des Frameworks, einen Puffer zuzuweisen.
ERROR_ARITHMETIC_OVERFLOW	Der Parameter TransferLength, HeaderLength oder TrailerLength hat eine Größe angegeben, die zu groß oder anderweitig ungültig war.

Diese Methode gibt möglicherweise einen der anderen Werte zurück, die Winerror.h enthält.

Hinweise

Sie können einen fortlaufenden Reader für eine Bulkpipe oder eine Interruptpipe konfigurieren. Die Pipe muss über einen Eingabeendpunkt verfügen.

Nachdem Sie ConfigureContinuousReader aufgerufen haben , um einen fortlaufenden Reader zu konfigurieren, muss Ihr Treiber IWDFIoTargetStateManagement::Start aufrufen, um den Reader zu starten. Um den Reader zu beenden, muss der Treiber IWDFIoTargetStateManagement::Stop aufrufen.

In der Regel ruft ein Treiber ConfigureContinuousReader aus seiner IPnpCallbackHardware::OnPrepareHardware-Rückruffunktion auf. Der Treiber sollte IWDFIoTargetStateManagement::Start innerhalb seiner IPnpCallback::OnD0Entry-Rückruffunktion und IWDFIoTargetStateManagement::Stop innerhalb seiner IPnpCallback::OnD0Exit-Rückruffunktion aufrufen.

Jedes Mal, wenn das E/A-Ziel der Pipe eine Leseanforderung erfolgreich abschließt, ruft das Framework die Rückruffunktion IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion des Treibers auf. Wenn das E/A-Ziel bei der Verarbeitung einer Anforderung einen Fehler meldet, ruft das Framework die IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure-Rückruffunktion des Treibers auf, nachdem alle Leseanforderungen abgeschlossen wurden. (Daher wird die OnReaderCompletion-Rückruffunktion nicht aufgerufen, während die OnReaderFailure-Rückruffunktion ausgeführt wird.)

Verwenden Sie die folgenden Richtlinien, um einen Wert für den NumPendingReads-Parameter auszuwählen:

Legen Sie NumPendingReads auf Null fest, wenn Ihr Treiber den Standardwert des Frameworks verwenden soll.
Der Standardwert ist größer als eins und bietet eine einigermaßen gute Leistung für viele Geräte in vielen Prozessorkonfigurationen.
Legen Sie NumPendingReads auf eins fest, wenn es wichtig ist, dass Ihr Treiber Datenpuffer in der genauen Reihenfolge empfängt, in der das Gerät die Daten übermittelt.
Wenn das Framework mehrere Leseanforderungen in die Warteschlange stellt, empfängt der Treiber die Datenpuffer möglicherweise nicht in derselben Reihenfolge, in der das Gerät die Daten übermittelt.
Legen Sie NumPendingReads auf eine Zahl fest, die die Leistungsanforderungen für Ihr Gerät erfüllt, basierend auf gründlichen Leistungsmessungen.
Testen Sie zunächst Ihr Gerät mit dem Standardwert (0) für NumPendingReads. Ihre Tests sollten verschiedene Hardwarekonfigurationen umfassen, einschließlich unterschiedlicher Prozessortypen und -anzahl sowie verschiedener USB-Hostcontroller und USB-Konfigurationen. Anschließend können Sie mit höheren Werten experimentieren, indem Sie die gleichen Tests verwenden. Ein Treiber, der möglicherweise einen höheren Wert erfordert, ist ein Treiber für ein Gerät mit einer hohen Interruptrate, bei dem Daten verloren gehen können, wenn Interrupts nicht schnell gewartet werden.

Ein numPendingReads-Wert , der zu groß ist, kann die Leistung eines Systems verlangsamen. Sie sollten den niedrigsten Wert verwenden, der Ihren Leistungsanforderungen entspricht. In der Regel verbessern Werte, die höher als drei oder vier sind, den Datendurchsatz nicht. Höhere Werte können jedoch die Latenz oder das Risiko fehlender Daten in einer Hochfrequenzpipe verringern.

Nachdem ein Treiber ConfigureContinuousReader aufgerufen hat, kann der Treiber IWDFIoRequest::Send nicht verwenden, um E/A-Anforderungen an die Pipe zu senden, es sei denn, die IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure-Rückruffunktion des Treibers wird aufgerufen und gibt FALSE zurück.

Weitere Informationen zur ConfigureContinuousReader-Methode und USB-E/A-Zielen finden Sie unter Lesen aus einer UMDF-USB-Pipe.

Beispiele

Im folgenden Codebeispiel wird ein fortlaufender Reader konfiguriert. In diesem Beispiel entspricht die maximale Puffergröße der Größe eines vom Treiber definierten Puffers. Die Pufferoffsets für Header und Trailer sind auf 0 (null) und die Anzahl der ausstehenden Lesevorgänge auf zwei festgelegt. Im Beispiel wird der Schnittstellenzeiger der Zielpipe für den pCompletionContext-Parameter verwendet, sodass die OnReaderCompletion-Rückruffunktion die Pipe bestimmen kann, für die der Lesevorgang abgeschlossen wurde.

HRESULT hr, hrQI;
IUsbTargetPipeContinuousReaderCallbackReadComplete *pOnCompletionCallback = NULL;
IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailureCallback= NULL;
IWDFUsbTargetPipe2 * pIUsbInterruptPipe2;

//
// Obtain interfaces.
//
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnCompletionCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnFailureCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = m_pIUsbInterruptPipe->QueryInterface(IID_PPV_ARGS(&pIUsbInterruptPipe2));
if (!SUCCEEDED(hrQI)) goto Error;

//
// Configure the reader.
//
hr = pIUsbInterruptPipe2->ConfigureContinuousReader(
                                                    sizeof(m_MyBuffer), 
                                                    0,
                                                    0,
                                                    2, 
                                                    NULL,
                                                    pOnCompletionCallback,
                                                    m_pIUsbTargetPipe,
                                                    pOnFailureCallback
                                                    );
...

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)
DLL	WUDFx.dll