Função CreateConsoleScreenBuffer

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.

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.

Exemplos

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

Requisitos

Confira também

Funções de Console

Buffers da tela do console

CloseHandle

DuplicateHandle

GetConsoleScreenBufferInfo

SECURITY_ATTRIBUTES

SetConsoleActiveScreenBuffer

SetConsoleScreenBufferSize