ReadConsoleOutput 函式

發行項
12/13/2023

重要

本文件說明已不再是生態系統藍圖一部分的控制台平臺功能。我們不建議您在新產品中使用此內容，但我們將繼續支持無限期的未來現有使用量。我們慣用的新式解決方案著重於 虛擬終端機序列 ，以在跨平臺案例中達到最大相容性。您可以在傳統 主控台與虛擬終端機 檔中找到此設計決策的詳細資訊。

從主控台畫面緩衝區中字元儲存格的矩形區塊讀取字元和色彩屬性數據，且函式會將數據寫入目的地緩衝區中指定位置的矩形區塊。

語法

BOOL WINAPI ReadConsoleOutput(
  _In_    HANDLE      hConsoleOutput,
  _Out_   PCHAR_INFO  lpBuffer,
  _In_    COORD       dwBufferSize,
  _In_    COORD       dwBufferCoord,
  _Inout_ PSMALL_RECT lpReadRegion
);

參數

hConsoleOutput [in]
主控台螢幕緩衝區的控點。句柄必須具有 GENERIC_READ 訪問許可權。如需詳細資訊，請參閱主控台緩衝區安全性和存取權限。

lpBuffer [out]
接收從控制台畫面緩衝區讀取之數據的目的地緩衝區指標。這個指標會被視為 CHAR_INFO由 dwBufferSize 參數指定大小之結構之二維陣列的原點。

dwBufferSize [in]
字元儲存格中 lpBuffer 參數的大小。 COORD 結構的 X 成員是數據行數目;Y 成員是數據列數目。

dwBufferCoord [in]
lpBuffer 參數中左上方儲存格的座標，接收從控制台畫面緩衝區讀取的數據。 COORD 結構的 X 成員是數據行，而 Y 成員則是數據列。

lpReadRegion [in， out]
SMALL_RECT 結構的指標。在輸入時，結構成員會指定要從中讀取函式之控制台畫面緩衝區矩形的左上方和右下角座標。在輸出中，結構成員會指定使用的實際矩形。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

ReadConsoleOutput 會將控制台畫面緩衝區和目的地緩衝區視為二維陣列（字元單元格的數據行和數據列）。 lpReadRegion 參數所指向的矩形會指定要從控制台畫面緩衝區讀取之區塊的大小和位置。相同大小的目的地矩形位於 lpBuffer 陣列中 dwBufferCoord 參數座標處的左上方儲存格。從主控台畫面緩衝區來源矩形中的儲存格讀取的數據會複製到目的地緩衝區中的對應儲存格。如果對應的儲存格超出目的緩衝區矩形的界限（其維度是由 dwBufferSize 參數指定），則不會複製數據。

目的地緩衝區中對應到不在控制台畫面緩衝區界限內的座標的資料格會保持不變。換句話說，這些是沒有可供讀取螢幕緩衝區數據的單元格。

在 ReadConsoleOutput 傳回之前，它會將 lpReadRegion 參數指向的結構成員設定為實際螢幕緩衝區矩形，其單元格已複製到目的地緩衝區。這個矩形會反映來源矩形中的單元格， 因為 ReadConsoleOutput 會裁剪來源矩形的維度以符合控制台畫面緩衝區的界限。

如果 lpReadRegion 所指定的矩形完全位於控制台畫面緩衝區的界限之外，或者如果對應的矩形完全位於目的地緩衝區的界限之外，則不會複製任何數據。在此情況下，函式會傳回具有 lpReadRegion 參數所指向之結構的成員，讓 Right 成員小於 Left，或 Bottom 成員小於 Top。 若要判斷主控台畫面緩衝區的大小，請使用 GetConsoleScreenBufferInfo 函式。

ReadConsoleOutput 函式不會影響控制台畫面緩衝區的數據指標位置。函式不會變更控制台畫面緩衝區的內容。

此函式會從主控台的目前字碼頁使用 Unicode 字元或 8 位元字元。主控台的字碼頁一開始會預設為系統的 OEM 字碼頁。若要變更控制台的字碼頁，請使用 SetConsoleCP 或 SetConsoleOutputCP 函式。舊版取用者也可以使用 chcp 或 mode con cp select= 命令，但不建議用於新的開發。

提示

不建議使用此 API，而且沒有 虛擬終端機 對等專案。此決策會刻意讓 Windows 平臺與其他作業系統保持一致，其中個別用戶端應用程式預期會記住自己的繪製狀態，以便進一步操作。透過跨平臺公用程式和 SSH 之類的傳輸進行遠端處理的應用程式在使用這個 API 時可能無法如預期般運作。

範例

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

需求


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