Функция IoEnumerateDeviceObjectList (ntifs.h)

Статья
08/07/2023

Подпрограмма 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 возвращает код NTSTATUS, например одно из следующих значений:

Код возврата	Описание
STATUS_SUCCESS	Вызов IoEnumerateDeviceObjectList успешно завершен.
STATUS_BUFFER_TOO_SMALL	Массив в DeviceObjectList слишком мал для хранения всего списка объектов устройства. В этом случае IoEnumerateDeviceObjectList копирует в массив как можно больше указателей на объект устройства.

Созданные им объекты устройства. Обычно это делается, когда драйвер готовится к выгрузке. Обратите внимание, что драйвер фильтра не может быть безопасно выгружен из работающей системы. Дополнительные сведения см. в разделе ZwUnloadDriver.
Объекты устройства, созданные базовой файловой системой, поэтому фильтру известно количество томов, к которым он может подключиться.

IoEnumerateDeviceObjectList возвращает все объекты устройства, созданные драйвером фильтра. Сюда входят объекты управляющих устройств (CDOS), а также объекты устройств томов (VDOS). Два типа объектов устройств можно отличить по тому факту, что по соглашению cdos называются, а VDOs — нет.

В последнем случае драйвер фильтра обычно вызывает IoEnumerateDeviceObjectList дважды: один раз, чтобы получить количество объектов устройств в списке, и один раз, чтобы получить сам список объектов устройств. В первом вызове вызывающий объект должен задать для параметра DeviceObjectList значение NULL, а для Параметра DeviceObjectListSize — нулевое значение. Во втором вызове DeviceObjectList должен содержать указатель на массив указателей соответствующего размера, а DeviceObjectListSize — размер этого массива в байтах.

IoEnumerateDeviceObjectList увеличивает число ссылок на каждый объект устройства в списке, на который указывает DeviceObjectList. Таким образом, каждый успешный вызов IoEnumerateDeviceObjectList должен соответствовать последующему вызову ObDereferenceObject для каждого объекта устройства в списке. В этом случае система не может освободить или удалить эти объекты устройства из-за неоплаченного количества ссылок.

Требования

Требование	Значение
Минимальная версия клиента	Накопительный пакет обновления Windows 2000 с пакетом обновления 4 (SP4); Windows XP
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL