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 KbdStringIn(pchBuffer, psibLength, fWait, hkbd)
PCH pchBuffer;              /* pointer to buffer for string           */
PSTRINGINBUF psibLength;    /* pointer to structure for string length */
USHORT fWait;               /* wait/no-wait flag                      */
HKBD hkbd;                  /* keyboard handle                        */
 
The KbdStringIn function reads a string of characters from a logical
keyboard. The function copies the character value of each keystroke to the
buffer pointed to by the pchBuffer parameter. Depending on the input mode of
the keyboard and on the value of the fWait parameter, KbdStringIn continues
to copy characters until it fills the buffer, retrieves the turn-around
character, or reaches the end of the buffer.
 
The KbdStringIn function is a family API function.
 
Parameter   Description
────────────────────────────────────────────────────────────────────────────
 
pchBuffer   Points to the buffer that receives the character string.
 
psibLength  Points to the STRINGINBUF structure that contains the length of
            the buffer that receives the string.
 
fWait       Specifies whether to wait for the entire string to be read. If
            this parameter is IO_WAIT, the function waits for all characters
            up to the next turn-around character or until it reaches the end
            of the buffer. If the parameter is IO_NOWAIT, the function
            returns immediately with whatever characters are available.
 
hkbd        Identifies the logical keyboard to read from. 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, which may be one of the following:
 
     ERROR_KBD_DETACHED
     ERROR_KBD_INVALID_HANDLE
 
Comments
 
The KbdStringIn function removes keystroke information from the input buffer
of the specified logical keyboard as it copies a character. If echo and
ASCII modes are turned on, the function echoes characters on the screen as
they are typed. If the keyboard is in ASCII mode, the function retrieves a
character for each key pressed, except shift keys and MS OS/2 CTRL and
editing keys. If the keyboard is in binary mode, the function retrieves a
character for any key pressed except shift keys.
 
The KbdStringIn function can retrieve extended ASCII codes, such as when the
ALT key, and another key, called the primary key, are pressed
simultaneously. When the function retrieves an extended code, the first
character is 0x0000 or 0x00E0 and the second is the extended code. 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.
 
In ASCII mode, KbdStringIn recognizes the MS OS/2 editing keys. These keys
can be used to display and edit the previously entered string. The
KbdStringIn function permits editing of the previous string only if the
cchIn field of the STRINGINBUF structure is set to the length of the
previous string before the function is called. If this field is set to zero,
the line cannot be edited.
 
Restrictions
 
In real mode, the following restriction applies to the KbdStringIn
function:
 
♦  The hkbd parameter is ignored.
 
Example
 
This example calls the KbdStringIn function to read a character string from
the default keyboard. In ASCII mode, the function waits for the RETURN key
to be pressed; in binary mode, it waits for the buffer to be filled:
 
CHAR achBuf[40];
STRINGINBUF kbsiBuf;
kbsiBuf.cb = sizeof(achBuf);
KbdStringIn(achBuf,            /* address of buffer           */
    &kbsiBuf,                  /* address of length structure */
    IO_WAIT,                   /* waits for characters        */
    0);                        /* keyboard handle             */
VioWrtTTY("\n", 1, 0);         /* sends linefeed character    */
VioWrtTTY(achBuf, kbsiBuf.cchIn, 0); /* displays string       */
 
See Also
 
DosRead, KbdCharIn, KbdGetStatus, KbdOpen, KbdSetStatus, STRINGINBUF
 
                                      ♦