функция обратного вызова PFLT_POST_OPERATION_CALLBACK (fltkernel.h)

Статья
08/07/2023

Драйвер мини-фильтра может зарегистрировать одну или несколько подпрограмм типа PFLT_POST_OPERATION_CALLBACK для выполнения обработки завершения операций ввода-вывода.

Синтаксис

PFLT_POST_OPERATION_CALLBACK PfltPostOperationCallback;

FLT_POSTOP_CALLBACK_STATUS PfltPostOperationCallback(
  [in, out]      PFLT_CALLBACK_DATA Data,
  [in]           PCFLT_RELATED_OBJECTS FltObjects,
  [in, optional] PVOID CompletionContext,
  [in]           FLT_POST_OPERATION_FLAGS Flags
)
{...}

Параметры

[in, out] Data

Указатель на данные обратного вызова FLT_CALLBACK_DATA структуру для операции ввода-вывода.

[in] FltObjects

Указатель на диспетчер фильтров, сохраненный FLT_RELATED_OBJECTS структуре, содержащей непрозрачные указатели для объектов, связанных с текущим запросом ввода-вывода.

[in, optional] CompletionContext

Указатель контекста, возвращенный функцией обратного вызова драйвера мини-фильтра перед операцией PFLT_PRE_OPERATION_CALLBACK подпрограммой. Указатель CompletionContext предоставляет способ передачи сведений из подпрограммы обратного вызова перед операцией в подпрограмму обратного вызова после операции.

[in] Flags

Битовая маска флагов, указывающая способ выполнения обратного вызова после операции.

Flag	Значение
FLTFL_POST_OPERATION_DRAINING	Диспетчер фильтров устанавливает этот флаг, чтобы указать, что экземпляр драйвера минифильтра отсоединяется и что эта подпрограмма обратного вызова после операции вызывается для очистки контекста завершения драйвера минифильтра. Обратный вызов после операции должен возвращать FLT_POSTOP_FINISHED_PROCESSING. Если этот флаг установлен, параметр Data указывает на копию исходной структуры данных обратного вызова для операции, а не на исходную структуру данных обратного вызова. Кроме того, если этот флаг установлен, подпрограмма обратного вызова после операции вызывается в IRQL <= APC_LEVEL.

Flag

Значение

FLTFL_POST_OPERATION_DRAINING

Диспетчер фильтров устанавливает этот флаг, чтобы указать, что экземпляр драйвера минифильтра отсоединяется и что эта подпрограмма обратного вызова после операции вызывается для очистки контекста завершения драйвера минифильтра. Обратный вызов после операции должен возвращать FLT_POSTOP_FINISHED_PROCESSING. Если этот флаг установлен, параметр Data указывает на копию исходной структуры данных обратного вызова для операции, а не на исходную структуру данных обратного вызова. Кроме того, если этот флаг установлен, подпрограмма обратного вызова после операции вызывается в IRQL <= APC_LEVEL.

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

Эта подпрограмма обратного вызова возвращает одно из следующих значений состояния:

Код возврата	Описание
FLT_POSTOP_FINISHED_PROCESSING	Драйвер минифильтра завершил обработку завершения операции ввода-вывода и возвращает управление операцией диспетчеру фильтров. После того как обратный вызов возвращает это значение состояния, диспетчер фильтров продолжает обработку завершения операции ввода-вывода.
FLT_POSTOP_MORE_PROCESSING_REQUIRED	Драйвер минифильтра приостановил обработку завершения операции ввода-вывода, но не возвращает управление операцией диспетчеру фильтров. Обратный вызов драйвера минифильтра после операции может возвращать это значение состояния, только если обратный вызов драйвера минифильтра после операции переместил операцию ввода-вывода в рабочую очередь. Драйвер мини-фильтра должен в конечном итоге возобновить обработку завершения операции ввода-вывода. После того как обратный вызов после операции возвращает FLT_POSTOP_MORE_PROCESSING_REQUIRED, диспетчер фильтров не выполняет дальнейшую обработку завершения операции ввода-вывода, если не выполняются оба следующих условия: Обратный вызов после операции переместил операцию ввода-вывода в рабочую очередь. После того как рабочая подпрограмма выполнит обработку завершения операции, она вызывает FltCompletePendedPostOperation , чтобы вернуть управление операцией диспетчеру фильтров. Это значение состояния может быть возвращено только для операций ввода-вывода на основе IRP. Чтобы определить, представляет ли данная структура данных обратного вызова операцию ввода-вывода на основе IRP, используйте макрос FLT_IS_IRP_OPERATION .
FLT_POSTOP_DISALLOW_FSFILTER_IO	Драйвер мини-фильтра не разрешает быструю операцию QueryOpen и заставляет ее спуститься по медленному пути. Это приводит к тому, что диспетчер ввода-вывода обслужит запрос, выполнив открытие, запрос и закрытие файла. Драйверы мини-фильтра должны возвращать это состояние только для Параметра QueryOpen.

Код возврата

Описание

FLT_POSTOP_FINISHED_PROCESSING

Драйвер минифильтра завершил обработку завершения операции ввода-вывода и возвращает управление операцией диспетчеру фильтров.

После того как обратный вызов возвращает это значение состояния, диспетчер фильтров продолжает обработку завершения операции ввода-вывода.

FLT_POSTOP_MORE_PROCESSING_REQUIRED

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

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

После того как обратный вызов после операции возвращает FLT_POSTOP_MORE_PROCESSING_REQUIRED, диспетчер фильтров не выполняет дальнейшую обработку завершения операции ввода-вывода, если не выполняются оба следующих условия:

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

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

FLT_POSTOP_DISALLOW_FSFILTER_IO

Драйвер мини-фильтра не разрешает быструю операцию QueryOpen и заставляет ее спуститься по медленному пути. Это приводит к тому, что диспетчер ввода-вывода обслужит запрос, выполнив открытие, запрос и закрытие файла. Драйверы мини-фильтра должны возвращать это состояние только для Параметра QueryOpen.

Подпрограммы обратного вызова после операции вызываются в произвольном контексте потока в irQL <= DISPATCH_LEVEL. Так как эта подпрограмма обратного вызова может вызываться на DISPATCH_LEVEL IRQL, на нее распространяются следующие ограничения:

Он не может безопасно вызывать какую-либо подпрограмму в режиме ядра, которая должна выполняться на более низком уровне IRQL.
Все структуры данных, используемые в этой подпрограмме, должны быть выделены из непагрегированного пула.
Его нельзя сделать страничной.
Он не может получить ресурсы, мьютексы или быстрые мьютексы. Однако он может получить спин-блокировки.
Он не может получать, задавать или удалять контексты, но может освобождать контексты.

Обработка завершения ввода-вывода, которую необходимо выполнить в IRQL < DISPATCH_LEVEL, не может выполняться непосредственно в процедуре обратного вызова после операции. Вместо этого он должен быть помещен в рабочую очередь путем вызова подпрограммы, такой как FltDoCompletionProcessingWhenSafe или FltQueueDeferredIoWorkItem.

Имейте в виду, что FltDoCompletionProcessingWhenSafe никогда не следует вызывать, если параметр Flags обратного вызова после операции имеет FLTFL_POST_OPERATION_DRAINING бит. Ниже приведены исключения из этого правила.

Если подпрограмма обратного вызова драйвера минифильтра перед операцией возвращает FLT_PREOP_SYNCHRONIZE для операции ввода-вывода на основе IRP, соответствующая подпрограмма обратного вызова после операции гарантированно будет вызвана в IRQL <= APC_LEVEL в том же контексте потока, что и обратный вызов перед операцией.
Подпрограммы обратного вызова после создания гарантированно вызываются на PASSIVE_LEVEL IRQL в контексте потока, который вызвал IRP_MJ_CREATE операцию.

Драйвер минифильтра регистрирует подпрограмму обратного вызова после операции для определенного типа операции ввода-вывода, сохраняя точку входа подпрограммы обратного вызова в массиве OperationRegistrationструктуры FLT_REGISTRATION . Драйвер минифильтра передает эту структуру в качестве параметра в FltRegisterFilter в своей подпрограмме DriverEntry .

Драйвер минифильтра может зарегистрировать подпрограмму обратного вызова после операции для определенного типа операции ввода-вывода без регистрации процедуры обратного вызова перед операцией (PFLT_PRE_OPERATION_CALLBACK) и наоборот.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в накопительном пакете обновления 1 для Microsoft Windows 2000 с пакетом обновления 4 (SP4), Windows XP с пакетом обновления 2 (SP2), Windows Server 2003 с пакетом обновления 1 (SP1) и более поздних версий операционных систем Windows.
Целевая платформа	Персональный компьютер
Верхняя часть	fltkernel.h (включая FltKernel.h)
IRQL	См. раздел "Примечания"