ReadConsoleInputEx function

Article
07/25/2022

Reads data from a console input buffer and removes it from the buffer, with configurable behavior.

Note This function has no associated import library. This function is available as the resources named ReadConsoleInputExA and ReadConsoleInputExW in Kernel32.dll. You must use the LoadLibrary and GetProcAddress functions to dynamically link to Kernel32.dll.

Syntax

BOOL WINAPI ReadConsoleInputEx(
  _In_  HANDLE        hConsoleInput,
  _Out_ PINPUT_RECORD lpBuffer,
  _In_  DWORD         nLength,
  _Out_ LPDWORD       lpNumberOfEventsRead,
  _In_  USHORT        wFlags
);

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 an array of INPUT_RECORD structures that receives the input buffer data.

nLength [in]
The size of the array pointed to by the lpBuffer parameter, in array elements.

lpNumberOfEventsRead [out]
A pointer to a variable that receives the number of input records read.

wFlags [in]

A set of flags (ORed together) that specify the console's reading behavior.

Value	Meaning
CONSOLE_READ_NOREMOVE `0x0001`	Leave the events in the input buffer (as in `PeekConsoleInput`)
CONSOLE_READ_NOWAIT `0x0002`	Return immediately, even if there are no events in the input buffer.

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

This function is a configurable version of ReadConsoleInput. See the remarks for ReadConsoleInput for additional operational details.

Calling ReadConsoleInputEx with the flags CONSOLE_READ_NOMOVE | CONSOLE_READ_NOWAIT is equivalent to calling PeekConsoleInput.

This function does not exist in the Windows Console headers. To gain access to it from a C or C++ application, include the following declarations and dynamically link kernel32.dll as noted above.

#ifndef CONSOLE_READ_NOREMOVE
#define CONSOLE_READ_NOREMOVE   0x0001
#endif

#ifndef CONSOLE_READ_NOWAIT
#define CONSOLE_READ_NOWAIT     0x0002
#endif

BOOL
WINAPI
ReadConsoleInputExA(
    _In_ HANDLE hConsoleInput,
    _Out_writes_(nLength) PINPUT_RECORD lpBuffer,
    _In_ DWORD nLength,
    _Out_ LPDWORD lpNumberOfEventsRead,
    _In_ USHORT wFlags);

BOOL
WINAPI
ReadConsoleInputExW(
    _In_ HANDLE hConsoleInput,
    _Out_writes_(nLength) PINPUT_RECORD lpBuffer,
    _In_ DWORD nLength,
    _Out_ LPDWORD lpNumberOfEventsRead,
    _In_ USHORT wFlags);

Requirements


Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Header	none, see remarks
Library	none, see remarks
DLL	Kernel32.dll
Unicode and ANSI names	ReadConsoleInputExW (Unicode) and ReadConsoleInputExA (ANSI)