source: appstream-generator/build/girepo/gio/SubprocessLauncher.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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