Функция 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 единицх nanosecond, когда ожидание будет завершено.

Если время ожидания указывает на нулевое значение (то есть *время ожидания == 0), подпрограмма возвращается без ожидания. Если вызывающий объект предоставляет указатель NULL (то есть время ожидания == NULL), подпрограмма ожидает неограниченное время, пока объект не будет задан сигнальным состоянием.

Положительное значение время ожидания указывает абсолютное время относительно 1 января 1601 года. Отрицательное время ожидания указывает интервал относительно текущего времени. Абсолютное время истечения срока действия отслеживает любые изменения в системном времени. Относительные сроки действия не влияют на изменения системного времени.

Если указана время ожидания, ожидание будет автоматически удовлетворено, если объект не установлен в сигнальное состояние при истечении заданного интервала.

Значение времени ожидания (т. е. *Timeout == 0) позволяет протестировать набор условий ожидания и условно выполнить любые дополнительные действия, если ожидание может быть немедленно удовлетворено, как при приобретении мьютекса.

[in, optional] CallbackData

Указатель на структуру FLT_CALLBACK_DATA, представляющую операцию ввода-вывода, выданную пользователем, и которая может быть отменена пользователем. Вызывающий объект должен убедиться, что операция ввода-вывода останется допустимой в течение этой подпрограммы, и что операции ввода-вывода не должны иметь набор подпрограмм отмены (например, fltSetCancelCompletion функция не должна вызываться в операции ввода-вывода). Обратите внимание, что вызывающий объект должен содержать CallbackData; Его нельзя передать драйверу нижнего уровня.

Возвращаемое значение

FltCancellableWaitForSingleObject может вернуть одно из следующих значений:

Возвращаемый код	Описание
STATUS_SUCCESS	Объект диспетчера, указанный параметром объекта, установлен в сигнальное состояние.
STATUS_TIMEOUT	Время ожидания произошло до того, как объект был задан в сигнальном состоянии. Это значение также можно вернуть, если указанное условие ожидания не может быть немедленно выполнено и время ожидания равно нулю.
STATUS_ABANDONED_WAIT_0	Вызывающий попытался ждать мьютекса, который был заброшен.
STATUS_CANCELLED	Ожидание было прервано ожидающей отменой запроса на операцию ввода-вывода. Обратите внимание, что это значение возвращается только в том случае, если CallbackData соответствует операции на основе IRP, передается в FltCancellableWaitForSingleObject, а операции ввода-вывода были отменены подпрограммой, например FltCancelIo.
STATUS_THREAD_IS_TERMINATING	Ожидание было прервано, так как приложение или пользователь завершили поток.

Возвращаемое значение указывает только состояние ожидания.

Обратите внимание, что макрос NT_SUCCESS возвращает значение FALSE ("сбой") для STATUS_CANCELLED и STATUS_THREAD_IS_TERMINATING значений состояния и TRUE ("успешно") для всех остальных значений состояния.

Замечания

Подпрограмма FltCancellableWaitForSingleObject выполняет операцию ожидания отмены для объекта диспетчера. Если пользователь или приложение завершает поток или если операции ввода-вывода, связанные с потоком, были отменены подпрограммой, например FltCancelIo, ожидание отменено.

Подпрограмма предназначена для поддержки рекомендаций по завершению ввода-вывода и отмене. Цель этих рекомендаций заключается в том, чтобы пользователи могли быстро завершить работу приложений. Это, в свою очередь, требует, чтобы приложения имели возможность быстро завершать потоки, выполняющие операции ввода-вывода и любые текущие операции ввода-вывода. Эта подпрограмма позволяет пользовательским потокам блокировать (т. е. ждать) в ядре для завершения ввода-вывода, объектов диспетчера или переменных синхронизации таким образом, чтобы ждать будет легко отменено. Эта подпрограмма также позволяет завершить ожидание потока, если поток завершается пользователем или приложением.

Например, перенаправление может потребоваться создать вторичную операцию ввода-вывода для обработки ввода-вывода в пользовательском режиме и синхронно ожидать завершения вторичного запроса. Одним из способов этого является настройка события, которое будет сигнализировать подпрограммой завершения вторичной операции ввода-вывода, а затем ждать, пока событие будет сигнализировать. Затем для выполнения операции ожидания, допускающей отмену, FltCancellableWaitForSingleObject вызывает передачу события, связанного с вторичной операцией ввода-вывода, и исходной операции ввода-вывода в пользовательском режиме. Ожидается, что событие будет отменено, если происходит ожидающее событие завершения или если исходная операция ввода-вывода в пользовательском режиме отменена.

Обратите внимание, что завершение ожидания не отменяет автоматическую операцию ввода-вывода, выданную вызывающим оператором, которая должна обрабатываться отдельно вызывающим оператором.

Особое внимание следует учитывать, когда параметр объекта, переданный FltCancellableWaitForSingleObject является мьютексом. Если объект диспетчера, который ожидается, является мьютексом, доставка APC совпадает со всеми другими объектами диспетчера во время ожидания. Однако после FltCancellableWaitForSingleObject возвращается с STATUS_SUCCESS, а поток фактически содержит мьютекс, доставляются только специальные API режима ядра. Доставка всех остальных API, как в режиме ядра, так и в пользовательском режиме, отключена. Это ограничение на доставку API сохраняется до тех пор, пока мьютекс не будет освобожден.

Мьютекс может быть рекурсивно приобретен только во время MINLONG. Если это ограничение превышено, подпрограмма вызывает исключение STATUS_MUTANT_LIMIT_EXCEEDED.

FltCancellableWaitForSingleObject должен вызываться в IRQL PASSIVE_LEVEL, если параметр callbackData callbackData представляет допустимый диспетчер фильтров IRP. В противном случае подпрограмму можно вызвать в IRQL меньше или равно APC_LEVEL. При необходимости обычные API ядра можно отключить вызывающим оператором, вызвав подпрограммы KeEnterCriticalRegion или FsRtlEnterFileSystem. Однако специальные API ядра не должны быть отключены.

Подпрограмма FltCancellableWaitForSingleObject будет утверждаться в отладочных сборках, если CallbackData представляет операцию IRP диспетчера фильтров, но IRP в структуре CallbackData имеет значение NULL.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista
целевая платформа	Всеобщий
заголовка	fltkernel.h (include Fltkernel.h, Ntifs.h)
библиотеки	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	См. раздел "Примечания".