IWDFUsbTargetPipe2::ConfigureContinuousReader メソッド (wudfusb.h)

[アーティクル]
03/05/2024

[警告: 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を返します。それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターンコード	形容
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)	ドライバーは既に USB パイプの連続リーダーを構成しています。 USB パイプは、一括転送または割り込み入力転送用に設定されていません。
E_OUTOFMEMORY	フレームワークのバッファーの割り当てに失敗しました。
ERROR_ARITHMETIC_OVERFLOW	TransferLength、HeaderLength、または TrailerLength パラメーターで、サイズが大きすぎるか無効であることを指定しました。

このメソッドは、Winerror.h に含まれる他の値の 1 つを返す場合があります。

備考

バルクパイプまたは割り込みパイプの連続リーダーを構成できます。パイプには入力エンドポイントが必要です。

ConfigureContinuousReader を呼び出して継続的リーダーを構成した後、ドライバーは IWDFIoTargetStateManagement::Start 呼び出してリーダーを起動する必要があります。リーダーを停止するには、ドライバーは IWDFIoTargetStateManagement::Stop 呼び出す必要があります。

通常、ドライバーは、IPnpCallbackHardware::OnPrepareHardware コールバック関数内から ConfigureContinuousReader を呼び出します。ドライバーは、IPnpCallback::OnD0Entry コールバック関数内から IWDFIoTargetStateManagement::Start を呼び出し、IWDFIoTargetStateManagement::Stop を IPnpCallback::OnD0Exit コールバック関数内から呼び出す必要があります。

パイプの I/O ターゲットが正常に読み取り要求を完了するたびに、フレームワークはドライバーの IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion コールバック関数を呼び出します。要求の処理中に I/O ターゲットからエラーが報告された場合、フレームワークは、すべての読み取り要求が完了した後、ドライバーの IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure コールバック関数を呼び出します。 (したがって、OnReaderCompletion コールバック関数は、OnReaderFailure コールバック関数の実行中は呼び出されません)。

NumPendingReads パラメーターの値を選択するには、次のガイドラインに従います。

ドライバー フレームワークの既定値を使用する場合は、numPendingReads を 0 に設定します。
既定値は 1 より大きく、多くのプロセッサ構成の多くのデバイスに対して適切なパフォーマンスを提供します。
ドライバー デバイスがデータを配信する正確な順序でデータバッファーを受信することが重要な場合は、numPendingReads を 1 に設定します。
フレームワークが複数の読み取り要求をキューに入れる場合、ドライバーは、デバイスがデータを配信する順序と同じデータバッファーを受信しない可能性があります。
NumPendingReads を、徹底的なパフォーマンス測定に基づいて、デバイスのパフォーマンス要件を満たす数値に設定します。
まず、numPendingReads の既定値 (0)デバイスをテストします。テストには、さまざまな種類とプロセッサ数、さまざまな USB ホストコントローラーと USB 構成など、さまざまなハードウェア構成を含める必要があります。その後、同じテストを使用して、より高い値を試すことができます。より高い値を必要とする可能性のあるドライバーは、割り込み速度が高いデバイスの場合であり、割り込みが迅速に処理されない場合にデータが失われる可能性があります。

NumPendingReads 値が大きすぎると、システムのパフォーマンスが低下する可能性があります。パフォーマンス要件を満たす最小値を使用する必要があります。通常、3 または 4 より大きい値では、データスループットは向上しません。ただし、値を大きくすると、高周波パイプの待機時間やデータが欠落する可能性が低下する可能性があります。

ドライバーが ConfigureContinuousReaderを呼び出した後、ドライバーは IWDFIoRequest::Send を使用して I/O 要求をパイプに送信することはできません。ただし、ドライバーの IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure コールバック関数が呼び出され、FALSE 返されます。

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
ヘッダー	wudfusb.h (Wudfusb.h を含む)
DLL	WUDFx.dll

次の方法で共有

IWDFUsbTargetPipe2::ConfigureContinuousReader メソッド (wudfusb.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース