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