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

Статья
03/01/2024

Подпрограмма IoCreateStreamFileObjectEx2 создает новый объект файла потока с параметрами создания для объекта целевого устройства.

Синтаксис

NTSTATUS IoCreateStreamFileObjectEx2(
  [in]            PIO_CREATE_STREAM_FILE_OPTIONS CreateOptions,
  [in, optional]  PFILE_OBJECT                   FileObject,
  [in, optional]  PDEVICE_OBJECT                 DeviceObject,
  [out]           PFILE_OBJECT                   *StreamFileObject,
  [out, optional] PHANDLE                        FileHandle
);

Параметры

[in] CreateOptions

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

[in, optional] FileObject

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

[in, optional] DeviceObject

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

[out] StreamFileObject

Указатель на объект устройства для получения объекта stream fille.

[out, optional] FileHandle

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

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

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

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

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

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

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

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

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

Требования

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