gio/gappinfo.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright (C) 2006-2007 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, see <http://www.gnu.org/licenses/>.
  17  *
  18  * Author: Alexander Larsson <alexl@redhat.com>
  19  */
  20
  21 #include "config.h"
  22
  23 #include "gappinfo.h"
  24 #include "gappinfoprivate.h"
  25 #include "gcontextspecificgroup.h"
  26
  27 #include "glibintl.h"
  28 #include <gioerror.h>
  29 #include <gfile.h>
  30
  31
  32 /**
  33  * SECTION:gappinfo
  34  * @short_description: Application information and launch contexts
  35  * @include: gio/gio.h
  36  * @see_also: #GAppInfoMonitor
  37  *
  38  * #GAppInfo and #GAppLaunchContext are used for describing and launching
  39  * applications installed on the system.
  40  *
  41  * As of GLib 2.20, URIs will always be converted to POSIX paths
  42  * (using g_file_get_path()) when using g_app_info_launch() even if
  43  * the application requested an URI and not a POSIX path. For example
  44  * for an desktop-file based application with Exec key `totem
  45  * %U` and a single URI, `sftp://foo/file.avi`, then
  46  * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
  47  * only work if a set of suitable GIO extensions (such as gvfs 2.26
  48  * compiled with FUSE support), is available and operational; if this
  49  * is not the case, the URI will be passed unmodified to the application.
  50  * Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX
  51  * path (in gvfs there's no FUSE mount for it); such URIs will be
  52  * passed unmodified to the application.
  53  *
  54  * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
  55  * back to the GIO URI in the #GFile constructors (since gvfs
  56  * implements the #GVfs extension point). As such, if the application
  57  * needs to examine the URI, it needs to use g_file_get_uri() or
  58  * similar on #GFile. In other words, an application cannot assume
  59  * that the URI passed to e.g. g_file_new_for_commandline_arg() is
  60  * equal to the result of g_file_get_uri(). The following snippet
  61  * illustrates this:
  62  *
  63  * |[
  64  * GFile *f;
  65  * char *uri;
  66  *
  67  * file = g_file_new_for_commandline_arg (uri_from_commandline);
  68  *
  69  * uri = g_file_get_uri (file);
  70  * strcmp (uri, uri_from_commandline) == 0;
  71  * g_free (uri);
  72  *
  73  * if (g_file_has_uri_scheme (file, "cdda"))
  74  *   {
  75  *     // do something special with uri
  76  *   }
  77  * g_object_unref (file);
  78  * ]|
  79  *
  80  * This code will work when both `cdda://sr0/Track 1.wav` and
  81  * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the
  82  * application. It should be noted that it's generally not safe
  83  * for applications to rely on the format of a particular URIs.
  84  * Different launcher applications (e.g. file managers) may have
  85  * different ideas of what a given URI means.
  86  */
  87
  88 typedef GAppInfoIface GAppInfoInterface;
  89 G_DEFINE_INTERFACE (GAppInfo, g_app_info, G_TYPE_OBJECT)
  90
  91 static void
  92 g_app_info_default_init (GAppInfoInterface *iface)
  93 {
  94 }
  95
  96
  97 /**
  98  * g_app_info_dup:
  99  * @appinfo: a #GAppInfo.
 100  *
 101  * Creates a duplicate of a #GAppInfo.
 102  *
 103  * Returns: (transfer full): a duplicate of @appinfo.
 104  **/
 105 GAppInfo *
 106 g_app_info_dup (GAppInfo *appinfo)
 107 {
 108   GAppInfoIface *iface;
 109
 110   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 111
 112   iface = G_APP_INFO_GET_IFACE (appinfo);
 113
 114   return (* iface->dup) (appinfo);
 115 }
 116
 117 /**
 118  * g_app_info_equal:
 119  * @appinfo1: the first #GAppInfo.
 120  * @appinfo2: the second #GAppInfo.
 121  *
 122  * Checks if two #GAppInfos are equal.
 123  *
 124  * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
 125  **/
 126 gboolean
 127 g_app_info_equal (GAppInfo *appinfo1,
 128                   GAppInfo *appinfo2)
 129 {
 130   GAppInfoIface *iface;
 131
 132   g_return_val_if_fail (G_IS_APP_INFO (appinfo1), FALSE);
 133   g_return_val_if_fail (G_IS_APP_INFO (appinfo2), FALSE);
 134
 135   if (G_TYPE_FROM_INSTANCE (appinfo1) != G_TYPE_FROM_INSTANCE (appinfo2))
 136     return FALSE;
 137
 138   iface = G_APP_INFO_GET_IFACE (appinfo1);
 139
 140   return (* iface->equal) (appinfo1, appinfo2);
 141 }
 142
 143 /**
 144  * g_app_info_get_id:
 145  * @appinfo: a #GAppInfo.
 146  *
 147  * Gets the ID of an application. An id is a string that
 148  * identifies the application. The exact format of the id is
 149  * platform dependent. For instance, on Unix this is the
 150  * desktop file id from the xdg menu specification.
 151  *
 152  * Note that the returned ID may be %NULL, depending on how
 153  * the @appinfo has been constructed.
 154  *
 155  * Returns: a string containing the application's ID.
 156  **/
 157 const char *
 158 g_app_info_get_id (GAppInfo *appinfo)
 159 {
 160   GAppInfoIface *iface;
 161
 162   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 163
 164   iface = G_APP_INFO_GET_IFACE (appinfo);
 165
 166   return (* iface->get_id) (appinfo);
 167 }
 168
 169 /**
 170  * g_app_info_get_name:
 171  * @appinfo: a #GAppInfo.
 172  *
 173  * Gets the installed name of the application.
 174  *
 175  * Returns: the name of the application for @appinfo.
 176  **/
 177 const char *
 178 g_app_info_get_name (GAppInfo *appinfo)
 179 {
 180   GAppInfoIface *iface;
 181
 182   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 183
 184   iface = G_APP_INFO_GET_IFACE (appinfo);
 185
 186   return (* iface->get_name) (appinfo);
 187 }
 188
 189 /**
 190  * g_app_info_get_display_name:
 191  * @appinfo: a #GAppInfo.
 192  *
 193  * Gets the display name of the application. The display name is often more
 194  * descriptive to the user than the name itself.
 195  *
 196  * Returns: the display name of the application for @appinfo, or the name if
 197  * no display name is available.
 198  *
 199  * Since: 2.24
 200  **/
 201 const char *
 202 g_app_info_get_display_name (GAppInfo *appinfo)
 203 {
 204   GAppInfoIface *iface;
 205
 206   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 207
 208   iface = G_APP_INFO_GET_IFACE (appinfo);
 209
 210   if (iface->get_display_name == NULL)
 211     return (* iface->get_name) (appinfo);
 212
 213   return (* iface->get_display_name) (appinfo);
 214 }
 215
 216 /**
 217  * g_app_info_get_description:
 218  * @appinfo: a #GAppInfo.
 219  *
 220  * Gets a human-readable description of an installed application.
 221  *
 222  * Returns: a string containing a description of the
 223  * application @appinfo, or %NULL if none.
 224  **/
 225 const char *
 226 g_app_info_get_description (GAppInfo *appinfo)
 227 {
 228   GAppInfoIface *iface;
 229
 230   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 231
 232   iface = G_APP_INFO_GET_IFACE (appinfo);
 233
 234   return (* iface->get_description) (appinfo);
 235 }
 236
 237 /**
 238  * g_app_info_get_executable:
 239  * @appinfo: a #GAppInfo
 240  *
 241  * Gets the executable's name for the installed application.
 242  *
 243  * Returns: a string containing the @appinfo's application
 244  * binaries name
 245  **/
 246 const char *
 247 g_app_info_get_executable (GAppInfo *appinfo)
 248 {
 249   GAppInfoIface *iface;
 250
 251   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 252
 253   iface = G_APP_INFO_GET_IFACE (appinfo);
 254
 255   return (* iface->get_executable) (appinfo);
 256 }
 257
 258
 259 /**
 260  * g_app_info_get_commandline:
 261  * @appinfo: a #GAppInfo
 262  *
 263  * Gets the commandline with which the application will be
 264  * started.
 265  *
 266  * Returns: a string containing the @appinfo's commandline,
 267  *     or %NULL if this information is not available
 268  *
 269  * Since: 2.20
 270  **/
 271 const char *
 272 g_app_info_get_commandline (GAppInfo *appinfo)
 273 {
 274   GAppInfoIface *iface;
 275
 276   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 277
 278   iface = G_APP_INFO_GET_IFACE (appinfo);
 279
 280   if (iface->get_commandline)
 281     return (* iface->get_commandline) (appinfo);
 282
 283   return NULL;
 284 }
 285
 286 /**
 287  * g_app_info_set_as_default_for_type:
 288  * @appinfo: a #GAppInfo.
 289  * @content_type: the content type.
 290  * @error: a #GError.
 291  *
 292  * Sets the application as the default handler for a given type.
 293  *
 294  * Returns: %TRUE on success, %FALSE on error.
 295  **/
 296 gboolean
 297 g_app_info_set_as_default_for_type (GAppInfo    *appinfo,
 298                                     const char  *content_type,
 299                                     GError     **error)
 300 {
 301   GAppInfoIface *iface;
 302
 303   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 304   g_return_val_if_fail (content_type != NULL, FALSE);
 305
 306   iface = G_APP_INFO_GET_IFACE (appinfo);
 307
 308   return (* iface->set_as_default_for_type) (appinfo, content_type, error);
 309 }
 310
 311 /**
 312  * g_app_info_set_as_last_used_for_type:
 313  * @appinfo: a #GAppInfo.
 314  * @content_type: the content type.
 315  * @error: a #GError.
 316  *
 317  * Sets the application as the last used application for a given type.
 318  * This will make the application appear as first in the list returned
 319  * by g_app_info_get_recommended_for_type(), regardless of the default
 320  * application for that content type.
 321  *
 322  * Returns: %TRUE on success, %FALSE on error.
 323  **/
 324 gboolean
 325 g_app_info_set_as_last_used_for_type (GAppInfo    *appinfo,
 326                                       const char  *content_type,
 327                                       GError     **error)
 328 {
 329   GAppInfoIface *iface;
 330
 331   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 332   g_return_val_if_fail (content_type != NULL, FALSE);
 333
 334   iface = G_APP_INFO_GET_IFACE (appinfo);
 335
 336   return (* iface->set_as_last_used_for_type) (appinfo, content_type, error);
 337 }
 338
 339 /**
 340  * g_app_info_set_as_default_for_extension:
 341  * @appinfo: a #GAppInfo.
 342  * @extension: a string containing the file extension (without the dot).
 343  * @error: a #GError.
 344  *
 345  * Sets the application as the default handler for the given file extension.
 346  *
 347  * Returns: %TRUE on success, %FALSE on error.
 348  **/
 349 gboolean
 350 g_app_info_set_as_default_for_extension (GAppInfo    *appinfo,
 351                                          const char  *extension,
 352                                          GError     **error)
 353 {
 354   GAppInfoIface *iface;
 355
 356   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 357   g_return_val_if_fail (extension != NULL, FALSE);
 358
 359   iface = G_APP_INFO_GET_IFACE (appinfo);
 360
 361   if (iface->set_as_default_for_extension)
 362     return (* iface->set_as_default_for_extension) (appinfo, extension, error);
 363
 364   g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
 365                        "g_app_info_set_as_default_for_extension not supported yet");
 366   return FALSE;
 367 }
 368
 369
 370 /**
 371  * g_app_info_add_supports_type:
 372  * @appinfo: a #GAppInfo.
 373  * @content_type: a string.
 374  * @error: a #GError.
 375  *
 376  * Adds a content type to the application information to indicate the
 377  * application is capable of opening files with the given content type.
 378  *
 379  * Returns: %TRUE on success, %FALSE on error.
 380  **/
 381 gboolean
 382 g_app_info_add_supports_type (GAppInfo    *appinfo,
 383                               const char  *content_type,
 384                               GError     **error)
 385 {
 386   GAppInfoIface *iface;
 387
 388   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 389   g_return_val_if_fail (content_type != NULL, FALSE);
 390
 391   iface = G_APP_INFO_GET_IFACE (appinfo);
 392
 393   if (iface->add_supports_type)
 394     return (* iface->add_supports_type) (appinfo, content_type, error);
 395
 396   g_set_error_literal (error, G_IO_ERROR,
 397                        G_IO_ERROR_NOT_SUPPORTED,
 398                        "g_app_info_add_supports_type not supported yet");
 399
 400   return FALSE;
 401 }
 402
 403
 404 /**
 405  * g_app_info_can_remove_supports_type:
 406  * @appinfo: a #GAppInfo.
 407  *
 408  * Checks if a supported content type can be removed from an application.
 409  *
 410  * Returns: %TRUE if it is possible to remove supported
 411  *     content types from a given @appinfo, %FALSE if not.
 412  **/
 413 gboolean
 414 g_app_info_can_remove_supports_type (GAppInfo *appinfo)
 415 {
 416   GAppInfoIface *iface;
 417
 418   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 419
 420   iface = G_APP_INFO_GET_IFACE (appinfo);
 421
 422   if (iface->can_remove_supports_type)
 423     return (* iface->can_remove_supports_type) (appinfo);
 424
 425   return FALSE;
 426 }
 427
 428
 429 /**
 430  * g_app_info_remove_supports_type:
 431  * @appinfo: a #GAppInfo.
 432  * @content_type: a string.
 433  * @error: a #GError.
 434  *
 435  * Removes a supported type from an application, if possible.
 436  *
 437  * Returns: %TRUE on success, %FALSE on error.
 438  **/
 439 gboolean
 440 g_app_info_remove_supports_type (GAppInfo    *appinfo,
 441                                  const char  *content_type,
 442                                  GError     **error)
 443 {
 444   GAppInfoIface *iface;
 445
 446   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 447   g_return_val_if_fail (content_type != NULL, FALSE);
 448
 449   iface = G_APP_INFO_GET_IFACE (appinfo);
 450
 451   if (iface->remove_supports_type)
 452     return (* iface->remove_supports_type) (appinfo, content_type, error);
 453
 454   g_set_error_literal (error, G_IO_ERROR,
 455                        G_IO_ERROR_NOT_SUPPORTED,
 456                        "g_app_info_remove_supports_type not supported yet");
 457
 458   return FALSE;
 459 }
 460
 461 /**
 462  * g_app_info_get_supported_types:
 463  * @appinfo: a #GAppInfo that can handle files
 464  *
 465  * Retrieves the list of content types that @app_info claims to support.
 466  * If this information is not provided by the environment, this function
 467  * will return %NULL.
 468  * This function does not take in consideration associations added with
 469  * g_app_info_add_supports_type(), but only those exported directly by
 470  * the application.
 471  *
 472  * Returns: (transfer none) (array zero-terminated=1) (element-type utf8):
 473  *    a list of content types.
 474  *
 475  * Since: 2.34
 476  */
 477 const char **
 478 g_app_info_get_supported_types (GAppInfo *appinfo)
 479 {
 480   GAppInfoIface *iface;
 481
 482   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 483
 484   iface = G_APP_INFO_GET_IFACE (appinfo);
 485
 486   if (iface->get_supported_types)
 487     return iface->get_supported_types (appinfo);
 488   else
 489     return NULL;
 490 }
 491
 492
 493 /**
 494  * g_app_info_get_icon:
 495  * @appinfo: a #GAppInfo.
 496  *
 497  * Gets the icon for the application.
 498  *
 499  * Returns: (transfer none): the default #GIcon for @appinfo or %NULL
 500  * if there is no default icon.
 501  **/
 502 GIcon *
 503 g_app_info_get_icon (GAppInfo *appinfo)
 504 {
 505   GAppInfoIface *iface;
 506
 507   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 508
 509   iface = G_APP_INFO_GET_IFACE (appinfo);
 510
 511   return (* iface->get_icon) (appinfo);
 512 }
 513
 514
 515 /**
 516  * g_app_info_launch:
 517  * @appinfo: a #GAppInfo
 518  * @files: (allow-none) (element-type GFile): a #GList of #GFile objects
 519  * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
 520  * @error: a #GError
 521  *
 522  * Launches the application. Passes @files to the launched application
 523  * as arguments, using the optional @launch_context to get information
 524  * about the details of the launcher (like what screen it is on).
 525  * On error, @error will be set accordingly.
 526  *
 527  * To launch the application without arguments pass a %NULL @files list.
 528  *
 529  * Note that even if the launch is successful the application launched
 530  * can fail to start if it runs into problems during startup. There is
 531  * no way to detect this.
 532  *
 533  * Some URIs can be changed when passed through a GFile (for instance
 534  * unsupported URIs with strange formats like mailto:), so if you have
 535  * a textual URI you want to pass in as argument, consider using
 536  * g_app_info_launch_uris() instead.
 537  *
 538  * The launched application inherits the environment of the launching
 539  * process, but it can be modified with g_app_launch_context_setenv()
 540  * and g_app_launch_context_unsetenv().
 541  *
 542  * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
 543  * environment variable with the path of the launched desktop file and
 544  * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
 545  * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
 546  * should it be inherited by further processes. The `DISPLAY` and
 547  * `DESKTOP_STARTUP_ID` environment variables are also set, based
 548  * on information provided in @launch_context.
 549  *
 550  * Returns: %TRUE on successful launch, %FALSE otherwise.
 551  **/
 552 gboolean
 553 g_app_info_launch (GAppInfo           *appinfo,
 554                    GList              *files,
 555                    GAppLaunchContext  *launch_context,
 556                    GError            **error)
 557 {
 558   GAppInfoIface *iface;
 559
 560   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 561
 562   iface = G_APP_INFO_GET_IFACE (appinfo);
 563
 564   return (* iface->launch) (appinfo, files, launch_context, error);
 565 }
 566
 567
 568 /**
 569  * g_app_info_supports_uris:
 570  * @appinfo: a #GAppInfo.
 571  *
 572  * Checks if the application supports reading files and directories from URIs.
 573  *
 574  * Returns: %TRUE if the @appinfo supports URIs.
 575  **/
 576 gboolean
 577 g_app_info_supports_uris (GAppInfo *appinfo)
 578 {
 579   GAppInfoIface *iface;
 580
 581   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 582
 583   iface = G_APP_INFO_GET_IFACE (appinfo);
 584
 585   return (* iface->supports_uris) (appinfo);
 586 }
 587
 588
 589 /**
 590  * g_app_info_supports_files:
 591  * @appinfo: a #GAppInfo.
 592  *
 593  * Checks if the application accepts files as arguments.
 594  *
 595  * Returns: %TRUE if the @appinfo supports files.
 596  **/
 597 gboolean
 598 g_app_info_supports_files (GAppInfo *appinfo)
 599 {
 600   GAppInfoIface *iface;
 601
 602   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 603
 604   iface = G_APP_INFO_GET_IFACE (appinfo);
 605
 606   return (* iface->supports_files) (appinfo);
 607 }
 608
 609
 610 /**
 611  * g_app_info_launch_uris:
 612  * @appinfo: a #GAppInfo
 613  * @uris: (allow-none) (element-type utf8): a #GList containing URIs to launch.
 614  * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
 615  * @error: a #GError
 616  *
 617  * Launches the application. This passes the @uris to the launched application
 618  * as arguments, using the optional @launch_context to get information
 619  * about the details of the launcher (like what screen it is on).
 620  * On error, @error will be set accordingly.
 621  *
 622  * To launch the application without arguments pass a %NULL @uris list.
 623  *
 624  * Note that even if the launch is successful the application launched
 625  * can fail to start if it runs into problems during startup. There is
 626  * no way to detect this.
 627  *
 628  * Returns: %TRUE on successful launch, %FALSE otherwise.
 629  **/
 630 gboolean
 631 g_app_info_launch_uris (GAppInfo           *appinfo,
 632                         GList              *uris,
 633                         GAppLaunchContext  *launch_context,
 634                         GError            **error)
 635 {
 636   GAppInfoIface *iface;
 637
 638   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 639
 640   iface = G_APP_INFO_GET_IFACE (appinfo);
 641
 642   return (* iface->launch_uris) (appinfo, uris, launch_context, error);
 643 }
 644
 645
 646 /**
 647  * g_app_info_should_show:
 648  * @appinfo: a #GAppInfo.
 649  *
 650  * Checks if the application info should be shown in menus that
 651  * list available applications.
 652  *
 653  * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
 654  **/
 655 gboolean
 656 g_app_info_should_show (GAppInfo *appinfo)
 657 {
 658   GAppInfoIface *iface;
 659
 660   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 661
 662   iface = G_APP_INFO_GET_IFACE (appinfo);
 663
 664   return (* iface->should_show) (appinfo);
 665 }
 666
 667 /**
 668  * g_app_info_launch_default_for_uri:
 669  * @uri: the uri to show
 670  * @launch_context: (allow-none): an optional #GAppLaunchContext.
 671  * @error: a #GError.
 672  *
 673  * Utility function that launches the default application
 674  * registered to handle the specified uri. Synchronous I/O
 675  * is done on the uri to detect the type of the file if
 676  * required.
 677  *
 678  * Returns: %TRUE on success, %FALSE on error.
 679  **/
 680 gboolean
 681 g_app_info_launch_default_for_uri (const char         *uri,
 682                                    GAppLaunchContext  *launch_context,
 683                                    GError            **error)
 684 {
 685   char *uri_scheme;
 686   GAppInfo *app_info = NULL;
 687   GList l;
 688   gboolean res;
 689
 690   /* g_file_query_default_handler() calls
 691    * g_app_info_get_default_for_uri_scheme() too, but we have to do it
 692    * here anyway in case GFile can't parse @uri correctly.
 693    */
 694   uri_scheme = g_uri_parse_scheme (uri);
 695   if (uri_scheme && uri_scheme[0] != '\0')
 696     app_info = g_app_info_get_default_for_uri_scheme (uri_scheme);
 697   g_free (uri_scheme);
 698
 699   if (!app_info)
 700     {
 701       GFile *file;
 702
 703       file = g_file_new_for_uri (uri);
 704       app_info = g_file_query_default_handler (file, NULL, error);
 705       g_object_unref (file);
 706       if (app_info == NULL)
 707         return FALSE;
 708
 709       /* We still use the original @uri rather than calling
 710        * g_file_get_uri(), because GFile might have modified the URI
 711        * in ways we don't want (eg, removing the fragment identifier
 712        * from a file: URI).
 713        */
 714     }
 715
 716   l.data = (char *)uri;
 717   l.next = l.prev = NULL;
 718   res = g_app_info_launch_uris (app_info, &l,
 719                                 launch_context, error);
 720
 721   g_object_unref (app_info);
 722
 723   return res;
 724 }
 725
 726 /**
 727  * g_app_info_can_delete:
 728  * @appinfo: a #GAppInfo
 729  *
 730  * Obtains the information whether the #GAppInfo can be deleted.
 731  * See g_app_info_delete().
 732  *
 733  * Returns: %TRUE if @appinfo can be deleted
 734  *
 735  * Since: 2.20
 736  */
 737 gboolean
 738 g_app_info_can_delete (GAppInfo *appinfo)
 739 {
 740   GAppInfoIface *iface;
 741
 742   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 743
 744   iface = G_APP_INFO_GET_IFACE (appinfo);
 745
 746   if (iface->can_delete)
 747     return (* iface->can_delete) (appinfo);
 748
 749   return FALSE;
 750 }
 751
 752
 753 /**
 754  * g_app_info_delete:
 755  * @appinfo: a #GAppInfo
 756  *
 757  * Tries to delete a #GAppInfo.
 758  *
 759  * On some platforms, there may be a difference between user-defined
 760  * #GAppInfos which can be deleted, and system-wide ones which cannot.
 761  * See g_app_info_can_delete().
 762  *
 763  * Virtual: do_delete
 764  * Returns: %TRUE if @appinfo has been deleted
 765  *
 766  * Since: 2.20
 767  */
 768 gboolean
 769 g_app_info_delete (GAppInfo *appinfo)
 770 {
 771   GAppInfoIface *iface;
 772
 773   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 774
 775   iface = G_APP_INFO_GET_IFACE (appinfo);
 776
 777   if (iface->do_delete)
 778     return (* iface->do_delete) (appinfo);
 779
 780   return FALSE;
 781 }
 782
 783
 784 enum {
 785   LAUNCH_FAILED,
 786   LAUNCHED,
 787   LAST_SIGNAL
 788 };
 789
 790 struct _GAppLaunchContextPrivate {
 791   char **envp;
 792 };
 793
 794 static guint signals[LAST_SIGNAL] = { 0 };
 795
 796 G_DEFINE_TYPE_WITH_PRIVATE (GAppLaunchContext, g_app_launch_context, G_TYPE_OBJECT)
 797
 798 /**
 799  * g_app_launch_context_new:
 800  *
 801  * Creates a new application launch context. This is not normally used,
 802  * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
 803  *
 804  * Returns: a #GAppLaunchContext.
 805  **/
 806 GAppLaunchContext *
 807 g_app_launch_context_new (void)
 808 {
 809   return g_object_new (G_TYPE_APP_LAUNCH_CONTEXT, NULL);
 810 }
 811
 812 static void
 813 g_app_launch_context_finalize (GObject *object)
 814 {
 815   GAppLaunchContext *context = G_APP_LAUNCH_CONTEXT (object);
 816
 817   g_strfreev (context->priv->envp);
 818
 819   G_OBJECT_CLASS (g_app_launch_context_parent_class)->finalize (object);
 820 }
 821
 822 static void
 823 g_app_launch_context_class_init (GAppLaunchContextClass *klass)
 824 {
 825   GObjectClass *object_class = G_OBJECT_CLASS (klass);
 826
 827   object_class->finalize = g_app_launch_context_finalize;
 828
 829   /**
 830    * GAppLaunchContext::launch-failed:
 831    * @context: the object emitting the signal
 832    * @startup_notify_id: the startup notification id for the failed launch
 833    *
 834    * The ::launch-failed signal is emitted when a #GAppInfo launch
 835    * fails. The startup notification id is provided, so that the launcher
 836    * can cancel the startup notification.
 837    *
 838    * Since: 2.36
 839    */
 840   signals[LAUNCH_FAILED] = g_signal_new (I_("launch-failed"),
 841                                          G_OBJECT_CLASS_TYPE (object_class),
 842                                          G_SIGNAL_RUN_LAST,
 843                                          G_STRUCT_OFFSET (GAppLaunchContextClass, launch_failed),
 844                                          NULL, NULL, NULL,
 845                                          G_TYPE_NONE, 1, G_TYPE_STRING);
 846
 847   /**
 848    * GAppLaunchContext::launched:
 849    * @context: the object emitting the signal
 850    * @info: the #GAppInfo that was just launched
 851    * @platform_data: additional platform-specific data for this launch
 852    *
 853    * The ::launched signal is emitted when a #GAppInfo is successfully
 854    * launched. The @platform_data is an GVariant dictionary mapping
 855    * strings to variants (ie a{sv}), which contains additional,
 856    * platform-specific data about this launch. On UNIX, at least the
 857    * "pid" and "startup-notification-id" keys will be present.
 858    *
 859    * Since: 2.36
 860    */
 861   signals[LAUNCHED] = g_signal_new (I_("launched"),
 862                                     G_OBJECT_CLASS_TYPE (object_class),
 863                                     G_SIGNAL_RUN_LAST,
 864                                     G_STRUCT_OFFSET (GAppLaunchContextClass, launched),
 865                                     NULL, NULL, NULL,
 866                                     G_TYPE_NONE, 2,
 867                                     G_TYPE_APP_INFO, G_TYPE_VARIANT);
 868 }
 869
 870 static void
 871 g_app_launch_context_init (GAppLaunchContext *context)
 872 {
 873   context->priv = g_app_launch_context_get_instance_private (context);
 874 }
 875
 876 /**
 877  * g_app_launch_context_setenv:
 878  * @context: a #GAppLaunchContext
 879  * @variable: the environment variable to set
 880  * @value: the value for to set the variable to.
 881  *
 882  * Arranges for @variable to be set to @value in the child's
 883  * environment when @context is used to launch an application.
 884  *
 885  * Since: 2.32
 886  */
 887 void
 888 g_app_launch_context_setenv (GAppLaunchContext *context,
 889                              const char        *variable,
 890                              const char        *value)
 891 {
 892   if (!context->priv->envp)
 893     context->priv->envp = g_get_environ ();
 894
 895   context->priv->envp =
 896     g_environ_setenv (context->priv->envp, variable, value, TRUE);
 897 }
 898
 899 /**
 900  * g_app_launch_context_unsetenv:
 901  * @context: a #GAppLaunchContext
 902  * @variable: the environment variable to remove
 903  *
 904  * Arranges for @variable to be unset in the child's environment
 905  * when @context is used to launch an application.
 906  *
 907  * Since: 2.32
 908  */
 909 void
 910 g_app_launch_context_unsetenv (GAppLaunchContext *context,
 911                                const char        *variable)
 912 {
 913   if (!context->priv->envp)
 914     context->priv->envp = g_get_environ ();
 915
 916   context->priv->envp =
 917     g_environ_unsetenv (context->priv->envp, variable);
 918 }
 919
 920 /**
 921  * g_app_launch_context_get_environment:
 922  * @context: a #GAppLaunchContext
 923  *
 924  * Gets the complete environment variable list to be passed to
 925  * the child process when @context is used to launch an application.
 926  * This is a %NULL-terminated array of strings, where each string has
 927  * the form `KEY=VALUE`.
 928  *
 929  * Returns: (array zero-terminated=1) (transfer full): the
 930  *     child's environment
 931  *
 932  * Since: 2.32
 933  */
 934 char **
 935 g_app_launch_context_get_environment (GAppLaunchContext *context)
 936 {
 937   if (!context->priv->envp)
 938     context->priv->envp = g_get_environ ();
 939
 940   return g_strdupv (context->priv->envp);
 941 }
 942
 943 /**
 944  * g_app_launch_context_get_display:
 945  * @context: a #GAppLaunchContext
 946  * @info: a #GAppInfo
 947  * @files: (element-type GFile): a #GList of #GFile objects
 948  *
 949  * Gets the display string for the @context. This is used to ensure new
 950  * applications are started on the same display as the launching
 951  * application, by setting the `DISPLAY` environment variable.
 952  *
 953  * Returns: a display string for the display.
 954  */
 955 char *
 956 g_app_launch_context_get_display (GAppLaunchContext *context,
 957                                   GAppInfo          *info,
 958                                   GList             *files)
 959 {
 960   GAppLaunchContextClass *class;
 961
 962   g_return_val_if_fail (G_IS_APP_LAUNCH_CONTEXT (context), NULL);
 963   g_return_val_if_fail (G_IS_APP_INFO (info), NULL);
 964
 965   class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context);
 966
 967   if (class->get_display == NULL)
 968     return NULL;
 969
 970   return class->get_display (context, info, files);
 971 }
 972
 973 /**
 974  * g_app_launch_context_get_startup_notify_id:
 975  * @context: a #GAppLaunchContext
 976  * @info: a #GAppInfo
 977  * @files: (element-type GFile): a #GList of of #GFile objects
 978  *
 979  * Initiates startup notification for the application and returns the
 980  * `DESKTOP_STARTUP_ID` for the launched operation, if supported.
 981  *
 982  * Startup notification IDs are defined in the
 983  * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt").
 984  *
 985  * Returns: a startup notification ID for the application, or %NULL if
 986  *     not supported.
 987  **/
 988 char *
 989 g_app_launch_context_get_startup_notify_id (GAppLaunchContext *context,
 990                                             GAppInfo          *info,
 991                                             GList             *files)
 992 {
 993   GAppLaunchContextClass *class;
 994
 995   g_return_val_if_fail (G_IS_APP_LAUNCH_CONTEXT (context), NULL);
 996   g_return_val_if_fail (G_IS_APP_INFO (info), NULL);
 997
 998   class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context);
 999
1000   if (class->get_startup_notify_id == NULL)
1001     return NULL;
1002
1003   return class->get_startup_notify_id (context, info, files);
1004 }
1005
1006
1007 /**
1008  * g_app_launch_context_launch_failed:
1009  * @context: a #GAppLaunchContext.
1010  * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
1011  *
1012  * Called when an application has failed to launch, so that it can cancel
1013  * the application startup notification started in g_app_launch_context_get_startup_notify_id().
1014  *
1015  **/
1016 void
1017 g_app_launch_context_launch_failed (GAppLaunchContext *context,
1018                                     const char        *startup_notify_id)
1019 {
1020   g_return_if_fail (G_IS_APP_LAUNCH_CONTEXT (context));
1021   g_return_if_fail (startup_notify_id != NULL);
1022
1023   g_signal_emit (context, signals[LAUNCH_FAILED], 0, startup_notify_id);
1024 }
1025
1026
1027 /**
1028  * SECTION:gappinfomonitor
1029  * @short_description: Monitor application information for changes
1030  *
1031  * #GAppInfoMonitor is a very simple object used for monitoring the app
1032  * info database for changes (ie: newly installed or removed
1033  * applications).
1034  *
1035  * Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect
1036  * to the "changed" signal.
1037  *
1038  * In the usual case, applications should try to make note of the change
1039  * (doing things like invalidating caches) but not act on it.  In
1040  * particular, applications should avoid making calls to #GAppInfo APIs
1041  * in response to the change signal, deferring these until the time that
1042  * the data is actually required.  The exception to this case is when
1043  * application information is actually being displayed on the screen
1044  * (eg: during a search or when the list of all applications is shown).
1045  * The reason for this is that changes to the list of installed
1046  * applications often come in groups (like during system updates) and
1047  * rescanning the list on every change is pointless and expensive.
1048  *
1049  * Since: 2.40
1050  **/
1051
1052 /**
1053  * GAppInfoMonitor:
1054  *
1055  * The only thing you can do with this is to get it via
1056  * g_app_info_monitor_get() and connect to the "changed" signal.
1057  *
1058  * Since: 2.40
1059  **/
1060
1061 typedef struct _GAppInfoMonitorClass GAppInfoMonitorClass;
1062
1063 struct _GAppInfoMonitor
1064 {
1065   GObject parent_instance;
1066   GMainContext *context;
1067 };
1068
1069 struct _GAppInfoMonitorClass
1070 {
1071   GObjectClass parent_class;
1072 };
1073
1074 static GContextSpecificGroup g_app_info_monitor_group;
1075 static guint                 g_app_info_monitor_changed_signal;
1076
1077 G_DEFINE_TYPE (GAppInfoMonitor, g_app_info_monitor, G_TYPE_OBJECT)
1078
1079 static void
1080 g_app_info_monitor_finalize (GObject *object)
1081 {
1082   GAppInfoMonitor *monitor = G_APP_INFO_MONITOR (object);
1083
1084   g_context_specific_group_remove (&g_app_info_monitor_group, monitor->context, monitor, NULL);
1085
1086   G_OBJECT_CLASS (g_app_info_monitor_parent_class)->finalize (object);
1087 }
1088
1089 static void
1090 g_app_info_monitor_init (GAppInfoMonitor *monitor)
1091 {
1092 }
1093
1094 static void
1095 g_app_info_monitor_class_init (GAppInfoMonitorClass *class)
1096 {
1097   GObjectClass *object_class = G_OBJECT_CLASS (class);
1098
1099   /**
1100    * GAppInfoMonitor::changed:
1101    *
1102    * Signal emitted when the app info database for changes (ie: newly installed
1103    * or removed applications).
1104    **/
1105   g_app_info_monitor_changed_signal = g_signal_new (I_("changed"), G_TYPE_APP_INFO_MONITOR, G_SIGNAL_RUN_FIRST,
1106                                                     0, NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
1107
1108   object_class->finalize = g_app_info_monitor_finalize;
1109 }
1110
1111 /**
1112  * g_app_info_monitor_get:
1113  *
1114  * Gets the #GAppInfoMonitor for the current thread-default main
1115  * context.
1116  *
1117  * The #GAppInfoMonitor will emit a "changed" signal in the
1118  * thread-default main context whenever the list of installed
1119  * applications (as reported by g_app_info_get_all()) may have changed.
1120  *
1121  * You must only call g_object_unref() on the return value from under
1122  * the same main context as you created it.
1123  *
1124  * Returns: (transfer full): a reference to a #GAppInfoMonitor
1125  *
1126  * Since: 2.40
1127  **/
1128 GAppInfoMonitor *
1129 g_app_info_monitor_get (void)
1130 {
1131   return g_context_specific_group_get (&g_app_info_monitor_group,
1132                                        G_TYPE_APP_INFO_MONITOR,
1133                                        G_STRUCT_OFFSET (GAppInfoMonitor, context),
1134                                        NULL);
1135 }
1136
1137 void
1138 g_app_info_monitor_fire (void)
1139 {
1140   g_context_specific_group_emit (&g_app_info_monitor_group, g_app_info_monitor_changed_signal);
1141 }