Ler em inglês

Compartilhar via


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)

Confira também

Funções de Console

GetConsoleCursorInfo

GetConsoleMode

GetConsoleScreenBufferInfo

Métodos de entrada e saída

ReadConsole

SetConsoleCP

SetConsoleCursorPosition

SetConsoleMode

SetConsoleOutputCP

SetConsoleTextAttribute

SetCursorPos

WriteFile