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 に設定します。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

ReadConsole は、コンソールの入力バッファーからキーボード入力を読み取ります。 Unicode (ワイド文字) または ANSI モードで読み取ることができる点を除き、ReadFile 関数と同様に動作します。 両方のモードと互換性がある 1 つのソース セットを維持するアプリケーションを作成するには、ReadFile ではなく ReadConsole を使用します。 ReadConsole はコンソール入力バッファー ハンドルでのみ使用できますが、ReadFile はその他のハンドル (ファイルやパイプなど) と共に使用できます。 コンソール ハンドル以外のハンドルにリダイレクトされた標準ハンドルと共に使用すると、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 が設定されている場合です。 クックド モードでは、コンソール ホストはコマンド ライン アプリケーションの代わりに編集行を提供し、Enter キーが押されるまで ReadFile または ReadConsole の呼び出しは戻りません。

中間読み取りは、クックド読み取りモードでの ReadConsole 呼び出しでのその動作の拡張です。 CONSOLE_READCONSOLE_CONTROL 構造体で dwCtrlWakeupMask にフラグを設定し、ReadConsole を呼び出す際に pinputControl に渡すと、読み取りは必ずしも改行を待つ必要はなく、指定された文字でも返されます。　

要件

関連項目

コンソール関数

CONSOLE_READCONSOLE_CONTROL

GetConsoleMode

入力と出力の方法

ReadConsoleInput

ReadFile

SetConsoleCP

SetConsoleMode

SetConsoleOutputCP

WriteConsole