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类型枚举器。
[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。 由于某些设置属性是动态的,因此数据大小可以在返回所需大小的时间和驱动程序再次调用此例程之间发生更改。 因此,驱动程序应在运行到返回状态未STATUS_BUFFER_TOO_SMALL的循环中调用 IoGetDeviceProperty。
支持旧总线和 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) |