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