IoCreateStreamFileObjectEx2 routine

The IoCreateStreamFileObjectEx2 routine creates a new stream file object with create options for a target device object.

Syntax


PFILE_OBJECT IoCreateStreamFileObjectEx(
  _In_      PIO_CREATE_STREAM_FILE_OPTIONS CreateOptions,
  _In_opt_  PFILE_OBJECT                   FileObject,
  _In_opt_  PDEVICE_OBJECT                 DeviceObject,
  _Out_     PDEVICE_OBJECT                 *StreamFileObject,
  _Out_opt_ PHANDLE                        FileHandle
);

Parameters

CreateOptions [in]

Pointer a IO_CREATE_STREAM_FILE_OPTIONS structure containing the create options for the new stream file object. IO_CREATE_STREAM_FILE_OPTIONS is defined in ntifs.h as the following.

typedef struct _IO_CREATE_STREAM_FILE_OPTIONS {
    USHORT Size;
    USHORT Flags;
    PDEVICE_OBJECT TargetDeviceObject;
} IO_CREATE_STREAM_FILE_OPTIONS, *PIO_CREATE_STREAM_FILE_OPTIONS;

Size

Size of the stream options structure. Set to sizeof(IO_CREATE_STREAM_FILE_OPTIONS).

Flags

The flags for the stream file create options. This value can be one of the following.

TermDescription

IO_CREATE_STREAM_FILE_RAISE_ON_ERROR

On an error condition, IoCreateStreamFileObjectEx2 will raise the error status as an exception instead of returning it. This flag is specified to maintain error status behavior of the other stream file object creation routines.

IO_CREATE_STREAM_FILE_LITE

A file object is created with out a file handle. No close operation is sent for the file object when it is deleted.

 

TargetDeviceObject

A pointer to the device object to set as the target for operations on the file handle. TargetDeviceObject must be in the same device stack as DeviceObject parameter. This member is optional.

FileObject [in, optional]

Pointer to the file object to which the new stream file is related. This parameter is optional and can be NULL.

DeviceObject [in, optional]

Pointer to a device object for the device on which the stream file is to be opened. If the caller specifies a non-NULL value for FileObject, the value of DeviceObject is ignored. Otherwise, the caller must specify a non-NULL value for DeviceObject.

StreamFileObject [out]

Pointer to a device object pointer to receive the stream fille object.

FileHandle [out, optional]

A pointer to a file handle for the stream on output. This parameter is optional and can be NULL.

Return value

IoCreateStreamFileObjectEx2 returns a pointer to the newly created stream file object.

Remarks

File systems call IoCreateStreamFileObjectEx2 to create a new stream file object. A stream file object is identical to an ordinary file object, except that the FO_STREAM_FILE file object flag is set.

A stream file object is commonly used to represent an internal stream for a volume mounted by the file system. This virtual volume file permits the file system to view, change, and cache the volume's on-disk structure as if it were an ordinary file. In this case, the DeviceObject parameter in the call to IoCreateStreamFileObjectEx2 specifies the volume device object (VDO) for the volume.

A stream file object can also be used to represent an alternate data stream for accessing a file's metadata, such as extended attributes or security descriptors. In this case, the FileObject parameter in the call to IoCreateStreamFileObjectEx2 specifies an existing file object for the file. The newly created stream file object permits the file system to view, change, and cache the file's metadata as if it were an ordinary file.

When the stream file object is no longer needed, the caller must decrement its reference count by calling ObDereferenceObject. When the stream file object's reference count reaches zero, an IRP_MJ_CLOSE request is sent to the file system driver stack for the volume.

File system filter driver writers should note that IoCreateStreamFileObjectEx2 causes an IRP_MJ_CLEANUP request to be sent to the file system driver stack for the volume. Because file systems often create stream file objects as a side effect of operations other than IRP_MJ_CREATE, it is difficult for filter drivers to reliably detect stream file object creation. Thus a filter driver should expect to receive IIRP_MJ_CLEANUP and IRP_MJ_CLOSE requests for previously unseen file objects.

If a pool allocation failure occurs, IoCreateStreamFileObjectEx2 raises a STATUS_INSUFFICIENT_RESOURCES exception.

Requirements

Target platform

Universal

Version

Available starting with Windows 8.

Header

Ntifs.h (include Ntifs.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

PASSIVE

See also

IoCreateStreamFileObject
IoCreateStreamFileObjectEx
IoCreateStreamFileObjectLite
IRP_MJ_CLEANUP
IRP_MJ_CLOSE
IRP_MJ_CREATE
ObDereferenceObject

 

 

Send comments about this topic to Microsoft

Show: