Funções de entrada e saída do console High-Level

As funções ReadFile e WriteFile , ou as funções ReadConsole e WriteConsole , permitem que um aplicativo leia a entrada do console e grave a saída do console como um fluxo de caracteres. ReadConsole e WriteConsole se comportam exatamente como ReadFile e WriteFile, exceto que eles podem ser usados como funções de caracteres largos (em que argumentos de texto devem usar Unicode) ou como funções ANSI (em que 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 só podem ser usados com alças de console; ReadFile e WriteFile podem ser usados com outras alças (como arquivos ou pipes). ReadConsole e WriteConsole falham se usados com um identificador padrão que foi redirecionado e não é mais um identificador de console.

Para obter a entrada do teclado, um processo pode 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, se STDIN tiver sido redirecionado. Essas funções retornam apenas eventos de teclado que podem ser traduzidos 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 do teclado envolvendo as teclas de função ou teclas de seta. Os eventos de entrada gerados pela entrada do mouse, janela, foco ou menu são descartados.

Se o modo de entrada de linha estiver ativado (o 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 desativado, 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é que não haja mais chaves disponíveis ou até que o número especificado de caracteres tenha sido lido. Os caracteres não lidos são armazenados em buffer até a próxima operação de leitura. As funções relatam o número total de caracteres realmente lidos. Se o modo de entrada de eco estiver ativado, os caracteres lidos por essas funções serão gravados no buffer de tela ativo na posição atual do cursor.

Um processo pode usar WriteFile ou WriteConsole para gravar em um buffer de tela ativo ou inativo, ou pode usar WriteFile para gravar em um arquivo ou pipe se o STDOUT tiver sido redirecionado. O modo de saída processado e o wrap no modo de saída EOL controlam a maneira como os caracteres são escritos 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 caracteres; no entanto, o comportamento no final de uma linha depende do wrap do buffer da tela do console no modo de saída EOL.

Mais detalhes sobre a posição do cursor podem ser encontrados através 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, um aplicativo pode 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 terminais virtuais é preferido para todos os desenvolvimentos novos e em curso. Mais detalhes sobre a estratégia por trás dessa decisão podem ser encontrados na documentação clássica de funções versus terminal virtual e roteiro do ecossistema .

Para obter um exemplo que usa as funções de E/S do console de alto nível, consulte Usando as funções de entrada e saída High-Level.