简介本资源是一个基于Visual C开发的USB HID设备检测工具项目面向Windows平台C开发者及嵌入式/驱动方向学习者解决HID类外设如键盘、鼠标、游戏手柄等在PC端的自动识别与信息获取问题。项目完整封装了SetupAPI枚举、HIDClass驱动交互、DeviceIoControl控制调用等核心逻辑涵盖设备路径获取、厂商/产品名读取、HID报告解析等关键能力。压缩包共30个文件含15个头文件h提供USB/HID标准接口定义3个CPP源码实现主程序逻辑2个VCProj与SLN工程配置支持VS2008编译另有LIB库文件、资源脚本及说明文档结构清晰便于理解Windows USB编程底层机制。资源大小仅89KB轻量但功能完备已有143人学习下载适合中高级C开发者快速掌握HID设备枚举与通信的实战编码范式。1. 这不是“插上就能用”的玩具一个能真实枚举键盘鼠标游戏手柄的 Visual C HID 检测工程为什么你编译失败、设备列表为空、甚至根本看不到 USB 设备你写完SetupDiGetClassDevs调了CreateFileDeviceIoControl返回ERROR_INVALID_PARAMETER调试器里HidD_GetProductString始终返回 false——这不是玄学是 Windows HID 编程的真实门槛。这个名为Computer_HID_detect.zip的工程不是教学 Demo而是一个可直接编译、运行、在 Win7/Win10/Win11 x64 上稳定列出所有物理 HID 设备含带复合接口的 USB 键盘音频电池的完整 MFC 对话框程序。它不依赖第三方库不走 WMI 或 PowerShell 封装全程调用原生 SetupAPI HID Class API核心逻辑藏在Test_HIDDlg.cpp里hid.lib是微软官方静态链接库非 DLLusb100.h和hidsdi.h等头文件全部来自 Windows SDK 7.1。适合两类人一是正在做 USB 外设管理工具、工业 HMI 设备监控、或需要绕过驱动直接读取 HID 报告的嵌入式联调工程师二是被《Windows 核心编程》第 19 章 HID 示例卡住、发现书上代码跑不通、HidP_GetCaps总是失败的新手。它解决的不是“能不能连”而是“连上了怎么拿到制造商名、序列号、报告描述符长度、输入/输出/特征报告数量”这些生产级需求。别急着改#define _WIN32_WINNT 0x0601——先看清楚Test_HID.vcproj里实际用的是哪个平台工具集。2. 从 .vcproj 到SetupDiEnumDeviceInfo还原这个工程真实的编译链路与设备枚举逻辑2.1 工程结构解剖为什么Test_HID.vcproj.XFD-PC.Administrator.user不该删而Test_HID.suo必须清空这个工程是典型的 Visual Studio 2008VC9MFC 对话框项目.vcproj文件决定了编译行为。关键点有三平台工具集ToolFiles节点中ToolFile指向v90即 VS2008 默认工具集而非 v142 或 v143。若强行用 VS2019 打开并升级hid.lib链接会失败符号不匹配因为hid.lib是 32 位静态库且导出符号基于__cdecl调用约定。预处理器定义PreprocessorDefinitions包含WIN32;_WINDOWS;_DEBUG;_AFXDLL;UNICODE;_UNICODE其中_UNICODE是硬性要求——HidD_GetManufacturerString内部使用WideCharToMultiByte若未定义字符串全为乱码。附加依赖项AdditionalDependencies明确列出hid.lib;setupapi.lib;advapi32.lib缺一不可。setupapi.lib提供SetupDi*系列函数advapi32.lib支持RegQueryValueEx用于读取设备注册表键值。提示Test_HID.suo是用户解决方案选项文件存储断点、窗口布局等不影响编译但Test_HID.vcproj.XFD-PC.Administrator.user记录了本机调试器路径和符号服务器设置删除后可能导致“无法加载 PDB”警告——这不是错误但会掩盖真实问题。2.2 设备枚举主干CtestHIDDlg::OnBnClickedButtonEnum()的四层过滤逻辑核心函数位于Test_HIDDlg.cpp第 127 行起。它不是简单调用SetupDiGetClassDevs获取所有 USB 设备而是执行严格四步筛选// 步骤1获取 HID 类设备句柄非 USB 类 HDEVINFO hDevInfo SetupDiGetClassDevs(GUID_DEVCLASS_HIDCLASS, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE); if (hDevInfo INVALID_HANDLE_VALUE) { /* 错误处理 */ } // 步骤2遍历每个设备接口提取设备路径关键 SP_DEVICE_INTERFACE_DATA deviceInterfaceData; deviceInterfaceData.cbSize sizeof(SP_DEVICE_INTERFACE_DATA); for (DWORD i 0; SetupDiEnumDeviceInterfaces(hDevInfo, NULL, GUID_DEVCLASS_HIDCLASS, i, deviceInterfaceData); i) { // 步骤3获取设备接口细节含设备路径 SP_DEVICE_INTERFACE_DETAIL_DATA* pDetail NULL; DWORD requiredSize 0; SetupDiGetDeviceInterfaceDetail(hDevInfo, deviceInterfaceData, NULL, 0, requiredSize, NULL); pDetail (SP_DEVICE_INTERFACE_DETAIL_DATA*)malloc(requiredSize); pDetail-cbSize sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA); if (!SetupDiGetDeviceInterfaceDetail(hDevInfo, deviceInterfaceData, pDetail, requiredSize, NULL, NULL)) { /* 跳过 */ } // 步骤4用设备路径打开句柄验证是否为有效 HID 设备 HANDLE hDevice CreateFile(pDetail-DevicePath, GENERIC_READ | GENERIC_WRITE, FILE_SHARE_READ | FILE_SHARE_WRITE, NULL, OPEN_EXISTING, 0, NULL); if (hDevice ! INVALID_HANDLE_VALUE) { // 后续调用 HidD_GetAttributes 等函数 CloseHandle(hDevice); } free(pDetail); } SetupDiDestroyDeviceInfoList(hDevInfo);逻辑说明GUID_DEVCLASS_HIDCLASS而非GUID_DEVCLASS_USB是关键。USB 键盘/鼠标在系统中注册为 HID 类设备其驱动是hidclass.sys不是usbccgp.sys。用 USB 类 GUID 枚举会漏掉绝大多数 HID 设备。DIGCF_DEVICEINTERFACE标志启用设备接口枚举这是获取DevicePath的唯一可靠方式。DevicePath形如\\?\hid#vid_046dpid_c52bmi_01#71a2b3c4d00000#{4d1e55b2-f16f-11cf-88cb-001111000030}CreateFile必须用此路径而非\\\\.\\USB#...。CreateFile的OPEN_EXISTING模式必须配合GENERIC_READ | GENERIC_WRITE权限。HID 设备要求写权限才能读取制造商字符串即使只读操作否则HidD_GetManufacturerString返回 false。2.3 HID 属性读取HidD_GetAttributes与HidD_GetPreparsedData的协作边界获取设备基本信息VID/PID后下一步是解析 HID 报告能力。Test_HIDDlg.cpp中GetHidDeviceInfo()函数调用顺序如下// 1. 获取基础属性VID/PID/版本 HIDD_ATTRIBUTES attr; attr.Size sizeof(HIDD_ATTRIBUTES); if (!HidD_GetAttributes(hDevice, attr)) { /* 失败 */ } // attr.VendorID, attr.ProductID, attr.VersionNumber 可直接使用 // 2. 获取预解析数据Preparsed Data这是后续解析报告描述符的前提 PHIDP_PREPARSED_DATA pPreparsedData NULL; if (!HidD_GetPreparsedData(hDevice, pPreparsedData)) { /* 失败 */ } // 3. 解析报告描述符能力注意此处不读原始描述符只读能力 HIDP_CAPS caps; if (HidP_GetCaps(pPreparsedData, caps) ! HIDP_STATUS_SUCCESS) { /* 失败 */ } // caps.NumberInputValueCaps 得到输入报告值数量 // caps.NumberOutputValueCaps 得到输出报告值数量 // caps.NumberFeatureValueCaps 得到特征报告值数量 // 4. 释放预解析数据必须否则内存泄漏 HidD_FreePreparsedData(pPreparsedData);参数说明HidD_GetAttributes是轻量级调用仅读取设备描述符中的idVendor/idProduct字段毫秒级完成。HidD_GetPreparsedData是重量级操作Windows 内核将原始 HID 报告描述符可能长达数百字节解析为内部结构体耗时约 1–5ms且每个设备句柄只能调用一次。重复调用会导致ERROR_INVALID_HANDLE。HidP_GetCaps依赖pPreparsedData它不返回原始字节流而是结构化信息。若需原始描述符如调试固件必须用HidD_GetReportDescriptor单独调用。3.hid.lib静态链接陷阱与HidP_GetUsages的正确姿势为什么你的HidP_GetUsageValue总是返回 03.1hid.lib的 ABI 兼容性雷区VS2008 vs VS2019 的二进制断裂Computer_HID_detect.zip中的hid.lib是 Windows SDK 7.1 提供的 32 位静态库其导出函数签名与现代 SDK 不兼容。典型症状在 VS2019 中启用/MT静态 CRT编译链接成功但运行时HidD_GetPreparsedData返回 false改用/MD动态 CRT后HidP_GetCaps返回HIDP_STATUS_INVALID_PREPARSED_DATA。根本原因hid.lib内部使用__cdecl调用约定而 VS2015 默认__vectorcall优化某些函数。解决方案只有两个强制降级编译器在 VS2019 中新建项目 → 属性 → 通用属性 → 平台工具集 → 选择Visual Studio 2008 - Windows XP (v90)需提前安装 VS2008 工具集替换为动态链接删除hid.lib改用LoadLibrary(hid.dll)GetProcAddress动态加载函数指针声明必须严格匹配typedef BOOLEAN (__stdcall *PFN_HidD_GetPreparsedData)(HANDLE, PHIDP_PREPARSED_DATA); HMODULE hHid LoadLibrary(Lhid.dll); PFN_HidD_GetPreparsedData pfnGetPreparsed (PFN_HidD_GetPreparsedData)GetProcAddress(hHid, HidD_GetPreparsedData);注意hid.dll在System32目录下无需额外分发。3.2HidP_GetUsages的缓冲区大小计算一个被文档严重误导的坑多数教程说“HidP_GetUsages的UsageList参数传入足够大的数组即可”但实际必须精确计算。Test_HIDDlg.cpp中的正确做法// 先获取所需缓冲区大小单位USHORT ULONG usageLength 0; NTSTATUS status HidP_GetUsages(pPreparsedData, HidP_Input, 0x0001, NULL, usageLength, 0); if (status ! HIDP_STATUS_BUFFER_TOO_SMALL) { /* 错误 */ } // 分配精确大小的 USHORT 数组不是 BYTE USHORT* pUsages (USHORT*)malloc(usageLength * sizeof(USHORT)); status HidP_GetUsages(pPreparsedData, HidP_Input, 0x0001, pUsages, usageLength, 0); // pUsages[0] 到 pUsages[usageLength-1] 即为所有 Usage ID关键点usageLength返回的是元素个数不是字节数。HidP_GetUsages第二个参数是USHORT*每个 Usage 占 2 字节因此分配空间为usageLength * sizeof(USHORT)。若传入BYTE*或int*会导致栈溢出或读取越界。0x0001是 HID Usage PageGeneric DesktopHidP_Input指定输入报告。若设备有多个 Usage Page如 Consumer Control LED需分别调用。3.3 避坑HID 设备枚举与读取的五大血泪经验现象原因解决设备列表为空但设备管理器显示正常SetupDiGetClassDevs使用了GUID_DEVCLASS_USB而非GUID_DEVCLASS_HIDCLASS或未加DIGCF_DEVICEINTERFACE标志严格使用GUID_DEVCLASS_HIDCLASS并确保DIGCF_DEVICEINTERFACE在标志中HidD_GetManufacturerString返回 false但GetLastError()是 0CreateFile未使用GENERIC_WRITE权限或设备路径字符串未以L\\?\开头Unicode 下必须CreateFile参数中dwDesiredAccess必须含GENERIC_WRITEDevicePath是宽字符直接传入即可HidP_GetCaps返回HIDP_STATUS_INVALID_PREPARSED_DATAHidD_GetPreparsedData调用后未检查返回值或对同一句柄重复调用每次HidD_GetPreparsedData后必须验证返回值pPreparsedData用完立即HidD_FreePreparsedDataHidP_GetUsages读出的 Usage ID 全为 0UsageList缓冲区大小不足或UsagePage参数错误如把0x0001写成1用HidP_GetUsages第一次调用获取usageLength再分配UsagePage必须是USHORT类型的十六进制值程序在 Win10 1903 上崩溃错误代码0xC0000005hid.lib与新 CRT 冲突或HidP_GetValueCaps传入了未初始化的PHIDP_VALUE_CAPS结构体改用动态加载hid.dllPHIDP_VALUE_CAPS数组必须ZeroMemory初始化不能只声明4.Test_HID.rc与资源注入如何安全扩展设备信息显示避免 MFC 对话框控件越界4.1 对话框资源重用IDD_TEST_HID_DIALOG的控件 ID 与CtestHIDDlg成员变量映射Test_HID.rc定义了主对话框IDD_TEST_HID_DIALOG其控件 ID 与Test_HIDDlg.h中的成员变量严格对应RC 中控件 IDHeader 中变量名类型用途IDC_LIST_DEVICEm_listDeviceCListCtrl显示 VID/PID/制造商/产品名IDC_EDIT_REPORT_DESCm_editReportDescCEdit显示原始 HID 报告描述符十六进制IDC_BUTTON_ENUMm_btnEnumCButton设备枚举触发按钮IDC_STATIC_VIDm_staticVidCStatic动态更新 VID 文本关键约束CListCtrl必须在DoDataExchange中通过DDX_Control绑定否则InsertItem无效CEdit控件属性需勾选MultilineRead-onlyVertical scroll否则长描述符显示不全所有CStatic文本控件的IDC_STATIC_*ID 在.rc中必须存在否则SetWindowText无效果。4.2 安全扩展添加“序列号读取”功能的三步改造法原工程未读取设备序列号但HidD_GetSerialNumberString可实现。安全注入步骤修改.rc文件在对话框资源中新增IDC_STATIC_SERIAL静态文本控件位置在IDC_STATIC_VID下方更新Test_HIDDlg.h在CtestHIDDlg类中添加CStatic m_staticSerial;并在DoDataExchange中加入DDX_Control(pDX, IDC_STATIC_SERIAL, m_staticSerial);在GetHidDeviceInfo()函数末尾插入WCHAR szSerial[128] {0}; if (HidD_GetSerialNumberString(hDevice, szSerial, sizeof(szSerial))) { m_staticSerial.SetWindowText(szSerial); } else { m_staticSerial.SetWindowText(LUnknown); }注意HidD_GetSerialNumberString与HidD_GetManufacturerString调用方式完全一致但部分廉价 HID 设备如某些国产游戏手柄固件未实现该请求返回 false 属正常不可抛异常。4.3ReadMe.txt的隐藏线索usbhead.h与usbdi.h的真实用途ReadMe.txt仅写“包含 USB 相关头文件”但实际usbhead.h和usbdi.h在本工程中未被任何.cpp文件包含。它们是历史残留usbhead.h定义USB_DEVICE_DESCRIPTOR等结构用于直接解析 USB 描述符需WinUSB驱动usbdi.h是内核模式头文件用户态程序不可用。结论这两个文件可安全删除不影响 HID 枚举功能。保留它们只会增加新手困惑——以为必须用WinUSB才能读 HID。5. 实时设备插拔监控用RegisterDeviceNotification替代轮询让程序真正“活”起来5.1 从轮询到事件驱动为什么OnTimer()检查设备列表是低效且不可靠的原工程OnTimer()函数每 2 秒调用一次EnumHidDevices()这导致三个问题CPU 占用率恒定 1–2%SetupDi*系列函数开销大设备插拔响应延迟最高达 2 秒频繁创建/销毁HDEVINFO句柄易触发系统资源泄漏Windows 限制每个进程HDEVINFO句柄数。正确方案使用RegisterDeviceNotification接收WM_DEVICECHANGE消息仅在设备实际变化时响应。5.2 注册设备通知的完整实现CtestHIDDlg::OnInitDialog()中的七行关键代码在OnInitDialog()末尾添加// 获取对话框窗口句柄 HWND hWnd GetSafeHwnd(); // 创建设备通知窗口必须是顶级窗口 DEV_BROADCAST_DEVICEINTERFACE dbi; ZeroMemory(dbi, sizeof(dbi)); dbi.dbcc_size sizeof(dbi); dbi.dbcc_devicetype DBT_DEVTYP_DEVICEINTERFACE; dbi.dbcc_classguid GUID_DEVCLASS_HIDCLASS; // 注册通知 HDEVNOTIFY hDevNotify RegisterDeviceNotification(hWnd, dbi, DEVICE_NOTIFY_WINDOW_HANDLE); if (hDevNotify NULL) { AfxMessageBox(_T(Failed to register device notification)); } // 将 hDevNotify 存为类成员变量如 m_hDevNotify便于 OnDestroy 时注销 m_hDevNotify hDevNotify;5.3 消息处理CtestHIDDlg::OnDeviceChange()的精准过滤逻辑在Test_HIDDlg.cpp中添加消息映射// 在 MESSAGE_MAP 中添加 ON_MESSAGE(WM_DEVICECHANGE, CtestHIDDlg::OnDeviceChange) // 实现函数 LRESULT CtestHIDDlg::OnDeviceChange(WPARAM wParam, LPARAM lParam) { switch (wParam) { case DBT_DEVICEARRIVAL: { PDEV_BROADCAST_DEVICEINTERFACE pDevInf (PDEV_BROADCAST_DEVICEINTERFACE)lParam; if (pDevInf pDevInf-dbcc_devicetype DBT_DEVTYP_DEVICEINTERFACE IsEqualGUID(pDevInf-dbcc_classguid, GUID_DEVCLASS_HIDCLASS)) { // 仅当到达的是 HID 设备时才重新枚举 EnumHidDevices(); } break; } case DBT_DEVICEREMOVECOMPLETE: { PDEV_BROADCAST_DEVICEINTERFACE pDevInf (PDEV_BROADCAST_DEVICEINTERFACE)lParam; if (pDevInf pDevInf-dbcc_devicetype DBT_DEVTYP_DEVICEINTERFACE IsEqualGUID(pDevInf-dbcc_classguid, GUID_DEVCLASS_HIDCLASS)) { // 设备移除清空列表或标记为离线 m_listDevice.DeleteAllItems(); } break; } } return 0; }关键点DBT_DEVICEARRIVAL和DBT_DEVICEREMOVECOMPLETE是设备物理插拔事件DBT_DEVNODES_CHANGED是系统内部状态变更不可靠IsEqualGUID比较dbcc_classguid确保只响应 HID 类设备避免 USB 存储、网卡等干扰EnumHidDevices()在插拔时调用比轮询节省 99% CPU。6. 验证 HID 报告描述符用HidP_GetReportDescriptorhidrd工具反向校验你的解析逻辑6.1HidP_GetReportDescriptor的原始字节提取绕过HidP_GetCaps的黑匣子Test_HIDDlg.cpp中未实现原始描述符读取但它是验证设备合规性的黄金标准。在GetHidDeviceInfo()中追加// 获取原始 HID 报告描述符长度 ULONG descLength 0; if (!HidD_GetReportDescriptor(hDevice, NULL, descLength)) { /* 失败 */ } // 分配缓冲区并读取 PUCHAR pDesc (PUCHAR)malloc(descLength); if (HidD_GetReportDescriptor(hDevice, pDesc, descLength)) { // 将 pDesc 转为十六进制字符串显示在 m_editReportDesc 中 CString strDesc; for (ULONG i 0; i descLength; i) { strDesc.AppendFormat(L%02X , pDesc[i]); if ((i 1) % 16 0) strDesc L\r\n; } m_editReportDesc.SetWindowText(strDesc); } free(pDesc);注意HidD_GetReportDescriptor返回的是原始二进制非 ASCII。pDesc中每个字节代表 HID 描述符的一个 Token如0x05, 0x01是 Usage Page: Generic Desktop。6.2 用hidrd工具解析确认你的HidP_GetUsages结果是否可信hidrd是开源命令行工具https://github.com/libusb/hidrd可将二进制描述符转为人类可读的.rd文件。验证步骤将m_editReportDesc中的十六进制字符串复制保存为raw.hex用 Python 脚本转换为二进制with open(raw.hex, r) as f: hex_str f.read().replace( , ).replace(\n, ) with open(desc.bin, wb) as f: f.write(bytes.fromhex(hex_str))运行hidrd -r desc.bin desc.rd查看输出是否包含Usage Page (Generic Desktop)、Usage (Keyboard)等字段对比HidP_GetUsages返回的 Usage ID如0x0006是 Keyboard与desc.rd中的Usage (0x0006)是否一致。常见不一致场景desc.rd显示Usage (0x0006)但HidP_GetUsages返回0x06→ 原因HidP_GetUsages返回的是 Usage ID低字节desc.rd显示完整 16 位值需用LOWORD(usage)提取desc.rd有Collection (Application)但HidP_GetUsages无结果 → 原因HidP_GetUsages默认只读顶层 Collection需用HidP_GetUsageValue读嵌套值。6.3 我的后悔药从那以后我每次解析 HID 设备都强制走一遍hidrd校验流程三年前调试一款医疗 HID 设备HidP_GetCaps显示有 8 个输入报告但实际固件只响应第一个。用hidrd解析发现描述符中Report Count被错误设为 8而Report Size为 0导致 Windows 内核忽略后续报告。当时花两天排查HidP_GetData缓冲区大小却没想过描述符本身有问题。现在我的工作流是用本工程Computer_HID_detect读出原始描述符hidrd转.rd查看结构对照 USB HID 规范Hut1_12.pdf检查Logical Minimum/Maximum、Report Size/Count是否合理最后才写业务逻辑。这个习惯让我避开过 7 次固件级缺陷也让我明白HID 编程的难点不在 API 调用而在读懂设备自己写的“说明书”。希望帮到你。本文还有配套的精品资源点击获取
