UMDF での USB パイプの操作
フレームワークは、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 入力パイプからデータを読み取るために、ドライバーは次の方法を使用できます。
データを同期的に読み取る。
UMDF ドライバーで USB 入力パイプからデータを同期的に読み取るには、まず、IWDFIoTarget::FormatRequestForRead メソッドを呼び出して読み取り要求を作成します。次に、WDF_REQUEST_SEND_OPTION_SYNCHRONOUS フラグを指定して IWDFIoRequest::Send メソッドを呼び出し、その要求を同期的に送信します。
データを非同期的に読み取る。
UMDF ドライバーで USB 入力パイプからデータを非同期的に読み取るには、まず、IWDFIoTarget::FormatRequestForRead メソッドを呼び出して読み取り要求を作成します。次に、WDF_REQUEST_SEND_OPTION_SYNCHRONOUS フラグを指定せずに IWDFIoRequest::Send メソッドを呼び出します。
データを同期的に連続して読み取る。
"連続的なリーダー" とは、フレームワークで提供されるメカニズムであり、USB パイプで読み取り要求を常に使用できるようにします。**このメカニズムにより、ドライバーは、要求されていない非同期の入力ストリームを提供するデバイスからいつでもデータを受信できる状態になります。たとえば、ネットワーク インターフェイス カード (NIC) のドライバーは、連続的なリーダーを使用して入力データを受信します。
入力パイプの連続的なリーダーを構成するために、ドライバーの IPnpCallbackHardware::OnPrepareHardware コールバック関数は IWDFUsbTargetPipe2::ConfigureContinuousReader メソッドを呼び出す必要があります。このメソッドは、デバイスの I/ O ターゲットへの一連の読み取り要求をキューに入れます。
また、ドライバーの IPnpCallback::OnD0Entry コールバック関数は IWDFIoTargetStateManagement::Start を呼び出して連続的なリーダーを開始し、ドライバーの IPnpCallback::OnD0Exit コールバック関数は IWDFIoTargetStateManagement::Stop を呼び出して連続的なリーダーを停止する必要があります。
データがデバイスから取得されるたびに、I/O ターゲットは読み取り要求を完了し、フレームワークは次の 2 つのコールバック関数の 1 つを呼び出します。I/O ターゲットがデータを正常に読み取った場合は IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion を呼び出し、I/O ターゲットがエラーを報告した場合は IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure を呼び出します。
ドライバーが IWDFUsbTargetPipe2::ConfigureContinuousReader を呼び出した後、ドライバーの IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure コールバック関数が呼び出され、FALSE を返さない限り、IWDFIoRequest::Send を使用してパイプに I/O 要求を送信することはできません。
連続的なリーダーは version 1.9 以降の UMDF でサポートされています。
UMDF-USB パイプへの書き込み
UMDF ドライバーで USB 出力パイプにデータを書き込むには、まず、IWDFIoTarget::FormatRequestForWrite メソッドを呼び出して書き込み要求を作成します。次に、IWDFIoRequest::Send メソッドを呼び出して、その要求を非同期的に送信します。
UMDF-USB パイプの停止、フラッシュ、およびリセット
UMDF ドライバーは次のメソッドを呼び出して、USB パイプを停止、フラッシュ、またはリセットできます。
IWDFUsbTargetPipe::Abort
USB パイプの保留中の転送をすべて停止するための要求を同期的に送信します。IWDFUsbTargetPipe::Flush
クライアントの要求より多くのデータがデバイスから返された場合に WinUsb が保存したデータを破棄するための要求を同期的に送信します。IWDFUsbTargetPipe::Reset
USB パイプをリセットするための要求を同期的に送信します。
UMDF-USB パイプのポリシーの設定
UMDF ドライバーで IWDFUsbTargetPipe::SetPipePolicy メソッドを呼び出すと、WinUsb の USB パイプに対する動作 (タイムアウト、短いパケットの処理、その他の動作など) を制御できます。
パイプ エラーの処理
ドライバーの USB ターゲットがエラー状態の値で I/O 要求を完了した場合、ドライバーは次の処理を実行する必要があります。
WdfIoTargetCancelSentIo フラグを設定して IWDFIoTargetStateManagement::Stop を呼び出します。これにより、パイプが停止され、ドライバーが USB ターゲットに送信した追加の I/O 要求が取り消されます (まだ完了していない場合)。
IWDFUsbTargetPipe::Abort を呼び出して、中止要求をパイプに送信します。
IWDFUsbTargetPipe::Reset を呼び出して、リセット要求をパイプに送信します。
IWDFIoTargetStateManagement::Start を呼び出して、パイプを再起動します。
失敗した I/O 要求、および失敗した要求の後のすべての I/O 要求を再送信します。