Differences

This shows you the differences between two versions of the page.

--- en:docs:fapi:kbdcharin [2020/12/05 10:46] – prokushev
+++ en:docs:fapi:kbdcharin [2021/09/18 15:17] (current) – prokushev
@@ Line 1: / Line 1: @@
-{{logos:os2.gif?35x35}} {{logos:dos.gif?35x35}}
+{{page>en:templates:fapiint}}
 ====== KbdCharIn ======
@@ Line 5: / Line 5: @@
 This call returns a character data record from the keyboard.
-==Syntax==
+===== Syntax =====
- KbdCharIn (CharData, IOWait, KbdHandle)
-==Parameters==
+<code c>
-;CharData (PKBDKEYINFO) - output : Address of the character data structure:
+KbdCharIn (CharData, IOWait, KbdHandle)
-:asciicharcode (UCHAR) : ASCII character code. The scan code received from the keyboard is translated to the ASCII character code.
+</code>
-:scancode (UCHAR) : Code received from the keyboard. The scan code received from the keyboard is translated to the ASCII character code.
+===== Parameters =====
+  * CharData ([[PKBDKEYINFO]]) - output : Address of the character data structure:
+    * asciicharcode ([[UCHAR]]) : ASCII character code. The scan code received from the keyboard is translated to the ASCII character code.
+    *scancode ([[UCHAR]]) : Code received from the keyboard. The scan code received from the keyboard is translated to the ASCII character code.
+    * status ([[UCHAR]]) : State of the keystroke event:
+^ Bit ^ Description ^
+| 7-6 | 00 = Undefined |
+| ::: | 01 = Final character, interim character flag off |
+| ::: | 10 = Interim character |
+| ::: | 11 = Final character, interim character flag on. |
+| 5 | 1 = Immediate conversion requested. |
+| 4-2 | Reserved. |
+| 1 | 0 = Scan code is a character. |
+| ::: | 1 = Scan code is not a character; is an extended key code from the keyboard. |
+| 0 | 1 = Shift status returned without character. |
+    * reserved ([[UCHAR]]):NLS shift status. Reserved, set to zero.
-status (UCHAR) : State of the keystroke event:
- '''Bit   Description'''
--6  00 = Undefined
-= Final character, interim character flag off
-= Interim character
-= Final character, interim character flag on.
-    1 = Immediate conversion requested.
--2  Reserved.
-    0 = Scan code is a character.
-= Scan code is not a character; is an extended key code from the keyboard.
-    1 = Shift status returned without character.
-reserved (UCHAR):NLS shift status. Reserved, set to zero.
     Kana-To-Kanji Conversion Mode (Japanese)
       Hanja_25: Hangeul-to-Hanja Conversion Mode (Korean)
@@ Line 53: / Line 55: @@
     DBCS Mode
-shiftkeystat (USHORT) : Shift key status.
+    * shiftkeystat ([[USHORT]]) : Shift key status.
  '''Bit   Description'''
    SysReq key down
@@ Line 71: / Line 74: @@
     Left Shift key down
     Right Shift key down
-time (ULONG) : Time stamp indicating when a key was pressed. It is specified in milliseconds from the time the system was started.
+    * time ([[ULONG]]) : Time stamp indicating when a key was pressed. It is specified in milliseconds from the time the system was started.
-;IOWait (USHORT) - input : Wait if a character is not available.
+  * IOWait ([[USHORT]]) - input : Wait if a character is not available.
- '''Value  Definition'''
+^ Value ^ Definition ^
-      Requestor waits for a character if one is not available.
+| 0 | Requestor waits for a character if one is not available. |
-      Requestor gets an immediate return if no character is available.
+| 1 | Requestor gets an immediate return if no character is available. |
-;KbdHandle (HKBD) - input : Default keyboard or the logical keyboard.
+  * KbdHandle ([[HKBD]]) - input : Default keyboard or the logical keyboard.
+===== Return Code =====
+rc ([[USHORT]]) - return
-==Return Code==
- rc (USHORT) - return
 Return code descriptions are:
-* 0     NO_ERROR
-* 375   ERROR_KBD_INVALID_IOWAIT
-* 439   ERROR_KBD_INVALID_HANDLE
-* 445   ERROR_KBD_FOCUS_REQUIRED
-* 447   ERROR_KBD_KEYBOARD_BUSY
-* 464   ERROR_KBD_DETACHED
-* 504   ERROR_KBD_EXTENDED_SG
-==Remarks==
+  * 0     NO_ERROR
+  * 375   ERROR_KBD_INVALID_IOWAIT
+  * 439   ERROR_KBD_INVALID_HANDLE
+  * 445   ERROR_KBD_FOCUS_REQUIRED
+  * 447   ERROR_KBD_KEYBOARD_BUSY
+  * 464   ERROR_KBD_DETACHED
+  * 504   ERROR_KBD_EXTENDED_SG
+===== Remarks =====
 On an enhanced keyboard, the secondary enter key returns the normal character 0DH and a scan code of E0H.
@@ Line 101: / Line 108: @@
 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.
-===Family API Considerations===
+==== Family API Considerations ====
 Some options operate differently in the DOS mode than in the OS /2 mode. Therefore, the following restrictions apply to KbdCharIn when coding in the DOS mode:
-* The CharData structure includes everything except the time stamp.
+  * The CharData structure includes everything except the time stamp.
-* Interim character is not supported
+  * Interim character is not supported
-* Status can be 0 or 40H
+  * Status can be 0 or 40H
-* KbdHandle is ignored.
+  * KbdHandle is ignored.
-==Example Code==
+===== Bindings =====
-===C Binding===
-<PRE>
+==== C Binding ====
+<code c>
 typedef struct _KBDKEYINFO {   /* kbci */
   UCHAR    chChar;             /* ASCII character code */
@@ Line 129: / Line 140: @@
 USHORT           rc;            /* return code */
-</PRE>
+</code>
+==== MASM Binding ====
-===MASM Binding===
+<code asm>
-<PRE>
 KBDKEYINFO struc
   kbci_chChar    db  ? ;ASCII character code
@@ Line 151: / Line 163: @@
 Returns WORD
-</PRE>
+</code>
-====== Note ======
+===== Note =====
 Text based on [[http://www.edm2.com/index.php/KbdCharIn_(FAPI)]]