FILE_OBJECT

To user-mode protected subsystems, a file object represents an open instance of a file, device, directory, or volume. To device and intermediate drivers, a file object usually represents a device object.

A file object is partially opaque. Certain types of drivers, such as FSDs and network transport drivers, use some of the fields of file objects. The following fields in file objects are accessible to drivers.

Accessible Fields

PDEVICE_OBJECT DeviceObject

Points to the device object on which the file is opened.

PVOID FsContext

Points to whatever optional state a driver maintains about the file object; otherwise, NULL.

PVOID FsContext2

Points to whatever additional state a driver maintains about the file object; otherwise, NULL.

UNICODE_STRING FileName

Is the name of the file opened on the device, or the Length of the string is zero if the device represented by DeviceObject is being opened.

Comments

Drivers can use the FsContext fields to maintain driver-determined state about an open file object. A driver cannot use these fields of a file object unless it is accessible in the driver’s I/O stack location of an IRP.

The remaining fields in a file object are opaque. They are reserved for use by the I/O Manager and file systems.

Undocumented fields within a file object should be considered inaccessible. Drivers with dependencies on object field locations or access to undocumented fields might not remain portable and interoperable with other drivers over time.

A higher-level driver that successfully calls IoGetDeviceObjectPointer during initialization is given a pointer to the file object that represents the next-lower driver’s device object in user mode. Such a higher-level driver should save the returned file object pointer. To release its reference to this file object, for example when the driver is being unloaded, the driver must call ObDereferenceObject with this file object pointer.

See Also

DEVICE_OBJECT, IoGetDeviceObjectPointer, ObDereferenceObject