WdfIoTargetPurge 関数 (wdfiotarget.h)

[アーティクル]
03/05/2024

[KMDF と UMDF に適用]

WdfIoTargetPurge メソッドは、ローカル、リモート、または特殊化された I/O ターゲットにキューに入れられているすべての I/O 要求を取り消し、新しい I/O 要求がキューに入れないようにします。メソッドは、I/O ターゲットのキューを離れ、下位のドライバーを入力した I/O 要求の取り消しも試みます。

構文

void WdfIoTargetPurge(
  [in] WDFIOTARGET                   IoTarget,
  [in] WDF_IO_TARGET_PURGE_IO_ACTION Action
);

パラメーター

[in] IoTarget

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

[in] Action

配信されたすべての要求が完了または取り消されるまで、フレームワークが WdfIoTargetPurge からの戻りを待機する必要があるかどうかを示す、WDF_IO_TARGET_PURGE_IO_ACTION型指定された値。

戻り値

なし

解説

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

ドライバーが以前に WdfUsbTargetPipeConfigContinuousReader を呼び出した場合は、IRQL = PASSIVE_LEVELで WdfIoTargetPurge を呼び出す必要があります。ドライバーが WdfUsbTargetPipeConfigContinuousReader を呼び出していない場合、WdfIoTargetPurge の Action パラメーターが WdfIoTargetPurgeIo の場合は、IRQL <= DISPATCH_LEVELで WdfIoTargetPurge を呼び出すことができます。それ以外の場合は、IRQL = PASSIVE_LEVELで WdfIoTargetPurge を呼び出す必要があります。

WdfIoTargetPurge を同期呼び出しにするには、ドライバーで Action パラメーターの WdfIoTargetPurgeIoAndWait 値を設定できます。この場合、 WdfIoTargetPurge は、配信されたすべての要求が完了または取り消されるまで、戻るまで待機します。

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

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

ドライバーは、I/O キューを消去した後、 WdfIoTargetStart を呼び出すことによってキューを再起動できます。

ドライバーは、WdfIoTargetStart、 WdfIoTargetStop 、 WdfIoTargetPurge を同期的に呼び出す必要があります。ドライバーは、これらの関数のいずれかを呼び出した後、前の呼び出しが返されるまで、他の関数のいずれかを呼び出す必要があります。

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

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

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

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

例

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

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

    WdfIoTargetPurge(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetPurgeIoAndWait
                    );

    return STATUS_SUCCESS;
}

要件

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