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 gobject.ObjectG;
35 public  import gtkc.giotypes;
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 	 * Returns the value of the environment variable @variable in the
113 	 * environment of processes launched from this launcher.
114 	 *
115 	 * On UNIX, the returned string can be an arbitrary byte string.
116 	 * On Windows, it will be UTF-8.
117 	 *
118 	 * Params:
119 	 *     variable = the environment variable to get
120 	 *
121 	 * Returns: the value of the environment variable,
122 	 *     %NULL if unset
123 	 *
124 	 * Since: 2.40
125 	 */
126 	public string getenv(string variable)
127 	{
128 		return Str.toString(g_subprocess_launcher_getenv(gSubprocessLauncher, Str.toStringz(variable)));
129 	}
130 
131 	/**
132 	 * Sets up a child setup function.
133 	 *
134 	 * The child setup function will be called after fork() but before
135 	 * exec() on the child's side.
136 	 *
137 	 * @destroy_notify will not be automatically called on the child's side
138 	 * of the fork().  It will only be called when the last reference on the
139 	 * #GSubprocessLauncher is dropped or when a new child setup function is
140 	 * given.
141 	 *
142 	 * %NULL can be given as @child_setup to disable the functionality.
143 	 *
144 	 * Child setup functions are only available on UNIX.
145 	 *
146 	 * Params:
147 	 *     childSetup = a #GSpawnChildSetupFunc to use as the child setup function
148 	 *     userData = user data for @child_setup
149 	 *     destroyNotify = a #GDestroyNotify for @user_data
150 	 *
151 	 * Since: 2.40
152 	 */
153 	public void setChildSetup(GSpawnChildSetupFunc childSetup, void* userData, GDestroyNotify destroyNotify)
154 	{
155 		g_subprocess_launcher_set_child_setup(gSubprocessLauncher, childSetup, userData, destroyNotify);
156 	}
157 
158 	/**
159 	 * Sets the current working directory that processes will be launched
160 	 * with.
161 	 *
162 	 * By default processes are launched with the current working directory
163 	 * of the launching process at the time of launch.
164 	 *
165 	 * Params:
166 	 *     cwd = the cwd for launched processes
167 	 *
168 	 * Since: 2.40
169 	 */
170 	public void setCwd(string cwd)
171 	{
172 		g_subprocess_launcher_set_cwd(gSubprocessLauncher, Str.toStringz(cwd));
173 	}
174 
175 	/**
176 	 * Replace the entire environment of processes launched from this
177 	 * launcher with the given 'environ' variable.
178 	 *
179 	 * Typically you will build this variable by using g_listenv() to copy
180 	 * the process 'environ' and using the functions g_environ_setenv(),
181 	 * g_environ_unsetenv(), etc.
182 	 *
183 	 * As an alternative, you can use g_subprocess_launcher_setenv(),
184 	 * g_subprocess_launcher_unsetenv(), etc.
185 	 *
186 	 * Pass an empty array to set an empty environment. Pass %NULL to inherit the
187 	 * parent process’ environment. As of GLib 2.54, the parent process’ environment
188 	 * will be copied when g_subprocess_launcher_set_environ() is called.
189 	 * Previously, it was copied when the subprocess was executed. This means the
190 	 * copied environment may now be modified (using g_subprocess_launcher_setenv(),
191 	 * etc.) before launching the subprocess.
192 	 *
193 	 * On UNIX, all strings in this array can be arbitrary byte strings.
194 	 * On Windows, they should be in UTF-8.
195 	 *
196 	 * Params:
197 	 *     env = the replacement environment
198 	 *
199 	 * Since: 2.40
200 	 */
201 	public void setEnviron(string[] env)
202 	{
203 		g_subprocess_launcher_set_environ(gSubprocessLauncher, Str.toStringzArray(env));
204 	}
205 
206 	/**
207 	 * Sets the flags on the launcher.
208 	 *
209 	 * The default flags are %G_SUBPROCESS_FLAGS_NONE.
210 	 *
211 	 * You may not set flags that specify conflicting options for how to
212 	 * handle a particular stdio stream (eg: specifying both
213 	 * %G_SUBPROCESS_FLAGS_STDIN_PIPE and
214 	 * %G_SUBPROCESS_FLAGS_STDIN_INHERIT).
215 	 *
216 	 * You may also not set a flag that conflicts with a previous call to a
217 	 * function like g_subprocess_launcher_set_stdin_file_path() or
218 	 * g_subprocess_launcher_take_stdout_fd().
219 	 *
220 	 * Params:
221 	 *     flags = #GSubprocessFlags
222 	 *
223 	 * Since: 2.40
224 	 */
225 	public void setFlags(GSubprocessFlags flags)
226 	{
227 		g_subprocess_launcher_set_flags(gSubprocessLauncher, flags);
228 	}
229 
230 	/**
231 	 * Sets the file path to use as the stderr for spawned processes.
232 	 *
233 	 * If @path is %NULL then any previously given path is unset.
234 	 *
235 	 * The file will be created or truncated when the process is spawned, as
236 	 * would be the case if using '2>' at the shell.
237 	 *
238 	 * If you want to send both stdout and stderr to the same file then use
239 	 * %G_SUBPROCESS_FLAGS_STDERR_MERGE.
240 	 *
241 	 * You may not set a stderr file path if a stderr fd is already set or
242 	 * if the launcher flags contain any flags directing stderr elsewhere.
243 	 *
244 	 * This feature is only available on UNIX.
245 	 *
246 	 * Params:
247 	 *     path = a filename or %NULL
248 	 *
249 	 * Since: 2.40
250 	 */
251 	public void setStderrFilePath(string path)
252 	{
253 		g_subprocess_launcher_set_stderr_file_path(gSubprocessLauncher, Str.toStringz(path));
254 	}
255 
256 	/**
257 	 * Sets the file path to use as the stdin for spawned processes.
258 	 *
259 	 * If @path is %NULL then any previously given path is unset.
260 	 *
261 	 * The file must exist or spawning the process will fail.
262 	 *
263 	 * You may not set a stdin file path if a stdin fd is already set or if
264 	 * the launcher flags contain any flags directing stdin elsewhere.
265 	 *
266 	 * This feature is only available on UNIX.
267 	 *
268 	 * Since: 2.40
269 	 */
270 	public void setStdinFilePath(string path)
271 	{
272 		g_subprocess_launcher_set_stdin_file_path(gSubprocessLauncher, Str.toStringz(path));
273 	}
274 
275 	/**
276 	 * Sets the file path to use as the stdout for spawned processes.
277 	 *
278 	 * If @path is %NULL then any previously given path is unset.
279 	 *
280 	 * The file will be created or truncated when the process is spawned, as
281 	 * would be the case if using '>' at the shell.
282 	 *
283 	 * You may not set a stdout file path if a stdout fd is already set or
284 	 * if the launcher flags contain any flags directing stdout elsewhere.
285 	 *
286 	 * This feature is only available on UNIX.
287 	 *
288 	 * Params:
289 	 *     path = a filename or %NULL
290 	 *
291 	 * Since: 2.40
292 	 */
293 	public void setStdoutFilePath(string path)
294 	{
295 		g_subprocess_launcher_set_stdout_file_path(gSubprocessLauncher, Str.toStringz(path));
296 	}
297 
298 	/**
299 	 * Sets the environment variable @variable in the environment of
300 	 * processes launched from this launcher.
301 	 *
302 	 * On UNIX, both the variable's name and value can be arbitrary byte
303 	 * strings, except that the variable's name cannot contain '='.
304 	 * On Windows, they should be in UTF-8.
305 	 *
306 	 * Params:
307 	 *     variable = the environment variable to set,
308 	 *         must not contain '='
309 	 *     value = the new value for the variable
310 	 *     overwrite = whether to change the variable if it already exists
311 	 *
312 	 * Since: 2.40
313 	 */
314 	public void setenv(string variable, string value, bool overwrite)
315 	{
316 		g_subprocess_launcher_setenv(gSubprocessLauncher, Str.toStringz(variable), Str.toStringz(value), overwrite);
317 	}
318 
319 	/**
320 	 * Creates a #GSubprocess given a provided array of arguments.
321 	 *
322 	 * Params:
323 	 *     argv = Command line arguments
324 	 *
325 	 * Returns: A new #GSubprocess, or %NULL on error (and @error will be set)
326 	 *
327 	 * Since: 2.40
328 	 *
329 	 * Throws: GException on failure.
330 	 */
331 	public Subprocess spawnv(string[] argv)
332 	{
333 		GError* err = null;
334 
335 		auto p = g_subprocess_launcher_spawnv(gSubprocessLauncher, Str.toStringzArray(argv), &err);
336 
337 		if (err !is null)
338 		{
339 			throw new GException( new ErrorG(err) );
340 		}
341 
342 		if(p is null)
343 		{
344 			return null;
345 		}
346 
347 		return ObjectG.getDObject!(Subprocess)(cast(GSubprocess*) p, true);
348 	}
349 
350 	/**
351 	 * Transfer an arbitrary file descriptor from parent process to the
352 	 * child.  This function takes "ownership" of the fd; it will be closed
353 	 * in the parent when @self is freed.
354 	 *
355 	 * By default, all file descriptors from the parent will be closed.
356 	 * This function allows you to create (for example) a custom pipe() or
357 	 * socketpair() before launching the process, and choose the target
358 	 * descriptor in the child.
359 	 *
360 	 * An example use case is GNUPG, which has a command line argument
361 	 * --passphrase-fd providing a file descriptor number where it expects
362 	 * the passphrase to be written.
363 	 *
364 	 * Params:
365 	 *     sourceFd = File descriptor in parent process
366 	 *     targetFd = Target descriptor for child process
367 	 */
368 	public void takeFd(int sourceFd, int targetFd)
369 	{
370 		g_subprocess_launcher_take_fd(gSubprocessLauncher, sourceFd, targetFd);
371 	}
372 
373 	/**
374 	 * Sets the file descriptor to use as the stderr for spawned processes.
375 	 *
376 	 * If @fd is -1 then any previously given fd is unset.
377 	 *
378 	 * Note that the default behaviour is to pass stderr through to the
379 	 * stderr of the parent process.
380 	 *
381 	 * The passed @fd belongs to the #GSubprocessLauncher.  It will be
382 	 * automatically closed when the launcher is finalized.  The file
383 	 * descriptor will also be closed on the child side when executing the
384 	 * spawned process.
385 	 *
386 	 * You may not set a stderr fd if a stderr file path is already set or
387 	 * if the launcher flags contain any flags directing stderr elsewhere.
388 	 *
389 	 * This feature is only available on UNIX.
390 	 *
391 	 * Params:
392 	 *     fd = a file descriptor, or -1
393 	 *
394 	 * Since: 2.40
395 	 */
396 	public void takeStderrFd(int fd)
397 	{
398 		g_subprocess_launcher_take_stderr_fd(gSubprocessLauncher, fd);
399 	}
400 
401 	/**
402 	 * Sets the file descriptor to use as the stdin for spawned processes.
403 	 *
404 	 * If @fd is -1 then any previously given fd is unset.
405 	 *
406 	 * Note that if your intention is to have the stdin of the calling
407 	 * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT
408 	 * is a better way to go about doing that.
409 	 *
410 	 * The passed @fd is noted but will not be touched in the current
411 	 * process.  It is therefore necessary that it be kept open by the
412 	 * caller until the subprocess is spawned.  The file descriptor will
413 	 * also not be explicitly closed on the child side, so it must be marked
414 	 * O_CLOEXEC if that's what you want.
415 	 *
416 	 * You may not set a stdin fd if a stdin file path is already set or if
417 	 * the launcher flags contain any flags directing stdin elsewhere.
418 	 *
419 	 * This feature is only available on UNIX.
420 	 *
421 	 * Params:
422 	 *     fd = a file descriptor, or -1
423 	 *
424 	 * Since: 2.40
425 	 */
426 	public void takeStdinFd(int fd)
427 	{
428 		g_subprocess_launcher_take_stdin_fd(gSubprocessLauncher, fd);
429 	}
430 
431 	/**
432 	 * Sets the file descriptor to use as the stdout for spawned processes.
433 	 *
434 	 * If @fd is -1 then any previously given fd is unset.
435 	 *
436 	 * Note that the default behaviour is to pass stdout through to the
437 	 * stdout of the parent process.
438 	 *
439 	 * The passed @fd is noted but will not be touched in the current
440 	 * process.  It is therefore necessary that it be kept open by the
441 	 * caller until the subprocess is spawned.  The file descriptor will
442 	 * also not be explicitly closed on the child side, so it must be marked
443 	 * O_CLOEXEC if that's what you want.
444 	 *
445 	 * You may not set a stdout fd if a stdout file path is already set or
446 	 * if the launcher flags contain any flags directing stdout elsewhere.
447 	 *
448 	 * This feature is only available on UNIX.
449 	 *
450 	 * Params:
451 	 *     fd = a file descriptor, or -1
452 	 *
453 	 * Since: 2.40
454 	 */
455 	public void takeStdoutFd(int fd)
456 	{
457 		g_subprocess_launcher_take_stdout_fd(gSubprocessLauncher, fd);
458 	}
459 
460 	/**
461 	 * Removes the environment variable @variable from the environment of
462 	 * processes launched from this launcher.
463 	 *
464 	 * On UNIX, the variable's name can be an arbitrary byte string not
465 	 * containing '='. On Windows, it should be in UTF-8.
466 	 *
467 	 * Params:
468 	 *     variable = the environment variable to unset,
469 	 *         must not contain '='
470 	 *
471 	 * Since: 2.40
472 	 */
473 	public void unsetenv(string variable)
474 	{
475 		g_subprocess_launcher_unsetenv(gSubprocessLauncher, Str.toStringz(variable));
476 	}
477 }