Debian Codegraph @

modules/lsp-runtime-lib/include/lsp-plug.in/ipc/Process.h

raw
1 /*
2 * Copyright (C) 2025 Linux Studio Plugins Project <https://lsp-plug.in/>
3 * (C) 2025 Vladimir Sadovnikov <[email protected]>
4 *
5 * This file is part of lsp-runtime-lib
6 * Created on: 24 июл. 2019 г.
7 *
8 * lsp-runtime-lib is free software: you can redistribute it and/or modify
9 * it under the terms of the GNU Lesser General Public License as published by
10 * the Free Software Foundation, either version 3 of the License, or
11 * any later version.
12 *
13 * lsp-runtime-lib is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with lsp-runtime-lib. If not, see <https://www.gnu.org/licenses/>.
20 */
21
22 #ifndef LSP_PLUG_IN_IPC_PROCESS_H_
23 #define LSP_PLUG_IN_IPC_PROCESS_H_
24
25 #include <lsp-plug.in/runtime/version.h>
26 #include <lsp-plug.in/runtime/LSPString.h>
27 #include <lsp-plug.in/common/types.h>
28 #include <lsp-plug.in/common/status.h>
29 #include <lsp-plug.in/io/IInStream.h>
30 #include <lsp-plug.in/io/IOutStream.h>
31 #include <lsp-plug.in/lltl/parray.h>
32
33 #include <unistd.h>
34
35 namespace lsp
36 {
37 namespace ipc
38 {
39 /**
40 * Class for running processes
41 */
42 class Process
43 {
44 public:
45 enum pstatus_t {
46 PSTATUS_CREATED,
47 PSTATUS_RUNNING,
48 PSTATUS_EXITED,
49 PSTATUS_ERROR,
50 PSTATUS_RUNNING_ERROR
51 };
52
53 private:
54 typedef struct envvar_t {
55 LSPString name;
56 LSPString value;
57 } envvar_t;
58
59 #ifdef PLATFORM_WINDOWS
60 typedef void *HANDLE;
61 #endif /* PLATFORM_WINDOWS */
62
63 private:
64 LSPString sCommand;
65 lltl::parray<LSPString> vArgs;
66 lltl::parray<envvar_t> vEnv;
67 pstatus_t nStatus;
68 int nExitCode;
69
70 #ifdef PLATFORM_WINDOWS
71 uint32_t nPID;
72 HANDLE hProcess;
73 HANDLE hStdIn;
74 HANDLE hStdOut;
75 HANDLE hStdErr;
76 #else
77 pid_t nPID;
78 int hStdIn;
79 int hStdOut;
80 int hStdErr;
81 #endif /* PLATFORM_WINDOWS */
82
83 io::IOutStream *pStdIn;
84 io::IInStream *pStdOut;
85 io::IInStream *pStdErr;
86
87 protected:
88 static void destroy_args(lltl::parray<LSPString> *args);
89 static void destroy_env(lltl::parray<envvar_t> *env);
90 void close_handles();
91
92 #ifdef PLATFORM_WINDOWS
93 static status_t append_arg_escaped(LSPString *dst, const LSPString *value);
94 status_t build_argv(LSPString *dst);
95 status_t build_envp(LSPString *dst);
96 #else
97 status_t build_argv(lltl::parray<char> *dst);
98 status_t build_envp(lltl::parray<char> *dst);
99 status_t spawn_process(const char *cmd, char * const *argv, char * const *envp);
100 status_t vfork_process(const char *cmd, char * const *argv, char * const *envp);
101 status_t fork_process(const char *cmd, char * const *argv, char * const *envp);
102 void execvpe_process(const char *cmd, char * const *argv, char * const *envp, bool soft_exit);
103 #endif /* PLATFORM_WINDOWS */
104
105 public:
106 explicit Process();
107 Process(const Process &) = delete;
108 Process(Process &&) = delete;
109 ~Process();
110
111 Process & operator = (const Process &) = delete;
112 Process & operator = (Process &&) = delete;
113
114 public:
115 /**
116 * Set command for execution
117 * @param cmd command to execute
118 * @return status of operation
119 */
120 status_t set_command(const LSPString *cmd);
121
122 /**
123 * Set command for execution
124 * @param cmd command to execute in UTF-8 encoding
125 * @return status of operation
126 */
127 status_t set_command(const char *cmd);
128
129 public:
130 /**
131 * Get overall number of additional command-line arguments
132 * @return number of additional command-line arguments
133 */
134 size_t args() const;
135
136 /**
137 * Add argument at the end of command line
138 * @param value argument value
139 * @return status of operation
140 */
141 status_t add_arg(const LSPString *value);
142
143 /**
144 * Add argument at the end of command line
145 * @param value argument value in UTF-8 encoding
146 * @return status of operation
147 */
148 status_t add_arg(const char *value);
149
150 /**
151 * Set value of argument at the specified place
152 * @param value argument value
153 * @return status of operation
154 */
155 status_t set_arg(size_t index, const LSPString *value);
156
157 /**
158 * Set value of argument at the specified place
159 * @param value argument value in UTF-8 encoding
160 * @return status of operation
161 */
162 status_t set_arg(size_t index, const char *value);
163
164 /**
165 * Get value of argument at the specified place
166 * @param value pointer to store argument value
167 * @return status of operation
168 */
169 status_t get_arg(size_t index, LSPString *value);
170
171 /**
172 * Get value of argument at the specified place
173 * @param value pointer to store argument value
174 * @return status of operation
175 */
176 status_t get_arg(size_t index, char **value);
177
178 /**
179 * Remove the argument at the specified place
180 * @param value pointer to store value of removed argument
181 * @return status of operation
182 */
183 status_t remove_arg(size_t index, LSPString *value = NULL);
184
185 /**
186 * Remove the argument at the specified place
187 * @param value pointer to store value of removed argument.
188 * The pointer should be free()'d after use
189 * @return status of operation
190 */
191 status_t remove_arg(size_t index, char **value = NULL);
192
193 /**
194 * Insert argument at the specified position
195 * @param value argument value
196 * @return status of operation
197 */
198 status_t insert_arg(size_t index, const LSPString *value);
199
200 /**
201 * Insert argument at the specified position
202 * @param value argument value in UTF-8 encoding
203 * @return status of operation
204 */
205 status_t insert_arg(size_t index, const char *value);
206
207 /**
208 * Clear arguments;
209 * @return status of operation
210 */
211 status_t clear_args();
212
213 public:
214 /**
215 * Return number of environment variables
216 * @return number of environment variables
217 */
218 size_t envs() const;
219
220 /**
221 * Set value of the specific environment variable
222 * @param key the name of environment variable
223 * @param value the value of environment variable
224 * @return status of operation
225 */
226 status_t set_env(const LSPString *key, const LSPString *value);
227
228 /**
229 * Set value of the specific environment variable
230 * @param key the name of environment variable in UTF-8 encoding
231 * @param value the value of environment variable in UTF-8 encoding
232 * @return status of operation
233 */
234 status_t set_env(const char *key, const char *value);
235
236 /**
237 * Remove the specific environment variable
238 * @param key the name of environment variable
239 * @param value pointer to store value of the removed environment variable
240 * @return status of operation
241 */
242 status_t remove_env(const LSPString *key, LSPString *value = NULL);
243
244 /**
245 * Remove the specific environment variable
246 * @param key the name of environment variable
247 * @param value pointer to store value of the removed environment variable
248 * @return status of operation
249 */
250 status_t remove_env(const char *key, LSPString *value = NULL);
251
252 /**
253 * Remove the specific environment variable
254 * @param key the name of environment variable in UTF-8 encoding
255 * @param value pointer to store value of the removed environment variable in UTF-8 encoding.
256 * The obtained pointer should be free()'d after use
257 * @return status of operation
258 */
259 status_t remove_env(const char *key, char **value = NULL);
260
261 /**
262 * Obtain the value of the specific environment variable
263 * @param key the name of environment variable
264 * @param value pointer to store value of the environment variable
265 * @return status of operation
266 */
267 status_t get_env(const LSPString *key, LSPString *value = NULL);
268
269 /**
270 * Obtain the value of the specific environment variable
271 * @param key the name of environment variable
272 * @param value pointer to store value of the environment variable
273 * @return status of operation
274 */
275 status_t get_env(const char *key, LSPString *value = NULL);
276
277 /**
278 * Obtain the value of the specific environment variable
279 * @param key the name of environment variable in UTF-8 encoding
280 * @param value pointer to store value of the environment variable in UTF-8 encoding.
281 * The obtained pointer should be free()'d after use
282 * @return status of operation
283 */
284 status_t get_env(const char *key, char **value = NULL);
285
286 /**
287 * Obtain the key and value of environment variable by index
288 * @param idx the environment variable index
289 * @param key environment variable key
290 * @param value environment variable value
291 * @return status of operation
292 */
293 status_t read_env(size_t idx, LSPString *key = NULL, LSPString *value = NULL);
294
295 /**
296 * Obtain the value of the specific environment variable
297 * @param idx the environment variable index
298 * @param key the name of environment variable in UTF-8 encoding
299 * The obtained pointer should be free()'d after use
300 * @param value pointer to store value of the environment variable in UTF-8 encoding.
301 * The obtained pointer should be free()'d after use
302 * @return status of operation
303 */
304 status_t read_env(size_t idx, char **key = NULL, char **value = NULL);
305
306 /**
307 * Clear all environment variables
308 * @return status of operation
309 */
310 status_t clear_env();
311
312 public:
313 /**
314 * Return redirected standard input stream of the process.
315 * The redirection is allowed before successful launch() has been issued.
316 *
317 * @return pointer to standard input stream
318 */
319 io::IOutStream *get_stdin();
320
321 /**
322 * Return redirected standard output stream of the process.
323 * The redirection is allowed before successful launch() has been issued.
324 *
325 * @return pointer to standard output stream
326 */
327 io::IInStream *get_stdout();
328
329 /**
330 * Return redirected standard error stream of the process.
331 * The redirection is allowed before successful launch() has been issued.
332 *
333 * @return pointer to standard error stream
334 */
335 io::IInStream *get_stderr();
336
337 /**
338 * Get process status
339 * @return process status
340 */
341 size_t status();
342
343 /**
344 * Copy environment variables of the current process
345 * @return status of operation
346 */
347 status_t copy_env();
348
349 /**
350 * Launch the process
351 * @return status of operation
352 */
353 status_t launch();
354
355 /**
356 * Chech that the object is not in error state
357 * @return true if object is in not error state
358 */
359 bool valid();
360
361 /**
362 * Check that process is in running state
363 * @return true if process is in running state
364 */
365 bool running();
366
367 /**
368 * Check that process has exited
369 * @return true if process has exited
370 */
371 bool exited();
372
373 /**
374 * Get unique process identifier
375 * @return process identifier
376 */
377 ssize_t process_id() const;
378
379 /**
380 * Wait for the process termination
381 * @param millis number of milliseconds to wait, negative value means infinite wait
382 * @return status of operation
383 */
384 status_t wait(wssize_t millis = -1);
385
386 /**
387 * Get process exit status
388 * @param code pointer to save exit status
389 * @return status of operation
390 */
391 status_t exit_code(int *code);
392 };
393
394 } /* namespace ipc */
395 } /* namespace lsp */
396
397 #endif /* LSP_PLUG_IN_IPC_PROCESS_H_ */