WdfUsbTargetPipeConfigContinuousReader 関数 (wdfusb.h)

[アーティクル]
08/08/2023

[KMDF と UMDF に適用]

WdfUsbTargetPipeConfigContinuousReader メソッドは、指定された USB パイプから継続的に読み取るフレームワークを構成します。

構文

NTSTATUS WdfUsbTargetPipeConfigContinuousReader(
  [in] WDFUSBPIPE                        Pipe,
  [in] PWDF_USB_CONTINUOUS_READER_CONFIG Config
);

パラメーター

[in] Pipe

WdfUsbInterfaceGetConfiguredPipe を呼び出して取得したフレームワークパイプオブジェクトへのハンドル。

[in] Config

呼び出し元によって割り当てられた WDF_USB_CONTINUOUS_READER_CONFIG 構造体へのポインター。

戻り値

操作が成功した場合、WdfUsbTargetPipeConfigContinuousReader はSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターンコード	説明
STATUS_INFO_LENGTH_MISMATCH	Config パラメーターが指定したWDF_USB_CONTINUOUS_READER_CONFIG構造体のサイズが正しくありません。
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES	メモリが不足していました。
STATUS_INVALID_DEVICE_REQUEST	パイプの種類が無効です。
STATUS_INTEGER_OVERFLOW	Config パラメーターでサイズが大きすぎるか無効であるサイズを指定したWDF_USB_CONTINUOUS_READER_CONFIG構造体の HeaderLength、TransferLength、または TrailerLength メンバー。
STATUS_INVALID_BUFFER_SIZE	読み取りバッファーのサイズが、パイプの最大パケットサイズの倍数ではありません。

WdfUsbTargetPipeConfigContinuousReader メソッドが返す可能性があるその他の戻り値の一覧については、「Framework オブジェクト作成エラー」を参照してください。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクトハンドルを提供すると、バグチェックが発生します。

注釈

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

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

通常、ドライバーは、EvtDevicePrepareHardware コールバック関数内から WdfUsbTargetPipeConfigContinuousReader を呼び出します。ドライバーは、EvtDeviceD0Entry コールバック関数内から WdfIoTargetStart を呼び出し、EvtDeviceD0Exit コールバック関数内から WdfIoTargetStop を呼び出す必要があります。

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

オプションの EvtUsbTargetPipeReadersFailed コールバックを指定しない場合、フレームワークは別の読み取り要求を送信して失敗した読み取り試行に応答します。そのため、バスが読み取りを受け入れていない状態の場合、フレームワークは、失敗した読み取りから回復するための新しい要求を継続的に送信します。

ドライバーが WdfUsbTargetPipeConfigContinuousReader を呼び出した後、ドライバーは WdfUsbTargetPipeReadSynchronously または WdfRequestSend を使用して、継続的リーダーが停止していない限り、パイプに I/O 要求を送信できません。リーダーを停止するために、ドライバーは WdfIoTargetStop を呼び出すか、EvtUsbTargetPipeReadersFailed コールバック関数から FALSE を返します。リーダーの停止中にドライバーが WdfUsbTargetPipeReadSynchronously を呼び出す場合は、RequestOptions パラメーターの Flags メンバーに WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE フラグを設定する必要があります。それ以外の場合、要求はターゲットが再起動されるまでペンで処理されます。

フレームワークは、内部 URB に USBD_SHORT_TRANSFER_OK フラグを設定します。このフラグを設定すると、データ転送の最後のパケットが最大パケットサイズより小さくなります。

WdfUsbTargetPipeConfigContinuousReader メソッドと USB I/O ターゲットの詳細については、「パイプからの読み取り」を参照してください。

例

次のコード例では、 WDF_USB_CONTINUOUS_READER_CONFIG 構造体を初期化し、 WdfUsbTargetPipeConfigContinuousReader を呼び出します。

WDF_USB_CONTINUOUS_READER_CONFIG  contReaderConfig;
NTSTATUS  status;

WDF_USB_CONTINUOUS_READER_CONFIG_INIT(
                                      &contReaderConfig,
                                      OsrFxEvtUsbInterruptPipeReadComplete,
                                      DeviceContext,
                                      sizeof(UCHAR)
                                      );
status = WdfUsbTargetPipeConfigContinuousReader(
                                      Pipe,
                                      &contReaderConfig
                                      );

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfusb.h (Wdfusb.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf)、FailD0EntryIoTargetState(kmdf)、KmdfIrql(kmdf)、KmdfIrql2 (kmdf)、KmdfIrqlExplicit(kmdf)、UsbContReader(kmdf)、UsbKmdfIrql(kmdf)、UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf)