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 	 * Since: 2.40
264 	 */
265 	public void setStdinFilePath(string path)
266 	{
267 		g_subprocess_launcher_set_stdin_file_path(gSubprocessLauncher, Str.toStringz(path));
268 	}
269 
270 	/**
271 	 * Sets the file path to use as the stdout for spawned processes.
272 	 *
273 	 * If @path is %NULL then any previously given path is unset.
274 	 *
275 	 * The file will be created or truncated when the process is spawned, as
276 	 * would be the case if using '>' at the shell.
277 	 *
278 	 * You may not set a stdout file path if a stdout fd is already set or
279 	 * if the launcher flags contain any flags directing stdout elsewhere.
280 	 *
281 	 * This feature is only available on UNIX.
282 	 *
283 	 * Params:
284 	 *     path = a filename or %NULL
285 	 *
286 	 * Since: 2.40
287 	 */
288 	public void setStdoutFilePath(string path)
289 	{
290 		g_subprocess_launcher_set_stdout_file_path(gSubprocessLauncher, Str.toStringz(path));
291 	}
292 
293 	/**
294 	 * Sets the environment variable @variable in the environment of
295 	 * processes launched from this launcher.
296 	 *
297 	 * On UNIX, both the variable's name and value can be arbitrary byte
298 	 * strings, except that the variable's name cannot contain '='.
299 	 * On Windows, they should be in UTF-8.
300 	 *
301 	 * Params:
302 	 *     variable = the environment variable to set, must not contain '='
303 	 *     value = the new value for the variable
304 	 *     overwrite = whether to change the variable if it already exists
305 	 *
306 	 * Since: 2.40
307 	 */
308 	public void setenv(string variable, string value, bool overwrite)
309 	{
310 		g_subprocess_launcher_setenv(gSubprocessLauncher, Str.toStringz(variable), Str.toStringz(value), overwrite);
311 	}
312 
313 	/**
314 	 * Creates a #GSubprocess given a provided array of arguments.
315 	 *
316 	 * Params:
317 	 *     argv = Command line arguments
318 	 *
319 	 * Return: A new #GSubprocess, or %NULL on error (and @error will be set)
320 	 *
321 	 * Since: 2.40
322 	 *
323 	 * Throws: GException on failure.
324 	 */
325 	public Subprocess spawnv(string[] argv)
326 	{
327 		GError* err = null;
328 		
329 		auto p = g_subprocess_launcher_spawnv(gSubprocessLauncher, Str.toStringzArray(argv), &err);
330 		
331 		if (err !is null)
332 		{
333 			throw new GException( new ErrorG(err) );
334 		}
335 		
336 		if(p is null)
337 		{
338 			return null;
339 		}
340 		
341 		return ObjectG.getDObject!(Subprocess)(cast(GSubprocess*) p, true);
342 	}
343 
344 	/**
345 	 * Transfer an arbitrary file descriptor from parent process to the
346 	 * child.  This function takes "ownership" of the fd; it will be closed
347 	 * in the parent when @self is freed.
348 	 *
349 	 * By default, all file descriptors from the parent will be closed.
350 	 * This function allows you to create (for example) a custom pipe() or
351 	 * socketpair() before launching the process, and choose the target
352 	 * descriptor in the child.
353 	 *
354 	 * An example use case is GNUPG, which has a command line argument
355 	 * --passphrase-fd providing a file descriptor number where it expects
356 	 * the passphrase to be written.
357 	 *
358 	 * Params:
359 	 *     sourceFd = File descriptor in parent process
360 	 *     targetFd = Target descriptor for child process
361 	 */
362 	public void takeFd(int sourceFd, int targetFd)
363 	{
364 		g_subprocess_launcher_take_fd(gSubprocessLauncher, sourceFd, targetFd);
365 	}
366 
367 	/**
368 	 * Sets the file descriptor to use as the stderr for spawned processes.
369 	 *
370 	 * If @fd is -1 then any previously given fd is unset.
371 	 *
372 	 * Note that the default behaviour is to pass stderr through to the
373 	 * stderr of the parent process.
374 	 *
375 	 * The passed @fd belongs to the #GSubprocessLauncher.  It will be
376 	 * automatically closed when the launcher is finalized.  The file
377 	 * descriptor will also be closed on the child side when executing the
378 	 * spawned process.
379 	 *
380 	 * You may not set a stderr fd if a stderr file path is already set or
381 	 * if the launcher flags contain any flags directing stderr elsewhere.
382 	 *
383 	 * This feature is only available on UNIX.
384 	 *
385 	 * Params:
386 	 *     fd = a file descriptor, or -1
387 	 *
388 	 * Since: 2.40
389 	 */
390 	public void takeStderrFd(int fd)
391 	{
392 		g_subprocess_launcher_take_stderr_fd(gSubprocessLauncher, fd);
393 	}
394 
395 	/**
396 	 * Sets the file descriptor to use as the stdin for spawned processes.
397 	 *
398 	 * If @fd is -1 then any previously given fd is unset.
399 	 *
400 	 * Note that if your intention is to have the stdin of the calling
401 	 * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT
402 	 * is a better way to go about doing that.
403 	 *
404 	 * The passed @fd is noted but will not be touched in the current
405 	 * process.  It is therefore necessary that it be kept open by the
406 	 * caller until the subprocess is spawned.  The file descriptor will
407 	 * also not be explicitly closed on the child side, so it must be marked
408 	 * O_CLOEXEC if that's what you want.
409 	 *
410 	 * You may not set a stdin fd if a stdin file path is already set or if
411 	 * the launcher flags contain any flags directing stdin elsewhere.
412 	 *
413 	 * This feature is only available on UNIX.
414 	 *
415 	 * Params:
416 	 *     fd = a file descriptor, or -1
417 	 *
418 	 * Since: 2.40
419 	 */
420 	public void takeStdinFd(int fd)
421 	{
422 		g_subprocess_launcher_take_stdin_fd(gSubprocessLauncher, fd);
423 	}
424 
425 	/**
426 	 * Sets the file descriptor to use as the stdout for spawned processes.
427 	 *
428 	 * If @fd is -1 then any previously given fd is unset.
429 	 *
430 	 * Note that the default behaviour is to pass stdout through to the
431 	 * stdout of the parent process.
432 	 *
433 	 * The passed @fd is noted but will not be touched in the current
434 	 * process.  It is therefore necessary that it be kept open by the
435 	 * caller until the subprocess is spawned.  The file descriptor will
436 	 * also not be explicitly closed on the child side, so it must be marked
437 	 * O_CLOEXEC if that's what you want.
438 	 *
439 	 * You may not set a stdout fd if a stdout file path is already set or
440 	 * if the launcher flags contain any flags directing stdout elsewhere.
441 	 *
442 	 * This feature is only available on UNIX.
443 	 *
444 	 * Params:
445 	 *     fd = a file descriptor, or -1
446 	 *
447 	 * Since: 2.40
448 	 */
449 	public void takeStdoutFd(int fd)
450 	{
451 		g_subprocess_launcher_take_stdout_fd(gSubprocessLauncher, fd);
452 	}
453 
454 	/**
455 	 * Removes the environment variable @variable from the environment of
456 	 * processes launched from this launcher.
457 	 *
458 	 * On UNIX, the variable's name can be an arbitrary byte string not
459 	 * containing '='. On Windows, it should be in UTF-8.
460 	 *
461 	 * Params:
462 	 *     variable = the environment variable to unset, must not contain '='
463 	 *
464 	 * Since: 2.40
465 	 */
466 	public void unsetenv(string variable)
467 	{
468 		g_subprocess_launcher_unsetenv(gSubprocessLauncher, Str.toStringz(variable));
469 	}
470 }