IoCreateStreamFileObjectEx2 函数 (ntifs.h)

项目
07/11/2023

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 的值。否则，调用方必须为 DeviceObject 指定非 NULL 值。

[out] StreamFileObject

指向设备对象指针的指针，用于接收流填充对象。

[out, optional] FileHandle

指向输出时流的文件句柄的指针。此参数是可选的，可以为 NULL。

返回值

IoCreateStreamFileObjectEx2 返回指向新创建的流文件对象的指针。

注解

文件系统调用 IoCreateStreamFileObjectEx2 以创建新的流文件对象。 流文件对象与普通文件对象相同，只不过设置了FO_STREAM_FILE文件对象标志。

流文件对象通常用于表示文件系统装载的卷的内部流。此 虚拟卷文件 允许文件系统查看、更改和缓存卷的磁盘结构，就像它是一个普通文件一样。在这种情况下，调用 IoCreateStreamFileObjectEx2 中的 DeviceObject 参数指定卷 (VDO) 的卷设备对象。

流文件对象还可用于表示用于访问文件元数据的备用数据流，例如扩展属性或安全描述符。在这种情况下，对 IoCreateStreamFileObjectEx2 的调用中的 FileObject 参数指定文件的现有文件对象。新创建的流文件对象允许文件系统查看、更改和缓存文件的元数据，就像它是一个普通文件一样。

当不再需要流文件对象时，调用方必须通过调用 ObDereferenceObject 来递减其引用计数。当流文件对象的引用计数达到零时，会将IRP_MJ_CLOSE 请求发送到卷的文件系统驱动程序堆栈。

文件系统筛选器驱动程序编写者应注意 ，IoCreateStreamFileObjectEx2 会导致 IRP_MJ_CLEANUP 请求发送到卷的文件系统驱动程序堆栈。由于文件系统通常会创建流文件对象作为除IRP_MJ_CREATE以外的操作的副作用，因此筛选器驱动程序很难可靠地检测流文件对象的创建。因此，筛选器驱动程序应会收到 IIRP_MJ_CLEANUP ，并 IRP_MJ_CLOSE 以前未看到的文件对象的请求。

如果发生池分配失败， IoCreateStreamFileObjectEx2 将引发 STATUS_INSUFFICIENT_RESOURCES 异常。