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 GType app_info_type
= 0;
53 static 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 */
67 g_type_register_static (G_TYPE_INTERFACE
, I_("GAppInfo"),
70 g_type_interface_add_prerequisite (app_info_type
, G_TYPE_OBJECT
);
77 g_app_info_class_init (gpointer g_class
,
83 g_app_info_base_init (gpointer g_class
)
90 * @appinfo: a #GAppInfo.
92 * Creates a duplicate of a #GAppInfo.
94 * Returns: a duplicate of @appinfo.
97 g_app_info_dup (GAppInfo
*appinfo
)
101 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
103 iface
= G_APP_INFO_GET_IFACE (appinfo
);
105 return (* iface
->dup
) (appinfo
);
110 * @appinfo1: the first #GAppInfo.
111 * @appinfo2: the second #GAppInfo.
113 * Checks if two #GAppInfos are equal.
115 * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
118 g_app_info_equal (GAppInfo
*appinfo1
,
121 GAppInfoIface
*iface
;
123 g_return_val_if_fail (G_IS_APP_INFO (appinfo1
), FALSE
);
124 g_return_val_if_fail (G_IS_APP_INFO (appinfo2
), FALSE
);
126 if (G_TYPE_FROM_INSTANCE (appinfo1
) != G_TYPE_FROM_INSTANCE (appinfo2
))
129 iface
= G_APP_INFO_GET_IFACE (appinfo1
);
131 return (* iface
->equal
) (appinfo1
, appinfo2
);
136 * @appinfo: a #GAppInfo.
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.
143 * Note that the returned ID may be %NULL, depending on how
144 * the @appinfo has been constructed.
146 * Returns: a string containing the application's ID.
149 g_app_info_get_id (GAppInfo
*appinfo
)
151 GAppInfoIface
*iface
;
153 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
155 iface
= G_APP_INFO_GET_IFACE (appinfo
);
157 return (* iface
->get_id
) (appinfo
);
161 * g_app_info_get_name:
162 * @appinfo: a #GAppInfo.
164 * Gets the installed name of the application.
166 * Returns: the name of the application for @appinfo.
169 g_app_info_get_name (GAppInfo
*appinfo
)
171 GAppInfoIface
*iface
;
173 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
175 iface
= G_APP_INFO_GET_IFACE (appinfo
);
177 return (* iface
->get_name
) (appinfo
);
181 * g_app_info_get_description:
182 * @appinfo: a #GAppInfo.
184 * Gets a human-readable description of an installed application.
186 * Returns: a string containing a description of the
187 * application @appinfo, or %NULL if none.
190 g_app_info_get_description (GAppInfo
*appinfo
)
192 GAppInfoIface
*iface
;
194 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
196 iface
= G_APP_INFO_GET_IFACE (appinfo
);
198 return (* iface
->get_description
) (appinfo
);
202 * g_app_info_get_executable:
203 * @appinfo: a #GAppInfo.
205 * Gets the executable's name for the installed application.
207 * Returns: a string containing the @appinfo's application
211 g_app_info_get_executable (GAppInfo
*appinfo
)
213 GAppInfoIface
*iface
;
215 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
217 iface
= G_APP_INFO_GET_IFACE (appinfo
);
219 return (* iface
->get_executable
) (appinfo
);
224 * g_app_info_set_as_default_for_type:
225 * @appinfo: a #GAppInfo.
226 * @content_type: the content type.
229 * Sets the application as the default handler for a given type.
231 * Returns: %TRUE on success, %FALSE on error.
234 g_app_info_set_as_default_for_type (GAppInfo
*appinfo
,
235 const char *content_type
,
238 GAppInfoIface
*iface
;
240 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
241 g_return_val_if_fail (content_type
!= NULL
, FALSE
);
243 iface
= G_APP_INFO_GET_IFACE (appinfo
);
245 return (* iface
->set_as_default_for_type
) (appinfo
, content_type
, error
);
250 * g_app_info_set_as_default_for_extension:
251 * @appinfo: a #GAppInfo.
252 * @extension: a string containing the file extension (without the dot).
255 * Sets the application as the default handler for the given file extention.
257 * Returns: %TRUE on success, %FALSE on error.
260 g_app_info_set_as_default_for_extension (GAppInfo
*appinfo
,
261 const char *extension
,
264 GAppInfoIface
*iface
;
266 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
267 g_return_val_if_fail (extension
!= NULL
, FALSE
);
269 iface
= G_APP_INFO_GET_IFACE (appinfo
);
271 if (iface
->set_as_default_for_extension
)
272 return (* iface
->set_as_default_for_extension
) (appinfo
, extension
, error
);
274 g_set_error (error
, G_IO_ERROR
, G_IO_ERROR_NOT_SUPPORTED
, "g_app_info_set_as_default_for_extension not supported yet");
280 * g_app_info_add_supports_type:
281 * @appinfo: a #GAppInfo.
282 * @content_type: a string.
285 * Adds a content type to the application information to indicate the
286 * application is capable of opening files with the given content type.
288 * Returns: %TRUE on success, %FALSE on error.
291 g_app_info_add_supports_type (GAppInfo
*appinfo
,
292 const char *content_type
,
295 GAppInfoIface
*iface
;
297 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
298 g_return_val_if_fail (content_type
!= NULL
, FALSE
);
300 iface
= G_APP_INFO_GET_IFACE (appinfo
);
302 if (iface
->add_supports_type
)
303 return (* iface
->add_supports_type
) (appinfo
, content_type
, error
);
305 g_set_error (error
, G_IO_ERROR
,
306 G_IO_ERROR_NOT_SUPPORTED
,
307 "g_app_info_add_supports_type not supported yet");
314 * g_app_info_can_remove_supports_type:
315 * @appinfo: a #GAppInfo.
317 * Checks if a supported content type can be removed from an application.
319 * Returns: %TRUE if it is possible to remove supported
320 * content types from a given @appinfo, %FALSE if not.
323 g_app_info_can_remove_supports_type (GAppInfo
*appinfo
)
325 GAppInfoIface
*iface
;
327 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
329 iface
= G_APP_INFO_GET_IFACE (appinfo
);
331 if (iface
->can_remove_supports_type
)
332 return (* iface
->can_remove_supports_type
) (appinfo
);
339 * g_app_info_remove_supports_type:
340 * @appinfo: a #GAppInfo.
341 * @content_type: a string.
344 * Removes a supported type from an application, if possible.
346 * Returns: %TRUE on success, %FALSE on error.
349 g_app_info_remove_supports_type (GAppInfo
*appinfo
,
350 const char *content_type
,
353 GAppInfoIface
*iface
;
355 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
356 g_return_val_if_fail (content_type
!= NULL
, FALSE
);
358 iface
= G_APP_INFO_GET_IFACE (appinfo
);
360 if (iface
->remove_supports_type
)
361 return (* iface
->remove_supports_type
) (appinfo
, content_type
, error
);
363 g_set_error (error
, G_IO_ERROR
,
364 G_IO_ERROR_NOT_SUPPORTED
,
365 "g_app_info_remove_supports_type not supported yet");
372 * g_app_info_get_icon:
373 * @appinfo: a #GAppInfo.
375 * Gets the icon for the application.
377 * Returns: the default #GIcon for @appinfo.
380 g_app_info_get_icon (GAppInfo
*appinfo
)
382 GAppInfoIface
*iface
;
384 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), NULL
);
386 iface
= G_APP_INFO_GET_IFACE (appinfo
);
388 return (* iface
->get_icon
) (appinfo
);
394 * @appinfo: a #GAppInfo.
395 * @files: a #GList of #GFile objects.
396 * @launch_context: a #GAppLaunchContext.
399 * Launches the application. Passes @files to the launched application
400 * as arguments, using the optional @launch_context to get information
401 * about the details of the launcher (like what screen it is on).
402 * On error, @error will be set accordingly.
404 * To lauch the application without arguments pass a %NULL @files list.
406 * Note that even if the launch is successful the application launched
407 * can fail to start if it runs into problems during startup. There is
408 * no way to detect this.
410 * Some URIs can be changed when passed through a GFile (for instance
411 * unsupported uris with strange formats like mailto:), so if you have
412 * a textual uri you want to pass in as argument, consider using
413 * g_app_info_launch_uris() instead.
415 * Returns: %TRUE on successful launch, %FALSE otherwise.
418 g_app_info_launch (GAppInfo
*appinfo
,
420 GAppLaunchContext
*launch_context
,
423 GAppInfoIface
*iface
;
425 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
427 iface
= G_APP_INFO_GET_IFACE (appinfo
);
429 return (* iface
->launch
) (appinfo
, files
, launch_context
, error
);
434 * g_app_info_supports_uris:
435 * @appinfo: a #GAppInfo.
437 * Checks if the application supports reading files and directories from URIs.
439 * Returns: %TRUE if the @appinfo supports URIs.
442 g_app_info_supports_uris (GAppInfo
*appinfo
)
444 GAppInfoIface
*iface
;
446 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
448 iface
= G_APP_INFO_GET_IFACE (appinfo
);
450 return (* iface
->supports_uris
) (appinfo
);
455 * g_app_info_supports_files:
456 * @appinfo: a #GAppInfo.
458 * Checks if the application accepts files as arguments.
460 * Returns: %TRUE if the @appinfo supports files.
463 g_app_info_supports_files (GAppInfo
*appinfo
)
465 GAppInfoIface
*iface
;
467 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
469 iface
= G_APP_INFO_GET_IFACE (appinfo
);
471 return (* iface
->supports_files
) (appinfo
);
476 * g_app_info_launch_uris:
477 * @appinfo: a #GAppInfo.
478 * @uris: a #GList containing URIs to launch.
479 * @launch_context: a #GAppLaunchContext.
482 * Launches the application. Passes @uris to the launched application
483 * as arguments, using the optional @launch_context to get information
484 * about the details of the launcher (like what screen it is on).
485 * On error, @error will be set accordingly.
487 * To lauch the application without arguments pass a %NULL @uris list.
489 * Note that even if the launch is successful the application launched
490 * can fail to start if it runs into problems during startup. There is
491 * no way to detect this.
493 * Returns: %TRUE on successful launch, %FALSE otherwise.
496 g_app_info_launch_uris (GAppInfo
*appinfo
,
498 GAppLaunchContext
*launch_context
,
501 GAppInfoIface
*iface
;
503 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
505 iface
= G_APP_INFO_GET_IFACE (appinfo
);
507 return (* iface
->launch_uris
) (appinfo
, uris
, launch_context
, error
);
512 * g_app_info_should_show:
513 * @appinfo: a #GAppInfo.
515 * Checks if the application info should be shown in menus that
516 * list available applications.
518 * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
521 g_app_info_should_show (GAppInfo
*appinfo
)
523 GAppInfoIface
*iface
;
525 g_return_val_if_fail (G_IS_APP_INFO (appinfo
), FALSE
);
527 iface
= G_APP_INFO_GET_IFACE (appinfo
);
529 return (* iface
->should_show
) (appinfo
);
533 * g_app_info_launch_default_for_uri:
534 * @uri: the uri to show
535 * @launch_context: an optional #GAppLaunchContext.
538 * Utility function that launches the default application
539 * registered to handle the specified uri. Synchronous I/O
540 * is done on the uri to detext the type of the file if
543 * Returns: %TRUE on success, %FALSE on error.
546 g_app_info_launch_default_for_uri (const char *uri
,
547 GAppLaunchContext
*launch_context
,
555 file
= g_file_new_for_uri (uri
);
556 app_info
= g_file_query_default_handler (file
, NULL
, error
);
557 g_object_unref (file
);
558 if (app_info
== NULL
)
561 /* Use the uri, not the GFile, as the GFile roundtrip may
562 * affect the uri which we don't want (for instance for a
565 l
.data
= (char *)uri
;
566 l
.next
= l
.prev
= NULL
;
567 res
= g_app_info_launch_uris (app_info
, &l
,
568 launch_context
, error
);
570 g_object_unref (app_info
);
576 G_DEFINE_TYPE (GAppLaunchContext
, g_app_launch_context
, G_TYPE_OBJECT
);
579 * g_app_launch_context_new:
581 * Creates a new application launch context. This is not normally used,
582 * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
584 * Returns: a #GAppLaunchContext.
587 g_app_launch_context_new (void)
589 return g_object_new (G_TYPE_APP_LAUNCH_CONTEXT
, NULL
);
593 g_app_launch_context_class_init (GAppLaunchContextClass
*klass
)
598 g_app_launch_context_init (GAppLaunchContext
*launch_context
)
603 * g_app_launch_context_get_display:
604 * @context: a #GAppLaunchContext.
605 * @info: a #GAppInfo.
606 * @files: a #GList of files.
608 * Gets the display string for the display. This is used to ensure new
609 * applications are started on the same display as the launching
612 * Returns: a display string for the display.
615 g_app_launch_context_get_display (GAppLaunchContext
*context
,
619 GAppLaunchContextClass
*class;
621 g_return_val_if_fail (G_IS_APP_LAUNCH_CONTEXT (context
), NULL
);
622 g_return_val_if_fail (G_IS_APP_INFO (info
), NULL
);
624 class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context
);
626 if (class->get_display
== NULL
)
629 return class->get_display (context
, info
, files
);
633 * g_app_launch_context_get_startup_notify_id:
634 * @context: a #GAppLaunchContext.
635 * @info: a #GAppInfo.
636 * @files: a #GList of files.
638 * Initiates startup notification for the applicaiont and returns the
639 * DESKTOP_STARTUP_ID for the launched operation, if supported.
641 * Startup notification IDs are defined in the FreeDesktop.Org Startup
642 * Notifications standard, at
643 * <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"/>.
645 * Returns: a startup notification ID for the application, or %NULL if
649 g_app_launch_context_get_startup_notify_id (GAppLaunchContext
*context
,
653 GAppLaunchContextClass
*class;
655 g_return_val_if_fail (G_IS_APP_LAUNCH_CONTEXT (context
), NULL
);
656 g_return_val_if_fail (G_IS_APP_INFO (info
), NULL
);
658 class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context
);
660 if (class->get_startup_notify_id
== NULL
)
663 return class->get_startup_notify_id (context
, info
, files
);
668 * g_app_launch_context_launch_failed:
669 * @context: a #GAppLaunchContext.
670 * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
672 * Called when an application has failed to launch, so that it can cancel
673 * the application startup notification started in g_app_launch_context_get_startup_notify_id().
677 g_app_launch_context_launch_failed (GAppLaunchContext
*context
,
678 const char *startup_notify_id
)
680 GAppLaunchContextClass
*class;
682 g_return_if_fail (G_IS_APP_LAUNCH_CONTEXT (context
));
683 g_return_if_fail (startup_notify_id
!= NULL
);
685 class = G_APP_LAUNCH_CONTEXT_GET_CLASS (context
);
687 if (class->launch_failed
!= NULL
)
688 class->launch_failed (context
, startup_notify_id
);
691 #define __G_APP_INFO_C__
692 #include "gioaliasdef.c"