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

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

Initial release

File size: 14.9 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.ApplicationCommandLine;
22
23private import gi.gio;
24public  import gi.giotypes;
25private import gio.File;
26private import gio.FileIF;
27private import gio.InputStream;
28private import glib.Str;
29private import glib.Variant;
30private import glib.VariantDict;
31private import gobject.ObjectG;
32
33
34/**
35 * #GApplicationCommandLine represents a command-line invocation of
36 * an application.  It is created by #GApplication and emitted
37 * in the #GApplication::command-line signal and virtual function.
38 *
39 * The class contains the list of arguments that the program was invoked
40 * with.  It is also possible to query if the commandline invocation was
41 * local (ie: the current process is running in direct response to the
42 * invocation) or remote (ie: some other process forwarded the
43 * commandline to this process).
44 *
45 * The GApplicationCommandLine object can provide the @argc and @argv
46 * parameters for use with the #GOptionContext command-line parsing API,
47 * with the g_application_command_line_get_arguments() function. See
48 * [gapplication-example-cmdline3.c][gapplication-example-cmdline3]
49 * for an example.
50 *
51 * The exit status of the originally-invoked process may be set and
52 * messages can be printed to stdout or stderr of that process.  The
53 * lifecycle of the originally-invoked process is tied to the lifecycle
54 * of this object (ie: the process exits when the last reference is
55 * dropped).
56 *
57 * The main use for #GApplicationCommandLine (and the
58 * #GApplication::command-line signal) is 'Emacs server' like use cases:
59 * You can set the `EDITOR` environment variable to have e.g. git use
60 * your favourite editor to edit commit messages, and if you already
61 * have an instance of the editor running, the editing will happen
62 * in the running instance, instead of opening a new one. An important
63 * aspect of this use case is that the process that gets started by git
64 * does not return until the editing is done.
65 *
66 * Normally, the commandline is completely handled in the
67 * #GApplication::command-line handler. The launching instance exits
68 * once the signal handler in the primary instance has returned, and
69 * the return value of the signal handler becomes the exit status
70 * of the launching instance.
71 * |[<!-- language="C" -->
72 * static int
73 * command_line (GApplication            *application,
74 * GApplicationCommandLine *cmdline)
75 * {
76 * gchar **argv;
77 * gint argc;
78 * gint i;
79 *
80 * argv = g_application_command_line_get_arguments (cmdline, &argc);
81 *
82 * g_application_command_line_print (cmdline,
83 * "This text is written back\n"
84 * "to stdout of the caller\n");
85 *
86 * for (i = 0; i < argc; i++)
87 * g_print ("argument %d: %s\n", i, argv[i]);
88 *
89 * g_strfreev (argv);
90 *
91 * return 0;
92 * }
93 * ]|
94 * The complete example can be found here:
95 * [gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c)
96 *
97 * In more complicated cases, the handling of the comandline can be
98 * split between the launcher and the primary instance.
99 * |[<!-- language="C" -->
100 * static gboolean
101 * test_local_cmdline (GApplication   *application,
102 * gchar        ***arguments,
103 * gint           *exit_status)
104 * {
105 * gint i, j;
106 * gchar **argv;
107 *
108 * argv = *arguments;
109 *
110 * i = 1;
111 * while (argv[i])
112 * {
113 * if (g_str_has_prefix (argv[i], "--local-"))
114 * {
115 * g_print ("handling argument %s locally\n", argv[i]);
116 * g_free (argv[i]);
117 * for (j = i; argv[j]; j++)
118 * argv[j] = argv[j + 1];
119 * }
120 * else
121 * {
122 * g_print ("not handling argument %s locally\n", argv[i]);
123 * i++;
124 * }
125 * }
126 *
127 * *exit_status = 0;
128 *
129 * return FALSE;
130 * }
131 *
132 * static void
133 * test_application_class_init (TestApplicationClass *class)
134 * {
135 * G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
136 *
137 * ...
138 * }
139 * ]|
140 * In this example of split commandline handling, options that start
141 * with `--local-` are handled locally, all other options are passed
142 * to the #GApplication::command-line handler which runs in the primary
143 * instance.
144 *
145 * The complete example can be found here:
146 * [gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c)
147 *
148 * If handling the commandline requires a lot of work, it may
149 * be better to defer it.
150 * |[<!-- language="C" -->
151 * static gboolean
152 * my_cmdline_handler (gpointer data)
153 * {
154 * GApplicationCommandLine *cmdline = data;
155 *
156 * // do the heavy lifting in an idle
157 *
158 * g_application_command_line_set_exit_status (cmdline, 0);
159 * g_object_unref (cmdline); // this releases the application
160 *
161 * return G_SOURCE_REMOVE;
162 * }
163 *
164 * static int
165 * command_line (GApplication            *application,
166 * GApplicationCommandLine *cmdline)
167 * {
168 * // keep the application running until we are done with this commandline
169 * g_application_hold (application);
170 *
171 * g_object_set_data_full (G_OBJECT (cmdline),
172 * "application", application,
173 * (GDestroyNotify)g_application_release);
174 *
175 * g_object_ref (cmdline);
176 * g_idle_add (my_cmdline_handler, cmdline);
177 *
178 * return 0;
179 * }
180 * ]|
181 * In this example the commandline is not completely handled before
182 * the #GApplication::command-line handler returns. Instead, we keep
183 * a reference to the #GApplicationCommandLine object and handle it
184 * later (in this example, in an idle). Note that it is necessary to
185 * hold the application until you are done with the commandline.
186 *
187 * The complete example can be found here:
188 * [gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c)
189 */
190public class ApplicationCommandLine : ObjectG
191{
192        /** the main Gtk struct */
193        protected GApplicationCommandLine* gApplicationCommandLine;
194
195        /** Get the main Gtk struct */
196        public GApplicationCommandLine* getApplicationCommandLineStruct()
197        {
198                return gApplicationCommandLine;
199        }
200
201        /** the main Gtk struct as a void* */
202        protected override void* getStruct()
203        {
204                return cast(void*)gApplicationCommandLine;
205        }
206
207        protected override void setStruct(GObject* obj)
208        {
209                gApplicationCommandLine = cast(GApplicationCommandLine*)obj;
210                super.setStruct(obj);
211        }
212
213        /**
214         * Sets our main struct and passes it to the parent class.
215         */
216        public this (GApplicationCommandLine* gApplicationCommandLine, bool ownedRef = false)
217        {
218                this.gApplicationCommandLine = gApplicationCommandLine;
219                super(cast(GObject*)gApplicationCommandLine, ownedRef);
220        }
221
222
223        /** */
224        public static GType getType()
225        {
226                return g_application_command_line_get_type();
227        }
228
229        /**
230         * Creates a #GFile corresponding to a filename that was given as part
231         * of the invocation of @cmdline.
232         *
233         * This differs from g_file_new_for_commandline_arg() in that it
234         * resolves relative pathnames using the current working directory of
235         * the invoking process rather than the local process.
236         *
237         * Params:
238         *     arg = an argument from @cmdline
239         *
240         * Returns: a new #GFile
241         *
242         * Since: 2.36
243         */
244        public FileIF createFileForArg(string arg)
245        {
246                auto p = g_application_command_line_create_file_for_arg(gApplicationCommandLine, Str.toStringz(arg));
247               
248                if(p is null)
249                {
250                        return null;
251                }
252               
253                return ObjectG.getDObject!(File, FileIF)(cast(GFile*) p, true);
254        }
255
256        /**
257         * Gets the list of arguments that was passed on the command line.
258         *
259         * The strings in the array may contain non-UTF-8 data on UNIX (such as
260         * filenames or arguments given in the system locale) but are always in
261         * UTF-8 on Windows.
262         *
263         * If you wish to use the return value with #GOptionContext, you must
264         * use g_option_context_parse_strv().
265         *
266         * The return value is %NULL-terminated and should be freed using
267         * g_strfreev().
268         *
269         * Returns: the string array
270         *     containing the arguments (the argv)
271         *
272         * Since: 2.28
273         */
274        public string[] getArguments()
275        {
276                int argc;
277               
278                auto retStr = g_application_command_line_get_arguments(gApplicationCommandLine, &argc);
279               
280                scope(exit) Str.freeStringArray(retStr);
281                return Str.toStringArray(retStr, argc);
282        }
283
284        /**
285         * Gets the working directory of the command line invocation.
286         * The string may contain non-utf8 data.
287         *
288         * It is possible that the remote application did not send a working
289         * directory, so this may be %NULL.
290         *
291         * The return value should not be modified or freed and is valid for as
292         * long as @cmdline exists.
293         *
294         * Returns: the current directory, or %NULL
295         *
296         * Since: 2.28
297         */
298        public string getCwd()
299        {
300                return Str.toString(g_application_command_line_get_cwd(gApplicationCommandLine));
301        }
302
303        /**
304         * Gets the contents of the 'environ' variable of the command line
305         * invocation, as would be returned by g_get_environ(), ie as a
306         * %NULL-terminated list of strings in the form 'NAME=VALUE'.
307         * The strings may contain non-utf8 data.
308         *
309         * The remote application usually does not send an environment.  Use
310         * %G_APPLICATION_SEND_ENVIRONMENT to affect that.  Even with this flag
311         * set it is possible that the environment is still not available (due
312         * to invocation messages from other applications).
313         *
314         * The return value should not be modified or freed and is valid for as
315         * long as @cmdline exists.
316         *
317         * See g_application_command_line_getenv() if you are only interested
318         * in the value of a single environment variable.
319         *
320         * Returns: the environment
321         *     strings, or %NULL if they were not sent
322         *
323         * Since: 2.28
324         */
325        public string[] getEnviron()
326        {
327                return Str.toStringArray(g_application_command_line_get_environ(gApplicationCommandLine));
328        }
329
330        /**
331         * Gets the exit status of @cmdline.  See
332         * g_application_command_line_set_exit_status() for more information.
333         *
334         * Returns: the exit status
335         *
336         * Since: 2.28
337         */
338        public int getExitStatus()
339        {
340                return g_application_command_line_get_exit_status(gApplicationCommandLine);
341        }
342
343        /**
344         * Determines if @cmdline represents a remote invocation.
345         *
346         * Returns: %TRUE if the invocation was remote
347         *
348         * Since: 2.28
349         */
350        public bool getIsRemote()
351        {
352                return g_application_command_line_get_is_remote(gApplicationCommandLine) != 0;
353        }
354
355        /**
356         * Gets the options there were passed to g_application_command_line().
357         *
358         * If you did not override local_command_line() then these are the same
359         * options that were parsed according to the #GOptionEntrys added to the
360         * application with g_application_add_main_option_entries() and possibly
361         * modified from your GApplication::handle-local-options handler.
362         *
363         * If no options were sent then an empty dictionary is returned so that
364         * you don't need to check for %NULL.
365         *
366         * Returns: a #GVariantDict with the options
367         *
368         * Since: 2.40
369         */
370        public VariantDict getOptionsDict()
371        {
372                auto p = g_application_command_line_get_options_dict(gApplicationCommandLine);
373               
374                if(p is null)
375                {
376                        return null;
377                }
378               
379                return new VariantDict(cast(GVariantDict*) p);
380        }
381
382        /**
383         * Gets the platform data associated with the invocation of @cmdline.
384         *
385         * This is a #GVariant dictionary containing information about the
386         * context in which the invocation occurred.  It typically contains
387         * information like the current working directory and the startup
388         * notification ID.
389         *
390         * For local invocation, it will be %NULL.
391         *
392         * Returns: the platform data, or %NULL
393         *
394         * Since: 2.28
395         */
396        public Variant getPlatformData()
397        {
398                auto p = g_application_command_line_get_platform_data(gApplicationCommandLine);
399               
400                if(p is null)
401                {
402                        return null;
403                }
404               
405                return new Variant(cast(GVariant*) p, true);
406        }
407
408        /**
409         * Gets the stdin of the invoking process.
410         *
411         * The #GInputStream can be used to read data passed to the standard
412         * input of the invoking process.
413         * This doesn't work on all platforms.  Presently, it is only available
414         * on UNIX when using a DBus daemon capable of passing file descriptors.
415         * If stdin is not available then %NULL will be returned.  In the
416         * future, support may be expanded to other platforms.
417         *
418         * You must only call this function once per commandline invocation.
419         *
420         * Returns: a #GInputStream for stdin
421         *
422         * Since: 2.34
423         */
424        public InputStream getStdin()
425        {
426                auto p = g_application_command_line_get_stdin(gApplicationCommandLine);
427               
428                if(p is null)
429                {
430                        return null;
431                }
432               
433                return ObjectG.getDObject!(InputStream)(cast(GInputStream*) p, true);
434        }
435
436        /**
437         * Gets the value of a particular environment variable of the command
438         * line invocation, as would be returned by g_getenv().  The strings may
439         * contain non-utf8 data.
440         *
441         * The remote application usually does not send an environment.  Use
442         * %G_APPLICATION_SEND_ENVIRONMENT to affect that.  Even with this flag
443         * set it is possible that the environment is still not available (due
444         * to invocation messages from other applications).
445         *
446         * The return value should not be modified or freed and is valid for as
447         * long as @cmdline exists.
448         *
449         * Params:
450         *     name = the environment variable to get
451         *
452         * Returns: the value of the variable, or %NULL if unset or unsent
453         *
454         * Since: 2.28
455         */
456        public string getenv(string name)
457        {
458                return Str.toString(g_application_command_line_getenv(gApplicationCommandLine, Str.toStringz(name)));
459        }
460
461        /**
462         * Sets the exit status that will be used when the invoking process
463         * exits.
464         *
465         * The return value of the #GApplication::command-line signal is
466         * passed to this function when the handler returns.  This is the usual
467         * way of setting the exit status.
468         *
469         * In the event that you want the remote invocation to continue running
470         * and want to decide on the exit status in the future, you can use this
471         * call.  For the case of a remote invocation, the remote process will
472         * typically exit when the last reference is dropped on @cmdline.  The
473         * exit status of the remote process will be equal to the last value
474         * that was set with this function.
475         *
476         * In the case that the commandline invocation is local, the situation
477         * is slightly more complicated.  If the commandline invocation results
478         * in the mainloop running (ie: because the use-count of the application
479         * increased to a non-zero value) then the application is considered to
480         * have been 'successful' in a certain sense, and the exit status is
481         * always zero.  If the application use count is zero, though, the exit
482         * status of the local #GApplicationCommandLine is used.
483         *
484         * Params:
485         *     exitStatus = the exit status
486         *
487         * Since: 2.28
488         */
489        public void setExitStatus(int exitStatus)
490        {
491                g_application_command_line_set_exit_status(gApplicationCommandLine, exitStatus);
492        }
493}
Note: See TracBrowser for help on using the repository browser.