KbdCharIn: Difference between revisions
Created page with "==Description== Reads a character data record from the keyboard. ==Syntax== <PRE> #define INCL_KBD #include <os2.h> PKBDKEYINFO CharData; /* Pointer to character data..." |
mNo edit summary |
||
| (5 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
Reads a character data record from the keyboard. | |||
Reads a character data record from the keyboard. | |||
==Syntax== | ==Syntax== | ||
KbdCharIn (CharData, Wait, hkbd) | |||
==Parameters== | ==Parameters== | ||
; CharData ( | ;CharData (P[[KBDKEYINFO]]) - output: Pointer to character data. | ||
:A pointer to a KBDKEYINFO structure in which the character data is returned. | |||
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. | |||
; Wait (ULONG) - input : Wait Flag. | ::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. | |||
; hkbd (HKBD) - input : Reserved. Must be 0. | |||
==Return Code== | ==Return Code== | ||
;rc (APIRET) - return:KbdCharIn returns one of the following values: | |||
*0 - NO_ERROR | |||
KbdCharIn returns one of the following values: | *375 - ERROR_KBD_INVALID_IOWAIT | ||
*445 - ERROR_KBD_FOCUS_REQUIRED | |||
* 0 | *447 - ERROR_KBD_KEYBOARD_BUSY | ||
* | *504 - ERROR_KBD_EXTENDED_SG | ||
* | |||
* | |||
* | |||
==Remarks== | ==Remarks== | ||
Note: KbdCharIn returns a complete keystroke. This | ;Note: KbdCharIn returns a complete keystroke. This behaviour is unlike the [[KbdCharIn (FAPI)|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. | If bit 0 of fbStatus is set, the character returned is either 0 or 0xe0. The Unicode character contains the virtual key. | ||
| Line 51: | Line 33: | ||
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. | 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. | 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. | ||
[[Category: | [[Category:Kbd]] | ||
Latest revision as of 02:49, 2 January 2020
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.