Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Overview►                                            ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_KBD
 
USHORT KbdPeek(pkbciKeyInfo, hkbd)
PKBDKEYINFO pkbciKeyInfo;    /* pointer to structure for keystroke info. */
HKBD hkbd;                   /* keyboard handle                          */
 
The KbdPeek function retrieves character and scan-code information from a
logical keyboard. The function copies information to the structure pointed
to by the pkbciKeyInfo parameter. The keystroke information includes the
character value of the key, the scan code, the keystroke status, the state
of the shift keys, and the system time (in milliseconds) when the keystroke
occurred.
 
The KbdPeek function is a family API function.
 
Parameter     Description
────────────────────────────────────────────────────────────────────────────
 
pkbciKeyInfo  Points to the KBDKEYINFO structure that receives the keystroke
              information.
 
hkbd          Identifies the logical keyboard. The handle must have been
              created previously by using the KbdOpen function.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value.
 
Comments
 
The KbdPeek function copies but does not remove keystroke information from
the input buffer of the specified logical keyboard. Although echo mode for
the logical keyboard may be turned on, the KbdPeek function does not echo
the characters it reads. If the keyboard is in ASCII mode, KbdPeek retrieves
keystroke information for each key pressed, except shift keys and MS OS/2
CTRL keys. If the keyboard is in binary mode, KbdPeek retrieves keystroke
information for any key pressed, except shift keys. In most cases, a shift
key is pressed in combination with other keys to create a single keystroke.
In binary mode with shift report turned on, a shift key by itself creates a
keystroke that this function can retrieve. For more information on binary
mode and shift-report mode, see the KbdSetStatus function.
 
The KbdPeek function retrieves extended ASCII codes, such as when the ALT
key and another key, called the primary key, are pressed simultaneously.
When the KbdPeek function retrieves an extended ASCII code, it sets the
chChar field of the KBDKEYINFO structure to 0x0000 or 0x00E0 and copies the
code to the chScan field. The extended code is usually the scan code of the
primary key. In ASCII mode, the function retrieves only complete extended
codes, which means that if both bytes of the extended code do not fit in the
buffer, neither byte is retrieved.
 
The KbdPeek function must be called twice to retrieve a code for a
double-byte character set (DBCS). If the code retrieved is the first byte of
a double-byte character, the fbStatus field of the KBDKEYINFO structure is
set to 0x0080.
 
Restrictions
 
In real mode, the following restrictions apply to the KbdPeek function:
 
♦  It does not copy the system time to the KBDKEYINFO structure, and there
   is no interim character support.
 
♦  It retrieves characters only from the default logical keyboard (handle
   0).
 
♦  The fbStatus field may be 0x0000 or SHIFT_KEY_IN.
 
♦  The hkbd parameter is ignored.
 
Example
 
This example calls the KbdPeek function to read a character from the default
keyboard without removing it from the keyboard input buffer. If there is
already a character in the buffer, the fbStatus field specifies this by
setting the sixth bit (0x40):
 
KBDKEYINFO kbciKeyInfo;
    .
    .
    .
KbdPeek(&kbciKeyInfo, 0);
if (kbciKeyInfo.fbStatus & 0x40) {
 
See Also
 
KbdCharIn, KbdGetStatus, KbdOpen, KbdSetStatus, KBDKEYINFO
 
                                      ♦