Chris Cant - Writing Windows WDM Device Drivers

Listing 23.1 Getting a HID device's capabilities

bool GetCapabilities(HANDLE hHidKbd, PHIDP_PREPARSED_DATA& HidPreparsedData, USHORT& InputReportLen, USHORT& OutputReportLen) {

// Get attributes, i.e. find vendor and product ids

HIDD_ATTRIBUTES HidAttributes;

if (!HidD_GetAttributes(hHidKbd, &HidAttributes)) {

printf("XXX Could not get HID attributes\n");

return false;

}

printf("HID attributes: VendorID=%04X, ProductID=%04X, VersionNumber=%04X\n",

HidAttributes.VendorID, HidAttributes.ProductID, HidAttributes.VersionNumber);

// Get preparsed data

if (!HidD_GetPreparsedData( hHidKbd, &HidPreparsedData)) {

printf("XXX Could not get HID preparsed data\n");

return false;

}

// Work out capabilities

HIDP_CAPS HidCaps;

bool found = false;

NTSTATUS status = HidP_GetCaps(HidPreparsedData, &HidCaps);

if (status==HIDP_STATUS_SUCCESS) {

printf("Top level Usage page %d usage %d\n", HidCaps.UsagePage, HidCaps.Usage);

if (HidCaps.UsagePage==HID_USAGE_PAGE_GENERIC && HidCaps.Usage==HD_USAGE_GENERIC_KEYBOARD) {

printf(" Found HID keyboard\n\n");

found = true;

}

// Remember max lengths of input and output reports

InputReportLen = HidCaps.InputReportByteLength;

OutputReportLen = HidCaps.OutputReportByteLength;

printf("InputReportByteLength %d\n", HidCaps.InputReportByteLength);

printf("OutputReportByteLength %d\n", HidCaps.OutputReportByteLength);

printf("FeatureReportByteLength %d\n\n", HidCaps.FeatureReportByteLength);

printf("NumberLinkCollectionNodes %d\n\n", HidCaps.NumberLinkCollectionNodes);

printf("NumberInputButtonCaps %d\n", HidCaps.NumberInputButtonCaps);

printf("NumberInputValueCaps %d\n", HidCaps.NumberInputValueCaps);

printf("NumberOutputButtonCaps %d\n", HidCaps.NumberOutputButtonCaps);

printf("NumberOutputValueCaps %d\n", HidCaps.NumberOutputValueCaps);

printf("NumberFeatureButtonCaps %d\n", HidCaps.NumberFeatureButtonCaps);

printf("NumberFeatureValueCaps %d\n\n", HidCaps.NumberFeatureValueCaps);

ShowButtonCaps("Input button capabilities", HidP_Input, HidCaps.NumberInputButtonCaps, HidPreparsedData);

ShowButtonCaps("Output button capabilities", HidP_Output, HidCaps.NumberOutputButtonCaps, HidPreparsedData);

}

return found;

}

Why Get Button and Value Capabilities?

Some programs cannot just rely on the HIDP_CAPS UsagePage and Usage fields. For example, in the future, some fancy device may use these fields to say that it is a "speech interface". A "speech interface" might still be able to generate key presses (e.g., when a user says a word). Its detailed capabilities would show that it could indeed present data that is of interest.

Each control in a HID device is seen by Windows as being either a button or a value. Anything that has a HID usage is defined as being a button. Controls that take on any other values are called values.

Each of the keys on a keyboard has a HID usage. All keyboard keys are in usage page 7. Within that usage page, most of the usages from 0 to 255 have key definitions. However, most Western keyboards produce usage codes in two ranges. Usages 0 to 101 contain most standard keys, while usages 224 to 231 represent the modifier keys such as Shift, Ctrl, Alt, etc. To be extra careful, check that the HID device generates usages in these two ranges.

Similarly to double check that the HID device has the correct LEDs check that its output report contains buttons in usage page 8, for LEDs. Within this usage page, usage 1 corresponds to NumLock, usage 2 with CapsLock, and usage 3 with ScrollLock.

Getting Button Capabilities

The HIDP_CAPS structure has fields that tell you how many button and value capabilities there are for each type of report. For example, NumberInputButtonCaps tells you how many button capabilities there are for input reports.

GetCapabilities uses the ShowButtonCaps routine shown in Listing 23.2 to show what button capabilities there are for different types of report. The NumCaps parameter is passed the number of button capabilities that are expected for the specified type of report.

ShowButtonCaps first allocates an array of HIDP_BUTTON_CAPS structures called ButtonCaps. The call to HidP_GetButtonCaps fills in this array. Afterwards, ShowButtonCaps simply goes through each element in ButtonCaps and prints out the usages that can be returned. The HIDP_BUTTON_CAPS UsagePage field gives the usage page of all the buttons referred to in this structure. ReportId specifies the report in which these buttons are. If the IsRange BOOLEAN is TRUE, the Range.UsageMin and Range.UsageMax fields are valid. Otherwise, the Not Range. Usage field holds the only valid usage.

Each HIDP_BUTTON_CAPS structure has similar fields for the string descriptors and physical designators associated with controls. Finally, various link fields specify in which collection the buttons are. See the previous chapter for a description of collections.

Listing 23.2 Getting buttons capabilities

void ShowButtonCaps(char* Msg, HIDP_REPORT_TYPE ReportType, USHORT NumCaps, PHIDP_PREPARSED_DATA HidPreparsedData) {

if (NumCaps==0) return;

printf(" %s\n", Msg);

HIDP_BUTTON_CAPS* ButtonCaps = new HIDP_BUTTON_CAPS[NumCaps];

if( ButtonCaps==NULL) return;

NTSTATUS status = HidP_GetButtonCaps(ReportType, ButtonCaps, &NumCaps, HidPreparsedData);

if (status==HIDP_STATUS_SUCCESS) {

for (USHORT i=0; i

printf("ButtonCaps[%d].UsagePage %d\n", i, ButtonCaps[i].UsagePage);

if (ButtonCaps[i].IsRange) printf(".Usages %d..%d\n\n", ButtonCaps[i].Range.UsageMin, ButtonCaps[i].Range.UsageMax);

else printf(".Usage %d\n\n", ButtonCaps[i].NotRange.Usage);

}

}

delete ButtonCaps;

}

Here is an excerpt from the output produced by the ShowButtonCaps routine. It confirms that, in this case, the HID device has the desired controls. It could be fairly laborious if you had to check that all the right buttons were available, as the button capabilities could arrive in any order.

Input button capabilities

ButtonCaps[0].UsagePage 7

.Usages 224..231

ButtonCaps[1].UsagePage 7

.Usages 0..101

Output button capabilities

ButtonCaps[0].UsagePage 8

.Usages 1..3

Use HidP_GetSpecificButtonCaps if you need to look for buttons in a different collection or search for a controls with a specific usage page or usage. This might be a better way of determining whether the controls you are interested in are supported.

Getting Value Capabilities

You can retrieve details of what control values are supported in a very similar way. Use HidP_GetValueCaps to get a list of all values in the top-level collection. Alternatively, HidP_GetSpecificValueCaps is used to look for values in a different collection, or search for controls with a specific usage page or usage. The information is stored in an array of HIDP_VALUE_CAPS structures.