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 字碼頁。 若要變更控制台的字碼頁,請使用 SetConsoleCPSetConsoleOutputCP 函式。 舊版取用者也可以使用 chcpmode con cp select= 命令,但不建議用於新的開發。

pInputControl 參數可用來啟用讀取的中繼喚醒,以回應CONSOLE_READCONSOLE_CONTROL結構中指定的檔案完成控制字元。 這項功能需要啟用命令延伸模組、標準輸出句柄為控制台輸出句柄,以及輸入為 Unicode。

Windows Server 2003 和 Windows XP/2000: 不支援中繼讀取功能。

[烹飪模式] 是在控制台輸入句柄上使用 SetConsoleMode 設定ENABLE_LINE_INPUT。 在烹飪模式中,主控台主機會代表命令行應用程式提供編輯行,而且呼叫 ReadFileReadConsole 在按下 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)

另請參閱

主控台函式

CONSOLE_READCONSOLE_CONTROL

GetConsoleMode

輸入和輸出方法

ReadConsoleInput

ReadFile

SetConsoleCP

SetConsoleMode

SetConsoleOutputCP

WriteConsole