Функция 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. Параметр 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 — это код успешного выполнения.

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