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

Статья
02/26/2024

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

Синтаксис

PFILE_OBJECT IoCreateStreamFileObject(
  [in, optional] PFILE_OBJECT   FileObject,
  [in, optional] PDEVICE_OBJECT DeviceObject
);

Параметры

[in, optional] FileObject

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

[in, optional] DeviceObject

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

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

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

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

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

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

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

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

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

Требования

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