WdfUsbTargetPipeFormatRequestForAbort 関数 (wdfusb.h)

[KMDF と UMDF に適用]

WdfUsbTargetPipeFormatRequestForAbort メソッドは、指定された USB パイプに対する中止要求をビルドしますが、要求は送信しません。

構文

NTSTATUS WdfUsbTargetPipeFormatRequestForAbort(
  [in] WDFUSBPIPE Pipe,
  [in] WDFREQUEST Request
);

パラメーター

[in] Pipe

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

[in] Request

フレームワーク要求オブジェクトへのハンドル。 詳細については、「解説」を参照してください。

戻り値

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

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

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

注釈

WdfUsbTargetPipeFormatRequestForAbort の後に WdfRequestSend を使用して、USB 中止要求を同期的または非同期的に送信します。 または、 WdfUsbTargetPipeAbortSynchronously メソッドを使用して、要求を同期的に送信します。

USB 中止要求により、ドライバーの I/O ターゲットは、パイプに送信されたすべての I/O 要求を取り消します。 ドライバーが WdfRequestSend を呼び出すと、フレームワークは I/O ターゲットに URB_FUNCTION_ABORT_PIPE 要求を送信します。 USB パイプ ("パイプの中止" とも呼ばれます) での操作の取り消しの詳細については、USB 仕様を参照してください。

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

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

新しい I/O 要求を作成するには、 WdfRequestCreate を呼び出して要求オブジェクトを事前割り当てします。 WdfUsbTargetPipeFormatRequestForAbort メソッドの Request パラメーターの要求ハンドルを指定します。 要求オブジェクトは 、WdfRequestReuse を呼び出すことで再利用できます。 ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前割り当てできます。

WdfUsbTargetPipeFormatRequestForAbort を呼び出して I/O 要求を書式設定した後、ドライバーは WdfRequestSend を呼び出して要求を (同期的または非同期的に) I/O ターゲットに送信する必要があります。

同じ要求を使用する WdfUsbTargetPipeFormatRequestForAbort を複数回呼び出しても、追加のリソース割り当ては発生しません。 そのため、 WdfRequestCreate がSTATUS_INSUFFICIENT_RESOURCESを返す可能性を減らすために、ドライバーの EvtDriverDeviceAdd コールバック関数は WdfRequestCreate を呼び出して、デバイスの 1 つ以上の要求オブジェクトを事前割り当てできます。 ドライバーは、後で WdfRequestCreate の呼び出しからSTATUS_INSUFFICIENT_RESOURCES戻り値を危険にさらすことなく、各要求オブジェクトを再利用 (呼び出し WdfRequestReuse)、再フォーマット (呼び出し WdfUsbTargetPipeFormatRequestForAbort)、および再送信 (呼び出し WdfRequestSend) を行うことができます。 再利用された要求オブジェクトに対する WdfUsbTargetPipeFormatRequestForAbort に対する後続のすべての呼び出しは、パラメーター値が変更されない場合、STATUS_SUCCESSを返します。 (ドライバーが毎回同じ要求形式メソッドを呼び出さない場合は、追加のリソースが割り当てられる可能性があります)。

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

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

例

次のコード例では、USB パイプの中止要求を書式設定し、 CompletionRoutine コールバック関数を登録して、要求を送信します。

status = WdfUsbTargetPipeFormatRequestForAbort(
                                               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;

要件

こちらもご覧ください

WdfUsbInterfaceGetConfiguredPipe