Windows主机端与自定义USB HID设备通信详解

Ref: http://blogold.chinaunix.net/u3/98810/showart_1963291.html

说明： -          以下结论都是基于Windows XP系统所得出的，不保证在其他系统的适用性。 -          在此讨论的是HID自定义设备，对于标准设备，譬如USB鼠标和键盘，由于操作系统对其独占，许多操作未必能正确执行。 1．  所使用的典型Windows API CreateFile ReadFile WriteFile 以下函数是DDK的内容： HidD_SetFeature HidD_GetFeature HidD_SetOutputReport HidD_GetInputReport 其中，CreateFile用于打开设备；ReadFile、HidD_GetFeature、HidD_GetInputReport用于设备到主机方向的数据通信；WriteFile、HidD_SetFeature、HidD_SetOutputReport用于主机到设备方向的数据通信。鉴于实际应用，后文主要讨论CreateFile，WriteFile，ReadFile，HidD_SetFeature四个函数，明白了这四个函数，其它的可以类推之。 2．  几个常见错误        当使用以上API时，如果操作失败，调用GetLastError()会得到以下常见错误：        6：         句柄无效        23：       数据错误（循环冗余码检查）        87：       参数错误        1784：    用户提供的buffer无效        后文将会详细说明这些错误情况。 3．         主机端设备枚举程序流程 4．         函数使用说明 CreateFile(devDetail->DevicePath,                                         //设备路径                GENERIC_READ | GENERIC_WRITE,                    //访问方式                FILE_SHARE_READ | FILE_SHARE_WRITE,         //共享模式                NULL,                OPEN_EXISTING,                                           //文件不存在时，返回失败                FILE_FLAG_OVERLAPPED,                                 //以重叠（异步）模式打开                NULL); 在这里，CreateFile用于打开HID设备，其中设备路径通过函数SetupDiGetInterfaceDeviceDetail取得。CreateFile有以下几点需要注意： -     访问方式： 如果是系统独占设备，例如鼠标、键盘等等，应将此参数设置为0，否则后续函数操作将失败（譬如HidD_GetAttributes）；也就是说，不能对独占设备进行除了查询以外的任何操作，所以能够使用的函数也是很有限的，下文的一些函数并不一定适合这些设备。在此顺便列出MSDN上关于此参数的说明： If this parameter is zero, the application can query file and device attributes without accessing the device. This is useful if an application wants to determine the size of a floppy disk drive and the formats it supports without requiring a floppy in the drive. It can also be used to test for the file's or directory's existence without opening it for read or write access。 -          重叠（异步）模式：此参数并不会在此处表现出明显的意义，它主要是对后续的WriteFile，ReadFile有影响。如果这里设置为重叠（异步）模式，那么在使用WriteFile，ReadFile时也应该使用重叠（异步）模式，反之亦然。这首先要求WriteFile，ReadFile的最后一个参数不能为空（NULL）。否则，便会返回87（参数错误）错误号。当然，87号错误并不代表就是此参数不正确，更多的信息将在具体讲述这两个函数时指出。此参数为0时，代表同步模式，即WriteFile，ReadFile操作会在数据处理完成之后才返回，否则阻塞在函数内部。 ReadFile(hDev,                                 //设备句柄，即CreateFile的返回值               recvBuffer,                          //用于接收数据的buffer               IN_REPORT_LEN,              //要读取数据的长度               &recvBytes,                         //实际收到的数据的字节数               &ol);                                  //异步模式 在这里，ReadFile用于读取HID设备通过中断IN传输发来的输入报告。有以下几点要注意： 1、ReadFile的调用不会引起设备的任何反应，即HID设备与主机之间的中断IN传输不与ReadFile打交道。实际上主机会在最大间隔时间（由设备的端点描述符来指定）内轮询设备，发出中断IN传输的请求。“读取”即意味着从某个buffer里面取回数据，实际上这个buffer就是HID设备驱动中的buffer。这个buffer的大小可以通过HidD_SetNumInputBuffers来改变。在XP上缺省值是32（个报告）。 2、读取的数据对象是输入报告，也即通过中断输入管道传入的数据。所以，如果设备不支持中断IN传输，那么是无法使用此函数来得到预期结果的。实际上这种情况不可能在HID中出现，因为协议指明了至少要有一个中断IN端点。 3、IN_REPORT_LEN代表要读取的数据的长度（实际的数据正文+一个byte的报告ID），这里是一个常数，主要是因为设备固件的信息我是完全知道的，当然知道要读取多少数据（也就是报告的长度）；不过也可以通过另外的函数（HidD_GetPreparsedData）来事先取得报告的长度，这里不做详细讨论。因为很难想象在不了解固件信息的情况下来做自定义设备的HID通信，在实际应用中一般来说就是固件与PC程序匹配着来开发。此参数如果设置过大，不会有实质性的错误，在recvBytes参数中会输出实际读到的长度；如果设置过小，即小于报告的长度，会返回1784号错误（用户提供的buffer无效）。 4、关于异步模式。前面已经提过，此参数的设置必须与CreateFile时的设置相对应，否则会返回87号错误（参数错误）。如果不需要异步模式，此参数需置为NULL。在这种情况下，ReadFile会一直等待直到数据读取成功，所以会阻塞住程序的当前过程。        WriteFile(hDev,                                 //设备句柄，即CreateFile的返回值                      reportBuf,                           //存有待发送数据的buffer                      OUT_REPORT_LEN,           //待发送数据的长度                      &sendBytes,                        //实际收到的数据的字节数                      &ol);                                  //异步模式        在这里，WriteFile用于传输一个输出报告给HID设备。有以下几点要注意： 1、  与ReadFile不同，WriteFile函数被调用后，虽然也是经过驱动程序，但是最终会反映到设备中。也就是说，调用WriteFile后，设备会接收到输出报告的请求。如果设备使用了中断OUT传输，则WriteFile会通过中断OUT管道来进行传输；否则会使用SetReport请求通过控制管道来传输。 2、  OUT_REPORT_LEN代表要写入的数据长度（实际的数据正文+一个byte的报告ID）。如果大于实际报告的长度，则使用实际报告长度；如果小于实际报告长度，会返回1784号错误（用户提供的buffer无效）。 3、  reportBuf[0]必须存有待发送报告的ID，并且此报告ID指示的必须是输出报告，否则会返回87号错误（参数错误）。这种情况可能容易被程序员忽略，结果不知错误号所反映的是什么，网上也经常有类似疑问的帖子。顺便指出，输入报告、输入报告、特征报告这些报告类型，是反映在HID设备的报告描述符中。后文将做举例讨论。 4、  关于异步模式。前面已经提过，此参数的设置必须与CreateFile时的设置相对应，否则会返回87号错误（参数错误）。如果不需要异步模式，此参数需置为NULL。在这种情况下，WriteFile会一直等待直到数据读取成功，所以会阻塞住程序的当前过程。 HidD_SetFeature(hDev,                                    //设备句柄，即CreateFile的返回值                      reportBuf,                                   //存有待发送数据的buffer                      FEATURE_REPORT_LEN);        //buffer的长度 HidD_SetOutputReport(hDev,                            //设备句柄，即CreateFile的返回值                      reportBuf,                                   //存有待发送数据的buffer                      OUT_REPORT_LEN);                //buffer的长度 HidD_SetFeature发送一个特征报告给设备，HidD_ SetOutputReport发送一个输出报告给设备。注意以下几点： 1、  跟WriteFile类似，必须在reportBuf[0]中指明要发送的报告的ID，并且和各自适合的类型相对应。也就是说，HidD_SetFeature只能发送特征报告，因此报告ID必须是特征报告的ID；HidD_SetOutputReport只能发送输出报告，因此报告ID只能是输出报告的ID。 2、  这两个函数最常返回的错误代码是23（数据错误）。包括但不仅限于以下情况： - 报告ID与固件描述的不符。 - 传入的buffer长度少于固件描述的报告的长度。 据有关资料反映（非官方文档），只要是驱动程序对请求无反应，都会产生此错误。 5．         常见错误汇总 - HID ReadFile   - Error Code 6 (handle is invalid)     传入的句柄无效   - Error Code 87 (参数错误)     很可能是createfile时声明了异步方式，但是读取时按同步读取。   - Error Code 1784 (用户提供的buffer无效):     传参时传入的“读取buffer长度”与实际的报告长度不符。 - HID WriteFile   - Error Code 6 (handle is invalid)     传入的句柄无效   - Error Code 87（参数错误）     - CreateFile时声明的同步/异步方式与实际调用WriteFile时传入的不同。     - 报告ID与固件中定义的不一致（buffer的首字节是报告ID）   - Error Code 1784 (用户提供的buffer无效)     传参时传入的“写入buffer长度”与实际的报告长度不符。 - HidD_SetFeature - HidD_SetOutputReport   - Error Code 1 (incorrect function)     不支持此函数，很可能是设备的报告描述符中未定义这样的报告类型（输入、输出、特征）   - Error Code 6 (handle is invalid)     传入的句柄无效   - Error Code 23（数据错误（循环冗余码检查））     - 报告ID与固件中定义的不相符（buffer的首字节是报告ID）     - 传入的buffer长度少于固件定义的报告长度（报告正文+1byte, 1byte为报告ID）     - 据相关资料反映（非官方文档），只要是驱动程序不接受此请求（对请求无反应），都会产生此错误 6．         报告描述符及数据通信程序示例 报告描述符（由于是汇编代码，所以不必留意其语法，仅需注意表中的每个数据都占1个字节）： _ReportDescriptor:                            //报告描述符        .dw 0x06,  0x00, 0xff                 //用法页     .dw 0x09,  0x01                            //用法(供应商用法1)     .dw 0xa1,  0x01                            //集合开始     .dw 0x85,  0x01                            //报告ID(1)     .dw 0x09,  0x01                            //用法(供应商用法1)       .dw 0x15,  0x00                            //逻辑最小值(0)     .dw 0x26,  0xff, 0x0                      //逻辑最大值(255)     .dw 0x75,  0x08                            //报告大小(8)     .dw 0x95,  0x07                            //报告计数(7)     .dw 0x81,  0x06                            //输入（数据，变量，相对值）         .dw 0x09,  0x01                          //用法(供应商用法1)       .dw 0x85,  0x03                          //报告ID（3）     .dw 0xb1,  0x06                          //特征（数据，变量，相对值）        .dw 0x09,  0x01                      //用法(供应商用法1)     .dw 0x85,  0x02                         //报告ID（2）     .dw 0xb1,  0x06                         //特征（数据，变量，相对值）         .dw 0x09,  0x01                         //用法(供应商用法1)       .dw 0x85,  0x04                         //报告ID（4）     .dw 0x91,  0x06                         //输出（数据，变量，相对值）     .dw   0xc0                                  //结合结束 _ReportDescriptor_End: 这个报告描述符，定义了4个不同的报告：输入报告1，特征报告2，特征报告3，输出报告4（数字代表其报告ID）。为了简化，每个报告都是7个字节（加上报告ID就是8个字节）。下面用一个简单的示例来描述PC端与USB HID设备进行通信的一般方法。   #define USB_VID 0xFC0 #define USB_PID 0x420 HANDLE OpenMyHIDDevice(int overlapped); void HIDSampleFunc() {     HANDLE        hDev;     BYTE        recvDataBuf[8];     BYTE        reportBuf[8];     DWORD        bytes;           hDev = OpenMyHIDDevice(0); //打开设备，不使用重叠（异步）方式;          if (hDev == INVALID_HANDLE_VALUE)         return;          reportBuf[0] = 4; //输出报告的报告ID是4     memset(reportBuf, 0, 8);     reportBuf[1] = 1;     if (!WriteFile(hDev, reportBuf, 8, &bytes, NULL)) //写入数据到设备         return;          ReadFile(hDev, recvDatatBuf, 8, &bytes, NULL); //读取设备发给主机的数据 } HANDLE OpenMyHIDDevice(int overlapped) {     HANDLE     hidHandle;     GUID     hidGuid;          HidD_GetHidGuid(&hidGuid);          HDEVINFO hDevInfo = SetupDiGetClassDevs(                     &hidGuid,                     NULL,                     NULL,                     (DIGCF_PRESENT | DIGCF_DEVICEINTERFACE));      if (hDevInfo == INVALID_HANDLE_VALUE)     {      return INVALID_HANDLE_VALUE;     }          SP_DEVICE_INTERFACE_DATA devInfoData;     devInfoData.cbSize = sizeof (SP_DEVICE_INTERFACE_DATA);     int deviceNo = 0;          SetLastError(NO_ERROR);          while (GetLastError() != ERROR_NO_MORE_ITEMS)     {         if (SetupDiEnumInterfaceDevice (hDevInfo,                     0,                      &hidGuid,                     deviceNo,                     &devInfoData))         {             ULONG requiredLength = 0;             SetupDiGetInterfaceDeviceDetail(hDevInfo,                                             &devInfoData,                                             NULL,                                              0,                                             &requiredLength,                                             NULL);             PSP_INTERFACE_DEVICE_DETAIL_DATA devDetail =                  (SP_INTERFACE_DEVICE_DETAIL_DATA*) malloc (requiredLength);             devDetail->cbSize = sizeof(SP_INTERFACE_DEVICE_DETAIL_DATA);             if(!SetupDiGetInterfaceDeviceDetail(hDevInfo,                         &devInfoData,                         devDetail,                         requiredLength,                         NULL,                         NULL))              {                 free(devDetail);                            SetupDiDestroyDeviceInfoList(hDevInfo);                 return INVALID_HANDLE_VALUE;             }                   if (overlapped)                   {                          hidHandle = CreateFile(devDetail->DevicePath,                         GENERIC_READ | GENERIC_WRITE,                         FILE_SHARE_READ | FILE_SHARE_WRITE,                         NULL,                          OPEN_EXISTING,                          FILE_FLAG_OVERLAPPED,                         NULL);                   }                   else                   {                          hidHandle = CreateFile(devDetail->DevicePath,                         GENERIC_READ | GENERIC_WRITE,                         FILE_SHARE_READ | FILE_SHARE_WRITE,                         NULL,                          OPEN_EXISTING,                          0,                         NULL);                   }             free(devDetail);             if (hidHandle==INVALID_HANDLE_VALUE)             {                 SetupDiDestroyDeviceInfoList(hDevInfo);                 free(devDetail);                 return INVALID_HANDLE_VALUE;             }             _HIDD_ATTRIBUTES hidAttributes;             if(!HidD_GetAttributes(hidHandle, &hidAttributes))             {                 CloseHandle(hidHandle);                            SetupDiDestroyDeviceInfoList(hDevInfo);                 return INVALID_HANDLE_VALUE;             }             if (USB_VID == hidAttributes.VendorID                  && USB_PID == hidAttributes.ProductID)             {                 break;             }             else             {                 CloseHandle(hidHandle);                 ++deviceNo;             }         }     }     SetupDiDestroyDeviceInfoList(hDevInfo);     return hidHandle; }