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