Поделиться через

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

  • Статья

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

Синтаксис

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

Параметры

[in] Oplock

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

[in] CallbackData

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

[in] Flags

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

OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)

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

OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)

Указывает, что FltCheckOplockEx должен проверять только оппортунистический ключ блокировки на FILE_OBJECT, связанной с операцией ввода-вывода. Эти операции ввода-вывода представлены данными обратного вызова, на которые указывает параметр CallbackData. FltCheckOplockEx необходимо добавить ключ, если он указан в операции ввода-вывода. Ни один другой процесс обработки оплока не выполняется; т. е. не будет происходить оппортунистический разрыв блокировки.

OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)

Указывает, что FsRtlCheckOplockEx должен вернуть любое состояние, ранее настроенное с помощью вызова процедуры FltOplockFsctrl. FltOplockFsctrl вызывается при обработке запроса IRP_MJ_CREATE. Этот запрос IRP_MJ_CREATE указывает флаг FILE_OPEN_REQUIRING_OPLOCK в параметре создания параметров. Флаг OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK обычно используется в окончательной обработке такого запроса на создание при сбое.

OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)

Позволяет продолжать все оппортунистические разрывы блокировки независимо от ключа оппортунистической блокировки.

[in, optional] Context

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

[in, optional] WaitCompletionRoutine

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

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

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

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

CallbackData

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

примечание, что при вызове WaitCompleteRoutine подстрока IoStatus может быть заполнена состоянием сбоя (например, STATUS_CANCELLED). Вы должны проверить это состояние и реагировать соответствующим образом.

Контекст

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

[in, optional] PrePostCallbackDataRoutine

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

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

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

CallbackData

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

Контекст

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

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

FltCheckOplockEx возвращает один из следующих кодов FLT_PREOP_CALLBACK_STATUS:

Возвращаемый код Описание
FLT_PREOP_COMPLETE
 FltCheckOplockEx возникла ошибка выделения пула или вызов функции FsRtlCheckOplockEx. FltCheckOplockEx задает код ошибки в элементе состояния элемента структуры IO_STATUS_BLOCK IoStatus в структуре данных обратного вызова FLT_CALLBACK_DATA. Параметр CallbackData указывает на эту структуру FLT_CALLBACK_DATA.
FLT_PREOP_PENDING
 Была инициирована блокировка, из-за которой диспетчер фильтров опубликовал операцию ввода-вывода в рабочую очередь. Операция ввода-вывода представлена данными обратного вызова, на которые указывает параметр CallbackData.
FLT_PREOP_SUCCESS_WITH_CALLBACK
 Данные обратного вызова, которые CallbackData указывает на то, что параметр не был задан, и операция ввода-вывода была выполнена немедленно. Помните, что если вызывающий объект указал OPLOCK_FLAG_COMPLETE_IF_OPLOCKED в параметре Флаги, то разрыв блокировки оплока может выполняться, даже если операция ввода-вывода не была выполнена. Чтобы определить, является ли это ситуацией, вызывающий объект должен проверить наличие STATUS_OPLOCK_BREAK_IN_PROGRESS в элементе состояния члена структуры IO_STATUS_BLOCK IoStatus члена структуры данных обратного вызова FLT_CALLBACK_DATA.

Замечания

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

  • Если операция ввода-вывода приведет к прерыванию операции ввода-вывода, инициируется прерывание операции.

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

  • Если драйвер мини-фильтра использует оплоки, он должен вызывать FltCheckOplockEx из любой процедуры обратного вызова (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.

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

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

Требования

Требование Ценность
минимальные поддерживаемые клиентские Подпрограмма FltCheckOplockEx доступна начиная с Windows 7.
целевая платформа Всеобщий
заголовка fltkernel.h (include Fltkernel.h)
библиотеки FltMgr.lib
IRQL <= APC_LEVEL

См. также

FLT_CALLBACK_DATA

FLT_IS_IRP_OPERATION

FltInitializeOplock

FltOplockFsctrl

FsRtlCheckOplockEx

IO_STATUS_BLOCK

PFLT_PRE_OPERATION_CALLBACK