Re: [libusb] Windows HID API Clarifications

[Tim R. <ti...@pr...>]

Xiaofan Chen wrote:
>
> So you can see that HIDAPI is using ReadFile for the fetching of HID reports
> continuously with the hid_read API. And then it does not use HidD_GetXxx routines
> to obtain the most current input report and feature report, rather it
> uses IOCTLs to get the input report and feature report.
>
> https://github.com/libusb/hidapi/blob/master/windows/hid.c#L56
> #define IOCTL_HID_GET_FEATURE                         HID_OUT_CTL_CODE(100)
> #define IOCTL_HID_GET_INPUT_REPORT              HID_OUT_CTL_CODE(104)
>
> Historical reasons why Alan Ott chose to use DeviceIoControl() call and not HidD_GetXxx.
> https://github.com/libusb/hidapi/issues/229

The ioctls are equivalent to the HidD calls.  The HidD calls do almost 
nothing other than format and send a DeviceIoControl request.

There are essentially 8 ways to talk to a HID device.

GetFeature/SetFeature read and write feature reports.  These get an 
immediate response, and include a report ID byte (if the descriptor has 
multiple reports).

SetOutputReport/WriteReport/WriteFile all write output reports and do 
the same thing.  These all happen immediately and include a report ID byte.

GetInputReport gets an input report immediately, and includes a report 
ID byte in both directions.

ReadReport/ReadFile are the strange ones.  These are long term calls.  
This says "send me the next report that changes, whatever it may be."  
It will get queued up for later.  When it returns, the buffer will 
include a report ID, but you don't ask for one to begin with.


> So it seems to me that the Microsoft documentation may be a bit confusing to
> say the driver can use the two IOCTLs. Usually driver means kernel space in
> this context even though there are user mode drivers as well.

Well, sort of.  A HID driver lives in kernel space.  It is NOW possible 
to write a UMDF HID driver, but only because Microsoft created a 
kernel-mode shim driver that shuffles the requests out to UMDF.  The HID 
subsystem is really a kernel component.


> Now the question is the return data of the two IOCTLs (output buffer).  From what I read, I believe
> HIDAPI codes are wrong in both cases, as Microsoft documentation says that the first byte of
> the buffer is unchanged (report ID or 0 if no report ID).
> https://github.com/libusb/hidapi/blob/master/windows/hid.c#L933
> https://github.com/libusb/hidapi/blob/master/windows/hid.c#L884

This code is wrong.  The "bytes_returned" value from a HID driver 
definitely does include the report ID byte.  This happens to be fresh in 
my mind because I just finished writing a fake HID driver that had to 
deal with this.  I wonder if they did their testing on a faulty driver?

-- 

Tim Roberts, ti...@pr...
Providenza & Boekelheide, Inc.