2 * Copyright (c) 2011-2016 Ryan Prichard
4 * Permission is hereby granted, free of charge, to any person obtaining a copy
5 * of this software and associated documentation files (the "Software"), to
6 * deal in the Software without restriction, including without limitation the
7 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8 * sell copies of the Software, and to permit persons to whom the Software is
9 * furnished to do so, subject to the following conditions:
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
28 #include "winpty_constants.h"
30 /* On 32-bit Windows, winpty functions have the default __cdecl (not __stdcall)
31 * calling convention. (64-bit Windows has only a single calling convention.)
32 * When compiled with __declspec(dllexport), with either MinGW or MSVC, the
33 * winpty functions are unadorned--no underscore prefix or '@nn' suffix--so
34 * GetProcAddress can be used easily. */
35 #ifdef COMPILING_WINPTY_DLL
36 #define WINPTY_API __declspec(dllexport)
38 #define WINPTY_API __declspec(dllimport)
45 /* The winpty API uses wide characters, instead of UTF-8, to avoid conversion
46 * complications related to surrogates. Windows generally tolerates unpaired
47 * surrogates in text, which makes conversion to and from UTF-8 ambiguous and
48 * complicated. (There are different UTF-8 variants that deal with UTF-16
49 * surrogates differently.) */
53 /*****************************************************************************
56 /* All the APIs have an optional winpty_error_t output parameter. If a
57 * non-NULL argument is specified, then either the API writes NULL to the
58 * value (on success) or writes a newly allocated winpty_error_t object. The
59 * object must be freed using winpty_error_free. */
61 /* An error object. */
62 typedef struct winpty_error_s winpty_error_t;
63 typedef winpty_error_t *winpty_error_ptr_t;
65 /* An error code -- one of WINPTY_ERROR_xxx. */
66 typedef DWORD winpty_result_t;
68 /* Gets the error code from the error object. */
69 WINPTY_API winpty_result_t winpty_error_code(winpty_error_ptr_t err);
71 /* Returns a textual representation of the error. The string is freed when
72 * the error is freed. */
73 WINPTY_API LPCWSTR winpty_error_msg(winpty_error_ptr_t err);
75 /* Free the error object. Every error returned from the winpty API must be
77 WINPTY_API void winpty_error_free(winpty_error_ptr_t err);
81 /*****************************************************************************
82 * Configuration of a new agent. */
84 /* The winpty_config_t object is not thread-safe. */
85 typedef struct winpty_config_s winpty_config_t;
87 /* Allocate a winpty_config_t value. Returns NULL on error. There are no
88 * required settings -- the object may immediately be used. agentFlags is a
89 * set of zero or more WINPTY_FLAG_xxx values. An unrecognized flag results
90 * in an assertion failure. */
91 WINPTY_API winpty_config_t *
92 winpty_config_new(UINT64 agentFlags, winpty_error_ptr_t *err /*OPTIONAL*/);
94 /* Free the cfg object after passing it to winpty_open. */
95 WINPTY_API void winpty_config_free(winpty_config_t *cfg);
98 winpty_config_set_initial_size(winpty_config_t *cfg, int cols, int rows);
100 /* Set the mouse mode to one of the WINPTY_MOUSE_MODE_xxx constants. */
102 winpty_config_set_mouse_mode(winpty_config_t *cfg, int mouseMode);
104 /* Amount of time to wait for the agent to startup and to wait for any given
105 * agent RPC request. Must be greater than 0. Can be INFINITE. */
107 winpty_config_set_agent_timeout(winpty_config_t *cfg, DWORD timeoutMs);
111 /*****************************************************************************
112 * Start the agent. */
114 /* The winpty_t object is thread-safe. */
115 typedef struct winpty_s winpty_t;
117 /* Starts the agent. Returns NULL on error. This process will connect to the
118 * agent over a control pipe, and the agent will open data pipes (e.g. CONIN
120 WINPTY_API winpty_t *
121 winpty_open(const winpty_config_t *cfg,
122 winpty_error_ptr_t *err /*OPTIONAL*/);
124 /* A handle to the agent process. This value is valid for the lifetime of the
125 * winpty_t object. Do not close it. */
126 WINPTY_API HANDLE winpty_agent_process(winpty_t *wp);
130 /*****************************************************************************
133 /* Returns the names of named pipes used for terminal I/O. Each input or
134 * output direction uses a different half-duplex pipe. The agent creates
135 * these pipes, and the client can connect to them using ordinary I/O methods.
136 * The strings are freed when the winpty_t object is freed.
138 * winpty_conerr_name returns NULL unless WINPTY_FLAG_CONERR is specified.
140 * N.B.: CreateFile does not block when connecting to a local server pipe. If
141 * the server pipe does not exist or is already connected, then it fails
143 WINPTY_API LPCWSTR winpty_conin_name(winpty_t *wp);
144 WINPTY_API LPCWSTR winpty_conout_name(winpty_t *wp);
145 WINPTY_API LPCWSTR winpty_conerr_name(winpty_t *wp);
149 /*****************************************************************************
150 * winpty agent RPC call: process creation. */
152 /* The winpty_spawn_config_t object is not thread-safe. */
153 typedef struct winpty_spawn_config_s winpty_spawn_config_t;
155 /* winpty_spawn_config strings do not need to live as long as the config
156 * object. They are copied. Returns NULL on error. spawnFlags is a set of
157 * zero or more WINPTY_SPAWN_FLAG_xxx values. An unrecognized flag results in
158 * an assertion failure.
160 * env is a a pointer to an environment block like that passed to
161 * CreateProcess--a contiguous array of NUL-terminated "VAR=VAL" strings
162 * followed by a final NUL terminator.
164 * N.B.: If you want to gather all of the child's output, you may want the
165 * WINPTY_SPAWN_FLAG_AUTO_SHUTDOWN flag.
167 WINPTY_API winpty_spawn_config_t *
168 winpty_spawn_config_new(UINT64 spawnFlags,
169 LPCWSTR appname /*OPTIONAL*/,
170 LPCWSTR cmdline /*OPTIONAL*/,
171 LPCWSTR cwd /*OPTIONAL*/,
172 LPCWSTR env /*OPTIONAL*/,
173 winpty_error_ptr_t *err /*OPTIONAL*/);
175 /* Free the cfg object after passing it to winpty_spawn. */
176 WINPTY_API void winpty_spawn_config_free(winpty_spawn_config_t *cfg);
179 * Spawns the new process.
181 * The function initializes all output parameters to zero or NULL.
183 * On success, the function returns TRUE. For each of process_handle and
184 * thread_handle that is non-NULL, the HANDLE returned from CreateProcess is
185 * duplicated from the agent and returned to the winpty client. The client is
186 * responsible for closing these HANDLES.
188 * On failure, the function returns FALSE, and if err is non-NULL, then *err
189 * is set to an error object.
191 * If the agent's CreateProcess call failed, then *create_process_error is set
192 * to GetLastError(), and the WINPTY_ERROR_SPAWN_CREATE_PROCESS_FAILED error
195 * winpty_spawn can only be called once per winpty_t object. If it is called
196 * before the output data pipe(s) is/are connected, then collected output is
197 * buffered until the pipes are connected, rather than being discarded.
199 * N.B.: GetProcessId works even if the process has exited. The PID is not
200 * recycled until the NT process object is freed.
201 * (https://blogs.msdn.microsoft.com/oldnewthing/20110107-00/?p=11803)
204 winpty_spawn(winpty_t *wp,
205 const winpty_spawn_config_t *cfg,
206 HANDLE *process_handle /*OPTIONAL*/,
207 HANDLE *thread_handle /*OPTIONAL*/,
208 DWORD *create_process_error /*OPTIONAL*/,
209 winpty_error_ptr_t *err /*OPTIONAL*/);
213 /*****************************************************************************
214 * winpty agent RPC calls: everything else */
216 /* Change the size of the Windows console window. */
218 winpty_set_size(winpty_t *wp, int cols, int rows,
219 winpty_error_ptr_t *err /*OPTIONAL*/);
221 /* Gets a list of processes attached to the console. */
223 winpty_get_console_process_list(winpty_t *wp, int *processList, const int processCount,
224 winpty_error_ptr_t *err /*OPTIONAL*/);
226 /* Frees the winpty_t object and the OS resources contained in it. This
227 * call breaks the connection with the agent, which should then close its
228 * console, terminating the processes attached to it.
230 * This function must not be called if any other threads are using the
231 * winpty_t object. Undefined behavior results. */
232 WINPTY_API void winpty_free(winpty_t *wp);
236 /****************************************************************************/
242 #endif /* WINPTY_H */