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

Статья
12/21/2024

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

Синтаксис

NTSTATUS FsRtlCheckOplockEx2(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in]           ULONG                         FlagsEx2,
  [in, optional] PVOID                         CompletionRoutineContext,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine,
  [in]           ULONGLONG                     Timeout,
  [in, optional] PVOID                         NotifyContext,
  [in, optional] POPLOCK_NOTIFY_ROUTINE        NotifyRoutine
);

Параметры

[in] Oplock

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

[in] Irp

Указатель на IRP, который объявляет запрошенную операцию ввода-вывода.

[in] Flags

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

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

[in] FlagsEx2

Скрытный; должно быть равно нулю.

[in, optional] CompletionRoutineContext

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

[in, optional] CompletionRoutine

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

CompletionRoutine объявлен следующим образом:

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

CompletionRoutine имеет следующие параметры:

контекста: указатель сведений о контексте, переданный в параметре контекста контекста для FsRtlCheckOplockEx2.
Irp: указатель на IRP для операции ввода-вывода.

[in, optional] PostIrpRoutine

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

PostIrpRoutine объявлен следующим образом:

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

PostIrpRoutine имеет следующие параметры:

Контекст, который является указателем сведений о контексте, который был передан в параметре контекстаFsRtlCheckOplockEx2.
Irp: указатель на IRP для операции ввода-вывода.

[in] Timeout

Если значение не равно нулю, указывает время ожидания (в миллисекундах), чтобы ждать события, используемого для блокировки потока вызывающего объекта, чтобы дождаться завершения разрыва оплока. Это значение игнорируется, если оба из следующих условий не имеют значения true: CompletionRoutine имеет значение NULL и NotifyRoutine не равно NULL.

[in, optional] NotifyContext

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

[in, optional] NotifyRoutine

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

NotifyRoutine объявлен следующим образом:

typedef NTSTATUS
(*POPLOCK_NOTIFY_ROUTINE) (
      IN POPLOCK_NOTIFY_PARAMS NotifyParams
      );

NotifyRoutine имеет следующие параметры:

NotifyParams, который является параметром NotifyContext, переданным FsRtlCheckOplockEx2.

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

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

Возвращаемый код	Описание
STATUS_CANCELLED	IRP был отменен. STATUS_CANCELLED — это код ошибки.
STATUS_CANNOT_BREAK_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, FsRtlCheckOplockEx2 блоки, а не возвращают STATUS_PENDING. STATUS_PENDING — это код успешного выполнения.

Замечания

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

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

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

Если поток вызывающего объекта заблокирован и NotifyRoutine не NULL, NotifyRoutine будет вызываться по любым или всем следующим причинам, заданным в NotifyParams:

OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT
OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED

Вызов NotifyRoutine по любой из указанных выше причин возникает только в том случае, если CompleteRoutine имеет значение NULL, и необходимо заблокировать поток вызывающего объекта, чтобы ждать завершения перерыва.

Если NotifyRoutine вызывается по причине OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT, он всегда будет вызываться по причине OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED, если ожидание завершается или завершается по какой-либо причине (что никогда не может быть).

FsRtlCheckOplockEx2 игнорирует коды состояния OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT и OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED, возвращенные NotifyRoutine.

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

Если флаг OPLOCK_FLAG_PARENT_OBJECT указан в Flags, FsRtlCheckOplockEx2 будет безоговорочно нарушать любой существующий родительский оплок; То есть основной код в Irp не считается.

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