ReadConsole
The ReadConsole
function reads character input from the console input buffer and removes it
from the buffer.
BOOL ReadConsole(
|
HANDLE hConsoleInput, |
// handle of a
console input buffer |
|
LPVOID lpBuffer, |
// address of
buffer to receive data |
|
DWORD nNumberOfCharsToRead, |
// number of
characters to read |
|
LPDWORD lpNumberOfCharsRead, |
// address of
number of characters read |
|
LPVOID lpReserved |
// reserved |
|
); |
|
Parameters
hConsoleInput
Identifies
the console input buffer. The handle must have GENERIC_READ access.
lpBuffer
Points to a
buffer that receives the data read from the console input buffer.
nNumberOfCharsToRead
Specifies the
number of characters to read. Because the function can read either 2-byte
Unicode or 1-byte ANSI characters, the size of the buffer pointed to by the lpBuffer
parameter should be at least nNumberOfCharsToRead * sizeof(TCHAR).
lpNumberOfCharsRead
Points to a
32-bit variable that receives the number of characters actually read.
lpReserved
Reserved;
must be NULL.
Return Values
If the
function succeeds, the return value is nonzero.
If the
function fails, the return value is zero. To get extended error information, call
GetLastError.
Remarks
ReadConsole reads keyboard input from a console s input buffer.
It behaves like the ReadFile
function, except that it can read in either Unicode (wide-character) or ANSI
mode. To have applications that maintain a single set of sources compatible with
both modes, use ReadConsole rather than ReadFile. Although ReadConsole
can only be used with a console input buffer handle, ReadFile can be
used with other handles (such as files or pipes). ReadConsole fails if
used with a standard handle that has been redirected to be something other than
a console handle.
All of the
input modes that affect the behavior of ReadFile have the same effect on
ReadConsole. To retrieve and set the input modes of a console input
buffer, use the GetConsoleMode and SetConsoleMode functions.
If the input
buffer contains input events other than keyboard events (such as mouse events
or window-resizing events), they are discarded. Those events can only be read
by using the ReadConsoleInput function.
Windows
NT: This function uses either Unicode
characters or 8-bit characters from the console's current codepage. The
console's codepage defaults initially to the system's OEM codepage. To change
the console's codepage, use the SetConsoleCP or SetConsoleOutputCP
functions, or use the chcp or mode con cp select= commands.
See Also