WdfUsbTargetPipeResetSynchronously 関数 (wdfusb.h)

[アーティクル]
07/16/2024

[KMDF と UMDF に適用]

WdfUsbTargetPipeResetSynchronously メソッドはリセット要求をビルドし、指定された USB パイプに同期的に送信します。

構文

NTSTATUS WdfUsbTargetPipeResetSynchronously(
  [in]           WDFUSBPIPE                Pipe,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions
);

パラメーター

[in] Pipe

WdfUsbInterfaceGetConfiguredPipe 呼び出すことによって取得されたフレームワークパイプオブジェクトへのハンドル。

[in, optional] Request

フレームワーク要求オブジェクトへのハンドル。このパラメーターは省略可能であり、NULL できます。詳細については、次の「解説」セクションを参照してください。

[in, optional] RequestOptions

要求のオプションを指定する呼び出し元によって割り当てられた WDF_REQUEST_SEND_OPTIONS 構造体へのポインター。このポインターは省略可能であり、NULL できます。詳細については、次の「解説」セクションを参照してください。

戻り値

WdfUsbTargetPipeResetSynchronously 操作が成功した場合、USB I/O ターゲットの完了状態値を返します。それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターンコード	形容
STATUS_INFO_LENGTH_MISMATCH	RequestOptions パラメーターが指定した WDF_REQUEST_SEND_OPTIONS 構造体のサイズが正しくありません。
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES	メモリが不足していました。
STATUS_INVALID_DEVICE_REQUEST	呼び出し元の IRQL がPASSIVE_LEVELされなかったか、指定された Request パラメーターが既に I/O ターゲットにキューに入れられていた I/O 要求。
STATUS_IO_TIMEOUT	ドライバーがタイムアウト値を指定し、割り当てられた時間内に要求が完了しませんでした。
STATUS_REQUEST_NOT_ACCEPTED	要求パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが要求を転送するのに十分な IO_STACK_LOCATION 構造体を提供しません。

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

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

備考

USB リセット要求を同期的に送信するには、WdfUsbTargetPipeResetSynchronously メソッドを使用します。このような要求を非同期的に送信するには、WdfUsbTargetPipeFormatRequestForResetを使用し、その後に WdfRequestSend をします。

フレームワークは、I/O ターゲットの USB パイプをリセットする前に、I/O ターゲットのキューに残っているすべての I/O 要求を取り消します。ドライバーは、WdfUsbTargetPipeResetSynchronously 戻るまで、追加の I/O 要求 I/O ターゲットに送信しないでください。

ドライバーは、WdfUsbTargetPipeResetSynchronously 呼び出す前に、WdfIoTargetStop を呼び出す必要があります。 WdfUsbTargetPipeResetSynchronously 戻後、ドライバーは WdfIoTargetStart 呼び出すことができます。

ドライバーが WdfUsbTargetPipeResetSynchronously 呼び出すと、フレームワークは I/O ターゲットに URB_FUNCTION_RESET_PIPE 要求を送信します。 USB パイプのリセットの詳細については、USB 仕様を参照してください。

WdfUsbTargetPipeResetSynchronously メソッドは、RequestOptions パラメーターが指す WDF_REQUEST_SEND_OPTIONS 構造体のタイムアウト値をドライバーが提供しない限り、またはエラーが検出されない限り、要求が完了するまで戻りません。

ドライバーが I/O キューで受信した I/O 要求を転送することも、新しい要求を作成して送信することもできます。

ドライバーが I/O キューで受信した I/O 要求を転送するには、WdfUsbTargetPipeResetSynchronously メソッドの Request パラメーターに対して受信した要求のハンドル 指定します。

新しい要求を作成して送信するには、Request パラメーターに対して NULL 要求ハンドルを指定するか、新しい要求オブジェクトを作成してそのハンドルを指定します。

NULL 要求ハンドルを指定すると、フレームワークは内部要求オブジェクトを使用します。この手法は簡単に使用できますが、ドライバーは要求をキャンセルできません。
WdfRequestCreate を呼び出して 1 つ以上の要求オブジェクトを作成する場合は、WdfRequestReuse 呼び出すことによって、これらの要求オブジェクトを再利用できます。この手法を使用すると、ドライバーの EvtDriverDeviceAdd コールバック関数を使用して、デバイスの要求オブジェクトを事前に割り当てることができます。さらに、別のドライバースレッドは、WdfRequestCancelSentRequest を呼び出して、必要に応じて要求を取り消すことができます。

ドライバーは、以外の NULL または NULLRequest パラメーターを提供するかどうかに関係なく、NULLRequestOptions パラメーターを指定できます。たとえば、RequestOptions パラメーターを使用してタイムアウト値を指定できます。

I/O 要求が完了した後の状態情報の取得については、「完了情報の取得を参照してください。

WdfUsbTargetPipeResetSynchronously メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲットの」を参照してください。

例

次のコード例では、USB デバイスのパイプにリセット要求を送信します。

NTSTATUS  status;

status = WdfUsbTargetPipeResetSynchronously(
                                            Pipe, 
                                            WDF_NO_HANDLE,
                                            NULL
                                            );

必要条件

要件	価値
ターゲットプラットフォームの	万国
最小 KMDF バージョン	1.0
UMDF の最小バージョンをする	2.0
ヘッダー	wdfusb.h (Wdfusb.h を含む)
ライブラリ	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則をする	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestForUrbXrb(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

次の方法で共有

WdfUsbTargetPipeResetSynchronously 関数 (wdfusb.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース