Функция IoReportDetectedDevice (ntddk.h)

Статья
08/07/2023

Подпрограмма IoReportDetectedDevice сообщает об устройстве, отличном от PnP, диспетчеру PnP.

Синтаксис

NTSTATUS IoReportDetectedDevice(
  [in]           PDRIVER_OBJECT                 DriverObject,
  [in]           INTERFACE_TYPE                 LegacyBusType,
  [in]           ULONG                          BusNumber,
  [in]           ULONG                          SlotNumber,
  [in, optional] PCM_RESOURCE_LIST              ResourceList,
  [in, optional] PIO_RESOURCE_REQUIREMENTS_LIST ResourceRequirements,
  [in]           BOOLEAN                        ResourceAssigned,
  [in, out]      PDEVICE_OBJECT                 *DeviceObject
);

Параметры

[in] DriverObject

Указатель на объект драйвера драйвера, который обнаружил устройство.

[in] LegacyBusType

Указывает тип шины, в которой находится устройство. Диспетчер PnP использует эти сведения для сопоставления сообщаемого устройства с экземпляром с перечислением PnP, если таковой существует.

Типы интерфейсов, такие как PCIBus, определены в Wdm.h. Если драйвер не знает legacyBusType для устройства, драйвер предоставляет значение InterfaceTypeUndefined для этого параметра.

[in] BusNumber

Указывает номер шины для устройства. Диспетчер PnP использует эти сведения для сопоставления сообщаемого устройства с экземпляром с перечислением PnP, если таковой существует.

Номер автобуса отличает автобус, в котором находится устройство, от других автобусов того же типа на компьютере. Схема нумерирования автобусов зависит от автобуса. Если драйвер не знает номер busNumber для устройства, драйвер предоставляет значение -1 для этого параметра.

[in] SlotNumber

Указывает номер логического слота устройства. Диспетчер PnP использует эти сведения для сопоставления сообщаемого устройства с экземпляром с перечислением PnP, если таковой существует.

Если драйвер не знает значение SlotNumber для устройства, драйвер предоставляет значение -1 для этого параметра.

[in, optional] ResourceList

Указатель на список ресурсов, используемый драйвером для обнаружения устройства. Ресурсы в этом списке находятся в необработанном, неперечисленном виде.

[in, optional] ResourceRequirements

При необходимости указывает на список требований к ресурсам для обнаруженного устройства. Значение NULL , если вызывающий объект не имеет этих сведений для устройства.

[in] ResourceAssigned

Указывает, были ли ресурсы устройства уже сообщены диспетчеру PnP. Если параметр ResourceAssigned имеет значение TRUE, о ресурсах уже сообщили, возможно, с помощью IoReportResourceForDetection, и диспетчер PnP не будет пытаться запросить их от имени устройства. Если задано значение TRUE, диспетчер PnP также не будет запрашивать ресурсы, если устройство перечисляется в корневом каталоге при последующих загрузках.

[in, out] DeviceObject

При необходимости указывает на PDO для обнаруженного устройства.

Значение NULL , если вызывающий объект не имеет PDO для устройства, как правило. Если DeviceObject имеет значение NULL, диспетчер PnP создает PDO для устройства и возвращает указатель на вызывающий объект.

Если вызывающий объект предоставляет PDO, диспетчер PnP не создает новое PDO. В данном вызове этой подпрограммы параметр DeviceObject является параметром IN или OUT, но не обоими.

Возвращаемое значение

IoReportDetectedDevice возвращает STATUS_SUCCESS при успешном выполнении или соответствующий код ошибки при сбое.

Драйверы для устаревших устройств используют IoReportDetectedDevice для передачи данных о своих устройствах в систему. Драйвер должен вызывать только IoReportDetectedDevice, чтобы сообщить о устаревшем устройстве, отличном от PnP. Устройства PnP должны быть представлены в ответ на запрос IRP_MN_QUERY_DEVICE_RELATIONS .

Драйверы должны вызывать IoReportDetectedDevice только при первой загрузке, так как диспетчер PnP кэширует сообщаемые сведения. Драйверы, использующие эту подпрограмму, должны хранить флаг в реестре, чтобы указать, что они уже выполнили обнаружение устройств.

Драйвер обычно вызывает эту подпрограмму из своей подпрограммы DriverEntry . Некоторые драйверы, такие как некоторые драйверы NDIS или EISA, могут вызывать эту процедуру из процедуры AddDevice .

После успешного завершения IoReportDetectedDevice вызывающий объект должен прикрепить FDO к PDO, возвращенной в DeviceObject. После того как вызывающий объект присоединяет FDO, вызывающий объект является драйвером функции для устройства, по крайней мере временно. Отсутствуют драйверы фильтров. Менеджер PnP владеет PDO.

Диспетчер PnP считает устройство запущенным и поэтому не вызывает процедуру AddDevice драйвера и не отправляет запрос IRP_MN_START_DEVICE . Однако драйвер должен быть готов к обработке всех остальных PnP IRP.

IoReportDetectedDevice помечает устройство как устройство с корневым перечислением, и эта идентификация сохраняется при загрузке системы. Во время последующих загрузок системы диспетчер PnP "обнаруживает" устройство в корневом списке и настраивает его как устройство PnP: диспетчер PnP запрашивает сведения об устройстве, определяет соответствующие драйверы и вызывает их подпрограммы AddDevice и отправляет все соответствующие PnP IRP.

Система создает две совместимые строки идентификатора для устройства в формате DETECTEDInterface\Driver и DETECTED\Driver. Интерфейс — это строковое имя INTERFACE_TYPE первой шины, указанной в параметре ResourceList . Если шина не указана, для интерфейса задано значение "Внутренний". Driver — это имя службы драйвера. Драйвер может предоставить дополнительные идентификаторы оборудования или совместимые идентификаторы, обрабатывая запрос IRP_MN_QUERY_ID .

Модуль записи драйверов должен предоставить INF-файл, соответствующий любому из указанных идентификаторов оборудования или совместимых идентификаторов. В INF-файле должен быть указан исходный драйвер, который вызвал IoReportDetectedDevice в качестве драйвера для загрузки этих идентификаторов. Система использует эти сведения для перестроения стека драйверов для устройства, например при перезапуске. Вызывающие устройства IoReportDetectedDevice должны выполняться в irQL = PASSIVE_LEVEL в контексте системного потока.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 2000.
Целевая платформа	Универсальное
Верхняя часть	ntddk.h (включая Ntddk.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
Правила соответствия DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

См. также раздел

IRP_MN_QUERY_DEVICE_RELATIONS

IoReportResourceForDetection