Document the new 24H2 APIs #323
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| <?xml version="1.0" encoding="UTF-8" standalone="yes"?> | ||
| <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0"> | ||
| <application> | ||
| <windowsSettings> | ||
| <consoleAllocationPolicy xmlns="http://schemas.microsoft.com/SMI/2024/WindowsSettings">detached</consoleAllocationPolicy> | ||
| </windowsSettings> | ||
| </application> | ||
| </assembly> | ||
| ``` | ||
|
|
||
| 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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🚫 Whitespace changes: https://github.com/MicrosoftDocs/Console-Docs/pull/323/files?w=1