Função WriteConsole
Grava uma cadeia de caracteres em um buffer da tela do console começando na localização atual do cursor.
Sintaxe
BOOL WINAPI WriteConsole(
_In_ HANDLE hConsoleOutput,
_In_ const VOID *lpBuffer,
_In_ DWORD nNumberOfCharsToWrite,
_Out_opt_ LPDWORD lpNumberOfCharsWritten,
_Reserved_ LPVOID lpReserved
);
Parâmetros
hConsoleOutput [in]
Um identificador do buffer da tela do console. O identificador deve ter o direito de acesso GENERIC_WRITE. Para saber mais, confira Segurança de buffer e direitos de acesso do console.
lpBuffer [in]
Um ponteiro para um buffer que contém os caracteres a serem gravados no buffer da tela do console. Espera-se que seja uma matriz de char para WriteConsoleA ou de wchar_t para WriteConsoleW.
nNumberOfCharsToWrite [in]
O número de caracteres a serem gravados. Se o tamanho total do número de caracteres especificado exceder o heap disponível, a função falhará com ERROR_NOT_ENOUGH_MEMORY.
lpNumberOfCharsWritten [out, opcional]
Um ponteiro para uma variável que recebe o número de caracteres de fato gravados.
lpReserved reservado; deve ser NULL.
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
A função WriteConsole grava caracteres no buffer da tela do console na posição atual do cursor. A posição do cursor avança conforme os caracteres são gravados. A função SetConsoleCursorPosition define a posição atual do cursor.
Os caracteres são gravados usando os atributos de cor do primeiro plano e da tela de fundo associados ao buffer da tela do console. A função SetConsoleTextAttribute altera essas cores. Para determinar os atributos de cor atuais e a posição atual do cursor, use GetConsoleScreenBufferInfo.
Todos os modos de entrada que afetam o comportamento da função WriteFile têm o mesmo efeito em WriteConsole. Para recuperar e definir os modos de saída de um buffer da tela do console, use as funções GetConsoleMode e SetConsoleMode.
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.
WriteConsole falhará se for usada com um identificador padrão que é redirecionado para um arquivo. Se um aplicativo processar uma saída multilíngue que pode ser redirecionada, determine se o identificador da saída é um identificador de console (um método é chamar a função GetConsoleMode e verificar se ela é bem-sucedida). Se o identificador for um identificador de console, chame WriteConsole. Se o identificador não for um identificador de console, a saída será redirecionada e você deverá chamar WriteFile executar a E/S. Certifique-se de prefixar um arquivo de texto sem formatação Unicode com uma marca de ordem de byte. Para obter mais informações, confira Usando marcas de ordem de byte.
Embora um aplicativo possa usar WriteConsole no modo ANSI para gravar caracteres ANSI, os consoles não dão suporte a sequências de "escape ANSI" ou de "terminal virtual", a menos que estejam habilitadas. Confira Sequências de terminais virtuais do console para obter mais informações e conhecer a aplicabilidade da versão do sistema operacional.
Quando as sequências de escape do terminal virtual não estão habilitadas, as funções de console podem fornecer funcionalidade equivalente. Para saber mais, confira SetCursorPos, SetConsoleTextAttribute e GetConsoleCursorInfo.
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 | WriteConsoleW (Unicode) e WriteConsoleA (ANSI) |