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