gio/gapplication.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright © 2010 Red Hat, Inc
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library 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 GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General
  16  * Public License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  *
  20  * Authors: Colin Walters <walters@verbum.org>
  21  *          Emmanuele Bassi <ebassi@linux.intel.com>
  22  */
  23
  24 #include "config.h"
  25
  26 #include <string.h>
  27 #include <stdlib.h>
  28
  29 #include <gobject/gvaluecollector.h>
  30
  31 #include "gapplication.h"
  32 #include "gio-marshal.h"
  33 #include "glibintl.h"
  34
  35 #include "gioerror.h"
  36
  37 #include "gdbusconnection.h"
  38 #include "gdbusintrospection.h"
  39 #include "gdbusmethodinvocation.h"
  40
  41 #include "gioalias.h"
  42
  43 /**
  44  * SECTION: gapplication
  45  * @title: GApplication
  46  * @short_description: Core application class
  47  *
  48  * A #GApplication is the foundation of an application, unique for
  49  * a given application identifier.  The #GApplication wraps some
  50  * low-level platform-specific services; it's expected that most
  51  * software will use a higher-level application class such as
  52  * #GtkApplication or #MxApplication.
  53  *
  54  * In addition to single-instance-ness, #GApplication provides support
  55  * for 'actions', which can be presented to the user in a platform-specific
  56  * way (e.g. Windows 7 jump lists). Note that these are just simple actions
  57  * without parameters. For more flexible scriptability, implementing a
  58  * a separate D-Bus interface is recommended, see e.g.
  59  * <xref linkend="gdbus-convenience"/>.
  60  *
  61  * Before using #GApplication, you must choose an "application identifier".
  62  * The expected form of an application identifier is very close to that of
  63  * of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>.
  64  * Examples include: "com.example.MyApp" "org.example.internal-apps.Calculator"
  65  * For convenience, the restrictions on application identifiers are reproduced
  66  * here:
  67  * <itemizedlist>
  68  *   <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit.</listitem>
  69  *   <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least two elements).</listitem>
  70  *   <listitem>Application identifiers must not begin with a '.' (period) character.</listitem>
  71  *   <listitem>Application identifiers must not exceed 255 characters.</listitem>
  72  * </itemizedlist>
  73  *
  74  * <refsect2><title>D-Bus implementation</title>
  75  * <para>
  76  * On UNIX systems using D-Bus, #GApplication is implemented by claiming the
  77  * application identifier as a bus name on the session bus. The implementation
  78  * exports an object at the object path that is created by replacing '.' with
  79  * '/' in the application identifier (e.g. the object path for the
  80  * application id 'org.gtk.TestApp' is '/org/gtk/TestApp'). The object
  81  * implements the org.gtk.Application interface.
  82  * </para>
  83  * <classsynopsis class="interface">
  84  *   <ooclass><interfacename>org.gtk.Application</interfacename></ooclass>
  85  *   <methodsynopsis>
  86  *     <void/>
  87  *     <methodname>Activate</methodname>
  88  *     <methodparam><modifier>in</modifier><type>aay</type><parameter>arguments</parameter></methodparam>
  89  *     <methodparam><modifier>in</modifier><type>a{sv}</type><parameter>data</parameter></methodparam>
  90  *   </methodsynopsis>
  91  *   <methodsynopsis>
  92  *     <void/>
  93  *     <methodname>InvokeAction</methodname>
  94  *     <methodparam><modifier>in</modifier><type>s</type><parameter>action</parameter></methodparam>
  95  *     <methodparam><modifier>in</modifier><type>u</type><parameter>timestamp</parameter></methodparam>
  96  *   </methodsynopsis>
  97  *   <methodsynopsis>
  98  *     <type>a{s(sb)}</type>
  99  *     <methodname>ListActions</methodname>
 100  *     <void/>
 101  *   </methodsynopsis>
 102  *   <methodsynopsis>
 103  *     <void/>
 104  *     <methodname>Quit</methodname>
 105  *     <methodparam><modifier>in</modifier><type>u</type><parameter>timestamp</parameter></methodparam>
 106  *   </methodsynopsis>
 107  *   <methodsynopsis>
 108  *     <modifier>Signal</modifier>
 109  *     <void/>
 110  *     <methodname>ActionsChanged</methodname>
 111  *     <void/>
 112  *   </methodsynopsis>
 113  * </classsynopsis>
 114  * <para>
 115  * The <methodname>Activate</methodname> function is called on the existing
 116  * application instance when a second instance fails to take the bus name.
 117  * @arguments contains the commandline arguments given to the second instance
 118  * and @data contains platform-specific additional data, see
 119  * g_application_format_activation_data().
 120  * </para>
 121  * <para>
 122  * The <methodname>InvokeAction</methodname> function can be called to invoke
 123  * one of the actions exported by the application. The @timestamp parameter
 124  * should be taken from the user event that triggered the method call (e.g.
 125  * a button press event).
 126  * </para>
 127  * <para>
 128  * The <methodname>ListActions</methodname> function returns a dictionary
 129  * with the exported actions of the application. The keys of the dictionary
 130  * are the action names, and the values are structs containing the description
 131  * for the action and a boolean that represents if the action is enabled or not.
 132  * </para>
 133  * <para>
 134  * The <methodname>Quit</methodname> function can be called to terminate
 135  * the application. The @timestamp parameter should be taken from the user
 136  * event that triggered the method call (e.g. a button press event).
 137  * </para>
 138  * <para>
 139  * The <methodname>ActionsChanged</methodname> signal is emitted when the
 140  * exported actions change (i.e. an action is added, removed, enabled,
 141  * disabled, or otherwise changed).
 142  * </para>
 143  * <para>
 144  * #GApplication is supported since Gio 2.26.
 145  * </para>
 146  * </refsect2>
 147  */
 148
 149 G_DEFINE_TYPE (GApplication, g_application, G_TYPE_OBJECT);
 150
 151 enum
 152 {
 153   PROP_0,
 154
 155   PROP_APPLICATION_ID,
 156   PROP_DEFAULT_QUIT,
 157   PROP_IS_REMOTE
 158 };
 159
 160 enum
 161 {
 162   QUIT,
 163   ACTION,
 164   PREPARE_ACTIVATION,
 165
 166   LAST_SIGNAL
 167 };
 168
 169 static guint application_signals[LAST_SIGNAL] = { 0 };
 170
 171 typedef struct {
 172   gchar *name;
 173   gchar *description;
 174   guint enabled : 1;
 175 } GApplicationAction;
 176
 177 struct _GApplicationPrivate
 178 {
 179   gchar *appid;
 180   GHashTable *actions; /* name -> GApplicationAction */
 181   GMainLoop *mainloop;
 182
 183   guint default_quit : 1;
 184   guint is_remote    : 1;
 185
 186   guint actions_changed_id;
 187
 188 #ifdef G_OS_UNIX
 189   gchar *dbus_path;
 190   GDBusConnection *session_bus;
 191 #endif
 192 };
 193
 194 static GApplication *primary_application = NULL;
 195 static GHashTable *instances_for_appid = NULL;
 196
 197 static void     _g_application_platform_init                    (GApplication  *app);
 198 static gboolean _g_application_platform_acquire_single_instance (GApplication  *app,
 199                                                                  GError       **error);
 200 static void     _g_application_platform_remote_invoke_action    (GApplication  *app,
 201                                                                  const gchar   *action,
 202                                                                  guint          timestamp);
 203 static void     _g_application_platform_remote_quit             (GApplication  *app,
 204                                                                  guint          timestamp);
 205 static void     _g_application_platform_activate                (GApplication  *app,
 206                                                                  GVariant      *data) G_GNUC_NORETURN;
 207 static void     _g_application_platform_on_actions_changed      (GApplication  *app);
 208
 209 #ifdef G_OS_UNIX
 210 #include "gdbusapplication.c"
 211 #else
 212 #include "gnullapplication.c"
 213 #endif
 214
 215 static gboolean
 216 _g_application_validate_id (const char *id)
 217 {
 218   gboolean allow_dot;
 219
 220   if (strlen (id) > 255)
 221     return FALSE;
 222
 223   if (!g_ascii_isalpha (*id))
 224     return FALSE;
 225
 226   id++;
 227   allow_dot = FALSE;
 228   for (; *id; id++)
 229     {
 230       if (g_ascii_isalnum (*id) || (*id == '-') || (*id == '_'))
 231         allow_dot = TRUE;
 232       else if (allow_dot && *id == '.')
 233         allow_dot = FALSE;
 234       else
 235         return FALSE;
 236     }
 237   return TRUE;
 238 }
 239
 240 static gpointer
 241 init_appid_statics (gpointer data)
 242 {
 243   instances_for_appid = g_hash_table_new (g_str_hash, g_str_equal);
 244   return NULL;
 245 }
 246
 247 static GApplication *
 248 application_for_appid (const char *appid)
 249 {
 250   static GOnce appid_once = G_ONCE_INIT;
 251
 252   g_once (&appid_once, init_appid_statics, NULL);
 253
 254   return g_hash_table_lookup (instances_for_appid, appid);
 255 }
 256
 257 static gboolean
 258 g_application_default_quit (GApplication *application,
 259                             guint         timestamp)
 260 {
 261   g_return_val_if_fail (application->priv->mainloop != NULL, FALSE);
 262   g_main_loop_quit (application->priv->mainloop);
 263
 264   return TRUE;
 265 }
 266
 267 static void
 268 g_application_default_run (GApplication *application)
 269 {
 270   if (application->priv->mainloop == NULL)
 271     application->priv->mainloop = g_main_loop_new (NULL, TRUE);
 272
 273   g_main_loop_run (application->priv->mainloop);
 274 }
 275
 276 static void
 277 _g_application_handle_activation (GApplication  *app,
 278                                   int            argc,
 279                                   char         **argv,
 280                                   GVariant      *platform_data)
 281 {
 282   GVariantBuilder builder;
 283   GVariant *message;
 284   int i;
 285
 286   g_variant_builder_init (&builder, G_VARIANT_TYPE ("(aaya{sv})"));
 287   g_variant_builder_open (&builder, G_VARIANT_TYPE ("aay"));
 288
 289   for (i = 1; i < argc; i++)
 290     {
 291       int j;
 292       guint8 *argv_bytes;
 293
 294       g_variant_builder_open (&builder, G_VARIANT_TYPE ("ay"));
 295
 296       argv_bytes = (guint8*) argv[i];
 297       for (j = 0; argv_bytes[j]; j++)
 298         g_variant_builder_add_value (&builder,
 299                                      g_variant_new_byte (argv_bytes[j]));
 300       g_variant_builder_close (&builder);
 301     }
 302   g_variant_builder_close (&builder);
 303
 304   if (platform_data)
 305     g_variant_builder_add (&builder, "@a{sv}", platform_data);
 306   else
 307     {
 308       g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}"));
 309       g_variant_builder_close (&builder);
 310     }
 311
 312   message = g_variant_builder_end (&builder);
 313   _g_application_platform_activate (app, message);
 314   g_variant_unref (message);
 315 }
 316
 317 static gboolean
 318 timeout_handle_actions_changed (gpointer user_data)
 319 {
 320   GApplication *application = user_data;
 321
 322   application->priv->actions_changed_id = 0;
 323
 324   _g_application_platform_on_actions_changed (application);
 325
 326   return FALSE;
 327 }
 328
 329 static inline void
 330 queue_actions_change_notification (GApplication *application)
 331 {
 332   GApplicationPrivate *priv = application->priv;
 333
 334   if (priv->actions_changed_id == 0)
 335     priv->actions_changed_id = g_timeout_add (0, timeout_handle_actions_changed, application);
 336 }
 337
 338 static void
 339 g_application_action_free (gpointer data)
 340 {
 341   if (G_LIKELY (data != NULL))
 342     {
 343       GApplicationAction *action = data;
 344
 345       g_free (action->name);
 346       g_free (action->description);
 347
 348       g_slice_free (GApplicationAction, action);
 349     }
 350 }
 351
 352
 353 /**
 354  * g_application_new:
 355  * @appid: System-dependent application identifier
 356  *
 357  * Create a new #GApplication.  The application is initially in
 358  * "remote" mode.  Almost certainly, you want to call
 359  * g_application_register() immediately after this function, which
 360  * will finish initialization.
 361  *
 362  * As a convenience, this function is defined to call g_type_init() as
 363  * its very first action.
 364  *
 365  * Returns: (transfer full): An application instance
 366  *
 367  * Since: 2.26
 368  */
 369 GApplication *
 370 g_application_new (const gchar *appid)
 371 {
 372   g_type_init ();
 373
 374   return G_APPLICATION (g_object_new (G_TYPE_APPLICATION, "application-id", appid, NULL));
 375 }
 376
 377 /**
 378  * g_application_register_with_data:
 379  * @application: A #GApplication
 380  * @argc: System argument count
 381  * @argv: (array length=argc): System argument vector
 382  * @platform_data: (allow-none): Arbitrary platform-specific data, must have signature "a{sv}"
 383  *
 384  * Ensure the current process is the unique owner of the application.
 385  * If successful, the #GApplication:is-remote property will be changed
 386  * to %FALSE, and it is safe to continue creating other resources
 387  * such as graphics windows.
 388  *
 389  * If the given @appid is already running in another process, the
 390  * #GApplication:default-exit property will be evaluated.  If it's
 391  * %TRUE, then a platform-specific action such as bringing any
 392  * graphics windows associated with the application to the foreground
 393  * may be initiated.  After that, the current process will terminate.
 394  * If %FALSE, then the application remains in the #GApplication:is-remote
 395  * state, and you can e.g. call g_application_invoke_action().
 396  *
 397  * This function may do synchronous I/O to obtain unique ownership
 398  * of the application id, and will block the calling thread in this
 399  * case.
 400  */
 401 void
 402 g_application_register_with_data (GApplication  *application,
 403                                   gint           argc,
 404                                   gchar        **argv,
 405                                   GVariant      *platform_data)
 406 {
 407   g_return_if_fail (application->priv->appid != NULL);
 408   g_return_if_fail (application->priv->is_remote);
 409   g_return_if_fail (platform_data == NULL
 410                     || g_variant_is_of_type (platform_data, G_VARIANT_TYPE ("a{sv}")));
 411
 412   if (!_g_application_platform_acquire_single_instance (application, NULL))
 413     {
 414       if (application->priv->default_quit)
 415         _g_application_handle_activation (application, argc, argv, platform_data);
 416       else
 417         return;
 418     }
 419
 420   application->priv->is_remote = FALSE;
 421
 422   _g_application_platform_init (application);
 423 }
 424
 425 /**
 426  * g_application_new_and_register:
 427  * @appid: An application identifier
 428  * @argc: System argument count
 429  * @argv: (array length=argc): System argument vector
 430  *
 431  * This is a convenience function which combines g_application_new()
 432  * with g_application_register_with_data(). Therefore, it may block
 433  * the calling thread just like g_application_register_with_data().
 434  */
 435 GApplication *
 436 g_application_new_and_register (const gchar  *appid,
 437                                 gint          argc,
 438                                 gchar       **argv)
 439 {
 440   GApplication *app = g_application_new (appid);
 441   g_application_register_with_data (app, argc, argv, NULL);
 442   return app;
 443 }
 444
 445 /**
 446  * g_application_add_action:
 447  * @application: a #GApplication
 448  * @name: the action name
 449  * @description: the action description; can be a translatable
 450  *   string
 451  *
 452  * Adds an action @name to the list of exported actions of @application.
 453  *
 454  * It is an error to call this function if @application is a proxy for
 455  * a remote application.
 456  *
 457  * You can invoke an action using g_application_invoke_action().
 458  *
 459  * The newly added action is enabled by default; you can call
 460  * g_application_set_action_enabled() to disable it.
 461  *
 462  * Since: 2.26
 463  */
 464 void
 465 g_application_add_action (GApplication *application,
 466                           const gchar  *name,
 467                           const gchar  *description)
 468 {
 469   GApplicationPrivate *priv;
 470   GApplicationAction *action;
 471
 472   g_return_if_fail (G_IS_APPLICATION (application));
 473   g_return_if_fail (name != NULL && *name != '\0');
 474   g_return_if_fail (!application->priv->is_remote);
 475
 476   priv = application->priv;
 477
 478   g_return_if_fail (g_hash_table_lookup (priv->actions, name) == NULL);
 479
 480   action = g_slice_new (GApplicationAction);
 481   action->name = g_strdup (name);
 482   action->description = g_strdup (description);
 483   action->enabled = TRUE;
 484
 485   g_hash_table_insert (priv->actions, action->name, action);
 486   queue_actions_change_notification (application);
 487 }
 488
 489 /**
 490  * g_application_remove_action:
 491  * @application: a #GApplication
 492  * @name: the name of the action to remove
 493  *
 494  * Removes the action @name from the list of exported actions of @application.
 495  *
 496  * It is an error to call this function if @application is a proxy for
 497  * a remote application.
 498  *
 499  * Since: 2.26
 500  */
 501 void
 502 g_application_remove_action (GApplication *application,
 503                              const gchar  *name)
 504 {
 505   GApplicationPrivate *priv;
 506
 507   g_return_if_fail (G_IS_APPLICATION (application));
 508   g_return_if_fail (name != NULL && *name != '\0');
 509   g_return_if_fail (!application->priv->is_remote);
 510
 511   priv = application->priv;
 512
 513   g_return_if_fail (g_hash_table_lookup (priv->actions, name) != NULL);
 514
 515   g_hash_table_remove (priv->actions, name);
 516   queue_actions_change_notification (application);
 517 }
 518
 519 /**
 520  * g_application_invoke_action:
 521  * @application: a #GApplication
 522  * @name: the name of the action to invoke
 523  * @timestamp: the timestamp that is going to be passed to
 524  *   the #GApplication::action signal
 525  *
 526  * Invokes the action @name of the passed #GApplication.
 527  *
 528  * This function has different behavior depending on whether @application
 529  * is acting as a proxy for another process.  In the normal case where
 530  * the current process is hosting the application, and the specified
 531  * action exists and is enabled, the #GApplication::action signal will
 532  * be emitted.
 533  *
 534  * If @application is a proxy, then the specified action will be invoked
 535  * in the remote process. It is not necessary to call
 536  * g_application_add_action() in the current process in order to invoke
 537  * one remotely.
 538  *
 539  * Since: 2.26
 540  */
 541 void
 542 g_application_invoke_action (GApplication *application,
 543                              const gchar  *name,
 544                              guint         timestamp)
 545 {
 546   GApplicationPrivate *priv;
 547   GApplicationAction *action;
 548
 549   g_return_if_fail (G_IS_APPLICATION (application));
 550   g_return_if_fail (name != NULL);
 551
 552   priv = application->priv;
 553
 554   if (priv->is_remote)
 555     {
 556       _g_application_platform_remote_invoke_action (application, name, timestamp);
 557       return;
 558     }
 559
 560   action = g_hash_table_lookup (priv->actions, name);
 561   g_return_if_fail (action != NULL);
 562   if (!action->enabled)
 563     return;
 564
 565   g_signal_emit (application, application_signals[ACTION],
 566                  g_quark_from_string (name),
 567                  name,
 568                  timestamp);
 569 }
 570
 571 /**
 572  * g_application_list_actions:
 573  * @application: a #GApplication
 574  *
 575  * Retrieves the list of action names currently exported by @application.
 576  *
 577  * It is an error to call this function if @application is a proxy for
 578  * a remote application.
 579  *
 580  * Return value: (transfer full): a newly allocation, %NULL-terminated array
 581  *   of strings containing action names; use g_strfreev() to free the
 582  *   resources used by the returned array
 583  *
 584  * Since: 2.26
 585  */
 586 gchar **
 587 g_application_list_actions (GApplication *application)
 588 {
 589   GApplicationPrivate *priv;
 590   GHashTableIter iter;
 591   gpointer key;
 592   gchar **retval;
 593   gint i;
 594
 595   g_return_val_if_fail (G_IS_APPLICATION (application), NULL);
 596   g_return_val_if_fail (!application->priv->is_remote, NULL);
 597
 598   priv = application->priv;
 599
 600   retval = g_new (gchar*, g_hash_table_size (priv->actions));
 601
 602   i = 0;
 603   g_hash_table_iter_init (&iter, priv->actions);
 604   while (g_hash_table_iter_next (&iter, &key, NULL))
 605     retval[i++] = g_strdup (key);
 606
 607   retval[i] = NULL;
 608
 609   return retval;
 610 }
 611
 612 /**
 613  * g_application_set_action_enabled:
 614  * @application: a #GApplication
 615  * @name: the name of the application
 616  * @enabled: whether to enable or disable the action @name
 617  *
 618  * Sets whether the action @name inside @application should be enabled
 619  * or disabled.
 620  *
 621  * It is an error to call this function if @application is a proxy for
 622  * a remote application.
 623  *
 624  * Invoking a disabled action will not result in the #GApplication::action
 625  * signal being emitted.
 626  *
 627  * Since: 2.26
 628  */
 629 void
 630 g_application_set_action_enabled (GApplication *application,
 631                                   const gchar  *name,
 632                                   gboolean      enabled)
 633 {
 634   GApplicationAction *action;
 635
 636   g_return_if_fail (G_IS_APPLICATION (application));
 637   g_return_if_fail (name != NULL);
 638   g_return_if_fail (!application->priv->is_remote);
 639
 640   enabled = !!enabled;
 641
 642   action = g_hash_table_lookup (application->priv->actions, name);
 643   g_return_if_fail (action != NULL);
 644   if (action->enabled == enabled)
 645     return;
 646
 647   action->enabled = enabled;
 648
 649   queue_actions_change_notification (application);
 650 }
 651
 652
 653 /**
 654  * g_application_get_action_description:
 655  * @application: a #GApplication
 656  * @name: Action name
 657  *
 658  * Gets the description of the action @name.
 659  *
 660  * It is an error to call this function if @application is a proxy for
 661  * a remote application.
 662  *
 663  * Returns: Description for the given action named @name
 664  *
 665  * Since: 2.26
 666  */
 667 G_CONST_RETURN gchar *
 668 g_application_get_action_description (GApplication *application,
 669                                       const gchar  *name)
 670 {
 671   GApplicationAction *action;
 672
 673   g_return_val_if_fail (G_IS_APPLICATION (application), NULL);
 674   g_return_val_if_fail (name != NULL, NULL);
 675   g_return_val_if_fail (!application->priv->is_remote, NULL);
 676
 677   action = g_hash_table_lookup (application->priv->actions, name);
 678   g_return_val_if_fail (action != NULL, NULL);
 679
 680   return action->description;
 681 }
 682
 683
 684 /**
 685  * g_application_get_action_enabled:
 686  * @application: a #GApplication
 687  * @name: the name of the action
 688  *
 689  * Retrieves whether the action @name is enabled or not.
 690  *
 691  * See g_application_set_action_enabled().
 692  *
 693  * It is an error to call this function if @application is a proxy for
 694  * a remote application.
 695  *
 696  * Return value: %TRUE if the action was enabled, and %FALSE otherwise
 697  *
 698  * Since: 2.26
 699  */
 700 gboolean
 701 g_application_get_action_enabled (GApplication *application,
 702                                   const gchar  *name)
 703 {
 704   GApplicationAction *action;
 705
 706   g_return_val_if_fail (G_IS_APPLICATION (application), FALSE);
 707   g_return_val_if_fail (name != NULL, FALSE);
 708   g_return_val_if_fail (!application->priv->is_remote, FALSE);
 709
 710   action = g_hash_table_lookup (application->priv->actions, name);
 711   g_return_val_if_fail (action != NULL, FALSE);
 712
 713   return action->enabled;
 714 }
 715
 716 /**
 717  * g_application_run:
 718  * @application: a #GApplication
 719  *
 720  * Starts the application.
 721  *
 722  * The default implementation of this virtual function will simply run
 723  * a main loop.
 724  *
 725  * It is an error to call this function if @application is a proxy for
 726  * a remote application.
 727  *
 728  * Since: 2.26
 729  */
 730 void
 731 g_application_run (GApplication *application)
 732 {
 733   g_return_if_fail (G_IS_APPLICATION (application));
 734   g_return_if_fail (!application->priv->is_remote);
 735
 736   G_APPLICATION_GET_CLASS (application)->run (application);
 737 }
 738
 739 /**
 740  * g_application_quit:
 741  * @application: a #GApplication
 742  * @timestamp: Platform-specific event timestamp, may be 0 for default
 743  *
 744  * Request that the application quits.
 745  *
 746  * This function has different behavior depending on whether @application
 747  * is acting as a proxy for another process.  In the normal case where
 748  * the current process is hosting the application, the default
 749  * implementation will quit the main loop created by g_application_run().
 750  *
 751  * If @application is a proxy, then the remote process will be asked
 752  * to quit.
 753  *
 754  * Returns: %TRUE if the application accepted the request, %FALSE otherwise
 755  *
 756  * Since: 2.26
 757  */
 758 gboolean
 759 g_application_quit (GApplication *application,
 760                     guint         timestamp)
 761 {
 762   gboolean retval = FALSE;
 763
 764   g_return_val_if_fail (G_IS_APPLICATION (application), FALSE);
 765
 766   if (application->priv->is_remote)
 767     {
 768        _g_application_platform_remote_quit (application, timestamp);
 769        retval = TRUE;
 770     }
 771   else
 772     g_signal_emit (application, application_signals[QUIT], 0, timestamp, &retval);
 773
 774   return retval;
 775 }
 776
 777 /**
 778  * g_application_get_instance:
 779  *
 780  * In the normal case where there is exactly one #GApplication instance
 781  * in this process, return that instance.  If there are multiple, the
 782  * first one created will be returned.  Otherwise, return %NULL.
 783  *
 784  * Returns: (transfer none): The primary instance of #GApplication,
 785  *   or %NULL if none is set
 786  *
 787  * Since: 2.26
 788  */
 789 GApplication *
 790 g_application_get_instance (void)
 791 {
 792   return primary_application;
 793 }
 794
 795 /**
 796  * g_application_get_id:
 797  * @application: a #GApplication
 798  *
 799  * Retrieves the platform-specific identifier for the #GApplication.
 800  *
 801  * Return value: The platform-specific identifier. The returned string
 802  *   is owned by the #GApplication instance and it should never be
 803  *   modified or freed
 804  *
 805  * Since: 2.26
 806  */
 807 G_CONST_RETURN gchar *
 808 g_application_get_id (GApplication *application)
 809 {
 810   g_return_val_if_fail (G_IS_APPLICATION (application), NULL);
 811
 812   return application->priv->appid;
 813 }
 814
 815 /**
 816  * g_application_is_remote:
 817  * @application: a #GApplication
 818  *
 819  * Returns: %TRUE if this object represents a proxy for a remote application.
 820  */
 821 gboolean
 822 g_application_is_remote (GApplication *application)
 823 {
 824   g_return_val_if_fail (G_IS_APPLICATION (application), FALSE);
 825
 826   return application->priv->is_remote;
 827 }
 828
 829 static void
 830 g_application_init (GApplication *app)
 831 {
 832   app->priv = G_TYPE_INSTANCE_GET_PRIVATE (app,
 833                                            G_TYPE_APPLICATION,
 834                                            GApplicationPrivate);
 835
 836   app->priv->actions = g_hash_table_new_full (g_str_hash, g_str_equal,
 837                                               NULL,
 838                                               g_application_action_free);
 839   app->priv->default_quit = TRUE;
 840   app->priv->is_remote = TRUE;
 841 }
 842
 843 static void
 844 g_application_get_property (GObject    *object,
 845                             guint       prop_id,
 846                             GValue     *value,
 847                             GParamSpec *pspec)
 848 {
 849   GApplication *app = G_APPLICATION (object);
 850
 851   switch (prop_id)
 852     {
 853     case PROP_APPLICATION_ID:
 854       g_value_set_string (value, g_application_get_id (app));
 855       break;
 856
 857     case PROP_DEFAULT_QUIT:
 858       g_value_set_boolean (value, app->priv->default_quit);
 859       break;
 860
 861     case PROP_IS_REMOTE:
 862       g_value_set_boolean (value, g_application_is_remote (app));
 863       break;
 864
 865     default:
 866       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 867     }
 868 }
 869
 870 static void
 871 g_application_set_property (GObject      *object,
 872                             guint         prop_id,
 873                             const GValue *value,
 874                             GParamSpec   *pspec)
 875 {
 876   GApplication *app = G_APPLICATION (object);
 877
 878   switch (prop_id)
 879     {
 880     case PROP_APPLICATION_ID:
 881       g_return_if_fail (_g_application_validate_id (g_value_get_string (value)));
 882       app->priv->appid = g_value_dup_string (value);
 883       break;
 884
 885     case PROP_DEFAULT_QUIT:
 886       app->priv->default_quit = g_value_get_boolean (value);
 887       break;
 888
 889     default:
 890       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 891     }
 892 }
 893
 894 static GObject*
 895 g_application_constructor (GType                  type,
 896                            guint                  n_construct_properties,
 897                            GObjectConstructParam *construct_params)
 898 {
 899   GApplication *app;
 900   GObject *object;
 901   const char *appid = NULL;
 902   guint i;
 903
 904   for (i = 0; i < n_construct_properties; i++)
 905     {
 906       GObjectConstructParam *param = &construct_params[i];
 907       if (strcmp (param->pspec->name, "application-id") == 0)
 908         appid = g_value_get_string (param->value);
 909     }
 910
 911   g_return_val_if_fail (appid != NULL, NULL);
 912
 913   app = application_for_appid (appid);
 914   if (app != NULL)
 915     return g_object_ref (app);
 916
 917   object = (* G_OBJECT_CLASS (g_application_parent_class)->constructor) (type,
 918                                                                          n_construct_properties,
 919                                                                          construct_params);
 920   app = G_APPLICATION (object);
 921
 922   if (primary_application == NULL)
 923     primary_application = app;
 924   g_hash_table_insert (instances_for_appid, g_strdup (appid), app);
 925
 926   return object;
 927 }
 928
 929 static void
 930 g_application_finalize (GObject *object)
 931 {
 932   GApplication *app = G_APPLICATION (object);
 933
 934   g_free (app->priv->appid);
 935   if (app->priv->actions)
 936     g_hash_table_unref (app->priv->actions);
 937   if (app->priv->actions_changed_id)
 938     g_source_remove (app->priv->actions_changed_id);
 939   if (app->priv->mainloop)
 940     g_main_loop_unref (app->priv->mainloop);
 941
 942 #ifdef G_OS_UNIX
 943   g_free (app->priv->dbus_path);
 944   if (app->priv->session_bus)
 945     g_object_unref (app->priv->session_bus);
 946 #endif
 947
 948   G_OBJECT_CLASS (g_application_parent_class)->finalize (object);
 949 }
 950
 951 static void
 952 g_application_class_init (GApplicationClass *klass)
 953 {
 954   GObjectClass *gobject_class G_GNUC_UNUSED = G_OBJECT_CLASS (klass);
 955
 956   g_type_class_add_private (klass, sizeof (GApplicationPrivate));
 957
 958   gobject_class->constructor = g_application_constructor;
 959   gobject_class->set_property = g_application_set_property;
 960   gobject_class->get_property = g_application_get_property;
 961
 962   gobject_class->finalize = g_application_finalize;
 963
 964   klass->run = g_application_default_run;
 965   klass->quit = g_application_default_quit;
 966
 967   /**
 968    * GApplication::quit:
 969    * @application: the object on which the signal is emitted
 970    * @timestamp: Platform-specific event timestamp, may be 0 for default
 971    *
 972    * This signal is emitted when the Quit action is invoked on the
 973    * application.
 974    *
 975    * The default handler for this signal exits the mainloop of the
 976    * application.
 977    *
 978    * Returns: %TRUE if the signal has been handled, %FALSE to continue
 979    *   signal emission
 980    */
 981   application_signals[QUIT] =
 982     g_signal_new (g_intern_static_string ("quit"),
 983                   G_OBJECT_CLASS_TYPE (klass),
 984                   G_SIGNAL_RUN_LAST,
 985                   G_STRUCT_OFFSET (GApplicationClass, quit),
 986                   g_signal_accumulator_true_handled, NULL,
 987                   _gio_marshal_BOOLEAN__UINT,
 988                   G_TYPE_BOOLEAN, 1,
 989                   G_TYPE_UINT);
 990
 991   /**
 992    * GApplication::action:
 993    * @application: the object on which the signal is emitted
 994    * @name: The name of the activated action
 995    * @timestamp: Platform-specific event timestamp, may be 0 for default
 996    *
 997    * This signal is emitted when an action is activated. The action name
 998    * is passed as the first argument, but also as signal detail, so it
 999    * is possible to connect to this signal for individual actions.
1000    *
1001    * The signal is never emitted for disabled actions.
1002    */
1003   application_signals[ACTION] =
1004     g_signal_new (g_intern_static_string ("action"),
1005                   G_OBJECT_CLASS_TYPE (klass),
1006                   G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_DETAILED,
1007                   G_STRUCT_OFFSET (GApplicationClass, action),
1008                   NULL, NULL,
1009                   _gio_marshal_VOID__STRING_UINT,
1010                   G_TYPE_NONE, 2,
1011                   G_TYPE_STRING,
1012                   G_TYPE_UINT);
1013
1014    /**
1015    * GApplication::prepare-activation:
1016    * @application: the object on which the signal is emitted
1017    * @arguments: A #GVariant with the signature "aay"
1018    * @platform_data: A #GVariant with the signature "a{sv}"
1019    *
1020    * This signal is emitted when a non-primary process for a given
1021    * application is invoked while your application is running; for
1022    * example, when a file browser launches your program to open a
1023    * file.  The raw operating system arguments are passed in the
1024    * @arguments variant.  Additional platform-dependent data is
1025    * stored in @platform_data.
1026    */
1027   application_signals[PREPARE_ACTIVATION] =
1028     g_signal_new (g_intern_static_string ("prepare-activation"),
1029                   G_OBJECT_CLASS_TYPE (klass),
1030                   G_SIGNAL_RUN_LAST,
1031                   G_STRUCT_OFFSET (GApplicationClass, prepare_activation),
1032                   NULL, NULL,
1033                   _gio_marshal_VOID__BOXED_BOXED,
1034                   G_TYPE_NONE, 2,
1035                   G_TYPE_VARIANT,
1036                   G_TYPE_VARIANT);
1037
1038    /**
1039    * GApplication:application-id:
1040    *
1041    * The unique identifier for this application.  See the documentation for
1042    * #GApplication for more information about this property.
1043    *
1044    */
1045   g_object_class_install_property (gobject_class,
1046                                    PROP_APPLICATION_ID,
1047                                    g_param_spec_string ("application-id",
1048                                                         P_("Application ID"),
1049                                                         P_("Identifier for this application"),
1050                                                         NULL,
1051                                                         G_PARAM_READWRITE |
1052                                                         G_PARAM_CONSTRUCT_ONLY |
1053                                                         G_PARAM_STATIC_STRINGS));
1054
1055   /**
1056    * GApplication:default-quit:
1057    *
1058    * By default, if a different process is running this application, the
1059    * process will be exited.  Set this property to %FALSE to allow custom
1060    * interaction with the remote process.
1061    *
1062    */
1063   g_object_class_install_property (gobject_class,
1064                                    PROP_DEFAULT_QUIT,
1065                                    g_param_spec_boolean ("default-quit",
1066                                                          P_("Default Quit"),
1067                                                          P_("Exit the process by default"),
1068                                                          TRUE,
1069                                                          G_PARAM_READWRITE |
1070                                                          G_PARAM_CONSTRUCT_ONLY |
1071                                                          G_PARAM_STATIC_STRINGS));
1072
1073
1074   /**
1075    * GApplication:is-remote:
1076    *
1077    * This property is %TRUE if this application instance represents a proxy
1078    * to the instance of this application in another process.
1079    *
1080    */
1081   g_object_class_install_property (gobject_class,
1082                                    PROP_IS_REMOTE,
1083                                    g_param_spec_boolean ("is-remote",
1084                                                          P_("Is Remote"),
1085                                                          P_("Whether this application is a proxy for another process"),
1086                                                          TRUE,
1087                                                          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
1088 }
1089
1090 #define __G_APPLICATION_C__
1091 #include "gioaliasdef.c"