CreateConsoleScreenBuffer 函式

發行項
12/13/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， optional]
SECURITY_ATTRIBUTES 結構的指標，決定傳回的句柄是否可以由子進程繼承。如果 lpSecurityAttributes 為 NULL，則無法繼承句柄。結構的 lpSecurityDescriptor 成員會指定新控制台畫面緩衝區的安全性描述元。如果 lpSecurityAttributes 為 NULL，控制台畫面緩衝區會取得預設的安全性描述元。控制台畫面緩衝區的預設安全性描述元中的 ACL 來自建立者的主要或模擬令牌。

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 函式來建立重複的螢幕緩衝區句柄，該句柄具有不同存取權或可繼承性的原始句柄。不過， DuplicateHandle 無法用來建立對不同進程有效的重複專案（但透過繼承除外）。

若要關閉主控台畫面緩衝區句柄，請使用 CloseHandle 函 式。

提示

不建議使用此 API，但它在替代螢幕緩衝區序列中具有近似虛擬終端機對等專案。 設定替代畫面緩衝區可為應用程式提供個別的隔離空間，以在其會話運行時間過程中繪製，同時保留應用程式叫用者所顯示的內容。這會維護在進程結束時簡單還原的繪圖資訊。

範例

如需範例，請參閱讀取和寫入字元和屬性區塊。

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
頁首	ConsoleApi2.h （透過 WinCon.h，包含 Windows.h）
程式庫	Kernel32.lib
DLL	Kernel32.dll