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