Функция IoCancelFileOpen (ntddk.h)

Статья
03/08/2023

Подпрограмма IoCancelFileOpen может использоваться драйвером фильтра файловой системы для закрытия файла, открытого драйвером файловой системы в стеке устройств драйвера фильтра.

Синтаксис

void IoCancelFileOpen(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PFILE_OBJECT   FileObject
);

Параметры

[in] DeviceObject

Указатель на верхнюю часть стека устройств непосредственно под объектом устройства драйвера фильтра.

[in] FileObject

Указатель на объект файла, который нужно закрыть.

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

None

Remarks

Если драйвер фильтра файловой системы определяет, что запрос на открытие файла или создание файла должен завершиться сбоем после того, как драйверы нижнего уровня уже завершили запрос с STATUS_SUCCESS, он может использовать IoCancelFileOpen для закрытия файла, открытого драйверами более низкого уровня.

Хотя STATUS_REPARSE является значением NTSTATUS успешного выполнения, не нужно вызывать IoCancelFileOpen для операции создания, которая была завершена с STATUS_REPARSE, так как это значение состояния указывает, что файл не был успешно открыт.

Успешный вызов IoCancelFileOpen имеет следующий эффект: для минифильтров и устаревших фильтров, которые находятся над вызывающим элементом в стеке файловой системы, запрос на создание, как представляется, завершился сбоем. Для тех, которые находятся под вызывающим элементом, файл, как представляется, был открыт (или создан), а затем закрыт.

Обратите внимание, что IoCancelFileOpen не отменяет никаких изменений в файле. Например, IoCancelFileOpen не удаляет только что созданный файл и не восстанавливает файл, который был перезаписан или заменен до предыдущего состояния.

Типичный пример:

Драйвер фильтра существует между драйвером фильтра более высокого уровня и драйвером файловой системы более низкого уровня.
Драйвер фильтра передает запрос IRP_MJ_CREATE вниз по стеку устройств драйверу файловой системы, и драйвер файловой системы завершает запрос IRP_MJ_CREATE с состоянием STATUS_SUCCESS.
Прежде чем драйвер фильтра завершит запрос на создание, он определяет, что файл необходимо закрыть.
Драйвер фильтра использует IoCancelFileOpen , чтобы закрыть файл, открытый драйвером файловой системы.

После вызова IoCancelFileOpen драйвер фильтра должен завершить запрос на создание с соответствующим кодом ошибки, например STATUS_UNSUCCESSFUL или STATUS_ACCESS_DENIED. Кроме того, для поля Irp-IoStatus.Information> должно быть задано значение 0.

Перед созданием дескрипторов для файла необходимо вызвать IoCancelFileOpen. Вызывающие объекты могут проверка элемент Flagsструктуры FILE_OBJECT, на которую указывает параметр FileObject. Если установлен флаг FO_HANDLE_CREATED, это означает, что для файла создан один или несколько дескрипторов, поэтому вызывать IoCancelFileOpen небезопасно.

IoCancelFileOpen задает флаг FO_FILE_OPEN_CANCELLED в элементе Flags объекта файла, на который указывает FileObject . Этот флаг указывает, что запрос IRP_MJ_CREATE отменен, и для этого объекта файла будет выдан запрос IRP_MJ_CLOSE. После отмены операции создания ее нельзя будет повторно выпустить, то есть STATUS_REPARSE не может быть возвращена устаревшим драйвером фильтра, если он вызвал подпрограмму IoCreateFileOpen .

Минифильтры должны использовать FltCancelFileOpen вместо IoCancelFileOpen.

Требования

Требование	Значение
Минимальная версия клиента	Эта подпрограмма доступна в Microsoft Windows 2000 и более поздних версий.
Целевая платформа	Универсальное
Верхняя часть	ntddk.h (включая Ntddk.h, Ntifs.h, Fltkernel.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL