Funções de entrada e saída do console de alto nível

As funções ReadFile e WriteFile ou as funções ReadConsole e WriteConsole permitem que aplicativos leiam a entrada do console e gravem a saída do console como um fluxo de caracteres. ReadConsole e WriteConsole se comportam exatamente como ReadFile e WriteFile, exceto que podem ser usadas como funções de caracteres largos (nas quais os argumentos de texto devem usar Unicode) ou como funções ANSI (nas quais os argumentos de texto devem usar caracteres do conjunto de caracteres do Windows). Os aplicativos que precisam manter um único conjunto de fontes para oferecer suporte a Unicode ou ao conjunto de caracteres ANSI devem usar ReadConsole e WriteConsole.

ReadConsole e WriteConsole podem ser usadas somente com identificadores do console; ReadFile e WriteFile podem ser usadas com outros identificadores (como arquivos ou pipes). ReadConsole e WriteConsole falham se usadas com identificadores padrão redirecionados que já não são mais identificadores do console.

Para obter a entrada do teclado, processos podem usar ReadFile ou ReadConsole com um identificador para o buffer de entrada do console ou pode usar ReadFile para ler a entrada de um arquivo ou pipe, em caso de redirecionamento de STDIN. Essas funções retornam somente eventos de teclado que podem ser convertidos em caracteres ANSI ou Unicode. A entrada que pode ser retornada inclui combinações de teclas de controle. As funções não retornam eventos de teclado envolvendo as teclas de função ou teclas de direção. Os eventos de entrada gerados pela entrada do mouse, janela, foco ou menu são descartados.

Se o modo de entrada de linha estiver habilitado (modo padrão), ReadFile e ReadConsole não retornarão ao aplicativo de chamada até que a tecla ENTER seja pressionada. Se o modo de entrada de linha estiver desabilitado, as funções não retornarão até que pelo menos um caractere esteja disponível. Em ambos os modos, todos os caracteres disponíveis são lidos até o fim das teclas disponíveis ou até a leitura do número especificado de caracteres. Os caracteres não lidos são armazenados em buffer até a próxima operação de leitura. As funções informam o número total de caracteres realmente lidos. Se o modo de entrada de eco estiver habilitado, os caracteres lidos por essas funções serão gravados no buffer de tela ativo na posição atual do cursor.

Processos podem usar WriteFile ou WriteConsole para gravar em um buffer de tela ativo ou inativo, ou podem usar WriteFile para gravar em um arquivo ou pipe em caso de redirecionamento de STDOUT. O modo de saída processado e a quebra automática no modo de saída EOL controlam a maneira como os caracteres são gravados ou ecoados em um buffer de tela.

Os caracteres escritos por WriteFile ou WriteConsole ou ecoados por ReadFile ou ReadConsole são inseridos em um buffer de tela na posição atual do cursor. À medida que cada caractere é escrito, a posição do cursor avança para a próxima célula de caractere; porém, o comportamento no final de uma linha depende da quebra do buffer da tela do console no modo de saída EOL.

Mais detalhes sobre a posição do cursor podem ser encontrados por meio de sequências de terminais virtuais, especificamente na categoria de estado de consulta para encontrar a posição atual e na categoria de posicionamento do cursor para definir a posição atual. Como alternativa, aplicativos podem usar a função GetConsoleScreenBufferInfo para determinar a posição atual do cursor e a função SetConsoleCursorPosition para definir a posição do cursor. No entanto, o mecanismo de sequências de terminais virtuais é preferido para todo o desenvolvimento novo e em andamento. Mais detalhes sobre a estratégia dessa decisão podem ser encontrados na documentação de funções clássicas versus terminal virtual e do roteiro do ecossistema.

Para obter um exemplo que usa as funções de E/S de console de alto nível, confira Usar as funções de entrada e saída de alto nível.