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 #include "gioalias.h"
  30
  31 /**
  32  * SECTION:gappinfo
  33  * @short_description: Application information and launch contexts
  34  * @include: gio/gio.h
  35  *
  36  * #GAppInfo and #GAppLaunchContext are used for describing and launching
  37  * applications installed on the system.
  38  *
  39  **/
  40
  41 static void g_app_info_base_init (gpointer g_class);
  42 static void g_app_info_class_init (gpointer g_class,
  43                                    gpointer class_data);
  44
  45
  46 GType
  47 g_app_info_get_type (void)
  48 {
  49   static GType app_info_type = 0;
  50
  51   if (! app_info_type)
  52     {
  53       static const GTypeInfo app_info_info =
  54       {
  55         sizeof (GAppInfoIface), /* class_size */
  56         g_app_info_base_init,   /* base_init */
  57         NULL,           /* base_finalize */
  58         g_app_info_class_init,
  59         NULL,           /* class_finalize */
  60         NULL,           /* class_data */
  61         0,
  62         0,              /* n_preallocs */
  63         NULL
  64       };
  65
  66       app_info_type =
  67         g_type_register_static (G_TYPE_INTERFACE, I_("GAppInfo"),
  68                                 &app_info_info, 0);
  69
  70       g_type_interface_add_prerequisite (app_info_type, G_TYPE_OBJECT);
  71     }
  72
  73   return app_info_type;
  74 }
  75
  76 static void
  77 g_app_info_class_init (gpointer g_class,
  78                        gpointer class_data)
  79 {
  80 }
  81
  82 static void
  83 g_app_info_base_init (gpointer g_class)
  84 {
  85 }
  86
  87
  88 /**
  89  * g_app_info_dup:
  90  * @appinfo: a #GAppInfo.
  91  *
  92  * Creates a duplicate of a #GAppInfo.
  93  *
  94  * Returns: a duplicate of @appinfo.
  95  **/
  96 GAppInfo *
  97 g_app_info_dup (GAppInfo *appinfo)
  98 {
  99   GAppInfoIface *iface;
 100
 101   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 102
 103   iface = G_APP_INFO_GET_IFACE (appinfo);
 104
 105   return (* iface->dup) (appinfo);
 106 }
 107
 108 /**
 109  * g_app_info_equal:
 110  * @appinfo1: the first #GAppInfo.
 111  * @appinfo2: the second #GAppInfo.
 112  *
 113  * Checks if two #GAppInfos are equal.
 114  *
 115  * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
 116  **/
 117 gboolean
 118 g_app_info_equal (GAppInfo *appinfo1,
 119                   GAppInfo *appinfo2)
 120 {
 121   GAppInfoIface *iface;
 122
 123   g_return_val_if_fail (G_IS_APP_INFO (appinfo1), FALSE);
 124   g_return_val_if_fail (G_IS_APP_INFO (appinfo2), FALSE);
 125
 126   if (G_TYPE_FROM_INSTANCE (appinfo1) != G_TYPE_FROM_INSTANCE (appinfo2))
 127     return FALSE;
 128
 129   iface = G_APP_INFO_GET_IFACE (appinfo1);
 130
 131   return (* iface->equal) (appinfo1, appinfo2);
 132 }
 133
 134 /**
 135  * g_app_info_get_id:
 136  * @appinfo: a #GAppInfo.
 137  *
 138  * Gets the ID of an application. An id is a string that
 139  * identifies the application. The exact format of the id is
 140  * platform dependent. For instance, on Unix this is the
 141  * desktop file id from the xdg menu specification.
 142  *
 143  * Note that the returned ID may be %NULL, depending on how
 144  * the @appinfo has been constructed.
 145  *
 146  * Returns: a string containing the application's ID.
 147  **/
 148 const char *
 149 g_app_info_get_id (GAppInfo *appinfo)
 150 {
 151   GAppInfoIface *iface;
 152
 153   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 154
 155   iface = G_APP_INFO_GET_IFACE (appinfo);
 156
 157   return (* iface->get_id) (appinfo);
 158 }
 159
 160 /**
 161  * g_app_info_get_name:
 162  * @appinfo: a #GAppInfo.
 163  *
 164  * Gets the installed name of the application.
 165  *
 166  * Returns: the name of the application for @appinfo.
 167  **/
 168 const char *
 169 g_app_info_get_name (GAppInfo *appinfo)
 170 {
 171   GAppInfoIface *iface;
 172
 173   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 174
 175   iface = G_APP_INFO_GET_IFACE (appinfo);
 176
 177   return (* iface->get_name) (appinfo);
 178 }
 179
 180 /**
 181  * g_app_info_get_description:
 182  * @appinfo: a #GAppInfo.
 183  *
 184  * Gets a human-readable description of an installed application.
 185  *
 186  * Returns: a string containing a description of the
 187  * application @appinfo, or %NULL if none.
 188  **/
 189 const char *
 190 g_app_info_get_description (GAppInfo *appinfo)
 191 {
 192   GAppInfoIface *iface;
 193
 194   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 195
 196   iface = G_APP_INFO_GET_IFACE (appinfo);
 197
 198   return (* iface->get_description) (appinfo);
 199 }
 200
 201 /**
 202  * g_app_info_get_executable:
 203  * @appinfo: a #GAppInfo.
 204  *
 205  * Gets the executable's name for the installed application.
 206  *
 207  * Returns: a string containing the @appinfo's application
 208  * binary's name.
 209  **/
 210 const char *
 211 g_app_info_get_executable (GAppInfo *appinfo)
 212 {
 213   GAppInfoIface *iface;
 214
 215   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 216
 217   iface = G_APP_INFO_GET_IFACE (appinfo);
 218
 219   return (* iface->get_executable) (appinfo);
 220 }
 221
 222
 223 /**
 224  * g_app_info_set_as_default_for_type:
 225  * @appinfo: a #GAppInfo.
 226  * @content_type: the content type.
 227  * @error: a #GError.
 228  *
 229  * Sets the application as the default handler for a given type.
 230  *
 231  * Returns: %TRUE on success, %FALSE on error.
 232  **/
 233 gboolean
 234 g_app_info_set_as_default_for_type (GAppInfo    *appinfo,
 235                                     const char  *content_type,
 236                                     GError     **error)
 237 {
 238   GAppInfoIface *iface;
 239
 240   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 241   g_return_val_if_fail (content_type != NULL, FALSE);
 242
 243   iface = G_APP_INFO_GET_IFACE (appinfo);
 244
 245   return (* iface->set_as_default_for_type) (appinfo, content_type, error);
 246 }
 247
 248
 249 /**
 250  * g_app_info_set_as_default_for_extension:
 251  * @appinfo: a #GAppInfo.
 252  * @extension: a string containing the file extension (without the dot).
 253  * @error: a #GError.
 254  *
 255  * Sets the application as the default handler for the given file extention.
 256  *
 257  * Returns: %TRUE on success, %FALSE on error.
 258  **/
 259 gboolean
 260 g_app_info_set_as_default_for_extension (GAppInfo    *appinfo,
 261                                          const char  *extension,
 262                                          GError     **error)
 263 {
 264   GAppInfoIface *iface;
 265
 266   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 267   g_return_val_if_fail (extension != NULL, FALSE);
 268
 269   iface = G_APP_INFO_GET_IFACE (appinfo);
 270
 271   if (iface->set_as_default_for_extension)
 272     return (* iface->set_as_default_for_extension) (appinfo, extension, error);
 273
 274   g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
 275                        "g_app_info_set_as_default_for_extension not supported yet");
 276   return FALSE;
 277 }
 278
 279
 280 /**
 281  * g_app_info_add_supports_type:
 282  * @appinfo: a #GAppInfo.
 283  * @content_type: a string.
 284  * @error: a #GError.
 285  *
 286  * Adds a content type to the application information to indicate the
 287  * application is capable of opening files with the given content type.
 288  *
 289  * Returns: %TRUE on success, %FALSE on error.
 290  **/
 291 gboolean
 292 g_app_info_add_supports_type (GAppInfo    *appinfo,
 293                               const char  *content_type,
 294                               GError     **error)
 295 {
 296   GAppInfoIface *iface;
 297
 298   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 299   g_return_val_if_fail (content_type != NULL, FALSE);
 300
 301   iface = G_APP_INFO_GET_IFACE (appinfo);
 302
 303   if (iface->add_supports_type)
 304     return (* iface->add_supports_type) (appinfo, content_type, error);
 305
 306   g_set_error_literal (error, G_IO_ERROR,
 307                        G_IO_ERROR_NOT_SUPPORTED,
 308                        "g_app_info_add_supports_type not supported yet");
 309
 310   return FALSE;
 311 }
 312
 313
 314 /**
 315  * g_app_info_can_remove_supports_type:
 316  * @appinfo: a #GAppInfo.
 317  *
 318  * Checks if a supported content type can be removed from an application.
 319  *
 320  * Returns: %TRUE if it is possible to remove supported
 321  *     content types from a given @appinfo, %FALSE if not.
 322  **/
 323 gboolean
 324 g_app_info_can_remove_supports_type (GAppInfo *appinfo)
 325 {
 326   GAppInfoIface *iface;
 327
 328   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 329
 330   iface = G_APP_INFO_GET_IFACE (appinfo);
 331
 332   if (iface->can_remove_supports_type)
 333     return (* iface->can_remove_supports_type) (appinfo);
 334
 335   return FALSE;
 336 }
 337
 338
 339 /**
 340  * g_app_info_remove_supports_type:
 341  * @appinfo: a #GAppInfo.
 342  * @content_type: a string.
 343  * @error: a #GError.
 344  *
 345  * Removes a supported type from an application, if possible.
 346  *
 347  * Returns: %TRUE on success, %FALSE on error.
 348  **/
 349 gboolean
 350 g_app_info_remove_supports_type (GAppInfo    *appinfo,
 351                                  const char  *content_type,
 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 (content_type != NULL, FALSE);
 358
 359   iface = G_APP_INFO_GET_IFACE (appinfo);
 360
 361   if (iface->remove_supports_type)
 362     return (* iface->remove_supports_type) (appinfo, content_type, error);
 363
 364   g_set_error_literal (error, G_IO_ERROR,
 365                        G_IO_ERROR_NOT_SUPPORTED,
 366                        "g_app_info_remove_supports_type not supported yet");
 367
 368   return FALSE;
 369 }
 370
 371
 372 /**
 373  * g_app_info_get_icon:
 374  * @appinfo: a #GAppInfo.
 375  *
 376  * Gets the icon for the application.
 377  *
 378  * Returns: the default #GIcon for @appinfo.
 379  **/
 380 GIcon *
 381 g_app_info_get_icon (GAppInfo *appinfo)
 382 {
 383   GAppInfoIface *iface;
 384
 385   g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
 386
 387   iface = G_APP_INFO_GET_IFACE (appinfo);
 388
 389   return (* iface->get_icon) (appinfo);
 390 }
 391
 392
 393 /**
 394  * g_app_info_launch:
 395  * @appinfo: a #GAppInfo.
 396  * @files: a #GList of #GFile objects.
 397  * @launch_context: a #GAppLaunchContext.
 398  * @error: a #GError.
 399  *
 400  * Launches the application. Passes @files to the launched application
 401  * as arguments, using the optional @launch_context to get information
 402  * about the details of the launcher (like what screen it is on).
 403  * On error, @error will be set accordingly.
 404  *
 405  * To lauch the application without arguments pass a %NULL @files list.
 406  *
 407  * Note that even if the launch is successful the application launched
 408  * can fail to start if it runs into problems during startup. There is
 409  * no way to detect this.
 410  *
 411  * Some URIs can be changed when passed through a GFile (for instance
 412  * unsupported uris with strange formats like mailto:), so if you have
 413  * a textual uri you want to pass in as argument, consider using
 414  * g_app_info_launch_uris() instead.
 415  *
 416  * Returns: %TRUE on successful launch, %FALSE otherwise.
 417  **/
 418 gboolean
 419 g_app_info_launch (GAppInfo           *appinfo,
 420                    GList              *files,
 421                    GAppLaunchContext  *launch_context,
 422                    GError            **error)
 423 {
 424   GAppInfoIface *iface;
 425
 426   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 427
 428   iface = G_APP_INFO_GET_IFACE (appinfo);
 429
 430   return (* iface->launch) (appinfo, files, launch_context, error);
 431 }
 432
 433
 434 /**
 435  * g_app_info_supports_uris:
 436  * @appinfo: a #GAppInfo.
 437  *
 438  * Checks if the application supports reading files and directories from URIs.
 439  *
 440  * Returns: %TRUE if the @appinfo supports URIs.
 441  **/
 442 gboolean
 443 g_app_info_supports_uris (GAppInfo *appinfo)
 444 {
 445   GAppInfoIface *iface;
 446
 447   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 448
 449   iface = G_APP_INFO_GET_IFACE (appinfo);
 450
 451   return (* iface->supports_uris) (appinfo);
 452 }
 453
 454
 455 /**
 456  * g_app_info_supports_files:
 457  * @appinfo: a #GAppInfo.
 458  *
 459  * Checks if the application accepts files as arguments.
 460  *
 461  * Returns: %TRUE if the @appinfo supports files.
 462  **/
 463 gboolean
 464 g_app_info_supports_files (GAppInfo *appinfo)
 465 {
 466   GAppInfoIface *iface;
 467
 468   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 469
 470   iface = G_APP_INFO_GET_IFACE (appinfo);
 471
 472   return (* iface->supports_files) (appinfo);
 473 }
 474
 475
 476 /**
 477  * g_app_info_launch_uris:
 478  * @appinfo: a #GAppInfo.
 479  * @uris: a #GList containing URIs to launch.
 480  * @launch_context: a #GAppLaunchContext.
 481  * @error: a #GError.
 482  *
 483  * Launches the application. Passes @uris to the launched application
 484  * as arguments, using the optional @launch_context to get information
 485  * about the details of the launcher (like what screen it is on).
 486  * On error, @error will be set accordingly.
 487  *
 488  * To lauch the application without arguments pass a %NULL @uris list.
 489  *
 490  * Note that even if the launch is successful the application launched
 491  * can fail to start if it runs into problems during startup. There is
 492  * no way to detect this.
 493  *
 494  * Returns: %TRUE on successful launch, %FALSE otherwise.
 495  **/
 496 gboolean
 497 g_app_info_launch_uris (GAppInfo           *appinfo,
 498                         GList              *uris,
 499                         GAppLaunchContext  *launch_context,
 500                         GError            **error)
 501 {
 502   GAppInfoIface *iface;
 503
 504   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 505
 506   iface = G_APP_INFO_GET_IFACE (appinfo);
 507
 508   return (* iface->launch_uris) (appinfo, uris, launch_context, error);
 509 }
 510
 511
 512 /**
 513  * g_app_info_should_show:
 514  * @appinfo: a #GAppInfo.
 515  *
 516  * Checks if the application info should be shown in menus that
 517  * list available applications.
 518  *
 519  * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
 520  **/
 521 gboolean
 522 g_app_info_should_show (GAppInfo *appinfo)
 523 {
 524   GAppInfoIface *iface;
 525
 526   g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
 527
 528   iface = G_APP_INFO_GET_IFACE (appinfo);
 529
 530   return (* iface->should_show) (appinfo);
 531 }
 532
 533 /**
 534  * g_app_info_launch_default_for_uri:
 535  * @uri: the uri to show
 536  * @launch_context: an optional #GAppLaunchContext.
 537  * @error: a #GError.
 538  *
 539  * Utility function that launches the default application
 540  * registered to handle the specified uri. Synchronous I/O
 541  * is done on the uri to detext the type of the file if
 542  * required.
 543  *
 544  * Returns: %TRUE on success, %FALSE on error.
 545  **/
 546 gboolean
 547 g_app_info_launch_default_for_uri (const char         *uri,
 548                                    GAppLaunchContext  *launch_context,
 549                                    GError            **error)
 550 {
 551   GAppInfo *app_info;
 552   GFile *file;
 553   GList l;
 554   gboolean res;
 555
 556   file = g_file_new_for_uri (uri);
 557   app_info = g_file_query_default_handler (file, NULL, error);
 558   g_object_unref (file);
 559   if (app_info == NULL)
 560     return FALSE;
 561
 562   /* Use the uri, not the GFile, as the GFile roundtrip may
 563    * affect the uri which we don't want (for instance for a
 564    * mailto: uri).
 565    */
 566   l.data = (char *)uri;
 567   l.next = l.prev = NULL;
 568   res = g_app_info_launch_uris (app_info, &l,
 569                                 launch_context, error);
 570
 571   g_object_unref (app_info);
 572
 573   return res;
 574 }
 575
 576
 577 G_DEFINE_TYPE (GAppLaunchContext, g_app_launch_context, G_TYPE_OBJECT);
 578
 579 /**
 580  * g_app_launch_context_new:
 581  *
 582  * Creates a new application launch context. This is not normally used,
 583  * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
 584  *
 585  * Returns: a #GAppLaunchContext.
 586  **/
 587 GAppLaunchContext *
 588 g_app_launch_context_new (void)
 589 {
 590   return g_object_new (G_TYPE_APP_LAUNCH_CONTEXT, NULL);
 591 }
 592
 593 static void
 594 g_app_launch_context_class_init (GAppLaunchContextClass *klass)
 595 {
 596 }
 597
 598 static void
 599 g_app_launch_context_init (GAppLaunchContext *launch_context)
 600 {
 601 }
 602
 603 /**
 604  * g_app_launch_context_get_display:
 605  * @context: a #GAppLaunchContext.
 606  * @info: a #GAppInfo.
 607  * @files: a #GList of files.
 608  *
 609  * Gets the display string for the display. This is used to ensure new
 610  * applications are started on the same display as the launching
 611  * application.
 612  *
 613  * Returns: a display string for the display.
 614  **/
 615 char *
 616 g_app_launch_context_get_display (GAppLaunchContext *context,
 617                                   GAppInfo          *info,
 618                                   GList             *files)
 619 {
 620   GAppLaunchContextClass *class;
 621
 622   g_return_val_if_fail (G_IS_APP_LAUNCH_CONTEXT (context), NULL);
 623   g_return_val_if_fail (G_IS_APP_INFO (info), NULL);
 624
 625   class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context);
 626
 627   if (class->get_display == NULL)
 628     return NULL;
 629
 630   return class->get_display (context, info, files);
 631 }
 632
 633 /**
 634  * g_app_launch_context_get_startup_notify_id:
 635  * @context: a #GAppLaunchContext.
 636  * @info: a #GAppInfo.
 637  * @files: a #GList of files.
 638  *
 639  * Initiates startup notification for the applicaiont and returns the
 640  * DESKTOP_STARTUP_ID for the launched operation, if supported.
 641  *
 642  * Startup notification IDs are defined in the <ulink
 643  * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
 644  * FreeDesktop.Org Startup Notifications standard</ulink>.
 645  *
 646  * Returns: a startup notification ID for the application, or %NULL if
 647  *     not supported.
 648  **/
 649 char *
 650 g_app_launch_context_get_startup_notify_id (GAppLaunchContext *context,
 651                                             GAppInfo          *info,
 652                                             GList             *files)
 653 {
 654   GAppLaunchContextClass *class;
 655
 656   g_return_val_if_fail (G_IS_APP_LAUNCH_CONTEXT (context), NULL);
 657   g_return_val_if_fail (G_IS_APP_INFO (info), NULL);
 658
 659   class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context);
 660
 661   if (class->get_startup_notify_id == NULL)
 662     return NULL;
 663
 664   return class->get_startup_notify_id (context, info, files);
 665 }
 666
 667
 668 /**
 669  * g_app_launch_context_launch_failed:
 670  * @context: a #GAppLaunchContext.
 671  * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
 672  *
 673  * Called when an application has failed to launch, so that it can cancel
 674  * the application startup notification started in g_app_launch_context_get_startup_notify_id().
 675  *
 676  **/
 677 void
 678 g_app_launch_context_launch_failed (GAppLaunchContext *context,
 679                                     const char        *startup_notify_id)
 680 {
 681   GAppLaunchContextClass *class;
 682
 683   g_return_if_fail (G_IS_APP_LAUNCH_CONTEXT (context));
 684   g_return_if_fail (startup_notify_id != NULL);
 685
 686   class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context);
 687
 688   if (class->launch_failed != NULL)
 689     class->launch_failed (context, startup_notify_id);
 690 }
 691
 692 #define __G_APP_INFO_C__
 693 #include "gioaliasdef.c"