FsRtlCancellableWaitForSingleObject 関数 (ntifs.h)
FsRtlCancellableWaitForSingleObject ルーチンは、ディスパッチャー オブジェクトに対してキャンセル可能な待機操作 (終了可能な待機) を実行します。
構文
NTSTATUS FsRtlCancellableWaitForSingleObject(
[in] PVOID Object,
[in, optional] PLARGE_INTEGER Timeout,
[in, optional] PIRP Irp
);
パラメーター
[in] Object
呼び出し元がストレージを提供する初期化されたディスパッチャー オブジェクト (イベント、ミューテックス、セマフォ、スレッド、またはタイマー) へのポインター。
[in, optional] Timeout
省略可能なタイムアウト値へのポインター。 このパラメーターは、待機が完了する 100 ナノ秒単位の絶対時間または相対時間を指定します。
Timeout が 0 の値 (つまり、*Timeout == 0) を指している場合、ルーチンは待機せずに を返します。 呼び出し元が NULL ポインター (つまり Timeout == NULL) を指定した場合、ルーチンはオブジェクトがシグナル状態に設定されるまで無期限に待機します。
正の タイムアウト 値は、1601 年 1 月 1 日を基準とした絶対時間を指定します。 負の タイムアウト 値は、現在の時刻を基準とした間隔を指定します。 絶対有効期限は、システム時刻の変更を追跡します。 相対有効期限は、システム時刻の変更の影響を受けません。
Timeout が指定されている場合、指定された間隔の有効期限が切れたときにオブジェクトがシグナル状態に設定されていない場合、待機は自動的に満たされます。
タイムアウト値が 0 (つまり、*Timeout == 0) の場合、一連の待機条件をテストし、ミューテックスの取得と同様に、待機がすぐに満たされる場合は、条件付きで追加のアクションを実行できます。
[in, optional] Irp
ユーザーによって発行され、ユーザーが取り消すことができる I/O 操作に対応する元の IRP へのポインター。 呼び出し元は、このルーチンの期間中、IRP が有効なままであること、および IRP にキャンセル ルーチンが設定されていないことを確認する必要があります (たとえば、 IoSetCancelRoutine が IRP で呼び出されていない必要があります)。 IRP は呼び出し元が保持する必要があり、下位レベルのドライバーに渡すことはできません。
戻り値
FsRtlCancellableWaitForSingleObject は、次のいずれかの値を返すことができます。
| リターン コード | 説明 |
|---|---|
| STATUS_SUCCESS | Object パラメーターで指定されたディスパッチャー オブジェクトが待機を満たしました。 |
| STATUS_TIMEOUT | オブジェクトがシグナル状態に設定される前にタイムアウトが発生しました。 この値は、指定した待機条件のセットをすぐに満たすことができないときに返され、 Timeout が 0 に設定されている場合に返されます。 |
| STATUS_ABANDONED_WAIT_0 | 呼び出し元は、破棄されたミューテックスを待機しようとしました。 |
| STATUS_CANCELLED | 指定した IRP の保留中のキャンセル要求によって待機が中断されました。 この値は、有効な IRP が FsRtlCancellableWaitForSingleObject に渡され、IRP が CancelSynchronousIo によって取り消された場合にのみ返されることに注意してください。 |
| STATUS_THREAD_IS_TERMINATING | スレッドがアプリケーションまたはユーザーによって終了されたため、待機が中断されました。 |
戻り値は、待機の状態のみを示します。 該当する場合、I/O 要求の実際の状態は、元のユーザー モード IRP を処理するプロセスで生成された別の IRP から直接取得する必要があります。
NT_SUCCESS マクロは、STATUS_CANCELLEDの場合は FALSE ("failure") を返し、その他のすべての状態値には TRUE ("success") をSTATUS_THREAD_IS_TERMINATING状態値を返します。
注釈
FsRtlCancellableWaitForSingleObject ルーチンは、ディスパッチャー オブジェクトに対してキャンセル可能な待機操作を実行します。 スレッドがユーザーまたはアプリケーションによって終了した場合、または CancelSynchronousIo がスレッドに関連付けられているスレッド IRP (同期 IRP) にキャンセル要求を送信した場合、待機は取り消されます。
FsRtlCancellableWaitForSingleObject ルーチンは、Windows Vista 以降の I/O 完了/取り消しガイドラインをサポートするように設計されています。 これらのガイドラインの目的は、ユーザー (またはアプリケーション) がアプリケーションをすばやく終了できるようにすることです。 この場合、アプリケーションでは、I/O を実行しているスレッドと現在の I/O 操作を迅速に終了できる必要があります。 このルーチンは、ユーザー スレッドが I/O 完了、ディスパッチャー オブジェクト、または同期変数のためにカーネル内で待機をブロックする方法を提供します。これにより、待機を簡単に取り消すことができます。 また、このルーチンは、スレッドがユーザーまたはアプリケーションによって終了された場合に、スレッドの待機を終了することを許可します。
たとえば、リダイレクターは、ユーザー モード IRP を処理し、セカンダリ IRP が完了するまで同期的に待機するために、1 つ以上のセカンダリ IRP を作成する必要がある場合があります。 これを行う方法の 1 つは、セカンダリ IRP の完了ルーチンによって通知されるイベントを設定し、イベントが通知されるまで待機することです。 次に、キャンセル可能な待機操作を実行するために、 FsRtlCancellableWaitForSingleObject が呼び出され、セカンダリ IRP に関連付けられたイベントと、元のユーザー モード IRP が渡されます。 保留中の終了イベントが発生した場合、または元のユーザー モード IRP が取り消された場合、スレッドのイベントが通知されるまでの待機が取り消されます。
待機を終了しても、呼び出し元によって発行された I/O 操作 (呼び出し元が個別に処理する必要がある) は自動的に取り消されないことに注意してください。
FsRtlCancellableWaitForSingleObject に渡される Object パラメーターがミューテックスである場合は、特別な考慮事項が適用されます。 待機中のディスパッチャー オブジェクトがミューテックスの場合、APC 配信は待機中の他のすべてのディスパッチャー オブジェクトの場合と同じです。 ただし、 FsRtlCancellableWaitForSingleObjects が STATUS_SUCCESS でを返し、スレッドが実際にミューテックスを保持すると、特殊なカーネル モードの APC のみが配信されます。 他のすべての APC (カーネル モードとユーザー モードの両方) の配信は無効になっています。 APC の配信に関するこの制限は、ミューテックスが解放されるまで保持されます。
ミューテックスは、MINLONG 回だけ再帰的に取得できます。 この制限を超えると、ルーチンによってSTATUS_MUTANT_LIMIT_EXCEEDED例外が発生します。
I/O 完了/取り消しガイドラインをサポートするために FsRtlCancellableWaitForSingleObject を使用する方法の例を次に示します。
//
// sample calling routine
//
NTSTATUS ProcessIrpFromUserMode( PIRP pOriginalIrp, ... )
{
NTSTATUS Status;
NTSTATUS WaitStatus;
KEVENT Event;
LARGE_INTEGERTimeout;
PIRP pAdditionalIrp;
BOOLEAN Cancelled;
//
// Allocate the additional IRP here:
//
KeInitializeEvent( &Event,
SynchronizationEvent,
FALSE );
pContext->pEvent = &Event; // Driver specific context structure.
IoSetCompletionRoutine( pAdditionalIrp,
FunctionCompletionRoutine,
pContext,
TRUE,
TRUE,
TRUE);
Status = IoCallDriver( pDeviceObject, pAdditionalIrp );
if (Status == STATUS_PENDING) {
//
// Initialize Timeout variable here. If no timeout is needed, pass NULL for
// that parameter instead.
//
WaitStatus = FsRtlCancellableWaitForSingleObject( &Event,
&Timeout,
pOriginalIrp );
if ((WaitStatus == STATUS_CANCELLED) || (WaitStatus == STATUS_THREAD_IS_TERMINATING)) {
//
// Thread is terminating. IRP was canceled.
// Cancel the additional IRP passed to the lower level driver, cleanup, and return quickly.
//
Cancelled = IoCancelIrp( pAdditionalIrp );
if (!Cancelled || KeReadStateEvent( &Event ) == 0) {
//
// Wait for the IRP to complete.
// If cancel was posted successfully on the IRP, this shouldn't take a long time.
//
(VOID) KeWaitForSingleObject( &Event,
Executive,
KernelMode, // WaitMode
FALSE, // Alertable
(PLARGE_INTEGER) NULL );
}
} else if (WaitStatus == STATUS_TIMEOUT) {
//
// Wait timed out. The IRP was canceled or the API
// waited for the I/O to complete.
//
} else {
ASSERT( WaitStatus == STATUS_SUCCESS );
//
// The wait completed without timeout
// or being canceled.
//
}
}
//
// IRP is valid and needs to be handled here.
// pAdditionalIrp->IoStatus.Status contains the status of the IRP.
// Finally, pOriginal IRP needs to be completed appropriately as well.
//
}
//
// Sample completion routine:
//
NTSTATUS
FunctionCompletionRoutine(
IN PDEVICE_OBJECT pDeviceObject,
INOUT PIRP pAdditionalIrp,
IN PVOID pContext)
{
if (pAdditionalIrp->PendingReturned) {
KeSetEvent( pContext->pEvent, 0, FALSE );
}
//
// Discontinue I/O completion.
// Dispatch routine will deal with IRP.
//
return STATUS_MORE_PROCESSING_REQUIRED;
}
オプションの Irp パラメーターが有効な IRP を指している場合は、IRQL PASSIVE_LEVELで FsRtlCancellableWaitForSingleObjectを呼び出す必要があります。 Irp パラメーターを使用しない場合は、IRQL でルーチンを呼び出すことができます以下のAPC_LEVELします。 通常のカーネル API は、必要に応じて、 KeEnterCriticalRegion ルーチンまたは FsRtlEnterFileSystem ルーチンを呼び出すことによって、呼び出し元によって無効にすることができます。 ただし、特殊なカーネル API を無効にすることはできません。
FSRtlCancellableWaitForSingleObject は、IRQL がAPC_LEVEL以上で、オプションの Irp パラメーターが有効な IRP を指している場合、デバッグ ビルドでアサートされます。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista |
| 対象プラットフォーム | ユニバーサル |
| Header | ntifs.h (Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | 「解説」を参照してください。 |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs(storport), SpNoWait(storport) |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示