FltCancellableWaitForSingleObject 関数 (fltkernel.h)

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

FltCancellableWaitForSingleObject ルーチンは、ディスパッチャーオブジェクトに対してキャンセル可能な待機操作 (終了可能な待機) を実行します。

構文

NTSTATUS FLTAPI FltCancellableWaitForSingleObject(
  [in]           PVOID              Object,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PFLT_CALLBACK_DATA CallbackData
);

パラメーター

[in] Object

呼び出し元がストレージを提供する初期化されたディスパッチャーオブジェクト (イベント、ミューテックス、セマフォ、スレッド、またはタイマー) へのポインター。

[in, optional] Timeout

省略可能なタイムアウト値へのポインター。このパラメーターは、待機が完了するまでの絶対時間または相対時間を 100 ナノ秒単位で指定します。

Timeout が 0 の値 (つまり、*Timeout == 0) を指している場合、ルーチンは待機せずにを返します。呼び出し元が NULL ポインター (つまり Timeout == NULL) を指定した場合、ルーチンはオブジェクトがシグナル状態に設定されるまで無期限に待機します。

正の タイムアウト 値は、1601 年 1 月 1 日を基準とした絶対時間を指定します。負の タイムアウト 値は、現在の時刻を基準とした間隔を指定します。絶対有効期限は、システム時刻の変更を追跡します。相対有効期限は、システム時刻の変更の影響を受けません。

Timeout が指定されている場合、指定された間隔の有効期限が切れたときにオブジェクトがシグナル状態に設定されていない場合、待機は自動的に満たされます。

タイムアウト値が 0 (つまり、*Timeout == 0) の場合、一連の待機条件をテストし、ミューテックスの取得と同様に、待機がすぐに満たされる場合は、条件付きで追加のアクションを実行できます。

[in, optional] CallbackData

ユーザー によって発行 され、ユーザーが取り消すことができる I/O 操作を表すFLT_CALLBACK_DATA構造体へのポインター。呼び出し元は、このルーチンの期間中、I/O 操作が有効であり続け、I/O に取り消しルーチンが設定されていないことを確認する必要があります (たとえば、 FltSetCancelCompletion 関数が I/O 操作で呼び出されていない必要があります)。呼び出し元は CallbackData を保持する必要があることに注意してください。下位レベルのドライバーに渡すことはできません。

戻り値

FltCancellableWaitForSingleObject は、次のいずれかの値を返すことができます。

リターンコード	説明
STATUS_SUCCESS	Object パラメーターで指定されたディスパッチャーオブジェクトは、シグナル状態に設定されています。
STATUS_TIMEOUT	オブジェクトがシグナル状態に設定される前にタイムアウトが発生しました。この値は、指定された待機条件をすぐに満たすことができないときにタイムアウトが 0 に設定されている場合にも返すことができます。
STATUS_ABANDONED_WAIT_0	呼び出し元は、破棄されたミューテックスを待機しようとしました。
STATUS_CANCELLED	I/O 操作で保留中の取り消し要求によって待機が中断されました。この値は、 CallbackData が IRP ベースの操作に対応して FltCancellableWaitForSingleObject に渡され、 FltCancelIo などのルーチンによって I/O が取り消された場合にのみ返されることに注意してください。
STATUS_THREAD_IS_TERMINATING	アプリケーションまたはユーザーがスレッドを終了したため、待機が中断されました。

戻り値は、待機の状態のみを示します。

NT_SUCCESS マクロは、STATUS_CANCELLEDの場合は FALSE ("failure") を返し、その他のすべての状態値には TRUE ("success") をSTATUS_THREAD_IS_TERMINATING状態値を返します。

注釈

FltCancellableWaitForSingleObject ルーチンは、ディスパッチャーオブジェクトに対してキャンセル可能な待機操作を実行します。ユーザーまたはアプリケーションがスレッドを終了した場合、またはスレッドに関連付けられている I/O が FltCancelIo などのルーチンによって取り消された場合、待機は取り消されます。

ルーチンは、 I/O 完了/取り消しガイドラインをサポートするように設計されています。これらのガイドラインの目的は、ユーザーがアプリケーションをすばやく終了できるようにすることです。これにより、アプリケーションは、I/O および現在の I/O 操作を実行しているスレッドをすばやく終了できる必要があります。このルーチンは、ユーザースレッドが I/O 完了、ディスパッチャーオブジェクト、または同期変数のカーネルで待機をブロックする方法を提供します。これにより、待機を簡単に取り消すことができます。また、このルーチンは、スレッドがユーザーまたはアプリケーションによって終了された場合に、スレッドの待機を終了することを許可します。

たとえば、リダイレクターは、ユーザーモードの I/O を処理し、セカンダリ要求が完了するまで同期的に待機するために、セカンダリ I/O 操作を作成する必要がある場合があります。これを行う方法の 1 つは、セカンダリ I/O 操作の完了ルーチンによって通知されるイベントを設定し、イベントが通知されるのを待つ方法です。次に、取り消し可能な待機操作を実行するために、 FltCancellableWaitForSingleObject が呼び出され、セカンダリ I/O 操作に関連付けられたイベントと、元のユーザーモード I/O 操作が渡されます。保留中の終了イベントが発生した場合、または元のユーザーモードの I/O 操作が取り消された場合、スレッドのイベントが通知されるまでの待機が取り消されます。

待機を終了しても、呼び出し元によって発行された I/O 操作 (呼び出し元が個別に処理する必要がある) は自動的には取り消されないことに注意してください。

FltCancellableWaitForSingleObject に渡される Object パラメーターがミューテックスである場合は、特別な考慮事項が適用されます。待機中のディスパッチャーオブジェクトがミューテックスの場合、APC 配信は待機中の他のすべてのディスパッチャーオブジェクトの場合と同じです。ただし、 FltCancellableWaitForSingleObject が STATUS_SUCCESS でを返し、スレッドが実際にミューテックスを保持すると、特殊なカーネルモード APC のみが配信されます。他のすべての APC (カーネルモードとユーザーモードの両方) の配信は無効になっています。 APC の配信に関するこの制限は、ミューテックスが解放されるまで保持されます。

ミューテックスは、MINLONG 回だけ再帰的に取得できます。この制限を超えると、ルーチンによってSTATUS_MUTANT_LIMIT_EXCEEDED例外が発生します。

CallbackData パラメーターが有効なフィルターマネージャー IRP を表す場合は、IRQL PASSIVE_LEVELで FltCancellableWaitForSingleObject を呼び出す必要があります。それ以外の場合は、IRQL でAPC_LEVEL以下のルーチンを呼び出すことができます。通常のカーネル API は、必要に応じて、 KeEnterCriticalRegion ルーチンまたは FsRtlEnterFileSystem ルーチンを呼び出すことによって、呼び出し元によって無効にすることができます。ただし、特殊なカーネル API を無効にすることはできません。

CallbackData がフィルターマネージャー IRP 操作を表しているが、CallbackData 構造体の IRP が NULL の場合、FltCancellableWaitForSingleObject ルーチンはデバッグビルドでアサートします。

要件

要件	値
サポートされている最小のクライアント	Windows Vista
対象プラットフォーム	ユニバーサル
Header	fltkernel.h (Fltkernel.h、Ntifs.h を含む)
Library	Fltmgr.lib
[DLL]	Fltmgr.sys
IRQL	「解説」を参照してください。