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

Статья
02/29/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 должен проверка только для ключа oplock на 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 имеет следующие параметры:

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

[in, optional] PostIrpRoutine

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

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

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

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

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

[in] Timeout

Если значение не равно нулю, указывает время ожидания (в миллисекундах) для ожидания события, используемого для блокировки потока вызывающего объекта, чтобы дождаться завершения прерывания блокировки. Это значение игнорируется, если не выполняются оба следующих условия: 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 была указана в параметре 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, FsRtlCheckOplockEx2 блокируется, а не возвращает STATUS_PENDING. STATUS_PENDING — это код успешного выполнения.

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

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

OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT
OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED

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

Если флаг OPLOCK_FLAG_PARENT_OBJECT указан в разделе Флаги, FsRtlCheckOplockEx2 безоговорочно разорвет все существующие родительские блокировки; т. е. основной код в IRP не учитывается.

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