ReadConsole 函数

项目
10/26/2023

从控制台输入缓冲区读取字符输入，并将其从缓冲区删除。

语法

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

参数

hConsoleInput [in]
控制台输入缓冲区的句柄。该句柄必须具有 GENERIC_READ 访问权限。有关详细信息，请参阅控制台缓冲区安全性和访问权限。

lpBuffer [out]
指针 – 指向接收从控制台输入缓冲区读取的数据的缓冲区。

nNumberOfCharsToRead [in]
要读取的字符数。 lpBuffer 参数指向的缓冲区的大小应至少为 nNumberOfCharsToRead * sizeof(TCHAR) 字节。

lpNumberOfCharsRead [out]
指针 – 指向接收实际读取的字符数的变量。

pInputControl [in, optional]
指针 – 指向 CONSOLE_READCONSOLE_CONTROL 结构（该结构指定表示读取操作结束的控制字符）。此参数可以为 NULL。

此参数默认需要 Unicode 输入。对于 ANSI 模式，请将此参数设为 NULL。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

备注

ReadConsole 从控制台的输入缓冲区读取键盘输入。该函数的行为类似于 ReadFile 函数，不同之处在于它可以在 Unicode（宽字符）或 ANSI 模式下读取。要让维护单个源集的应用程序与这两种模式兼容，请使用 ReadConsole 而不是 ReadFile。尽管 ReadConsole 只能与控制台输入缓冲区句柄一起使用，但 ReadFile 可以与其他句柄（如文件或管道）一起使用。如果与已重定向到控制台句柄以外的标准句柄一起使用，ReadConsole 将失败。

影响 ReadFile 行为的所有输入模式对 ReadConsole 具有相同的影响。若要取回和设置控制台输入缓冲区的输入模式，请使用 GetConsoleMode 和 SetConsoleMode 函数。

如果输入缓冲区包含键盘事件以外的输入事件（例如鼠标事件或窗口重设大小事件），则它们将被丢弃。只能使用 ReadConsoleInput 函数来读取这些事件。

此函数使用控制台当前代码页中的 Unicode 字符或 8 位字符。控制台的代码页最初默认为系统的 OEM 代码页。若要更改控制台的代码页，请使用 SetConsoleCP 或 SetConsoleOutputCP 函数。旧版使用者也可以使用 chcp 或 mode con cp select= 命令，但不建议将其用于新开发。

pInputControl 参数可用于在读取中启用中间唤醒，以响应在 CONSOLE_READCONSOLE_CONTROL 结构中指定的文件完成控制字符。此功能要求启用命令扩展、将标准输出句柄设为控制台输出句柄，以及输入为 Unicode。

Windows Server 2003 和 Windows XP/2000：不支持中间读取功能。

成熟模式是指在控制台输入句柄上使用 SetConsoleMode 设置 ENABLE_LINE_INPUT 时的模式。在成熟模式下，控制台主机将代表命令行应用程序提供编辑行，并且在按下 Enter 键之前，对 ReadFile 或 ReadConsole 的调用将不会返回结果。

中间读取是成熟读取模式下 ReadConsole 调用上该行为的扩充。在 CONSOLE_READCONSOLE_CONTROL 结构上的 dwCtrlWakeupMask 中设置标志并在调用 ReadConsole 时将其传递给 pinputControl，将导致读取操作不必等待换行，而是在指定字符时也返回结果。

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
Header	ConsoleApi.h (via WinCon.h, include Windows.h)
库	Kernel32.lib
DLL	Kernel32.dll
Unicode 和 ANSI 名称	ReadConsoleW (Unicode) 和 ReadConsoleA (ANSI)