Reads character input from the console input buffer and removes it from the buffer.
BOOL WINAPI ReadConsole( _In_ HANDLE hConsoleInput, _Out_ LPVOID lpBuffer, _In_ DWORD nNumberOfCharsToRead, _Out_ LPDWORD lpNumberOfCharsRead, _In_opt_ LPVOID pInputControl );
- hConsoleInput [in]
A handle to the console input buffer. The handle must have the GENERIC_READ access right. For more information, see Console Buffer Security and Access Rights.
- lpBuffer [out]
A pointer to a buffer that receives the data read from the console input buffer.
The storage for this buffer is allocated from a shared heap for the process that is 64 KB in size. The maximum size of the buffer will depend on heap usage.
- nNumberOfCharsToRead [in]
The number of characters to be read. The size of the buffer pointed to by the lpBuffer parameter should be at least
nNumberOfCharsToRead * sizeof(TCHAR)bytes.
- lpNumberOfCharsRead [out]
A pointer to a variable that receives the number of characters actually read.
- pInputControl [in, optional]
A pointer to a CONSOLE_READCONSOLE_CONTROL structure that specifies a control character to signal the end of the read operation. This parameter can be NULL.
This parameter requires Unicode input by default. For ANSI mode, set this parameter to NULL.
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.
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.
This function uses either Unicode characters or 8-bit characters from the console's current code page. The console's code page defaults initially to the system's OEM code page. To change the console's code page, use the SetConsoleCP or SetConsoleOutputCP functions, or use the chcp or mode con cp select= commands.
The pInputControl parameter can be used to enable intermediate wakeups from the read in response to a file-completion control character specified in a CONSOLE_READCONSOLE_CONTROL structure. This feature requires command extensions to be enabled, the standard output handle to be a console output handle, and input to be Unicode.
Windows Server 2003 and Windows XP/2000: The intermediate read feature is not supported.
Minimum supported client
|Windows 2000 Professional [desktop apps only]|
Minimum supported server
|Windows 2000 Server [desktop apps only]|
Unicode and ANSI names
|ReadConsoleW (Unicode) and ReadConsoleA (ANSI)|
- Console Functions
- Input and Output Methods