CreateConsoleScreenBuffer
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 kopiertDisplay Window Size- Aus aktivem Bildschirmpuffer kopiertBuffer Size- abgeglichenDisplay Window Size(NICHT kopiert)Default Attributes(Farben) - aus dem aktiven Bildschirmpuffer kopiertDefault 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 |
Siehe auch
DuplicateHandle