* Author: Alexander Larsson <alexl@redhat.com>
*/
-#include <config.h>
+#include "config.h"
#include "gappinfo.h"
#include "glibintl.h"
#include <gioerror.h>
+#include <gfile.h>
#include "gioalias.h"
/**
* SECTION:gappinfo
* @short_description: Application information and launch contexts
- * @include: gio.h
+ * @include: gio/gio.h
*
* #GAppInfo and #GAppLaunchContext are used for describing and launching
- * applications installed on the system.
+ * applications installed on the system.
+ *
+ * As of GLib 2.20, URIs will always be converted to POSIX paths
+ * (using g_file_get_path()) when using g_app_info_launch() even if
+ * the application requested an URI and not a POSIX path. For example
+ * for an desktop-file based application with Exec key <literal>totem
+ * %%U</literal> and a single URI,
+ * <literal>sftp://foo/file.avi</literal>, then
+ * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> will be
+ * passed. This will only work if a set of suitable GIO extensions
+ * (such as gvfs 2.26 compiled with FUSE support), is available and
+ * operational; if this is not the case, the URI will be passed
+ * unmodified to the application. Some URIs, such as
+ * <literal>mailto:</literal>, of course cannot be mapped to a POSIX
+ * path (in gvfs there's no FUSE mount for it); such URIs will be
+ * passed unmodified to the application.
+ *
+ * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
+ * back to the GIO URI in the #GFile constructors (since gvfs
+ * implements the #GVfs extension point). As such, if the application
+ * needs to examine the URI, it needs to use g_file_get_uri() or
+ * similar on #GFile. In other words, an application cannot assume
+ * that the URI passed to e.g. g_file_new_for_commandline_arg() is
+ * equal to the result of g_file_get_uri(). The following snippet
+ * illustrates this:
+ *
+ * <programlisting>
+ * GFile *f;
+ * char *uri;
+ *
+ * file = g_file_new_for_commandline_arg (uri_from_commandline);
+ *
+ * uri = g_file_get_uri (file);
+ * strcmp (uri, uri_from_commandline) == 0; // FALSE
+ * g_free (uri);
+ *
+ * if (g_file_has_uri_scheme (file, "cdda"))
+ * {
+ * // do something special with uri
+ * }
+ * g_object_unref (file);
+ * </programlisting>
+ *
+ * This code will work when both <literal>cdda://sr0/Track
+ * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track
+ * 1.wav</literal> is passed to the application. It should be noted
+ * that it's generally not safe for applications to rely on the format
+ * of a particular URIs. Different launcher applications (e.g. file
+ * managers) may have different ideas of what a given URI means.
*
**/
-static void g_app_info_base_init (gpointer g_class);
-static void g_app_info_class_init (gpointer g_class,
- gpointer class_data);
-
-
-GType
-g_app_info_get_type (void)
-{
- static GType app_info_type = 0;
-
- if (! app_info_type)
- {
- static const GTypeInfo app_info_info =
- {
- sizeof (GAppInfoIface), /* class_size */
- g_app_info_base_init, /* base_init */
- NULL, /* base_finalize */
- g_app_info_class_init,
- NULL, /* class_finalize */
- NULL, /* class_data */
- 0,
- 0, /* n_preallocs */
- NULL
- };
-
- app_info_type =
- g_type_register_static (G_TYPE_INTERFACE, I_("GAppInfo"),
- &app_info_info, 0);
-
- g_type_interface_add_prerequisite (app_info_type, G_TYPE_OBJECT);
- }
-
- return app_info_type;
-}
-
-static void
-g_app_info_class_init (gpointer g_class,
- gpointer class_data)
-{
-}
+typedef GAppInfoIface GAppInfoInterface;
+G_DEFINE_INTERFACE (GAppInfo, g_app_info, G_TYPE_OBJECT)
static void
-g_app_info_base_init (gpointer g_class)
+g_app_info_default_init (GAppInfoInterface *iface)
{
}
* @appinfo1: the first #GAppInfo.
* @appinfo2: the second #GAppInfo.
*
- * Checks if two #GAppInfos are equal.
+ * Checks if two #GAppInfo<!-- -->s are equal.
*
* Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
**/
*
* Gets the ID of an application. An id is a string that
* identifies the application. The exact format of the id is
- * platform dependent. For instance on Unix this is the
+ * platform dependent. For instance, on Unix this is the
* desktop file id from the xdg menu specification.
*
* Note that the returned ID may be %NULL, depending on how
}
/**
+ * g_app_info_get_display_name:
+ * @appinfo: a #GAppInfo.
+ *
+ * Gets the display name of the application. The display name is often more
+ * descriptive to the user than the name itself.
+ *
+ * Returns: the display name of the application for @appinfo, or the name if
+ * no display name is available.
+ *
+ * Since: 2.24
+ **/
+const char *
+g_app_info_get_display_name (GAppInfo *appinfo)
+{
+ GAppInfoIface *iface;
+
+ g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
+
+ iface = G_APP_INFO_GET_IFACE (appinfo);
+
+ if (iface->get_display_name == NULL)
+ return (* iface->get_name) (appinfo);
+
+ return (* iface->get_display_name) (appinfo);
+}
+
+/**
* g_app_info_get_description:
* @appinfo: a #GAppInfo.
*
/**
* g_app_info_get_executable:
- * @appinfo: a #GAppInfo.
+ * @appinfo: a #GAppInfo
*
* Gets the executable's name for the installed application.
*
* Returns: a string containing the @appinfo's application
- * binary's name.
+ * binaries name
**/
const char *
g_app_info_get_executable (GAppInfo *appinfo)
/**
+ * g_app_info_get_commandline:
+ * @appinfo: a #GAppInfo
+ *
+ * Gets the commandline with which the application will be
+ * started.
+ *
+ * Returns: a string containing the @appinfo's commandline,
+ * or %NULL if this information is not available
+ *
+ * Since: 2.20
+ **/
+const char *
+g_app_info_get_commandline (GAppInfo *appinfo)
+{
+ GAppInfoIface *iface;
+
+ g_return_val_if_fail (G_IS_APP_INFO (appinfo), NULL);
+
+ iface = G_APP_INFO_GET_IFACE (appinfo);
+
+ if (iface->get_commandline)
+ return (* iface->get_commandline) (appinfo);
+
+ return NULL;
+}
+
+/**
* g_app_info_set_as_default_for_type:
* @appinfo: a #GAppInfo.
* @content_type: the content type.
* @extension: a string containing the file extension (without the dot).
* @error: a #GError.
*
- * Sets the application as the default handler for the given file extention.
+ * Sets the application as the default handler for the given file extension.
*
* Returns: %TRUE on success, %FALSE on error.
**/
if (iface->set_as_default_for_extension)
return (* iface->set_as_default_for_extension) (appinfo, extension, error);
- g_set_error (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED, "g_app_info_set_as_default_for_extension not supported yet");
+ g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
+ "g_app_info_set_as_default_for_extension not supported yet");
return FALSE;
}
if (iface->add_supports_type)
return (* iface->add_supports_type) (appinfo, content_type, error);
- g_set_error (error, G_IO_ERROR,
- G_IO_ERROR_NOT_SUPPORTED,
- "g_app_info_add_supports_type not supported yet");
+ g_set_error_literal (error, G_IO_ERROR,
+ G_IO_ERROR_NOT_SUPPORTED,
+ "g_app_info_add_supports_type not supported yet");
return FALSE;
}
if (iface->remove_supports_type)
return (* iface->remove_supports_type) (appinfo, content_type, error);
- g_set_error (error, G_IO_ERROR,
- G_IO_ERROR_NOT_SUPPORTED,
- "g_app_info_remove_supports_type not supported yet");
+ g_set_error_literal (error, G_IO_ERROR,
+ G_IO_ERROR_NOT_SUPPORTED,
+ "g_app_info_remove_supports_type not supported yet");
return FALSE;
}
/**
* g_app_info_launch:
- * @appinfo: a #GAppInfo.
- * @files: a #GList of #GFile objects.
- * @launch_context: a #GAppLaunchContext.
- * @error: a #GError.
+ * @appinfo: a #GAppInfo
+ * @files: a #GList of #GFile objects
+ * @launch_context: a #GAppLaunchContext or %NULL
+ * @error: a #GError
*
* Launches the application. Passes @files to the launched application
* as arguments, using the optional @launch_context to get information
- * about the details of the launcher (like what screen its is on).
+ * about the details of the launcher (like what screen it is on).
* On error, @error will be set accordingly.
*
* To lauch the application without arguments pass a %NULL @files list.
* can fail to start if it runs into problems during startup. There is
* no way to detect this.
*
+ * Some URIs can be changed when passed through a GFile (for instance
+ * unsupported uris with strange formats like mailto:), so if you have
+ * a textual uri you want to pass in as argument, consider using
+ * g_app_info_launch_uris() instead.
+ *
* Returns: %TRUE on successful launch, %FALSE otherwise.
**/
gboolean
/**
- * g_app_info_launch_uris:
+ * g_app_info_supports_files:
* @appinfo: a #GAppInfo.
+ *
+ * Checks if the application accepts files as arguments.
+ *
+ * Returns: %TRUE if the @appinfo supports files.
+ **/
+gboolean
+g_app_info_supports_files (GAppInfo *appinfo)
+{
+ GAppInfoIface *iface;
+
+ g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
+
+ iface = G_APP_INFO_GET_IFACE (appinfo);
+
+ return (* iface->supports_files) (appinfo);
+}
+
+
+/**
+ * g_app_info_launch_uris:
+ * @appinfo: a #GAppInfo
* @uris: a #GList containing URIs to launch.
- * @launch_context: a #GAppLaunchContext.
- * @error: a #GError.
+ * @launch_context: a #GAppLaunchContext or %NULL
+ * @error: a #GError
*
* Launches the application. Passes @uris to the launched application
* as arguments, using the optional @launch_context to get information
- * about the details of the launcher (like what screen its is on).
+ * about the details of the launcher (like what screen it is on).
* On error, @error will be set accordingly.
*
* To lauch the application without arguments pass a %NULL @uris list.
iface = G_APP_INFO_GET_IFACE (appinfo);
- return (* iface->launch) (appinfo, uris, launch_context, error);
+ return (* iface->launch_uris) (appinfo, uris, launch_context, error);
}
/**
* g_app_info_should_show:
* @appinfo: a #GAppInfo.
- * @desktop_env: A string specifying what desktop this is, or %NULL.
- *
- * Checks if the application info should be shown when listing
- * applications available.
*
- * @destkop_env is used to hide applications that are specified to
- * just show up in specific desktops. For instance, passing in "GNOME"
- * would show all applications specific to the Gnome desktop.
+ * Checks if the application info should be shown in menus that
+ * list available applications.
*
* Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
**/
gboolean
-g_app_info_should_show (GAppInfo *appinfo,
- const char *desktop_env)
+g_app_info_should_show (GAppInfo *appinfo)
+{
+ GAppInfoIface *iface;
+
+ g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
+
+ iface = G_APP_INFO_GET_IFACE (appinfo);
+
+ return (* iface->should_show) (appinfo);
+}
+
+/**
+ * g_app_info_launch_default_for_uri:
+ * @uri: the uri to show
+ * @launch_context: an optional #GAppLaunchContext.
+ * @error: a #GError.
+ *
+ * Utility function that launches the default application
+ * registered to handle the specified uri. Synchronous I/O
+ * is done on the uri to detect the type of the file if
+ * required.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ **/
+gboolean
+g_app_info_launch_default_for_uri (const char *uri,
+ GAppLaunchContext *launch_context,
+ GError **error)
+{
+ GAppInfo *app_info;
+ GFile *file;
+ GList l;
+ gboolean res;
+
+ file = g_file_new_for_uri (uri);
+ app_info = g_file_query_default_handler (file, NULL, error);
+ g_object_unref (file);
+ if (app_info == NULL)
+ return FALSE;
+
+ /* Use the uri, not the GFile, as the GFile roundtrip may
+ * affect the uri which we don't want (for instance for a
+ * mailto: uri).
+ */
+ l.data = (char *)uri;
+ l.next = l.prev = NULL;
+ res = g_app_info_launch_uris (app_info, &l,
+ launch_context, error);
+
+ g_object_unref (app_info);
+
+ return res;
+}
+
+/**
+ * g_app_info_can_delete:
+ * @appinfo: a #GAppInfo
+ *
+ * Obtains the information whether the #GAppInfo can be deleted.
+ * See g_app_info_delete().
+ *
+ * Returns: %TRUE if @appinfo can be deleted
+ *
+ * Since: 2.20
+ */
+gboolean
+g_app_info_can_delete (GAppInfo *appinfo)
+{
+ GAppInfoIface *iface;
+
+ g_return_val_if_fail (G_IS_APP_INFO (appinfo), FALSE);
+
+ iface = G_APP_INFO_GET_IFACE (appinfo);
+
+ if (iface->can_delete)
+ return (* iface->can_delete) (appinfo);
+
+ return FALSE;
+}
+
+
+/**
+ * g_app_info_delete:
+ * @appinfo: a #GAppInfo
+ *
+ * Tries to delete a #GAppInfo.
+ *
+ * On some platforms, there may be a difference between user-defined
+ * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which
+ * cannot. See g_app_info_can_delete().
+ *
+ * Returns: %TRUE if @appinfo has been deleted
+ *
+ * Since: 2.20
+ */
+gboolean
+g_app_info_delete (GAppInfo *appinfo)
{
GAppInfoIface *iface;
iface = G_APP_INFO_GET_IFACE (appinfo);
- return (* iface->should_show) (appinfo, desktop_env);
+ if (iface->do_delete)
+ return (* iface->do_delete) (appinfo);
+
+ return FALSE;
}
+
G_DEFINE_TYPE (GAppLaunchContext, g_app_launch_context, G_TYPE_OBJECT);
/**
/**
* g_app_launch_context_get_display:
- * @context: a #GAppLaunchContext.
- * @info: a #GAppInfo.
- * @files: a #GList of files.
+ * @context: a #GAppLaunchContext
+ * @info: a #GAppInfo
+ * @files: a #GList of #GFile objects
*
* Gets the display string for the display. This is used to ensure new
* applications are started on the same display as the launching
/**
* g_app_launch_context_get_startup_notify_id:
- * @context: a #GAppLaunchContext.
- * @info: a #GAppInfo.
- * @files: a #GList of files.
+ * @context: a #GAppLaunchContext
+ * @info: a #GAppInfo
+ * @files: a #GList of of #GFile objects
*
- * Initiates startup notification for the applicaiont and returns the
+ * Initiates startup notification for the application and returns the
* DESKTOP_STARTUP_ID for the launched operation, if supported.
*
- * Startup notification IDs are defined in the FreeDesktop.Org Startup
- * Notifications standard, at
- * <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"/>.
+ * Startup notification IDs are defined in the <ulink
+ * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
+ * FreeDesktop.Org Startup Notifications standard</ulink>.
*
* Returns: a startup notification ID for the application, or %NULL if
* not supported.
class->launch_failed (context, startup_notify_id);
}
+
#define __G_APP_INFO_C__
#include "gioaliasdef.c"