Arbeiten mit USB-Pipes in UMDF 1.x-Treibern

Das Framework stellt jede Pipe in einer USB-Schnittstelle als Framework-USB-Pipe-Objekt dar. Wenn ein Treiber ein USB-Gerät konfiguriert, erstellt das Framework ein Framework-USB-Pipe-Objekt für jede Pipe in jeder ausgewählten Schnittstelle. Pipeobjektmethoden ermöglichen einem Treiber Folgendes:

• Abrufen von Pipeinformationen.

• Aus einer Pipe lesen.

• Schreiben sie in eine Pipe.

• Beenden, Leeren oder Zurücksetzen einer Pipe.

• Legen Sie eine Piperichtlinie fest.

• Behandeln von Pipefehlern.

Abrufen von UMDF-USB-Pipe-Informationen

Nachdem ein UMDF-Treiber die IWDFUsbInterface::RetrieveUsbPipeObject-Methode aufgerufen hat, um einen Zeiger auf die IWDFUsbTargetPipe-Schnittstelle für ein USB-Pipe-Objekt abzurufen, kann der Treiber die folgenden Methoden aufrufen, die das USB-Pipe-Objekt zum Abrufen von Informationen über die USB-Pipe definiert:

IWDFUsbTargetPipe::GetInformation
Ruft Informationen zu einer USB-Pipe und ihrem Endpunkt ab.

IWDFUsbTargetPipe::GetType
Gibt den Typ einer USB-Pipe zurück.

IWDFUsbTargetPipe::IsInEndPoint
Bestimmt, ob eine USB-Pipe mit einem Eingabeendpunkt verbunden ist.

IWDFUsbTargetPipe::IsOutEndPoint
Bestimmt, ob eine USB-Pipe mit einem Ausgabeendpunkt verbunden ist.

IWDFUsbTargetPipe::RetrievePipePolicy
Ruft eine WinUsb-Piperichtlinie ab.

Lesen aus einer UMDF-USB-Pipe

Um Daten aus einer USB-Eingabepipe zu lesen, kann Ihr Treiber entweder (oder beides) der folgenden Techniken verwenden:

• Daten synchron lesen.

  Um Daten synchron aus einer USB-Eingabepipe zu lesen, ruft ein UMDF-Treiber zuerst die IWDFIoTarget::FormatRequestForRead-Methode auf, um eine Leseanforderung zu erstellen. Anschließend ruft der Treiber die IWDFIoRequest::Send-Methode auf und gibt das WDF_REQUEST_SEND_OPTION_SYNCHRONOUS-Flag an, um die Anforderung synchron zu senden.

• Daten asynchron lesen.

  Um Daten asynchron aus einer USB-Eingabepipe zu lesen, ruft ein UMDF-Treiber zuerst die IWDFIoTarget::FormatRequestForRead-Methode auf, um eine Leseanforderung zu erstellen. Anschließend ruft der Treiber die IWDFIoRequest::Send-Methode auf, ohne das flag WDF_REQUEST_SEND_OPTION_SYNCHRONOUS anzugeben.

• Lesen Sie Daten synchron und kontinuierlich.

  Ein fortlaufender Reader ist ein vom Framework bereitgestellter Mechanismus, der sicherstellt, dass eine Leseanforderung für eine USB-Pipe immer verfügbar ist. Dieser Mechanismus garantiert, dass der Treiber immer bereit ist, Daten von einem Gerät zu empfangen, das einen asynchronen, nicht angeforderten Eingabedatenstrom bereitstellt. Beispielsweise kann ein Treiber für eine Netzwerkschnittstelle Karte (NIC) einen kontinuierlichen Reader verwenden, um Eingabedaten zu empfangen.

  Um einen kontinuierlichen Reader für eine Eingabepipe zu konfigurieren, muss die IPnpCallbackHardware::OnPrepareHardware-Rückruffunktion des Treibers die IWDFUsbTargetPipe2::ConfigureContinuousReader-Methode aufrufen. Diese Methode stellt eine Reihe von Leseanforderungen an das E/A-Ziel des Geräts in die Warteschlange.

  Außerdem muss die IPnpCallback::OnD0Entry-Rückruffunktion des Treibers IWDFIoTargetStateManagement::Start aufrufen, um den kontinuierlichen Reader zu starten, und die IPnpCallback::OnD0Exit-Rückruffunktion des Treibers muss IWDFIogetTarTarStateManagement::Stop aufrufen, um den fortlaufenden Reader zu beenden.

  Jedes Mal, wenn diese Daten vom Gerät verfügbar sind, führt das E/A-Ziel eine Leseanforderung aus, und das Framework ruft eine von zwei Rückruffunktionen auf: IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion , wenn das E/A-Ziel die Daten erfolgreich liest, oder IUsbTargetPipeContinuousReaderCallbackReadersFailed:OnReaderFailure , wenn das E/A-Ziel einen Fehler meldet.

  Nachdem ein Treiber IWDFUsbTargetPipe2::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 wird aufgerufen und gibt FALSE zurück.

  Continuous Reader werden in UMDF-Versionen 1.9 und höher unterstützt.

Schreiben in eine UMDF-USB-Pipe

Um Daten in eine USB-Ausgabepipe zu schreiben, kann ein UMDF-Treiber zuerst die IWDFIoTarget::FormatRequestForWrite-Methode aufrufen, um eine Schreibanforderung zu erstellen. Anschließend kann der Treiber die IWDFIoRequest::Send-Methode aufrufen, um die Anforderung asynchron zu senden.

Beenden, Leeren und Zurücksetzen einer UMDF-USB-Pipe

Ein UMDF-Treiber kann die folgenden Methoden aufrufen, um eine USB-Pipe zu beenden, zu leeren oder zurückzusetzen:

IWDFUsbTargetPipe::Abort
Sendet synchron eine Anforderung zum Beenden aller ausstehenden Übertragungen an einer USB-Pipe.

IWDFUsbTargetPipe::Flush
Sendet synchron eine Anforderung zum Verwerfen von Daten, die WinUsb gespeichert hat, wenn das Gerät mehr Daten zurückgegeben hat, als der Client angefordert hat.

IWDFUsbTargetPipe::Reset
Sendet synchron eine Anforderung zum Zurücksetzen einer USB-Pipe.

Festlegen einer Richtlinie für eine UMDF-USB-Pipe

Ein UMDF-Treiber kann die IWDFUsbTargetPipe::SetPipePolicy-Methode aufrufen, um das Verhalten zu steuern, das von WinUsb für eine USB-Pipe verwendet wird (z. B. Timeouts, Umgang mit kurzen Paketen und andere Verhaltensweisen).

Behandeln von Pipefehlern

Wenn das USB-Ziel Ihres Treibers eine E/A-Anforderung mit einem Fehler status Wert abschließt, sollte Ihr Treiber die folgenden Schritte ausführen:

1. Rufen Sie IWDFIoTargetStateManagement::Stop auf, wenn das WdfIoTargetCancelSentIo-Flag festgelegt ist. Dieser Aufruf beendet die Pipe und bricht alle zusätzlichen E/A-Anforderungen ab, die der Treiber an das USB-Ziel gesendet hat, wenn das Ziel die Anforderungen nicht abgeschlossen hat.

2. Rufen Sie IWDFUsbTargetPipe::Abort auf, um eine Abbruchanforderung an die Pipe zu senden.

3. Rufen Sie IWDFUsbTargetPipe::Reset auf, um eine Zurücksetzungsanforderung an die Pipe zu senden.

4. Rufen Sie IWDFIoTargetStateManagement::Start auf, um die Pipe neu zu starten.

5. Senden Sie die E/A-Anforderung, bei der ein Fehler aufgetreten ist, und alle E/A-Anforderungen, die auf die fehlgeschlagene Anforderung folgten, erneut.