Return to Unit Reference
Description
Ultibo USB Keyboard Driver unit
USB Keyboard Devices
The USB keyboard driver in this unit uses HID Boot Protocol only and has been replaced by the HIDKeyboard unit which provides complete HID Report Protocol support for USB keyboards. It is retained here for legacy uses and backwards compatibility only.
To use this driver in place of the default HID Keyboard driver set the following configuration variables in your application during system initialization.
HID_REGISTER_KEYBOARD := False;
USB_KEYBOARD_REGISTER_DRIVER := True;
This driver does not recognize devices that do not report themselves as boot keyboards.
Constants
[Expand]
USB keyboard specific constants NAME_*
USBKEYBOARD_DRIVER_NAME = 'USB Keyboard Driver (HID boot protocol)';
|
Name of USB keyboard driver
|
USBKEYBOARD_KEYBOARD_DESCRIPTION = 'USB HID Keyboard';
|
Description of USB keyboard device
|
[Expand]
USB HID interface subclass USB_HID_SUBCLASS_*
| See USB HID v1.11 specification
|
|
|
USB_HID_SUBCLASS_NONE = 0;
|
Section 4.2
|
USB_HID_SUBCLASS_BOOT = 1;
|
Section 4.2
|
[Expand]
USB HID interface protocol USB_HID_BOOT_PROTOCOL_*
| See USB HID v1.11 specification
|
|
|
USB_HID_BOOT_PROTOCOL_NONE = 0;
|
Section 4.3
|
USB_HID_BOOT_PROTOCOL_KEYBOARD = 1;
|
Section 4.3
|
USB_HID_BOOT_PROTOCOL_MOUSE = 2;
|
Section 4.3
|
[Expand]
USB HID class descriptor USB_HID_DESCRIPTOR_*
| See USB HID v1.11 specification
|
|
|
USB_HID_DESCRIPTOR_TYPE_HID = $21;
|
Section 7.1
|
USB_HID_DESCRIPTOR_TYPE_REPORT = $22;
|
Section 7.1
|
USB_HID_DESCRIPTOR_TYPE_PHYSICAL_DESCRIPTOR = $23;
|
Section 7.1
|
[Expand]
USB HID request USB_HID_REQUEST_*
| See USB HID v1.11 specification
|
|
|
USB_HID_REQUEST_GET_REPORT = $01;
|
Section 7.2
|
USB_HID_REQUEST_GET_IDLE = $02;
|
Section 7.2
|
USB_HID_REQUEST_GET_PROTOCOL = $03;
|
Section 7.2
|
USB_HID_REQUEST_SET_REPORT = $09;
|
Section 7.2
|
USB_HID_REQUEST_SET_IDLE = $0A;
|
Section 7.2
|
USB_HID_REQUEST_SET_PROTOCOL = $0B;
|
Section 7.2
|
[Expand]
USB HID protocol USB_HID_PROTOCOL_*
| See USB HID v1.11 specification
|
|
|
USB_HID_PROTOCOL_BOOT = 0;
|
Section 7.2.5
|
USB_HID_PROTOCOL_REPORT = 1;
|
Section 7.2.5
|
[Expand]
USB HID report USB_HID_REPORT_*
| See USB HID v1.11 specification
|
|
|
USB_HID_REPORT_INPUT = 1;
|
Section 7.2.1
|
USB_HID_REPORT_OUTPUT = 2;
|
Section 7.2.1
|
USB_HID_REPORT_FEATURE = 3;
|
Section 7.2.1
|
[Expand]
USB HID report Ids USB_HID_REPORTID_*
| See USB HID v1.11 specification
|
|
|
USB_HID_REPORTID_NONE = 0;
|
Section 7.2.1
|
[Expand]
USB HID boot protocol USB_HID_BOOT_LEFT_*, USB_HID_BOOT_RIGHT_*
USB_HID_BOOT_LEFT_CTRL = (1 shl 0);
|
|
USB_HID_BOOT_LEFT_SHIFT = (1 shl 1);
|
|
USB_HID_BOOT_LEFT_ALT = (1 shl 2);
|
|
USB_HID_BOOT_LEFT_GUI = (1 shl 3);
|
|
USB_HID_BOOT_RIGHT_CTRL = (1 shl 4);
|
|
USB_HID_BOOT_RIGHT_SHIFT = (1 shl 5);
|
|
USB_HID_BOOT_RIGHT_ALT = (1 shl 6);
|
|
USB_HID_BOOT_RIGHT_GUI = (1 shl 7);
|
|
[Expand]
USB HID boot protocol report data USB_HID_BOOT_REPORT_*
USB_HID_BOOT_REPORT_SIZE = 8;
|
Appendix B of HID Device Class Definition 1.11
|
[Expand]
USB HID boot protocol output USB_HID_BOOT_*_LED
USB_HID_BOOT_NUMLOCK_LED = (1 shl 0);
|
|
USB_HID_BOOT_CAPSLOCK_LED = (1 shl 1);
|
|
USB_HID_BOOT_SCROLLLOCK_LED = (1 shl 2);
|
|
USB_HID_BOOT_COMPOSE_LED = (1 shl 3);
|
|
USB_HID_BOOT_KANA_LED = (1 shl 4);
|
|
|
|
USB_HID_BOOT_LEDMASK = USB_HID_BOOT_NUMLOCK_LED or USB_HID_BOOT_CAPSLOCK_LED or USB_HID_BOOT_SCROLLLOCK_LED or USB_HID_BOOT_COMPOSE_LED or USB_HID_BOOT_KANA_LED;
|
|
[Expand]
USB HID boot protocol output data USB_HID_BOOT_OUTPUT_*
USB_HID_BOOT_OUTPUT_SIZE = 1;
|
Appendix B of HID Device Class Definition 1.11
|
|
|
USB_HID_BOOT_USAGE_NUMLOCK = SCAN_CODE_NUMLOCK;
|
83
|
USB_HID_BOOT_USAGE_CAPSLOCK = SCAN_CODE_CAPSLOCK;
|
57
|
USB_HID_BOOT_USAGE_SCROLLLOCK = SCAN_CODE_SCROLLLOCK;
|
71
|
Type definitions
USB HID descriptor
[Expand]
PUSBHIDDescriptor = ^TUSBHIDDescriptor;
TUSBHIDDescriptor = packed record
bLength:Byte;
|
|
bDescriptorType:Byte;
|
|
bcdHID:Word;
|
|
bCountryCode:Byte;
|
|
bNumDescriptors:Byte;
|
|
bHIDDescriptorType:Byte;
|
|
wHIDDescriptorLength:Word;
|
|
| Note: Up to two optional bHIDDescriptorType/wHIDDescriptorLength pairs after the Report descriptor details
|
USB boot keyboard report
[Expand]
PUSBKeyboardReport = ^TUSBKeyboardReport;
TUSBKeyboardReport = array[0..7] of Byte;
USB keyboard device
[Expand]
PUSBKeyboardDevice = ^TUSBKeyboardDevice;
TUSBKeyboardDevice = record
| Keyboard Properties
|
Keyboard:TKeyboardDevice;
|
|
| USB Properties
|
HIDInterface:PUSBInterface;
|
USB HID Keyboard Interface
|
ReportRequest:PUSBRequest;
|
USB request for keyboard report data
|
ReportEndpoint:PUSBEndpointDescriptor;
|
USB Keyboard Interrupt IN Endpoint
|
HIDDescriptor:PUSBHIDDescriptor;
|
USB HID Descriptor for keyboard
|
ReportDescriptor:Pointer;
|
USB HID Report Descriptor for keyboard
|
LastCode:Word;
|
The scan code of the last key pressed
|
LastCount:LongWord;
|
The repeat count of the last key pressed
|
LastReport:TUSBKeyboardReport;
|
The last keyboard report received
|
PendingCount:LongWord;
|
Number of USB requests pending for this keyboard
|
WaiterThread:TThreadId;
|
Thread waiting for pending requests to complete (for keyboard detachment)
|
Public variables
None defined
Function declarations
Initialization functions
[Expand]
procedure USBKeyboardInit;
Description: Initialize the USB keyboard driver
| Note
|
Called only during system startup
|
USB keyboard functions
[Expand]
function USBKeyboardDeviceRead(Keyboard:PKeyboardDevice; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Implementation of KeyboardDeviceRead API for USB Keyboard
| Note
|
Not intended to be called directly by applications, use KeyboardDeviceRead instead.
|
[Expand]
function USBKeyboardDeviceControl(Keyboard:PKeyboardDevice; Request:Integer; Argument1:PtrUInt; var Argument2:PtrUInt):LongWord;
Description: Implementation of KeyboardDeviceControl API for USB Keyboard
| Note
|
Not intended to be called directly by applications, use KeyboardDeviceControl instead.
|
[Expand]
function USBKeyboardDriverBind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Bind the Keyboard driver to a USB device if it is suitable
| Device
|
The USB device to attempt to bind to
|
| Interrface
|
The USB interface to attempt to bind to (or nil for whole device)
|
| Return
|
USB_STATUS_SUCCESS if completed, USB_STATUS_DEVICE_UNSUPPORTED if unsupported or another error code on failure
|
[Expand]
function USBKeyboardDriverUnbind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Unbind the Keyboard driver from a USB device
| Device
|
The USB device to unbind from
|
| Interrface
|
The USB interface to unbind from (or nil for whole device)
|
| Return
|
USB_STATUS_SUCCESS if completed or another error code on failure
|
[Expand]
procedure USBKeyboardReportWorker(Request:PUSBRequest);
Description: Called (by a Worker thread) to process a completed USB request from a USB keyboard IN interrupt endpoint
| Request
|
The USB request which has completed
|
[Expand]
procedure USBKeyboardReportComplete(Request:PUSBRequest);
Description: Called when a USB request from a USB keyboard IN interrupt endpoint completes
| Request
|
The USB request which has completed
|
| Note
|
Request is passed to worker thread for processing to prevent blocking the USB completion
|
USB helper functions
[Expand]
function USBKeyboardCheckDevice(Device:PUSBDevice):Boolean;
Description: Check if the supplied USB device is suitable for detection as a HID Keyboard Device
| Device
|
The USB device to check
|
| Return
|
True if the device is suitable or False if it is not
|
[Expand]
function USBKeyboardCheckPressed(Keyboard:PUSBKeyboardDevice; ScanCode:Byte):Boolean;
Description: Check if the passed scan code has been pressed (True if not pressed in last report)
| Keyboard
|
The USB keyboard device to check for
|
| ScanCode
|
The keyboard scan code to check
|
| Note
|
Caller must hold the keyboard lock
|
[Expand]
function USBKeyboardCheckRepeated(Keyboard:PUSBKeyboardDevice; ScanCode:Byte):Boolean;
Description: Check if the passed scan code was the last key pressed and if the repeat delay has expired
| Keyboard
|
The USB keyboard device to check for
|
| ScanCode
|
The keyboard scan code to check
|
| Note
|
Caller must hold the keyboard lock
|
[Expand]
function USBKeyboardCheckReleased(Keyboard:PUSBKeyboardDevice; Report:PUSBKeyboardReport; ScanCode:Byte):Boolean;
Description: Check if the passed scan code has been released (True if not pressed in current report)
| Keyboard
|
The USB keyboard device to check for
|
| Report
|
The USB keyboard report to compare against (Current)
|
| ScanCode
|
The keyboard scan code to check
|
| Note
|
Caller must hold the keyboard lock
|
[Expand]
function USBKeyboardDeviceSetLEDs(Keyboard:PUSBKeyboardDevice; LEDs:Byte):LongWord;
Description: Set the state of the LEDs for a USB keyboard device
| Keyboard
|
The USB keyboard device to set the LEDs for
|
| LEDs
|
The LED state to set (eg KEYBOARD_LED_NUMLOCK)
|
| Return
|
USB_STATUS_SUCCESS if completed or another USB error code on failure
|
[Expand]
function USBKeyboardDeviceSetIdle(Keyboard:PUSBKeyboardDevice; Duration,ReportId:Byte):LongWord;
Description: Set the idle duration (Time between reports when no changes) for a USB keyboard device
| Keyboard
|
The USB keyboard device to set the idle duration for
|
| Duration
|
The idle duration to set (Milliseconds divided by 4)
|
| ReportId
|
The report Id to set the idle duration for (eg USB_HID_REPORTID_NONE)
|
| Return
|
USB_STATUS_SUCCESS if completed or another USB error code on failure
|
[Expand]
function USBKeyboardDeviceSetProtocol(Keyboard:PUSBKeyboardDevice; Protocol:Byte):LongWord;
Description: Set the report protocol for a USB keyboard device
| Keyboard
|
The USB keyboard device to set the report protocol for
|
| Protocol
|
The report protocol to set (eg USB_HID_PROTOCOL_BOOT)
|
| Return
|
USB_STATUS_SUCCESS if completed or another USB error code on failure
|
[Expand]
function USBKeyboardDeviceGetHIDDescriptor(Keyboard:PUSBKeyboardDevice; Descriptor:PUSBHIDDescriptor):LongWord;
Description: Get the HID Descriptor for a USB keyboard device
| Keyboard
|
The USB keyboard device to get the descriptor for
|
| Descriptor
|
Pointer to a USB HID Descriptor structure for the returned data
|
| Descriptor
|
USB_STATUS_SUCCESS if completed or another USB error code on failure
|
[Expand]
function USBKeyboardDeviceGetReportDescriptor(Keyboard:PUSBKeyboardDevice; Descriptor:Pointer; Size:LongWord):LongWord;
Description: Get the Report Descriptor for a USB keyboard device
| Keyboard
|
The USB keyboard device to get the descriptor for
|
| Descriptor
|
Pointer to a buffer to return the USB Report Descriptor
|
| Size
|
The size in bytes of the buffer pointed to by Descriptor
|
| Return
|
USB_STATUS_SUCCESS if completed or another USB error code on failure
|
Return to Unit Reference
