Функция FltCheckOplock (fltkernel.h)

Статья
02/26/2024

Драйвер мини-фильтра вызывает FltCheckOplock для синхронизации структуры данных обратного вызова для операции ввода-вывода на основе IRP с текущим оппортунистическим состоянием блокировки (oplock) файла.

Синтаксис

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplock(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [in, optional] PVOID                                   Context,
  [in, optional] PFLTOPLOCK_WAIT_COMPLETE_ROUTINE        WaitCompletionRoutine,
  [in, optional] PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE PrePostCallbackDataRoutine
);

Параметры

[in] Oplock

Непрозрачный указатель oplock для файла. Этот указатель должен быть инициализирован предыдущим вызовом FltInitializeOplock.

[in] CallbackData

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

[in, optional] Context

Указатель на определяемые вызывающим объектом контекстные сведения, передаваемые подпрограммам обратного вызова, на которые указывают WaitCompletionRoutine и PrePostCallbackDataRoutine . Диспетчер фильтров обрабатывает эти сведения как непрозрачные.

[in, optional] WaitCompletionRoutine

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

Эта подпрограмма объявляется следующим образом:

typedef VOID
(*PFLTOPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

Эта подпрограмма имеет следующие параметры:

CallbackData

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

Контекст

Указатель сведений о контексте, который был передан в параметре Contextв FltCheckOplock.

[in, optional] PrePostCallbackDataRoutine

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

Эта подпрограмма объявляется следующим образом:

typedef VOID
(*PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

CallbackData

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

Контекст

Указатель сведений о контексте, который был передан в параметре Contextв FltCheckOplock.

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

Функция FltCheckOplock возвращает один из следующих кодов FLT_PREOP_CALLBACK_STATUS:

Код возврата	Описание
FLT_PREOP_COMPLETE	FltCheckOplock обнаружил сбой выделения пула или вызов функции FsRtlCheckOplock вернул ошибку. FltCheckOplock задаст код ошибки в элементе Statusструктуры IO_STATUS_BLOCK элемента IoStatusструктуры данных FLT_CALLBACK_DATA обратного вызова. Параметр CallbackData указывает на этот FLT_CALLBACK_DATA.
FLT_PREOP_PENDING	Был инициирован разрыв блокировки, в результате которого диспетчер фильтров перенаправил операцию ввода-вывода в рабочую очередь. Операция ввода-вывода представлена данными обратного вызова, на которые указывает параметр CallbackData .
FLT_PREOP_SUCCESS_WITH_CALLBACK	Операция ввода-вывода была выполнена немедленно. Имейте в виду, что если эта операция была операцией создания, которая указала FILE_COMPLETE_IF_OPLOCKED в параметре create-options, возможно, на самом деле происходит прерывание блокировки, даже если операция была выполнена немедленно. Чтобы определить, является ли это ситуацией, вызывающий объект должен проверка состояние в элементе Statusструктуры IO_STATUS_BLOCK элемента IoStatus структуры данных обратного вызова FLT_CALLBACK_DATA.

Драйвер мини-фильтра вызывает FltCheckOplock для синхронизации операции ввода-вывода на основе IRP с текущим состоянием блокировки файла в соответствии со следующими условиями:

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

Если драйвер мини-фильтра использует блокировки, он должен вызывать FltCheckOplock из любых процедур обратного вызова перед работой (PFLT_PRE_OPERATION_CALLBACK) для операций ввода-вывода, которые могут привести к прерыванию работы. Это правило применяется к следующим типам операций ввода-вывода, так как эти операции могут привести к разрыву блокировки:

IRP_MJ_CLEANUP

IRP_MJ_CREATE

IRP_MJ_FILE_SYSTEM_CONTROL

IRP_MJ_FLUSH_BUFFERS

IRP_MJ_LOCK_CONTROL

IRP_MJ_READ

IRP_MJ_SET_INFORMATION

IRP_MJ_WRITE

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

Минифильтры не должны снова вызывать FltCheckOplock в обратном вызове, указанном в WaitCompletionRoutine. Это может привести к взаимоблокировке, если пакет oplock вызывает обратный вызов завершения до возврата FltCheckOplock .

Подробные сведения об оппортунистических блокировках см. в документации по Microsoft Windows SDK.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h)
IRQL	<= APC_LEVEL