ReadConsole 函式
從主控台輸入緩衝區讀取字元輸入,並將它從緩衝區中移除。
BOOL WINAPI ReadConsole(
_In_ HANDLE hConsoleInput,
_Out_ LPVOID lpBuffer,
_In_ DWORD nNumberOfCharsToRead,
_Out_ LPDWORD lpNumberOfCharsRead,
_In_opt_ LPVOID pInputControl
);
hConsoleInput [in]
主控台輸入緩衝區的句柄。 句柄必須具有 GENERIC_READ 訪問許可權。 如需詳細資訊,請參閱主控台緩衝區安全性和存取權限。
lpBuffer [out]
緩衝區的指標,接收從控制台輸入緩衝區讀取的數據。
nNumberOfCharsToRead [in]
要讀取的字元數。 lpBuffer 參數所指向的緩衝區大小至少應該是nNumberOfCharsToRead * sizeof(TCHAR)
位元組。
lpNumberOfCharsRead [out]
接收實際讀取字元數之變數的指標。
pInputControl [in, optional]
CONSOLE_READCONSOLE_CONTROL 結構的指標,指定控件字元來發出讀取作業結尾的訊號。 此參數可以是 Null。
此參數預設需要 Unicode 輸入。 若為 ANSI 模式,請將此參數設定為 NULL。
如果函式成功,則傳回非零的值。
如果此函式失敗,則傳回值為零。 若要取得擴充的錯誤資訊,請呼叫 GetLastError。
ReadConsole 會從控制台的輸入緩衝區讀取鍵盤輸入。 其行為與 ReadFile 函式類似,不同之處在於它可以在 Unicode (寬字元) 或 ANSI 模式中讀取。 若要讓應用程式維護與這兩種模式相容的單一來源集,請使用 ReadConsole ,而不是 ReadFile。 雖然 ReadConsole 只能與控制台輸入緩衝區句柄搭配使用, 但 ReadFile 可以搭配其他句柄使用(例如檔案或管道)。 如果搭配已重新導向為控制台句柄以外的標準句柄使用 ReadConsole,則 ReadConsole 會失敗。
影響 ReadFile 行為的所有輸入模式在 ReadConsole 上都有相同的效果。 若要擷取和設定主控台輸入緩衝區的輸入模式,請使用 GetConsoleMode 和 SetConsoleMode 函式。
如果輸入緩衝區包含鍵盤事件以外的輸入事件(例如滑鼠事件或視窗重設大小事件),則會捨棄它們。 這些事件只能使用 ReadConsoleInput 函式來讀取。
此函式會從主控台的目前字碼頁使用 Unicode 字元或 8 位元字元。 主控台的字碼頁一開始會預設為系統的 OEM 字碼頁。 若要變更控制台的字碼頁,請使用 SetConsoleCP 或 SetConsoleOutputCP 函式。 舊版取用者也可以使用 chcp 或 mode con cp select= 命令,但不建議用於新的開發。
pInputControl 參數可用來啟用讀取的中繼喚醒,以回應CONSOLE_READCONSOLE_CONTROL結構中指定的檔案完成控制字元。 這項功能需要啟用命令延伸模組、標準輸出句柄為控制台輸出句柄,以及輸入為 Unicode。
Windows Server 2003 和 Windows XP/2000: 不支援中繼讀取功能。
[烹飪模式] 是在控制台輸入句柄上使用 SetConsoleMode 設定ENABLE_LINE_INPUT時。 在烹飪模式中,主控台主機會代表命令行應用程式提供編輯行,而且呼叫 ReadFile 或 ReadConsole 在按下 Enter 鍵之前,將不會傳回。
中繼讀取 是讀取模式中 ReadConsole 呼叫上該行為的增強。 在 CONSOLE_READCONSOLE_CONTROL 結構上設定 dwCtrlWakeupMask 中的旗標,並在呼叫 ReadConsole 時將其傳遞至 pinputControl,會導致讀取不一定等待換行符,但也會傳回指定的字元。
最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
頁首 | ConsoleApi.h (透過 WinCon.h,包括 Windows.h) |
程式庫 | Kernel32.lib |
DLL | Kernel32.dll |
Unicode 和 ANSI 名稱 | ReadConsoleW (Unicode) 和 ReadConsoleA (ANSI) |