Функция ReadConsoleOutput

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

Синтаксис

BOOL ReadConsoleOutput(

HANDLE hConsoleOutput,   // дескриптор экранного буфера
PCHAR_INFO
lpBuffer,     // буфер данных
COORD
dwBufferSize,      // размер буфера в сроках колонок
COORD
dwBufferCoord,     // левая верхняя ячейка для записи
PSMALL_RECT
lpReadRegion // прямоугольник чтения

);

Параметры

hConsoleOutput

[in] Дескриптор экранного буфера консоли. Дескриптор должен иметь право доступа GENERIC_READ. Для получения дополнительной информации, см. статью Защита буфера и права доступа в консоли.

lpBuffer

[out] Указатель на буфер назначения, который принимает чтение данных из экранного буфера консоли. Этот указатель рассматривается как начало двухмерного массива структур CHAR_INFO, размер которых указан параметром dwBufferSize. Общий размер массива должен быть меньше чем 64КБ

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 , которое устанавливает так, что член Right является меньше чем Left , или член Bottom - меньше чем Top. Чтобы выяснять размер экранного буфера консоли, используйте функцию GetConsoleScreenBufferInfo.

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

Windows NT /2000/XP: эта функция использует или символы Unicode или 8-разрядные символы от текущей кодовой страницы консоли. Кодовая страница консоли вначале устанавливается по умолчанию как системная кодовая страница (OEM). Чтобы изменить кодовую страницу консоли, используйте функции SetConsoleCP или SetConsoleOutputCP, или используйте команды chcp или mode con cp select =.

Windows 95/98/Me: функция ReadConsoleOutputW поддерживает Microsoft Layer for Unicode. Чтобы использовать его, Вы должны добавить некоторые файлы к вашему приложению, как изложено в Microsoft Layer for Unicode для систем Windows 95/98/Me.

Код примера

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

Смотри также

Обзор консольных приложений, Функции консоли, CHAR_INFO, COORD, ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, SetConsoleCP, SetConsoleOutputCP, SMALL_RECT, WriteConsoleOutput

Размещение и совместимость ReadConsoleOutput

Windows. NET Server

Да

Windows XP

Да

Windows 2000

Да

Windows NT

Да

Windows Me

Да

Windows 98

Да

Windows 95

Да

Используемая библиотека

Kernel32.lib

Заголовочный файл

 

- объявлено в

Wincon.h

- включено в

Windows.h

Unicode

Реализуется как Unicode и ANSI в версиях Windows NT/2000/XP. А также поддерживает Microsoft Layer for Unicode

Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz