IWDFUsbTargetPipe2：：ConfigureContinuousReader 方法 (wudfusb.h)
[警告： UMDF 2 是最新版的 UMDF，並取代 UMDF 1。 所有新的 UMDF 驅動程式都應該使用 UMDF 2 來撰寫。 未將新功能新增至 UMDF 1，且較新版本的 #D27BB84C6A514455EB87900769CEC6865 上不支援 UMDF 1。 通用 Windows 驅動程式必須使用 UMDF 2。 如需詳細資訊，請參閱使用 UMDF 使用者入門。]
ConfigureContinuousReader 方法會將架構設定為從 USB 管道持續讀取。
語法
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
);
參數
[in] TransferLength
可從裝置接收的數據長度上限，以位元組為單位。
[in] HeaderLength
從裝置接收數據的緩衝區中，以位元組為單位的位移。 架構會從裝置的數據儲存在讀取緩衝區中，從位移值開始。 換句話說，此空間位於 TransferLength 大小的空間之前，架構會儲存來自裝置的數據。
[in] TrailerLength
尾端緩衝區空間的長度，以位元組為單位。 此空間會遵循 TransferLength 大小的空間，其中架構會儲存來自裝置的數據。
[in] NumPendingReads
架構將排入佇列以從 I/O 目標接收資料的讀取要求數目。 如果此值為零，架構會使用預設數目的讀取要求。 如果指定的值大於允許的最大值，架構會使用允許的最大值。 如需 NumPendingReads 參數的詳細資訊，請參閱下列一節。
[in, optional] pMemoryCleanupCallbackInterface
架構用來存取選擇性 IObjectCleanup：：OnCleanup 回呼函式的驅動程式提供的 IUnkown 介面指標。 當架構解除分配讀取緩衝區以處理連續讀取作業時，架構會呼叫回呼函式。 此參數是選擇性的，可以是 NULL。
[in] pOnCompletion
驅動程式提供的 IUsbTargetPipeContinuousReaderCallbackReadComplete 介面的指標，提供 OnReaderCompletion 回呼函式。
[in, optional] pCompletionContext
架構傳遞至驅動程式 IUsbTargetPipeContinuousReaderCallbackReadComplete：：OnReaderCompletion 回呼函式的驅動程式定義內容資訊不具類型的指標。
[in, optional] pOnFailure
驅動程式提供的 IUsbTargetPipeContinuousReaderCallbackReadersFailed 介面指標，提供 OnReaderFailure 回呼函式。
傳回值
ConfigureContinuousReader 會在作業成功時傳回S_OK。 否則，此方法可以傳回下列其中一個值：
| 傳回碼 | Description |
|---|---|
|
驅動程式已經為 USB 管道設定連續讀取器。
USB 管道未設定大量或中斷輸入傳輸。 |
|
架構嘗試配置緩衝區失敗。 |
|
TransferLength、HeaderLength 或 TrailerLength 參數指定了太大或無效的大小。 |
這個方法可能會傳回 Winerror.h 包含的其他其中一個值。
備註
您可以為大量管道或中斷管道設定連續讀取器。 管道必須有輸入端點。
呼叫 ConfigureContinuousReader 以設定連續讀取器之後，您的驅動程式必須呼叫 IWDFIoTargetStateManagement：：Start 來啟動讀取器。 若要停止讀取器，驅動程式必須呼叫 IWDFIoTargetStateManagement：：Stop。
一般而言，驅動程式會從其 IPnpCallbackHardware：：OnPrepareHardware 回呼函式內呼叫 ConfigureContinuousReader。 驅動程式應該從 IPnpCallback：：OnD0Entry 回呼函式內呼叫 IWDFIoTargetStateManagement：：Stop，從其 IPnpCallback：：OnD0Exit 回呼函式內呼叫 IWDFIoTargetStateManagement：：Start。
每次管道的 I/O 目標成功完成讀取要求時，架構都會呼叫驅動程式的 IUsbTargetPipeContinuousReaderCallbackReadComplete：：OnReaderCompletion 回呼函式。 如果 I/O 目標在處理要求時回報失敗，架構會在所有讀取要求完成後呼叫驅動程式的 IUsbTargetPipeContinuousReaderCallbackReadersFailed：：OnReaderFailure 回呼函式。 (因此，在 OnReaderFailure 回呼函式正在執行時，將不會呼叫 OnReaderCompletion 回呼函式。)
使用下列指導方針來選擇 NumPendingReads 參數的值：
-
如果您希望驅動程式使用架構的預設值，請將 NumPendingReads 設定為零。
默認值大於一，且在許多處理器組態上為許多裝置提供合理的良好效能。
-
如果驅動程式以裝置傳遞數據的正確順序接收數據緩衝區，請將 NumPendingReads 設定為一。
如果架構將多個讀取要求排入佇列，驅動程式可能不會依照裝置傳遞數據的順序接收數據緩衝區。
-
根據完整的效能測量，將 NumPendingReads 設定為符合裝置效能需求的數位。
首先，使用 NumPendingReads 的預設值 (0) 測試您的裝置。 您的測試應該包含各種硬體組態，包括不同類型的處理器和數目，以及不同的USB主機控制器和USB組態。 然後，您可以使用相同的測試，以較高的值進行實驗。 可能需要較高值的驅動程式是具有高中斷率之裝置的驅動程式，其中如果中斷未快速服務，可能會遺失數據。
驅動程式呼叫 ConfigureContinuousReader 之後，除非呼叫驅動程式的 IUsbTargetPipeContinuousReaderCallbackReadersFailed：：OnReaderFailure 回呼函式，否則驅動程式無法使用 IWDFIoRequest：：Send 將 I/O 要求傳送至管道。
如需 ConfigureContinuousReader 方法和 USB I/O 目標的詳細資訊，請參閱 從 UMDF-USB 管道讀取。
範例
下列程式代碼範例會設定連續讀取器。 在此範例中，緩衝區大小上限是驅動程式定義緩衝區的大小。 標頭和預告片緩衝區位移會設定為零，而擱置的讀取作業數目會設定為兩個。 此範例會針對 pCompletionContext 參數使用目標管道的介面指標，因此 OnReaderCompletion 回呼函式可以判斷讀取作業已完成的管道。
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
);
...
規格需求
| 需求 | 值 |
|---|---|
| 終止支援 | UMDF 2.0 和更新版本中無法使用。 |
| 目標平台 | 桌面 |
| 最低UMDF版本 | 1.9 |
| 標頭 | wudfusb.h (包括 Wudfusb.h) |
| Dll | WUDFx.dll |
另請參閱
IPnpCallbackHardware：：OnPrepareHardware
IUsbTargetPipeContinuousReaderCallbackReadComplete：：OnReaderCompletion
IUsbTargetPipeContinuousReaderCallbackReadersFailed：：OnReaderFailure
IWDFIoTargetStateManagement：：Start