Функция ReadConsoleOutput

Статья
10/23/2023

Важно!

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

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

Синтаксис

BOOL WINAPI ReadConsoleOutput(
  _In_    HANDLE      hConsoleOutput,
  _Out_   PCHAR_INFO  lpBuffer,
  _In_    COORD       dwBufferSize,
  _In_    COORD       dwBufferCoord,
  _Inout_ PSMALL_RECT lpReadRegion
);

Параметры

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

lpBuffer [out]
Указатель на целевой буфер, который получает данные, считываемые из буфера экрана консоли. Этот указатель рассматривается как источник двухмерного массива CHAR_INFO структур, размер которого задается параметром dwBufferSize.

dwBufferSize [in]
Размер параметра lpBuffer в ячейках символов. Элемент X структуры COORD — это количество столбцов; элемент Y — это число строк.

dwBufferCoord [in]
Координаты левой верхней ячейки в параметре lpBuffer , получающем данные из буфера экрана консоли. Элемент X структуры COORD — это столбец, а элемент Y — строка.

lpReadRegion [in, out]
Указатель на структуру SMALL_RECT . Во входных данных члены структуры указывают координаты прямоугольника буфера экрана консоли в левом верхнем и нижнем углу, из которого требуется считывать функцию. В выходных данных члены структуры указывают фактический прямоугольник, который использовался.

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

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

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

Замечания

ReadConsoleOutput обрабатывает буфер экрана консоли и целевой буфер как двухмерные массивы (столбцы и строки символьных ячеек). Прямоугольник, на который указывает параметр lpReadRegion , указывает размер и расположение блока для чтения из буфера экрана консоли. Прямоугольник назначения с тем же размером расположен с левой верхней ячейкой в координатах параметра dwBufferCoord в массиве lpBuffer . Данные, считываемые из ячеек в исходном прямоугольнике буфера экрана консоли, копируются в соответствующие ячейки в целевом буфере. Если соответствующая ячейка находится за пределами прямоугольника буфера назначения (измерения которых указаны параметром dwBufferSize ), данные не копируются.

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

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

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

Функция ReadConsoleOutput не влияет на положение курсора буфера экрана консоли. Содержимое буфера экрана консоли не изменяется функцией.

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

Совет

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

Примеры

Пример см. в разделе "Чтение и запись блоков символов и атрибутов".

Requirements


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