WdfUsbTargetPipeConfigContinuousReader-Funktion (wdfusb.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfUsbTargetPipeConfigContinuousReader-Methode konfiguriert das Framework so, dass kontinuierlich aus einer angegebenen USB-Pipe gelesen wird.

Syntax

NTSTATUS WdfUsbTargetPipeConfigContinuousReader(
  [in] WDFUSBPIPE                        Pipe,
  [in] PWDF_USB_CONTINUOUS_READER_CONFIG Config
);

Parameter

[in] Pipe

Ein Handle für ein Framework-Pipeobjekt, das durch Aufrufen von WdfUsbInterfaceGetConfiguredPipe abgerufen wurde.

[in] Config

Ein Zeiger auf eine vom Aufrufer zugeordnete WDF_USB_CONTINUOUS_READER_CONFIG-Struktur .

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_INFO_LENGTH_MISMATCH	Die Größe der WDF_USB_CONTINUOUS_READER_CONFIG Struktur, die vom Config-Parameter angegeben wurde, war falsch.
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_INSUFFICIENT_RESOURCES	Es war nicht genügend Arbeitsspeicher verfügbar.
STATUS_INVALID_DEVICE_REQUEST	Der Typ der Pipe war ungültig.
STATUS_INTEGER_OVERFLOW	Der HeaderLength-, TransferLength- oder TrailerLength-Member des WDF_USB_CONTINUOUS_READER_CONFIG Struktur, dass der Config-Parameter eine Größe angegeben hat, die zu groß oder anderweitig ungültig war.
STATUS_INVALID_BUFFER_SIZE	Die Größe des Lesepuffers war kein Vielfaches der maximalen Paketgröße der Pipe.

Eine Liste mit anderen Rückgabewerten, die von der WdfUsbTargetPipeConfigContinuousReader-Methode möglicherweise zurückgegeben werden, finden Sie unter Fehler bei der Erstellung von Frameworkobjekten.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

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

Nach dem Aufrufen von WdfUsbTargetPipeConfigContinuousReader zum Konfigurieren eines fortlaufenden Readers muss Ihr Treiber WdfIoTargetStart aufrufen, um den Reader zu starten. Um den Reader zu beenden, muss der Treiber WdfIoTargetStop aufrufen.

In der Regel ruft ein Treiber WdfUsbTargetPipeConfigContinuousReader aus seiner EvtDevicePrepareHardware-Rückruffunktion auf. Der Treiber sollte WdfIoTargetStart aus seiner EvtDeviceD0Entry-Rückruffunktion und WdfIoTargetStop aus seiner EvtDeviceD0Exit-Rückruffunktion aufrufen.

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

Wenn Sie den optionalen EvtUsbTargetPipeReadersFailed-Rückruf nicht bereitstellen, reagiert das Framework auf einen fehlgeschlagenen Leseversuch, indem es eine weitere Leseanforderung sendet. Wenn sich der Bus also in einem Zustand befindet, in dem er keine Lesevorgänge akzeptiert, sendet das Framework ständig neue Anforderungen zur Wiederherstellung nach einem fehlgeschlagenen Lesevorgang.

Nachdem ein Treiber WdfUsbTargetPipeConfigContinuousReader aufgerufen hat, kann der Treiber WdfUsbTargetPipeReadSynchronously oder WdfRequestSend nicht verwenden, um E/A-Anforderungen an die Pipe zu senden, es sei denn, der fortlaufende Reader wurde beendet. Um den Reader zu beenden, kann der Treiber WdfIoTargetStop aufrufen oder FALSE von seiner EvtUsbTargetPipeReadersFailed-Rückruffunktion zurückgeben. Wenn der Treiber WdfUsbTargetPipeReadSynchronly aufruft , während der Reader angehalten wird, muss er das flag WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE im Flags-Member des RequestOptions-Parameters festlegen. Andernfalls wird die Anforderung mit dem Stift versehen, bis das Ziel neu gestartet wird.

Das Framework legt das flag USBD_SHORT_TRANSFER_OK in seiner internen URB fest. Durch Festlegen dieses Flags kann das letzte Paket einer Datenübertragung kleiner als die maximale Paketgröße sein.

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

Beispiele

Im folgenden Codebeispiel wird eine WDF_USB_CONTINUOUS_READER_CONFIG-Struktur initialisiert und WdfUsbTargetPipeConfigContinuousReader aufgerufen.

WDF_USB_CONTINUOUS_READER_CONFIG  contReaderConfig;
NTSTATUS  status;

WDF_USB_CONTINUOUS_READER_CONFIG_INIT(
                                      &contReaderConfig,
                                      OsrFxEvtUsbInterruptPipeReadComplete,
                                      DeviceContext,
                                      sizeof(UCHAR)
                                      );
status = WdfUsbTargetPipeConfigContinuousReader(
                                      Pipe,
                                      &contReaderConfig
                                      );

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfusb.h (wdfusb.h einschließen)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbContReader(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)