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.File;
28 private import gio.FileIF;
29 private import gio.InputStream;
30 private import glib.Str;
31 private import glib.Variant;
32 private import glib.VariantDict;
33 private import gobject.ObjectG;
34 private import gtkc.gio;
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 	protected override void setStruct(GObject* obj)
214 	{
215 		gApplicationCommandLine = cast(GApplicationCommandLine*)obj;
216 		super.setStruct(obj);
217 	}
218 
219 	/**
220 	 * Sets our main struct and passes it to the parent class.
221 	 */
222 	public this (GApplicationCommandLine* gApplicationCommandLine, bool ownedRef = false)
223 	{
224 		this.gApplicationCommandLine = gApplicationCommandLine;
225 		super(cast(GObject*)gApplicationCommandLine, ownedRef);
226 	}
227 
228 
229 	/** */
230 	public static GType getType()
231 	{
232 		return g_application_command_line_get_type();
233 	}
234 
235 	/**
236 	 * Creates a #GFile corresponding to a filename that was given as part
237 	 * of the invocation of @cmdline.
238 	 *
239 	 * This differs from g_file_new_for_commandline_arg() in that it
240 	 * resolves relative pathnames using the current working directory of
241 	 * the invoking process rather than the local process.
242 	 *
243 	 * Params:
244 	 *     arg = an argument from @cmdline
245 	 *
246 	 * Returns: a new #GFile
247 	 *
248 	 * Since: 2.36
249 	 */
250 	public FileIF createFileForArg(string arg)
251 	{
252 		auto p = g_application_command_line_create_file_for_arg(gApplicationCommandLine, Str.toStringz(arg));
253 		
254 		if(p is null)
255 		{
256 			return null;
257 		}
258 		
259 		return ObjectG.getDObject!(File, FileIF)(cast(GFile*) p, true);
260 	}
261 
262 	/**
263 	 * Gets the list of arguments that was passed on the command line.
264 	 *
265 	 * The strings in the array may contain non-UTF-8 data on UNIX (such as
266 	 * filenames or arguments given in the system locale) but are always in
267 	 * UTF-8 on Windows.
268 	 *
269 	 * If you wish to use the return value with #GOptionContext, you must
270 	 * use g_option_context_parse_strv().
271 	 *
272 	 * The return value is %NULL-terminated and should be freed using
273 	 * g_strfreev().
274 	 *
275 	 * Returns: the string array
276 	 *     containing the arguments (the argv)
277 	 *
278 	 * Since: 2.28
279 	 */
280 	public string[] getArguments()
281 	{
282 		int argc;
283 		
284 		auto retStr = g_application_command_line_get_arguments(gApplicationCommandLine, &argc);
285 		
286 		scope(exit) Str.freeStringArray(retStr);
287 		return Str.toStringArray(retStr, argc);
288 	}
289 
290 	/**
291 	 * Gets the working directory of the command line invocation.
292 	 * The string may contain non-utf8 data.
293 	 *
294 	 * It is possible that the remote application did not send a working
295 	 * directory, so this may be %NULL.
296 	 *
297 	 * The return value should not be modified or freed and is valid for as
298 	 * long as @cmdline exists.
299 	 *
300 	 * Returns: the current directory, or %NULL
301 	 *
302 	 * Since: 2.28
303 	 */
304 	public string getCwd()
305 	{
306 		return Str.toString(g_application_command_line_get_cwd(gApplicationCommandLine));
307 	}
308 
309 	/**
310 	 * Gets the contents of the 'environ' variable of the command line
311 	 * invocation, as would be returned by g_get_environ(), ie as a
312 	 * %NULL-terminated list of strings in the form 'NAME=VALUE'.
313 	 * The strings may contain non-utf8 data.
314 	 *
315 	 * The remote application usually does not send an environment.  Use
316 	 * %G_APPLICATION_SEND_ENVIRONMENT to affect that.  Even with this flag
317 	 * set it is possible that the environment is still not available (due
318 	 * to invocation messages from other applications).
319 	 *
320 	 * The return value should not be modified or freed and is valid for as
321 	 * long as @cmdline exists.
322 	 *
323 	 * See g_application_command_line_getenv() if you are only interested
324 	 * in the value of a single environment variable.
325 	 *
326 	 * Returns: the environment
327 	 *     strings, or %NULL if they were not sent
328 	 *
329 	 * Since: 2.28
330 	 */
331 	public string[] getEnviron()
332 	{
333 		return Str.toStringArray(g_application_command_line_get_environ(gApplicationCommandLine));
334 	}
335 
336 	/**
337 	 * Gets the exit status of @cmdline.  See
338 	 * g_application_command_line_set_exit_status() for more information.
339 	 *
340 	 * Returns: the exit status
341 	 *
342 	 * Since: 2.28
343 	 */
344 	public int getExitStatus()
345 	{
346 		return g_application_command_line_get_exit_status(gApplicationCommandLine);
347 	}
348 
349 	/**
350 	 * Determines if @cmdline represents a remote invocation.
351 	 *
352 	 * Returns: %TRUE if the invocation was remote
353 	 *
354 	 * Since: 2.28
355 	 */
356 	public bool getIsRemote()
357 	{
358 		return g_application_command_line_get_is_remote(gApplicationCommandLine) != 0;
359 	}
360 
361 	/**
362 	 * Gets the options there were passed to g_application_command_line().
363 	 *
364 	 * If you did not override local_command_line() then these are the same
365 	 * options that were parsed according to the #GOptionEntrys added to the
366 	 * application with g_application_add_main_option_entries() and possibly
367 	 * modified from your GApplication::handle-local-options handler.
368 	 *
369 	 * If no options were sent then an empty dictionary is returned so that
370 	 * you don't need to check for %NULL.
371 	 *
372 	 * Returns: a #GVariantDict with the options
373 	 *
374 	 * Since: 2.40
375 	 */
376 	public VariantDict getOptionsDict()
377 	{
378 		auto p = g_application_command_line_get_options_dict(gApplicationCommandLine);
379 		
380 		if(p is null)
381 		{
382 			return null;
383 		}
384 		
385 		return new VariantDict(cast(GVariantDict*) p);
386 	}
387 
388 	/**
389 	 * Gets the platform data associated with the invocation of @cmdline.
390 	 *
391 	 * This is a #GVariant dictionary containing information about the
392 	 * context in which the invocation occurred.  It typically contains
393 	 * information like the current working directory and the startup
394 	 * notification ID.
395 	 *
396 	 * For local invocation, it will be %NULL.
397 	 *
398 	 * Returns: the platform data, or %NULL
399 	 *
400 	 * Since: 2.28
401 	 */
402 	public Variant getPlatformData()
403 	{
404 		auto p = g_application_command_line_get_platform_data(gApplicationCommandLine);
405 		
406 		if(p is null)
407 		{
408 			return null;
409 		}
410 		
411 		return new Variant(cast(GVariant*) p, true);
412 	}
413 
414 	/**
415 	 * Gets the stdin of the invoking process.
416 	 *
417 	 * The #GInputStream can be used to read data passed to the standard
418 	 * input of the invoking process.
419 	 * This doesn't work on all platforms.  Presently, it is only available
420 	 * on UNIX when using a DBus daemon capable of passing file descriptors.
421 	 * If stdin is not available then %NULL will be returned.  In the
422 	 * future, support may be expanded to other platforms.
423 	 *
424 	 * You must only call this function once per commandline invocation.
425 	 *
426 	 * Returns: a #GInputStream for stdin
427 	 *
428 	 * Since: 2.34
429 	 */
430 	public InputStream getStdin()
431 	{
432 		auto p = g_application_command_line_get_stdin(gApplicationCommandLine);
433 		
434 		if(p is null)
435 		{
436 			return null;
437 		}
438 		
439 		return ObjectG.getDObject!(InputStream)(cast(GInputStream*) p, true);
440 	}
441 
442 	/**
443 	 * Gets the value of a particular environment variable of the command
444 	 * line invocation, as would be returned by g_getenv().  The strings may
445 	 * contain non-utf8 data.
446 	 *
447 	 * The remote application usually does not send an environment.  Use
448 	 * %G_APPLICATION_SEND_ENVIRONMENT to affect that.  Even with this flag
449 	 * set it is possible that the environment is still not available (due
450 	 * to invocation messages from other applications).
451 	 *
452 	 * The return value should not be modified or freed and is valid for as
453 	 * long as @cmdline exists.
454 	 *
455 	 * Params:
456 	 *     name = the environment variable to get
457 	 *
458 	 * Returns: the value of the variable, or %NULL if unset or unsent
459 	 *
460 	 * Since: 2.28
461 	 */
462 	public string getenv(string name)
463 	{
464 		return Str.toString(g_application_command_line_getenv(gApplicationCommandLine, Str.toStringz(name)));
465 	}
466 
467 	/**
468 	 * Sets the exit status that will be used when the invoking process
469 	 * exits.
470 	 *
471 	 * The return value of the #GApplication::command-line signal is
472 	 * passed to this function when the handler returns.  This is the usual
473 	 * way of setting the exit status.
474 	 *
475 	 * In the event that you want the remote invocation to continue running
476 	 * and want to decide on the exit status in the future, you can use this
477 	 * call.  For the case of a remote invocation, the remote process will
478 	 * typically exit when the last reference is dropped on @cmdline.  The
479 	 * exit status of the remote process will be equal to the last value
480 	 * that was set with this function.
481 	 *
482 	 * In the case that the commandline invocation is local, the situation
483 	 * is slightly more complicated.  If the commandline invocation results
484 	 * in the mainloop running (ie: because the use-count of the application
485 	 * increased to a non-zero value) then the application is considered to
486 	 * have been 'successful' in a certain sense, and the exit status is
487 	 * always zero.  If the application use count is zero, though, the exit
488 	 * status of the local #GApplicationCommandLine is used.
489 	 *
490 	 * Params:
491 	 *     exitStatus = the exit status
492 	 *
493 	 * Since: 2.28
494 	 */
495 	public void setExitStatus(int exitStatus)
496 	{
497 		g_application_command_line_set_exit_status(gApplicationCommandLine, exitStatus);
498 	}
499 }