Функция IoReportResourceForDetection (ntddk.h)
Подпрограмма IoReportResourceForDetection запрашивает аппаратные ресурсы в реестре конфигурации для устаревшего устройства.
Синтаксис
NTSTATUS IoReportResourceForDetection(
[in] PDRIVER_OBJECT DriverObject,
[in, optional] PCM_RESOURCE_LIST DriverList,
[in, optional] ULONG DriverListSize,
[in, optional] PDEVICE_OBJECT DeviceObject,
[in, optional] PCM_RESOURCE_LIST DeviceList,
[in, optional] ULONG DeviceListSize,
[out] PBOOLEAN ConflictDetected
);
Параметры
[in] DriverObject
Указатель на объект драйвера, который входил в подпрограмму DriverEntry драйвера.
[in, optional] DriverList
При необходимости указывает на предоставленный вызывающим объектом буфер, содержащий список ресурсов драйвера, если драйвер запрашивает одни и те же ресурсы для всех своих устройств. Если вызывающий объект указывает DeviceList, этот параметр игнорируется.
[in, optional] DriverListSize
Задает размер в байтах необязательного списка драйверов. Если DriverList имеет значение NULL, этот параметр должен быть равен нулю.
[in, optional] DeviceObject
При необходимости указывает на объект устройства, представляющий устройство, для которого драйвер пытается запросить ресурсы.
[in, optional] DeviceList
При необходимости указывает на предоставленный вызывающим объектом буфер, содержащий список ресурсов устройства. Если драйвер запрашивает одни и те же ресурсы для всех своих устройств, вызывающий объект может вместо этого указать DriverList .
[in, optional] DeviceListSize
Задает размер в байтах необязательного элемента DeviceList. Если DeviceList имеет значение NULL, этот параметр должен быть равен нулю.
[out] ConflictDetected
Указатель на предоставленное вызывающим абонентом логическое значение, которое имеет значение TRUE при возврате, если ресурсы недоступны.
Возвращаемое значение
IoReportResourceForDetection возвращает STATUS_SUCCESS, если ресурсы запрашиваются. Возможные возвращаемые значения ошибок включают следующие.
| Код возврата | Описание |
|---|---|
| STATUS_CONFLICTING_ADDRESSES | Не удалось запросить ресурсы, так как они уже используются или необходимы для перечисляемого устройства PnP. |
| STATUS_UNSUCCESSFUL | Недопустимый список устройств или список драйверов. |
Комментарии
Эта подпрограмма предназначена для драйверов, которые обнаруживают более раннее оборудование, которое не может быть перечислено Plug and Play (PnP).
Если драйвер поддерживает только оборудование PnP, он не обнаруживает и поэтому не вызывает IoReportResourceForDetection. Система PnP перечисляет каждое устройство PnP, назначает ресурсы устройству и передает эти ресурсы драйверам устройства в запросе IRP_MN_START_DEVICE .
Однако если драйвер PnP поддерживает устаревшее оборудование, он должен вызвать IoReportResourceForDetection , чтобы запросить аппаратные ресурсы, прежде чем пытаться обнаружить устройство.
Вызывающие стороны этой подпрограммы указывают CM_RESOURCE_LIST в DeviceList или DriverList , выделенные из страничной памяти и состоящие из необработанных непереведенных ресурсов. Вызывающий объект отвечает за освобождение памяти.
Драйвер, который может управлять несколькими устаревшими карта одновременно, должен запрашивать ресурсы для каждого устройства в объекте устройства для соответствующего устройства (с помощью параметров DeviceObject, DeviceList и DeviceListSize). Такой драйвер не должен запрашивать эти ресурсы для своего объекта драйвера.
CM_RESOURCE_LIST содержит два массива переменной величины. Размер каждого массива по умолчанию — один. Если любой из массивов содержит несколько элементов, вызывающий объект должен динамически выделять память для хранения дополнительных элементов. Только один CM_PARTIAL_RESOURCE_DESCRIPTOR может быть частью каждого CM_FULL_RESOURCE_DESCRIPTOR в списке, за исключением последнего полного дескриптора ресурса в CM_RESOURCE_LIST, который может содержать дополнительные частичные дескрипторы ресурсов в своем массиве.
IoReportResourceForDetection с помощью диспетчера PnP определяет, конфликтуют ли запрашиваемые ресурсы с уже запрошенными ресурсами.
При обнаружении конфликта эта подпрограмма устанавливает для параметра BOOLEAN в ConflictDetectedзначение TRUE и возвращает STATUS_CONFLICTING_ADDRESSES.
Если конфликт не обнаружен, эта подпрограмма утверждает ресурсы, устанавливает для параметра BOOLEAN в ConflictDetectedзначение FALSE и возвращает STATUS_SUCCESS.
Если эта подпрограмма выполняется успешно и драйвер обнаруживает устаревшее устройство, драйвер сообщает об устройстве диспетчеру PnP, вызвав IoReportDetectedDevice. В этом вызове драйвер задает параметру ResourceAssigned значение TRUE , чтобы диспетчер PnP не пытался снова запросить ресурсы.
Если драйверу больше не требуются ресурсы, запрашиваемые вызовом этой подпрограммы, драйвер снова вызывает эту подпрограмму с помощью DriverList или DeviceList с числом , равным нулю.
Если драйвер запрашивает ресурсы на основе конкретного устройства для нескольких устройств, драйвер должен вызывать эту подпрограмму для каждого такого устройства.
Драйвер может вызывать эту подпрограмму несколько раз для данного устройства. В случае сбоя одного набора ресурсов драйвер может снова вызвать подпрограмму для того же устройства с другим набором ресурсов. Если набор ресурсов завершается успешно, драйвер может снова вызвать эту подпрограмму с новым списком; новый список заменяет предыдущий.
Вызывающие функции IoReportResourceForDetection должны выполняться в среде IRQL = PASSIVE_LEVEL в контексте системного потока.
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Универсальное |
| Верхняя часть | ntddk.h (включая Ntddk.h) |
| Библиотека | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (см. раздел "Примечания") |