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, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  *
  20  * Author: Alexander Larsson <alexl@redhat.com>
  21  */
  22
  23 #include "config.h"
  24 #include "gappinfo.h"
  25 #include "glibintl.h"
  26 #include <gioerror.h>
  27 #include <gfile.h>
  28
  29
  30 /**
  31  * SECTION:gappinfo
  32  * @short_description: Application information and launch contexts
  33  * @include: gio/gio.h
  34  *
  35  * #GAppInfo and #GAppLaunchContext are used for describing and launching
  36  * applications installed on the system.
  37  *
  38  * As of GLib 2.20, URIs will always be converted to POSIX paths
  39  * (using g_file_get_path()) when using g_app_info_launch() even if
  40  * the application requested an URI and not a POSIX path. For example
  41  * for an desktop-file based application with Exec key <literal>totem
  42  * %%U</literal> and a single URI,
  43  * <literal>sftp://foo/file.avi</literal>, then
  44  * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> will be
  45  * passed. This will only work if a set of suitable GIO extensions
  46  * (such as gvfs 2.26 compiled with FUSE support), is available and
  47  * operational; if this is not the case, the URI will be passed
  48  * unmodified to the application. Some URIs, such as
  49  * <literal>mailto:</literal>, of course cannot be mapped to a POSIX
  50  * path (in gvfs there's no FUSE mount for it); such URIs will be
  51  * passed unmodified to the application.
  52  *
  53  * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
  54  * back to the GIO URI in the #GFile constructors (since gvfs
  55  * implements the #GVfs extension point). As such, if the application
  56  * needs to examine the URI, it needs to use g_file_get_uri() or
  57  * similar on #GFile. In other words, an application cannot assume
  58  * that the URI passed to e.g. g_file_new_for_commandline_arg() is
  59  * equal to the result of g_file_get_uri(). The following snippet
  60  * illustrates this:
  61  *
  62  * <programlisting>
  63  * GFile *f;
  64  * char *uri;
  65  *
  66  * file = g_file_new_for_commandline_arg (uri_from_commandline);
  67  *
  68  * uri = g_file_get_uri (file);
  69  * strcmp (uri, uri_from_commandline) == 0; // FALSE
  70  * g_free (uri);
  71  *
  72  * if (g_file_has_uri_scheme (file, "cdda"))
  73  *   {
  74  *     // do something special with uri
  75  *   }
  76  * g_object_unref (file);
  77  * </programlisting>
  78  *
  79  * This code will work when both <literal>cdda://sr0/Track
  80  * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track
  81  * 1.wav</literal> is passed to the application. It should be noted
  82  * that it's generally not safe for applications to rely on the format
  83  * of a particular URIs. Different launcher applications (e.g. file
  84  * managers) may have different ideas of what a given URI means.
  85  *
  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 #GAppInfo<!-- -->s 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 /**
 313  * g_app_info_set_as_default_for_extension:
 314  * @appinfo: a #GAppInfo.
 315  * @extension: a string containing the file extension (without the dot).
 316  * @error: a #GError.
 317  *
 318  * Sets the application as the default handler for the given file extension.
 319  *
 320  * Returns: %TRUE on success, %FALSE on error.
 321  **/
 322 gboolean
 323 g_app_info_set_as_default_for_extension (GAppInfo    *appinfo,
 324                                          const char  *extension,
 325                                          GError     **error)
 326 {
 327   GAppInfoIface *iface;
 328
 329   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 330   g_return_val_if_fail (extension != NULL, FALSE);
 331
 332   iface = G_APP_INFO_GET_IFACE (appinfo);
 333
 334   if (iface->set_as_default_for_extension)
 335     return (* iface->set_as_default_for_extension) (appinfo, extension, error);
 336
 337   g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
 338                        "g_app_info_set_as_default_for_extension not supported yet");
 339   return FALSE;
 340 }
 341
 342
 343 /**
 344  * g_app_info_add_supports_type:
 345  * @appinfo: a #GAppInfo.
 346  * @content_type: a string.
 347  * @error: a #GError.
 348  *
 349  * Adds a content type to the application information to indicate the
 350  * application is capable of opening files with the given content type.
 351  *
 352  * Returns: %TRUE on success, %FALSE on error.
 353  **/
 354 gboolean
 355 g_app_info_add_supports_type (GAppInfo    *appinfo,
 356                               const char  *content_type,
 357                               GError     **error)
 358 {
 359   GAppInfoIface *iface;
 360
 361   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 362   g_return_val_if_fail (content_type != NULL, FALSE);
 363
 364   iface = G_APP_INFO_GET_IFACE (appinfo);
 365
 366   if (iface->add_supports_type)
 367     return (* iface->add_supports_type) (appinfo, content_type, error);
 368
 369   g_set_error_literal (error, G_IO_ERROR,
 370                        G_IO_ERROR_NOT_SUPPORTED,
 371                        "g_app_info_add_supports_type not supported yet");
 372
 373   return FALSE;
 374 }
 375
 376
 377 /**
 378  * g_app_info_can_remove_supports_type:
 379  * @appinfo: a #GAppInfo.
 380  *
 381  * Checks if a supported content type can be removed from an application.
 382  *
 383  * Returns: %TRUE if it is possible to remove supported
 384  *     content types from a given @appinfo, %FALSE if not.
 385  **/
 386 gboolean
 387 g_app_info_can_remove_supports_type (GAppInfo *appinfo)
 388 {
 389   GAppInfoIface *iface;
 390
 391   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 392
 393   iface = G_APP_INFO_GET_IFACE (appinfo);
 394
 395   if (iface->can_remove_supports_type)
 396     return (* iface->can_remove_supports_type) (appinfo);
 397
 398   return FALSE;
 399 }
 400
 401
 402 /**
 403  * g_app_info_remove_supports_type:
 404  * @appinfo: a #GAppInfo.
 405  * @content_type: a string.
 406  * @error: a #GError.
 407  *
 408  * Removes a supported type from an application, if possible.
 409  *
 410  * Returns: %TRUE on success, %FALSE on error.
 411  **/
 412 gboolean
 413 g_app_info_remove_supports_type (GAppInfo    *appinfo,
 414                                  const char  *content_type,
 415                                  GError     **error)
 416 {
 417   GAppInfoIface *iface;
 418
 419   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 420   g_return_val_if_fail (content_type != NULL, FALSE);
 421
 422   iface = G_APP_INFO_GET_IFACE (appinfo);
 423
 424   if (iface->remove_supports_type)
 425     return (* iface->remove_supports_type) (appinfo, content_type, error);
 426
 427   g_set_error_literal (error, G_IO_ERROR,
 428                        G_IO_ERROR_NOT_SUPPORTED,
 429                        "g_app_info_remove_supports_type not supported yet");
 430
 431   return FALSE;
 432 }
 433
 434
 435 /**
 436  * g_app_info_get_icon:
 437  * @appinfo: a #GAppInfo.
 438  *
 439  * Gets the icon for the application.
 440  *
 441  * Returns: (transfer none): the default #GIcon for @appinfo.
 442  **/
 443 GIcon *
 444 g_app_info_get_icon (GAppInfo *appinfo)
 445 {
 446   GAppInfoIface *iface;
 447
 448   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 449
 450   iface = G_APP_INFO_GET_IFACE (appinfo);
 451
 452   return (* iface->get_icon) (appinfo);
 453 }
 454
 455
 456 /**
 457  * g_app_info_launch:
 458  * @appinfo: a #GAppInfo
 459  * @files: (element-type GFile): a #GList of #GFile objects
 460  * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
 461  * @error: a #GError
 462  *
 463  * Launches the application. Passes @files to the launched application
 464  * as arguments, using the optional @launch_context to get information
 465  * about the details of the launcher (like what screen it is on).
 466  * On error, @error will be set accordingly.
 467  *
 468  * To launch the application without arguments pass a %NULL @files list.
 469  *
 470  * Note that even if the launch is successful the application launched
 471  * can fail to start if it runs into problems during startup. There is
 472  * no way to detect this.
 473  *
 474  * Some URIs can be changed when passed through a GFile (for instance
 475  * unsupported uris with strange formats like mailto:), so if you have
 476  * a textual uri you want to pass in as argument, consider using
 477  * g_app_info_launch_uris() instead.
 478  *
 479  * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
 480  * environment variable with the path of the launched desktop file and
 481  * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process
 482  * id of the launched process. This can be used to ignore
 483  * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited
 484  * by further processes. The <envar>DISPLAY</envar> and
 485  * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also
 486  * set, based on information provided in @launch_context.
 487  *
 488  * Returns: %TRUE on successful launch, %FALSE otherwise.
 489  **/
 490 gboolean
 491 g_app_info_launch (GAppInfo           *appinfo,
 492                    GList              *files,
 493                    GAppLaunchContext  *launch_context,
 494                    GError            **error)
 495 {
 496   GAppInfoIface *iface;
 497
 498   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 499
 500   iface = G_APP_INFO_GET_IFACE (appinfo);
 501
 502   return (* iface->launch) (appinfo, files, launch_context, error);
 503 }
 504
 505
 506 /**
 507  * g_app_info_supports_uris:
 508  * @appinfo: a #GAppInfo.
 509  *
 510  * Checks if the application supports reading files and directories from URIs.
 511  *
 512  * Returns: %TRUE if the @appinfo supports URIs.
 513  **/
 514 gboolean
 515 g_app_info_supports_uris (GAppInfo *appinfo)
 516 {
 517   GAppInfoIface *iface;
 518
 519   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 520
 521   iface = G_APP_INFO_GET_IFACE (appinfo);
 522
 523   return (* iface->supports_uris) (appinfo);
 524 }
 525
 526
 527 /**
 528  * g_app_info_supports_files:
 529  * @appinfo: a #GAppInfo.
 530  *
 531  * Checks if the application accepts files as arguments.
 532  *
 533  * Returns: %TRUE if the @appinfo supports files.
 534  **/
 535 gboolean
 536 g_app_info_supports_files (GAppInfo *appinfo)
 537 {
 538   GAppInfoIface *iface;
 539
 540   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 541
 542   iface = G_APP_INFO_GET_IFACE (appinfo);
 543
 544   return (* iface->supports_files) (appinfo);
 545 }
 546
 547
 548 /**
 549  * g_app_info_launch_uris:
 550  * @appinfo: a #GAppInfo
 551  * @uris: (element-type char*): a #GList containing URIs to launch.
 552  * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
 553  * @error: a #GError
 554  *
 555  * Launches the application. Passes @uris to the launched application
 556  * as arguments, using the optional @launch_context to get information
 557  * about the details of the launcher (like what screen it is on).
 558  * On error, @error will be set accordingly.
 559  *
 560  * To lauch the application without arguments pass a %NULL @uris list.
 561  *
 562  * Note that even if the launch is successful the application launched
 563  * can fail to start if it runs into problems during startup. There is
 564  * no way to detect this.
 565  *
 566  * Returns: %TRUE on successful launch, %FALSE otherwise.
 567  **/
 568 gboolean
 569 g_app_info_launch_uris (GAppInfo           *appinfo,
 570                         GList              *uris,
 571                         GAppLaunchContext  *launch_context,
 572                         GError            **error)
 573 {
 574   GAppInfoIface *iface;
 575
 576   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 577
 578   iface = G_APP_INFO_GET_IFACE (appinfo);
 579
 580   return (* iface->launch_uris) (appinfo, uris, launch_context, error);
 581 }
 582
 583
 584 /**
 585  * g_app_info_should_show:
 586  * @appinfo: a #GAppInfo.
 587  *
 588  * Checks if the application info should be shown in menus that
 589  * list available applications.
 590  *
 591  * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
 592  **/
 593 gboolean
 594 g_app_info_should_show (GAppInfo *appinfo)
 595 {
 596   GAppInfoIface *iface;
 597
 598   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 599
 600   iface = G_APP_INFO_GET_IFACE (appinfo);
 601
 602   return (* iface->should_show) (appinfo);
 603 }
 604
 605 /**
 606  * g_app_info_launch_default_for_uri:
 607  * @uri: the uri to show
 608  * @launch_context: an optional #GAppLaunchContext.
 609  * @error: a #GError.
 610  *
 611  * Utility function that launches the default application
 612  * registered to handle the specified uri. Synchronous I/O
 613  * is done on the uri to detect the type of the file if
 614  * required.
 615  *
 616  * Returns: %TRUE on success, %FALSE on error.
 617  **/
 618 gboolean
 619 g_app_info_launch_default_for_uri (const char         *uri,
 620                                    GAppLaunchContext  *launch_context,
 621                                    GError            **error)
 622 {
 623   GAppInfo *app_info;
 624   GFile *file;
 625   GList l;
 626   gboolean res;
 627
 628   file = g_file_new_for_uri (uri);
 629   app_info = g_file_query_default_handler (file, NULL, error);
 630   g_object_unref (file);
 631   if (app_info == NULL)
 632     return FALSE;
 633
 634   /* Use the uri, not the GFile, as the GFile roundtrip may
 635    * affect the uri which we don't want (for instance for a
 636    * mailto: uri).
 637    */
 638   l.data = (char *)uri;
 639   l.next = l.prev = NULL;
 640   res = g_app_info_launch_uris (app_info, &l,
 641                                 launch_context, error);
 642
 643   g_object_unref (app_info);
 644
 645   return res;
 646 }
 647
 648 /**
 649  * g_app_info_can_delete:
 650  * @appinfo: a #GAppInfo
 651  *
 652  * Obtains the information whether the #GAppInfo can be deleted.
 653  * See g_app_info_delete().
 654  *
 655  * Returns: %TRUE if @appinfo can be deleted
 656  *
 657  * Since: 2.20
 658  */
 659 gboolean
 660 g_app_info_can_delete (GAppInfo *appinfo)
 661 {
 662   GAppInfoIface *iface;
 663
 664   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 665
 666   iface = G_APP_INFO_GET_IFACE (appinfo);
 667
 668   if (iface->can_delete)
 669     return (* iface->can_delete) (appinfo);
 670
 671   return FALSE;
 672 }
 673
 674
 675 /**
 676  * g_app_info_delete:
 677  * @appinfo: a #GAppInfo
 678  *
 679  * Tries to delete a #GAppInfo.
 680  *
 681  * On some platforms, there may be a difference between user-defined
 682  * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which
 683  * cannot. See g_app_info_can_delete().
 684  *
 685  * Virtual: do_delete
 686  * Returns: %TRUE if @appinfo has been deleted
 687  *
 688  * Since: 2.20
 689  */
 690 gboolean
 691 g_app_info_delete (GAppInfo *appinfo)
 692 {
 693   GAppInfoIface *iface;
 694
 695   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 696
 697   iface = G_APP_INFO_GET_IFACE (appinfo);
 698
 699   if (iface->do_delete)
 700     return (* iface->do_delete) (appinfo);
 701
 702   return FALSE;
 703 }
 704
 705
 706 G_DEFINE_TYPE (GAppLaunchContext, g_app_launch_context, G_TYPE_OBJECT);
 707
 708 /**
 709  * g_app_launch_context_new:
 710  *
 711  * Creates a new application launch context. This is not normally used,
 712  * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
 713  *
 714  * Returns: a #GAppLaunchContext.
 715  **/
 716 GAppLaunchContext *
 717 g_app_launch_context_new (void)
 718 {
 719   return g_object_new (G_TYPE_APP_LAUNCH_CONTEXT, NULL);
 720 }
 721
 722 static void
 723 g_app_launch_context_class_init (GAppLaunchContextClass *klass)
 724 {
 725 }
 726
 727 static void
 728 g_app_launch_context_init (GAppLaunchContext *launch_context)
 729 {
 730 }
 731
 732 /**
 733  * g_app_launch_context_get_display:
 734  * @context: a #GAppLaunchContext
 735  * @info: a #GAppInfo
 736  * @files: (element-type GFile): a #GList of #GFile objects
 737  *
 738  * Gets the display string for the @context. This is used to ensure new
 739  * applications are started on the same display as the launching
 740  * application, by setting the <envar>DISPLAY</envar> environment variable.
 741  *
 742  * Returns: a display string for the display.
 743  **/
 744 char *
 745 g_app_launch_context_get_display (GAppLaunchContext *context,
 746                                   GAppInfo          *info,
 747                                   GList             *files)
 748 {
 749   GAppLaunchContextClass *class;
 750
 751   g_return_val_if_fail (G_IS_APP_LAUNCH_CONTEXT (context), NULL);
 752   g_return_val_if_fail (G_IS_APP_INFO (info), NULL);
 753
 754   class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context);
 755
 756   if (class->get_display == NULL)
 757     return NULL;
 758
 759   return class->get_display (context, info, files);
 760 }
 761
 762 /**
 763  * g_app_launch_context_get_startup_notify_id:
 764  * @context: a #GAppLaunchContext
 765  * @info: a #GAppInfo
 766  * @files: (element-type GFile): a #GList of of #GFile objects
 767  *
 768  * Initiates startup notification for the application and returns the
 769  * <envar>DESKTOP_STARTUP_ID</envar> for the launched operation,
 770  * if supported.
 771  *
 772  * Startup notification IDs are defined in the <ulink
 773  * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
 774  * FreeDesktop.Org Startup Notifications standard</ulink>.
 775  *
 776  * Returns: a startup notification ID for the application, or %NULL if
 777  *     not supported.
 778  **/
 779 char *
 780 g_app_launch_context_get_startup_notify_id (GAppLaunchContext *context,
 781                                             GAppInfo          *info,
 782                                             GList             *files)
 783 {
 784   GAppLaunchContextClass *class;
 785
 786   g_return_val_if_fail (G_IS_APP_LAUNCH_CONTEXT (context), NULL);
 787   g_return_val_if_fail (G_IS_APP_INFO (info), NULL);
 788
 789   class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context);
 790
 791   if (class->get_startup_notify_id == NULL)
 792     return NULL;
 793
 794   return class->get_startup_notify_id (context, info, files);
 795 }
 796
 797
 798 /**
 799  * g_app_launch_context_launch_failed:
 800  * @context: a #GAppLaunchContext.
 801  * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
 802  *
 803  * Called when an application has failed to launch, so that it can cancel
 804  * the application startup notification started in g_app_launch_context_get_startup_notify_id().
 805  *
 806  **/
 807 void
 808 g_app_launch_context_launch_failed (GAppLaunchContext *context,
 809                                     const char        *startup_notify_id)
 810 {
 811   GAppLaunchContextClass *class;
 812
 813   g_return_if_fail (G_IS_APP_LAUNCH_CONTEXT (context));
 814   g_return_if_fail (startup_notify_id != NULL);
 815
 816   class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context);
 817
 818   if (class->launch_failed != NULL)
 819     class->launch_failed (context, startup_notify_id);
 820 }