Unit Keyboard

Return to Unit Reference

Description

---

Keyboard Devices

This unit provides both the Keyboard device interface and the generic USB HID keyboard driver. The keyboard unit also provides the STDIN interface for the Run Time Library (RTL).

USB Keyboard Devices

This driver currently uses HID Boot Protocol only and could be redesigned in future to use the HID Report Protocol instead to allow for greater language support etc.

Constants

---

To be documented

Type definitions

---

To be documented

Public variables

---

To be documented

Function declarations

---

Initialization functions

[Expand]

procedure KeyboardInit;

Description: Initialize the keyboard unit, device table and USB keyboard driver

Note	Called only during system startup

Keyboard functions

[Expand]

function KeyboardGet(var KeyCode:Word):LongWord;

Description: Get the first key code from the global keyboard buffer

KeyCode	The returned key code read from the buffer (eg KEY_CODE_A)
Return	ERROR_SUCCESS if completed or another error code on failure
Note	Key code is the value translated from the scan code using the current keymap it may not be a character code and it may include non printable characters. To translate a key code to a character call KeymapGetCharCode()

[Expand]

function KeyboardPeek:LongWord;

Description: Peek at the global keyboard buffer to see if any data packets are ready

Return	ERROR_SUCCESS if packets are ready, ERROR_NO_MORE_ITEMS if not or another error code on failure

[Expand]

function KeyboardRead(Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord; inline;

Description: Read keyboard data packets from the global keyboard buffer

Buffer	Pointer to a buffer to copy the keyboard data packets to
Size	The size of the buffer in bytes (Must be at least TKeyboardData or greater)
Count	The number of keyboard data packets copied to the buffer
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardReadEx(Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;

Description: Read keyboard data packets from the global keyboard buffer

Buffer	Pointer to a buffer to copy the keyboard data packets to
Size	TThe size of the buffer in bytes (Must be at least TKeyboardData or greater)
Flags	The flags to use for the read (eg KEYBOARD_FLAG_NON_BLOCK)
Count	The number of keyboard data packets copied to the buffer
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardPut(ScanCode,KeyCode:Word; Modifiers:LongWord):LongWord;

Description: Put a scan code and key code in the global keyboard buffer

ScanCode	The scan code to write to the buffer (eg SCAN_CODE_A)
KeyCode	The key code to write to the buffer (eg KEY_CODE_A)
Modifiers	The modifier keys to write to the buffer (eg KEYBOARD_LEFT_CTRL)
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardWrite(Buffer:Pointer; Size,Count:LongWord):LongWord;

Description: Write keyboard data packets to the global keyboard buffer

Buffer	Pointer to a buffer to copy the keyboard data packets from
Size	The size of the buffer in bytes (Must be at least TKeyboardData or greater)
Count	The number of keyboard data packets to copy from the buffer
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardFlush:LongWord;

Description: Flush the contents of the global keyboard buffer

Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardDeviceGet(Keyboard:PKeyboardDevice; var KeyCode:Word):LongWord;

Description: Get the first key code from the buffer of the specified keyboard

Keyboard	The keyboard device to get from
Keycode	The returned key code read from the buffer (eg KEY_CODE_A)
Return	ERROR_SUCCESS if completed or another error code on failure
Note	Key code is the value translated from the scan code using the current keymap it may not be a character code and it may include non printable characters. To translate a key code to a character call KeymapGetCharCode()

[Expand]

function KeyboardDeviceRead(Keyboard:PKeyboardDevice; Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;

Description: Read keyboard data packets from the buffer of the specified keyboard

Keyboard	The keyboard device to read from
Buffer	Pointer to a buffer to copy the keyboard data packets to
Size	The size of the buffer in bytes (Must be at least TKeyboardData or greater)
Count	The number of keyboard data packets copied to the buffer
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardDeviceControl(Keyboard:PKeyboardDevice; Request:Integer; Argument1:LongWord; var Argument2:LongWord):LongWord;

Description: Perform a control request on the specified keyboard device

Keyboard	The keyboard device to control
Request	The request code for the operation (eg KEYBOARD_CONTROL_GET_FLAG)
Argument1	The first argument for the operation (Dependant on request code)
Argument2	The second argument for the operation (Dependant on request code)
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardDeviceSetState(Keyboard:PKeyboardDevice; State:LongWord):LongWord;

Description: Set the state of the specified keyboard and send a notification

Keyboard	The keyboard to set the state for
State	The new state to set and notify
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardDeviceCreate:PKeyboardDevice;

Description: Create a new Keyboard device entry

Return	Pointer to new Keyboard device entry or nil if keyboard could not be created

[Expand]

function KeyboardDeviceCreateEx(Size:LongWord):PKeyboardDevice;

Description: Create a new Keyboard device entry

Size	Size in bytes to allocate for new keyboard (Including the keyboard device entry)
Return	Pointer to new Keyboard device entry or nil if keyboard could not be created

[Expand]

function KeyboardDeviceDestroy(Keyboard:PKeyboardDevice):LongWord;

Description: Destroy an existing Keyboard device entry

Keyboard	The keyboard device to destroy
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardDeviceRegister(Keyboard:PKeyboardDevice):LongWord;

Description: Register a new Keyboard device in the Keyboard table

Keyboard	The keyboard device to register
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardDeviceDeregister(Keyboard:PKeyboardDevice):LongWord;

Description: Deregister a Keyboard device from the Keyboard table

Keyboard	The keyboard device to deregister
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardDeviceFind(KeyboardId:LongWord):PKeyboardDevice;

Description: Find a keyboard device by ID in the keyboard table

KeyboardId	The ID number of the keyboard to find
Return	Pointer to keyboard device entry or nil if not found

[Expand]

function KeyboardDeviceFindByName(const Name:String):PKeyboardDevice; inline;

Description: Find a keyboard device by name in the keyboard table

Name	The name of the keyboard to find (eg Keyboard0)
Return	Pointer to keyboard device entry or nil if not found

[Expand]

function KeyboardDeviceFindByDescription(const Description:String):PKeyboardDevice; inline;

Description: Find a keyboard device by description in the keyboard table

Description	The description of the keyboard to find (eg USB HID Keyboard)
Return	Pointer to keyboard device entry or nil if not found

[Expand]

function KeyboardDeviceEnumerate(Callback:TKeyboardEnumerate; Data:Pointer):LongWord;

Description: Enumerate all keyboard devices in the keyboard table

Callback	The callback function to call for each keyboard in the table
Data	A private data pointer to pass to callback for each keyboard in the table
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function KeyboardDeviceNotification(Keyboard:PKeyboardDevice; Callback:TKeyboardNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;

Description: Register a notification for keyboard device changes

Keyboard	The keyboard device to notify changes for (Optional, pass nil for all keyboards)
Callback	The function to call when a notification event occurs
Data	A private data pointer to pass to callback when a notification event occurs
Notification	The events to register for notification of (eg DEVICE_NOTIFICATION_REGISTER)
Flags	The flags to control the notification (eg NOTIFIER_FLAG_WORKER)

RTL console functions

[Expand]

function SysConsoleGetKey(var ACh:Char; AUserData:Pointer):Boolean;

Description: Handler for Platform ConsoleGetKey function

Note	To be documented

[Expand]

function SysConsolePeekKey(var ACh:Char; AUserData:Pointer):Boolean;

Description: Handler for Platform ConsolePeekKey function

Note	To be documented

[Expand]

function SysConsoleReadChar(var ACh:Char; AUserData:Pointer):Boolean;

Description: Handler for Platform ConsoleReadChar function

Note	To be documented

[Expand]

function SysConsoleReadWideChar(var ACh:WideChar; AUserData:Pointer):Boolean;

Description: Handler for Platform ConsoleReadWideChar function

Note	To be documented

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	To be documented

[Expand]

function USBKeyboardDeviceControl(Keyboard:PKeyboardDevice; Request:Integer; Argument1:LongWord; var Argument2:LongWord):LongWord;

Description: Implementation of KeyboardDeviceControl API for USB Keyboard

Note	To be documented

[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
Interface	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
Interface	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

Keyboard helper functions

[Expand]

function KeyboardGetCount:LongWord; inline;

Description: Get the current keyboard count

Note	To be documented

[Expand]

function KeyboardDeviceCheck(Keyboard:PKeyboardDevice):PKeyboardDevice;

Description: Check if the supplied Keyboard is in the keyboard table

Note	To be documented

[Expand]

function KeyboardDeviceTypeToString(KeyboardType:LongWord):String;

Description: To be documented

Note	To be documented

[Expand]

function KeyboardDeviceStateToString(KeyboardState:LongWord):String;

Description: To be documented

Note	To be documented

[Expand]

function KeyboardDeviceStateToNotification(State:LongWord):LongWord;

Description: Convert a Keyboard state value into the notification code for device notifications

Note	To be documented

[Expand]

function KeyboardRemapCtrlCode(KeyCode,CharCode:Word):Word;

Description: Remap Ctrl-<Key> combinations to ASCII control codes

Note	Caller must check for Left-Ctrl or Right-Ctrl modifiers

[Expand]

function KeyboardRemapKeyCode(ScanCode,KeyCode:Word; var CharCode:Byte; Modifiers:LongWord):Boolean;

Description: Remap the SCAN_CODE_* and KEY_CODE_* values to DOS compatible scan codes

Return	Returns True if the key was remapped, False if it was not
See	http://www.freepascal.org/docs-html/rtl/keyboard/kbdscancode.html See also: \source\packages\rtl-console\src\inc\keyscan.inc
Note	See below for a version that uses SCAN_CODE_* values instead of translated KEY_CODE_* values

[Expand]

function KeyboardRemapScanCode(ScanCode,KeyCode:Word; var CharCode:Byte; Modifiers:LongWord):Boolean;

Description: Remap the SCAN_CODE_* and KEY_CODE_* values to DOS compatible scan codes

Return	Returns True if the key was remapped, False if it was not
See	http://www.freepascal.org/docs-html/rtl/keyboard/kbdscancode.html See also: \source\packages\rtl-console\src\inc\keyscan.inc
Note	Same as above except using SCAN_CODE_* values instead of translated KEY_CODE_* values

[Expand]

procedure KeyboardLog(Level:LongWord; Keyboard:PKeyboardDevice; const AText:String);

Description: To be documented

Note	To be documented

[Expand]

procedure KeyboardLogInfo(Keyboard:PKeyboardDevice; const AText:String);

Description: To be documented

Note	To be documented

[Expand]

procedure KeyboardLogError(Keyboard:PKeyboardDevice; const AText:String);

Description: To be documented

Note	To be documented

[Expand]

procedure KeyboardLogDebug(Keyboard:PKeyboardDevice; const AText:String);

Description: To be documented

Note	To be documented

USB keyboard helper functions

[Expand]

function USBKeyboardInsertData(Keyboard:PUSBKeyboardDevice; Data:PKeyboardData):LongWord;

Description: Insert a TKeyboardData entry into the keyboard buffer (Direct or Global)

Keyboard	The USB keyboard device to insert data for
Data	The TKeyboardData entry to insert
Return	ERROR_SUCCESS if completed or another error code on failure
Note	Caller must hold the keyboard lock

[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

Return to Unit Reference