Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revision | |||
| en:docs:fapi:kbdstringin [2021/08/20 08:01] – prokushev | en:docs:fapi:kbdstringin [2021/09/19 01:30] (current) – prokushev | ||
|---|---|---|---|
| Line 5: | Line 5: | ||
| This call reads a character string (character codes only) from the keyboard. | This call reads a character string (character codes only) from the keyboard. | ||
| - | ==Syntax== | + | ===== Syntax |
| - | | + | <code c> |
| + | KbdStringIn (CharBuffer, | ||
| + | </ | ||
| - | ==Parameters== | + | ===== Parameters ===== |
| - | ;CharBuffer ([[PCH]]) - output : Address of the character string buffer. | + | |
| - | ;StringLength (P[[STRINGINBUF]]) - input/ | + | |
| - | ::buflen ([[USHORT]]) : Length of the input buffer. | + | |
| - | ::inputlen (USHORT) : Number of bytes read into the buffer. | + | |
| - | ;IOWait (USHORT) - input : Wait if a character is not available. | + | |
| - | ::0 - Wait. In Binary input mode, the requestor waits until CharBuffer is full. In ASCII input mode, the requestor waits until a carriage return is pressed. | + | |
| - | ::1 - No wait. The requestor gets an immediate return if no characters are available. If characters are available, KbdStringIn returns immediately with as many characters as are available (up to the maximum). No wait is not supported in ASCII input mode. | + | *0 - Wait. In Binary input mode, the requestor waits until CharBuffer is full. In ASCII input mode, the requestor waits until a carriage return is pressed. |
| - | ;KbdHandle ([[HKBD]]) - input : Default keyboard or the logical keyboard. | + | *1 - No wait. The requestor gets an immediate return if no characters are available. If characters are available, KbdStringIn returns immediately with as many characters as are available (up to the maximum). No wait is not supported in ASCII input mode. |
| + | | ||
| + | |||
| + | ===== Return Code ===== | ||
| + | |||
| + | rc ([[USHORT]]) - return | ||
| - | ==Return Code== | ||
| - | rc (USHORT) - return | ||
| Return code descriptions are: | Return code descriptions are: | ||
| - | * 0 | ||
| - | * 375 ERROR_KBD_INVALID_IOWAIT | ||
| - | * 439 ERROR_KBD_INVALID_HANDLE | ||
| - | * 445 ERROR_KBD_FOCUS_REQUIRED | ||
| - | * 464 ERROR_KBD_DETACHED | ||
| - | * 504 ERROR_KBD_EXTENDED_SG | ||
| - | ==Remarks== | + | * 0 |
| + | * 375 ERROR_KBD_INVALID_IOWAIT | ||
| + | * 439 ERROR_KBD_INVALID_HANDLE | ||
| + | * 445 ERROR_KBD_FOCUS_REQUIRED | ||
| + | * 464 ERROR_KBD_DETACHED | ||
| + | * 504 ERROR_KBD_EXTENDED_SG | ||
| + | |||
| + | ===== Remarks ===== | ||
| The character strings may be optionally echoed on the display if echo mode is set. When echo is on each character is echoed as it is read from the keyboard. Echo mode and BINARY mode are mutually exclusive. Reference [[KbdSetStatus]] and [[KbdGetStatus]] for more information. | The character strings may be optionally echoed on the display if echo mode is set. When echo is on each character is echoed as it is read from the keyboard. Echo mode and BINARY mode are mutually exclusive. Reference [[KbdSetStatus]] and [[KbdGetStatus]] for more information. | ||
| Line 34: | Line 41: | ||
| In input mode (BINARY, ASCII), The following returns can be set and retrieved with KbdSetStatus and KbdGetStatus: | In input mode (BINARY, ASCII), The following returns can be set and retrieved with KbdSetStatus and KbdGetStatus: | ||
| - | * Turnaround Character | + | |
| - | * Echo Mode | + | * Echo Mode |
| - | * Interim Character Flag | + | * Interim Character Flag |
| - | * Shift State | + | * Shift State |
| The received input length is also used by the KbdStringIn line edit functions for re-displaying and entering a caller specified string. On the next KbdStringIn call the received input length indicates the length of the input buffer that may be recalled by the user using the line editing keys. A value of 0 inhibits the line editing function for the current KbdStringIn request. | The received input length is also used by the KbdStringIn line edit functions for re-displaying and entering a caller specified string. On the next KbdStringIn call the received input length indicates the length of the input buffer that may be recalled by the user using the line editing keys. A value of 0 inhibits the line editing function for the current KbdStringIn request. | ||
| Line 43: | Line 50: | ||
| KbdStringIn completes when the handle has access to the physical keyboard (focus), or is equal to zero and no other handle has the focus. | KbdStringIn completes when the handle has access to the physical keyboard (focus), or is equal to zero and no other handle has the focus. | ||
| - | ===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 KbdStringIn when coding in the DOS mode: | Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following restrictions apply to KbdStringIn when coding in the DOS mode: | ||
| - | * KbdHandle is ignored | + | |
| + | |||
| + | Refer to the [[DosRead]] Family API Considerations for differences between DOS and OS/2 node when reading from a handle opened to the CON device. | ||
| - | Refer to the DosRead Family API Considerations for differences between DOS and OS/2 node when reading from a handle opened to the CON device. | + | ===== Bindings ===== |
| - | ==Example Code== | + | ====C Binding==== |
| - | ===C Binding=== | + | <code c> |
| - | <PRE> | + | |
| typedef struct _STRINGINBUF { /* kbsi */ | typedef struct _STRINGINBUF { /* kbsi */ | ||
| USHORT cb; /* input buffer length */ | USHORT cb; /* input buffer length */ | ||
| Line 67: | Line 76: | ||
| USHORT | USHORT | ||
| - | </PRE> | + | </code> |
| - | ===MASM Binding=== | + | ==== MASM Binding ==== |
| - | <PRE> | + | |
| + | <code asm> | ||
| STRINGINBUF struc | STRINGINBUF struc | ||
| kbsi_cb | kbsi_cb | ||
| Line 86: | Line 96: | ||
| Returns WORD | Returns WORD | ||
| - | </PRE> | + | </code> |
| - | + | ||
| - | ====== Note ====== | + | ===== Note ===== |
| Text based on [[http:// | Text based on [[http:// | ||