KbdCharIn (FAPI)

This call returns a character data record from the keyboard.

Syntax
KbdCharIn (CharData, IOWait, KbdHandle)

Parameters

 * CharData (PKBDKEYINFO) - output: Address of the character data structure
 * IOWait (USHORT) - input : Wait if a character is not available.
 * 0 - Requestor waits for a character if one is not available.
 * 1 - Requestor gets an immediate return if no character is available.


 * KbdHandle (HKBD) - input : Default keyboard or the logical keyboard.

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
On an enhanced keyboard, the secondary enter key returns the normal character 0DH and a scan code of E0H.

Double-byte character codes (DBCS) require two function calls to obtain the entire code.

If shift report is set with KbdSetStatus, the CharData record returned reflects changed shift information only.

Extended ASCII codes are identified with the status byte, bit 1 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.

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.
 * Interim character is not supported.
 * Status can be 0 or 40H
 * KbdHandle is ignored.

C
 typedef struct _KBDKEYINFO { /* kbci */ UCHAR   chChar;           /* ASCII character code */ UCHAR   chScan;           /* Scan Code */ UCHAR   fbStatus;         /* State of the character */ UCHAR   bNlsShift;        /* Reserved (set to zero) */ USHORT  fsState;          /* State of the shift keys */ ULONG   time;             /* Time stamp of keystroke (ms since ipl) */ }KBDKEYINFO;


 * 1) define INCL_KBD

USHORT rc = KbdCharIn(CharData, IOWait, KbdHandle);

PKBDKEYINFO CharData;      /* Buffer for data */ USHORT      IOWait;        /* Indicate if wait */ HKBD        KbdHandle;     /* Keyboard handle */

USHORT      rc;            /* return code */ 

MASM
 KBDKEYINFO struc kbci_chChar   db  ? ;ASCII character code kbci_chScan   db  ? ;Scan Code kbci_fbStatus db  ? ;State of the character kbci_bNlsShift db ? ;Reserved (set to zero) kbci_fsState  dw  ? ;state of the shift keys kbci_time     dd  ? ;time stamp of keystroke (ms since ipl) KBDKEYINFO ends

EXTRN KbdCharIn:FAR INCL_KBD           EQU 1

PUSH@ OTHER   CharData      ;Buffer for data PUSH  WORD    IOWait        ;Indicate if wait PUSH  WORD    KbdHandle     ;Keyboard handle CALL  KbdCharIn

Returns WORD 