Функция CreateConsoleScreenBuffer

Статья
10/23/2023

Важно!

В этом документе описаны функции платформы консоли, которые больше не являются частью стратегии развития экосистемы. Мы не рекомендуем использовать это содержимое в новых продуктах, но мы будем продолжать поддерживать существующие использования для неопределенного будущего. Наше предпочтительное современное решение ориентировано на последовательности виртуальных терминалов для обеспечения максимальной совместимости в кроссплатформенных сценариях. Дополнительные сведения об этом решении по проектированию можно найти в классической консоли и в документе виртуального терминала .

Создает буфер экрана консоли.

Синтаксис

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

Параметры

dwDesiredAccess [in]
Доступ к буферу экрана консоли. Список прав доступа см. в разделе "Безопасность буфера консоли" и "Права доступа".

dwShareMode [in]
Этот параметр может быть равен нулю, указывая, что буфер не может быть общим или может быть одним или несколькими из следующих значений.

Значение	Значение
FILE_SHARE_READ 0x00000001	Другие открытые операции можно выполнять в буфере экрана консоли для доступа на чтение.
FILE_SHARE_WRITE 0x00000002	Другие открытые операции можно выполнять в буфере экрана консоли для доступа на запись.

lpSecurityAttributes [in, необязательный]
Указатель на структуру SECURITY_ATTRIBUTES , которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Если значение lpSecurityAttributes равно NULL, дескриптор не может быть унаследован. Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового буфера экрана консоли. Если значение lpSecurityAttributes равно NULL, буфер экрана консоли получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для буфера экрана консоли приходят из основного или олицетворения маркера создателя.

dwFlags [in]
Тип создаваемого буфера экрана консоли. Единственным поддерживаемым типом буфера экрана является CONSOLE_TEXTMODE_BUFFER.

lpScreenBufferData
Защищены; должно иметь значение NULL.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение является дескриптором нового буфера экрана консоли.

Если функция завершается неудачно, возвращается значение INVALID_HANDLE_VALUE. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Замечания

Консоль может иметь несколько буферов экрана, но только один активный буфер экрана. К неактивным буферам экрана можно обращаться для чтения и записи, но отображается только активный буфер экрана. Чтобы создать буфер экрана активным буфером экрана, используйте функцию SetConsoleActiveScreenBuffer .

Созданный буфер экрана будет копировать некоторые свойства из активного буфера экрана во время вызова этой функции. Поведение выглядит следующим образом:

Font — скопировано из активного буфера экрана
Display Window Size — скопировано из активного буфера экрана
Buffer Size — сопоставлено Display Window Size с (НЕ скопировано)
Default Attributes (цвета) — скопировано из активного буфера экрана
Default Popup Attributes (цвета) — скопировано из активного буфера экрана

Вызывающий процесс может использовать возвращенный дескриптор в любой функции, требующей дескриптора в буфер экрана консоли, при условии ограничений доступа, указанных параметром dwDesiredAccess .

Вызывающий процесс может использовать функцию DuplicateHandle для создания повторяющегося дескриптора буфера экрана, имеющего другой доступ или наследование от исходного дескриптора. Однако для создания дубликата, допустимого для другого процесса (за исключением наследования), нельзя использовать Дубликат.

Чтобы закрыть дескриптор буфера экрана консоли, используйте функцию CloseHandle .

Совет

Этот API не рекомендуется, но он имеет приблизительный виртуальный терминал эквивалент в альтернативной последовательности буфера экрана. Настройка альтернативного буфера экрана может предоставить приложению отдельное изолированное пространство для рисования в течение среды выполнения сеанса при сохранении содержимого, отображаемого вызывающим объектом приложения. Это сохраняет, что рисование сведений для простого восстановления при выходе процесса.

Примеры

Пример см. в разделе "Чтение и запись блоков символов и атрибутов".

Requirements


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Верхний колонтитул	ConsoleApi2.h (через WinCon.h, включая Windows.h)
Библиотека	Kernel32.lib
DLL-библиотеки	Kernel32.dll