简介这是一份面向VC开发者的Windows HID设备通信示例程序专为需要与键盘、鼠标、游戏控制器等外设进行低延迟数据交换的软硬件工程师设计完整演示设备枚举、句柄打开、报告读写、描述符解析及热插拔事件通知等关键环节。资源包共74个文件包含可直接阅读的C源码h/cpp、Visual Studio解决方案与工程文件sln/vcxproj、编译中间文件tlog/obj、可执行文件exe以及HID通讯说明文本压缩包整体约25.27MB并附有多时间节点的工程备份与打包脚本便于版本对比与二次开发。已有619人学习使用。示例代码将HID操作封装为类提供Open、WriteReport、ReadReport、Close等简洁接口读者可快速搭建调试环境深入理解HidD_GetPreparsedData、HidP_GetCaps、DeviceIoControl等API的实际调用方式是入门Windows下HID编程的实用参考。1. 从一包“识别不了”的HID数据讲起接过一个读卡器的外包调试硬件工程师丢过来一个自研USB设备说“插上就能出数据”。结果设备管理器里确实枚举成了HID设备但自己写的VC程序用CreateFile打开设备路径后ReadFile要么卡死、要么读到一包长度完全不对的废数据。折腾了一下午才意识到问题不在驱动而在HID的“报告”机制键盘鼠标这类标准设备由系统驱动处理但自定义HID设备需要应用层自己解析报告描述符、按报告ID对齐字段、控制读写超时。这个示例程序包里除了HID通讯说明.txt和HidPack-2016-12-13源码最有价值的其实是那套完整的枚举—打开—读写—关闭流程。如果你也在Windows下用VC做非标HID外设采集卡、工业按钮、医用脚踏、自研传感器这篇文章把整条链路拆开讲直接对着改就能跑。2. HID报告结构与描述符解析2.1 为什么必须先读报告描述符再谈通讯HID设备不是串口没有“流”的概念。主机和设备之间交换的是报告分为输入报告设备发给主机、输出报告主机发给设备和特征报告双向控制。每个报告由报告ID和按位排列的数据字段组成。字段的物理含义是8位无符号整数还是16位有符号数、值的范围是多少全部编码在报告描述符里。不同厂商的HID设备哪怕VID、PID只差一个数字报告长度也可能从2字节跳到64字节。示例程序包里专门放置了HID通讯说明.txt和.bak备份文件说明原作者在调试时反复修改过设备端的报告格式。实践中的标准流程是先用HidD_GetPreparsedData取得解析后的报告数据Preparsed Data再调用HidP_GetCaps获取设备能力输入/输出/特征报告的长度和数量最后才能确定读写缓冲区大小。跳过这一步直接ReadFile是初学者最常见的错误缓冲区小了会截断大了又无法判断有效字节还会引入等待超时。2.1.1 用HidP_GetCaps拿到报告长度上限打开设备句柄之后第一步是获取Preparsed Data代码模式如下HIDP_CAPS caps {0}; PHIDP_PREPARSED_DATA preparsedData NULL; if (!HidD_GetPreparsedData(hDev, preparsedData)) { // 获取失败多半是设备句柄已经被占用或驱动异常 return -1; } if (HidP_GetCaps(preparsedData, caps) ! HIDP_STATUS_SUCCESS) { HidD_FreePreparsedData(preparsedData); return -1; } // 接下来就可以根据caps决定读写缓冲区 int inputReportLen caps.InputReportByteLength; int outputReportLen caps.OutputReportByteLength; BYTE* inBuffer new BYTE[inputReportLen 1]; // 多出的1字节用于承载报告ID BYTE* outBuffer new BYTE[outputReportLen 1];这段代码先通过HidD_GetPreparsedData取得设备固件中报告描述符的解析结果然后由HidP_GetCaps填充一个HIDP_CAPS结构体。结构体里的InputReportByteLength和OutputReportByteLength就是该设备输入、输出报告的实际字节数。注意inBuffer分配时预留了1字节如果设备使用报告ID缓冲区首字节必须是报告ID无ID设备填0数据部分从第二个字节开始。很多自定义HID设备固件没有启用报告ID但为了兼容有ID的设备统一多分配一字节是最保险的写法。2.2 报告字段的对齐与取值边界拿到报告长度只是第一步更关键的是弄清楚每个字节里面是什么。HID描述符里定义了每个字段的Usage用途、Report Count字段数量、Report Size每个字段的位宽和Logical Min/Max逻辑上下限。例如一个采集温度的设备描述符可能定义第0字节是状态标志第1-2字节是16位小端温度值第3字节是保留位。如果用通用工具读取看到的是一串十六进制数字但只有对照描述符才能知道哪几位代表温度。示例程序里的HID通讯说明.txt大概率描述了这类映射关系。我在实际项目中习惯先导出一份描述符文本再写一个偏移表注释在代码头部偏移位宽含义设备示例08 bit报告ID无ID时为00x0018 bit状态标志bit0连接bit1故障0x012-316 bit主数据小端序0x34 0x1248 bit校验和0x8A字段对齐的核心原则是按位偏移累加不是按字节对齐。比如一个字段占3位下一个字段从第4位开始跨字节时低位在前。处理这种描述符时我通常写一个移位函数读取UINT16 GetFieldValue(BYTE* report, int bitOffset, int bitLength) { UINT16 value 0; for (int i 0; i bitLength; i) { int byteIndex (bitOffset i) / 8; int bitIndex (bitOffset i) % 8; int bit (report[byteIndex] bitIndex) 0x01; value | (bit i); } return value; }这个函数按位遍历把不连续的位字段拉通成一个整数值。参数里bitOffset是字段起始位bitLength是字段位宽小技巧是逐位读取并拼接到结果里避免移位越界。虽然逐个位处理效率不高但对于HID这类控制类设备几十字节的报告完全够用。遇到负数取值时还要根据Logical Min判断是否需要做符号扩展这部分逻辑放在解析函数里会更清晰。3. 枚举设备与打开句柄3.1 用SetupDi系列API枚举HID接口HID设备在Windows里同时存在两种设备节点一个在HIDClass下一个在USB\VID_xxxxPID_xxxx下。应用层通讯要操作的是HID接口设备接口枚举时使用HDEVINFO集合和SP_DEVICE_INTERFACE_DATA结构体。示例程序的核心枚举逻辑对应的是这个标准流程#include setupapi.h #include hidsdi.h #include dbt.h // 链接时注意工程属性里需要链接 setupapi.lib 和 hid.lib GUID hidGuid; HidD_GetHidGuid(hidGuid); // 获取系统HID设备接口GUID HDEVINFO devInfo SetupDiGetClassDevs(hidGuid, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE); if (devInfo INVALID_HANDLE_VALUE) return; SP_DEVICE_INTERFACE_DATA devInterfaceData {0}; devInterfaceData.cbSize sizeof(SP_DEVICE_INTERFACE_DATA); for (int index 0; SetupDiEnumDeviceInterfaces(devInfo, NULL, hidGuid, index, devInterfaceData); index) { // 第一次调用获取所需缓冲区长度 DWORD requiredSize 0; SetupDiGetDeviceInterfaceDetail(devInfo, devInterfaceData, NULL, 0, requiredSize, NULL); // 缓冲区里包含路径字符串需要一个SP_DEVICE_INTERFACE_DETAIL_DATA头 PSP_DEVICE_INTERFACE_DETAIL_DATA detailData (PSP_DEVICE_INTERFACE_DETAIL_DATA)new BYTE[requiredSize]; detailData-cbSize sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA); if (SetupDiGetDeviceInterfaceDetail(devInfo, devInterfaceData, detailData, requiredSize, NULL, NULL)) { // detailData-DevicePath 就是CreateFile需要的路径 HANDLE hDev CreateFile(detailData-DevicePath, GENERIC_READ | GENERIC_WRITE, FILE_SHARE_READ | FILE_SHARE_WRITE, NULL, OPEN_EXISTING, 0, NULL); // 拿到hDev之后做HidD_GetPreparsedData等进一步操作 } delete[] detailData; } SetupDiDestroyDeviceInfoList(devInfo);SetupDiGetClassDevs返回当前系统的HID设备集合DIGCF_DEVICEINTERFACE标志表示筛选设备接口而不是设备本身。SetupDiEnumDeviceInterfaces配合循环下标遍历所有HID接口每次枚举一个。SetupDiGetDeviceInterfaceDetail第一次调用传入空缓冲区目的是取回requiredSize第二次才真正拿到包含DevicePath的结构体。这里有一个初学者常掉的坑detailData-cbSize在XP及以前版本必须初始化为sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA)但在Win7之后部分系统要求扩展长度所以统一用上面的动态分配写法最稳妥。CreateFile打开的是设备路径而不是物理设备名因此权限参数上使用GENERIC_READ | GENERIC_WRITE应对双向通讯。FILE_SHARE_READ | FILE_SHARE_WRITE必须写全否则设备被本进程打开后其它监控工具或第二个调试器就无法再打开它导致热插拔测试时句柄泄漏。3.2 过滤多个同类HID定向打开设备当一个系统里同时插了普通鼠标、键盘和你的自定义设备时枚举循环会全捞出来。如果不加过滤程序会挨个打开、逐个尝试读写表现就是“能找到设备但数据对不上”。实际工程里我习惯在枚举循环里增加VID/PID匹配用HidD_GetAttributes读取设备属性HIDD_ATTRIBUTES attrib {0}; attrib.Size sizeof(HIDD_ATTRIBUTES); if (HidD_GetAttributes(hDev, attrib)) { // VID为0x1234、PID为0x5678时才是目标设备 if (attrib.VendorID 0x1234 attrib.ProductID 0x5678) { // 命中了保留句柄并退出循环 } else { CloseHandle(hDev); hDev INVALID_HANDLE_VALUE; } }HIDD_ATTRIBUTES只有三个有效成员VendorID、ProductID和VersionNumber打开设备后立即调用即可。用这个办法过滤后即便系统里插着键盘鼠标也不会串台。注意VID/PID一定要查设备固件里USB描述符的设定值如果设备没有上报VID/PID这里的值会是0就会误判。另一个思路是比对厂商字符串或产品字符串通过HidD_GetProductString等接口读取宽字符名称再匹配适合固件没烧录VID的场景。3.3 读写前的句柄有效性检查CreateFile返回句柄后不要急着立刻做ReadFile。有些设备固件上电后需要几百毫秒初始化刚插上立即打开容易返回成功但后续IO失败。更稳妥的是先做一次HidD_GetPreparsedData试探设备是否就绪失败则释放句柄并延时重试重试次数建议2-3次。这个技巧在设备频繁热插拔的调试场景里特别关键能明显减少误报“设备打开失败”。另外如果枚举时组合使用了SetupDiDestroyDeviceInfoList记得在所有设备路径都已拷贝到局部变量后再销毁因为detailData里的字符串指针随缓冲区释放而失效。4. 三种报告读写方式与超时控制4.1 中断传输下的ReadFile直接读取HID设备默认通过中断端点传输输入报告。使用同步ReadFile时线程会阻塞直到有数据到达或设备出错。示例程序里最简单的主循环读法如下BYTE inReport[64] {0}; DWORD bytesRead 0; BOOL result ReadFile(hDev, inReport, inputReportLen, bytesRead, NULL); if (result) { // 解析inReport注意首字节可能是报告ID // 从inReport[1]开始才是数据字段如果支持报告ID }ReadFile的第三个参数是期望读取字节数这里传inputReportLen指的是设备报告描述符里定义的长度不是缓冲区总大小。设备实际返回的字节数写入bytesRead。这个模式的坑在于没有超时机制HID的输入报告只有在设备主动上报时才会返回如果设备停机或线缆松动线程会一直阻塞。示例程序的HidPackTest测试工程里作者在高版本源码中已经改用OVERLAPPED异步模式说明踩过这个坑。4.2 基于DeviceIoControl的主动查询与下发除了被动接收控制类HID设备经常需要主动查询当前状态或者下发配置参数。此时使用DeviceIoControl配合IOCTL_HID_GET_INPUT_REPORT和IOCTL_HID_SET_OUTPUT_REPORT是另一个常用通道。与ReadFile不同IOCTL_HID_GET_INPUT_REPORT是主动请求设备生成一份最新的输入报告不依赖中断上报BYTE inBuffer[65] {0}; DWORD bytesReturned 0; // 主动读取输入报告缓冲区首字节填0表示不按报告ID过滤 BOOL ok DeviceIoControl(hDev, IOCTL_HID_GET_INPUT_REPORT, NULL, 0, inBuffer, inputReportLen 1, bytesReturned, NULL); if (ok) { // inBuffer[0]是报告ID无ID设备为0 // 数据从inBuffer[1]开始 } // 下发输出报告 BYTE outBuffer[65] {0}; outBuffer[0] 0; // 报告ID固定设备无ID填0 outBuffer[1] 0x01; // 例如第一位表示启动某个功能 ok DeviceIoControl(hDev, IOCTL_HID_SET_OUTPUT_REPORT, outBuffer, outputReportLen 1, NULL, 0, bytesReturned, NULL);IOCTL_HID_GET_INPUT_REPORT的输入缓冲区参数第二、三参为NULL输出缓冲区存放设备返回的数据。IOCTL_HID_SET_OUTPUT_REPORT则相反输入缓冲区是待发送的报告输出缓冲区可以省掉。宏对应的控制码在hidio.h头文件里定义。使用这个方式最大的好处是同步返回调用线程不会被长时间阻塞在UI线程里做定时查询也相对安全。不过要注意主动GET请求依赖设备固件支持个别低端HID单片机固件只在中断端点上回报数据不处理GET命令这种情况下IOCTL_HID_GET_INPUT_REPORT会返回失败或一直超时。4.3 用OVERLAPPED异步读写解决卡死工程级应用必须考虑设备拔出或故障时ReadFile阻塞的问题。解决思路是异步I/O或独立线程。示例包里2016-12-13这版相比旧的HidPack-08.rar改进点就在引入了OVERLAPPED结构和超时取消机制关键代码骨架如下HANDLE hEvent CreateEvent(NULL, TRUE, FALSE, NULL); OVERLAPPED ovl {0}; ovl.hEvent hEvent; BYTE inBuffer[64] {0}; DWORD bytesRead 0; BOOL ok ReadFile(hDev, inBuffer, inputReportLen, bytesRead, ovl); if (!ok GetLastError() ERROR_IO_PENDING) { // 等待事件触发或超时 DWORD waitResult WaitForSingleObject(hEvent, 1000); // 1秒超时 if (waitResult WAIT_TIMEOUT) { CancelIoEx(hDev, ovl); // 取消未完成的IO请求 // 清理并重新发起读取 } else { GetOverlappedResult(hDev, ovl, bytesRead, FALSE); } } CloseHandle(hEvent);异步模式的关键点有三个一是OVERLAPPED结构里必须设置hEvent否则无法获得完成通知二是每次调用ReadFile前都要重置事件对象ResetEvent否则上一次的信号残留会导致误判三是超时发生后必须调用CancelIoEx取消正在排队的IO请求否则设备句柄关闭时会引发“访问被拒绝”之类的脏错误。WaitForSingleObject的等待时间要大于设备上报周期比如设备每100毫秒上报一次超时设500毫秒比较合理太短会导致正常数据被误杀太长则设备拔出后界面响应迟钝。5. 热插拔自愈与排查技巧5.1 注册设备通知实现插拔自愈工业设备和工具型软件都需要处理“设备拔了再插”的场景。Windows提供了RegisterDeviceNotification机制在窗口程序中接收WM_DEVICECHANGE消息示例程序包含的HID通讯说明.txt.bak文件里记录了原作者自己加的设备移除判断逻辑。注册代码要放在初始化阶段DEV_BROADCAST_DEVICEINTERFACE filter {0}; filter.dbcc_size sizeof(DEV_BROADCAST_DEVICEINTERFACE); filter.dbcc_devicetype DBT_DEVTYP_DEVICEINTERFACE; // 使用相同的HID GUID进行过滤 GUID hidGuid; HidD_GetHidGuid(hidGuid); filter.dbcc_classguid hidGuid; HDEVNOTIFY hNotify RegisterDeviceNotification(hWnd, filter, DEVICE_NOTIFY_WINDOW_HANDLE);在窗口过程函数中处理WM_DEVICECHANGEcase WM_DEVICECHANGE: switch (wParam) { case DBT_DEVICEARRIVAL: // 设备插入重新枚举并自动打开 ReopenHidDevice(); break; case DBT_DEVICEREMOVECOMPLETE: // 设备移除关闭旧句柄置为无效 CloseHandle(g_hHidDevice); g_hHidDevice INVALID_HANDLE_VALUE; break; } return TRUE;DEVICE_NOTIFY_WINDOW_HANDLE表示消息投递到指定窗口。设备拔出时DBT_DEVICEREMOVECOMPLETE消息通常会先于下一次读操作到达只要在这里把旧句柄置空后续读写就会直接返回无效句柄错误避免误读脏数据。注意RegisterDeviceNotification注册时使用的是接口类的GUID不是设备类GUID两者都源于系统返回的HidD_GetHidGuid这两个值在大多数系统上相同但混用时容易在某些驱动版本出现消息不到达的诡异问题。5.2 常见错误码对照与定位读写失败时不要只看“函数返回FALSE”要把GetLastError取出来对照定位。HID通讯里高频出现的错误码和应对方式错误码含义排查方向87参数错误检查缓冲区长度是否与报告长度匹配5拒绝访问设备被其它进程独占关闭调试器或监控软件1功能错误固件不支持该IOCTL命令对照描述符确认1167设备未连接设备已被拔出句柄失效995IO操作被取消调用了CancelIoEx属于预期行为1006文件卷已更改设备重枚举需要重新打开87是最常见的多数是因为ReadFile缓冲区长度填了数组容量而没按HidP_GetCaps返回的长度。5在调试阶段频繁出现多半是调试器里上一次运行的程序没有正常关闭句柄设备被僵尸进程占住这时打开任务管理器结束残留进程即可。995是CancelIoEx成功后返回的正常错误要做成独立分支判断不要当成失败日志刷屏。5.3 用报告ID区分多功能设备带多个功能模块的复合HID设备例如同时具备条码扫描和RFID读取功能通常会使用不同的报告ID区分数据来源。解析时先读inBuffer[0]根据ID值分发到不同处理函数。示例程序如果碰到这类设备整个解析框架要做成状态机模式。BYTE reportId inBuffer[0]; switch (reportId) { case 0x01: // 条码数据 HandleBarcodeData(inBuffer 1, bytesRead - 1); break; case 0x02: // RFID数据 HandleRfidData(inBuffer 1, bytesRead - 1); break; default: break; }5.4 合上设备句柄的三个细节程序退出时CloseHandle之前有三件容易被忽略的事先取消所有未决的异步IO请求、再关闭关联的事件对象、最后才关闭设备句柄。顺序颠倒的话系统可能在句柄关闭后仍尝试向事件对象发送完成回调引发访问越界或随机崩溃。如果程序在调试状态下频繁重启设备句柄没有正确释放会导致下次启动时枚举正常但打开失败这时需要打开设备管理器禁用再启用设备节点这个动作比重启电脑省时间。调试HID设备时建议在窗口标题栏直接显示当前句柄状态和最近一次错误码能显著缩短定位周期。本文还有配套的精品资源点击获取