Função ReadConsoleOutput

Artigo
12/28/2023

Importante

Este documento descreve a funcionalidade da plataforma do console que não faz mais parte do nosso roteiro de ecossistema. Não recomendamos o uso desse conteúdo em novos produtos, mas continuaremos a oferecer suporte aos usos existentes por tempo indeterminado. Nossa solução moderna preferida se concentra em sequências de terminais virtuais para máxima compatibilidade em cenários de multiplataforma. Você pode encontrar mais informações sobre essa decisão de design em nosso documento Console clássico versus terminal virtual.

Lê dados de atributos de caracteres e de cores de um bloco retangular de células de caracteres em um buffer de tela do console; a função grava os dados em um bloco retangular em um local especificado no buffer de destino.

Sintaxe

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

Parâmetros

hConsoleOutput [in]
Um identificador do buffer da tela do console. O identificador deve ter o direito de acesso GENERIC_READ. Para saber mais, confira Segurança de buffer e direitos de acesso do console.

lpBuffer [out]
Um ponteiro para um buffer de destino que recebe os dados lidos do buffer de tela do console. Esse ponteiro é tratado como a origem de uma matriz bidimensional de estruturas CHAR_INFO cujo tamanho é especificado pelo parâmetro dwBufferSize.

dwBufferSize [in]
O tamanho do parâmetro lpBuffer, em células de caracteres. O membro X da estrutura COORD é o número de colunas, o membro Y é o número de linhas.

dwBufferCoord [in]
As coordenadas da célula superior esquerda no parâmetro lpBuffer que recebe os dados lidos do buffer da tela do console. O membro X da estrutura COORD é a coluna e o membro Y é a linha.

lpReadRegion [in, out]
Um ponteiro para uma estrutura SMALL_RECT. Na entrada, os membros da estrutura especificam as coordenadas superior esquerdas e inferior direitas do retângulo do buffer da tela do console para leitura da função. Na saída, os membros da estrutura especificam o retângulo real que foi usado.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

ReadConsoleOutput trata o buffer de tela do console e o buffer de destino como matrizes bidimensionais (colunas e linhas de células de caracteres). O retângulo apontado pelo parâmetro lpReadRegion especifica o tamanho e o local do bloco a ser lido do buffer da tela do console. Um retângulo de destino do mesmo tamanho está localizado com sua célula superior esquerda nas coordenadas do parâmetro dwBufferCoord na matriz lpBuffer. Os dados lidos das células no retângulo de origem do buffer da tela do console são copiados para as células correspondentes no buffer de destino. Se a célula correspondente estiver fora dos limites do retângulo do buffer de destino (cujas dimensões são especificadas pelo parâmetro dwBufferSize), os dados não serão copiados.

As células no buffer de destino correspondentes às coordenadas que não estão dentro dos limites do buffer da tela do console ficam inalteradas. Essas são as células para as quais nenhum dado de buffer de tela está disponível para leitura.

Antes do retorno de ReadConsoleOutput, ele define os membros da estrutura apontados pelo parâmetro lpReadRegion para o retângulo de buffer de tela real cujas células foram copiadas para o buffer de destino. Esse retângulo reflete as células no retângulo de origem para as quais havia uma célula correspondente no buffer de destino, pois ReadConsoleOutput corta as dimensões do retângulo de origem até os limites do buffer de tela do console.

Se o retângulo especificado por lpReadRegion estiver completamente fora dos limites do buffer de tela do console ou se o retângulo correspondente estiver posicionado totalmente fora dos limites do buffer de destino, nenhum dado será copiado. Nesse caso, a função retorna com os membros da estrutura apontados pelo conjunto de parâmetros lpReadRegion, de forma que o membro Right seja menor que o membro Left ou que o membro Bottom seja menor que o membro Top. Para determinar o tamanho do buffer de tela do console, use a função GetConsoleScreenBufferInfo.

A função ReadConsoleOutput não tem efeito na posição do cursor do buffer da tela do console. O conteúdo do buffer de tela do console não é alterado pela função.

Essa função usa caracteres Unicode ou caracteres de 8 bits da página de código atual do console. O padrão da página de código do console inicialmente é a página de código OEM do sistema. Para alterar a página de código do console, use as funções SetConsoleCP ou SetConsoleOutputCP. Os consumidores herdados também podem usar os comandos chcp ou mode con cp select=, mas eles não são recomendados para novos desenvolvimentos.

Dica

Essa API não é recomendada e não tem um equivalente de terminal virtual. Essa decisão intencionalmente alinha a plataforma do Windows com outros sistemas operacionais nos quais se espera que o aplicativo cliente individual se lembre do seu próprio estado desenhado para manipulação posterior. A comunicação remota de aplicativos por meio de utilitários multiplataforma e transportes como SSH pode não funcionar como esperado se estiver usando essa API.

Exemplos

Para ver um exemplo, confira Ler e gravar blocos de caracteres e atributos.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	ConsoleApi2.h (via WinCon.h, inclui o Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll
Nomes Unicode e ANSI	ReadConsoleOutputW (Unicode) e ReadConsoleOutputA (ANSI)