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


Функция FsRtlCheckOplockEx (ntifs.h)

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

Синтаксис

NTSTATUS FsRtlCheckOplockEx(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in, optional] PVOID                         Context,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine
);

Параметры

[in] Oplock

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

[in] Irp

Указатель на IRP для операции ввода-вывода.

[in] Flags

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

Значение Значение
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001) Указывает, чтобы оппортунистический разрыв блокировки продолжался без блокировки или ожидания операции, вызвавшей прерывание блокировки.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002) Поддерживается начиная с Windows 7. Указывает, что FsRtlCheckOplockEx должен проверка только для ключа оппортунистической блокировки на FILE_OBJECT, связанном с IRP, на которую указывает параметр IRP. Затем FsRtlCheckOplockEx необходимо добавить ключ, если он указан в IRP. Другие операции обработки не выполняются; т. е. оппортунистический разрыв блокировки не будет происходить.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004) Поддерживается начиная с Windows 7. Указывает, что FsRtlCheckOplockEx должен отменить изменения любое состояние, которое было ранее настроено с помощью вызова подпрограммы FsRtlOplockFsctrl. FsRtlOplockFsctrl вызывается во время обработки запроса IRP_MJ_CREATE, указывающего флаг FILE_OPEN_REQUIRING_OPLOCK в параметре create options. Флаг OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK обычно используется при окончательной обработке такого запроса на создание, если он ранее завершился ошибкой.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008) Поддерживается начиная с Windows 7. Указывает, чтобы разрешить выполнение всех оппортунистических блокировок независимо от ключа оппортунистической блокировки.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010) Поддерживается начиная с Windows 8. Указывает, что Oplock связан с родительским элементом (каталогом) файла или каталога, в который направляется IRP в параметре IRP .
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020) Поддерживается начиная с Windows 8. Указывает, что операция ввода-вывода, указанная в IRP , является IRP_MJ_CLEANUP для дескриптора, который был изначально открыт с флагом FILE_DELETE_ON_CLOSE, заданным в параметрах создания. Этот флаг не действует, если IRP не является IRP_MJ_CLEANUP операцией. Указание этого флага может привести к оппортунистической блокировке.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040) Поддерживается начиная с Windows 8. Указывает обработку оппортунистического разрыва блокировки в родительском каталоге при удалении файла или ссылки в этом каталоге. Если этот флаг указан, его необходимо объединить с OPLOCK_FLAG_PARENT_OBJECT. Этот флаг необходимо указать, когда файловая система обрабатывает операцию, которая приводит к удалению ссылки или файла.

[in, optional] Context

Указатель на определяемые вызывающим объектом контекстные сведения, передаваемые подпрограммам обратного вызова, на которые указывают параметры CompletionRoutine и PostIrpRoutine .

[in, optional] CompletionRoutine

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

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

typedef VOID
(*POPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PVOID Context,
      IN PIRP Irp
      );

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

Параметр Описание
Контекст Указатель сведений о контексте, переданный в параметре Context в FsRtlCheckOplockEx.
Irp Указатель на IRP для операции ввода-вывода.

[in, optional] PostIrpRoutine

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

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

typedef VOID
(*POPLOCK_FS_PREPOST_IRP) (
      IN PVOID Context,
      IN PIRP Irp
      );

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

Параметр Описание
Контекст Указатель сведений о контексте, переданный в параметре Context в FsRtlCheckOplockEx.
Irp Указатель на IRP для операции ввода-вывода.

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

FsRtlCheckOplockEx возвращает STATUS_SUCCESS или соответствующий код NTSTATUS, например один из следующих:

Код возврата Описание
STATUS_CANCELLED IRP была отменена. STATUS_CANCELLED — это код ошибки.
STATUS_CANNOT_BREAK_OPLOCK Невозможно выполнить оппортунистическую блокировку (oplock). IRP — это запрос IRP_MJ_CREATE. FILE_OPEN_REQUIRING_OPLOCK была указана в параметре create options для операции, и имеется предоставленная блокировка oplock.
STATUS_OPLOCK_BREAK_IN_PROGRESS Идет оппортунистическая блокировка. IRP является IRP_MJ_CREATE запросом, и FILE_COMPLETE_IF_OPLOCKED был указан в параметре create options для операции. STATUS_OPLOCK_BREAK_IN_PROGRESS — это код успешного выполнения, который возвращается, если задано OPLOCK_FLAG_COMPLETE_IF_OPLOCKED и была нарушена оппортунистическая блокировка.
STATUS_PENDING Был инициирован оппортунистический разрыв блокировки, а управление IRP передано пакету oplock. Если параметр CompletionRoutine имеет значение NULL, эта подпрограмма будет блокироваться во время обработки прерывания операции, а не возвращать STATUS_PENDING. STATUS_PENDING — это код успешного выполнения.

Комментарии

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

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

  • Если операция ввода-вывода не может продолжаться до тех пор, пока не будет завершена оппортунистическая блокировка и не указана подпрограмма завершения в CompletionRoutine , функция FsRtlCheckOplockEx возвращает STATUS_PENDING и вызывает подпрограмму обратного вызова, указанную в PostIrpRoutine. При подтверждении оппортунистического разрыва блокировки вызывается подпрограмма обратного вызова в CompletionRoutine .

  • Если операция ввода-вывода не может продолжаться до тех пор, пока не будет завершена оппортунистическая блокировка и не указан параметр CompletionRoutine , функция FsRtlCheckOplockEx не будет возвращена, пока не будет подтверждена оппортунистическая блокировка.

PostIrpRoutine следует указывать только в том случае, если указан параметр CompletionRoutine.

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

  • 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

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

Минифильтры должны вызывать FltCheckOplockEx вместо FsRtlCheckOplockEx.

Требования

Требование Значение
Минимальная версия клиента Windows Vista
Целевая платформа Универсальное
Верхняя часть ntifs.h (включая Ntifs.h)
Библиотека NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL

См. также раздел

FSCTL_OPBATCH_ACK_CLOSE_PENDING

FSCTL_OPLOCK_BREAK_ACKNOWLEDGE

FSCTL_OPLOCK_BREAK_ACK_NO_2

FSCTL_OPLOCK_BREAK_NOTIFY

FSCTL_REQUEST_BATCH_OPLOCK

FSCTL_REQUEST_FILTER_OPLOCK

FSCTL_REQUEST_OPLOCK_LEVEL_1

FSCTL_REQUEST_OPLOCK_LEVEL_2

FltCheckOplockEx

FsRtlCurrentBatchOplock

FsRtlInitializeOplock

FsRtlOplockFsctrl

FsRtlOplockIsFastIoPossible

FsRtlUninitializeOplock