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