ReadConsole function

Reads character input from the console input buffer and removes it from the buffer.

Syntax


BOOL WINAPI ReadConsole(
  _In_      HANDLE hConsoleInput,
  _Out_     LPVOID lpBuffer,
  _In_      DWORD nNumberOfCharsToRead,
  _Out_     LPDWORD lpNumberOfCharsRead,
  _In_opt_  LPVOID pInputControl
);

Parameters

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.

Return value

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.

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.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Wincon.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

ReadConsoleW (Unicode) and ReadConsoleA (ANSI)

See also

Console Functions
CONSOLE_READCONSOLE_CONTROL
GetConsoleMode
Input and Output Methods
ReadConsoleInput
ReadFile
SetConsoleCP
SetConsoleMode
SetConsoleOutputCP
WriteConsole

 

 

Community Additions

ADD
Show:
© 2014 Microsoft