WriteConsole 函数

从当前光标位置开始,将字符串写入控制台屏幕缓冲区。

语法

BOOL WINAPI WriteConsole(
  _In_             HANDLE  hConsoleOutput,
  _In_       const VOID    *lpBuffer,
  _In_             DWORD   nNumberOfCharsToWrite,
  _Out_opt_        LPDWORD lpNumberOfCharsWritten,
  _Reserved_       LPVOID  lpReserved
);

参数

hConsoleOutput [进]
控制台屏幕缓冲区的句柄。 此句柄必须具有 GENERIC_WRITE 访问权限。 有关详细信息,请参阅控制台缓冲区安全性和访问权限

lpBuffer [进]
指向缓冲区的指针,该缓冲区包含要写入控制台屏幕缓冲区的字符。 这应为 WriteConsoleAchar 数组,或 WriteConsoleWwchar_t 数组。

nNumberOfCharsToWrite [进]
将要写入的字符数。 如果指定数量的字符的总大小超过可用堆,则函数将失败并出现 ERROR_NOT_ENOUGH_MEMORY。

lpNumberOfCharsWritten [出,可选]
指向某个变量的指针,该变量接收实际写入的字符数。

lpReserved 保留;必须为 NULL。

返回值

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

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

备注

WriteConsole 函数将字符写入控制台屏幕缓冲区中的当前光标位置。 写入字符时,光标位置会前移。 SetConsoleCursorPosition 函数设置当前光标位置。

字符使用与控制台屏幕缓冲区关联的前景色和背景色属性进行写入。 SetConsoleTextAttribute 函数更改这些颜色。 若要确定当前颜色属性和当前光标位置,请使用 GetConsoleScreenBufferInfo

影响 WriteFile 函数行为的所有输入模式对于 WriteConsole 都具有相同的效果 。 若要检索和设置控制台屏幕缓冲区的输出模式,请使用 GetConsoleModeSetConsoleMode 函数 。

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

如果 WriteConsole 与重定向到某个文件的标准句柄一起使用,则会失败。 如果应用程序处理可重定向的多语言输出,请确定输出句柄是否为控制台句柄(一种方法是调用 GetConsoleMode 函数并检查是否成功)。 如果该句柄为控制台句柄,请调用 WriteConsole。 如果该句柄不是控制台句柄,则会重定向输出,应调用 WriteFile 来执行 I/O。 请确保使用字节顺序标记作为 Unicode 纯文本文件的前缀。 有关详细信息,请参阅使用字节顺序标记

尽管应用程序可使用 ANSI 模式下 WriteConsole 来写入 ANSI 字符,但控制台并不支持“ANSI 转义”或“虚拟终端”序列(除非启用)。 有关详细信息和操作系统版本适用性,请参阅控制台虚拟终端序列

如果未启用虚拟终端转义序列,控制台函数可提供等效功能。 有关详细信息,请参阅 SetCursorPosSetConsoleTextAttributeGetConsoleCursorInfo

要求

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

另请参阅

控制台函数

GetConsoleCursorInfo

GetConsoleMode

GetConsoleScreenBufferInfo

输入和输出方法

ReadConsole

SetConsoleCP

SetConsoleCursorPosition

SetConsoleMode

SetConsoleOutputCP

SetConsoleTextAttribute

SetCursorPos

WriteFile