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
指向一个正在查询的属性的指针，可以为NULL
PropertyBuffer
指向缓冲区属性内容的指针
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。