In addition to storing the basic HID structures as defined in HIDPI.H and HIDSDI.H, the HID_DEVICE structure also maintains an array of HID_DATA structures for each report type. These structures contain the most recent value used for each of the controls defined in the HIDP_VALUE_CAPS list and HIDP_BUTTON_CAPS list for the given report type. The fields within this structure are used by routines that pack/unpack data reports. The usage of these fields is discussed further in the section entitled Building/Interpreting HID Reports.

The function OpenHidDevice() in PNP.C performs the necessary steps to fill a HID_DEVICE structure for a device. In order to do so, it performs the following steps:

• Call CreateFile() – Open a handle to the specific HID device. In this case, we request read/write access to the device, allow the device to be shared, and synchronize access to the device handle (no OVERLAPPED flag).
• Call HidD_GetPreparsedData() – Get the preparsed data for the device. The preparsed data is a HID parser specific block of data used for processing HID reports. The memory for this structure is allocated by the HID.DLL function and must be freed when no longer needed with HidD_FreePreparsedData().
• Call HidD_GetAttributes() – Get the attributes of the device. The attributes structure contains the vendor ID, product ID and version number of the given HID device
• Call HidD_GetCaps() – Get the capabilities of the device. The device capabilities include the usage page and usage of the device, the required buffer length for the different reports on the device, the number of link collection nodes on the device and a count of the number of buttons and values for each of the different report types.
• Call FillDeviceInfo() – Fill in the rest of the HID_DEVICE structure. This function allocates space for and retrieves the link collection nodes, the value caps, and the button caps for the device.

A given client application may not need to perform all of the above steps. For instance, if a client application only operates with a specific HID device (ie. vendor ID/product ID), it may forego any more processing after retrieving the attributes if the device it is currently opening is not the one it’s interested in.

A client application may also work only for a given usage page/usage combination. For example, a monitor control application would only need to open devices that match the monitor usage page and usage combination.

Lastly, a HID client may require only a subset of the detailed information currently stored in the HID_DEVICE structure. This sample application performs a broad range of functionality to provide a detailed sample.

Communicating with HID Devices

As mentioned above, a HID device’s basic method of communication is through reports. A HID device can contain as many as 255 reports for each report type (Input, Output, and Feature). In order to properly communicate with a device, a client application must be able to create reports (when sending data) or extract data from reports (when receiving data). See the section titled: Building/Interpreting HID Reports for information on how to manipulate these report buffers.

A HID device reports information to the host through Input reports or Feature Reports. Typically, input reports contain the data generated by user interaction, such as a button press. Feature reports, on the other hand, report the current state or settings for a device. The methods for obtaining these two different reports are implemented in the functions Read() and GetFeature() in REPORT.C.

In order to receive data, HClient must use the file handle created in OpenHidDevice that has READ access and the buffer allocated for the given report type. For input reports, Read() calls the Win32 API ReadFile() and waits for the device to return a report. For feature reports, GetFeature() sets the first byte of the report buffer to the desired report ID and calls HidD_GetFeature() to obtain that feature report. After receiving a report back from the underlying drivers, these routines call UnpackReport() to fill in the corresponding HID_DATA structures.

Outputting data to a device is a bit more complicated. Once again, there are two different types of reports that can be sent to a device, Output and Feature. The corresponding functions for outputting data are Write() and SetFeature() in REPORT.C.

The first step that both of these functions perform is creating the desired report buffer. First, the HID_DATA structure with the desired report ID value is found. Then, these functions call PackReport() to set the data values within the allocated report buffer for that report ID. Once the report buffer has been created, either WriteFile() or HidD_SetFeature() is called to send the report packet to the device.

It is important to understand that all access to a HID device file handle is synchronized. Therefore, all threads using that handle will block until all previous requests to the device have completed. One possible client implementation would have one thread continuously read input reports while another thread sends or receives feature reports. Since the HidD_GetFeature() and HidD_SetFeature functions are implemented as DeviceIoControl calls, they are also synchronized with ReadFile and WriteFile(). There are two solutions to this scenario. One solutions uses overlapped I/O for asynchronous control. The second is to open two handles for the device, one for the read thread and one for the feature thread.

Building/Interpreting HID Reports

The last important idea when dealing with reports is extracting/setting data values from/in a given report buffer. The section covers the details of the functions PackReport() and UnpackReport() as implemented in REPORT.C.

As mentioned above, in order to communicate with a HID device, the client application must be able to either create the appropriate report to send to the device or extract the relevant information from a report received from the device. When Hclient initially opened the HID device and created the HID_DEVICE structure for that device, it also created an array of HID_DATA structures for each of the report types. The format of this HID_DATA structure is as follows:

 typedef struct _HID_DATA {
   BOOLEAN     IsButtonData;
   UCHAR       Reserved;
   USAGE       UsagePage;   // The usage page for which we are looking.
   ULONG       Status;      // The last status returned from the accessor function
                            // when updating this field.
   ULONG       ReportID;    // ReportID for this given data structure
   BOOLEAN     IsDataSet;   // Variable to track whether a given data structure
                            //  has already been added to a report structure

   union {
      struct {
         ULONG       UsageMin;       // Variables to track the usage minimum and max
         ULONG       UsageMax;       // If equal, then only a single usage
         ULONG       MaxUsageLength; // Usages buffer length.
         PUSAGE      Usages;         // list of usages (buttons ``down'' on the device.

      } ButtonData;
      struct {
         USAGE       Usage; // The usage describing this value;
         USHORT      Reserved;

         ULONG       Value;
         LONG        ScaledValue;
      } ValueData;
   };
} HID_DATA, *PHID_DATA;