diff --git a/docs/TOC.md b/docs/TOC.md index 1094117..37a7c82 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -1,140 +1,143 @@ -# [Home](index.md) +# [Home](index.md) ## [Ecosystem Roadmap](ecosystem-roadmap.md) ## [Definitions](definitions.md) ## [Console APIs vs. Virtual Terminal](classic-vs-vt.md) -# [About Character Mode Applications](about-character-mode-applications.md) -## [Input And Output Methods](input-and-output-methods.md) +# [About Character Mode Applications](about-character-mode-applications.md) +## [Input And Output Methods](input-and-output-methods.md) ## [Console Code Pages](console-code-pages.md) ## [Console Control Handlers](console-control-handlers.md) ## [Console Aliases](console-aliases.md) ## [Console Buffer Security and Access Rights](console-buffer-security-and-access-rights.md) ## [Console Application Issues](console-application-issues.md) -# [About Consoles](consoles.md) -## [Creation of a Console](creation-of-a-console.md) -## [Attaching to a Console](attaching-to-a-console.md) +# [About Consoles](consoles.md) +## [Creation of a Console](creation-of-a-console.md) +## [Attaching to a Console](attaching-to-a-console.md) ## [Closing a Console](closing-a-console.md) -## [Console Handles](console-handles.md) +## [Console Handles](console-handles.md) ## [Console Input Buffer](console-input-buffer.md) -## [Console Screen Buffers](console-screen-buffers.md) +## [Console Screen Buffers](console-screen-buffers.md) ## [Console Modes](console-modes.md) ## [Console Process Groups](console-process-groups.md) -## [Window And Screen Buffer Size](window-and-screen-buffer-size.md) +## [Window And Screen Buffer Size](window-and-screen-buffer-size.md) ## [Console Selection](console-selection.md) ## [About Legacy Console Mode](legacymode.md) ## [About Pseudoconsoles](pseudoconsoles.md) -# [Console Developer's guide & API Reference](console-reference.md) -## [Using The Console API](using-the-console.md) -### [High Level Console Input And Output Functions](high-level-console-input-and-output-functions.md) -### [Using The High Level Input And Output Functions](using-the-high-level-Input-and-output-functions.md) -### [High Level Console Modes](high-level-console-modes.md) -### [High Level Console I/O](high-level-console-i-o.md) +# [Console Developer's guide & API Reference](console-reference.md) +## [Using The Console API](using-the-console.md) +### [High Level Console Input And Output Functions](high-level-console-input-and-output-functions.md) +### [Using The High Level Input And Output Functions](using-the-high-level-Input-and-output-functions.md) +### [High Level Console Modes](high-level-console-modes.md) +### [High Level Console I/O](high-level-console-i-o.md) ### [Low Level Console Input Functions](low-level-console-input-functions.md) ### [Low Level Console Output Functions](low-level-console-output-functions.md) -### [Low Level Console I/O](low-level-console-i-o.md) +### [Low Level Console I/O](low-level-console-i-o.md) ### [Low Level Console Modes](low-level-console-modes.md) -### [Reading And Writing Blocks Of Characters And Attributes](reading-and-writing-blocks-of-Characters-and-attributes.md) -### [Reading Input Buffer Events](reading-input-buffer-events.md) +### [Reading And Writing Blocks Of Characters And Attributes](reading-and-writing-blocks-of-Characters-and-attributes.md) +### [Reading Input Buffer Events](reading-input-buffer-events.md) ### [Clearing the screen](clearing-the-screen.md) -### [Scrolling a Screen Buffer](scrolling-the-screen-buffer.md) -### [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md) -### [Scrolling a Screen Buffer's Window](scrolling-a-screen-buffer-s-window.md) -### [Ctrl C And Ctrl Break Signals](ctrl-c-and-ctrl-break-signals.md) -### [Ctrl Close Signal](ctrl-close-signal.md) -### [Registering a Control Handler Function](registering-a-control-handler-function.md) -### [Console Virtual Terminal Sequences](console-virtual-terminal-sequences.md) +### [Scrolling a Screen Buffer](scrolling-the-screen-buffer.md) +### [Scrolling a Screen Buffer's Contents](scrolling-a-screen-buffer-s-contents.md) +### [Scrolling a Screen Buffer's Window](scrolling-a-screen-buffer-s-window.md) +### [Ctrl C And Ctrl Break Signals](ctrl-c-and-ctrl-break-signals.md) +### [Ctrl Close Signal](ctrl-close-signal.md) +### [Registering a Control Handler Function](registering-a-control-handler-function.md) +### [Console Virtual Terminal Sequences](console-virtual-terminal-sequences.md) ### [Creating a Pseudoconsole Session](creating-a-pseudoconsole-session.md) -## [Console API Functions](console-functions.md) -### [AddConsoleAlias](addconsolealias.md) -### [AllocConsole](allocconsole.md) -### [AttachConsole](attachconsole.md) +## [Console API Functions](console-functions.md) +### [AddConsoleAlias](addconsolealias.md) +### [AllocConsole](allocconsole.md) +### [AllocConsoleWithOptions](allocconsolewithoptions.md) +### [AttachConsole](attachconsole.md) ### [ClosePseudoConsole](closepseudoconsole.md) -### [CreateConsoleScreenBuffer](createconsolescreenbuffer.md) -### [CreatePseudoConsole](createpseudoconsole.md) ### [ConsoleControl](consolecontrol.md) -### [FillConsoleOutputAttribute](fillconsoleoutputattribute.md) -### [FillConsoleOutputCharacter](fillconsoleoutputcharacter.md) -### [FlushConsoleInputBuffer](flushconsoleinputbuffer.md) -### [FreeConsole](freeconsole.md) -### [GenerateConsoleCtrlEvent](generateconsolectrlevent.md) -### [GetConsoleAlias](getconsolealias.md) -### [GetConsoleAliases](getconsolealiases.md) -### [GetConsoleAliasesLength](getconsolealiaseslength.md) -### [GetConsoleAliasExes](getconsolealiasexes.md) -### [GetConsoleAliasExesLength](getconsolealiasexeslength.md) -### [GetConsoleCP](getconsolecp.md) -### [GetConsoleCursorInfo](getconsolecursorinfo.md) -### [GetConsoleDisplayMode](getconsoledisplaymode.md) -### [GetConsoleFontSize](getconsolefontsize.md) -### [GetConsoleHistoryInfo](getconsolehistoryinfo.md) -### [GetConsoleMode](getconsolemode.md) -### [GetConsoleOriginalTitle](getconsoleoriginaltitle.md) -### [GetConsoleOutputCP](getconsoleoutputcp.md) -### [GetConsoleProcessList](getconsoleprocesslist.md) -### [GetConsoleScreenBufferInfo](getconsolescreenBufferinfo.md) -### [GetConsoleScreenBufferInfoEx](getconsolescreenbufferinfoex.md) -### [GetConsoleSelectionInfo](getconsoleselectioninfo.md) -### [GetConsoleTitle](getconsoletitle.md) -### [GetConsoleWindow](getconsolewindow.md) -### [GetCurrentConsoleFont](getcurrentconsolefont.md) -### [GetCurrentConsoleFontEx](getcurrentconsolefontex.md) -### [GetLargestConsoleWindowSize](getlargestconsolewindowsize.md) -### [GetNumberOfConsoleInputEvents](getnumberofconsoleinputevents.md) -### [GetNumberOfConsoleMouseButtons](getnumberofconsolemousebuttons.md) -### [GetStdHandle](getstdhandle.md) -### [HandlerRoutine](handlerroutine.md) -### [PeekConsoleInput](peekconsoleinput.md) -### [ReadConsole](readconsole.md) -### [ReadConsoleInput](readconsoleinput.md) +### [CreateConsoleScreenBuffer](createconsolescreenbuffer.md) +### [CreatePseudoConsole](createpseudoconsole.md) +### [FillConsoleOutputAttribute](fillconsoleoutputattribute.md) +### [FillConsoleOutputCharacter](fillconsoleoutputcharacter.md) +### [FlushConsoleInputBuffer](flushconsoleinputbuffer.md) +### [FreeConsole](freeconsole.md) +### [GenerateConsoleCtrlEvent](generateconsolectrlevent.md) +### [GetConsoleAlias](getconsolealias.md) +### [GetConsoleAliases](getconsolealiases.md) +### [GetConsoleAliasesLength](getconsolealiaseslength.md) +### [GetConsoleAliasExes](getconsolealiasexes.md) +### [GetConsoleAliasExesLength](getconsolealiasexeslength.md) +### [GetConsoleCP](getconsolecp.md) +### [GetConsoleCursorInfo](getconsolecursorinfo.md) +### [GetConsoleDisplayMode](getconsoledisplaymode.md) +### [GetConsoleFontSize](getconsolefontsize.md) +### [GetConsoleHistoryInfo](getconsolehistoryinfo.md) +### [GetConsoleMode](getconsolemode.md) +### [GetConsoleOriginalTitle](getconsoleoriginaltitle.md) +### [GetConsoleOutputCP](getconsoleoutputcp.md) +### [GetConsoleProcessList](getconsoleprocesslist.md) +### [GetConsoleScreenBufferInfo](getconsolescreenBufferinfo.md) +### [GetConsoleScreenBufferInfoEx](getconsolescreenbufferinfoex.md) +### [GetConsoleSelectionInfo](getconsoleselectioninfo.md) +### [GetConsoleTitle](getconsoletitle.md) +### [GetConsoleWindow](getconsolewindow.md) +### [GetCurrentConsoleFont](getcurrentconsolefont.md) +### [GetCurrentConsoleFontEx](getcurrentconsolefontex.md) +### [GetLargestConsoleWindowSize](getlargestconsolewindowsize.md) +### [GetNumberOfConsoleInputEvents](getnumberofconsoleinputevents.md) +### [GetNumberOfConsoleMouseButtons](getnumberofconsolemousebuttons.md) +### [GetStdHandle](getstdhandle.md) +### [HandlerRoutine](handlerroutine.md) +### [PeekConsoleInput](peekconsoleinput.md) +### [ReadConsole](readconsole.md) +### [ReadConsoleInput](readconsoleinput.md) ### [ReadConsoleInputEx](readconsoleinputex.md) -### [ReadConsoleOutput](readconsoleoutput.md) -### [ReadConsoleOutputAttribute](readconsoleoutputattribute.md) -### [ReadConsoleOutputCharacter](readconsoleoutputcharacter.md) +### [ReadConsoleOutput](readconsoleoutput.md) +### [ReadConsoleOutputAttribute](readconsoleoutputattribute.md) +### [ReadConsoleOutputCharacter](readconsoleoutputcharacter.md) +### [ReleasePseudoConsole](releasepseudoconsole.md) ### [ResizePseudoConsole](resizepseudoconsole.md) -### [ScrollConsoleScreenBuffer](scrollconsolescreenbuffer.md) -### [SetConsoleActiveScreenBuffer](setconsoleactivescreenbuffer.md) -### [SetConsoleCP](setconsolecp.md) -### [SetConsoleCtrlHandler](setconsolectrlhandler.md) -### [SetConsoleCursorInfo](setconsolecursorinfo.md) -### [SetConsoleCursorPosition](setconsolecursorposition.md) -### [SetConsoleDisplayMode](setconsoledisplaymode.md) -### [SetConsoleHistoryInfo](setconsolehistoryinfo.md) -### [SetConsoleMode](setconsolemode.md) -### [SetConsoleOutputCP](setconsoleoutputcp.md) -### [SetConsoleScreenBufferInfoEx](setconsolescreenbufferinfoex.md) -### [SetConsoleScreenBufferSize](setconsolescreenbuffersize.md) -### [SetConsoleTextAttribute](setconsoletextattribute.md) -### [SetConsoleTitle](setconsoletitle.md) -### [SetConsoleWindowInfo](setconsolewindowinfo.md) -### [SetCurrentConsoleFontEx](setcurrentconsolefontex.md) -### [SetStdHandle](setstdhandle.md) -### [WriteConsole](writeconsole.md) -### [WriteConsoleInput](writeconsoleinput.md) -### [WriteConsoleOutput](writeconsoleoutput.md) -### [WriteConsoleOutputAttribute](writeconsoleoutputattribute.md) +### [ScrollConsoleScreenBuffer](scrollconsolescreenbuffer.md) +### [SetConsoleActiveScreenBuffer](setconsoleactivescreenbuffer.md) +### [SetConsoleCP](setconsolecp.md) +### [SetConsoleCtrlHandler](setconsolectrlhandler.md) +### [SetConsoleCursorInfo](setconsolecursorinfo.md) +### [SetConsoleCursorPosition](setconsolecursorposition.md) +### [SetConsoleDisplayMode](setconsoledisplaymode.md) +### [SetConsoleHistoryInfo](setconsolehistoryinfo.md) +### [SetConsoleMode](setconsolemode.md) +### [SetConsoleOutputCP](setconsoleoutputcp.md) +### [SetConsoleScreenBufferInfoEx](setconsolescreenbufferinfoex.md) +### [SetConsoleScreenBufferSize](setconsolescreenbuffersize.md) +### [SetConsoleTextAttribute](setconsoletextattribute.md) +### [SetConsoleTitle](setconsoletitle.md) +### [SetConsoleWindowInfo](setconsolewindowinfo.md) +### [SetCurrentConsoleFontEx](setcurrentconsolefontex.md) +### [SetStdHandle](setstdhandle.md) +### [WriteConsole](writeconsole.md) +### [WriteConsoleInput](writeconsoleinput.md) +### [WriteConsoleOutput](writeconsoleoutput.md) +### [WriteConsoleOutputAttribute](writeconsoleoutputattribute.md) ### [WriteConsoleOutputCharacter](writeconsoleoutputcharacter.md) -## [Console API Structures](console-structures.md) -### [CONSOLE_HISTORY_INFO structure](console-history-info.md) -### [CONSOLE_READCONSOLE_CONTROL structure](console-readconsole-control.md) -### [CONSOLE_SELECTION_INFO structure](console-selection-info-str.md) +## [Console API Structures](console-structures.md) +### [ALLOC_CONSOLE_OPTIONS](alloc-console-options.md) +### [CHAR_INFO structure](char-info-str.md) ### [CONSOLE_CURSOR_INFO structure](console-cursor-info-str.md) ### [CONSOLE_FONT_INFO structure](console-font-info-str.md) ### [CONSOLE_FONT_INFOEX structure](console-font-infoex.md) -### [CONSOLE_SCREEN_BUFFER_INFO structure](console-screen-buffer-info-str.md) -### [CONSOLE_SCREEN_BUFFER_INFOEX structure](console-screen-buffer-infoex.md) -### [CHAR_INFO structure](char-info-str.md) -### [COORD structure](coord-str.md) -### [SMALL_RECT structure](small-rect-str.md) -### [INPUT_RECORD structure](input-record-str.md) -### [KEY_EVENT_RECORD structure](key-event-record-str.md) -### [MENU_EVENT_RECORD structure](menu-event-record-str.md) -### [MOUSE_EVENT_RECORD structure](mouse-event-record-str.md) -### [FOCUS_EVENT_RECORD structure](focus-event-record-str.md) -### [WINDOW_BUFFER_SIZE_RECORD structure](window-buffer-size-record-str.md) +### [CONSOLE_HISTORY_INFO structure](console-history-info.md) +### [CONSOLE_READCONSOLE_CONTROL structure](console-readconsole-control.md) +### [CONSOLE_SCREEN_BUFFER_INFO structure](console-screen-buffer-info-str.md) +### [CONSOLE_SCREEN_BUFFER_INFOEX structure](console-screen-buffer-infoex.md) +### [CONSOLE_SELECTION_INFO structure](console-selection-info-str.md) +### [COORD structure](coord-str.md) +### [FOCUS_EVENT_RECORD structure](focus-event-record-str.md) +### [INPUT_RECORD structure](input-record-str.md) +### [KEY_EVENT_RECORD structure](key-event-record-str.md) +### [MENU_EVENT_RECORD structure](menu-event-record-str.md) +### [MOUSE_EVENT_RECORD structure](mouse-event-record-str.md) +### [SMALL_RECT structure](small-rect-str.md) +### [WINDOW_BUFFER_SIZE_RECORD structure](window-buffer-size-record-str.md) -## [Console API Winevents](console-winevents.md) +## [Console API Winevents](console-winevents.md) diff --git a/docs/alloc-console-options.md b/docs/alloc-console-options.md new file mode 100644 index 0000000..a58f80a --- /dev/null +++ b/docs/alloc-console-options.md @@ -0,0 +1,63 @@ +--- +title: ALLOC_CONSOLE_OPTIONS structure +description: See reference information about the ALLOC_CONSOLE_OPTIONS structure, which contains extended information about a console screen buffer. +author: lhecker +ms.author: lhecker +ms.topic: article +keywords: console, character mode applications, command line applications, terminal applications, console api +f1_keywords: +- consoleapi/ALLOC_CONSOLE_OPTIONS +- ALLOC_CONSOLE_OPTIONS +- PALLOC_CONSOLE_OPTIONS +topic_type: +- apiref +api_name: +- ALLOC_CONSOLE_OPTIONS +api_location: +- WinCon.h +api_type: +- HeaderDef +--- + +# ALLOC\_CONSOLE\_OPTIONS structure + +Controls how **AllocConsoleWithOptions** allocates a console window. + +## Syntax + +```C +typedef struct _ALLOC_CONSOLE_OPTIONS { + ALLOC_CONSOLE_MODE mode; + BOOL useShowWindow; + WORD showWindow; +} ALLOC_CONSOLE_OPTIONS, *PALLOC_CONSOLE_OPTIONS; +``` + +## Members + +**mode** +This parameter can be one of the following values: + +| Value | Meaning | +|-|-| +| **ALLOC\_CONSOLE\_MODE\_DEFAULT** 0 | Allocate a console session if one was requested by the parent process. | +| **ALLOC\_CONSOLE\_MODE\_NEW\_WINDOW** 1 | Allocate a console session with a window, even if this process was created with **CREATE\_NO\_CONSOLE** or **DETACHED\_PROCESS**. | +| **ALLOC\_CONSOLE\_MODE\_NO\_WINDOW** 2 | Allocate a console session without a window, even if this process was created with **CREATE\_NEW\_WINDOW** or **DETACHED\_PROCESS**. | + +**useShowWindow** +Specifies whether the **showWindow** parameter should be used. + +**showWindow** +If **useShowWindow** is **TRUE**, this specifies the **nCmdShow** used to show the console window. See [**ShowWindow**](/windows/win32/api/winuser/nf-winuser-showwindow) for more information. + +## Requirements + +|   |   | +|-|-| +| Minimum supported client | Windows 11 24H2 (build 26100) \[desktop apps only\] | +| Minimum supported server | n/a | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | + +## See also + +[**AllocConsoleWithOptions**](allocconsolewithoptions.md) diff --git a/docs/allocconsole.md b/docs/allocconsole.md index 8cd6431..f130873 100644 --- a/docs/allocconsole.md +++ b/docs/allocconsole.md @@ -5,7 +5,7 @@ author: miniksa ms.author: miniksa ms.topic: article keywords: console, character mode applications, command line applications, terminal applications, console api -f1_keywords: +f1_keywords: - consoleapi/AllocConsole - wincon/AllocConsole - AllocConsole @@ -77,6 +77,8 @@ This function is primarily used by a graphical user interface (GUI) application [Consoles](consoles.md) +[**AllocConsoleWithOptions**](allocconsolewithoptions.md) + [**AttachConsole**](attachconsole.md) [**CreateProcess**](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessa) diff --git a/docs/allocconsolewithoptions.md b/docs/allocconsolewithoptions.md new file mode 100644 index 0000000..3eada57 --- /dev/null +++ b/docs/allocconsolewithoptions.md @@ -0,0 +1,82 @@ +--- +title: AllocConsoleWithOptions function +description: See reference information about the AllocConsoleWithOptions function, which allocates a new console for the calling process. +author: lhecker +ms.author: lhecker +ms.topic: article +keywords: console, character mode applications, command line applications, terminal applications, console api, conpty, pseudoconsole +topic_type: +- apiref +api_name: +- AllocConsoleWithOptions +api_location: +- Kernel32.dll +- API-MS-Win-Core-Console-l1-2-2.dll +- KernelBase.dll +api_type: +- DllExport +--- + +# AllocConsoleWithOptions function + +Optionally allocates a new console for the calling process, while allowing you to specify the visibility of the new console window. + +## Syntax + +```C +HRESULT WINAPI AllocConsoleWithOptions( + _In_opt_ PALLOC_CONSOLE_OPTIONS allocOptions, + _Out_opt_ PALLOC_CONSOLE_RESULT result +); +``` + +## Parameters + +*allocOptions* \[in, optional\] +A [**ALLOC\_CONSOLE\_OPTIONS**](alloc-console-options.md) structure that controls how this function allocates a window. + +*result* \[out, optional\] +Receives one of the following values: + +| Value | Meaning | +|-|-| +| **ALLOC\_CONSOLE\_RESULT\_NO\_CONSOLE** 0 | No console was created, because **ALLOC\_CONSOLE\_MODE\_DEFAULT** was used and the parent process asked for none to be created. | +| **ALLOC\_CONSOLE\_RESULT\_NEW\_CONSOLE** 1 | A new console session was created as a result of this call. The resulting behavior is identical to [**AllocConsole**](allocconsole.md). | +| **ALLOC\_CONSOLE\_RESULT\_EXISTING\_CONSOLE** 2 | The process has attached itself to an existing console session, inherited by the parent process. The resulting behavior is identical to [**AttachConsole**](attachconsole.md). | + +## Return value + +Type: **HRESULT** + +If this method succeeds, it returns **S_OK**. Otherwise, it returns an **HRESULT** error code. + +## Remarks + +Unlike with [**AllocConsole**](allocconsole.md) or [**AttachConsole**](attachconsole.md), calling this method when already connected to a console session does not result in an error. +The *result* parameter will be set to **ALLOC\_CONSOLE\_RESULT\_EXISTING\_CONSOLE** in that case. + +A process can use the [**FreeConsole**](freeconsole.md) function to detach itself from its current console. A console is closed when the last process attached to it terminates or calls **FreeConsole**. + +## Requirements + +|   |   | +|-|-| +| Minimum supported client | Windows 11 24H2 (build 26100) \[desktop apps only\] | +| Minimum supported server | n/a | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also + +[Console Functions](console-functions.md) + +[Consoles](consoles.md) + +[Console Allocation Policy](console-allocation-policy.md) + +[**AllocConsole**](allocconsole.md) + +[**AttachConsole**](attachconsole.md) + +[**FreeConsole**](freeconsole.md) diff --git a/docs/attachconsole.md b/docs/attachconsole.md index 299d66a..d17a447 100644 --- a/docs/attachconsole.md +++ b/docs/attachconsole.md @@ -5,7 +5,7 @@ author: miniksa ms.author: miniksa ms.topic: article keywords: console, character mode applications, command line applications, terminal applications, console api -f1_keywords: +f1_keywords: - consoleapi/AttachConsole - wincon/AttachConsole - AttachConsole @@ -84,6 +84,8 @@ To compile an application that uses this function, define **\_WIN32\_WINNT** as [Consoles](consoles.md) +[**AllocConsoleWithOptions**](allocconsolewithoptions.md) + [**AllocConsole**](allocconsole.md) [**FreeConsole**](freeconsole.md) diff --git a/docs/closepseudoconsole.md b/docs/closepseudoconsole.md index 3700a21..929d7e9 100644 --- a/docs/closepseudoconsole.md +++ b/docs/closepseudoconsole.md @@ -19,7 +19,7 @@ api_type: # ClosePseudoConsole function -Closes a pseudoconsole from the given handle. +Shuts down and releases resources associated with the given pseudoconsole. ## Syntax @@ -40,9 +40,13 @@ A handle to an active pseudoconsole as opened by [CreatePseudoConsole](createpse ## Remarks -Upon closing a pseudoconsole, client applications attached to the session will be terminated as well. +Closing a pseudoconsole will send **CTRL_CLOSE_EVENT** to each client application that is still connected. Until the applications have disconnected they may continue writing more output. Because of this, your application is expected to either close the output pipe before calling **ClosePseudoConsole** or to continue reading from the pipe until after **ClosePseudoConsole** has returned. -A final painted frame may arrive on the `hOutput` handle originally provided to [CreatePseudoConsole](createpseudoconsole.md) when this API is called. It is expected that the caller will drain this information from the communication channel buffer and either present it or discard it. Failure to drain the buffer may cause the Close call to wait indefinitely until it is drained or the communication channels are broken another way. +> [!NOTE] +> Starting Windows 11 24H2 (build 26100) **ClosePseudoConsole** will return immediately to avoid accidental deadlocks. Earlier versions will wait indefinitely for the pseudoconsole to exit. If you need to know when all clients have disconnected, simply continue reading from the output pipe until it has been closed on you. + +> [!WARNING] +> As a consequence of the above, failure to either close or drain the output pipe may cause **ClosePseudoConsole** to wait indefinitely in earlier versions of Windows. To avoid deadlocks on older versions, don't call **ClosePseudoConsole** on the same thread that you're reading the output pipe from, unless the output pipe was previously closed by you or closed on you by the pseudoconsole. ## Requirements diff --git a/docs/console-allocation-policy.md b/docs/console-allocation-policy.md new file mode 100644 index 0000000..5f02a50 --- /dev/null +++ b/docs/console-allocation-policy.md @@ -0,0 +1,47 @@ +--- +title: Console Allocation Policy +description: Learn more about the Console Allocation Policy, allowing you to create hybrid graphical/console applications. +author: lhecker +ms.author: lhecker +ms.topic: conceptual +keywords: console, character mode applications, command line applications, terminal applications, console api +--- + +# Console Allocation Policy + +> [!NOTE] +> This feature requires Windows 11 24H2 (build 26100) or later. + +Most applications on Windows are either of the **IMAGE_SUBSYSTEM_WINDOWS_GUI** or **IMAGE_SUBSYSTEM_WINDOWS_CUI** type. +The former is a typical graphical, windowed application, whereas the latter is what's commonly called a console or terminal application. +When running an application marked as **IMAGE_SUBSYSTEM_WINDOWS_CUI** it'll be allocated a console, unless it's executed inside an existing console session. +Additionally, executing such an application inside a shell like CMD or PowerShell will block until the application has finished executing. +Neither of these are true for **IMAGE_SUBSYSTEM_WINDOWS_GUI** applications. +It'll neither be allocated a console, nor block execution inside a shell. + +Now what if you want to write an application that seems like a graphical application when run from Explorer, but you can also write debug output to the console, if run inside an existing console session? +To achieve this, build your application as an **IMAGE_SUBSYSTEM_WINDOWS_CUI** one (for instance with **/SUBSYSTEM:CONSOLE** in MSVC) and add the following application manifest: + +```xml + + + + + detached + + + +``` + +The **IMAGE_SUBSYSTEM_WINDOWS_CUI** type informs shells that they need to block until your application has finished executing, while the application manifest informs the operating system to skip allocating a console. + +## Requirements + +|   |   | +|-|-| +| Minimum supported client | Windows 11 24H2 (build 26100) \[desktop apps only\] | +| Minimum supported server | n/a | + +## See also + +[**GetNumberOfConsoleInputEvents**](allocconsolewithoptions.md) diff --git a/docs/console-functions.md b/docs/console-functions.md index 0a13567..ffe3834 100644 --- a/docs/console-functions.md +++ b/docs/console-functions.md @@ -23,10 +23,11 @@ The following functions are used to access a console. |-|-| | [**AddConsoleAlias**](addconsolealias.md) | Defines a console alias for the specified executable. | | [**AllocConsole**](allocconsole.md) | Allocates a new console for the calling process. | +| [**AllocConsoleWithOptions**](allocconsolewithoptions.md) | Optionally allocates a new console for the calling process, while allowing you to specify the visibility of the new console window. | | [**AttachConsole**](attachconsole.md) | Attaches the calling process to the console of the specified process. | | [**ClosePseudoConsole**](closepseudoconsole.md) | Closes a pseudoconsole from the given handle. | -| [**CreatePseudoConsole**](createpseudoconsole.md) | Allocates a new pseudoconsole for the calling process. | | [**CreateConsoleScreenBuffer**](createconsolescreenbuffer.md) | Creates a console screen buffer. | +| [**CreatePseudoConsole**](createpseudoconsole.md) | Allocates a new pseudoconsole for the calling process. | | [**FillConsoleOutputAttribute**](fillconsoleoutputattribute.md) | Sets the text and background color attributes for a specified number of character cells. | | [**FillConsoleOutputCharacter**](fillconsoleoutputcharacter.md) | Writes a character to the console screen buffer a specified number of times. | | [**FlushConsoleInputBuffer**](flushconsoleinputbuffer.md) | Flushes the console input buffer. | @@ -65,6 +66,7 @@ The following functions are used to access a console. | [**ReadConsoleOutput**](readconsoleoutput.md) | Reads character and color attribute data from a rectangular block of character cells in a console screen buffer. | | [**ReadConsoleOutputAttribute**](readconsoleoutputattribute.md) | Copies a specified number of foreground and background color attributes from consecutive cells of a console screen buffer. | | [**ReadConsoleOutputCharacter**](readconsoleoutputcharacter.md) | Copies a number of characters from consecutive cells of a console screen buffer. | +| [**ReleasePseudoConsole**](releasepseudoconsole.md) | Relinquishes ownership of the `HPCON` handle to the pseudoconsole, allowing it to automatically exit once all clients have disconnected. | | [**ResizePseudoConsole**](resizepseudoconsole.md) | Resizes the internal buffers for a pseudoconsole to the given size. | | [**ScrollConsoleScreenBuffer**](scrollconsolescreenbuffer.md) | Moves a block of data in a screen buffer. | | [**SetConsoleActiveScreenBuffer**](setconsoleactivescreenbuffer.md) | Sets the specified screen buffer to be the currently displayed console screen buffer. | diff --git a/docs/console-structures.md b/docs/console-structures.md index e5341a5..6bb3020 100644 --- a/docs/console-structures.md +++ b/docs/console-structures.md @@ -19,6 +19,7 @@ ms.assetid: 60f59616-d42b-469a-acf1-c1b71e68f560 The following structures are used to access a console. +- [**ALLOC\_CONSOLE\_OPTIONS**](alloc-console-options.md) - [**CHAR\_INFO**](char-info-str.md) - [**CONSOLE\_CURSOR\_INFO**](console-cursor-info-str.md) - [**CONSOLE\_FONT\_INFO**](console-font-info-str.md) diff --git a/docs/releasepseudoconsole.md b/docs/releasepseudoconsole.md new file mode 100644 index 0000000..8c75fec --- /dev/null +++ b/docs/releasepseudoconsole.md @@ -0,0 +1,76 @@ +--- +title: ReleasePseudoConsole function +description: See reference information about the ReleasePseudoConsole function, which allows the pseudoconsole to exit once all clients have disconnected. +author: lhecker +ms.author: lhecker +ms.topic: article +keywords: console, character mode applications, command line applications, terminal applications, console api, conpty, pseudoconsole +f1_keywords: +- consoleapi/ReleasePseudoConsole +- ReleasePseudoConsole +topic_type: +- apiref +api_name: +- ReleasePseudoConsole +api_location: +- Kernel32.dll +- API-MS-Win-Core-Console-l1-2-2.dll +- KernelBase.dll +api_type: +- DllExport +--- + +# ReleasePseudoConsole function + +Relinquishes ownership of the `HPCON` handle to the pseudoconsole, allowing it to automatically exit once all clients have disconnected. + +## Syntax + +```C +HRESULT WINAPI ReleasePseudoConsole( + _In_ HPCON hPC +); +``` + +## Parameters + +*hPC* \[in\] +A handle to an active pseudoconsole as opened by [CreatePseudoConsole](createpseudoconsole.md). + +## Return value + +Type: **HRESULT** + +If this method succeeds, it returns **S_OK**. Otherwise, it returns an **HRESULT** error code. +The call is not expected to fail unless the **hPC** argument is invalid in which case it returns **E_INVALIDARG**. + +## Remarks + +Before this method was introduced, the initial pseudoconsole API was inherently flawed: **ClosePseudoConsole** would only exit until after the pseudoconsole has finished using the output pipe. This meant that the pseudoconsole effectively kept your application alive. The **HPCON** handle owned by your application on the other hand kept the pseudoconsole session alive until **ClosePseudoConsole** was called. This created a lifetime and ownership loop. The way applications were expected to break this loop up was by manually waiting for the spawned terminal processes to exit and then call **ClosePseudoConsole**. This made the API failure prone and resulted in shutdown deadlocks in various applications. + +**ReleasePseudoConsole** solves this problem: It allows you to relinquish your half of the ownership. This in turn allows the pseudoconsole to automatically exit as soon as all clients have disconnected. All you need to do now is to read from or write to your output and input pipe handles until they return a failure. This indicates to you that all clients have disconnected and the the pseudoconsole is about to exit on its own. + +> [!WARNING] +> **ReleasePseudoConsole** does not deallocate the memory associated with the **HPCON**. You must still call **ClosePseudoConsole** once you're done using the **HPCON** instance. See [ClosePseudoConsole](closepseudoconsole.md) for important information about its correct usage. + +## Examples + +For a full walkthrough on using this function to establish a pseudoconsole session, please see [Creating a Pseudoconsole Session](creating-a-pseudoconsole-session.md). + +## Requirements + +|   |   | +|-|-| +| Minimum supported client | Windows 11 24H2 (build 26100) \[desktop apps only\] | +| Minimum supported server | n/a | +| Header | ConsoleApi.h (via WinCon.h, include Windows.h) | +| Library | Kernel32.lib | +| DLL | Kernel32.dll | + +## See also + +[Pseudoconsoles](pseudoconsoles.md) + +[Creating a Pseudoconsole Session](creating-a-pseudoconsole-session.md) + +[**ClosePseudoConsole**](closepseudoconsole.md)