IoGetDeviceProperty 例程

IoGetDeviceProperty 例程

　　IoGetDeviceProperty例程检索有关设备的信息, 如配置信息和其 PDO 的名称。

语法

NTSTATUS IoGetDeviceProperty(
  _In_      PDEVICE_OBJECT           DeviceObject,
  _In_      DEVICE_REGISTRY_PROPERTY DeviceProperty,
  _In_      ULONG                    BufferLength,
  _Out_opt_ PVOID                    PropertyBuffer,
  _Out_     PULONG                   ResultLength
);

参数

• DeviceObject [in]
  　　指向要查询的设备的物理设备对象 (PDO) 的指针。
• DeviceProperty [in]
  　　指定所请求的设备属性。必须是下列 DEVICE_REGISTRY_PROPERTY 枚举值之一:
  
  • DevicePropertyAddress
    　　请求总线上设备的地址。PropertyBuffer指向 ULONG。
    　　此地址的解释是特定于总线的。此例程的调用方应再次调用该例程以请求DevicePropertyBusTypeGuid, 或者可能是DevicePropertyLegacyBusType, 以便它可以解释该地址。地址值0xFFFFFFFF 表示底层总线驱动程序没有为设备提供总线地址。
  • 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 的空终止数组。此例程以字符串格式返回 GUID, 其中每个 “c” 表示十六进制字符: {cccccccc-交-交-交-cccccccccccc}
  • DevicePropertyClassName
    　　以文本格式请求设备的安装程序类的名称。PropertyBuffer指向一个空终止的 WCHAR 字符串。
  • DevicePropertyCompatibleIDs
    　　请求设备报告的 兼容 id 。PropertyBuffer指向 REG_MULTI_SZ 值。
  • DevicePropertyDeviceDescription
    　　请求一个描述设备的字符串, 如 “Microsoft PS/2 端口鼠标”, 通常由制造商定义。PropertyBuffer指向一个以 NULL 结尾的 WCHAR 字符串。
  • DevicePropertyDriverKeyName
    　　请求特定于驱动程序的注册表项的名称。PropertyBuffer指向一个空终止的 WCHAR 字符串。
  • DevicePropertyEnumeratorName
    　　请求设备的枚举器的名称, 如 “PCI” 或 “根”。PropertyBuffer指向一个空终止的 WCHAR 字符串。
  • DevicePropertyFriendlyName
    　　请求可用于区分两个类似设备 (通常由类安装程序定义) 的字符串。PropertyBuffer指向一个空终止的 WCHAR 字符串。
  • DevicePropertyHardwareID
    　　请求由标识设备的设备提供的 硬件 id 。PropertyBuffer指向 REG_MULTI_SZ 值。
  • DevicePropertyInstallState
    　　(windows XP 和更高版本的 windows。请求设备的安装状态。安装状态作为 DEVICE_INSTALL_STATE 枚举值返回 (请参见 Ntddk 头文件)。
  • DevicePropertyLegacyBusType
    　　请求总线类型, 如 PCIBus 或 PCMCIABus。PropertyBuffer指向 INTERFACE_TYPE “枚举值。
  • DevicePropertyLocationInformation
    　　请求有关设备在总线上位置的信息;此信息的解释是特定于总线的。PropertyBuffer指向一个以 NULL 结尾的 WCHAR 字符串。
  • DevicePropertyManufacturer
    　　请求一个标识设备制造商的字符串。PropertyBuffer指向一个以 NULL 结尾的 WCHAR 字符串。
  • DevicePropertyPhysicalDeviceObjectName
    　　请求此设备的 PDO 的名称。PropertyBuffer指向一个空终止的 WCHAR 字符串。
  • DevicePropertyRemovalPolicy
    　　(windows XP 和更高版本的 windows。请求设备的当前删除策略。操作系统使用此值作为提示来确定设备的正常删除方式。PropertyBuffer参数指向 DEVICE_REMOVAL_POLICY “枚举值。
  • DevicePropertyUINumber
    　　请求与可在用户界面中显示的设备相关联的数字。PropertyBuffer指向 ULONG 值。
    此数字通常是用户感知的插槽号, 例如, 在主板上的插槽旁边打印的数字, 或使用户更容易定位物理设备的其他数字。如果设备在没有 ui 号约定的总线上, 或者该设备的总线驱动程序无法确定 ui 号, 则该值为0xFFFFFFFF。
• BufferLength [in]
  　　指定调用方提供的PropertyBuffer的大小 (以字节为单位).
• PropertyBuffer [out, 可选]
  　　指向调用方提供的缓冲区以接收属性信息的指针。可以从页内存中分配缓冲区。缓冲区的类型由DeviceProperty确定 (参见上图)。
• ResultLength [out]
  　　指向 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属性来区分总线。

要求

Target platform	Universal
Version	Available starting with Windows 2000.
Header	Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI compliance rules	PowerIrpDDis, HwStorPortProhibitedDDIs

另请参阅

ExAllocatePoolWithTag
CM_RESOURCE_LIST
DEVICE_REMOVAL_POLICY
GUID
IO_RESOURCE_REQUIREMENTS_LIST
INTERFACE_TYPE