Função ReadConsole
Lê as entradas de caracteres do buffer de entrada do console e as remove do buffer.
Sintaxe
BOOL WINAPI ReadConsole(
_In_ HANDLE hConsoleInput,
_Out_ LPVOID lpBuffer,
_In_ DWORD nNumberOfCharsToRead,
_Out_ LPDWORD lpNumberOfCharsRead,
_In_opt_ LPVOID pInputControl
);
Parâmetros
hConsoleInput [in]
Um identificador do buffer da entrada 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 que recebe os dados lidos do buffer de entrada do console.
nNumberOfCharsToRead [in]
O número de caracteres a serem lidos. O tamanho do buffer apontado pelo parâmetro lpBuffer deve ser de pelo menos nNumberOfCharsToRead * sizeof(TCHAR) bytes.
lpNumberOfCharsRead [out]
Um ponteiro para uma variável que recebe o número de caracteres realmente lidos.
pInputControl [in, opcional]
Um ponteiro para uma estrutura CONSOLE_READCONSOLE_CONTROL que especifica um caractere de controle que sinalizará o final da operação de leitura. Este parâmetro pode ser NULO.
Esse parâmetro exige entrada Unicode por padrão. Para o modo ANSI, defina esse parâmetro como NULO.
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
O ReadConsole lê a entrada do teclado a partir do buffer de entrada do console. Seu comportamento é o mesmo da função ReadFile, exceto que ele pode ler em modo Unicode (caractere largo) ou ANSI. Para ter aplicativos que mantêm um único conjunto de fontes compatíveis com os dois modos, use ReadConsole em vez de ReadFile. Embora ReadConsole seja usado somente com um identificador de buffer de entrada do console, ReadFile pode ser usado com outros identificadores (como arquivos ou pipes). ReadConsole falhará se usado com um identificador padrão redirecionado para algo diferente de um identificador de console.
Todos os modos de entrada que afetam o comportamento de ReadFile afetam ReadConsole da mesma forma. Para recuperar e definir os modos de entrada de um buffer de entrada do console, use as funções GetConsoleMode e SetConsoleMode.
Se o buffer de entrada contiver eventos de entrada diferentes de eventos de teclado (como eventos de mouse ou eventos de redimensionamento de janela), eles serão descartados. Esses eventos podem ser lidos somente com a função ReadConsoleInput.
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.
O parâmetro pInputControl pode ser usado para habilitar ativações intermediárias da leitura em resposta a um caractere de controle de conclusão de arquivo especificado em uma estrutura CONSOLE_READCONSOLE_CONTROL. Esse recurso exige que as extensões de comando sejam habilitadas, que o identificador de saída padrão seja um identificador de saída do console e que a entrada seja Unicode.
Windows Server 2003 e Windows XP/2000: não há suporte para o recurso de leitura intermediário.
Modo processado é quando ENABLE_LINE_INPUT é definido com SetConsoleMode no identificador de entrada do console. No modo processado, o host do console fornece uma linha de edição em nome do aplicativo de linha de comando e as chamadas para ReadFile ou ReadConsole não retornam até que a tecla enter seja pressionada.
A Leitura Intermediária amplia esse comportamento na chamada do ReadConsole no modo de leitura processado. A definição de um sinalizador em dwCtrlWakeupMask na estrutura CONSOLE_READCONSOLE_CONTROL e sua passagem para pinputControl conforme chama ReadConsole, faz com que a leitura não necessariamente espere por uma nova linha e que retorne também em um caractere especificado.
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 | ConsoleApi.h (via WinCon.h, inclui o Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
| Nomes Unicode e ANSI | ReadConsoleW (Unicode) e ReadConsoleA (ANSI) |