The IoEnumerateDeviceObjectList routine enumerates a driver's device object list.
NTSTATUS IoEnumerateDeviceObjectList( PDRIVER_OBJECT DriverObject, PDEVICE_OBJECT *DeviceObjectList, ULONG DeviceObjectListSize, PULONG ActualNumberDeviceObjects );
A pointer to the driver object for the driver.
A pointer to a caller-allocated array that receives the device object pointers. This parameter can be NULL.
Size, in bytes, of the DeviceObjectList array. Can be zero.
Actual number of device objects found in the driver object's device object list. Note that if the array at DeviceObjectList is too small, the number of device object pointers that are copied into the array will be less than ActualNumberDeviceObjects.
IoEnumerateDeviceObjectList can return one of the following:
||The call to IoEnumerateDeviceObjectList was successful.|
||The array at DeviceObjectList is too small to hold the entire device object list. In this case, IoEnumerateDeviceObjectList copies as many device object pointers into the array as possible.|
A file system filter driver calls IoEnumerateDeviceObjectList to enumerate:
- The device objects it has created. This is commonly done when the driver is preparing to unload. Note that a file system filter driver cannot safely be unloaded from a running system. For more information, see ZwUnloadDriver.
- The device objects created by the base file system, so the filter knows the number of volumes to which it can attach.
In the latter case, the filter driver typically calls IoEnumerateDeviceObjectList twice: once to get the number of device objects in the list, and once to get the device object list itself. In the first call, the caller should set the DeviceObjectList parameter to NULL and DeviceObjectListSize to zero. In the second call, DeviceObjectList should contain a pointer to an appropriately-sized pointer array, and DeviceObjectListSize should contain the size, in bytes, of that array.
IoEnumerateDeviceObjectList increments the reference count on every device object in the list pointed to by DeviceObjectList. Thus every successful call to IoEnumerateDeviceObjectList must be matched by a subsequent call to ObDereferenceObjectfor each device object in the list. Failure to do so prevents the system from freeing or deleting these device objects because of an outstanding reference count.
|Minimum supported client||This routine is available on Update Rollup for Windows 2000 Service Pack 4 (SP4) and on Windows XP and later.|
|Header||ntifs.h (include Ntifs.h)|