1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2006-2007 Red Hat, Inc.
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.
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.
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.
20 * Author: Alexander Larsson <alexl@redhat.com>
33 * @short_description: Application information and launch contexts
36 * #GAppInfo and #GAppLaunchContext are used for describing and launching
37 * applications installed on the system.
41 static void g_app_info_base_init (gpointer g_class
);
42 static void g_app_info_class_init (gpointer g_class
,
47 g_app_info_get_type (void)
49 static volatile gsize g_define_type_id__volatile
= 0;
51 if (g_once_init_enter (&g_define_type_id__volatile
))
53 const GTypeInfo app_info_info
=
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 */
65 GType g_define_type_id
=
66 g_type_register_static (G_TYPE_INTERFACE
, I_("GAppInfo"),
69 g_type_interface_add_prerequisite (g_define_type_id
, G_TYPE_OBJECT
);
71 g_once_init_leave (&g_define_type_id__volatile
, g_define_type_id
);
74 return g_define_type_id__volatile
;
78 g_app_info_class_init (gpointer g_class
,
84 g_app_info_base_init (gpointer g_class
)
91 * @appinfo: a #GAppInfo.
93 * Creates a duplicate of a #GAppInfo.
95 * Returns: a duplicate of @appinfo.
98 g_app_info_dup (GAppInfo
*appinfo
)
100 GAppInfoIface
*iface
;
102 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
104 iface
= G_APP_INFO_GET_IFACE (appinfo
);
106 return (* iface
->dup
) (appinfo
);
111 * @appinfo1: the first #GAppInfo.
112 * @appinfo2: the second #GAppInfo.
114 * Checks if two #GAppInfos are equal.
116 * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
119 g_app_info_equal (GAppInfo
*appinfo1
,
122 GAppInfoIface
*iface
;
124 g_return_val_if_fail (G_IS_APP_INFO (appinfo1
), FALSE
);
125 g_return_val_if_fail (G_IS_APP_INFO (appinfo2
), FALSE
);
127 if (G_TYPE_FROM_INSTANCE (appinfo1
) != G_TYPE_FROM_INSTANCE (appinfo2
))
130 iface
= G_APP_INFO_GET_IFACE (appinfo1
);
132 return (* iface
->equal
) (appinfo1
, appinfo2
);
137 * @appinfo: a #GAppInfo.
139 * Gets the ID of an application. An id is a string that
140 * identifies the application. The exact format of the id is
141 * platform dependent. For instance, on Unix this is the
142 * desktop file id from the xdg menu specification.
144 * Note that the returned ID may be %NULL, depending on how
145 * the @appinfo has been constructed.
147 * Returns: a string containing the application's ID.
150 g_app_info_get_id (GAppInfo
*appinfo
)
152 GAppInfoIface
*iface
;
154 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
156 iface
= G_APP_INFO_GET_IFACE (appinfo
);
158 return (* iface
->get_id
) (appinfo
);
162 * g_app_info_get_name:
163 * @appinfo: a #GAppInfo.
165 * Gets the installed name of the application.
167 * Returns: the name of the application for @appinfo.
170 g_app_info_get_name (GAppInfo
*appinfo
)
172 GAppInfoIface
*iface
;
174 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
176 iface
= G_APP_INFO_GET_IFACE (appinfo
);
178 return (* iface
->get_name
) (appinfo
);
182 * g_app_info_get_description:
183 * @appinfo: a #GAppInfo.
185 * Gets a human-readable description of an installed application.
187 * Returns: a string containing a description of the
188 * application @appinfo, or %NULL if none.
191 g_app_info_get_description (GAppInfo
*appinfo
)
193 GAppInfoIface
*iface
;
195 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
197 iface
= G_APP_INFO_GET_IFACE (appinfo
);
199 return (* iface
->get_description
) (appinfo
);
203 * g_app_info_get_executable:
204 * @appinfo: a #GAppInfo.
206 * Gets the executable's name for the installed application.
208 * Returns: a string containing the @appinfo's application
212 g_app_info_get_executable (GAppInfo
*appinfo
)
214 GAppInfoIface
*iface
;
216 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
218 iface
= G_APP_INFO_GET_IFACE (appinfo
);
220 return (* iface
->get_executable
) (appinfo
);
225 * g_app_info_set_as_default_for_type:
226 * @appinfo: a #GAppInfo.
227 * @content_type: the content type.
230 * Sets the application as the default handler for a given type.
232 * Returns: %TRUE on success, %FALSE on error.
235 g_app_info_set_as_default_for_type (GAppInfo
*appinfo
,
236 const char *content_type
,
239 GAppInfoIface
*iface
;
241 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
242 g_return_val_if_fail (content_type
!= NULL
, FALSE
);
244 iface
= G_APP_INFO_GET_IFACE (appinfo
);
246 return (* iface
->set_as_default_for_type
) (appinfo
, content_type
, error
);
251 * g_app_info_set_as_default_for_extension:
252 * @appinfo: a #GAppInfo.
253 * @extension: a string containing the file extension (without the dot).
256 * Sets the application as the default handler for the given file extention.
258 * Returns: %TRUE on success, %FALSE on error.
261 g_app_info_set_as_default_for_extension (GAppInfo
*appinfo
,
262 const char *extension
,
265 GAppInfoIface
*iface
;
267 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
268 g_return_val_if_fail (extension
!= NULL
, FALSE
);
270 iface
= G_APP_INFO_GET_IFACE (appinfo
);
272 if (iface
->set_as_default_for_extension
)
273 return (* iface
->set_as_default_for_extension
) (appinfo
, extension
, error
);
275 g_set_error_literal (error
, G_IO_ERROR
, G_IO_ERROR_NOT_SUPPORTED
,
276 "g_app_info_set_as_default_for_extension not supported yet");
282 * g_app_info_add_supports_type:
283 * @appinfo: a #GAppInfo.
284 * @content_type: a string.
287 * Adds a content type to the application information to indicate the
288 * application is capable of opening files with the given content type.
290 * Returns: %TRUE on success, %FALSE on error.
293 g_app_info_add_supports_type (GAppInfo
*appinfo
,
294 const char *content_type
,
297 GAppInfoIface
*iface
;
299 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
300 g_return_val_if_fail (content_type
!= NULL
, FALSE
);
302 iface
= G_APP_INFO_GET_IFACE (appinfo
);
304 if (iface
->add_supports_type
)
305 return (* iface
->add_supports_type
) (appinfo
, content_type
, error
);
307 g_set_error_literal (error
, G_IO_ERROR
,
308 G_IO_ERROR_NOT_SUPPORTED
,
309 "g_app_info_add_supports_type not supported yet");
316 * g_app_info_can_remove_supports_type:
317 * @appinfo: a #GAppInfo.
319 * Checks if a supported content type can be removed from an application.
321 * Returns: %TRUE if it is possible to remove supported
322 * content types from a given @appinfo, %FALSE if not.
325 g_app_info_can_remove_supports_type (GAppInfo
*appinfo
)
327 GAppInfoIface
*iface
;
329 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
331 iface
= G_APP_INFO_GET_IFACE (appinfo
);
333 if (iface
->can_remove_supports_type
)
334 return (* iface
->can_remove_supports_type
) (appinfo
);
341 * g_app_info_remove_supports_type:
342 * @appinfo: a #GAppInfo.
343 * @content_type: a string.
346 * Removes a supported type from an application, if possible.
348 * Returns: %TRUE on success, %FALSE on error.
351 g_app_info_remove_supports_type (GAppInfo
*appinfo
,
352 const char *content_type
,
355 GAppInfoIface
*iface
;
357 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
358 g_return_val_if_fail (content_type
!= NULL
, FALSE
);
360 iface
= G_APP_INFO_GET_IFACE (appinfo
);
362 if (iface
->remove_supports_type
)
363 return (* iface
->remove_supports_type
) (appinfo
, content_type
, error
);
365 g_set_error_literal (error
, G_IO_ERROR
,
366 G_IO_ERROR_NOT_SUPPORTED
,
367 "g_app_info_remove_supports_type not supported yet");
374 * g_app_info_get_icon:
375 * @appinfo: a #GAppInfo.
377 * Gets the icon for the application.
379 * Returns: the default #GIcon for @appinfo.
382 g_app_info_get_icon (GAppInfo
*appinfo
)
384 GAppInfoIface
*iface
;
386 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
388 iface
= G_APP_INFO_GET_IFACE (appinfo
);
390 return (* iface
->get_icon
) (appinfo
);
396 * @appinfo: a #GAppInfo
397 * @files: a #GList of #GFile objects
398 * @launch_context: a #GAppLaunchContext or %NULL
401 * Launches the application. Passes @files to the launched application
402 * as arguments, using the optional @launch_context to get information
403 * about the details of the launcher (like what screen it is on).
404 * On error, @error will be set accordingly.
406 * To lauch the application without arguments pass a %NULL @files list.
408 * Note that even if the launch is successful the application launched
409 * can fail to start if it runs into problems during startup. There is
410 * no way to detect this.
412 * Some URIs can be changed when passed through a GFile (for instance
413 * unsupported uris with strange formats like mailto:), so if you have
414 * a textual uri you want to pass in as argument, consider using
415 * g_app_info_launch_uris() instead.
417 * Returns: %TRUE on successful launch, %FALSE otherwise.
420 g_app_info_launch (GAppInfo
*appinfo
,
422 GAppLaunchContext
*launch_context
,
425 GAppInfoIface
*iface
;
427 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
429 iface
= G_APP_INFO_GET_IFACE (appinfo
);
431 return (* iface
->launch
) (appinfo
, files
, launch_context
, error
);
436 * g_app_info_supports_uris:
437 * @appinfo: a #GAppInfo.
439 * Checks if the application supports reading files and directories from URIs.
441 * Returns: %TRUE if the @appinfo supports URIs.
444 g_app_info_supports_uris (GAppInfo
*appinfo
)
446 GAppInfoIface
*iface
;
448 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
450 iface
= G_APP_INFO_GET_IFACE (appinfo
);
452 return (* iface
->supports_uris
) (appinfo
);
457 * g_app_info_supports_files:
458 * @appinfo: a #GAppInfo.
460 * Checks if the application accepts files as arguments.
462 * Returns: %TRUE if the @appinfo supports files.
465 g_app_info_supports_files (GAppInfo
*appinfo
)
467 GAppInfoIface
*iface
;
469 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
471 iface
= G_APP_INFO_GET_IFACE (appinfo
);
473 return (* iface
->supports_files
) (appinfo
);
478 * g_app_info_launch_uris:
479 * @appinfo: a #GAppInfo
480 * @uris: a #GList containing URIs to launch.
481 * @launch_context: a #GAppLaunchContext or %NULL
484 * Launches the application. Passes @uris to the launched application
485 * as arguments, using the optional @launch_context to get information
486 * about the details of the launcher (like what screen it is on).
487 * On error, @error will be set accordingly.
489 * To lauch the application without arguments pass a %NULL @uris list.
491 * Note that even if the launch is successful the application launched
492 * can fail to start if it runs into problems during startup. There is
493 * no way to detect this.
495 * Returns: %TRUE on successful launch, %FALSE otherwise.
498 g_app_info_launch_uris (GAppInfo
*appinfo
,
500 GAppLaunchContext
*launch_context
,
503 GAppInfoIface
*iface
;
505 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
507 iface
= G_APP_INFO_GET_IFACE (appinfo
);
509 return (* iface
->launch_uris
) (appinfo
, uris
, launch_context
, error
);
514 * g_app_info_should_show:
515 * @appinfo: a #GAppInfo.
517 * Checks if the application info should be shown in menus that
518 * list available applications.
520 * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
523 g_app_info_should_show (GAppInfo
*appinfo
)
525 GAppInfoIface
*iface
;
527 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
529 iface
= G_APP_INFO_GET_IFACE (appinfo
);
531 return (* iface
->should_show
) (appinfo
);
535 * g_app_info_launch_default_for_uri:
536 * @uri: the uri to show
537 * @launch_context: an optional #GAppLaunchContext.
540 * Utility function that launches the default application
541 * registered to handle the specified uri. Synchronous I/O
542 * is done on the uri to detext the type of the file if
545 * Returns: %TRUE on success, %FALSE on error.
548 g_app_info_launch_default_for_uri (const char *uri
,
549 GAppLaunchContext
*launch_context
,
557 file
= g_file_new_for_uri (uri
);
558 app_info
= g_file_query_default_handler (file
, NULL
, error
);
559 g_object_unref (file
);
560 if (app_info
== NULL
)
563 /* Use the uri, not the GFile, as the GFile roundtrip may
564 * affect the uri which we don't want (for instance for a
567 l
.data
= (char *)uri
;
568 l
.next
= l
.prev
= NULL
;
569 res
= g_app_info_launch_uris (app_info
, &l
,
570 launch_context
, error
);
572 g_object_unref (app_info
);
578 G_DEFINE_TYPE (GAppLaunchContext
, g_app_launch_context
, G_TYPE_OBJECT
);
581 * g_app_launch_context_new:
583 * Creates a new application launch context. This is not normally used,
584 * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
586 * Returns: a #GAppLaunchContext.
589 g_app_launch_context_new (void)
591 return g_object_new (G_TYPE_APP_LAUNCH_CONTEXT
, NULL
);
595 g_app_launch_context_class_init (GAppLaunchContextClass
*klass
)
600 g_app_launch_context_init (GAppLaunchContext
*launch_context
)
605 * g_app_launch_context_get_display:
606 * @context: a #GAppLaunchContext
608 * @files: a #GList of #GFile objects
610 * Gets the display string for the display. This is used to ensure new
611 * applications are started on the same display as the launching
614 * Returns: a display string for the display.
617 g_app_launch_context_get_display (GAppLaunchContext
*context
,
621 GAppLaunchContextClass
*class;
623 g_return_val_if_fail (G_IS_APP_LAUNCH_CONTEXT (context
), NULL
);
624 g_return_val_if_fail (G_IS_APP_INFO (info
), NULL
);
626 class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context
);
628 if (class->get_display
== NULL
)
631 return class->get_display (context
, info
, files
);
635 * g_app_launch_context_get_startup_notify_id:
636 * @context: a #GAppLaunchContext
638 * @files: a #GList of of #GFile objects
640 * Initiates startup notification for the application and returns the
641 * DESKTOP_STARTUP_ID for the launched operation, if supported.
643 * Startup notification IDs are defined in the <ulink
644 * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
645 * FreeDesktop.Org Startup Notifications standard</ulink>.
647 * Returns: a startup notification ID for the application, or %NULL if
651 g_app_launch_context_get_startup_notify_id (GAppLaunchContext
*context
,
655 GAppLaunchContextClass
*class;
657 g_return_val_if_fail (G_IS_APP_LAUNCH_CONTEXT (context
), NULL
);
658 g_return_val_if_fail (G_IS_APP_INFO (info
), NULL
);
660 class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context
);
662 if (class->get_startup_notify_id
== NULL
)
665 return class->get_startup_notify_id (context
, info
, files
);
670 * g_app_launch_context_launch_failed:
671 * @context: a #GAppLaunchContext.
672 * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
674 * Called when an application has failed to launch, so that it can cancel
675 * the application startup notification started in g_app_launch_context_get_startup_notify_id().
679 g_app_launch_context_launch_failed (GAppLaunchContext
*context
,
680 const char *startup_notify_id
)
682 GAppLaunchContextClass
*class;
684 g_return_if_fail (G_IS_APP_LAUNCH_CONTEXT (context
));
685 g_return_if_fail (startup_notify_id
!= NULL
);
687 class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context
);
689 if (class->launch_failed
!= NULL
)
690 class->launch_failed (context
, startup_notify_id
);
693 #define __G_APP_INFO_C__
694 #include "gioaliasdef.c"