node_modules/node-pty/deps/winpty/src/include/winpty.h

   1 /*
   2  * Copyright (c) 2011-2016 Ryan Prichard
   3  *
   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:
  10  *
  11  * The above copyright notice and this permission notice shall be included in
  12  * all copies or substantial portions of the Software.
  13  *
  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
  20  * IN THE SOFTWARE.
  21  */
  22
  23 #ifndef WINPTY_H
  24 #define WINPTY_H
  25
  26 #include <windows.h>
  27
  28 #include "winpty_constants.h"
  29
  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)
  37 #else
  38 #define WINPTY_API __declspec(dllimport)
  39 #endif
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  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.) */
  50
  51
  52
  53 /*****************************************************************************
  54  * Error handling. */
  55
  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. */
  60
  61 /* An error object. */
  62 typedef struct winpty_error_s winpty_error_t;
  63 typedef winpty_error_t *winpty_error_ptr_t;
  64
  65 /* An error code -- one of WINPTY_ERROR_xxx. */
  66 typedef DWORD winpty_result_t;
  67
  68 /* Gets the error code from the error object. */
  69 WINPTY_API winpty_result_t winpty_error_code(winpty_error_ptr_t err);
  70
  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);
  74
  75 /* Free the error object.  Every error returned from the winpty API must be
  76  * freed. */
  77 WINPTY_API void winpty_error_free(winpty_error_ptr_t err);
  78
  79
  80
  81 /*****************************************************************************
  82  * Configuration of a new agent. */
  83
  84 /* The winpty_config_t object is not thread-safe. */
  85 typedef struct winpty_config_s winpty_config_t;
  86
  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*/);
  93
  94 /* Free the cfg object after passing it to winpty_open. */
  95 WINPTY_API void winpty_config_free(winpty_config_t *cfg);
  96
  97 WINPTY_API void
  98 winpty_config_set_initial_size(winpty_config_t *cfg, int cols, int rows);
  99
 100 /* Set the mouse mode to one of the WINPTY_MOUSE_MODE_xxx constants. */
 101 WINPTY_API void
 102 winpty_config_set_mouse_mode(winpty_config_t *cfg, int mouseMode);
 103
 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. */
 106 WINPTY_API void
 107 winpty_config_set_agent_timeout(winpty_config_t *cfg, DWORD timeoutMs);
 108
 109
 110
 111 /*****************************************************************************
 112  * Start the agent. */
 113
 114 /* The winpty_t object is thread-safe. */
 115 typedef struct winpty_s winpty_t;
 116
 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
 119  * and CONOUT). */
 120 WINPTY_API winpty_t *
 121 winpty_open(const winpty_config_t *cfg,
 122             winpty_error_ptr_t *err /*OPTIONAL*/);
 123
 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);
 127
 128
 129
 130 /*****************************************************************************
 131  * I/O pipes. */
 132
 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.
 137  *
 138  * winpty_conerr_name returns NULL unless WINPTY_FLAG_CONERR is specified.
 139  *
 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
 142  * instantly. */
 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);
 146
 147
 148
 149 /*****************************************************************************
 150  * winpty agent RPC call: process creation. */
 151
 152 /* The winpty_spawn_config_t object is not thread-safe. */
 153 typedef struct winpty_spawn_config_s winpty_spawn_config_t;
 154
 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.
 159  *
 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.
 163  *
 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.
 166  */
 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*/);
 174
 175 /* Free the cfg object after passing it to winpty_spawn. */
 176 WINPTY_API void winpty_spawn_config_free(winpty_spawn_config_t *cfg);
 177
 178 /*
 179  * Spawns the new process.
 180  *
 181  * The function initializes all output parameters to zero or NULL.
 182  *
 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.
 187  *
 188  * On failure, the function returns FALSE, and if err is non-NULL, then *err
 189  * is set to an error object.
 190  *
 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
 193  * is returned.
 194  *
 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.
 198  *
 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)
 202  */
 203 WINPTY_API BOOL
 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*/);
 210
 211
 212
 213 /*****************************************************************************
 214  * winpty agent RPC calls: everything else */
 215
 216 /* Change the size of the Windows console window. */
 217 WINPTY_API BOOL
 218 winpty_set_size(winpty_t *wp, int cols, int rows,
 219                 winpty_error_ptr_t *err /*OPTIONAL*/);
 220
 221 /* Gets a list of processes attached to the console. */
 222 WINPTY_API int
 223 winpty_get_console_process_list(winpty_t *wp, int *processList, const int processCount,
 224                                 winpty_error_ptr_t *err /*OPTIONAL*/);
 225
 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.
 229  *
 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);
 233
 234
 235
 236 /****************************************************************************/
 237
 238 #ifdef __cplusplus
 239 }
 240 #endif
 241
 242 #endif /* WINPTY_H */