简介面向VC6.0开发者的HID设备读写示例资源适合嵌入式系统、设备驱动及上位机通信开发入门者。示例演示了通过Win32 API与HID类驱动交互的完整流程涵盖设备集合枚举、目标接口选择、句柄打开、报告读写与资源释放等环节并具体涉及SetupDiGetClassDevs、SetupDiEnumDeviceInterfaces、CreateFile、DeviceIoControl等关键函数的使用有助于理解系统级硬件通信编程的实现思路也便于掌握HID报告描述符的基本解析方法。资源包共24个文件压缩后大小约73KB以头文件、源文件和库文件为主其中头文件用于接口与常量声明源文件实现读写逻辑另含工程配置文件、说明文档以及可直接运行的示例程序便于边运行边对照分析代码。目前已有109人对此资源进行学习浏览。对于希望快速掌握VC下HID设备读写实现方法的开发者而言这份示例短小精悍代码结构直接可迁移应用到实际项目中。1. VC HID读写例程为什么老例子最值得翻出来跑一遍做上位机难免要跟 USB 读卡器、加密狗、体感传感器这类自定义 HID 设备打交道。HID 通信看起来简单真上手时枚举路径、报告 ID、缓冲区长度、拔插重连全是细节。这个 VC6.0 时代的 HID 读写实例把从设备枚举到句柄读写的完整链路都捋了一遍既有最朴素的同步读写代码也有对缓冲区边界的处理。适合还在维护老工控工程、需要快速看清 HID 接口调用方式的人也适合新项目里想复用这套枚举和读写逻辑的开发者。我照着它把一台卡在读写环节的产线设备拉了起来这一篇把例子里可以直接抄的部分展开讲同时把最容易踩的坑标出来。2. HID读写原理报告、端点和两套API怎么选2.1 HID设备在Windows系统里到底长什么样HID 设备虽然挂在 USB 总线上但应用层看到的并不是一个个端点而是由系统 HID 类驱动抽象出来的“顶层集合”。每个顶层集合对应一个设备接口接口的符号链接名就是我们常说的 DevicePath。应用层要读写 HID 设备第一步不是直接发数据而是先通过 SetupAPI 枚举出这个设备路径再用 CreateFile 把它换成一个可读写的句柄。搞清楚系统对 HID 的抽象方式很多问题就都好解释了。比如为什么枚举到的路径是一长串包含 VID、PID 和实例号的字符串而不是简单的“COM3”为什么同一个 USB 设备可能枚举出多个 HID 接口为什么某些键盘鼠标的读写行为和其他 HID 设备不一样。这套例程把枚举代码写在最前面就是想让使用者先看到设备路径再去执行读写。在数据层面HID 设备使用报告Report来通信。报告分三类输入报告承载设备发给主机的数据输出报告承载主机发给设备的数据Feature 报告则用于配置类信息。输入输出报告走中断端点Feature 报告走控制端点。理解这个区别很关键因为后面调用 API 时读写输入输出报告用的是 ReadFile/WriteFile而访问 Feature 报告用的是 HidD_GetFeature/HidD_SetFeature两者不能混用。例子里把两套调用都写全了正好可以对比着看。2.2 为什么是VC6.0加hid.dll而不是libusb我在拿到这套例子时第一个疑问就是都什么年代了为什么不直接用 libusb 或者 WinUSB把代码看了一遍才明白在 HID 设备这个场景里Windows 自带的 hid.dll 就是最直接的方案第三方库反而增加了部署成本。hid.dll 是操作系统自带的标准组件任何 Windows 版本都有不需要额外安装运行库。HID 设备本身使用系统内置的 HID 类驱动不需要自己写内核驱动或者安装第三方驱动这大大降低了交付时的麻烦。对 VC6.0 这种老工程来说尤其重要——老项目往往运行在受控的工控环境下不能随便装运行库而 hid.dll 接口稳定从 Windows 2000 到现在的系统都保持了兼容性。libusb 在自定义 USB 设备场景下确实更强但它的前提是设备能被 WinUSB 驱动接管。HID 设备默认装的是 HID 类驱动直接绕过它去操作端点会破坏系统对键盘鼠标等标准设备的处理。更关键的是这套例子的目的很明确现有系统已经识别出设备是 HID只需要在应用层完成数据交互。既然应用层 API 够用就不需要把问题复杂化。所以我后来的习惯是只要设备能被系统识别成 HID就用这套原生接口如果是完全自定义的 USB 设备才考虑 WinUSB 或 libusb。2.3 HidD_* 与 ReadFile/WriteFile 的定位差异这套例程里同时出现了两组 API初学者最容易搞混。我最初也在这里翻过车把 Feature 报告当成普通数据流用 ReadFile 去读结果读出来的内容完全不对。HidD_ 系列函数是从 hid.dll 导出的用途偏“管理面”。HidD_GetAttributes 拿设备属性HidD_GetPreparsedData 拿解析过的报告描述符HidD_GetFeature 和 HidD_SetFeature 用于读取和设置 Feature 报告。这些操作不经过中断端点所以不受设备是否正在发数据的影响适合做配置初始化。ReadFile/WriteFile 则是标准的文件读写接口用途偏“数据面”。它们操作的是输入报告和输出报告所对应的端点缓冲区。当设备主动上报数据时数据会先进入系统的输入报告队列ReadFile 从这个队列取数据WriteFile 把输出报告送入端点等待设备取走。这两组 API 可以共存在一个句柄上但要注意时序一边用 HidD_SetFeature 配置设备一边用 WriteFile 发数据两边并不会自动排队。最稳妥的做法是先通过 Feature 报告完成配置再进入数据收发循环。理解了这两者的分工再去看例子代码就会发现它的结构非常典型开头用 HidD_GetHidGuid 和 SetupAPI 找设备路径打开句柄后先用 HidD_GetAttributes 校验 VID/PID然后用 WriteFile 发送指令用 ReadFile 等待响应遇到配置类命令则临时切到 HidD_SetFeature。这种分层方式算是 HID 应用开发的通行做法照着抄不会出大错。3. 枚举HID设备VC6.0工程搭建与设备路径获取3.1 工程配置头文件、链接库和字符集选择要在 VC6.0 里跑通这套例子工程配置是第一道坎。新建一个 Win32 Console Application 或 MFC 对话框工程后需要引入三个东西setupapi.h、hidsdi.h 两个头文件以及 setupapi.lib、hid.lib 两个静态库。老版本的 Platform SDK 可能没有带 hidsdi.h 和 hid.lib要确认安装目录里存在这两个文件。工程设置里需要注意一个细节字符集设置在 VC6.0 里默认是“Not Set”这种情况下 TCHAR 会被展开成 char而设备路径是宽字符数组。例子里申请缓冲区用的是 char 数组也可以前提是不要对路径内容做字节操作只在取出路径后转成宽字符串。我一般直接在代码里显式调用 CreateFileW 和 HidD_GetAttributes不让宏决定 API 版本这样就算工程字符集是 ANSI 也能正确编译。为了避免每建一个工程都要检查一遍我习惯写一个公共头文件把必要的包含和链接指令固定放在里面// HidCommon.h #ifndef HID_COMMON_H #define HID_COMMON_H #define WIN32_LEAN_AND_MEAN #include windows.h #include setupapi.h #include hidsdi.h #pragma comment(lib, setupapi.lib) #pragma comment(lib, hid.lib) #endif这里 WIN32_LEAN_AND_MEAN 的作用是去掉 windows.h 里不常用的定义加快编译速度也可以减少和某些第三方头文件的重名冲突。setupapi.lib 提供 SetupDiGetClassDevs 等设备的枚举接口hid.lib 提供 HidD_GetHidGuid、HidD_GetAttributes 等 HID 专用函数。这两个库在老 SDK 里如果找不到可以把路径指到最新 Windows SDK 的 Lib 目录通常能直接兼容。3.2 枚举代码HidD_GetHidGuid 与 SetupAPI 配合使用枚举 HID 设备的标准做法是先通过 HidD_GetHidGuid 拿到 HID 设备的全局 GUID再用 SetupAPI 遍历所有匹配这个 GUID 的接口。这段代码在例子里占的篇幅不小我建议直接抄但要理解它为什么是两遍调用。// EnumHid.c —— 枚举系统中所有HID设备路径 #include stdio.h #include stdlib.h #include HidCommon.h void EnumerateHidDevices() { GUID hidGuid; HidD_GetHidGuid(hidGuid); HDEVINFO hDevInfo SetupDiGetClassDevs( hidGuid, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE); if (hDevInfo INVALID_HANDLE_VALUE) { printf(SetupDiGetClassDevs failed: %d\n, GetLastError()); return; } SP_DEVICE_INTERFACE_DATA ifData; ifData.cbSize sizeof(SP_DEVICE_INTERFACE_DATA); for (DWORD index 0; SetupDiEnumDeviceInterfaces(hDevInfo, NULL, hidGuid, index, ifData); index) { // 第一次调用获取设备路径所需的缓冲区大小 DWORD requiredSize 0; SetupDiGetDeviceInterfaceDetail( hDevInfo, ifData, NULL, 0, requiredSize, NULL); PSP_DEVICE_INTERFACE_DETAIL_DATA detail (PSP_DEVICE_INTERFACE_DETAIL_DATA)malloc(requiredSize); detail-cbSize sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA); // 第二次调用真正取出设备路径 if (SetupDiGetDeviceInterfaceDetail( hDevInfo, ifData, detail, requiredSize, NULL, NULL)) { // detail-DevicePath 是宽字符设备路径 // 在实际工程里应把路径保存到全局表中备用 wprintf(LDevicePath: %s\n, detail-DevicePath); } free(detail); } SetupDiDestroyDeviceInfoList(hDevInfo); }这段代码里最关键的是 SetupDiGetDeviceInterfaceDetail 为什么调用两次的原因。第一次传入 NULL 缓冲区函数会把需要的字节数写入 requiredSize第二次分配足够空间后再调用才能拿到完整路径。如果跳过第一次直接传一个固定大小的缓冲区路径稍微长一点就会返回 ERROR_INSUFFICIENT_BUFFER这是枚举时最常见的翻车点之一。3.3 从设备路径到可读写句柄拿到设备路径后只是一个字符串真正要和设备通信必须用 CreateFile 把这个字符串转换成句柄。例子工程里会定义一个打开函数把路径、访问权限和共享模式都准备好。HANDLE OpenHidDevice(const WCHAR* devicePath) { HANDLE hDevice CreateFileW( devicePath, GENERIC_READ | GENERIC_WRITE, FILE_SHARE_READ | FILE_SHARE_WRITE, NULL, OPEN_EXISTING, 0, NULL); if (hDevice INVALID_HANDLE_VALUE) { printf(CreateFile failed: %d\n, GetLastError()); return INVALID_HANDLE_VALUE; } return hDevice; }打开句柄时有几个参数是 HID 场景下必须注意的。访问权限要同时包含读和写因为输入输出报告各占一端共享模式要带上读和写否则设备被自己的应用打开后就无法被监控或调试工具访问了。最后一个参数控制是否使用重叠 I/O。例子里传的是 0表示同步读写逻辑简单。如果设备上报频率很高或者读写可能长时间阻塞就要考虑把这个参数换成 FILE_FLAG_OVERLAPPED用事件或回调处理异步结果。我曾经在一个数据采集项目里因为没设置这个标志导致 UI 线程被一个迟迟不响应的设备卡死后来把同步调用挪到了工作线程里才解决。4. 读写HID设备输出报告、输入报告与Feature报告的实现4.1 打开句柄与同步写输出报告设备打开成功之后下一步就是通信。这套例子的核心代码集中在写入函数它把业务数据放到报告缓冲区再通过 WriteFile 发送到设备的输出端点。// WriteHid.c —— 向HID设备发送输出报告 BOOL WriteHidData(HANDLE hDevice, BYTE* payload, DWORD payloadLen) { // 输出报告缓冲区 报告ID占用1字节 业务数据长度 DWORD reportLen payloadLen 1; BYTE* reportBuf (BYTE*)malloc(reportLen); if (reportBuf NULL) { return FALSE; } // 第一位是报告ID无ID多用途设备通常填写0 reportBuf[0] 0x00; memcpy(reportBuf 1, payload, payloadLen); DWORD written 0; BOOL ok WriteFile(hDevice, reportBuf, reportLen, written, NULL); if (!ok) { printf(WriteFile failed: %d\n, GetLastError()); } free(reportBuf); return ok (written reportLen); }这里的 buffer 组织方式是一个容易忽视的点HID 报告在传输时第一字节固定是报告 ID即使设备只支持一种报告、不存在多个报告 ID也要把这一字节留出来。比如设备的输出报告描述符长度为 64 字节那实际传给 WriteFile 的数据就要 65 字节第一字节填 0后面的 64 字节才是真实数据。例子工程里没有把这种细节单独拿出来讲但注释里写得很明确。我在另一个项目里就是因为少算了这一字节设备收不到任何指令排查了很久。如果设备支持多份报告那么 reportBuf[0] 就填对应的报告 ID如果设备没有声明报告 ID系统要求填 0。通用的做法是先通过 HidD_GetPreparsedData 解析报告描述符拿到最大报告长度后再分配缓冲区这样比硬编码牢靠得多。4.2 读输入报告时的阻塞问题读取输入报告是 HID 通信里另一个容易出问题的地方。WriteFile 把数据发出去之后设备可能要几十毫秒甚至更久才会响应如果拿着同步 ReadFile 在 UI 线程里等界面就卡住了。例子工程把读取函数独立出来并且放在一个单独的线程里执行这个设计值得借鉴。// ReadHid.c —— 读取HID设备输入报告 BOOL ReadHidData(HANDLE hDevice, BYTE* payload, DWORD* payloadLen) { BYTE reportBuf[65] {0}; // 输入报告长度 报告ID占位 DWORD bytesRead 0; BOOL ok ReadFile(hDevice, reportBuf, 65, bytesRead, NULL); if (!ok) { return FALSE; } if (bytesRead 1) { // bytesRead[0] 是报告ID业务数据从下标1开始 *payloadLen bytesRead - 1; memcpy(payload, reportBuf 1, *payloadLen); return TRUE; } return FALSE; }同步 ReadFile 的行为是阻塞等待直到输入报告队列里有数据或者出错才返回。哪种设备会一直不返回数据很多自定义 HID 设备只在收到指令后才发送响应甚至有些设备只上报事件平时完全没有数据流。针对这种情况我的做法是给 ReadFile 传入一个可取消的 I/O 或使用超时控制。如果想保持同步逻辑简单也可以像例子工程那样把读取放到独立的线程线程阻塞不影响界面操作。读缓冲区的大小同样要遵循“报告长度 1”的规则。系统从设备收到的输入报告会加上报告 ID 字节后放进队列如果缓冲区比这个长度小ReadFile 返回时会报缓冲区过小错误数据也会被丢弃。所以我在代码里固定用 65 字节对应 64 字节输入报告加 1 字节 ID 的典型场景。如果设备报告长度经过解析确认是 32 字节就把缓冲区改成 33不要盲目沿用这个数字。4.3 Feature报告的正确打开方式输入输出报告用于数据交互Feature 报告则用于设备配置、固件版本读取这类管理操作。它不走中断端点而是通过控制端点传输所以不能用 ReadFile/WriteFile 直接操作。例子工程里专门调用了 HidD_GetFeature 和 HidD_SetFeature这里也把关键调用拎出来看。BYTE featureBuf[33] {0}; featureBuf[0] 0x01; // Feature报告ID // 读取设备固件版本 BOOL ok HidD_GetFeature(hDevice, featureBuf, sizeof(featureBuf)); if (ok) { // featureBuf[0] 是报告ID // featureBuf[1] 起为设备返回的特征数据 } // 设置设备参数 BYTE configBuf[33] {0}; configBuf[0] 0x01; configBuf[1] 0x5A; configBuf[2] 0x01; BOOL okSet HidD_SetFeature(hDevice, configBuf, sizeof(configBuf));Feature 报告的缓冲区大小同样需要包含报告 ID但最大长度来自报告描述符不能拍脑袋。和输入输出报告不同HidD_SetFeature 不会像 WriteFile 那样因为设备没有响应而长时间阻塞它走的是控制端点系统会在超时后返回失败。这个特性让它非常适合做初始化配置。我在写设备握手流程时通常先用 HidD_SetFeature 下发设备模式再用 ReadFile 等待设备回应确认信号两个阶段分开处理逻辑会很清晰。5. 避坑HID读写最常见的五个翻车点5.1 按现象排一遍缓冲区、句柄、共享冲突这些老问题以下是这套 HID 例子里最容易踩到的问题我按实战中出现的频率从高到低一个个列出来每条都给出排查思路。现象一WriteFile / ReadFile 报“参数错误”设备完全无响应。原因报告缓冲区长度没有加报告 ID 字节。设备报告描述符声明 64 字节但应用层只分配 64 字节就调用读写 API系统按 65 字节解释收发数据长度不匹配直接返回 ERROR_INVALID_PARAMETER。 解决先在设备属性或报告描述符中拿到最大输入、输出报告长度代码里统一加 1 后再分配缓冲区。例子工程里是固定用了 65 字节只要设备报告长度是 64 就能直接抄。现象二设备拔掉再插入后原句柄读写全部失败应用不会自动恢复。原因CreateFile 得到的句柄绑定的是设备实例。设备重新枚举后会生成新的符号链接名旧句柄已经失效。很多工程只在启动时打开一次设备拔插后没有重新枚举。 解决监听系统设备变更消息或者让设备读写线程在返回 ERROR_DEVICE_REMOVED / ERROR_GEN_FAILURE 时触发重连流程重新枚举路径、重新打开句柄。例子工程把设备路径保存在全局变量里重连时只需要重新跑一遍枚举代码。现象三SetupDiGetDeviceInterfaceDetail 第一次调用返回 ERROR_INSUFFICIENT_BUFFER分配了空间后还是失败。原因没有设置 detail-cbSize 字段为 sizeof 或设备上下文结构大小。这个 API 要求调用前把 cbSize 初始化老 SDK 的示例代码经常漏掉这一点。 解决分配 requiredSize 字节后先把 detail-cbSize 赋值为 sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA)再调用第二次。这套例子的枚举函数里已经包含这个步骤直接用即可。现象四CreateFile 打开失败GetLastError 返回 ERROR_ACCESS_DENIED 或 ERROR_SHARING_VIOLATION。原因设备已经被其他进程以独占方式打开。常见的是厂商调试工具占用了设备或者上一次程序崩溃后句柄没释放干净。 解决先关闭可能占用设备的监控工具再检查 CreateFile 的共享模式是否带了 FILE_SHARE_READ | FILE_SHARE_WRITE。如果多个进程必须同时访问同一个 HID 设备共享模式必须显式声明否则后打开的进程会被拒绝。现象五在 VC6.0 老工程里使用 CreateFileW 编译不过提示无法解析的外部符号或找不到 hidsdi.h。原因老工程安装的 SDK 版本太旧头文件和导入库不全字符集也不匹配。这种情况通常发生在从网上下载的老源码包里。 解决升级 Platform SDK 或将 include/lib 目录指向更新的 Windows SDK同时在工程预处理里加上 _WIN32_WINNT0x0501让系统 API 定义完整。换用新 SDK 后HidD_GetHidGuid 和 CreateFileW 都能正确声明。5.2 动手前先确认的四个关键参数除了上面五个坑之外真正把例程移植到自己项目里之前我建议先向设备厂商或通过 USB 树查看四个参数。第一是设备 VID 和 PID用来在枚举结果中过滤目标设备避免同一台电脑上多支 HID 设备时打开错误。第二是输入报告长度和输出报告长度它们决定了缓冲区分配和读写 API 的字节数。第三是该设备是否使用报告 ID如果使用要确认具体的 ID 值。第四是设备是否存在批量数据流如果设备只在收到指令后应答直接同步读取极容易卡死必须用异步或工作线程。这四个参数在例子工程里并没有全部自动化它只是提供了一个可直接编译的骨架。我把枚举、打开、写、读、重连的流程走通之后第一个动作就是把这些参数做成一个配置结构体放在代码最前面后续换设备时只需要改这一处。有了这套准备HID 通信的开发就基本变成体力活了遇到问题也有了明确的排查顺序而不是靠玄学试。6. 复用与验证把例程封装成自己的HID通信类6.1 封装类的最小结构把例程里分散的函数归拢成一个类复用起来会轻松很多。下面这个封装是借鉴例程结构再压缩后的最小版本足够覆盖绝大多数应用场景。// HidDevice.h —— HID设备操作封装 class HidDevice { public: HidDevice(); virtual ~HidDevice(); bool Open(const WCHAR* devicePath); void Close(); bool WriteCommand(const BYTE* data, DWORD len); bool ReadResponse(BYTE* data, DWORD* len); bool GetFeature(BYTE reportId, BYTE* data, DWORD len); bool SetFeature(BYTE reportId, const BYTE* data, DWORD len); private: HANDLE m_hDev; };类的核心价值是把设备路径、句柄、缓冲区长度这些状态收敛在一起。打开时把例程里的 CreateFile 逻辑放进来读写时自动处理报告 ID 偏移关闭时释放句柄并清理内部状态。有了这个类应用主逻辑里就不再出现 API 层面的细节排查问题时也只需要关注类内部实现的几个函数。6.2 用枚举和回环数据验证通信链路封装完成后的第一件事不是接真实设备而是做一次链路验证。我通常先在设备树里把目标设备的路径打印出来然后用 HidD_GetAttributes 读取 VID/PID 和版本号这能确认枚举和打开这段链路没有问题。接下来做回环测试向设备发送一个已知特征的指令然后等待设备返回约定好的数据。如果设备固件支持回环模式这就能同时验证写和读两条链路。如果设备固件不支持至少可以通过逻辑分析仪或设备自带的调试接口确认它收到了数据然后再去追读取环节。最后做拔插测试在设备读写过程中拔出设备确认应用能感知到失败并进入重连流程再插回设备看是否能自动恢复。这套流程走完之后我对这套 HID 例程的信任度会明显提高因为它把最容易出错的几个点都覆盖了一遍。从那以后我每次接手 HID 相关的通信工程都强制自己先跑一遍这套验证流程尤其是报告长度加 1 和设备路径枚举这两个老坑再也不敢跳过。希望这次的拆解对你有用。本文还有配套的精品资源点击获取
