1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gio.SubprocessLauncher;
26 
27 private import gio.Subprocess;
28 private import gio.c.functions;
29 public  import gio.c.types;
30 private import glib.ConstructionException;
31 private import glib.ErrorG;
32 private import glib.GException;
33 private import glib.Str;
34 private import glib.c.functions;
35 private import gobject.ObjectG;
36 
37 
38 /**
39  * This class contains a set of options for launching child processes,
40  * such as where its standard input and output will be directed, the
41  * argument list, the environment, and more.
42  * 
43  * While the #GSubprocess class has high level functions covering
44  * popular cases, use of this class allows access to more advanced
45  * options.  It can also be used to launch multiple subprocesses with
46  * a similar configuration.
47  *
48  * Since: 2.40
49  */
50 public class SubprocessLauncher : ObjectG
51 {
52 	/** the main Gtk struct */
53 	protected GSubprocessLauncher* gSubprocessLauncher;
54 
55 	/** Get the main Gtk struct */
56 	public GSubprocessLauncher* getSubprocessLauncherStruct(bool transferOwnership = false)
57 	{
58 		if (transferOwnership)
59 			ownedRef = false;
60 		return gSubprocessLauncher;
61 	}
62 
63 	/** the main Gtk struct as a void* */
64 	protected override void* getStruct()
65 	{
66 		return cast(void*)gSubprocessLauncher;
67 	}
68 
69 	/**
70 	 * Sets our main struct and passes it to the parent class.
71 	 */
72 	public this (GSubprocessLauncher* gSubprocessLauncher, bool ownedRef = false)
73 	{
74 		this.gSubprocessLauncher = gSubprocessLauncher;
75 		super(cast(GObject*)gSubprocessLauncher, ownedRef);
76 	}
77 
78 
79 	/** */
80 	public static GType getType()
81 	{
82 		return g_subprocess_launcher_get_type();
83 	}
84 
85 	/**
86 	 * Creates a new #GSubprocessLauncher.
87 	 *
88 	 * The launcher is created with the default options.  A copy of the
89 	 * environment of the calling process is made at the time of this call
90 	 * and will be used as the environment that the process is launched in.
91 	 *
92 	 * Params:
93 	 *     flags = #GSubprocessFlags
94 	 *
95 	 * Since: 2.40
96 	 *
97 	 * Throws: ConstructionException GTK+ fails to create the object.
98 	 */
99 	public this(GSubprocessFlags flags)
100 	{
101 		auto __p = g_subprocess_launcher_new(flags);
102 
103 		if(__p is null)
104 		{
105 			throw new ConstructionException("null returned by new");
106 		}
107 
108 		this(cast(GSubprocessLauncher*) __p, true);
109 	}
110 
111 	/**
112 	 * Closes all the file descriptors previously passed to the object with
113 	 * g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc.
114 	 *
115 	 * After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or g_subprocess_launcher_spawnv() will
116 	 * return %G_IO_ERROR_CLOSED. This method is idempotent if
117 	 * called more than once.
118 	 *
119 	 * This function is called automatically when the #GSubprocessLauncher
120 	 * is disposed, but is provided separately so that garbage collected
121 	 * language bindings can call it earlier to guarantee when FDs are closed.
122 	 *
123 	 * Since: 2.68
124 	 */
125 	public void close()
126 	{
127 		g_subprocess_launcher_close(gSubprocessLauncher);
128 	}
129 
130 	/**
131 	 * Returns the value of the environment variable @variable in the
132 	 * environment of processes launched from this launcher.
133 	 *
134 	 * On UNIX, the returned string can be an arbitrary byte string.
135 	 * On Windows, it will be UTF-8.
136 	 *
137 	 * Params:
138 	 *     variable = the environment variable to get
139 	 *
140 	 * Returns: the value of the environment variable,
141 	 *     %NULL if unset
142 	 *
143 	 * Since: 2.40
144 	 */
145 	public string getenv(string variable)
146 	{
147 		return Str.toString(g_subprocess_launcher_getenv(gSubprocessLauncher, Str.toStringz(variable)));
148 	}
149 
150 	/**
151 	 * Sets up a child setup function.
152 	 *
153 	 * The child setup function will be called after fork() but before
154 	 * exec() on the child's side.
155 	 *
156 	 * @destroy_notify will not be automatically called on the child's side
157 	 * of the fork().  It will only be called when the last reference on the
158 	 * #GSubprocessLauncher is dropped or when a new child setup function is
159 	 * given.
160 	 *
161 	 * %NULL can be given as @child_setup to disable the functionality.
162 	 *
163 	 * Child setup functions are only available on UNIX.
164 	 *
165 	 * Params:
166 	 *     childSetup = a #GSpawnChildSetupFunc to use as the child setup function
167 	 *     userData = user data for @child_setup
168 	 *     destroyNotify = a #GDestroyNotify for @user_data
169 	 *
170 	 * Since: 2.40
171 	 */
172 	public void setChildSetup(GSpawnChildSetupFunc childSetup, void* userData, GDestroyNotify destroyNotify)
173 	{
174 		g_subprocess_launcher_set_child_setup(gSubprocessLauncher, childSetup, userData, destroyNotify);
175 	}
176 
177 	/**
178 	 * Sets the current working directory that processes will be launched
179 	 * with.
180 	 *
181 	 * By default processes are launched with the current working directory
182 	 * of the launching process at the time of launch.
183 	 *
184 	 * Params:
185 	 *     cwd = the cwd for launched processes
186 	 *
187 	 * Since: 2.40
188 	 */
189 	public void setCwd(string cwd)
190 	{
191 		g_subprocess_launcher_set_cwd(gSubprocessLauncher, Str.toStringz(cwd));
192 	}
193 
194 	/**
195 	 * Replace the entire environment of processes launched from this
196 	 * launcher with the given 'environ' variable.
197 	 *
198 	 * Typically you will build this variable by using g_listenv() to copy
199 	 * the process 'environ' and using the functions g_environ_setenv(),
200 	 * g_environ_unsetenv(), etc.
201 	 *
202 	 * As an alternative, you can use g_subprocess_launcher_setenv(),
203 	 * g_subprocess_launcher_unsetenv(), etc.
204 	 *
205 	 * Pass an empty array to set an empty environment. Pass %NULL to inherit the
206 	 * parent process’ environment. As of GLib 2.54, the parent process’ environment
207 	 * will be copied when g_subprocess_launcher_set_environ() is called.
208 	 * Previously, it was copied when the subprocess was executed. This means the
209 	 * copied environment may now be modified (using g_subprocess_launcher_setenv(),
210 	 * etc.) before launching the subprocess.
211 	 *
212 	 * On UNIX, all strings in this array can be arbitrary byte strings.
213 	 * On Windows, they should be in UTF-8.
214 	 *
215 	 * Params:
216 	 *     env = the replacement environment
217 	 *
218 	 * Since: 2.40
219 	 */
220 	public void setEnviron(string[] env)
221 	{
222 		g_subprocess_launcher_set_environ(gSubprocessLauncher, Str.toStringzArray(env));
223 	}
224 
225 	/**
226 	 * Sets the flags on the launcher.
227 	 *
228 	 * The default flags are %G_SUBPROCESS_FLAGS_NONE.
229 	 *
230 	 * You may not set flags that specify conflicting options for how to
231 	 * handle a particular stdio stream (eg: specifying both
232 	 * %G_SUBPROCESS_FLAGS_STDIN_PIPE and
233 	 * %G_SUBPROCESS_FLAGS_STDIN_INHERIT).
234 	 *
235 	 * You may also not set a flag that conflicts with a previous call to a
236 	 * function like g_subprocess_launcher_set_stdin_file_path() or
237 	 * g_subprocess_launcher_take_stdout_fd().
238 	 *
239 	 * Params:
240 	 *     flags = #GSubprocessFlags
241 	 *
242 	 * Since: 2.40
243 	 */
244 	public void setFlags(GSubprocessFlags flags)
245 	{
246 		g_subprocess_launcher_set_flags(gSubprocessLauncher, flags);
247 	}
248 
249 	/**
250 	 * Sets the file path to use as the stderr for spawned processes.
251 	 *
252 	 * If @path is %NULL then any previously given path is unset.
253 	 *
254 	 * The file will be created or truncated when the process is spawned, as
255 	 * would be the case if using '2>' at the shell.
256 	 *
257 	 * If you want to send both stdout and stderr to the same file then use
258 	 * %G_SUBPROCESS_FLAGS_STDERR_MERGE.
259 	 *
260 	 * You may not set a stderr file path if a stderr fd is already set or
261 	 * if the launcher flags contain any flags directing stderr elsewhere.
262 	 *
263 	 * This feature is only available on UNIX.
264 	 *
265 	 * Params:
266 	 *     path = a filename or %NULL
267 	 *
268 	 * Since: 2.40
269 	 */
270 	public void setStderrFilePath(string path)
271 	{
272 		g_subprocess_launcher_set_stderr_file_path(gSubprocessLauncher, Str.toStringz(path));
273 	}
274 
275 	/**
276 	 * Sets the file path to use as the stdin for spawned processes.
277 	 *
278 	 * If @path is %NULL then any previously given path is unset.
279 	 *
280 	 * The file must exist or spawning the process will fail.
281 	 *
282 	 * You may not set a stdin file path if a stdin fd is already set or if
283 	 * the launcher flags contain any flags directing stdin elsewhere.
284 	 *
285 	 * This feature is only available on UNIX.
286 	 *
287 	 * Since: 2.40
288 	 */
289 	public void setStdinFilePath(string path)
290 	{
291 		g_subprocess_launcher_set_stdin_file_path(gSubprocessLauncher, Str.toStringz(path));
292 	}
293 
294 	/**
295 	 * Sets the file path to use as the stdout for spawned processes.
296 	 *
297 	 * If @path is %NULL then any previously given path is unset.
298 	 *
299 	 * The file will be created or truncated when the process is spawned, as
300 	 * would be the case if using '>' at the shell.
301 	 *
302 	 * You may not set a stdout file path if a stdout fd is already set or
303 	 * if the launcher flags contain any flags directing stdout elsewhere.
304 	 *
305 	 * This feature is only available on UNIX.
306 	 *
307 	 * Params:
308 	 *     path = a filename or %NULL
309 	 *
310 	 * Since: 2.40
311 	 */
312 	public void setStdoutFilePath(string path)
313 	{
314 		g_subprocess_launcher_set_stdout_file_path(gSubprocessLauncher, Str.toStringz(path));
315 	}
316 
317 	/**
318 	 * Sets the environment variable @variable in the environment of
319 	 * processes launched from this launcher.
320 	 *
321 	 * On UNIX, both the variable's name and value can be arbitrary byte
322 	 * strings, except that the variable's name cannot contain '='.
323 	 * On Windows, they should be in UTF-8.
324 	 *
325 	 * Params:
326 	 *     variable = the environment variable to set,
327 	 *         must not contain '='
328 	 *     value = the new value for the variable
329 	 *     overwrite = whether to change the variable if it already exists
330 	 *
331 	 * Since: 2.40
332 	 */
333 	public void setenv(string variable, string value, bool overwrite)
334 	{
335 		g_subprocess_launcher_setenv(gSubprocessLauncher, Str.toStringz(variable), Str.toStringz(value), overwrite);
336 	}
337 
338 	/**
339 	 * Creates a #GSubprocess given a provided array of arguments.
340 	 *
341 	 * Params:
342 	 *     argv = Command line arguments
343 	 *
344 	 * Returns: A new #GSubprocess, or %NULL on error (and @error will be set)
345 	 *
346 	 * Since: 2.40
347 	 *
348 	 * Throws: GException on failure.
349 	 */
350 	public Subprocess spawnv(string[] argv)
351 	{
352 		GError* err = null;
353 
354 		auto __p = g_subprocess_launcher_spawnv(gSubprocessLauncher, Str.toStringzArray(argv), &err);
355 
356 		if (err !is null)
357 		{
358 			throw new GException( new ErrorG(err) );
359 		}
360 
361 		if(__p is null)
362 		{
363 			return null;
364 		}
365 
366 		return ObjectG.getDObject!(Subprocess)(cast(GSubprocess*) __p, true);
367 	}
368 
369 	/**
370 	 * Transfer an arbitrary file descriptor from parent process to the
371 	 * child.  This function takes ownership of the @source_fd; it will be closed
372 	 * in the parent when @self is freed.
373 	 *
374 	 * By default, all file descriptors from the parent will be closed.
375 	 * This function allows you to create (for example) a custom `pipe()` or
376 	 * `socketpair()` before launching the process, and choose the target
377 	 * descriptor in the child.
378 	 *
379 	 * An example use case is GNUPG, which has a command line argument
380 	 * `--passphrase-fd` providing a file descriptor number where it expects
381 	 * the passphrase to be written.
382 	 *
383 	 * Params:
384 	 *     sourceFd = File descriptor in parent process
385 	 *     targetFd = Target descriptor for child process
386 	 */
387 	public void takeFd(int sourceFd, int targetFd)
388 	{
389 		g_subprocess_launcher_take_fd(gSubprocessLauncher, sourceFd, targetFd);
390 	}
391 
392 	/**
393 	 * Sets the file descriptor to use as the stderr for spawned processes.
394 	 *
395 	 * If @fd is -1 then any previously given fd is unset.
396 	 *
397 	 * Note that the default behaviour is to pass stderr through to the
398 	 * stderr of the parent process.
399 	 *
400 	 * The passed @fd belongs to the #GSubprocessLauncher.  It will be
401 	 * automatically closed when the launcher is finalized.  The file
402 	 * descriptor will also be closed on the child side when executing the
403 	 * spawned process.
404 	 *
405 	 * You may not set a stderr fd if a stderr file path is already set or
406 	 * if the launcher flags contain any flags directing stderr elsewhere.
407 	 *
408 	 * This feature is only available on UNIX.
409 	 *
410 	 * Params:
411 	 *     fd = a file descriptor, or -1
412 	 *
413 	 * Since: 2.40
414 	 */
415 	public void takeStderrFd(int fd)
416 	{
417 		g_subprocess_launcher_take_stderr_fd(gSubprocessLauncher, fd);
418 	}
419 
420 	/**
421 	 * Sets the file descriptor to use as the stdin for spawned processes.
422 	 *
423 	 * If @fd is -1 then any previously given fd is unset.
424 	 *
425 	 * Note that if your intention is to have the stdin of the calling
426 	 * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT
427 	 * is a better way to go about doing that.
428 	 *
429 	 * The passed @fd is noted but will not be touched in the current
430 	 * process.  It is therefore necessary that it be kept open by the
431 	 * caller until the subprocess is spawned.  The file descriptor will
432 	 * also not be explicitly closed on the child side, so it must be marked
433 	 * O_CLOEXEC if that's what you want.
434 	 *
435 	 * You may not set a stdin fd if a stdin file path is already set or if
436 	 * the launcher flags contain any flags directing stdin elsewhere.
437 	 *
438 	 * This feature is only available on UNIX.
439 	 *
440 	 * Params:
441 	 *     fd = a file descriptor, or -1
442 	 *
443 	 * Since: 2.40
444 	 */
445 	public void takeStdinFd(int fd)
446 	{
447 		g_subprocess_launcher_take_stdin_fd(gSubprocessLauncher, fd);
448 	}
449 
450 	/**
451 	 * Sets the file descriptor to use as the stdout for spawned processes.
452 	 *
453 	 * If @fd is -1 then any previously given fd is unset.
454 	 *
455 	 * Note that the default behaviour is to pass stdout through to the
456 	 * stdout of the parent process.
457 	 *
458 	 * The passed @fd is noted but will not be touched in the current
459 	 * process.  It is therefore necessary that it be kept open by the
460 	 * caller until the subprocess is spawned.  The file descriptor will
461 	 * also not be explicitly closed on the child side, so it must be marked
462 	 * O_CLOEXEC if that's what you want.
463 	 *
464 	 * You may not set a stdout fd if a stdout file path is already set or
465 	 * if the launcher flags contain any flags directing stdout elsewhere.
466 	 *
467 	 * This feature is only available on UNIX.
468 	 *
469 	 * Params:
470 	 *     fd = a file descriptor, or -1
471 	 *
472 	 * Since: 2.40
473 	 */
474 	public void takeStdoutFd(int fd)
475 	{
476 		g_subprocess_launcher_take_stdout_fd(gSubprocessLauncher, fd);
477 	}
478 
479 	/**
480 	 * Removes the environment variable @variable from the environment of
481 	 * processes launched from this launcher.
482 	 *
483 	 * On UNIX, the variable's name can be an arbitrary byte string not
484 	 * containing '='. On Windows, it should be in UTF-8.
485 	 *
486 	 * Params:
487 	 *     variable = the environment variable to unset,
488 	 *         must not contain '='
489 	 *
490 	 * Since: 2.40
491 	 */
492 	public void unsetenv(string variable)
493 	{
494 		g_subprocess_launcher_unsetenv(gSubprocessLauncher, Str.toStringz(variable));
495 	}
496 }