WdfUsbTargetPipeAbortSynchronously 関数 (wdfusb.h)

  • [アーティクル]

[KMDF と UMDF に適用]

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

構文

NTSTATUS WdfUsbTargetPipeAbortSynchronously(
  [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 にすることができます。 詳細については、「解説」を参照してください。

戻り値

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

リターン コード 説明
STATUS_INFO_LENGTH_MISMATCH
 RequestOptions パラメーターが指定したWDF_REQUEST_SEND_OPTIONS構造体のサイズが正しくありません。
STATUS_INVALID_PARAMETER
 無効なハンドルが検出されました。
STATUS_INSUFFICIENT_RESOURCES
 メモリが不足していました。
STATUS_INVALID_DEVICE_REQUEST
 呼び出し元の IRQL がPASSIVE_LEVELされていないか、指定された I/O 要求が既に I/O ターゲットにキューに入れられました。
STATUS_IO_TIMEOUT
 ドライバーはタイムアウト値を指定し、割り当てられた時間内に要求が完了しませんでした。
 

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

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

注釈

USB 中止要求を同期的に送信するには、 WdfUsbTargetPipeAbortSynchronously メソッドを使用します。 このような要求を非同期に送信するには、 WdfUsbTargetPipeFormatRequestForAbort を使用し、その後に WdfRequestSend を使用します。

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

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

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

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

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

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

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

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

例

次のコード例では、USB デバイスのインターフェイス用に構成されているすべてのパイプに中止要求を送信します。

UCHAR  i;
ULONG  count;
NTSTATUS  status;
PDEVICE_CONTEXT  pDevContext;

pDevContext = GetDeviceContext(Device);

count = WdfUsbInterfaceGetNumConfiguredPipes(
                                             pDevContext->UsbInterface
                                             );

for (i = 0; i < count; i++) {
    WDFUSBPIPE pipe;

    pipe = WdfUsbInterfaceGetConfiguredPipe(
                                            pDevContext->UsbInterface,
                                            i,
                                            NULL
                                            );
    status = WdfUsbTargetPipeAbortSynchronously(
                                                pipe,
                                                WDF_NO_HANDLE,
                                                NULL
                                                );
    if (!NT_SUCCESS(status)) {
        break;
    }
}

要件

要件 値
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
最小 UMDF バージョン 2.0
Header wdfusb.h (Wdfusb.h を含む)
Library 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)

こちらもご覧ください

WdfRequestCancelSentRequest

WdfUsbTargetPipeResetSynchronously