Функция WriteConsole

Статья
07/12/2023

Записывает строку символов в буфер экрана консоли, начиная с текущего положения курсора.

Синтаксис

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

Параметры

hConsoleOutput [ввод]
Дескриптор буфера экрана консоли. У дескриптора должно быть право на доступ GENERIC_WRITE. Дополнительные сведения см. в статье Безопасность и права доступа для буфера консоли.

lpBuffer [ввод]
Указатель на буфер, содержащий символы для записи в буфер экрана консоли. Предполагается, что это массив char для WriteConsoleA или wchar_t для WriteConsoleW.

nNumberOfCharsToWrite [ввод]
Количество записываемых символов. Если общий размер указанного количества символов превышает доступную кучу, функция завершается ошибкой ERROR_NOT_ENOUGH_MEMORY.

lpNumberOfCharsWritten [вывод, необязательный]
Указатель на переменную, которая получает количество фактически записанных символов.

lpReserved Зарезервировано; должно быть значение NULL.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Замечания

Функция WriteConsole записывает символы в буфер экрана консоли в текущем положении курсора. Курсор передвигается по мере написания символов. Функция SetConsoleCursorPosition задает текущее положение курсора.

Символы записываются с помощью атрибутов цвета переднего плана и фона, связанных с буфером экрана консоли. Функция SetConsoleTextAttribute изменяет эти цвета. Чтобы определить текущие атрибуты цвета и текущее положение курсора, используйте GetConsoleScreenBufferInfo.

Все режимы ввода, влияющие на поведение функции WriteFile, действуют так же на WriteConsole. Чтобы получить и установить режимы вывода буфера экрана консоли, используйте функции GetConsoleMode и SetConsoleMode.

Эта функция использует либо символы Юникода, либо 8-разрядные символы из текущей кодовой страницы консоли. Кодовая страница консоли по умолчанию изначально соответствует кодовой странице OEM системы. Чтобы изменить кодовую страницу консоли, используйте функции SetConsoleCP или SetConsoleOutputCP. Пользователи прежних версий могут также использовать команды chcp или mode con cp select= (но это не рекомендуется для новой разработки).

WriteConsole завершается ошибкой, если используется со стандартным дескриптором, который перенаправляется в файл. Если приложение обрабатывает многоязычный вывод, который можно перенаправить, определите, является ли дескриптор вывода дескриптором консоли (один метод заключается в вызове функции GetConsoleMode и проверке успешности ее выполнения). Если дескриптор является дескриптором консоли, вызовите WriteConsole. Если дескриптор не является дескриптором консоли, вывод перенаправляется и для выполнения операций ввода-вывода следует вызвать WriteFile. Обязательно добавьте в обычный текстовый файл в Юникоде метку порядка следования байтов в качестве префикса. Дополнительные сведения см. в статье Использование меток порядка следования байтов.

Несмотря на то что приложение может использовать WriteConsole в режиме ANSI для записи символов ANSI, консоли не поддерживают последовательности escape-кодов ANSI или виртуальных терминалов, если они не включены. Дополнительные сведения, а также информацию о применимости к версии операционной системы см. в статье Последовательности виртуального терминала в консоли.

Если escape-последовательности виртуального терминала не включены, функции консоли могут обеспечить эквивалентную функциональность. Дополнительные сведения см. в статьях о функциях SetCursorPos, SetConsoleTextAttribute и GetConsoleCursorInfo.

Requirements


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Верхний колонтитул	ConsoleApi.h (через WinCon.h, включая Windows.h)
Библиотека	Kernel32.lib
DLL-библиотеки	Kernel32.dll
Имена Юникода и ANSI	WriteConsoleW (Юникод) и WriteConsoleA (ANSI)