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

Статья
12/21/2024

FsRtlOplockFsctrl выполняет различные операции оппортунистической блокировки (oplock) от имени файловой системы или драйвера фильтра.

Синтаксис

NTSTATUS FsRtlOplockFsctrl(
  [in] POPLOCK Oplock,
  [in] PIRP    Irp,
  [in] ULONG   OpenCount
);

Параметры

[in] Oplock

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

[in] Irp

Указатель на IRP для операции ввода-вывода. Этот параметр является обязательным и не может быть null.

[in] OpenCount

Количество пользовательских дескрипторов для файла, если запрашивается монопольная блокировка. Задание ненулевого значения для запроса oplock уровня 2, R или RH указывает на наличие блокировок диапазона байтов в файле. Сведения о типах oplock см. в обзоре Oplock.

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

FsRtlOplockFsctrl возвращает одно из следующих значений NTSTATUS:

Возвращаемый код	Описание
STATUS_SUCCESS	Для запроса IRP_MJ_CREATE STATUS_SUCCESS указывает, что запрошенная блокировка фильтра была предоставлена. Для операции FSCTL значение STATUS_SUCCESS зависит от кода FSCTL. Дополнительные сведения см. на справочных страницах для кодов FSCTL, перечисленных в следующем разделе "Примечания".
STATUS_CANCELLED	Операция ввода-вывода отменена. STATUS_CANCELLED — это код ошибки.
STATUS_INVALID_PARAMETER	Код FSCTL для операции ввода-вывода не был одним из допустимых значений, перечисленных в следующем разделе примечания. STATUS_INVALID_PARAMETER — это код ошибки.
STATUS_OPLOCK_NOT_GRANTED	Не удалось предоставить оплок. STATUS_OPLOCK_NOT_GRANTED — это код ошибки.
STATUS_PENDING	Используется только для операций FSCTL. Значение STATUS_PENDING зависит от кода FSCTL. Дополнительные сведения см. на справочных страницах для кодов FSCTL, перечисленных в следующем разделе "Примечания". STATUS_PENDING — это код успешного выполнения.
STATUS_CANNOT_BREAK_OPLOCK	Новое оплок не может быть предоставлено. IRP — это запрос IRP_MJ_CREATE и FILE_OPEN_REQUIRING_OPLOCK был указан в параметре параметров создания для операции. STATUS_CANNOT_BREAK_OPLOCK — это код успешного выполнения.

Замечания

Файловые системы и устаревшие драйверы фильтров вызывают FsRtlOplockFsctrl для выполнения различных операций управления операцией ввода-вывода или управления файловой системой. Минифильтры должны вызывать FltOplockFsctrl вместо FsRtlOplockFsctrl.

IRP, на который указывает параметр Irp, должен быть допустимым IRP для операции IRP_MJ_FILE_SYSTEM_CONTROL или IRP_MJ_CREATE.

Если IRP является запросом IRP_MJ_FILE_SYSTEM_CONTROL, FsRtlOplockFsctrl можно использовать с одним из следующих кодов FSCTL, который устанавливается в IrpSp->Parameters.FileSystemControl.FsControl.FsControlCode:

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

Если IRP является запросом IRP_MJ_CREATE, FsRtlOplockFsctrl можно использовать для запроса ожидающей блокировки фильтра, если все из следующих условий имеют значение true:

Значение параметра OpenCount должно иметь значение 1.
Значение параметра DesiredAccess для запроса IRP_MJ_CREATE должно быть FILE_READ_ATTRIBUTES.
Значение параметра ShareAccess для запроса IRP_MJ_CREATE должно быть FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

Если запрос для ожидающего блокировки фильтра предоставлен, FsRtlOplockFsctrl возвращает STATUS_SUCCESS. Дополнительные сведения о создании параметров см. в справочной записи для IRP_MJ_CREATE.

Фильтры и файловые системы, вызывающие эту функцию, должны синхронизировать вызовы в пакет oplock, предоставленный системой. Дополнительные сведения см. в синхронизации Oplock.

Требования

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