Функция IoGetDeviceProperty (wdm.h)

Статья
08/08/2023

Подпрограмма IoGetDeviceProperty извлекает сведения об устройстве, такие как сведения о конфигурации и имя его PDO.

Синтаксис

NTSTATUS IoGetDeviceProperty(
  [in]            PDEVICE_OBJECT           DeviceObject,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

Параметры

[in] DeviceObject

Указатель на объект физического устройства (PDO) для запрашиваемого устройства.

[in] DeviceProperty

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

DevicePropertyAddress

Запрашивает адрес устройства в шине. PropertyBuffer указывает на ULONG.

Интерпретация этого адреса зависит от шины. Вызывающий объект этой подпрограммы должен снова вызвать подпрограмму, чтобы запросить DevicePropertyBusTypeGuid или, возможно, DevicePropertyLegacyBusType, чтобы он мог интерпретировать адрес. Значение адреса 0xFFFFFFFF указывает, что базовый водитель автобуса не указал адрес автобуса для устройства.

В следующем списке описаны сведения, которые некоторые водители автобуса хранят в PropertyBuffer для своих дочерних устройств.

Шина	Описание
1394	Не предоставляет адрес, так как адреса являются переменными. По умолчанию используется 0xFFFFFFFF.
EISA	Номер слота (0–F).
IDE	Для устройства интегрированной среды разработки адрес содержит целевой идентификатор и LUN. Для канала интегрированной среды разработки адрес равен нулю или одному (0 = основной канал и 1 = дополнительный канал).
ISApnp	Не предоставляет адрес. По умолчанию используется 0xFFFFFFFF.
Pc Card (PCMCIA)	Номер сокета (обычно 0x00 или 0x40).
PCI	Номер устройства в высоком слове и номер функции в нижнем слове.
SCSI	Идентификатор целевого объекта.
USB	номер порта.

DevicePropertyBootConfiguration

Запрашивает аппаратные ресурсы, назначенные устройству встроенным ПО, в необработанном виде. PropertyBuffer указывает на структуру CM_RESOURCE_LIST .

DevicePropertyBootConfigurationTranslated

Аппаратные ресурсы, назначенные устройству встроенным ПО в переведенном виде. PropertyBuffer указывает на структуру CM_RESOURCE_LIST .

DevicePropertyBusNumber

Запрашивает устаревший номер шины, к которому подключено устройство. PropertyBuffer указывает на ULONG.

DevicePropertyBusTypeGuid

Запрашивает GUID для шины, к которому подключено устройство. Идентификаторы GUID типа системной шины перечислены в файле заголовка Wdmguid.h. PropertyBuffer указывает на GUID, который представляет собой 16-байтовую структуру, содержащую GUID в двоичной форме.

DevicePropertyClassGuid

Запрашивает GUID для класса установки устройства. PropertyBuffer указывает на массив WCHAR, завершающийся значением NULL. Эта подпрограмма возвращает GUID в строковом формате следующим образом, где каждый "c" представляет шестнадцатеричный символ: {cccccccc-cccc-cccc-cccc-cccccc}

DevicePropertyClassName

Запрашивает имя класса установки устройства в текстовом формате. PropertyBuffer указывает на строку WCHAR с завершением NULL.

DevicePropertyCompatibleIDs

Запрашивает совместимые идентификаторы, сообщаемые устройством. PropertyBuffer указывает на значение REG_MULTI_SZ.

DevicePropertyDeviceDescription

Запрашивает строку, описывающую устройство, например "Microsoft PS/2 Port Mouse", обычно определяемую производителем. PropertyBuffer указывает на строку WCHAR с завершением NULL.

DevicePropertyDriverKeyName

Запрашивает имя раздела реестра для конкретного драйвера. PropertyBuffer указывает на строку WCHAR с завершением NULL.

DevicePropertyEnumeratorName

Запрашивает имя перечислителя для устройства, например "PCI" или "root". PropertyBuffer указывает на строку WCHAR с завершением NULL.

DevicePropertyFriendlyName

Запрашивает строку, которая может использоваться для различения двух похожих устройств, обычно определяемых установщиком класса. PropertyBuffer указывает на строку WCHAR с завершением NULL.

DevicePropertyHardwareID

Запрашивает идентификаторы оборудования , предоставленные устройством, которые идентифицируют устройство. PropertyBuffer указывает на значение REG_MULTI_SZ.

DevicePropertyInstallState

Запрашивает состояние установки устройства. Состояние установки возвращается в виде значения перечисления DEVICE_INSTALL_STATE .

DevicePropertyLegacyBusType

Запрашивает тип шины, например PCIBus или PCMCIABus. PropertyBuffer указывает на значение перечисления INTERFACE_TYPE .

DevicePropertyLocationInformation

Запрашивает сведения о расположении устройства в автобусе; интерпретация этой информации зависит от автобуса. PropertyBuffer указывает на строку WCHAR с завершением NULL.

DevicePropertyManufacturer

Запрашивает строку, определяющую производителя устройства. PropertyBuffer указывает на строку WCHAR с завершением NULL.

DevicePropertyPhysicalDeviceObjectName

Запрашивает имя PDO для этого устройства. PropertyBuffer указывает на строку WCHAR с завершением NULL.

DevicePropertyRemovalPolicy

Запрашивает текущую политику удаления устройства. Операционная система использует это значение в качестве указания для определения способа удаления устройства. Параметр PropertyBuffer указывает на значение перечисления DEVICE_REMOVAL_POLICY .

DevicePropertyUINumber

Запрашивает число, связанное с устройством, которое может отображаться в пользовательском интерфейсе. PropertyBuffer указывает на значение ULONG.

Обычно это номер слота, воспринимаемый пользователем, например номер, напечатанный рядом с слотом на доске, или другое число, которое упрощает поиск физического устройства для пользователя. Если устройство находится в шине без соглашения о номерах пользовательского интерфейса или драйверу не удается определить номер пользовательского интерфейса, это значение будет 0xFFFFFFFF.

[in] BufferLength

Задает размер объекта PropertyBuffer, предоставленного вызывающим элементом , в байтах.

[out, optional] PropertyBuffer

Указатель на буфер, предоставленный вызывающим объектом, для получения сведений о свойстве. Буфер может быть выделен из страничной памяти. Тип буфера определяется свойством DeviceProperty (см. выше).

[out] ResultLength

Указатель на ULONG для получения размера сведений о свойстве, возвращаемых в PropertyBuffer. Если IoGetDeviceProperty возвращает STATUS_BUFFER_TOO_SMALL, он устанавливает для этого параметра необходимую длину буфера.

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

IoGetDeviceProperty возвращает STATUS_SUCCESS, если вызов был выполнен успешно. Возможные возвращаемые значения ошибок включают следующее.

Код возврата	Описание
STATUS_BUFFER_TOO_SMALL	Буфер в PropertyBuffer был слишком мал. ResultLength указывает на необходимую длину буфера.
STATUS_INVALID_PARAMETER_2	Данное свойство DeviceProperty не является одним из свойств, обрабатываемых этой подпрограммой.
STATUS_INVALID_DEVICE_REQUEST	Возможно, указывает, что данный объект DeviceObject не был допустимым указателем PDO.

IoGetDeviceProperty извлекает сведения о настройке устройства из реестра. Используйте эту процедуру вместо прямого доступа к реестру, чтобы изолировать драйвер от различий на разных платформах и от возможных изменений в структуре реестра.

Для многих запросов DeviceProperty может потребоваться два или более вызовов IoGetDeviceProperty , чтобы определить требуемый BufferLength. При первом вызове должно использоваться лучшее значение. Если состояние возврата STATUS_BUFFER_TOO_SMALL, драйвер должен освободить текущий буфер, выделить буфер размера, возвращаемого в ResultLength, и снова вызвать IoGetDeviceProperty . Так как некоторые свойства настройки являются динамическими, размер данных может меняться между временем возврата требуемого размера и повторным вызовом этой подпрограммы. Поэтому драйверы должны вызывать IoGetDeviceProperty внутри цикла, который выполняется до тех пор, пока состояние возврата не STATUS_BUFFER_TOO_SMALL.

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

Требования

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