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

Статья
02/26/2024

Подпрограмма IoCreateStreamFileObjectEx создает новый объект файла потока.

Синтаксис

PFILE_OBJECT IoCreateStreamFileObjectEx(
  [in, optional]  PFILE_OBJECT   FileObject,
  [in, optional]  PDEVICE_OBJECT DeviceObject,
  [out, optional] PHANDLE        FileHandle
);

Параметры

[in, optional] FileObject

Указатель на объект файла, с которым связан новый файл потока. Этот параметр является необязательным и может иметь значение NULL.

[in, optional] DeviceObject

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

[out, optional] FileHandle

Указатель на дескриптор файла для потока в выходных данных. Этот параметр является необязательным и может иметь значение NULL.

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

IoCreateStreamFileObjectEx возвращает указатель на только что созданный объект потокового файла.

Файловые системы вызывают IoCreateStreamFileObjectEx для создания нового объекта файла потока. Объект файла потока идентичен обычному файловому объекту, за исключением того, что установлен флаг FO_STREAM_FILE файлового объекта.

Объект stream file обычно используется для представления внутреннего потока для тома, подключенного файловой системой. Этот файл виртуального тома позволяет файловой системе просматривать, изменять и кэшировать структуру тома на диске, как если бы это был обычный файл. В этом случае параметр DeviceObject в вызове IoCreateStreamFileObjectEx указывает объект устройства тома (VDO) для тома.

Объект stream file также можно использовать для представления альтернативного потока данных для доступа к метаданным файла, например расширенным атрибутам или дескрипторам безопасности. В этом случае параметр FileObject в вызове IoCreateStreamFileObjectEx указывает существующий объект файла для файла. Созданный объект stream file позволяет файловой системе просматривать, изменять и кэшировать метаданные файла, как если бы это был обычный файл.

Если объект файла потока больше не требуется, вызывающий объект должен уменьшать количество ссылок путем вызова ObDereferenceObject. Когда количество ссылок объекта stream file достигает нуля, в стек драйверов файловой системы для тома отправляется запрос IRP_MJ_CLOSE.

Модули записи драйверов фильтров файловой системы должны учитывать, что IoCreateStreamFileObjectEx вызывает отправку запроса IRP_MJ_CLEANUP в стек драйверов файловой системы для тома. Так как файловые системы часто создают объекты потоковых файлов в качестве побочных эффектов операций, отличных от IRP_MJ_CREATE, драйверам фильтров сложно надежно обнаружить создание объектов потокового файла. Таким образом, драйвер фильтра должен ожидать получения IRP_MJ_CLEANUP и IRP_MJ_CLOSE запросов для ранее невидимых файловых объектов.

Если происходит сбой выделения пула, IoCreateStreamFileObjectEx вызывает исключение STATUS_INSUFFICIENT_RESOURCES.

Требования

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