Windows自定义HID API相关函数解释

CreateFile()

CreateFile()函数的函数原型为：

HANDLE CreateFile(
  LPCWSTR lpFileName,        //指向路径的指针
  DWORD dwDesiredAccess,     //访问模式（读/写）
  DWORD dwShareMode,         //共享模式
  LPSECURITY_ATTRIBUTES lpSecurityAttributes, //指向安全属性的指针
  DWORD dwCreationDisposition,   //如何创建
  DWORD dwFlagsAndAttributes,    //文件属性（同步或异步）
  HANDLE hTemplateFile           //用于复制文件句柄
);

CreateFile()用于打开HID设备，设备路径可通过函数SetupDi系列函数获取。此函数有以下需要注意的地方：

● 访问模式。 系统独占设备，比如鼠标、键盘等，应将此参数设置为0，否则后续函数的操作将失败。也就是说，对独占设备只能进行查询操作，所以可使用的函数有限。

● 文件属性。此参数用来设置同步或异步模式，它主要是对后续的WriteFile()和ReadFile()有影响。此参数为0时，代表同步模式，也即数据处理完成之后才返回，否则阻塞在函数内部。

CreateFile在创建时，一个重要的参数就是dwFlagsAndAttributes是否含有FILE_FLAG_OVERLAPPED标识，表示是否为异步操作。这里的异步操作将会影响到后续ReadFile,WriteFile最后一个参数。如果没有对应起来，调用ReadFile,WriteFile使用GetLastError()将返回参数错误。

ReadFile()

BOOL ReadFile(
  HANDLE hFile,        //设备句柄，可通过CreateFile得到
  LPVOID lpBuffer,     //存储数据的缓冲区
  DWORD nNumberOfBytesToRead,   //要读取的数据长度
  LPDWORD lpNumberOfBytesRead,  //实际收到的数据长度
  LPOVERLAPPED lpOverlapped      //OVERLAPPED结构体指针
);

ReadFile()用于读取设备通过中断IN传输发来的输入报告，读取的数据从中断输入管道传入。其读取的数据是从HID设备驱动的缓冲区中得到的，缓冲区的大小，可通过HidD _ SetNumInputBuffers()来改变。

ReadFile()的入口参数nNumberOfBytesToRead代表要读取数据的长度（数据正文+1字节报告ID）。当然，在实际设计中，HID设备是由我们自己设计的，我们是知道设备固件的信息的。

上位机也可通过HidD _ GetPreparsedData()来取得报告的长度。此参数设置过大，不会有错误产生，上位机将受到实际读到的长度；此参数设置过小，也即小于数据长度，会返回错误。

WriteFile()

BOOL WriteFile(
  HANDLE hFile,             //设备句柄，可通过CreateFile得到
  LPCVOID lpBuffer,         //要发送的buffer（指针）
  DWORD nNumberOfBytesToWrite,   //要发送数据的长度
  LPDWORD lpNumberOfBytesWritten,   //实际发送数据的长度
  LPOVERLAPPED lpOverlapped  //OVERLAPPED结构体指针，如果设备是以
//FILE_FLAG_OVERLAPPED方式打开的话，那么这个指针就不能为NULL
);

WriteFile()通过中断OUT得到来自设备的数据，其入口参数lpBuffer的第一个元素为待发送的报告ID，而且此报告ID必须是Output Report，否则会返回错误。

HidD_GetInputReport()和HidD_SetOutputReport()

BOOLEAN HidD_GetInputReport(
  HANDLE HidDeviceObject,     //设备句柄
  PVOID  ReportBuffer,        //存储数据的缓冲区
  ULONG  ReportBufferLength  //缓冲区长度
);
BOOLEAN HidD_SetOutputReport(
  HANDLE HidDeviceObject,    //设备句柄
  PVOID  ReportBuffer,       //存有待发送数据的缓冲区
  ULONG  ReportBufferLength //缓冲区长度
);

这两个函数通过Input Report和Output Report进行数据传输。主要在其它们的入口参数中，缓冲区的数据，第一个元素为Report ID，后面跟着的才是数据正文。

在固件程序中，这两个函数对应的类命令为Get Report和Set Report。

HidD_SetFeature()和HidD_GetFeature()

BOOLEAN HidD_GetFeature(
  HANDLE HidDeviceObject,     //设备句柄
  PVOID  ReportBuffer,        //存储数据的缓冲区
  ULONG  ReportBufferLength  //缓冲区长度
);
BOOLEAN HidD_SetFeature(
  HANDLE HidDeviceObject,    //设备句柄
  PVOID  ReportBuffer,       //存有待发送数据的缓冲区
  ULONG  ReportBufferLength //缓冲区长度
);

与介绍的两个函数类似，不过这两个函数是通过Feature Report进行数据传输的。在固件程序中，对应的类命令也是Get Report和Set Report。

其它相关

当然，如果自己使用API嫌麻烦的话，也可以使用GIThub上已经封装好的HidApi库来进行开发，下载地址是https://github.com/yigityuce/HidApi