IWDFUsbTargetPipe2::ConfigureContinuousReader メソッド (wudfusb.h)
[警告: UMDF 2 は UMDF の最新バージョンであり、UMDF 1 よりも優先されます。 すべての新しい UMDF ドライバーは、UMDF 2 を使用して記述する必要があります。 UMDF 1 には新機能が追加されておらず、新しいバージョンのWindows 10では 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 ターゲットからデータを受信するためにフレームワークがキューに登録する読み取り要求の数。 この値が 0 の場合、フレームワークは既定の数の読み取り要求を使用します。 指定した値が許可された最大値より大きい場合、フレームワークでは許可された最大値が使用されます。 NumPendingReads パラメーターの詳細については、次の「解説」セクションを参照してください。
[in, optional] pMemoryCleanupCallbackInterface
フレームワークがオプションの IObjectCleanup::OnCleanup コールバック関数にアクセスするために使用する、ドライバー提供の IUnkown インターフェイスへのポインター。 フレームワークは、継続的な読み取り操作を処理するために作成された読み取りバッファーの割り当てを解除すると、コールバック関数を呼び出します。 このパラメーターは省略可能であり、 NULL にすることができます。
[in] pOnCompletion
OnReaderCompletion コールバック関数を提供する、ドライバーが提供する IUsbTargetPipeContinuousReaderCallbackReadComplete インターフェイスへのポインター。
[in, optional] pCompletionContext
フレームワークがドライバーの IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion コールバック関数に渡す、ドライバー定義のコンテキスト情報への型指定されていないポインター。
[in, optional] pOnFailure
OnReaderFailure コールバック関数を提供する、ドライバーが提供する IUsbTargetPipeContinuousReaderCallbackReadersFailed インターフェイスへのポインター。
戻り値
ConfigureContinuousReader は 、操作が成功した場合にS_OKを返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。
| リターン コード | 説明 |
|---|---|
|
ドライバーは、USB パイプ用の連続リーダーを既に構成しています。
USB パイプは、バルクまたは割り込み入力転送用に設定されていません。 |
|
バッファーを割り当てるフレームワークの試行が失敗しました。 |
|
TransferLength、HeaderLength、または TrailerLength パラメーターで、サイズが大きすぎるか無効であることを指定しました。 |
このメソッドは、Winerror.h に含まれる他の値のいずれかを返す場合があります。
注釈
バルク パイプまたは割り込みパイプの連続リーダーを構成できます。 パイプには入力エンドポイントが必要です。
ConfigureContinuousReader を呼び出して継続的リーダーを構成した後、ドライバーは IWDFIoTargetStateManagement::Start を呼び出してリーダーを起動する必要があります。 リーダーを停止するには、ドライバーで IWDFIoTargetStateManagement::Stop を呼び出す必要があります。
通常、ドライバーは IPnpCallbackHardware::OnPrepareHardware コールバック関数内から ConfigureContinuousReader を呼び出します。 ドライバーは、IPnpCallback::OnD0Entry コールバック関数内から IWDFIoTargetStateManagement::Start を呼び出し、IPnpCallback::OnD0Exit コールバック関数内から IWDFIoTargetStateManagement::Stop を呼び出す必要があります。
パイプの I/O ターゲットが正常に読み取り要求を完了するたびに、フレームワークはドライバーの IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion コールバック関数を呼び出します。 要求の処理中に I/O ターゲットからエラーが報告された場合、フレームワークは、すべての読み取り要求が完了した後、ドライバーの IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure コールバック関数を呼び出します。 (そのため、OnReaderFailure コールバック関数の実行中は、OnReaderCompletion コールバック関数は呼び出されません)。
NumPendingReads パラメーターの値を選択するには、次のガイドラインを使用します。
-
ドライバーでフレームワークの既定値を使用する場合は、 NumPendingReads を 0 に設定します。
既定値は 1 より大きく、多くのプロセッサ構成の多くのデバイスに対して合理的に優れたパフォーマンスを提供します。
-
デバイスがデータを配信する正確な順序でドライバーがデータ バッファーを受信することが重要な場合は、 NumPendingReads を 1 に設定します。
フレームワークが複数の読み取り要求をキューに入れる場合、ドライバーはデバイスがデータを配信する順序と同じ順序でデータ バッファーを受信しない可能性があります。
-
NumPendingReads を、徹底的なパフォーマンス測定に基づいて、デバイスのパフォーマンス要件を満たす数値に設定します。
まず、 NumPendingReads の既定値 (0) でデバイスをテストします。 テストには、さまざまな種類と数のプロセッサ、さまざまな USB ホスト コントローラーと USB 構成など、さまざまなハードウェア構成が含まれている必要があります。 その後、同じテストを使用して、より高い値を試すことができます。 より高い値を必要とする可能性があるドライバーは、割り込み速度が高いデバイスでは 1 つであり、割り込みが迅速に処理されない場合にデータが失われる可能性があります。
ドライバーが ConfigureContinuousReader を呼び出した後は、ドライバーの IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure コールバック関数が呼び出され、FALSE が返されない限り、ドライバーは IWDFIoRequest::Send を使用してパイプに I/O 要求を送信できません。
ConfigureContinuousReader メソッドと USB I/O ターゲットの詳細については、「UMDF-USB パイプからの読み取り」を参照してください。
例
次のコード例では、継続的リーダーを構成します。 この例では、最大バッファー サイズはドライバー定義バッファーのサイズです。 ヘッダーとトレーラーのバッファー オフセットは 0 に設定され、保留中の読み取り操作の数は 2 に設定されます。 この例では、 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 |
| Header | wudfusb.h (Wudfusb.h を含む) |
| [DLL] | WUDFx.dll |
こちらもご覧ください
IPnpCallbackHardware::OnPrepareHardware
IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion
IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure
IWDFIoTargetStateManagement::Start