Função ReadConsoleOutputCharacter

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.

Copia um número de caracteres de células consecutivas de um buffer de tela do console, começando em um local especificado.

Sintaxe

BOOL WINAPI ReadConsoleOutputCharacter(
  _In_  HANDLE  hConsoleOutput,
  _Out_ LPTSTR  lpCharacter,
  _In_  DWORD   nLength,
  _In_  COORD   dwReadCoord,
  _Out_ LPDWORD lpNumberOfCharsRead
);

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.

lpCharacter [out]
Um ponteiro para um buffer que recebe os caracteres lidos do buffer de tela do console.

nLength [in]
O número de células de caracteres do buffer de tela para leitura. O tamanho do buffer apontado pelo parâmetro lpCharacter deve ser nLength * sizeof(TCHAR).

dwReadCoord [in]
As coordenadas da primeira célula no buffer de tela do console para leitura, em caracteres. O membro X da estrutura COORD é a coluna e o membro Y é a linha.

lpNumberOfCharsRead [out]
Um ponteiro para uma variável que recebe o número de caracteres realmente lidos.

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

Se o número de caracteres a serem lidos se estender além do final da linha de buffer de tela especificada, os caracteres serão lidos a partir da próxima linha. Se o número de caracteres a serem lidos se estender além do final do buffer de tela do console, os caracteres serão lidos até o final do buffer de tela do console.

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 terminal virtual equivalente. 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.

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	ReadConsoleOutputCharacterW (Unicode) e ReadConsoleOutputCharacterA (ANSI)