WdfUsbTargetPipeFormatRequestForReset 関数 (wdfusb.h)
[KMDF と UMDF に適用]
WdfUsbTargetPipeFormatRequestForReset メソッドは、指定された USB パイプのリセット要求を作成しますが、要求は送信しません。
構文
NTSTATUS WdfUsbTargetPipeFormatRequestForReset(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request
);
パラメーター
[in] Pipe
WdfUsbInterfaceGetConfiguredPipe を呼び出して取得したフレームワーク パイプ オブジェクトへのハンドル。
[in] Request
フレームワーク要求オブジェクトへのハンドル。 詳細については、「解説」を参照してください。
戻り値
操作が成功した場合、WdfUsbTargetPipeFormatRequestForReset は USB I/O ターゲットの完了状態値を返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。
| リターン コード | 説明 |
|---|---|
|
無効なパラメーターが検出されました。 |
|
メモリが不足していました。 |
|
要求パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが 要求 を転送できるようにするため の十 分なIO_STACK_LOCATION構造体を提供しません。 |
このメソッドは、他の NTSTATUS 値を返す場合もあります。
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
注釈
WdfUsbTargetPipeFormatRequestForReset の後に WdfRequestSend を使用して、USB リセット要求を同期的または非同期的に送信します。 または、 WdfUsbTargetPipeResetSynchronously メソッドを使用して、要求を同期的に送信します。
ドライバーが WdfRequestSend を呼び出す前に、 WdfIoTargetStop を呼び出す必要があり、I/O ターゲットに送信したすべての I/O 要求を 完了 または 取り消す 必要があります。 ドライバーは、リセット要求が完了するまで、追加の I/O 要求を I/O ターゲットに送信することはできません。
ドライバーが WdfRequestSend を呼び出すと、フレームワークは I/O ターゲットに URB_FUNCTION_RESET_PIPE 要求を送信します。 USB パイプのリセットの詳細については、USB 仕様を参照してください。
ドライバーが I/O キューで受信した I/O 要求を転送することも、新しい要求を作成して送信することもできます。
ドライバーが I/O キューで受信した I/O 要求を転送するには、 WdfUsbTargetPipeFormatRequestForReset メソッドの Request パラメーターに対して、受信した 要求 のハンドルを指定します。
新しい I/O 要求を作成するには、 WdfRequestCreate を呼び出して要求オブジェクトを事前割り当てします。 WdfUsbTargetPipeFormatRequestForReset メソッドの Request パラメーターの要求ハンドルを指定します。 要求オブジェクトは 、WdfRequestReuse を呼び出すことで再利用できます。 ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前割り当てできます。
WdfUsbTargetPipeFormatRequestForReset を呼び出して I/O 要求を書式設定した後、ドライバーは WdfRequestSend を呼び出して要求を (同期的または非同期的に) I/O ターゲットに送信する必要があります。
同じ要求を使用する WdfUsbTargetPipeFormatRequestForReset を複数回呼び出しても、追加のリソース割り当ては発生しません。 そのため、 WdfRequestCreate がSTATUS_INSUFFICIENT_RESOURCESを返す可能性を減らすために、ドライバーの EvtDriverDeviceAdd コールバック関数は WdfRequestCreate を呼び出して、デバイスの 1 つ以上の要求オブジェクトを事前割り当てできます。 ドライバーは、その後、 WdfRequestReuse の呼び出し、再フォーマット ( WdfUsbTargetPipeFormatRequestForReset の呼び出し)、および WdfRequestCreate の後の呼び出しからSTATUS_INSUFFICIENT_RESOURCES戻り値を危険にさらすことなく、各要求オブジェクトを再送信 (呼び出し WdfRequestSend) できます。 パラメーター値が変更されない場合、再利用された要求オブジェクトに対する WdfUsbTargetPipeFormatRequestForReset に対する後続のすべての呼び出しは、STATUS_SUCCESSを返します。 (ドライバーが毎回同じ要求形式メソッドを呼び出さない場合は、追加のリソースが割り当てられる可能性があります)。
I/O 要求の完了後に状態情報を取得する方法については、「 完了情報の取得」を参照してください。
WdfUsbTargetPipeFormatRequestForReset メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲット」を参照してください。
例
次のコード例では、USB パイプのリセット要求を書式設定し、 CompletionRoutine コールバック関数を登録して、要求を送信します。
status = WdfUsbTargetPipeFormatRequestForReset(
pipe,
Request
);
if (!NT_SUCCESS(status)) {
goto Exit;
}
WdfRequestSetCompletionRoutine(
Request,
AbortCompletionRoutine,
pipe
);
if (WdfRequestSend(
Request,
WdfUsbTargetPipeGetIoTarget(pipe),
WDF_NO_SEND_OPTIONS
) == FALSE) {
status = WdfRequestGetStatus(Request);
goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
WdfRequestCompleteWithInformation(
Request,
status,
0
);
}
return;
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| 最小 KMDF バージョン | 1.0 |
| 最小 UMDF バージョン | 2.0 |
| Header | wdfusb.h (Wdfusb.h を含む) |
| Library | Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI コンプライアンス規則 | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 RequestFormattedValid(kmdf)、 RequestForUrbXrb(kmdf)、 RequestSendAndForgetNoFormatting(kmdf)、 RequestSendAndForgetNoFormatting2(kmdf)、 UsbKmdfIrql(kmdf)、 UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf) |