windows SetupAPI 介绍和使用

在NT的基础上，MS在NT4.0后的操作系统里都提供了很多以SetupDiXXXXX开头的函数，就是大家经常所说的 SetupAPI.

需要包含头文件setupapi.h。setupapi.lib。

1,首先我们要访问系统的硬件库，用API SetupDiGetClassDevs，在DDK的文档中，函数的原型如下：

HDEVINFOSetupDiGetClassDevs(const GUID* ClassGuid,PCTSTR Enumerator,HWND hwndParent,DWORD Flags);

输入参数：

PGUIDClassGuid

在创建设备列表的时候提供一个指向GUID的指针。如果设定了标志DIGCF_ALLCLASSES，则这个参数可以忽略，且列表结果中包括所有已经安装的设备类别。

PCTSTREnumerator

提供包含设备实例的枚举注册表分支下的键名，可以通过它获取设备信息。如果这个参数没有指定，则要从整个枚举树中获取所有设备实例的设备信息。

HWNDhwndParent

提供顶级窗口的句柄，所有用户接口可以使用它来与成员联系。

DWORDFlags

提供在设备信息结构中使用的控制选项。可以是以下数值：

DIGCF_PRESENT - 只返回当前存在的设备。

DIGCF_ALLCLASSES - 返回所有已安装的设备。如果这个标志设置了，ClassGuid参数将被忽略。

DIGCF_PROFILE - 只返回当前硬件配置文件中的设备。

DIGCF_DEVICEINTERFACE - 返回所有支持的设备。

DIGCF_DEFAULT - 只返回与系统默认设备相关的设备。

返回值 HDEVINFO

如果函数运行成功，返回设备信息结构的句柄，该结构包含与指定参数匹配的所有已安装设备。如果失败，则返回INVALID_HANDLE_VALUE。调用GetLastError可以获得更多错误信息。

HDEVINFO 定义 typedef PVOID HDEVINFO;

2,然后利用HDEVINFO hDev 遍历所有的硬件，API原型如下：

WINSETUPAPI BOOL WINAPI SetupDiEnumDeviceInfo( INHDEVINFO DeviceInfoSet,IN DWORD MemberIndex, OUT PSP_DEVINFO_DATA DeviceInfoData );

SetupDiEnumDeviceInfo 枚举指定设备信息集合的成员，并将数据放在PSP_DEVINFO_DATA中

参数说明：

DeviceInfoSet

提供一个设备信息集合的句柄

MemberIndex

指定一个要取得的设备信息成员序号，从0开始

DeviceInfoData

指向SP_DEVINFO_DATA结构的指针，关于指定成员的返回信息就放在该结构中

Return ValueThe

成功返回True,否则返回False

3、用SetupDiGetDeviceRegistryProperty
获得硬件属性信息。
原型：WINSETUPAPI BOOL WINAPI

SetupDiGetDeviceRegistryProperty( IN HDEVINFO DeviceInfoSet, IN PSP_DEVINFO_DATA DeviceInfoData,
IN DWORD Property,

OUT PDWORD PropertyRegDataType,OPTIONAL
OUT PBYTE PropertyBuffer, IN DWORD PropertyBufferSize,

OUT PDWORD RequiredSize OPTIONAL);

参数说明：

DeviceInfoSet

设备信息句柄

DeviceInfoData

SP_DEVINFO_DATA结构体，包含DeviceInfoSet 中的设备信息

Property

取以下的值：

SPDRP_ADDRESS 查询设备的地址

SPDRP_BUSNUMBER 查询设备的bus号

SPDRP_BUSTYPEGUID 查询设备的GUID号

等等，定义在SetupApi.h中，有很多类似

#define SPDRP_DEVICEDESC (0x00000000) // DeviceDesc (R/W)

PropertyRegDataType指向一个正在查询的属性的指针，可以为NULLPropertyBuffer指向缓冲区属性内容的指针PropertyBufferSize以字节为单位，PropertyBuffer 缓冲区的大小。

RequiredSize指向所需大小的变量的指针。此参数是可选的并且可以为 NULL。

Return Value

成功返回true，否则返回false，错误类型可以用GetLastError查看

4、禁止或启用特定的设备了。相关API

SetupDiSetClassInstallParams

原型：

WINSETUPAPI BOOL WINAPI SetupDiSetClassInstallParams(

IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA DeviceInfoData, OPTIONAL

IN PSP_CLASSINSTALL_HEADER ClassInstallParams, OPTIONAL
IN DWORD ClassInstallParamsSize);

参数说明：

DeviceInfoSet

指向一个需要改变属性的device information

DeviceInfoData

指向SP_DEVINFO_DATA结构的指针

ClassInstallParams

指向SP_CLASSINSTALL_HEADER

结构的指针

ClassInstallParamsSize

ClassInstallParams
缓冲区的大小。如果未提供缓冲区 ，ClassInstallParamsSize 必须为 0。

返回值
成功返回true，否则返回false，错误类型可以用GetLastError查看

原型：

SetupDiCallClassInstaller

BOOL SetupDiCallClassInstaller(
_In_      DI_FUNCTION InstallFunction,
_In_      HDEVINFO DeviceInfoSet,
_In_opt_  PSP_DEVINFO_DATA DeviceInfoData
);

参数：

InstallFunction

设备安装请求 类型，在 Setupapi.h 中定义，例如#define DIF_PROPERTYCHANGE 0x00000012

DeviceInfoSet

指向一个需要改变属性的device information

DeviceInfoData

指向SP_DEVINFO_DATA结构的指针

返回值

成功返回true，否则返回false，错误类型可以用GetLastError查看

解释：

device instance ID：设备实例
ID 是系统提供的设备标识字符串，用于唯一标识系统中的设备。插即用 (PnP) 管理器将一个设备实例 ID 分配给系统的设备树中的每个设备节点 （devnode）。

格式为：<device-ID>\<instance-specific-ID>
例如：PCI\VEN_1000 & DEV_0001 & SUBSYS_00000000 & REV_02\1 08 &
注册表位置：
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Enum\PCI\VEN_8086&DEV_24C2&SUBSYS_3080103C&REV_03\3&61aaa01&0&E8

3&61aaa01&0&E8解释：

第一个3表示这个device在整个device
tree里面的level.他在第三级

root是0,root下面是acpi再下面是pci root bridge.这个设备就直接在root bridge下面

第二个是个hash值.他是这个设备的parent 设备的instance path大写以后计算出来的hash值

instance path是从current control set下面的enum算起(不包含enum)

第三个是hash instance.你很少有看到这个值不为0的

他表示为同一个parent计算上面这个hash的次数 - 1.通常都只是计算一次.计算以后就会保存下面.下一次就直接读取了而不会再重新计算

最后一个就是由bus驱动为他们的pdo返回的instance id了

可以用SetupDiGetDeviceInstanceId函数获取。

还有一个有用的函数SetupDiClassNameFromGuid，可以获取className。