次の方法で共有

UMDF 1.x ドライバーでの USB パイプの操作

  • [アーティクル]

警告

UMDF 2 は UMDF の最新バージョンであり、UMDF 1 よりも優先されます。 すべての新しい UMDF ドライバーは、UMDF 2 を使用して記述する必要があります。 UMDF 1 には新機能が追加されておらず、Windows 10 の新しいバージョンでは UMDF 1 のサポートが制限されています。 ユニバーサル Windows ドライバーでは、UMDF 2 を使用する必要があります。

アーカイブされた UMDF 1 サンプルは、「Windows 11, バージョン 22H2 - 2022 年 5 月 ドライバーサンプルの更新」でご確認いただけます。

詳しくは、「UMDF の概要」をご覧ください。

フレームワークは、USB インターフェイス内の各パイプをフレームワーク USB パイプ オブジェクトとして表します。 ドライバーが USB デバイスを構成すると、フレームワークは、選択した各インターフェイスの各パイプのフレームワーク USB パイプ オブジェクトを作成します。 パイプ オブジェクト メソッドを使用すると、ドライバーは次の処理を実行できます。

UMDF-USB パイプ情報の取得

UMDF ドライバーが IWDFUsbInterface::RetrieveUsbPipeObject メソッドを呼び出して USB パイプ オブジェクトの IWDFUsbTargetPipe インターフェイスへのポインターを取得した後、ドライバーは USB パイプ に関する情報を取得するために USB パイプ オブジェクトが定義する次のメソッドを呼び出すことができます。

IWDFUsbTargetPipe::GetInformation
USB パイプとそのエンドポイントに関する情報を取得します。

IWDFUsbTargetPipe::GetType
USB パイプの型を返します。

IWDFUsbTargetPipe::IsInEndPoint
USB パイプが入力エンドポイントに接続されているかどうかを判断します。

IWDFUsbTargetPipe::IsOutEndPoint
USB パイプが出力エンドポイントに接続されているかどうかを判断します。

IWDFUsbTargetPipe::RetrievePipePolicy
WinUsb パイプ ポリシーを取得します。

UMDF-USB パイプからの読み取り

USB 入力パイプからデータを読み取るために、ドライバーは次のいずれかの方法 (または両方) を使用できます。

  • データを同期的に読み取る。

    USB 入力パイプからデータを同期的に読み取るために、UMDF ドライバーは最初に IWDFIoTarget::FormatRequestForRead メソッドを呼び出して読み取り要求を作成します。 その後、ドライバーは IWDFIoRequest::Send メソッドを呼び出し、WDF_REQUEST_Standard Edition ND_OPTION_SYNCHRONOUS フラグを指定して要求を同期的に送信します。

  • データを非同期的に読み取る。

    USB 入力パイプからデータを非同期的に読み取るために、UMDF ドライバーは最初に IWDFIoTarget::FormatRequestForRead メソッドを呼び出して読み取り要求を作成します。 その後、ドライバーは、WDF_REQUEST_Standard Edition ND_OPTION_SYNCHRONOUS フラグを指定せずに IWDFIoRequest::Send メソッドを呼び出します。

  • データを同期的かつ継続的に読み取る。

    連続リーダーは、USB パイプで常に読み取り要求を使用できるようにするフレームワークによって提供されるメカニズムです。 このメカニズムにより、非同期の要求されていない入力ストリームを提供するデバイスからドライバーが常にデータを受信する準備が整っていることを保証します。 たとえば、ネットワーク インターフェイス カード (NIC) のドライバーは、入力データを受信するために連続リーダーを使用する場合があります。

    入力パイプの連続リーダーを構成するには、ドライバーの IPnpCallbackHardware::OnPrepareHardware コールバック関数が IWDFUsbTargetPipe2::ConfigureContinuousReader メソッドを呼び出す必要があります。 このメソッドは、デバイスの I/O ターゲットに対する一連の読み取り要求をキューに入れます。

    また、ドライバーの IPnpCallback::OnD0Entry コールバック関数は IWDFIoTargetStateManagement::Start を呼び出して連続リーダーを開始する必要があり、ドライバーの IPnpCallback::OnD0Exit コールバック関数は IWDFIoTargetStateManagement::Stop を呼び出して連続リーダーを停止する必要があります。

    デバイスからデータが使用可能になるたびに、I/O ターゲットは読み取り要求を完了し、フレームワークは 2 つのコールバック関数のいずれかを呼び出します。I/O ターゲットがデータを正常に読み取った場合は IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion、I/O ターゲットがエラーを報告する場合は IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure です。

    ドライバーが IWDFUsbTargetPipe2::ConfigureContinuousReader を呼び出した後、ドライバーは IWDFIoRequest::Send を使用して、ドライバーの IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure コールバック関数を呼び出して FALSE を返さない限り、パイプに I/O 要求を送信できませんStandard Edition。

    継続的リーダーは、UMDF バージョン 1.9 以降でサポートされています。

UMDF-USB パイプへの書き込み

USB 出力パイプにデータを書き込むには、UMDF ドライバーは最初に IWDFIoTarget::FormatRequestForWrite メソッドを呼び出して書き込み要求を作成できます。 その後で、ドライバーは IWDFIoRequest::Send メソッドを呼び出して、要求を同期的または非同期的に送信できます。

UMDF-USB パイプの停止、フラッシュ、リセット

UMDF ドライバーは、USB パイプを停止、フラッシュ、またはリセットする次のメソッドを呼び出すことができます。

IWDFUsbTargetPipe::Abort
USB パイプで保留中のすべての転送を停止する要求を同期的に送信します。

IWDFUsbTargetPipe::Flush
同期的に要求を送信してカードデバイスがクライアント要求よりも多くのデータを返したときに WinUsb が保存したすべてのデータを削除します。

IWDFUsbTargetPipe::Reset
USB パイプをリセットする要求を同期的に送信します。

UMDF USB パイプのポリシーの設定

UMDF ドライバーは IWDFUsbTargetPipe::SetPipePolicy メソッドを呼び出して、USB パイプに対して WinUsb によって使用される動作 (タイムアウト、短いパケットの処理、その他の動作など) を制御できます。

パイプ エラー処理

ドライバーの USB ターゲットがエラー状態の値で I/O 要求を完了 した場合、ドライバーは次の操作を行う必要があります。

  1. WdfIoTargetCancelSentIo フラグを設定して IWDFIoTargetStateManagement::Stop を呼び出します。 ターゲットが要求を完了していない場合、この呼び出しは、パイプを停止し、ドライバーが USB ターゲットに送信した追加の I/O 要求を取り消します。

  2. IWDFUsbTargetPipe::Abort を呼び出して、パイプに中止要求を送信します。

  3. IWDFUsbTargetPipe::Reset を呼び出して、パイプにリセット要求を送信します。

  4. IWDFIoTargetStateManagement::Start を呼び出してパイプを再起動します。

  5. 失敗した I/O 要求と、失敗した要求に続くすべての I/O 要求を再送信します。