低階主控台輸入函式

重要

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

低階主控台輸入函式緩衝區包含輸入記錄，可包含鍵盤、滑鼠、緩衝區重設大小、焦點和功能表事件的相關信息。 低階函式提供直接存取輸入緩衝區，不同於篩選和處理輸入緩衝區數據的高階函式，捨棄除了鍵盤輸入外的所有函式。

存取主控台輸入緩衝區有五個低階函式：

• ReadConsoleInput
• PeekConsoleInput
• GetNumberOfConsoleInputEvents
• WriteConsoleInput
• FlushConsoleInputBuffer

ReadConsoleInput、PeekConsoleInput 和 WriteConsoleInput 函式會使用 INPUT_RECORD 結構來讀取或寫入輸入緩衝區。

以下是低階主控台輸入函式的描述。

函式	描述
ReadConsoleInput	從輸入緩衝區讀取和移除輸入記錄。 函式不會傳回，直到至少有一筆記錄可供讀取為止。 然後，所有可用的記錄都會傳送至呼叫進程的緩衝區，直到沒有更多記錄可用或已讀取指定的記錄數目為止。 未讀取的記錄會保留在下一個讀取作業的輸入緩衝區中。 函式會報告已讀取的記錄總數。 如需使用 ReadConsoleInput 的範例，請參閱讀取輸入緩衝區事件。
PeekConsoleInput	讀取而不移除輸入緩衝區中的暫止輸入記錄。 所有可用的記錄最多指定號碼都會複製到呼叫進程的緩衝區中。 如果沒有可用的記錄，函式會立即傳回。 函式會報告已讀取的記錄總數。
GetNumberOfConsoleInputEvents	決定輸入緩衝區中未讀取的輸入記錄數目。
WriteConsoleInput	將輸入記錄放在緩衝區中任何暫止記錄之後的輸入緩衝區中。 視需要，輸入緩衝區會動態成長，以保留所寫入的記錄數目。 若要使用此函式，指定的輸入緩衝區句柄必須具有GENERIC_WRITE訪問許可權。
FlushConsoleInputBuffer	捨棄輸入緩衝區中的所有未讀取事件。 若要使用此函式，指定的輸入緩衝區句柄必須具有GENERIC_WRITE訪問許可權。

應用程式進程的線程可以執行等候作業，等待輸入緩衝區中可用的輸入。 若要起始等候作業，請在呼叫任何等候函式時指定輸入緩衝區的句柄。 當一或多個物件的狀態發出訊號時，這些函式可以傳回。 主控台輸入句柄的狀態會在其輸入緩衝區中有未讀取的記錄時發出訊號。 當輸入緩衝區變成空白時，狀態會重設為非訊號。 如果沒有可用的輸入，呼叫線程會進入有效率的等候狀態，在等候等候作業的條件時耗用非常少的處理器時間。