CreatePseudoConsole function

Article
09/20/2022

Creates a new pseudoconsole object for the calling process.

Syntax

HRESULT WINAPI CreatePseudoConsole(
    _In_ COORD size,
    _In_ HANDLE hInput,
    _In_ HANDLE hOutput,
    _In_ DWORD dwFlags,
    _Out_ HPCON* phPC
);

Parameters

size [in]
The dimensions of the window/buffer in count of characters that will be used on initial creation of the pseudoconsole. This can be adjusted later with ResizePseudoConsole.

hInput [in]
An open handle to a stream of data that represents user input to the device. This is currently restricted to synchronous I/O.

hOutput [in]
An open handle to a stream of data that represents application output from the device. This is currently restricted to synchronous I/O.

dwFlags [in]
The value can be one of the following:

Value	Meaning
0	Perform a standard pseudoconsole creation.
PSEUDOCONSOLE_INHERIT_CURSOR (DWORD)1	The created pseudoconsole session will attempt to inherit the cursor position of the parent console.

phPC [out]
Pointer to a location that will receive a handle to the new pseudoconsole device.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This function is primarily used by applications attempting to be a terminal window for a command-line user interface (CUI) application. The callers become responsible for presentation of the information on the output stream and for collecting user input and serializing it into the input stream.

The input and output streams encoded as UTF-8 contain plain text interleaved with Virtual Terminal Sequences.

On the output stream, the virtual terminal sequences can be decoded by the calling application to layout and present the plain text in a display window.

On the input stream, plain text represents standard keyboard keys input by a user. More complicated operations are represented by encoding control keys and mouse movements as virtual terminal sequences embedded in this stream.

The handle created by this function must be closed with ClosePseudoConsole when operations are complete.

If using PSEUDOCONSOLE_INHERIT_CURSOR, the calling application should be prepared to respond to the request for the cursor state in an asynchronous fashion on a background thread by forwarding or interpreting the request for cursor information that will be received on hOutput and replying on hInput. Failure to do so may cause the calling application to hang while making another request of the pseudoconsole system.

Examples

For a full walkthrough on using this function to establish a pseudoconsole session, please see Creating a Pseudoconsole Session.

Requirements


Minimum supported client	Windows 10 October 2018 Update (version 1809) [desktop apps only]
Minimum supported server	Windows Server 2019 [desktop apps only]
Header	ConsoleApi.h (via WinCon.h, include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll