Функция WriteConsoleOutputCharacter

Статья
12/13/2023

Важно!

В этом документе описаны функции платформы консоли, которые больше не являются частью стратегии развития экосистемы. Мы не рекомендуем использовать это содержимое в новых продуктах, но мы будем продолжать поддерживать существующие использования для неопределенного будущего. Наше предпочтительное современное решение ориентировано на последовательности виртуальных терминалов для обеспечения максимальной совместимости в кроссплатформенных сценариях. Дополнительные сведения об этом решении по проектированию можно найти в классической консоли и в документе виртуального терминала .

Копирует ряд символов в последовательные ячейки буфера экрана консоли, начиная с указанного расположения.

Синтаксис

BOOL WINAPI WriteConsoleOutputCharacter(
  _In_  HANDLE  hConsoleOutput,
  _In_  LPCTSTR lpCharacter,
  _In_  DWORD   nLength,
  _In_  COORD   dwWriteCoord,
  _Out_ LPDWORD lpNumberOfCharsWritten
);

Параметры

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

lpCharacter [in]
Символы, записываемые в буфер экрана консоли.

nLength [in]
Количество записываемых символов.

dwWriteCoord [in]
Структура COORD, указывающая координаты символов первой ячейки в буфере экрана консоли, в которую будут записываться символы.

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

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

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

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

Замечания

Если число символов, записываемых в конец указанной строки в буфере экрана консоли, символы записываются в следующую строку. Если число символов, записываемых в буфер экрана консоли, выходит за пределы буфера экрана консоли, символы записываются до конца буфера экрана консоли.

Значения атрибутов на позициях, записанных в не изменяемые.

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

Совет

Этот API имеет эквивалент виртуального терминала в последовательностях форматирования текста и размещения курсоров. Переместите курсор в расположение для вставки, примените требуемое форматирование и запишите текст для заполнения. Нет эквивалента отправки текста в область без применения активного форматирования цвета. Это решение намеренно выравнивает платформу Windows с другими операционными системами, где отдельное клиентское приложение, как ожидается, запоминает собственное состояние рисования для дальнейшего управления.

Requirements


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