IWDFUsbTargetPipe2::ConfigureContinuousReader-Methode (wudfusb.h)

Artikel
02/07/2025

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. Es werden keine neuen Features zu UMDF 1 hinzugefügt, und es gibt eingeschränkte Unterstützung für UMDF 1 für neuere Versionen von Windows 10. 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 gelesen wird.

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 von 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 mit dem Offsetwert. Mit anderen Worten, dieser Bereich steht vor dem TransferLength-Größenbereich, in dem das Framework Daten vom Gerät speichert.

[in] TrailerLength

Die Länge eines nachgestellten Pufferraums in Bytes. Dieser Bereich folgt dem TransferLengthGröße, in dem das Framework Daten vom Gerät speichert.

[in] NumPendingReads

Die Anzahl der Leseanforderungen, die vom Framework in die Warteschlange gestellt werden, 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 der lesepuffer, den es zum Verarbeiten des fortlaufenden Lesevorgangs erstellt, zu behandeln. Dieser Parameter ist optional und kann NULL-werden.

[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 ü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 das USB-Pipe konfiguriert. Das 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, HeaderLengthoder TrailerLength Parameter 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.

Bemerkungen

Sie können einen endlosen Reader für ein Massenrohr oder eine Unterbrechungspipeline konfigurieren. Die Pipe muss über einen Eingabeendpunkt verfügen.

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

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

Jedes Mal, wenn das E/A-Ziel der Pipe eine Leseanforderung erfolgreich abgeschlossen hat, ruft das Framework die IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion Rückruffunktion auf. Wenn beim Verarbeiten einer Anforderung ein Fehler gemeldet wird, ruft das Framework die IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure Rückruffunktion 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 parameter NumPendingReads auszuwählen:

Legen Sie NumPendingReads- auf Null fest, wenn Der Treiber den Standardwert des Frameworks verwenden soll.
Der Standardwert ist größer als ein Wert und bietet für viele Geräte mit vielen Prozessorkonfigurationen eine vernünftige Leistung.
Legen Sie NumPendingReads- auf eine fest, wenn es wichtig ist, dass Ihr Treiber Datenpuffer in der genauen Reihenfolge empfängt, in der das Gerät die Daten liefert.
Wenn das Framework mehrere Leseanforderungen in die Warteschlange stellt, empfängt der Treiber möglicherweise nicht die Datenpuffer in derselben Reihenfolge, in der das Gerät die Daten liefert.
Legen Sie NumPendingReads- auf eine Zahl fest, die die Leistungsanforderungen für Ihr Gerät basierend auf gründlichen Leistungsmessungen erfüllt.
Testen Sie zunächst Ihr Gerät mit dem Standardwert (0) für NumPendingReads. Ihre Tests sollten verschiedene Hardwarekonfigurationen enthalten, einschließlich verschiedener Typen und Anzahl von Prozessoren und verschiedenen USB-Hostcontrollern und USB-Konfigurationen. Sie können dann mit höheren Werten experimentieren, indem Sie dieselben Tests verwenden. Ein Treiber, der möglicherweise einen höheren Wert erfordert, ist eine für ein Gerät mit hoher Unterbrechungsrate, bei dem Daten verloren gehen können, wenn Unterbrechungen 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 die Wahrscheinlichkeit fehlender Daten auf einer Hochfrequenzpipeline verringern.

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

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

Beispiele

Im folgenden Codebeispiel wird ein fortlaufender Reader konfiguriert. In diesem Beispiel ist die maximale Puffergröße die Größe eines treiberdefinierten Puffers. Die Offsets für Kopfzeilen- und Trailerpuffer werden auf Null festgelegt, und die Anzahl der ausstehenden Lesevorgänge wird auf zwei festgelegt. Im Beispiel wird der Schnittstellenzeiger der Zielpipeline 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
Mindest-UMDF-Version	1.9
Header-	wudfusb.h (include Wudfusb.h)
DLL-	WUDFx.dll