FltCancellableWaitForSingleObject 函数 （fltkernel.h）
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），则例程返回而不等待。 如果调用方提供 NULL 指针（即，Timeout == NULL），则例程将无限期等待，直到对象设置为信号状态。
正 超时 值指定相对于 1601 年 1 月 1 日绝对时间。 负 超时 值指定相对于当前时间的间隔。 绝对过期时间跟踪系统时间中的任何更改。 相对过期时间不受系统时间更改的影响。
如果指定了 超时，则如果未在给定间隔过期时将对象设置为信号状态，则会自动满足等待。
超时值为零（即 *Timeout == 0）允许测试一组等待条件，并在可以立即满足等待时有条件地执行任何其他作，就像获取互斥体一样。
[in, optional] CallbackData
指向 FLT_CALLBACK_DATA 结构的指针，该结构表示用户颁发的 I/O作，并且可以由用户取消。 调用方必须确保 I/O作在此例程的持续时间内保持有效，并且 I/O 不得具有取消例程集（例如，FltSetCancelCompletion 函数不得在 I/O作上调用）。 请注意，调用方必须保留 CallbackData;无法将其传递给较低级别的驱动程序。
返回值
FltCancellableWaitForSingleObject 可以返回以下值之一：
| 返回代码 | 描述 |
|---|---|
| STATUS_SUCCESS | 由 Object 参数指定的调度程序对象已设置为信号状态。 |
| STATUS_TIMEOUT | 在对象设置为信号状态之前发生超时。 当无法立即满足指定的等待条件并且 超时 设置为零时，也可以返回此值。 |
| STATUS_ABANDONED_WAIT_0 | 调用方试图等待已放弃的互斥体。 |
| STATUS_CANCELLED | 等待被 I/O作的挂起取消请求中断。 请注意，仅当 CallbackData 对应于基于 IRP 的作传递给 FltCancellableWaitForSingleObject 并且 I/O 已被例程（如 FltCancelIo）取消时，才会返回此值。 |
| STATUS_THREAD_IS_TERMINATING | 由于应用程序或用户已终止线程，等待中断。 |
返回值仅指示等待状态。
请注意，NT_SUCCESS宏为STATUS_CANCELLED返回 FALSE（“failure”），对于所有其他状态值STATUS_THREAD_IS_TERMINATING状态值和 TRUE（“success”）。
言论
FltCancellableWaitForSingleObject 例程对调度程序对象执行可取消的等待作。 如果用户或应用程序终止线程，或者与线程关联的 I/O 已由例程（如 FltCancelIo）取消，则会取消等待。
例程旨在支持 I/O 完成/取消指南。 这些准则的目标是允许用户快速终止应用程序。 反过来，这又要求应用程序能够快速终止正在执行 I/O 和任何当前 I/O作的线程。 此例程为用户线程提供了一种阻止（即等待）内核中 I/O 完成、调度程序对象或同步变量的方法，允许等待随时取消。 如果线程由用户或应用程序终止，此例程还允许线程等待终止。
例如，重定向程序可能需要创建辅助 I/O作才能处理用户模式 I/O，并同步等待辅助请求完成。 执行此作的一种方法是设置一个事件，该事件将由辅助 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。 调用方可以根据需要通过调用 KeEnterCriticalRegion 或 FsRtlEnterFileSystem 例程来禁用正常内核 APC。 但是，不能禁用特殊内核 APC。
如果 CallbackData 表示筛选器管理器 IRP作，FltCancellableWaitForSingleObject 例程将在调试生成上断言，但在 CallbackData 结构中的 IRP 为 NULL。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows Vista |
| 目标平台 | 普遍 |
| 标头 | fltkernel.h （包括 Fltkernel.h、 Ntifs.h） |
| 库 | Fltmgr.lib |
| DLL | Fltmgr.sys |
| IRQL | 请参阅“备注”部分。 |
另请参阅
FltCancellableWaitForMultipleObjects