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

Статья
09/27/2023

Подпрограмма 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. Параметр флагов имеет следующие параметры:

Ценность	Значение
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
      );

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

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

[in, optional] PostIrpRoutine

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

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

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

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

Параметр	Описание
Контекст	Указатель сведений о контекст е, переданный в параметре контекста 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 был указан в параметре параметров создания для операции, и существует предоставленная оплока.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Ведется оппортунистический разрыв блокировки. IRP — это запрос IRP_MJ_CREATE и FILE_COMPLETE_IF_OPLOCKED был указан в параметре создания параметров для операции. STATUS_OPLOCK_BREAK_IN_PROGRESS — это код успешного выполнения, возвращаемый при задании OPLOCK_FLAG_COMPLETE_IF_OPLOCKED, а оппортунистическая блокировка была нарушена.
STATUS_PENDING	Была инициирована оппортунистическая блокировка, а управление IRP передано в пакет oplock. Если значение CompletionRoutine равно NULL, эта подпрограмма будет блокироваться во время обработки останова оплока, а не возвращать STATUS_PENDING. STATUS_PENDING — это код успешного выполнения.

Замечания

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

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

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

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

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

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista
целевая платформа	Всеобщий
заголовка	ntifs.h (include Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL