KbdCharIn

From EDM2
Jump to: navigation, search

Reads a character data record from the keyboard.

Syntax

KbdCharIn (CharData, Wait, hkbd)

Parameters

CharData (PKBDKEYINFO) - output
Pointer to character data.
A pointer to a KBDKEYINFO structure in which the character data is returned.
Wait (ULONG) - input
Wait Flag.
0 IO_WAIT: Wait for a keystroke if one is not available. The keystroke returned is removed from the queue.
1 IO_NOWAIT: Return immediately, with or without a keystroke. If a keystroke is returned, remove it from the queue.
2 IO_PEEK: Return immediately, with or without a keystroke. Do not remove the keystroke from the queue.
3 IO_PEEKWAIT: Wait for a keystroke if one is not available. Return the keystroke but do not remove it from the queue.
hkbd (HKBD) - input
Reserved. Must be 0.

Return Code

rc (APIRET) - return
KbdCharIn returns one of the following values:
  • 0 - NO_ERROR
  • 375 - ERROR_KBD_INVALID_IOWAIT
  • 445 - ERROR_KBD_FOCUS_REQUIRED
  • 447 - ERROR_KBD_KEYBOARD_BUSY
  • 504 - ERROR_KBD_EXTENDED_SG

Remarks

Note
KbdCharIn returns a complete keystroke. This behaviour is unlike the OS/2 1.3 version, which returns only a single byte. This affects only double-byte character set (DBCS) characters.

If bit 0 of fbStatus is set, the character returned is either 0 or 0xe0. The Unicode character contains the virtual key.

For valid characters, the character in the current code page is returned, and the Unicode character contains the Unicode encoding of the character.

On an enhanced keyboard, the secondary enter key returns the normal character 0DH and a scan code of E0H.

Extended ASCII codes are identified by bit 1 of the status byte being set to on, and the ASCII character code being either 00H or E0H. Both conditions must be satisfied for the character to be an extended keystroke. For extended ASCII codes, the scan-code byte returned is the second code (extended code). Usually, the extended ASCII code is the scan code of the primary key that was pressed.

A thread in the foreground session that repeatedly polls the keyboard with KbdCharIn (with no wait), can prevent all regular priority-class threads from executing. If polling must be used, and a minimal amount of other processing is being performed, the thread should periodically yield to the CPU by issuing a DosSleep call for an interval of at least 5 milliseconds.