Chris Cant - Writing Windows WDM Device Drivers

Getting Collection Capabilities

The HidP_GetLinkCollectionNodes function is used to obtain details of all the collections in a top-level collection. It fills in an array of HIDP_LINK_COLLECTION_NODE structures. See the DDK for full details of how this array specifies the arrangement of collections within the top-level collection.

Reading input reports from a HID device is straightforward. Listing 23.3 shows how this is done in the HidUsbUser main routine. It keeps reading input reports until the Esc key is pressed on the HID keyboard. See Listing 23.6 for some example output from this routine.

First, allocate and zero a buffer to receive a report, with the size given in the HIDP_CAPS structure. A keyboard input report is always eight bytes long. However, the InputReportByteLength field in HIDP_CAPS is one longer than this, as the first byte is used to indicate the report ID. For keyboard reports, this first byte will be zero, as report IDs are not used.

Use ReadFile to read the next available input report. If the device can return two different input reports then this call may obtain either of them. Suppose these two reports have different lengths. For the smaller input report, the returned count of bytes transferred will be less than the buffer size you passed.

Listing 23.3 Reading keyboard input reports

DWORD TxdBytes;

char* InputReport = new char[InputReportLen];

assert(InputReport!=NULL);

// Loop until Esc pressed on keyboard

do {

if (!ReadFile( hHidKbd, InputReport, InputReportLen, &TxdBytes, NULL)) {

printf("XXX Could not read value %d\n", GetLastError());

break;

} else if (TxdBytes==InputReportLen) {

printf(" Input report %d:", InputReport[0]);

for(USHORT i=1; i

printf("\n");

DecodeInputUsages(InputReport, InputReportLen, HidPreparsedData);

} else {

printf("XXX Wrong number of bytes read: %d\n", TxdBytes);

break;

}

} while (InputReport[3]!=0x29);

delete InputReport;

What Buttons Were Set in My Report?

You could just look directly at the received buffer and work out what it means. However, the correct HID way to analyze reports is get the HID parsing routines to tell you what usages were set in the report. DecodeInputUsages, shown in Listing 23.4, does just this job. Indeed, it goes further by telling you what changes have occurred since the last input report. It prints out the usages that have just been "made" and the ones have just been "broken".

The HidP_GetButtonsEx function analyses an input report buffer and reports which button usages were set in the report. The output is an array of USAGE_AND_PAGE structures (i.e., usage page and usage values).

DecodeInputUsages must first find out the maximum size for this output array using HidP_MaxUsageListLength , so that a suitably sized array can be allocated. Actually, DecodeInputUsages cheats, as I know the maximum size in advance. I use the MaxPreviousUsages constant to declare fixed-size arrays; this avoids allocating and freeing buffers all over the place.

The maximum usage list length for a keyboard report is 14. This is made up of the six keys that the HID Report descriptor says can be pressed simultaneously, and the eight modifier keys, again that the Report descriptor says can be pressed simultaneously. Obviously, it is extremely unlikely that 14 keys can be pressed at the same time.

HidP_GetButtonsEx analyses the input report just received and fills in the array of USAGE_AND_PAGE structures, called Usages. The ValidUsages variable is filled with the number of valid elements in this array. DecodeInputUsages simply prints out the usage page and usage for each of these valid key presses.

The next job, if desired, is to work out what has changed since the last input report. The HidP_UsageListDifference function does this. It is passed the previous usage list and the current usage list as input. It fills in two further arrays, one with a list of usages that have been "made" (or just arrived), and one with a list of usages that have just "broken" (or gone away). DecodeInputUsages prints out these two arrays. Note that HidP_UsageListDifference deals with arrays of USAGE values, not USAGE_AND_PAGEs. In DecodeInputUsages all the input usages are in the keyboard usage page, so this is not a problem.

Listing 23.4 Decoding input report usages

const ULONG MaxPreviousUsages = 14;

USAGE_AND_PAGE Usages[MaxPreviousUsages];

USAGE PreviousUsages[MaxPreviousUsages];

void DecodeInputUsages(char* KbdReport, USHORT KbdReportLen, PHIDP_PREPARSED_DATA HidPreparsedData) {

// Get max number of USAGE_ANQ_PAGEs required for all input reports in

// top-level collection

ULONG MaxUsages = HidP_MaxUsageListLength(HidP_Input, 0, HidPreparsedData);

if (MaxUsages==0 || MaxUsages>MaxPreviousUsages) {

printf("XXX Invalid HidP_MaxUsageListLength returned %d\n", MaxUsages);

return;

}

// Get usages set in given keyboard report

ULONG ValidUsages = MaxUsages;

NTSTATUS status = HidP_GetButtonsEx(HidP_Input, 0, Usages, &ValidUsages, HidPreparsedData, KbdReport, KbdReportLen);

if (status==HIDP_STATUS_SUCCESS) {

USAGE CurrentUsages[MaxPreviousUsages];

USAGE BreakUsages[MaxPreviousUsages];

USAGE MakeUsages[MaxPreviousUsages];

// Show current usages

memset(CurrentUsages, 0, sizeof(CurrentUsages));

printf(" Usages set: ");

for (ULONG i=0; i

printf( " %02X:%02X", Usages[i].UsagePage, Usages[i].Usage);

CurrentUsages[i] = Usages[i].Usage;

}

// Work out differences compared to previous usages

HidP_UsageListDifference(PreviousUsages, CurrentUsages, BreakUsages, MakeUsages, MaxUsages);

// Print out usages broken and made

printf(" (Break: ");

for (i=0; i

if (BreakUsages[i]==0) break;

printf(" %02X", BreakUsages[i]);

}

printf(") (Make: ");

for(i=0; i

if (MakeUsages[i]==0) break;

printf(" %02X", MakeUsages[i]);

}

printf(")\n\n");

// Save previous usages

memcpy(PreviousUsages, CurrentUsages, MaxUsages*sizeof(USAGE));

}

}

The HidP_GetButtons function can be used if you are only looking for buttons in a particular usage page. Both HidP_GetButtons and HidP_GetButtonsEx have parameters that let you look for buttons in a particular collection.

What Values Were Set in My Report?

Use the HidP_GetUsageValue, HidP_GetScaledUsageValue , or HidP_GetUsageValueArray functions to retrieve control values.

You send HID output reports using the Win32 WriteFile function. While you can build the output buffer by hand, it is safer to use the HID parsing routines to fill in the buffer.