Sending Output Reports
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.
The SetLEDs function shown in Listing 23.5 shows how a single output report is sent to set the state of the HID keyboard LEDs. It has three optional parameters, which must contain the individual LED usages that you want set on. This line in the HidUsbUser main routine shows how to turn the ScrollLock LED on and turn the other LEDs off.
SetLEDs(hHidKbd, OutputReportLen, HidPreparsedData, HID_USAGE_LED_SCROLL_LOCK);
A keyboard output report consists of just one byte. However, as before, the output buffer must have an extra byte at the beginning for the report ID. This is set to zero in this case, as keyboards do not use report IDs. SetLEDs allocates an output buffer and zeroes it.
SetLEDs must now build an array of USAGEs, filled with any of its optional parameters that are non-zero. This array and its length are passed to HidP_SetButtons. HidP_SetButtons builds the output buffer in the correct format. SetLEDs then simply calls WriteFile to send off the output report.
You can call HidP_SetButtons more than once for a single output report. Indeed, you may also want to call one of the set value functions, if the output report must contain values. Set values into an output report using the HidP_SetUsageValue, HidP_SetScaledUsageValue, and HidP_SetUsageValueArray functions.
Be careful if you are using a HID device that has more than one output report. HidP_SetButtons can only build one output report at a time. HidP_SetButtons sets the report ID, if appropriate. If a second call to HidP_SetButtons tries to set a usage that is not in the first report, it fails with a suitable error code. However, if you start afresh with a new output report and repeat the second call to HidP_SetButtons, it should work this time. This whole process makes it particularly laborious to set output usages in a way that is truly independent of the device that is attached.
Listing 23.5 Setting keyboard LEDs using an output HID report
void SetLEDs(HANDLE hHidKbd, USHORT OutputReportLen, PHIDP_PREPARSED_DATA HidPreparsedData,
USAGE Usage1/*=0*/, USAGE Usage2/*=0*/, USAGE Usage3/*=0*/) {
// Build Output report from given usage(s)
char* OutputReport = new char[OutputReportLen];
assert(OutputReport!=NULL);
memset(OutputReport, 0, OutputReportLen);
USAGE UsageList[3];
UsageList[0] = Usage1;
UsageList[1] = Usage2;
UsageList[2] = Usage3;
ULONG UsageLength = 0;
if (Usage1!=0) {
UsageLength++;
if (Usage2!=0) {
UsageLength++;
if (Usage3!=0) {
UsageLength++;
}
}
}
// Convert usages into an output report
NTSTATUS status = HidP_SetButtons(HidP_Output, HID_USAGE_PAGE_LED, 0, UsageList, &UsageLength, HidPreparsedData, OutputReport, OutputReportLen);
if (status!=HIDP_STATUS_SUCCESS) {
delete OutputReport;
return;
}
printf(" Output report: ");
for (ULONG i=1; i
printf("\n");
// Send off output report
DWORD TxdBytes;
if (!WriteFile(hHidKbd, OutputReport, OutputReportLen, &TxdBytes, NULL))
printf("XXX Could not write value %d\n", GetLastError());
else if (TxdBytes==OutputReportLen) printf(" Wrote output report 0K\n");
else printf("XXX Wrong number of bytes written: %d\n",TxdBytes);
delete OutputReport;
}