CreateConsoleScreenBuffer 関数

[アーティクル]
12/25/2023

重要

このドキュメントでは、エコシステムロードマップの一部ではなくなったコンソールプラットフォームの機能について説明します。このコンテンツを新しい製品で使用することはお勧めしませんが、今後も既存の使用をサポートし続けます。推奨される最新のソリューションでは、クロスプラットフォームシナリオでの互換性を最大限に高める仮想ターミナルシーケンスに重点を置いています。この設計決定の詳細については、クラシックコンソールと仮想ターミナルのドキュメントを参照してください。

コンソールスクリーンバッファーを作成します。

構文

HANDLE WINAPI CreateConsoleScreenBuffer(
  _In_             DWORD               dwDesiredAccess,
  _In_             DWORD               dwShareMode,
  _In_opt_   const SECURITY_ATTRIBUTES *lpSecurityAttributes,
  _In_             DWORD               dwFlags,
  _Reserved_       LPVOID              lpScreenBufferData
);

パラメーター

dwDesiredAccess [in]
コンソールスクリーンバッファーのアクセス。アクセス権のリストについては、「コンソールバッファーのセキュリティとアクセス権」を参照してください。

dwShareMode [in]
このパラメーターは、バッファーを共有できないことを示す 0 にすることも、次の値の 1 つ以上にすることもできます。

Value	意味
FILE_SHARE_READ 0x00000001	その他のオープン操作は、読み取りアクセスのためにコンソールスクリーンバッファーで実行できます。
FILE_SHARE_WRITE 0x00000002	その他のオープン操作は、書き込みアクセスのためにコンソールスクリーンバッファーで実行できます。

lpSecurityAttributes [in, optional]
返されたハンドルを子プロセスが継承できるかどうかを決定する SECURITY_ATTRIBUTES 構造体へのポインター。 lpSecurityAttributes が NULL の場合、ハンドルを継承できません。構造体の lpSecurityDescriptor メンバーは、新しいコンソールスクリーンバッファーのセキュリティ記述子を指定します。 lpSecurityAttributes が NULL の場合、コンソールスクリーンバッファーは既定のセキュリティ記述子を取得します。コンソールスクリーンバッファーのデフォルトのセキュリティ記述子の ACL は、作成者のプライマリトークンまたは偽装トークンから取得されます。

dwFlags [in]
作成するコンソールスクリーンバッファーの種類。サポートされているスクリーンバッファーの種類は CONSOLE_TEXTMODE_BUFFER のみです。

lpScreenBufferData
予約、NULL にする必要があります。

戻り値

関数が成功した場合、戻り値は新しいコンソールスクリーンバッファーへのハンドルです。

失敗した場合の戻り値は、INVALID_HANDLE_VALUE です。詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

コンソールには複数のスクリーンバッファーを含めることができますが、アクティブなスクリーンバッファーは 1 つだけです。非アクティブなスクリーンバッファーには読み取りと書き込みのためにアクセスできますが、アクティブなスクリーンバッファーのみが表示されます。新しいスクリーンバッファーをアクティブなスクリーンバッファーにするには、SetConsoleActiveScreenBuffer 関数を使用します。

新しく作成されたスクリーンバッファーは、この関数が呼び出されるときに、アクティブなスクリーンバッファーからいくつかのプロパティをコピーします。動作は次のようになります。

Font - アクティブなスクリーンバッファーからコピー
Display Window Size - アクティブなスクリーンバッファーからコピー
Buffer Size - Display Window Size に一致 (コピーされない)
Default Attributes (色) - アクティブなスクリーンバッファーからコピー
Default Popup Attributes (色) - アクティブなスクリーンバッファーからコピー

呼び出し元のプロセスは、dwDesiredAccess パラメーターで指定されたアクセスの制限に従って、コンソールスクリーンバッファーへのハンドルを必要とする任意の関数で返されたハンドルを使用できます。

呼び出しプロセスでは、DuplicateHandle 関数を使用して、元のハンドルとは異なるアクセス権や継承性を持つ重複するスクリーンバッファーハンドルを作成できます。ただし、 DuplicateHandle を使用して、(継承を除く) 別のプロセスで有効な重複を作成することはできません。

コンソールスクリーンバッファーハンドルを閉じるには、CloseHandle 関数を使用します。

ヒント

この API は推奨されませんが、代替スクリーンバッファー シーケンスに相当するおおよその仮想ターミナルがあります。 代替スクリーンバッファーを設定すると、アプリケーションの呼び出し側によって表示されたコンテンツを保持しながら、セッションランタイムの過程で描画するための独立した分離スペースをアプリケーションに提供できます。これは、プロセス終了時に簡単に復元するための描画情報を維持します。

例

例については、「文字と属性のブロックの読み取りと書き込み」を参照してください。

要件


サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
ヘッダー	ConsoleApi2.h（WinCon.h 経由、Windows.h を含む）
ライブラリ	Kernel32.lib
[DLL]	Kernel32.dll

CreateConsoleScreenBuffer 関数

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

フィードバック

その他のリソース