gio/gapplication.c

   1 /*
   2  * Copyright © 2010 Codethink Limited
   3  *
   4  * This program is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published
   6  * by the Free Software Foundation; either version 2 of the licence or (at
   7  * your option) any later version.
   8  *
   9  * This library 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 GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General
  15  * Public License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  *
  19  * Authors: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 /* Prologue {{{1 */
  23 #include "config.h"
  24
  25 #include "gapplication.h"
  26
  27 #include "gapplicationcommandline.h"
  28 #include "gapplicationimpl.h"
  29 #include "gactiongroup.h"
  30
  31 #include "gioenumtypes.h"
  32 #include "gio-marshal.h"
  33 #include "gioenums.h"
  34 #include "gfile.h"
  35
  36 #include "glibintl.h"
  37
  38 #include <string.h>
  39
  40 /**
  41  * SECTION: gapplication
  42  * @title: GApplication
  43  * @short_description: Core application class
  44  *
  45  * A #GApplication is the foundation of an application, unique for a
  46  * given application identifier.  The GApplication class wraps some
  47  * low-level platform-specific services and is intended to act as the
  48  * foundation for higher-level application classes such as
  49  * #GtkApplication or #MxApplication.  In general, you should not use
  50  * this class outside of a higher level framework.
  51  *
  52  * One of the core features that GApplication provides is process
  53  * uniqueness, in the context of a "session".  The session concept is
  54  * platform-dependent, but corresponds roughly to a graphical desktop
  55  * login.  When your application is launched again, its arguments
  56  * are passed through platform communication to the already running
  57  * program. The already running instance of the program is called the
  58  * <firstterm>primary instance</firstterm>.
  59  *
  60  * Before using GApplication, you must choose an "application identifier".
  61  * The expected form of an application identifier is very close to that of
  62  * of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>.
  63  * Examples include: "com.example.MyApp" "org.example.internal-apps.Calculator"
  64  * For convenience, the restrictions on application identifiers are reproduced
  65  * here:
  66  * <itemizedlist>
  67  *   <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit.</listitem>
  68  *   <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least two elements).</listitem>
  69  *   <listitem>Application identifiers must not begin with a '.' (period) character.</listitem>
  70  *   <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
  71  *   <listitem>Application identifiers must not exceed 255 characters.</listitem>
  72  * </itemizedlist>
  73  */
  74
  75 struct _GApplicationPrivate
  76 {
  77   GApplicationFlags  flags;
  78   gchar             *id;
  79
  80   GActionGroup      *actions;
  81   GMainLoop         *mainloop;
  82
  83   guint              inactivity_timeout_id;
  84   guint              inactivity_timeout;
  85   guint              use_count;
  86
  87   guint              is_registered : 1;
  88   guint              is_remote : 1;
  89
  90   GApplicationImpl  *impl;
  91 };
  92
  93 enum
  94 {
  95   PROP_NONE,
  96   PROP_APPLICATION_ID,
  97   PROP_FLAGS,
  98   PROP_IS_REGISTERED,
  99   PROP_IS_REMOTE,
 100   PROP_INACTIVITY_TIMEOUT,
 101   PROP_ACTION_GROUP
 102 };
 103
 104 enum
 105 {
 106   SIGNAL_STARTUP,
 107   SIGNAL_ACTIVATE,
 108   SIGNAL_OPEN,
 109   SIGNAL_ACTION,
 110   SIGNAL_COMMAND_LINE,
 111   NR_SIGNALS
 112 };
 113
 114 static guint g_application_signals[NR_SIGNALS];
 115
 116 static void g_application_action_group_iface_init (GActionGroupInterface *);
 117 G_DEFINE_TYPE_WITH_CODE (GApplication, g_application, G_TYPE_OBJECT,
 118  G_IMPLEMENT_INTERFACE (G_TYPE_ACTION_GROUP,
 119    g_application_action_group_iface_init))
 120
 121 /* vfunc defaults {{{1 */
 122 static void
 123 g_application_real_before_emit (GApplication *application,
 124                                 GVariant     *platform_data)
 125 {
 126 }
 127
 128 static void
 129 g_application_real_after_emit (GApplication *application,
 130                                GVariant     *platform_data)
 131 {
 132 }
 133
 134 static void
 135 g_application_real_startup (GApplication *application)
 136 {
 137 }
 138
 139 static void
 140 g_application_real_activate (GApplication *application)
 141 {
 142   if (!g_signal_has_handler_pending (application,
 143                                      g_application_signals[SIGNAL_ACTIVATE],
 144                                      0, TRUE))
 145     {
 146       static gboolean warned;
 147
 148       if (warned)
 149         return;
 150
 151       g_warning ("Your application does not implement "
 152                  "g_application_activate() and has no handlers connected "
 153                  "to the 'activate' signal.  It should do one of these.");
 154       warned = TRUE;
 155     }
 156 }
 157
 158 static void
 159 g_application_real_open (GApplication  *application,
 160                          GFile        **files,
 161                          gint           n_files,
 162                          const gchar   *hint)
 163 {
 164   if (!g_signal_has_handler_pending (application,
 165                                      g_application_signals[SIGNAL_OPEN],
 166                                      0, TRUE))
 167     {
 168       static gboolean warned;
 169
 170       if (warned)
 171         return;
 172
 173       g_warning ("Your application claims to support opening files "
 174                  "but does not implement g_application_open() and has no "
 175                  "handlers connected to the 'open' signal.");
 176       warned = TRUE;
 177     }
 178 }
 179
 180 static int
 181 g_application_real_command_line (GApplication            *application,
 182                                  GApplicationCommandLine *cmdline)
 183 {
 184   static gboolean warned;
 185
 186   if (warned)
 187     return 1;
 188
 189   g_warning ("Your application claims to support custom command line "
 190              "handling but does not implement g_application_command_line() "
 191              "and has no handlers connected to the 'command-line' signal.");
 192
 193   warned = TRUE;
 194
 195   return 1;
 196 }
 197
 198 static gboolean
 199 g_application_real_local_command_line (GApplication   *application,
 200                                        gchar        ***arguments,
 201                                        int            *exit_status)
 202 {
 203   if (application->priv->flags & G_APPLICATION_HANDLES_COMMAND_LINE)
 204     return FALSE;
 205
 206   else
 207     {
 208       GError *error = NULL;
 209       gint n_args;
 210
 211       if (!g_application_register (application, NULL, &error))
 212         {
 213           g_critical ("%s", error->message);
 214           g_error_free (error);
 215           *exit_status = 1;
 216           return TRUE;
 217         }
 218
 219       n_args = g_strv_length (*arguments);
 220
 221       if (application->priv->flags & G_APPLICATION_IS_SERVICE)
 222         {
 223           if (n_args > 1)
 224             {
 225               g_printerr ("GApplication service mode takes no arguments.\n");
 226               application->priv->flags &= ~G_APPLICATION_IS_SERVICE;
 227             }
 228
 229           return TRUE;
 230         }
 231
 232       if (n_args <= 1)
 233         {
 234           g_application_activate (application);
 235           *exit_status = 0;
 236         }
 237
 238       else
 239         {
 240           if (~application->priv->flags & G_APPLICATION_HANDLES_OPEN)
 241             {
 242               g_critical ("This application can not open files.");
 243               *exit_status = 1;
 244             }
 245           else
 246             {
 247               GFile **files;
 248               gint n_files;
 249               gint i;
 250
 251               n_files = n_args - 1;
 252               files = g_new (GFile *, n_files);
 253
 254               for (i = 0; i < n_files; i++)
 255                 files[i] = g_file_new_for_commandline_arg ((*arguments)[i + 1]);
 256
 257               g_application_open (application, files, n_files, "");
 258
 259               for (i = 0; i < n_files; i++)
 260                 g_object_unref (files[i]);
 261               g_free (files);
 262
 263               *exit_status = 0;
 264             }
 265         }
 266
 267       return TRUE;
 268     }
 269 }
 270
 271 static void
 272 g_application_real_add_platform_data (GApplication    *application,
 273                                       GVariantBuilder *builder)
 274 {
 275 }
 276
 277 static void
 278 g_application_real_quit_mainloop (GApplication *application)
 279 {
 280   if (application->priv->mainloop != NULL)
 281     g_main_loop_quit (application->priv->mainloop);
 282 }
 283
 284 static void
 285 g_application_real_run_mainloop (GApplication *application)
 286 {
 287   if (application->priv->mainloop == NULL)
 288     application->priv->mainloop = g_main_loop_new (NULL, FALSE);
 289
 290   g_main_loop_run (application->priv->mainloop);
 291 }
 292
 293 /* GObject implementation stuff {{{1 */
 294 static void
 295 g_application_set_property (GObject      *object,
 296                             guint         prop_id,
 297                             const GValue *value,
 298                             GParamSpec   *pspec)
 299 {
 300   GApplication *application = G_APPLICATION (object);
 301
 302   switch (prop_id)
 303     {
 304     case PROP_APPLICATION_ID:
 305       g_application_set_application_id (application,
 306                                         g_value_get_string (value));
 307       break;
 308
 309     case PROP_FLAGS:
 310       g_application_set_flags (application, g_value_get_flags (value));
 311       break;
 312
 313     case PROP_INACTIVITY_TIMEOUT:
 314       g_application_set_inactivity_timeout (application,
 315                                             g_value_get_uint (value));
 316       break;
 317
 318     case PROP_ACTION_GROUP:
 319       g_application_set_action_group (application,
 320                                       g_value_get_object (value));
 321       break;
 322
 323     default:
 324       g_assert_not_reached ();
 325     }
 326 }
 327
 328 /**
 329  * g_application_set_action_group:
 330  * @application: a #GApplication
 331  * @action_group: a #GActionGroup, or %NULL
 332  *
 333  * Sets or unsets the group of actions associated with the application.
 334  *
 335  * These actions are the actions that can be remotely invoked.
 336  *
 337  * It is an error to call this function after the application has been
 338  * registered.
 339  *
 340  * Since: 2.28
 341  **/
 342 void
 343 g_application_set_action_group (GApplication *application,
 344                                 GActionGroup *action_group)
 345 {
 346   g_return_if_fail (G_IS_APPLICATION (application));
 347   g_return_if_fail (application->priv->is_registered);
 348
 349   if (application->priv->actions != NULL)
 350     g_object_unref (application->priv->actions);
 351
 352   application->priv->actions = action_group;
 353
 354   if (application->priv->actions != NULL)
 355     g_object_ref (application->priv->actions);
 356 }
 357
 358 static void
 359 g_application_get_property (GObject    *object,
 360                             guint       prop_id,
 361                             GValue     *value,
 362                             GParamSpec *pspec)
 363 {
 364   GApplication *application = G_APPLICATION (object);
 365
 366   switch (prop_id)
 367     {
 368     case PROP_APPLICATION_ID:
 369       g_value_set_string (value,
 370                           g_application_get_application_id (application));
 371       break;
 372
 373     case PROP_FLAGS:
 374       g_value_set_flags (value,
 375                          g_application_get_flags (application));
 376       break;
 377
 378     case PROP_IS_REGISTERED:
 379       g_value_set_boolean (value,
 380                            g_application_get_is_registered (application));
 381       break;
 382
 383     case PROP_IS_REMOTE:
 384       g_value_set_boolean (value,
 385                            g_application_get_is_remote (application));
 386       break;
 387
 388     case PROP_INACTIVITY_TIMEOUT:
 389       g_value_set_uint (value,
 390                         g_application_get_inactivity_timeout (application));
 391       break;
 392
 393     default:
 394       g_assert_not_reached ();
 395     }
 396 }
 397
 398 static void
 399 g_application_constructed (GObject *object)
 400 {
 401   GApplication *application = G_APPLICATION (object);
 402
 403   g_assert (application->priv->id != NULL);
 404 }
 405
 406 static void
 407 g_application_finalize (GObject *object)
 408 {
 409   GApplication *application = G_APPLICATION (object);
 410
 411   if (application->priv->impl)
 412     g_application_impl_destroy (application->priv->impl);
 413   g_free (application->priv->id);
 414
 415   if (application->priv->mainloop)
 416     g_main_loop_unref (application->priv->mainloop);
 417
 418   G_OBJECT_CLASS (g_application_parent_class)
 419     ->finalize (object);
 420 }
 421
 422 static void
 423 g_application_init (GApplication *application)
 424 {
 425   application->priv = G_TYPE_INSTANCE_GET_PRIVATE (application,
 426                                                    G_TYPE_APPLICATION,
 427                                                    GApplicationPrivate);
 428 }
 429
 430 static void
 431 g_application_class_init (GApplicationClass *class)
 432 {
 433   GObjectClass *object_class = G_OBJECT_CLASS (class);
 434
 435   object_class->constructed = g_application_constructed;
 436   object_class->finalize = g_application_finalize;
 437   object_class->get_property = g_application_get_property;
 438   object_class->set_property = g_application_set_property;
 439
 440   class->before_emit = g_application_real_before_emit;
 441   class->after_emit = g_application_real_after_emit;
 442   class->startup = g_application_real_startup;
 443   class->activate = g_application_real_activate;
 444   class->open = g_application_real_open;
 445   class->command_line = g_application_real_command_line;
 446   class->local_command_line = g_application_real_local_command_line;
 447   class->add_platform_data = g_application_real_add_platform_data;
 448   class->quit_mainloop = g_application_real_quit_mainloop;
 449   class->run_mainloop = g_application_real_run_mainloop;
 450
 451   g_object_class_install_property (object_class, PROP_APPLICATION_ID,
 452     g_param_spec_string ("application-id",
 453                          P_("Application identifier"),
 454                          P_("The unique identifier for the application"),
 455                          NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT |
 456                          G_PARAM_STATIC_STRINGS));
 457
 458   g_object_class_install_property (object_class, PROP_FLAGS,
 459     g_param_spec_flags ("flags",
 460                         P_("Application flags"),
 461                         P_("Flags specifying the behaviour of the application"),
 462                         G_TYPE_APPLICATION_FLAGS, G_APPLICATION_FLAGS_NONE,
 463                         G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 464
 465   g_object_class_install_property (object_class, PROP_IS_REGISTERED,
 466     g_param_spec_boolean ("is-registered",
 467                           P_("Is registered"),
 468                           P_("If g_application_register() has been called"),
 469                           FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 470
 471   g_object_class_install_property (object_class, PROP_IS_REMOTE,
 472     g_param_spec_boolean ("is-remote",
 473                           P_("Is remote"),
 474                           P_("If this application instance is remote"),
 475                           FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 476
 477   g_object_class_install_property (object_class, PROP_INACTIVITY_TIMEOUT,
 478     g_param_spec_boolean ("inactivity-timeout",
 479                           P_("Inactivity timeout"),
 480                           P_("Iime (ms) to stay alive after becoming idle"),
 481                           FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 482
 483   g_object_class_install_property (object_class, PROP_ACTION_GROUP,
 484     g_param_spec_object ("action-group",
 485                          P_("Action group"),
 486                          P_("The group of actions that the application exports"),
 487                          G_TYPE_ACTION_GROUP,
 488                          G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS));
 489
 490   /**
 491    * GApplication::startup:
 492    * @application: the application
 493    *
 494    * The ::startup signal is emitted on the primary instance immediately
 495    * after registration. See g_activation_register().
 496    */
 497   g_application_signals[SIGNAL_STARTUP] =
 498     g_signal_new ("startup", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
 499                   G_STRUCT_OFFSET (GApplicationClass, startup),
 500                   NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
 501
 502   /**
 503    * GApplication::activate:
 504    * @application: the application
 505    *
 506    * The ::activate signal is emitted on the primary instance when an
 507    * activation occurs. See g_application_activate().
 508    */
 509   g_application_signals[SIGNAL_ACTIVATE] =
 510     g_signal_new ("activate", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
 511                   G_STRUCT_OFFSET (GApplicationClass, activate),
 512                   NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
 513
 514
 515   /**
 516    * GApplication::open:
 517    * @application: the application
 518    * @files: an array of #GFile objects
 519    * @n_files: the length of @files
 520    * @hint: a hint provided by the calling instance
 521    *
 522    * The ::open signal is emitted on the primary instance when there are
 523    * files to open. See g_application_open() for more information.
 524    */
 525   g_application_signals[SIGNAL_OPEN] =
 526     g_signal_new ("open", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
 527                   G_STRUCT_OFFSET (GApplicationClass, open),
 528                   NULL, NULL, _gio_marshal_VOID__POINTER_INT_STRING,
 529                   G_TYPE_NONE, 3, G_TYPE_POINTER, G_TYPE_INT, G_TYPE_STRING);
 530
 531   /**
 532    * GApplication::command-line:
 533    * @application: the application
 534    * @command_line: a #GApplicationCommandLine representing the
 535    *     passed commandline
 536    *
 537    * The ::command-line signal is emitted on the primary instance when
 538    * a commandline is not handled locally. See g_application_run() for
 539    * more information.
 540    */
 541   g_application_signals[SIGNAL_COMMAND_LINE] =
 542     g_signal_new ("command-line", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
 543                   G_STRUCT_OFFSET (GApplicationClass, command_line),
 544                   g_signal_accumulator_first_wins, NULL,
 545                   _gio_marshal_INT__OBJECT,
 546                   G_TYPE_INT, 1, G_TYPE_APPLICATION_COMMAND_LINE);
 547
 548   g_type_class_add_private (class, sizeof (GApplicationPrivate));
 549 }
 550
 551 static GVariant *
 552 get_platform_data (GApplication *application)
 553 {
 554   GVariantBuilder *builder;
 555   GVariant *result;
 556
 557   builder = g_variant_builder_new (G_VARIANT_TYPE ("a{sv}"));
 558
 559   {
 560     gchar *cwd = g_get_current_dir ();
 561     g_variant_builder_add (builder, "{sv}", "cwd",
 562                            g_variant_new_bytestring (cwd));
 563     g_free (cwd);
 564   }
 565
 566   G_APPLICATION_GET_CLASS (application)->
 567     add_platform_data (application, builder);
 568
 569   result = g_variant_builder_end (builder);
 570   g_variant_builder_unref (builder);
 571
 572   return result;
 573 }
 574
 575 /* Application ID validity {{{1 */
 576
 577 /**
 578  * g_application_id_is_valid:
 579  * @application_id: a potential application identifier
 580  * @returns: %TRUE if @application_id is valid
 581  *
 582  * Checks if @application_id is a valid application ID.  A valid ID is
 583  * required for calls to g_application_new() and
 584  * g_application_set_application_id().
 585  **/
 586 gboolean
 587 g_application_id_is_valid (const gchar *application_id)
 588 {
 589   gboolean allow_dot;
 590
 591   if (strlen (application_id) > 255)
 592     return FALSE;
 593
 594   if (!g_ascii_isalpha (*application_id))
 595     return FALSE;
 596
 597   application_id++;
 598   allow_dot = FALSE;
 599   for (; *application_id; application_id++)
 600     {
 601       if (g_ascii_isalnum (*application_id) ||
 602           (*application_id == '-') ||
 603           (*application_id == '_'))
 604         allow_dot = TRUE;
 605       else if (allow_dot && *application_id == '.')
 606         allow_dot = FALSE;
 607       else
 608         return FALSE;
 609     }
 610
 611   return TRUE;
 612 }
 613
 614 /* Public Constructor {{{1 */
 615 /**
 616  * g_application_new:
 617  * @application_id: the application id
 618  * @flags: the application flags
 619  * @returns: a new #GApplication instance
 620  *
 621  * Creates a new #GApplication instance.
 622  *
 623  * This function calls g_type_init() for you.
 624  *
 625  * The application id must be valid.  See g_application_id_is_valid().
 626  **/
 627 GApplication *
 628 g_application_new (const gchar       *application_id,
 629                    GApplicationFlags  flags)
 630 {
 631   g_return_val_if_fail (g_application_id_is_valid (application_id), NULL);
 632
 633   g_type_init ();
 634
 635   return g_object_new (G_TYPE_APPLICATION,
 636                        "application-id", application_id,
 637                        "flags", flags,
 638                        NULL);
 639 }
 640
 641 /* Simple get/set: application id, flags, inactivity timeout {{{1 */
 642 /**
 643  * g_application_get_application_id:
 644  * @application: a #GApplication
 645  * @returns: the identifier for @application, owned by @application
 646  *
 647  * Gets the unique identifier for @application.
 648  *
 649  * Since: 2.28
 650  **/
 651 const gchar *
 652 g_application_get_application_id (GApplication *application)
 653 {
 654   g_return_val_if_fail (G_IS_APPLICATION (application), NULL);
 655
 656   return application->priv->id;
 657 }
 658
 659 /**
 660  * g_application_set_application_id:
 661  * @application: a #GApplication
 662  * @application_id: the identifier for @application
 663  *
 664  * Sets the unique identifier for @application.
 665  *
 666  * The application id can only be modified if @application has not yet
 667  * been registered.
 668  *
 669  * The application id must be valid.  See g_application_id_is_valid().
 670  *
 671  * Since: 2.28
 672  **/
 673 void
 674 g_application_set_application_id (GApplication *application,
 675                                   const gchar  *application_id)
 676 {
 677   g_return_if_fail (G_IS_APPLICATION (application));
 678
 679   if (g_strcmp0 (application->priv->id, application_id) != 0)
 680     {
 681       g_return_if_fail (g_application_id_is_valid (application_id));
 682       g_return_if_fail (!application->priv->is_registered);
 683
 684       g_free (application->priv->id);
 685       application->priv->id = g_strdup (application_id);
 686
 687       g_object_notify (G_OBJECT (application), "application-id");
 688     }
 689 }
 690
 691 /**
 692  * g_application_get_flags:
 693  * @application: a #GApplication
 694  * @returns: the flags for @application
 695  *
 696  * Gets the flags for @application.
 697  *
 698  * See #GApplicationFlags.
 699  *
 700  * Since: 2.28
 701  **/
 702 GApplicationFlags
 703 g_application_get_flags (GApplication *application)
 704 {
 705   g_return_val_if_fail (G_IS_APPLICATION (application), 0);
 706
 707   return application->priv->flags;
 708 }
 709
 710 /**
 711  * g_application_set_flags:
 712  * @application: a #GApplication
 713  * @flags: the flags for @application
 714  *
 715  * Sets the flags for @application.
 716  *
 717  * The flags can only be modified if @application has not yet been
 718  * registered.
 719  *
 720  * See #GApplicationFlags.
 721  *
 722  * Since: 2.28
 723  **/
 724 void
 725 g_application_set_flags (GApplication      *application,
 726                          GApplicationFlags  flags)
 727 {
 728   g_return_if_fail (G_IS_APPLICATION (application));
 729
 730   if (application->priv->flags != flags)
 731     {
 732       g_return_if_fail (!application->priv->is_registered);
 733
 734       application->priv->flags = flags;
 735
 736       g_object_notify (G_OBJECT (application), "flags");
 737     }
 738 }
 739
 740 /**
 741  * g_application_get_inactivity_timeout:
 742  * @application: a #GApplication
 743  *
 744  * Gets the current inactivity timeout for the application.
 745  *
 746  * This is the amount of time (in milliseconds) after the last call to
 747  * g_application_release() before the application stops running.
 748  *
 749  * Returns: the timeout, in milliseconds
 750  *
 751  * Since: 2.28
 752  **/
 753 guint
 754 g_application_get_inactivity_timeout (GApplication *application)
 755 {
 756   g_return_val_if_fail (G_IS_APPLICATION (application), 0);
 757
 758   return application->priv->inactivity_timeout;
 759 }
 760
 761 /**
 762  * g_application_set_inactivity_timeout:
 763  * @application: a #GApplication
 764  * @inactivity_timeout: the timeout, in milliseconds
 765  *
 766  * Sets the current inactivity timeout for the application.
 767  *
 768  * This is the amount of time (in milliseconds) after the last call to
 769  * g_application_release() before the application stops running.
 770  *
 771  * This call has no side effects of its own.  The value set here is only
 772  * used for next time g_application_release() drops the use count to
 773  * zero.  Any timeouts currently in progress are not impacted.
 774  *
 775  * Returns: the timeout, in milliseconds
 776  *
 777  * Since: 2.28
 778  **/
 779 void
 780 g_application_set_inactivity_timeout (GApplication *application,
 781                                       guint         inactivity_timeout)
 782 {
 783   g_return_if_fail (G_IS_APPLICATION (application));
 784
 785   if (application->priv->inactivity_timeout != inactivity_timeout)
 786     {
 787       application->priv->inactivity_timeout = inactivity_timeout;
 788
 789       g_object_notify (G_OBJECT (application), "inactivity-timeout");
 790     }
 791 }
 792 /* Read-only property getters (is registered, is remote) {{{1 */
 793 /**
 794  * g_application_get_is_registered:
 795  * @application: a #GApplication
 796  * @returns: %TRUE if @application is registered
 797  *
 798  * Checks if @application is registered.
 799  *
 800  * An application is registered if g_application_register() has been
 801  * successfully called.
 802  *
 803  * Since: 2.28
 804  **/
 805 gboolean
 806 g_application_get_is_registered (GApplication *application)
 807 {
 808   g_return_val_if_fail (G_IS_APPLICATION (application), FALSE);
 809
 810   return application->priv->is_registered;
 811 }
 812
 813 /**
 814  * g_application_get_is_remote:
 815  * @application: a #GApplication
 816  * @returns: %TRUE if @application is remote
 817  *
 818  * Checks if @application is remote.
 819  *
 820  * If @application is remote then it means that another instance of
 821  * application already exists (the 'primary' instance).  Calls to
 822  * perform actions on @application will result in the actions being
 823  * performed by the primary instance.
 824  *
 825  * The value of this property can not be accessed before
 826  * g_application_register() has been called.  See
 827  * g_application_get_is_registered().
 828  *
 829  * Since: 2.28
 830  **/
 831 gboolean
 832 g_application_get_is_remote (GApplication *application)
 833 {
 834   g_return_val_if_fail (G_IS_APPLICATION (application), FALSE);
 835   g_return_val_if_fail (application->priv->is_registered, FALSE);
 836
 837   return application->priv->is_remote;
 838 }
 839
 840 /* Register {{{1 */
 841 /**
 842  * g_application_register:
 843  * @application: a #GApplication
 844  * @cancellable: a #GCancellable, or %NULL
 845  * @error: a pointer to a NULL #GError, or %NULL
 846  * @returns: %TRUE if registration succeeded
 847  *
 848  * Attempts registration of the application.
 849  *
 850  * This is the point at which the application discovers if it is the
 851  * primary instance or merely acting as a remote for an already-existing
 852  * primary instance.
 853  *
 854  * If the application has already been registered then %TRUE is
 855  * returned with no work performed.
 856  *
 857  * The startup() virtual function is invoked if registration succeeds
 858  * and @application is the primary instance.
 859  *
 860  * In the event of an error (such as @cancellable being cancelled, or a
 861  * failure to connect to the session bus), %FALSE is returned and @error
 862  * is set appropriately.
 863  *
 864  * Note: the return value of this function is not an indicator that this
 865  * instance is or is not the primary instance of the application.  See
 866  * g_application_get_is_remote() for that.
 867  *
 868  * Since: 2.28
 869  **/
 870 gboolean
 871 g_application_register (GApplication  *application,
 872                         GCancellable  *cancellable,
 873                         GError       **error)
 874 {
 875   g_return_val_if_fail (G_IS_APPLICATION (application), FALSE);
 876
 877   if (!application->priv->is_registered)
 878     {
 879       gboolean is_remote;
 880       gboolean try;
 881
 882       /* don't try to be the primary instance if
 883        * G_APPLICATION_IS_LAUNCHER was specified.
 884        */
 885       try = !(application->priv->flags & G_APPLICATION_IS_LAUNCHER);
 886
 887       application->priv->impl =
 888         g_application_impl_register (application, application->priv->id,
 889                                      application->priv->flags,
 890                                      &is_remote, cancellable, error);
 891
 892       if (application->priv->impl == NULL)
 893         return FALSE;
 894
 895       application->priv->is_remote = is_remote;
 896       application->priv->is_registered = TRUE;
 897
 898       g_object_notify (G_OBJECT (application), "is-registered");
 899
 900       if (!is_remote)
 901         g_signal_emit (application, g_application_signals[SIGNAL_STARTUP], 0);
 902     }
 903
 904   return TRUE;
 905 }
 906
 907 /* Hold/release {{{1 */
 908 /**
 909  * g_application_hold:
 910  * @application: a #GApplication
 911  *
 912  * Increases the use count of @application.
 913  *
 914  * Use this function to indicate that the application has a reason to
 915  * continue to run.  For example, g_application_hold() is called by Gtk
 916  * when a toplevel window is on the screen.
 917  *
 918  * To cancel the hold, call g_application_release().
 919  **/
 920 void
 921 g_application_hold (GApplication *application)
 922 {
 923   if (application->priv->inactivity_timeout_id)
 924     {
 925       g_source_remove (application->priv->inactivity_timeout_id);
 926       application->priv->inactivity_timeout_id = 0;
 927     }
 928
 929   application->priv->use_count++;
 930 }
 931
 932 static gboolean
 933 inactivity_timeout_expired (gpointer data)
 934 {
 935   GApplication *application = G_APPLICATION (data);
 936
 937   G_APPLICATION_GET_CLASS (application)
 938     ->quit_mainloop (application);
 939
 940   return FALSE;
 941 }
 942
 943
 944 /**
 945  * g_application_release:
 946  * @application: a #GApplication
 947  *
 948  * Decrease the use count of @application.
 949  *
 950  * When the use count reaches zero, the application will stop running.
 951  *
 952  * Never call this function except to cancel the effect of a previous
 953  * call to g_application_hold().
 954  **/
 955 void
 956 g_application_release (GApplication *application)
 957 {
 958   application->priv->use_count--;
 959
 960   if (application->priv->use_count == 0)
 961     {
 962       if (application->priv->inactivity_timeout)
 963         application->priv->inactivity_timeout_id =
 964           g_timeout_add (application->priv->inactivity_timeout,
 965                          inactivity_timeout_expired, application);
 966
 967       else
 968         G_APPLICATION_GET_CLASS (application)
 969           ->quit_mainloop (application);
 970     }
 971 }
 972
 973 /* Activate, Open {{{1 */
 974 /**
 975  * g_application_activate:
 976  * @application: a #GApplication
 977  *
 978  * Activates the application.
 979  *
 980  * In essence, this results in the activate() virtual function being
 981  * invoked in the primary instance.
 982  *
 983  * The application must be registered before calling this function.
 984  *
 985  * Since: 2.28
 986  **/
 987 void
 988 g_application_activate (GApplication *application)
 989 {
 990   g_return_if_fail (G_IS_APPLICATION (application));
 991   g_return_if_fail (application->priv->is_registered);
 992
 993   if (application->priv->is_remote)
 994     g_application_impl_activate (application->priv->impl,
 995                                  get_platform_data (application));
 996
 997   else
 998     g_signal_emit (application, g_application_signals[SIGNAL_ACTIVATE], 0);
 999 }
1000
1001 /**
1002  * g_application_open:
1003  * @application: a #GApplication
1004  * @files: an array of #GFile<!-- -->s to open
1005  * @n_files: the length of the @files array
1006  * @hint: a hint (or ""), but never %NULL
1007  *
1008  * Opens the given files.
1009  *
1010  * In essence, this results in the open() virtual function being invoked
1011  * in the primary instance.
1012  *
1013  * @n_files must be greater than zero.
1014  *
1015  * @hint is simply passed through to the open() virtual function.  It is
1016  * intended to be used by applications that have multiple modes for
1017  * opening files (eg: "view" vs "edit", etc).  Unless you have a need
1018  * for this functionality, you should use "".
1019  *
1020  * The application must be registered before calling this function and
1021  * it must have the %G_APPLICATION_HANDLES_OPEN flag set.  The open()
1022  * virtual function should also be implemented in order for anything
1023  * meaningful to happen.
1024  *
1025  * Since: 2.28
1026  **/
1027 void
1028 g_application_open (GApplication  *application,
1029                     GFile        **files,
1030                     gint           n_files,
1031                     const gchar   *hint)
1032 {
1033   g_return_if_fail (G_IS_APPLICATION (application));
1034   g_return_if_fail (application->priv->flags &
1035                     G_APPLICATION_HANDLES_OPEN);
1036   g_return_if_fail (application->priv->is_registered);
1037
1038   if (application->priv->is_remote)
1039     g_application_impl_open (application->priv->impl,
1040                              files, n_files, hint,
1041                              get_platform_data (application));
1042
1043   else
1044     g_signal_emit (application, g_application_signals[SIGNAL_OPEN],
1045                    0, files, n_files, hint);
1046 }
1047
1048 /* Run {{{1 */
1049 /**
1050  * g_application_run:
1051  * @application: a #GApplication
1052  * @argc: the argc from main()
1053  * @argv: the argv from main()
1054  * @returns: the exit status
1055  *
1056  * Runs the application.
1057  *
1058  * This function is intended to be run from main() and its return value
1059  * is intended to be returned by main().
1060  *
1061  * First, the handle_command_line() virtual function is invoked.  This
1062  * function always runs on the local instance.  If that function returns
1063  * %FALSE then the application is registered and the #GApplication::command-line
1064  * signal is emitted in the primary instance (which may or may not be
1065  * this instance).
1066  *
1067  * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
1068  * flag set then the default implementation of handle_command_line()
1069  * always returns %FALSE immediately, resulting in the commandline
1070  * always being handled in the primary instance.
1071  *
1072  * Otherwise, the default implementation of handle_command_line() tries
1073  * to do a couple of things that are probably reasonable for most
1074  * applications.  First, g_application_register() is called to attempt
1075  * to register the application.  If that works, then the command line
1076  * arguments are inspected.  If no commandline arguments are given, then
1077  * g_application_activate() is called.  If commandline arguments are
1078  * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they
1079  * are assumed to be filenames and g_application_open() is called.
1080  *
1081  * If you are interested in doing more complicated local handling of the
1082  * commandline then you should override handle_command_line().
1083  *
1084  * If, after the above is done, the use count of the application is zero
1085  * then the exit status is returned immediately.  If the use count is
1086  * non-zero then the mainloop is run until the use count falls to zero,
1087  * at which point 0 is returned.
1088  *
1089  * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at
1090  * use count of zero is delayed for a while (ie: the instance stays
1091  * around to provide its <emphasis>service</emphasis> to others).
1092  *
1093  * Since: 2.28
1094  **/
1095 int
1096 g_application_run (GApplication  *application,
1097                    int            argc,
1098                    char         **argv)
1099 {
1100   gchar **arguments;
1101   int status;
1102   gint i;
1103
1104   g_return_val_if_fail (G_IS_APPLICATION (application), 1);
1105   g_return_val_if_fail (argc == 0 || argv != NULL, 1);
1106
1107   arguments = g_new (gchar *, argc + 1);
1108   for (i = 0; i < argc; i++)
1109     arguments[i] = g_strdup (argv[i]);
1110   arguments[i] = NULL;
1111
1112   if (g_get_prgname () == NULL && argc > 0)
1113     {
1114       gchar *prgname;
1115
1116       prgname = g_path_get_basename (argv[0]);
1117       g_set_prgname (prgname);
1118       g_free (prgname);
1119     }
1120
1121   if (!G_APPLICATION_GET_CLASS (application)
1122         ->local_command_line (application, &arguments, &status))
1123     {
1124       GError *error = NULL;
1125
1126       if (!g_application_register (application, NULL, &error))
1127         {
1128           g_printerr ("%s", error->message);
1129           g_error_free (error);
1130           return 1;
1131         }
1132
1133       if (application->priv->is_remote)
1134         {
1135           GVariant *platform_data;
1136
1137           platform_data = get_platform_data (application);
1138           status = g_application_impl_command_line (application->priv->impl,
1139                                                     arguments, platform_data);
1140         }
1141       else
1142         {
1143           GApplicationCommandLine *cmdline;
1144           GVariant *v;
1145
1146           v = g_variant_new_bytestring_array ((const gchar **) arguments, -1);
1147           cmdline = g_object_new (G_TYPE_APPLICATION_COMMAND_LINE,
1148                                   "arguments", v, NULL);
1149           g_signal_emit (application,
1150                          g_application_signals[SIGNAL_COMMAND_LINE],
1151                          0, cmdline, &status);
1152           g_object_unref (cmdline);
1153         }
1154     }
1155
1156   g_strfreev (arguments);
1157
1158   if (application->priv->flags & G_APPLICATION_IS_SERVICE &&
1159       !application->priv->use_count &&
1160       !application->priv->inactivity_timeout_id)
1161     {
1162       application->priv->inactivity_timeout_id =
1163         g_timeout_add (10000, inactivity_timeout_expired, application);
1164     }
1165
1166   if (application->priv->use_count ||
1167       application->priv->inactivity_timeout_id)
1168     {
1169       G_APPLICATION_GET_CLASS (application)
1170         ->run_mainloop (application);
1171       status = 0;
1172     }
1173
1174   if (application->priv->impl)
1175     g_application_impl_flush (application->priv->impl);
1176
1177   return status;
1178 }
1179
1180 static gboolean
1181 g_application_has_action (GActionGroup *action_group,
1182                           const gchar  *action_name)
1183 {
1184   GApplication *application = G_APPLICATION (action_group);
1185
1186   g_return_val_if_fail (application->priv->is_registered, FALSE);
1187
1188   return application->priv->actions &&
1189          g_action_group_has_action (application->priv->actions, action_name);
1190 }
1191
1192 static gchar **
1193 g_application_list_actions (GActionGroup *action_group)
1194 {
1195   GApplication *application = G_APPLICATION (action_group);
1196
1197   g_return_val_if_fail (application->priv->is_registered, NULL);
1198
1199   if (application->priv->actions != NULL)
1200     return g_action_group_list_actions (application->priv->actions);
1201
1202   else
1203     /* empty string array */
1204     return g_new0 (gchar *, 1);
1205 }
1206
1207 static gboolean
1208 g_application_get_action_enabled (GActionGroup *action_group,
1209                                   const gchar  *action_name)
1210 {
1211   GApplication *application = G_APPLICATION (action_group);
1212
1213   g_return_val_if_fail (application->priv->actions != NULL, FALSE);
1214   g_return_val_if_fail (application->priv->is_registered, FALSE);
1215
1216   return g_action_group_get_action_enabled (application->priv->actions,
1217                                             action_name);
1218 }
1219
1220 static const GVariantType *
1221 g_application_get_action_parameter_type (GActionGroup *action_group,
1222                                          const gchar  *action_name)
1223 {
1224   GApplication *application = G_APPLICATION (action_group);
1225
1226   g_return_val_if_fail (application->priv->actions != NULL, NULL);
1227   g_return_val_if_fail (application->priv->is_registered, NULL);
1228
1229   return g_action_group_get_action_parameter_type (application->priv->actions,
1230                                                    action_name);
1231 }
1232
1233 static const GVariantType *
1234 g_application_get_action_state_type (GActionGroup *action_group,
1235                                      const gchar  *action_name)
1236 {
1237   GApplication *application = G_APPLICATION (action_group);
1238
1239   g_return_val_if_fail (application->priv->actions != NULL, NULL);
1240   g_return_val_if_fail (application->priv->is_registered, NULL);
1241
1242   return g_action_group_get_action_state_type (application->priv->actions,
1243                                                action_name);
1244 }
1245
1246 static GVariant *
1247 g_application_get_action_state_hint (GActionGroup *action_group,
1248                                      const gchar  *action_name)
1249 {
1250   GApplication *application = G_APPLICATION (action_group);
1251
1252   g_return_val_if_fail (application->priv->actions != NULL, NULL);
1253   g_return_val_if_fail (application->priv->is_registered, NULL);
1254
1255   return g_action_group_get_action_state_hint (application->priv->actions,
1256                                                action_name);
1257 }
1258
1259 static GVariant *
1260 g_application_get_action_state (GActionGroup *action_group,
1261                                 const gchar  *action_name)
1262 {
1263   GApplication *application = G_APPLICATION (action_group);
1264
1265   g_return_val_if_fail (application->priv->actions != NULL, NULL);
1266   g_return_val_if_fail (application->priv->is_registered, NULL);
1267
1268   return g_action_group_get_action_state (application->priv->actions,
1269                                           action_name);
1270 }
1271
1272 static void
1273 g_application_change_action_state (GActionGroup *action_group,
1274                                    const gchar  *action_name,
1275                                    GVariant     *value)
1276 {
1277   GApplication *application = G_APPLICATION (action_group);
1278
1279   g_return_if_fail (application->priv->actions != NULL);
1280   g_return_if_fail (application->priv->is_registered);
1281
1282   g_action_group_change_action_state (application->priv->actions,
1283                                       action_name, value);
1284 }
1285
1286 static void
1287 g_application_activate_action (GActionGroup *action_group,
1288                                const gchar  *action_name,
1289                                GVariant     *parameter)
1290 {
1291   GApplication *application = G_APPLICATION (action_group);
1292
1293   g_return_if_fail (application->priv->actions != NULL);
1294   g_return_if_fail (application->priv->is_registered);
1295
1296   g_action_group_activate_action (application->priv->actions,
1297                                   action_name, parameter);
1298 }
1299
1300 static void
1301 g_application_action_group_iface_init (GActionGroupInterface *iface)
1302 {
1303   iface->has_action = g_application_has_action;
1304   iface->list_actions = g_application_list_actions;
1305
1306   iface->get_action_enabled = g_application_get_action_enabled;
1307   iface->get_action_parameter_type = g_application_get_action_parameter_type;
1308   iface->get_action_state_type = g_application_get_action_state_type;
1309   iface->get_action_state_hint = g_application_get_action_state_hint;
1310   iface->get_action_state = g_application_get_action_state;
1311   iface->change_action_state = g_application_change_action_state;
1312   iface->activate_action = g_application_activate_action;
1313 }
1314
1315 /* Epilogue {{{1 */
1316 /* vim:set foldmethod=marker: */