WdfUsbTargetPipeConfigContinuousReader 函式（wdfusb.h）

發行項
02/07/2025

[適用於 KMDF 和 UMDF]

WdfUsbTargetPipeConfigContinuousReader 方法會將架構設定為從指定的 USB 管道持續讀取。

語法

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

參數

[in] Pipe

呼叫 WdfUsbInterfaceGetConfiguredPipe 取得之架構管道物件的句柄。

[in] Config

呼叫端配置的 WDF_USB_CONTINUOUS_READER_CONFIG 結構的指標。

傳回值

WdfUsbTargetPipeConfigContinuousReader 如果作業成功，就會傳回STATUS_SUCCESS。否則，這個方法可以傳回下列其中一個值：

傳回碼	描述
STATUS_INFO_LENGTH_MISMATCH	Config 參數所指定之 WDF_USB_CONTINUOUS_READER_CONFIG 結構的大小不正確。
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_INSUFFICIENT_RESOURCES	記憶體不足。
STATUS_INVALID_DEVICE_REQUEST	管道的類型無效。
STATUS_INTEGER_OVERFLOW	HeaderLength、TransferLength或 TrailerLengthWDF_USB_CONTINUOUS_READER_CONFIG 結構的成員，Config 參數指定了太大或無效的大小。
STATUS_INVALID_BUFFER_SIZE	讀取緩衝區的大小不是管道封包大小上限的倍數。

如需 WdfUsbTargetPipeConfigContinuousReader 方法可能會傳回的其他傳回值清單，請參閱 Framework 物件建立錯誤。

此方法也可能傳回其他NTSTATUS 值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

言論

您可以設定大量管道或中斷管道的連續讀取器。管道必須有輸入端點。

呼叫 WdfUsbTargetPipeConfigContinuousReader 以設定連續讀取器之後，驅動程式必須呼叫 WdfIoTargetStart 來啟動讀取器。若要停止讀取器，驅動程式必須呼叫 WdfIoTargetStop。

一般而言，驅動程式會從其 EvtDevicePrepareHardware 函式內呼叫 WdfUsbTargetPipeConfigContinuousReader。驅動程式應該從其 EvtDeviceD0Entry 回呼函式內呼叫 WdfIoTargetStart，而且應該從其 EvtDeviceD0Exit 回呼函式內呼叫 WdfIoTargetStop。

每次管道的 I/O 目標成功完成讀取要求時，架構都會呼叫驅動程式的 EvtUsbTargetPipeReadComplete 回呼函式。如果 I/O 目標在處理要求時回報失敗，架構會在所有讀取要求完成後呼叫驅動程式的 EvtUsbTargetPipeReadersFailed 回呼函式。因此，EvtUsbTargetPipeReadComplete 回呼函式將不會呼叫，而執行 EvtUsbTargetPipeReadersFailed 回呼函式）。

如果您沒有提供選擇性 EvtUsbTargetPipeReadersFailed 回呼，架構會藉由傳送另一個讀取要求來回應失敗的讀取嘗試。因此，如果總線處於不接受讀取的狀態，架構會持續傳送新的要求，以從失敗的讀取中復原。

在驅動程式呼叫 WdfUsbTargetPipeConfigContinuousReader之後，除非連續讀取器已停止，否則驅動程式無法使用 WdfUsbTargetPipeReadSynchronously 或 WdfRequestSend 將 I/O 要求傳送至管道。若要停止讀取器，驅動程式可以呼叫 WdfIoTargetStop，或從其 EvtUsbTargetPipeReadersFailed 回呼函式傳回 FALSE。如果驅動程式在讀取器停止時呼叫 WdfUsbTargetPipeReadSynchronously，則必須在 RequestOptions 參數的 Flags 成員中設定WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE旗標。否則，要求會掛號，直到目標重新啟動為止。

架構會在其內部 URB中設定USBD_SHORT_TRANSFER_OK旗標。設定此旗標可讓數據傳輸的最後一個封包小於封包大小上限。

如需 WdfUsbTargetPipeConfigContinuousReader 方法和 USB I/O 目標的詳細資訊，請參閱從管道讀取。

例子

下列程式代碼範例會初始化 WDF_USB_CONTINUOUS_READER_CONFIG 結構，並呼叫 WdfUsbTargetPipeConfigContinuousReader。

WDF_USB_CONTINUOUS_READER_CONFIG  contReaderConfig;
NTSTATUS  status;

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

要求

要求	價值
目標平臺	普遍
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
標頭	wdfusb.h （包括 Wdfusb.h）
連結庫	Wdf01000.sys （KMDF）：WUDFx02000.dll （UMDF）
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate（kmdf），FailD0EntryIoTargetState（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf），UsbContReader（kmdf），UsbKmdfIrql（kmdf），UsbKmdfIrql2（kmdf），UsbKmdfIrqlExplicit（kmdf）