Expand Minimize

IoEnumerateDeviceObjectList routine

The IoEnumerateDeviceObjectList routine enumerates a driver's device object list.

Syntax


NTSTATUS IoEnumerateDeviceObjectList(
  _In_   PDRIVER_OBJECT DriverObject,
  _Out_  PDEVICE_OBJECT *DeviceObjectList,
  _In_   ULONG DeviceObjectListSize,
  _Out_  PULONG ActualNumberDeviceObjects
);

Parameters

DriverObject [in]

A pointer to the driver object for the driver.

DeviceObjectList [out]

A pointer to a caller-allocated array that receives the device object pointers. This parameter can be NULL.

DeviceObjectListSize [in]

Size, in bytes, of the DeviceObjectList array. Can be zero.

ActualNumberDeviceObjects [out]

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.

Return value

IoEnumerateDeviceObjectList can return one of the following:

Return codeDescription
STATUS_SUCCESS

The call to IoEnumerateDeviceObjectList was successful.

STATUS_BUFFER_TOO_SMALL

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.

 

Remarks

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.

IoEnumerateDeviceObjectList returns all device objects created by the driver. This includes control device objects (CDO) as well as volume device objects (VDO). The two types of device objects can be distinguished by the fact that, by convention, CDOs are named and VDOs are not.

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.

Requirements

Version

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)

Library

Ntoskrnl.lib

IRQL

<= DISPATCH_LEVEL

See also

IoGetAttachedDevice
IoGetAttachedDeviceReference
IoGetLowerDeviceObject
ObDereferenceObject
ZwUnloadDriver

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.