ioGetDeviceProperty 函数 (wdm.h)

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的地址值指示基础总线驱动程序未为设备提供总线地址。

以下列表描述了某些总线驱动程序在其子设备 的属性Buffer 中存储的信息:

总线 说明
1394 不提供地址,因为地址是易失的。 默认为0xFFFFFFFF。
EISA 槽号 (0-F) 。
IDE 对于 IDE 设备,地址包含目标 ID 和 LUN。 对于 IDE 通道,地址为零或一 (0 = 主通道,1 = 辅助通道) 。
ISApnp 不提供地址。 默认为0xFFFFFFFF。
PC 卡 (PCMCIA) 套接字号 (通常0x00或0x40) 。
PCI 高单词中的设备编号和低单词中的函数编号。
SCSI 目标 ID。
USB 端口号。

DevicePropertyBootConfiguration

以原始形式请求固件分配给设备的硬件资源。 PropertyBuffer 指向 CM_RESOURCE_LIST 结构。

DevicePropertyBootConfigurationTranslated

由固件分配的硬件资源,采用已翻译形式分配给设备。 PropertyBuffer 指向 CM_RESOURCE_LIST 结构。

DevicePropertyBusNumber

请求设备连接到的总线的旧总线编号。 PropertyBuffer 指向 ULONG。

DevicePropertyBusTypeGuid

请求设备连接到的总线的 GUID。 系统定义的总线类型 GUID 列在 Wdmguid.h 头文件中。 PropertyBuffer 指向 GUID,它是一个包含二进制形式的 GUID 的 16 字节结构。

DevicePropertyClassGuid

请求设备的安装类的 GUID。 PropertyBuffer 指向 WCHAR 的 NULL 终止数组。 此例程返回字符串格式的 GUID,其中每个“c”表示十六进制字符:{cccccc-cccc-cccc-cccc-cccc-cc}

DevicePropertyClassName

以文本格式请求设备设置类的名称。 PropertyBuffer 指向以 NULL 结尾的 WCHAR 字符串。

DevicePropertyCompatibleIDs

请求设备报告的 兼容 IDPropertyBuffer 指向REG_MULTI_SZ值。

DevicePropertyDeviceDescription

请求描述设备(例如“Microsoft PS/2 端口鼠标”)的字符串,通常由制造商定义。 PropertyBuffer 指向以 NULL 结尾的 WCHAR 字符串。

DevicePropertyDriverKeyName

请求特定于驱动程序的注册表项的名称。 PropertyBuffer 指向以 NULL 结尾的 WCHAR 字符串。

DevicePropertyEnumeratorName

请求设备枚举器的名称,例如“PCI”或“root”。 PropertyBuffer 指向以 NULL 结尾的 WCHAR 字符串。

DevicePropertyFriendlyName

请求一个字符串,该字符串可用于区分两个类似的设备,通常由类安装程序定义。 PropertyBuffer 指向以 NULL 结尾的 WCHAR 字符串。

DevicePropertyHardwareID

请求标识设备提供 的硬件 ID。 PropertyBuffer 指向REG_MULTI_SZ值。

DevicePropertyInstallState

请求设备的安装状态。 安装状态作为 DEVICE_INSTALL_STATE 枚举值返回。

DevicePropertyLegacyBusType

请求总线类型,例如 PCIBus 或 PCMCIABus。 PropertyBuffer 指向 INTERFACE_TYPE 枚举值。

DevicePropertyLocationInformation

请求有关设备在总线上的位置的信息;此信息的解释特定于总线。 PropertyBuffer 指向以 NULL 结尾的 WCHAR 字符串。

DevicePropertyManufacturer

请求标识设备的制造商的字符串。 PropertyBuffer 指向以 NULL 结尾的 WCHAR 字符串。

DevicePropertyPhysicalDeviceObjectName

请求此设备的 PDO 名称。 PropertyBuffer 指向以 NULL 结尾的 WCHAR 字符串。

DevicePropertyRemovalPolicy

请求设备的当前删除策略。 操作系统使用此值作为提示来确定设备正常删除的方式。 PropertyBuffer 参数指向DEVICE_REMOVAL_POLICY枚举值。

DevicePropertyUINumber

请求与可在用户界面中显示的设备关联的数字。 PropertyBuffer 指向 ULONG 值。

此数字通常是用户感知的槽号,例如在板上的槽旁边打印的数字,或一些其他数字,使用户更容易定位物理设备。 如果设备位于没有 UI 号码约定的总线上,或者设备总线驱动程序无法确定 UI 编号,则此值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 总线上的设备的函数驱动程序可以使用 DevicePropertyBusNumberDevicePropertyBusTypeGuidDevicePropertyLegacyBusType 属性来区分总线。

要求

   
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 wdm.h(包括 Wdm.h、Ntddk.h、Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 符合性规则 HwStorPortProhibitedDDIs (storport) PowerIrpDDis (wdm)

另请参阅

CM_RESOURCE_LIST

DEVICE_REMOVAL_POLICY

ExAllocatePoolWithTag

GUID

INTERFACE_TYPE

IO_RESOURCE_REQUIREMENTS_LIST