Função CreateConsoleScreenBuffer

Artigo
12/28/2023

Importante

Este documento descreve a funcionalidade da plataforma de console que não faz mais parte do nosso roteiro do ecossistema. Não recomendamos o uso desse conteúdo em novos produtos, mas continuaremos a oferecer suporte aos usos existentes por tempo indeterminado. Nossa solução moderna preferida se concentra em sequências de terminais virtuais para máxima compatibilidade em cenários de multiplataforma. Você pode encontrar mais informações sobre essa decisão de design em nosso documento Console clássico versus terminal virtual.

Cria um buffer de tela do console.

Sintaxe

HANDLE WINAPI CreateConsoleScreenBuffer(
  _In_             DWORD               dwDesiredAccess,
  _In_             DWORD               dwShareMode,
  _In_opt_   const SECURITY_ATTRIBUTES *lpSecurityAttributes,
  _In_             DWORD               dwFlags,
  _Reserved_       LPVOID              lpScreenBufferData
);

Parâmetros

dwDesiredAccess [in]
O acesso ao buffer da tela do console. Para ver uma lista de direitos de acesso, consulte Segurança de buffer e direitos de acesso do console.

dwShareMode [in]
Esse parâmetro pode ser zero, indicando que o buffer não pode ser compartilhado, ou pode ser um ou mais dos valores a seguir.

Valor	Significado
FILE_SHARE_READ 0x00000001	Outras operações abertas podem ser realizadas no buffer da tela do console para acesso de leitura.
FILE_SHARE_WRITE 0x00000002	Outras operações abertas podem ser realizadas no buffer da tela do console para acesso de gravação.

lpSecurityAttributes [in, opcional]
Um ponteiro para uma estrutura SECURITY_ATTRIBUTES que determina se o identificador retornado pode ser herdado por processos filhos. Se lpSecurityAttributes for NULL, o indicador não poderá ser herdado. O membro lpSecurityDescriptor da estrutura especifica um descritor de segurança para o novo buffer de tela do console. Se lpSecurityAttributes for NULL, o buffer de tela do console obterá um descritor de segurança padrão. As ACLs no descritor de segurança padrão para um buffer de tela de console vêm do token primário ou de representação do criador.

dwFlags [in]
O tipo de buffer de tela do console a ser criado. O único tipo de buffer de tela com suporte é CONSOLE_TEXTMODE_BUFFER.

lpScreenBufferData
Reservado; deve ser NULL.

Valor retornado

Se a função obtiver êxito, o valor retornado será um identificador para o novo buffer de tela do console.

Se houver falha na função, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Um console pode ter múltiplos buffers de tela, mas somente um buffer de tela ativo. Os buffers de tela inativos podem ser acessados para leitura e gravação, mas somente o buffer de tela ativa é exibido. Para tornar o novo buffer de tela ativo, use a função SetConsoleActiveScreenBuffer.

O buffer de tela recém-criado copiará algumas propriedades do buffer de tela ativo quando essa função for chamada. O comportamento é o seguinte:

Font – copiada do buffer de tela ativo
Display Window Size – copiada do buffer de tela ativo
Buffer Size – correspondente ao Display Window Size (NÃO copiado)
Default Attributes (cores) – copiados do buffer de tela ativo
Default Popup Attributes (cores) – copiados do buffer de tela ativo

O processo de chamada pode usar o identificador retornado em qualquer função que exija um identificador para um buffer de tela do console, de acordo com as limitações de acesso especificadas pelo parâmetro dwDesiredAccess.

O processo pode usar a função DuplicateHandle para criar um identificador de buffer de tela duplicado com acesso ou capacidade de herança diferente do identificador original. No entanto, DuplicateHandle não pode ser usado para criar uma duplicata válida para um processo diferente (exceto por herança).

Para fechar o identificador de buffer de tela do console, use a função CloseHandle.

Dica

Essa API não é recomendada, mas tem um terminal virtual equivalente aproximado na sequência de buffer de tela alternativo. A definição do buffer de tela alternativo pode fornecer um espaço separado e isolado a um aplicativo para desenho ao longo do tempo de execução de sessão, preservando o conteúdo exibido pelo invocador do aplicativo. Isso mantém as informações de desenho para restauração simples na saída do processo.

Exemplos

Para ver um exemplo, Ler e gravar blocos de caracteres e atributos.

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	ConsoleApi2.h (via WinCon.h, inclui o Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll