ReadConsoleOutput

BOOL ReadConsoleOutput(hConsoleOutput, pchiDestBuffer, coordDestBufferSize, coordDestBufferCoord, psrctSourceRect)
HANDLE hConsoleOutput;	/* identifies console output buffer	*/
PCHAR_INFO pchiDestBuffer;	/* points to buffer that receives data	*/
COORD coordDestBufferSize;	/* column/row size of destination buffer	*/
COORD coordDestBufferCoord;	/* upper-left cell to write to in dest	*/
PSMALL_RECT psrctSourceRect;	/* screen buffer rectangle to read from	*/

The ReadConsoleOutput function reads character and color attribute data from a specified rectangular block of character cells in a console screen buffer, and writes the data into a rectangular block at a specified location of the destination buffer.

Parameters

hConsoleOutput

Specifies an open handle to a console screen buffer from which to read. The handle must have GENERIC_READ access.

pchiDestBuffer

Points to the buffer to receive the data read from the screen buffer. This pointer is treated as the origin of a two dimensional array of CHAR_INFO whose size is specified by coordDestBufferSize.

The CHAR_INFO data structure has the following format:

typedef struct _CHAR_INFO { /* chi */

union {

WCHAR UnicodeChar;

CHAR AsciiChar;

} Char;

WORD Attributes;

} CHAR_INFO, *PCHAR_INFO;

coordDestBufferSize

Specifies the size in character cells of pchiDestBuffer. The X member of the COORD structure is the number of columns; and the Y member is the number of rows.

The COORD data structure has the following format:

typedef struct _COORD { /* coord */

SHORT X; /* horizontal coordinate */

SHORT Y; /* vertical coordinate */

} COORD, *PCOORD;

coordDestBufferCoord

Specifies the coordinates of the upper-left cell in pchiDestBuffer to receive the data read from the screen buffer. The X member of the structure is the column, and the Y member is the row.

psrctSourceRect

Points to a SMALL_RECT structure. On input the structure members specify the upper-left and lower-right coordinates of the screen buffer rectangle from which to read. On output, the structure members specify the actual rectangle that was read.

The SMALL_RECT data structure has the following format:

typedef struct _SMALL_RECT { /* srct */

SHORT Left;

SHORT Top;

SHORT Right;

SHORT Bottom;

} SMALL_RECT, *PSMALL_RECT;

Return Value

The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.

Comments

The ReadConsoleOutput function treats the screen buffer and the destination buffer as two-dimensional arrays (columns and rows of character cells). The psrctSourceRect rectangle specifies the size and location of the block to read from in the screen buffer. A destination rectangle of the same size is located with its upper-left cell at coordDestBufferCoord in the pchiDestBuffer array. Data read from the cells in the screen buffer SourceRect is copied to the corresponding cells in the DestBuffer. Where the corresponding cell is outside the boundaries of the DestBuffer rectangle (whose dimensions are specified in coordSrcBufferSize) the data is not copied. Cells in the DestBuffer corresponding to coordinates that are not within the boundaries of the screen buffer are left unchanged (in other words, these are the cells for which there is no screen buffer data available to be read).

When the function returns, the members of psrctSourceRect have been set to the actual screen buffer rectangle whose cells were copied into the DestBuffer. This reflects the cells in the SourceRect for which there existed a corresponding cell in the DestBuffer; and it clips the dimensions of the SourceRect to the boundaries of the screen buffer.

If the rectangle specified by psrctSourceRect lies completely outside the boundaries of the screen buffer, or if the corresponding rectangle is positioned completely outside the boundaries of the DestBuffer, no data is copied. In this case, the function returns with the members of psrctSourceRect set such that the Right member is less than the Left, or the Bottom member is less than the Top.

The ReadConsoleOutput function has no effect on the cursor position. The contents of the screen buffer are not changed by the function.

The ReadConsoleOutput function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).

Example

This example illustrates how ReadConsoleOutput acts when the SourceRect extends beyond the boundaries of the screen buffer.

Assume that the screen buffer is 10 rows high, 10 columns wide, and that the rectangle pointed to by psrctSourceRect has its members set as follows: Left = -2, Top = 3, Right = 4, and Bottom = 6. This extends the SourceRect beyond the left edge of the screen buffer. Assume that the size of the DestBuffer is 10 rows by 10 columns (coordDestBufferSize = (10, 10)), and that coordDestBufferCoord is set to (0, 0).

The rectangle in the DestBuffer corresponding to SourceRect in the screen buffer would be: Left = 0, Top = 0, Right = 6, and Bottom = 3. But because the SourceRect extends beyond the boundaries of the screen buffer, data would be copied only to the following region of the DestBuffer: Left=2, Top=0, Right=6, and Bottom=3. The clipped region of the DestBuffer (Left=0, Top=0, Right=2, and Bottom=3) would be left untouched.