Difference between revisions of "Unit HIDKEYBOARD"

From Ultibo.org
Jump to: navigation, search
(Created page with "Return to Unit Reference === Description === ---- ''To be documented'' === Constants === ---- ''To be documented'' === Type definitions === ---- ''To...")
 
 
(4 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
----
 
----
  
−
''To be documented''
+
'''Ultibo HID Keyboard Consumer unit'''
 +
 
 +
This is a consumer for any generic HID keyboard device, it accepts HID application collections in the generic desktop page (HID_PAGE_GENERIC_DESKTOP) with the usage set to keyboard (HID_DESKTOP_KEYBOARD).
 +
 +
The consumer will bind to any keyboard collection that includes at a minimum an input report containing a field that provides keypress data from the keyboard / keypad page (HID_PAGE_KEYBOARD_KEYPAD) and a field providing modifier keys from the same page.
 +
 +
The consumer will also look for an output report containing a field from the LED page (HID_PAGE_LED) and will use this to set the keyboard LEDs if found.
 +
 +
Up to 16 keypresses per report can be accepted (see HID_KEYBOARD_MAX_KEYS) but most keyboards will commonly report up to 6 which is the size defined in the USB HID usage tables for boot mode keyboard reports.
  
 
=== Constants ===
 
=== Constants ===
 
----
 
----
  
−
''To be documented''
+
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;">
 +
<div style="font-size: 14px; padding-left: 12px;">'''HID keyboard specific constants''' <code> HID_KEYBOARD_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>HID_KEYBOARD_CONSUMER_NAME = 'HID Keyboard Consumer';</code>
 +
| Name of HID Keyboard consumer
 +
|-
 +
| <code>HID_KEYBOARD_DESCRIPTION = 'HID Keyboard';</code>
 +
| Description of HID Keyboard device
 +
|-
 +
| <code>HID_KEYBOARD_MAX_KEYS = 16;</code>
 +
| Maximum number of keys allowed in any report
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Type definitions ===
 
=== Type definitions ===
 
----
 
----
  
−
''To be documented''
+
 
 +
'''HID keyboard keys'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PHIDKeyboardKeys = ^THIDKeyboardKeys;</code>
 +
 
 +
<code>THIDKeyboardKeys = array[0..HID_KEYBOARD_MAX_KEYS - 1] of Byte;</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| &nbsp;
 +
| style="width: 50%;"|&nbsp;
 +
|-
 +
|}
 +
</div></div>
 +
 
 +
'''HID keyboard device'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PHIDKeyboardDevice = ^THIDKeyboardDevice;</code>
 +
 
 +
<code>THIDKeyboardDevice = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|''Keyboard Properties''
 +
|-
 +
| <code>Keyboard:TKeyboardDevice;</code>
 +
| &nbsp;
 +
|-
 +
|colspan="2"|''HID Properties''
 +
|-
 +
| <code>Collection:PHIDCollection;</code>
 +
| The HID collection this keyboard is bound to
 +
|-
 +
| <code>Definitions:PHIDDefinition;</code>
 +
| The input report definitions that can be accepted as keyboard reports
 +
|-
 +
| <code>LEDDefinition:PHIDDefinition;</code>
 +
| The report definition that corresponds to the LED output
 +
|-
 +
| <code>LastCode:Word;</code>
 +
| The scan code of the last key pressed
 +
|-
 +
| <code>LastCount:LongWord;</code>
 +
| The repeat count of the last key pressed
 +
|-
 +
| <code>LastKeys:THIDKeyboardKeys;</code>
 +
| The keys from the last keyboard report received
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Public variables ===
 
=== Public variables ===
Line 25: Line 102:
 
----
 
----
  
−
''To be documented''
 
  
 +
'''Initialization functions'''
 +
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">procedure HIDKeyboardInit;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Initialize the HID Keyboard unit and HID Keyboard driver</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| Called only during system startup
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''HID keyboard functions'''
 +
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function HIDKeyboardDeviceControl(Keyboard:PKeyboardDevice; Request:Integer; Argument1:PtrUInt; var Argument2:PtrUInt):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of KeyboardDeviceControl API for HID Keyboard</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| Not intended to be called directly by applications, use KeyboardDeviceControl instead.
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''HID keyboard helper functions'''
 +
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function HIDKeyboardCheckCollection(Collection:PHIDCollection):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if a HID collection is suitable for use as a keyboard device</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function HIDKeyboardCheckInputDefinition(Definition:PHIDDefinition):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if a HID definition is suitable for use as a keyboard input report</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function HIDKeyboardCheckOutputDefinition(Definition:PHIDDefinition):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if a HID definition is suitable for use as a keyboard output (LED) report</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function HIDKeyboardCheckPressed(Keyboard:PHIDKeyboardDevice; ScanCode:Byte):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if the passed scan code has been pressed (True if not pressed in last report</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The HID keyboard device to check for
 +
|-
 +
! ScanCode
 +
| The keyboard scan code to check
 +
|-
 +
! Note
 +
| Caller must hold the keyboard lock
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function HIDKeyboardCheckRepeated(Keyboard:PHIDKeyboardDevice; ScanCode:Byte):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if the passed scan code was the last key pressed and if the repeat delay has expired</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The HID keyboard device to check for
 +
|-
 +
! ScanCode
 +
| The keyboard scan code to check
 +
|-
 +
! Note
 +
| Caller must hold the keyboard lock
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function HIDKeyboardCheckReleased(Keyboard:PHIDKeyboardDevice; Keys:PHIDKeyboardKeys; ScanCode:Byte):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if the passed scan code has been released (True if not pressed in current report)</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The HID keyboard device to check for
 +
|-
 +
! Keys
 +
| The HID keyboard keys to compare against (Current)
 +
|-
 +
! ScanCode
 +
| The keyboard scan code to check
 +
|-
 +
! Note
 +
| Caller must hold the keyboard lock
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function HIDKeyboardDeviceSetLEDs(Keyboard:PHIDKeyboardDevice; LEDs:Byte):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the state of the LEDs for a HID keyboard device</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The HID keyboard device to set the LEDs for
 +
|-
 +
! LEDs
 +
| The LED state to set (eg KEYBOARD_LED_NUMLOCK)
 +
|-
 +
! Return
 +
| ERROR_SUCCESS if completed or another error code on failure
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function HIDKeyboardDeviceSetIdle(Keyboard:PHIDKeyboardDevice; Duration,ReportId:Byte):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the idle duration (Time between reports when no changes) for a HID keyboard device</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Keyboard
 +
| The HID 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 HID_REPORTID_NONE)
 +
|-
 +
! Return
 +
| ERROR_SUCCESS if completed or another error code on failure
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
Return to [[Unit_Reference|Unit Reference]]
 
Return to [[Unit_Reference|Unit Reference]]

Latest revision as of 03:20, 17 November 2022

Return to Unit Reference


Description

Ultibo HID Keyboard Consumer unit

This is a consumer for any generic HID keyboard device, it accepts HID application collections in the generic desktop page (HID_PAGE_GENERIC_DESKTOP) with the usage set to keyboard (HID_DESKTOP_KEYBOARD).

The consumer will bind to any keyboard collection that includes at a minimum an input report containing a field that provides keypress data from the keyboard / keypad page (HID_PAGE_KEYBOARD_KEYPAD) and a field providing modifier keys from the same page.

The consumer will also look for an output report containing a field from the LED page (HID_PAGE_LED) and will use this to set the keyboard LEDs if found.

Up to 16 keypresses per report can be accepted (see HID_KEYBOARD_MAX_KEYS) but most keyboards will commonly report up to 6 which is the size defined in the USB HID usage tables for boot mode keyboard reports.

Constants


HID keyboard specific constants HID_KEYBOARD_*
HID_KEYBOARD_CONSUMER_NAME = 'HID Keyboard Consumer'; Name of HID Keyboard consumer
HID_KEYBOARD_DESCRIPTION = 'HID Keyboard'; Description of HID Keyboard device
HID_KEYBOARD_MAX_KEYS = 16; Maximum number of keys allowed in any report


Type definitions


HID keyboard keys

PHIDKeyboardKeys = ^THIDKeyboardKeys;

THIDKeyboardKeys = array[0..HID_KEYBOARD_MAX_KEYS - 1] of Byte;

   

HID keyboard device

PHIDKeyboardDevice = ^THIDKeyboardDevice;

THIDKeyboardDevice = record

Keyboard Properties
Keyboard:TKeyboardDevice;  
HID Properties
Collection:PHIDCollection; The HID collection this keyboard is bound to
Definitions:PHIDDefinition; The input report definitions that can be accepted as keyboard reports
LEDDefinition:PHIDDefinition; The report definition that corresponds to the LED output
LastCode:Word; The scan code of the last key pressed
LastCount:LongWord; The repeat count of the last key pressed
LastKeys:THIDKeyboardKeys; The keys from the last keyboard report received


Public variables

None defined

Function declarations


Initialization functions 

procedure HIDKeyboardInit;
Description: Initialize the HID Keyboard unit and HID Keyboard driver
Note Called only during system startup


HID keyboard functions 

function HIDKeyboardDeviceControl(Keyboard:PKeyboardDevice; Request:Integer; Argument1:PtrUInt; var Argument2:PtrUInt):LongWord;
Description: Implementation of KeyboardDeviceControl API for HID Keyboard
Note Not intended to be called directly by applications, use KeyboardDeviceControl instead.


HID keyboard helper functions 

function HIDKeyboardCheckCollection(Collection:PHIDCollection):LongWord;
Description: Check if a HID collection is suitable for use as a keyboard device
Note None documented 


function HIDKeyboardCheckInputDefinition(Definition:PHIDDefinition):LongWord;
Description: Check if a HID definition is suitable for use as a keyboard input report
Note None documented 


function HIDKeyboardCheckOutputDefinition(Definition:PHIDDefinition):LongWord;
Description: Check if a HID definition is suitable for use as a keyboard output (LED) report
Note None documented 


function HIDKeyboardCheckPressed(Keyboard:PHIDKeyboardDevice; ScanCode:Byte):Boolean;
Description: Check if the passed scan code has been pressed (True if not pressed in last report
Keyboard The HID keyboard device to check for
ScanCode The keyboard scan code to check
Note Caller must hold the keyboard lock 


function HIDKeyboardCheckRepeated(Keyboard:PHIDKeyboardDevice; ScanCode:Byte):Boolean;
Description: Check if the passed scan code was the last key pressed and if the repeat delay has expired
Keyboard The HID keyboard device to check for
ScanCode The keyboard scan code to check
Note Caller must hold the keyboard lock 


function HIDKeyboardCheckReleased(Keyboard:PHIDKeyboardDevice; Keys:PHIDKeyboardKeys; ScanCode:Byte):Boolean;
Description: Check if the passed scan code has been released (True if not pressed in current report)
Keyboard The HID keyboard device to check for
Keys The HID keyboard keys to compare against (Current)
ScanCode The keyboard scan code to check
Note Caller must hold the keyboard lock 


function HIDKeyboardDeviceSetLEDs(Keyboard:PHIDKeyboardDevice; LEDs:Byte):LongWord;
Description: Set the state of the LEDs for a HID keyboard device
Keyboard The HID keyboard device to set the LEDs for
LEDs The LED state to set (eg KEYBOARD_LED_NUMLOCK)
Return ERROR_SUCCESS if completed or another error code on failure 


function HIDKeyboardDeviceSetIdle(Keyboard:PHIDKeyboardDevice; Duration,ReportId:Byte):LongWord;
Description: Set the idle duration (Time between reports when no changes) for a HID keyboard device
Keyboard The HID 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 HID_REPORTID_NONE)
Return ERROR_SUCCESS if completed or another error code on failure


Return to Unit Reference

Retrieved from "https://ultibo.org/mediawiki_ultibo_org/index.php?title=Unit_HIDKEYBOARD&oldid=5616"