WdfIoTargetStop 関数 (wdfiotarget.h)

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

[KMDF と UMDF に適用]

WdfIoTargetStop メソッドは、キューに登録された要求をローカルまたはリモートの I/O ターゲットに送信しなくなります。

構文

void WdfIoTargetStop(
  [in] WDFIOTARGET                  IoTarget,
  [in] WDF_IO_TARGET_SENT_IO_ACTION Action
);

パラメーター

[in] IoTarget

WdfDeviceGetIoTarget または WdfIoTargetCreate の以前の呼び出し、または特殊化された I/O ターゲットが提供するメソッドから取得されたローカルまたはリモートの I/O ターゲットオブジェクトへのハンドル。

[in] Action

ドライバーが I/O ターゲットに送信した I/O 要求 (ターゲットが要求を完了していない場合) をフレームワークが処理する方法を指定する、 WDF_IO_TARGET_SENT_IO_ACTION型指定の値。

戻り値

なし

解説

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

ドライバーが回復可能なデバイスエラーを検出できる場合は、 ドライバーが WdfIoTargetStop を呼び出して要求の送信を一時的に停止し、後で WdfIoTargetStart を呼び出して要求の送信を再開することができます。

停止中、I/O ターゲットは引き続き新しい要求を受け入れますが、キューに入れられた要求を適切なドライバーに配信しません。

I/O ターゲットで使用できる状態の詳細については、「一般的な I/O ターゲットの状態の制御」を参照してください。

ドライバーが WdfUsbTargetPipeConfigContinuousReader を呼び出して USB パイプの連続リーダーを構成する場合、ドライバーの EvtDeviceD0Exit コールバック関数は WdfIoTargetStop を呼び出してリーダーを停止する必要があります。

ドライバーが WdfIoTargetStop を呼び出した場合でも、要求の WDF_REQUEST_SEND_OPTIONS 構造体で WDF_REQUEST_OPTION_IGNORE_TARGET_STATE フラグを設定することで、ターゲットに要求を送信できます。ドライバーがこのフラグを設定した場合、ドライバーは、ドライバーが WdfIoTargetStop を呼び出した後に、USB パイプをリセットする要求 (WdfUsbTargetPipeResetSynchronously を参照) などの要求をデバイスに送信できます。

ドライバーが WdfIoTargetStop を呼び出すとき、フレームワークは、要求の WDF_REQUEST_SEND_OPTIONS 構造体の WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE フラグまたは WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET フラグを使用して、以前にターゲットに送信された I/O 要求をキャンセルまたは待機しません。

ドライバーは、WdfIoTargetStart と WdfIoTargetStop を同期的に呼び出す必要があります。ドライバーは、これらの関数のいずれかを呼び出した後、最初の呼び出しが返される前に、どちらの関数も呼び出してはなりません。

ドライバーは 、WdfIoTargetStart を 呼び出さずに、1 つのスレッドから WdfIoTargetStop を複数回呼び出すことができます。たとえば、ドライバーで次の操作を行う場合があります。

WdfIoTargetStop を呼び出し、Action 値 WdfIoTargetLeaveSentIoPending を指定します。
ターゲットが I/O 要求の処理を再開する必要があるかどうかを判断します。
ターゲットを再開する必要がある場合は、 WdfIoTargetStart を呼び出します。それ以外の場合は、 WdfIoTargetCancelSentIoの Action 値を使用して WdfIoTargetStop を再度呼び出します。

メモWdfIoTargetStop はスレッドセーフではありません。異なるスレッドから WdfIoTargetStop を 同時に呼び出しても安全ではありません。

I/O ターゲットの詳細については、「I /O ターゲットの使用」を参照してください。

ドライバーがパイプの WdfUsbTargetPipeConfigContinuousReader を呼び出した場合は、IRQL = PASSIVE_LEVELで WdfIoTargetStop を呼び出す必要があります。

ドライバーで WdfUsbTargetPipeConfigContinuousReader が呼び出されておらず、WdfIoTargetStop の Action パラメーターが WdfIoTargetLeaveSentIoPending である場合、WdfIoTargetStop は IRQL <= DISPATCH_LEVELで呼び出すことができます。それ以外の場合、 WdfIoTargetStop は IRQL = PASSIVE_LEVELで呼び出されます。

例

次のコード例は、ドライバーが USB パイプに連続リーダーを使用している場合に、 EvtDeviceD0Exit コールバック関数が WdfIoTargetStop を呼び出す方法を示しています。

NTSTATUS
MyEvtDeviceD0Exit(
    IN  WDFDEVICE Device,
    IN  WDF_POWER_DEVICE_STATE TargetState
)
{
    PDEVICE_CONTEXT  pDeviceContext;
    pDeviceContext = GetMyDeviceContext(Device);

    WdfIoTargetStop(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetCancelSentIo
                    );

    return STATUS_SUCCESS;
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfiotarget.h (Wdf.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	「解説」を参照してください。
DDI コンプライアンス規則	DriverCreate(kmdf)、 FailD0EntryIoTargetState(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)