IoGetLowerDeviceObject function (ntifs.h)

Article
03/15/2024

The IoGetLowerDeviceObject routine returns a pointer to the next-lower-level device object on the driver stack.

Syntax

PDEVICE_OBJECT IoGetLowerDeviceObject(
  [in] PDEVICE_OBJECT DeviceObject
);

Parameters

[in] DeviceObject

A pointer to the device object in the stack for which the next-lower-level device object is to be returned.

Return value

IoGetLowerDeviceObject returns a pointer to the next-lower-level device object on the driver stack.

Remarks

Given a pointer to a device object in a file system or device driver stack, IoGetLowerDeviceObject returns a pointer to the next-lower-level device object on the stack.

IoGetLowerDeviceObject returns NULL if:

The next-lower-level driver is not loaded.
The next-lower-level driver is currently being unloaded, removed, or deleted.
The device object pointed to by DeviceObject is the lowest device object in the driver stack.

A file system filter driver typically uses IoGetLowerDeviceObject to determine whether it is already attached to the filter driver stack that is chained above a given file system device object. First, the filter calls IoGetAttachedDeviceReference to get a pointer to the topmost device object in the stack. Then it calls IoGetLowerDeviceObject repeatedly to walk the driver stack, checking each device object to see whether the object belongs to the filter driver.

IoGetLowerDeviceObject increments the reference count on the next-lower-level device object if there is one. Thus every call to IoGetLowerDeviceObject that doesn't return NULL must be matched by a subsequent call ObDereferenceObject.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 SP4 Update Rollup; Windows XP
Target Platform	Universal
Header	ntifs.h (include Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL