IoEnumerateDeviceObjectList 函数 (ntifs.h)

IoEnumerateDeviceObjectList 例程枚举驱动程序的设备对象列表。

语法

NTSTATUS IoEnumerateDeviceObjectList(
  [in]  PDRIVER_OBJECT DriverObject,
  [out] PDEVICE_OBJECT *DeviceObjectList,
  [in]  ULONG          DeviceObjectListSize,
  [out] PULONG         ActualNumberDeviceObjects
);

参数

[in] DriverObject

指向驱动程序对象的指针。

[out] DeviceObjectList

指向接收设备对象指针的调用方分配数组的指针。 此参数可以为 NULL。

[in] DeviceObjectListSize

DeviceObjectList 数组的大小(以字节为单位)。 可以为零。

[out] ActualNumberDeviceObjects

驱动程序对象的设备对象列表中找到的实际设备对象数。 请注意,如果 DeviceObjectList 处的数组太小,则复制到数组中的设备对象指针的数量将小于 ActualNumberDeviceObjects

返回值

IoEnumerateDeviceObjectList 可以返回以下项之一:

返回代码 说明
STATUS_SUCCESS
IoEnumerateDeviceObjectList 的调用已成功。
STATUS_BUFFER_TOO_SMALL
DeviceObjectList 处的数组太小,无法容纳整个设备对象列表。 在这种情况下, IoEnumerateDeviceObjectList 将尽可能多的设备对象指针复制到数组中。

备注

文件系统筛选器驱动程序调用 IoEnumerateDeviceObjectList 来枚举:

  • 它创建的设备对象。 当驱动程序准备卸载时,通常会执行此操作。 请注意,无法安全地从正在运行的系统卸载文件系统筛选器驱动程序。 有关详细信息,请参阅 ZwUnloadDriver
  • 基本文件系统创建的设备对象,因此筛选器知道可以附加到的卷数。
IoEnumerateDeviceObjectList 返回驱动程序创建的所有设备对象。 这包括 (CDO) 控制设备对象,以及 VDO) (卷设备对象。 这两种类型的设备对象可以通过这样一个事实来区分:按约定命名的 CDO 和 VDO 不是。

在后一种情况下,筛选器驱动程序通常调用 IoEnumerateDeviceObjectList 两次:一次获取列表中的设备对象数,一次获取设备对象列表本身。 在第一次调用中,调用方应将 DeviceObjectList 参数设置为 NULL将 DeviceObjectListSize 设置为零。 第二次调用中, DeviceObjectList 应包含指向适当大小的指针数组的指针, DeviceObjectListSize 应包含该数组的大小(以字节为单位)。

IoEnumerateDeviceObjectListDeviceObjectList 指向的列表中每个设备对象上递增引用计数。 因此,对 IoEnumerateDeviceObjectList 的每个成功调用都必须匹配对列表中每个设备对象的 ObDereferenceObject 的后续调用。 否则,由于未完成的引用计数,系统无法释放或删除这些设备对象。

要求

   
最低受支持的客户端 此例程适用于 Windows 2000 Service Pack 4 (SP4) 及更高版本更新汇总。
目标平台 通用
标头 ntifs.h (包括 Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= DISPATCH_LEVEL

另请参阅

IoGetAttachedDevice

IoGetAttachedDeviceReference

IoGetLowerDeviceObject

ObDereferenceObject

ZwUnloadDriver