WriteConsole 函式

發行項
12/13/2023

從目前的游標位置開始，將字元字串寫入主控台螢幕緩衝區。

語法

BOOL WINAPI WriteConsole(
  _In_             HANDLE  hConsoleOutput,
  _In_       const VOID    *lpBuffer,
  _In_             DWORD   nNumberOfCharsToWrite,
  _Out_opt_        LPDWORD lpNumberOfCharsWritten,
  _Reserved_       LPVOID  lpReserved
);

參數

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

lpBuffer [in]
緩衝區的指標，其中包含要寫入主控台螢幕緩衝區的字元。這應該是 WriteConsoleA 的 char 陣列，或 WriteConsoleW 的 wchar_t 陣列。

nNumberOfCharsToWrite [in]
要寫入的字元數。如果指定字元數的總大小超過可用的堆積，則函式會失敗並ERROR_NOT_ENOUGH_MEMORY。

lpNumberOfCharsWritten [out， optional]
變數的指標，可接收實際寫入的字元數。

lpReserved 已保留；必須是 NULL。

傳回值

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

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

備註

WriteConsole 函式會在目前游標位置將字元寫入主控台螢幕緩衝區。游標位置會在寫入字元時前進。 SetConsoleCursorPosition 函式會設定目前的游標位置。

字元是使用與主控台螢幕緩衝區相關聯的前景和背景色彩屬性來撰寫。 SetConsoleTextAttribute 函式會變更這些色彩。若要判斷目前的色彩屬性和目前的游標位置，請使用 GetConsoleScreenBufferInfo。

所有會影響 WriteFile 函式行為的輸入模式，在 WriteConsole 上具有相同的效果。若要擷取及設定主控台螢幕緩衝區的輸出模式，請使用 GetConsoleMode 和 SetConsoleMode 函式。

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

如果 WriteConsole 搭配會重新導向至檔案的標準控點使用，則會失敗。如果應用程式處理可重新導向的多語系輸出，請判斷輸出控點是否為主控台控點 (其中一種方法是呼叫 GetConsoleMode 函式並檢查其是否成功)。如果控點是主控台控點，請呼叫 WriteConsole。如果控點不是主控台控點，系統就會將輸出重新導向，而且您應該呼叫 WriteFile 來執行 I/O。請務必在 Unicode 純文字檔案前面加上位元組順序標記。如需詳細資訊，請參閱使用位元組順序標記。

雖然應用程式可以使用 ANSI 模式的 WriteConsole 來寫入 ANSI 字元，但除非已啟用「ANSI 逸出」或「虛擬終端機」序列，否則主控台不提供支援。如需詳細資訊和作業系統版本適用性，請參閱主控台虛擬終端機序列。

若未啟用當虛擬終端機逸出序列，主控台函式可以提供對等的功能。如需詳細資訊，請參閱 SetCursorPos、SetConsoleTextAttribute 和 GetConsoleCursorInfo。

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
頁首	ConsoleApi.h (透過 WinCon.h，包括 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll
Unicode 和 ANSI 名稱	WriteConsoleW (Unicode) 和 WriteConsoleA (ANSI)