WdfUsbTargetPipeConfigContinuousReader 函式 (wdfusb.h)

發行項
03/01/2024

[適用於 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。否則，此方法可以傳回下列其中一個值：

傳回碼	Description
STATUS_INFO_LENGTH_MISMATCH	指定 Config 參數的WDF_USB_CONTINUOUS_READER_CONFIG結構大小不正確。
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_INSUFFICIENT_RESOURCES	記憶體不足。
STATUS_INVALID_DEVICE_REQUEST	管道的類型無效。
STATUS_INTEGER_OVERFLOW	Config 參數指定大小太大或無效之WDF_USB_CONTINUOUS_READER_CONFIG結構的 HeaderLength、TransferLength 或 TrailerLength 成員。
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 要求傳送至管道。若要停止讀取器，驅動程式可以從其 EvtUsbTargetPipeReadersFailed 回呼函式呼叫 WdfIoTargetStop 或傳回 FALSE。如果驅動程式在讀取器停止時呼叫 WdfUsbTargetPipeReadSynchronous，則必須在 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
                                      );

規格需求

需求	值
目標平台	Universal
最小 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)