CreateConsoleScreenBuffer

Artikel
12/21/2023

Wichtig

In diesem Dokument werden Konsolenplattformfunktionen beschrieben, die nicht mehr Teil unserer Ökosystem-Roadmap sind. Wir empfehlen nicht, diesen Inhalt in neuen Produkten zu verwenden, aber wir werden weiterhin vorhandene Nutzungen für die unbegrenzte Zukunft unterstützen. Unsere bevorzugte moderne Lösung konzentriert sich auf virtuelle Terminalsequenzen für maximale Kompatibilität in plattformübergreifenden Szenarien. Weitere Informationen zu dieser Designentscheidung finden Sie in unserem klassischen Konsolendokument im Vergleich zum virtuellen Terminal .

Erstellt einen Konsolenbildschirmpuffer.

Syntax

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

Parameter

dwDesiredAccess [in]
Der Zugang zum Konsolenbildschirm-Puffer. Eine Liste der Zugriffsrechte finden Sie unter Console Buffer Security and Access Rights.

dwShareMode [in]
Dieser Parameter kann null sein, was angibt, dass der Puffer nicht freigegeben werden kann, oder es kann sich um einen oder mehrere der folgenden Werte handeln.

Wert	Bedeutung
FILE_SHARE_READ 0x00000001	Andere geöffnete Vorgänge können im Konsolenbildschirmpuffer für den Lesezugriff ausgeführt werden.
FILE_SHARE_WRITE 0x00000002	Andere geöffnete Vorgänge können im Konsolenbildschirmpuffer für schreibgeschützten Zugriff ausgeführt werden.

lpSecurityAttributes [in, optional]
Zeiger auf eine SECURITY_ATTRIBUTES -Struktur, die bestimmt, ob das zurückgegebene Handle von untergeordneten Prozessen erhalten werden kann. Wenn NULL ist, kann das Handle nicht erhalten werden. Das lpSecurityDescriptor-Element der Struktur gibt einen Sicherheitsdeskriptor für den neuen Konsolenbildschirmpuffer an. Wenn lpSecurityAttributes NULL ist, erhält der Konsolenbildschirmpuffer einen Standardsicherheitsdeskriptor. Die ACLs im Standardsicherheitsdeskriptor für einen Konsolenbildschirmpuffer stammen aus dem primären oder Identitätswechseltoken des Erstellers.

dwFlags [in]
Der Typ des zu erstellenden Konsolenbildschirmpuffers. Der einzige unterstützte Bildschirmpuffertyp ist CONSOLE_TEXTMODE_BUFFER.

lpScreenBufferData
Reserviert; sollte NULL sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für den neuen Konsolenbildschirmpuffer.

Wenn die Funktion fehlschlägt, ist der Rückgabewert INVALID_HANDLE_VALUE. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Eine Konsole kann mehrere Bildschirmpuffer aufweisen, aber nur einen aktiven Bildschirmpuffer. Auf inaktive Bildschirmpuffer kann zum Lesen und Schreiben zugegriffen werden, aber nur der aktive Bildschirmpuffer wird angezeigt. Um den neuen Bildschirmpuffer zum aktiven Bildschirmpuffer zu machen, verwenden Sie die SetConsoleActiveScreenBuffer-Funktion.

Der neu erstellte Bildschirmpuffer kopiert einige Eigenschaften aus dem aktiven Bildschirmpuffer zum Zeitpunkt des Aufrufs dieser Funktion. Das Flag verhält sich wie folgt:

Font - Aus aktivem Bildschirmpuffer kopiert
Display Window Size - Aus aktivem Bildschirmpuffer kopiert
Buffer Size - abgeglichen Display Window Size (NICHT kopiert)
Default Attributes (Farben) - aus dem aktiven Bildschirmpuffer kopiert
Default Popup Attributes (Farben) - aus dem aktiven Bildschirmpuffer kopiert

Der aufrufende Prozess kann das zurückgegebene Handle in jeder Funktion verwenden, die ein Handle für einen Konsolenbildschirmpuffer erfordert, vorbehaltlich der Einschränkungen des Zugriffs durch den dwDesiredAccess-Parameter .

Ein Prozess kann die DuplicateHandle-Funktion verwenden, um ein Duplikat eines Konsolenhandles zu erstellen, das gegenüber dem ursprünglichen Handle abweichende Zugriffsrechte oder eine andere Vererbung aufweist. DuplicateHandle kann jedoch nicht verwendet werden, um ein Duplikat zu erstellen, das für einen anderen Prozess gültig ist (mit Ausnahme der Vererbung).

Zum Schließen eines Konsolenhandles kann ein Prozess die CloseHandle-Funktion verwenden.

Tipp

Diese API wird nicht empfohlen, verfügt aber über eine ungefähre virtuelle Terminalentsprechung in der alternativen Bildschirmpuffersequenz. Das Festlegen des alternativen Bildschirmpuffers kann einer Anwendung einen separaten, isolierten Bereich zum Zeichnen über die Sitzungslaufzeit bereitstellen und gleichzeitig den Inhalt beibehalten, der vom Aufrufer der Anwendung angezeigt wurde. Dadurch Standard enthält das Zeichnen von Informationen für die einfache Wiederherstellung beim Beenden des Prozesses.

Beispiele

Lesen und Schreiben von Zeichen- und Attributblöcken

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Header	ConsoleApi.h (über WinCon.h, Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll