Функция 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 указывает на нулевое значение (т. е. *Timeout == 0), подпрограмма возвращается без ожидания. Если вызывающий объект предоставляет указатель NULL (то есть Timeout == NULL), подпрограмма ожидает неограниченное время, пока объект не будет установлен в состояние сигнала.

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

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

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

[in, optional] CallbackData

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

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

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

Код возврата	Описание
STATUS_SUCCESS	Для объекта диспетчера, заданного параметром Object , задано состояние сигнала.
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 , передавая событие, связанное с дополнительной операцией ввода-вывода, и исходную операцию ввода-вывода в пользовательском режиме. Ожидание потока сигнала о событии отменяется, если происходит ожидающее событие завершения или если отменяется исходная операция ввода-вывода в пользовательском режиме.

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

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

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

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

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

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h, Ntifs.h)
Библиотека	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	См. раздел "Примечания".