ReadConsoleOutput 関数
重要
このドキュメントでは、エコシステム ロードマップの一部ではなくなったコンソール プラットフォームの機能について説明します。 このコンテンツを新しい製品で使用することはお勧めしませんが、今後も既存の使用をサポートし続けます。 推奨される最新のソリューションでは、クロスプラットフォーム シナリオでの互換性を最大限に高める仮想ターミナル シーケンスに重点を置いています。 この設計決定の詳細については、クラシック コンソールと仮想ターミナルのドキュメントを参照してください。
コンソール スクリーン バッファー内の四角形の文字セル ブロックから文字と色の属性データを読み取り、この関数は目的のバッファー内の指定された場所にある四角形のブロックにデータを書き込みます。
構文
BOOL WINAPI ReadConsoleOutput(
_In_ HANDLE hConsoleOutput,
_Out_ PCHAR_INFO lpBuffer,
_In_ COORD dwBufferSize,
_In_ COORD dwBufferCoord,
_Inout_ PSMALL_RECT lpReadRegion
);
パラメーター
hConsoleOutput [in]
コンソール画面バッファーのハンドル。 ハンドルには、GENERIC_READ アクセス権があります。 詳細については、「コンソール バッファーのセキュリティとアクセス権」を参照してください。
lpBuffer [out]
コンソール スクリーン バッファーから読み取られたデータを受信する宛先バッファーへのポインター。 このポインターは、dwBufferSize パラメーターでサイズが指定 CHAR_INFO 構造体の 2 次元配列の原点として扱われます。
dwBufferSize [in]
lpBuffer パラメーターのサイズ (文字セル単位)。 COORD 構造体の X メンバーは列数です。Y メンバーは行数です。
dwBufferCoord [in]
コンソール スクリーン バッファーから読み取られたデータを受け取る lpBuffer パラメーターの左上のセルの座標。 COORD 構造体の X メンバーは列であり、Y メンバーは行です。
lpReadRegion [in, out]
SMALL_RECT構造体へのポインター。 入力時に、構造体メンバーは、関数が読み込まれるコンソール スクリーン バッファーの四角形の左上と右下の座標を指定します。 出力時に、構造体メンバーは使用された実際の四角形を指定します。
戻り値
関数が成功すると、戻り値は 0 以外になります。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
ReadConsoleOutput は、コンソール スクリーン バッファーと宛先先バッファーを 2 次元配列 (文字セルの列と行) として扱います。 lpReadRegion パラメーターが指す四角形は、コンソール スクリーン バッファーから読み込まれるブロックのサイズと場所を指定します。 同じサイズの目的の四角形は、lpBuffer 配列の dwBufferCoord パラメーターの座標にある左上のセルと共に配置されます。 コンソール スクリーン バッファーのソース四角形内のセルから読み取られたデータは、コピー先バッファー内の対応するセルにコピーされます。 対応するセルがコピー先バッファーの四角形 (dwBufferSize パラメーターで指定されたサイズ) の境界外にある場合、データはコピーされません。
コンソール スクリーン バッファーの境界内にない座標に対応する宛先先バッファー内のセルは変更されません。 つまり、スクリーン バッファー データを読み込むことができないセルです。
ReadConsoleOutput が返される前に、lpReadRegion パラメーターが指す構造体のメンバーを、コピー先バッファーにセルがコピーされた実際のスクリーン バッファーの四角形に設定します。 ReadConsoleOutput は目的の四角形のサイズをクリップしてコンソール スクリーン バッファーの境界に合わせるため、この移動元の四角形は、ソース バッファー内に対応するセルが存在していた移動先の四角形内のセルを反映します。
lpReadRegion で指定された四角形がコンソール スクリーン バッファーの境界の外側にある場合、または対応する四角形がコピー先バッファーの境界の外に完全に配置されている場合、データはコピーされなくなります。 この場合、関数は、Right メンバーが Left より小さいか、Bottom メンバーが Top より小さいよう、lpReadRegion パラメーター セットが指す構造体のメンバーを返します。 コンソール スクリーン バッファのサイズを確認するには、GetConsoleScreenBufferInfo 関数を使用します。
ReadConsoleOutput 関数は、コンソール スクリーン バッファーのカーソル位置には影響しません。 コンソール スクリーン バッファーの内容は、関数によって変更されません。
この関数では、Unicode 文字またはコンソールの現在のコード ページの 8 ビット文字が使用されます。 コンソールのコード ページには、最初はシステムの OEM コード ページが既定で設定されます。 コンソールのコード ページを変更するには、SetConsoleCP または SetConsoleOutputCP 関数を使用します。 従来のユーザーは、chcp または mode con cp select= コマンドを使用することもできますが、それは新規の開発ではお勧めできません。
ヒント
この API は推奨されておらず、同等の 仮想ターミナル はありません。 この決定により、Windows プラットフォームは、個々のクライアント アプリケーションがそれ自体の描画状態を記憶してさらに操作することが期待される他のオペレーティング システムと意図的に調整されます。 この API を使用している場合、クロスプラットフォーム ユーティリティや SSH などのトランスポートを介したアプリケーションのリモート処理は、想定どおりに動作しない可能性があります。
例
例については、「文字と属性のブロックの読み取りと書き込み」を参照してください。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| ヘッダー | ConsoleApi2.h（WinCon.h 経由、Windows.h を含む） |
| ライブラリ | Kernel32.lib |
| [DLL] | Kernel32.dll |
| Unicode 名と ANSI 名 | ReadConsoleOutputW (Unicode) と ReadConsoleOutputA (ANSI) |