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

Статья
09/27/2023

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

Синтаксис

NTSTATUS FsRtlCheckOplock(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [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, optional] Context

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

[in, optional] CompletionRoutine

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

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

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

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

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

[in, optional] PostIrpRoutine

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования

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