From c474d4065dbda1220fae731e874ae5b1915a7074 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 24 Jul 2024 14:23:18 +0200 Subject: [PATCH 1/6] gdesktopappinfo: Port doc comments to gi-docgen syntax Signed-off-by: Philip Withnall Helps: #3250 --- gio/gdesktopappinfo.c | 289 +++++++++++++++++++++--------------------- 1 file changed, 146 insertions(+), 143 deletions(-) diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c index 640057a06..7276a79d0 100644 --- a/gio/gdesktopappinfo.c +++ b/gio/gdesktopappinfo.c @@ -1777,7 +1777,7 @@ g_desktop_app_info_class_init (GDesktopAppInfoClass *klass) /** * GDesktopAppInfo:filename: * - * The origin filename of this #GDesktopAppInfo + * The origin filename of this [class@Gio.DesktopAppInfo] */ g_object_class_install_property (gobject_class, PROP_FILENAME, @@ -2064,11 +2064,11 @@ g_desktop_app_info_load_file (GDesktopAppInfo *self) /** * g_desktop_app_info_new_from_keyfile: - * @key_file: an opened #GKeyFile + * @key_file: an opened [type@GLib.KeyFile] * - * Creates a new #GDesktopAppInfo. + * Creates a new [class@Gio.DesktopAppInfo]. * - * Returns: (nullable): a new #GDesktopAppInfo or %NULL on error. + * Returns: (nullable): a new [class@Gio.DesktopAppInfo] or `NULL` on error. * * Since: 2.18 **/ @@ -2095,9 +2095,9 @@ g_desktop_app_info_new_from_keyfile (GKeyFile *key_file) * @filename: (type filename): the path of a desktop file, in the GLib * filename encoding * - * Creates a new #GDesktopAppInfo. + * Creates a new [class@Gio.DesktopAppInfo]. * - * Returns: (nullable): a new #GDesktopAppInfo or %NULL on error. + * Returns: (nullable): a new [class@Gio.DesktopAppInfo] or `NULL` on error. **/ GDesktopAppInfo * g_desktop_app_info_new_from_filename (const char *filename) @@ -2115,22 +2115,22 @@ g_desktop_app_info_new_from_filename (const char *filename) /** * g_desktop_app_info_new: - * @desktop_id: the desktop file id + * @desktop_id: the desktop file ID * - * Creates a new #GDesktopAppInfo based on a desktop file id. + * Creates a new [class@Gio.DesktopAppInfo] based on a desktop file ID. * - * A desktop file id is the basename of the desktop file, including the - * .desktop extension. GIO is looking for a desktop file with this name + * A desktop file ID is the basename of the desktop file, including the + * `.desktop` extension. GIO is looking for a desktop file with this name * in the `applications` subdirectories of the XDG * data directories (i.e. the directories specified in the `XDG_DATA_HOME` * and `XDG_DATA_DIRS` environment variables). GIO also supports the * prefix-to-subdirectory mapping that is described in the * [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/) - * (i.e. a desktop id of kde-foo.desktop will match + * (i.e. a desktop ID of `kde-foo.desktop` will match * `/usr/share/applications/kde/foo.desktop`). * - * Returns: (nullable): a new #GDesktopAppInfo, or %NULL if no desktop - * file with that id exists. + * Returns: (nullable): a new [class@Gio.DesktopAppInfo], or `NULL` if no + * desktop file with that ID exists. */ GDesktopAppInfo * g_desktop_app_info_new (const char *desktop_id) @@ -2248,12 +2248,12 @@ g_desktop_app_info_get_display_name (GAppInfo *appinfo) /** * g_desktop_app_info_get_is_hidden: - * @info: a #GDesktopAppInfo. + * @info: a [class@Gio.DesktopAppInfo]. * - * A desktop file is hidden if the Hidden key in it is - * set to True. + * A desktop file is hidden if the `Hidden` key in it is + * set to `True`. * - * Returns: %TRUE if hidden, %FALSE otherwise. + * Returns: `TRUE` if hidden, `FALSE` otherwise. **/ gboolean g_desktop_app_info_get_is_hidden (GDesktopAppInfo *info) @@ -2263,14 +2263,14 @@ g_desktop_app_info_get_is_hidden (GDesktopAppInfo *info) /** * g_desktop_app_info_get_filename: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * * When @info was created from a known filename, return it. In some - * situations such as the #GDesktopAppInfo returned from - * g_desktop_app_info_new_from_keyfile(), this function will return %NULL. + * situations such as a [class@Gio.DesktopAppInfo] returned from + * [ctor@Gio.DesktopAppInfo.new_from_keyfile], this function will return `NULL`. * * Returns: (nullable) (type filename): The full path to the file for @info, - * or %NULL if not known. + * or `NULL` if not known. * Since: 2.24 */ const char * @@ -2313,12 +2313,12 @@ g_desktop_app_info_get_icon (GAppInfo *appinfo) /** * g_desktop_app_info_get_categories: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * * Gets the categories from the desktop file. * - * Returns: (nullable): The unparsed Categories key from the desktop file; - * i.e. no attempt is made to split it by ';' or validate it. + * Returns: (nullable): The unparsed `Categories` key from the desktop file; + * i.e. no attempt is made to split it by `;` or validate it. */ const char * g_desktop_app_info_get_categories (GDesktopAppInfo *info) @@ -2328,11 +2328,11 @@ g_desktop_app_info_get_categories (GDesktopAppInfo *info) /** * g_desktop_app_info_get_keywords: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * * Gets the keywords from the desktop file. * - * Returns: (transfer none): The value of the Keywords key + * Returns: (transfer none): The value of the `Keywords` key * * Since: 2.32 */ @@ -2344,11 +2344,11 @@ g_desktop_app_info_get_keywords (GDesktopAppInfo *info) /** * g_desktop_app_info_get_generic_name: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * * Gets the generic name from the desktop file. * - * Returns: (nullable): The value of the GenericName key + * Returns: (nullable): The value of the `GenericName` key */ const char * g_desktop_app_info_get_generic_name (GDesktopAppInfo *info) @@ -2358,13 +2358,13 @@ g_desktop_app_info_get_generic_name (GDesktopAppInfo *info) /** * g_desktop_app_info_get_nodisplay: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * - * Gets the value of the NoDisplay key, which helps determine if the + * Gets the value of the `NoDisplay` key, which helps determine if the * application info should be shown in menus. See - * %G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show(). + * `G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY` and [method@Gio.AppInfo.should_show]. * - * Returns: The value of the NoDisplay key + * Returns: The value of the `NoDisplay` key * * Since: 2.30 */ @@ -2376,24 +2376,23 @@ g_desktop_app_info_get_nodisplay (GDesktopAppInfo *info) /** * g_desktop_app_info_get_show_in: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * @desktop_env: (nullable): a string specifying a desktop name * * Checks if the application info should be shown in menus that list available * applications for a specific name of the desktop, based on the * `OnlyShowIn` and `NotShowIn` keys. * - * @desktop_env should typically be given as %NULL, in which case the + * @desktop_env should typically be given as `NULL`, in which case the * `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want * to override the default mechanism then you may specify @desktop_env, * but this is not recommended. * - * Note that g_app_info_should_show() for @info will include this check (with - * %NULL for @desktop_env) as well as additional checks. + * Note that [method@Gio.AppInfo.should_show] for @info will include this check + * (with `NULL` for @desktop_env) as well as additional checks. * - * Returns: %TRUE if the @info should be shown in @desktop_env according to the - * `OnlyShowIn` and `NotShowIn` keys, %FALSE - * otherwise. + * Returns: `TRUE` if the @info should be shown in @desktop_env according to the + * `OnlyShowIn` and `NotShowIn` keys, `FALSE` otherwise. * * Since: 2.30 */ @@ -3544,28 +3543,28 @@ g_desktop_app_info_launch (GAppInfo *appinfo, /** * g_desktop_app_info_launch_uris_as_manager_with_fds: - * @appinfo: a #GDesktopAppInfo + * @appinfo: a [class@Gio.DesktopAppInfo] * @uris: (element-type utf8): List of URIs - * @launch_context: (nullable): a #GAppLaunchContext - * @spawn_flags: #GSpawnFlags, used for each process - * @user_setup: (scope async) (nullable) (closure user_setup_data): a #GSpawnChildSetupFunc, used once - * for each process. + * @launch_context: (nullable): a [class@Gio.AppLaunchContext] + * @spawn_flags: [flags@GLib.SpawnFlags], used for each process + * @user_setup: (scope async) (nullable) (closure user_setup_data): a + * [callback@GLib.SpawnChildSetupFunc], used once for each process. * @user_setup_data: User data for @user_setup * @pid_callback: (scope call) (nullable) (closure pid_callback_data): Callback for child processes * @pid_callback_data: User data for @callback - * @stdin_fd: file descriptor to use for child's stdin, or -1 - * @stdout_fd: file descriptor to use for child's stdout, or -1 - * @stderr_fd: file descriptor to use for child's stderr, or -1 - * @error: return location for a #GError, or %NULL + * @stdin_fd: file descriptor to use for child’s stdin, or `-1` + * @stdout_fd: file descriptor to use for child’s stdout, or `-1` + * @stderr_fd: file descriptor to use for child’s stderr, or `-1` + * @error: return location for a #GError, or `NULL` * - * Equivalent to g_desktop_app_info_launch_uris_as_manager() but allows + * Equivalent to [method@Gio.DesktopAppInfo.launch_uris_as_manager] but allows * you to pass in file descriptors for the stdin, stdout and stderr streams * of the launched process. * * If application launching occurs via some non-spawn mechanism (e.g. D-Bus * activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. * - * Returns: %TRUE on successful launch, %FALSE otherwise. + * Returns: `TRUE` on successful launch, `FALSE` otherwise. * * Since: 2.58 */ @@ -3599,34 +3598,35 @@ g_desktop_app_info_launch_uris_as_manager_with_fds (GDesktopAppInfo * /** * g_desktop_app_info_launch_uris_as_manager: - * @appinfo: a #GDesktopAppInfo + * @appinfo: a [class@Gio.DesktopAppInfo] * @uris: (element-type utf8): List of URIs - * @launch_context: (nullable): a #GAppLaunchContext - * @spawn_flags: #GSpawnFlags, used for each process - * @user_setup: (scope async) (nullable): a #GSpawnChildSetupFunc, used once - * for each process. + * @launch_context: (nullable): a [class@Gio.AppLaunchContext] + * @spawn_flags: [flags@GLib.SpawnFlags], used for each process + * @user_setup: (scope async) (nullable): a [callback@GLib.SpawnChildSetupFunc], + * used once for each process. * @user_setup_data: (closure user_setup) (nullable): User data for @user_setup * @pid_callback: (scope call) (nullable): Callback for child processes * @pid_callback_data: (closure pid_callback) (nullable): User data for @callback - * @error: return location for a #GError, or %NULL + * @error: return location for a #GError, or `NULL` * - * This function performs the equivalent of g_app_info_launch_uris(), + * This function performs the equivalent of [method@Gio.AppInfo.launch_uris], * but is intended primarily for operating system components that * launch applications. Ordinary applications should use - * g_app_info_launch_uris(). + * [method@Gio.AppInfo.launch_uris]. * * If the application is launched via GSpawn, then @spawn_flags, @user_setup - * and @user_setup_data are used for the call to g_spawn_async(). + * and @user_setup_data are used for the call to [func@GLib.spawn_async]. * Additionally, @pid_callback (with @pid_callback_data) will be called to - * inform about the PID of the created process. See g_spawn_async_with_pipes() - * for information on certain parameter conditions that can enable an - * optimized posix_spawn() codepath to be used. + * inform about the PID of the created process. See + * [func@GLib.spawn_async_with_pipes] for information on certain parameter + * conditions that can enable an optimized [`posix_spawn()`](man:posix_spawn(3)) + * code path to be used. * - * If application launching occurs via some other mechanism (eg: D-Bus + * If application launching occurs via some other mechanism (for example, D-Bus * activation) then @spawn_flags, @user_setup, @user_setup_data, * @pid_callback and @pid_callback_data are ignored. * - * Returns: %TRUE on successful launch, %FALSE otherwise. + * Returns: `TRUE` on successful launch, `FALSE` otherwise. */ gboolean g_desktop_app_info_launch_uris_as_manager (GDesktopAppInfo *appinfo, @@ -3658,15 +3658,15 @@ g_desktop_app_info_launch_uris_as_manager (GDesktopAppInfo *appinfo, * @desktop_env: a string specifying what desktop this is * * Sets the name of the desktop that the application is running in. - * This is used by g_app_info_should_show() and - * g_desktop_app_info_get_show_in() to evaluate the - * `OnlyShowIn` and `NotShowIn` - * desktop entry fields. + * + * This is used by [method@Gio.AppInfo.should_show] and + * [method@Gio.DesktopAppInfo.get_show_in] to evaluate the + * `OnlyShowIn` and `NotShowIn` desktop entry fields. * * Should be called only once; subsequent calls are ignored. * * Deprecated:2.42:do not use this API. Since 2.42 the value of the - * `XDG_CURRENT_DESKTOP` environment variable will be used. + * `XDG_CURRENT_DESKTOP` environment variable will be used. */ void g_desktop_app_info_set_desktop_env (const gchar *desktop_env) @@ -4316,20 +4316,21 @@ g_desktop_app_info_delete (GAppInfo *appinfo) /* Create for commandline {{{2 */ /** * g_app_info_create_from_commandline: - * @commandline: (type filename): the commandline to use - * @application_name: (nullable): the application name, or %NULL to use @commandline - * @flags: flags that can specify details of the created #GAppInfo - * @error: a #GError location to store the error occurring, %NULL to ignore. + * @commandline: (type filename): the command line to use + * @application_name: (nullable): the application name, or `NULL` to use @commandline + * @flags: flags that can specify details of the created [iface@Gio.AppInfo] + * @error: a [type@GLib.Error] location to store the error occurring, + * `NULL` to ignore. * - * Creates a new #GAppInfo from the given information. + * Creates a new [iface@Gio.AppInfo] from the given information. * - * Note that for @commandline, the quoting rules of the Exec key of the + * Note that for @commandline, the quoting rules of the `Exec` key of the * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) * are applied. For example, if the @commandline contains * percent-encoded URIs, the percent-character must be doubled in order to prevent it from - * being swallowed by Exec key unquoting. See the specification for exact quoting rules. + * being swallowed by `Exec` key unquoting. See the specification for exact quoting rules. * - * Returns: (transfer full): new #GAppInfo for given command. + * Returns: (transfer full): new [iface@Gio.AppInfo] for given command. **/ GAppInfo * g_app_info_create_from_commandline (const char *commandline, @@ -4717,13 +4718,13 @@ out: * g_app_info_get_default_for_uri_scheme: * @uri_scheme: a string containing a URI scheme. * - * Gets the default application for handling URIs with - * the given URI scheme. A URI scheme is the initial part - * of the URI, up to but not including the ':', e.g. "http", - * "ftp" or "sip". + * Gets the default application for handling URIs with the given URI scheme. * - * Returns: (transfer full) (nullable): #GAppInfo for given @uri_scheme or - * %NULL on error. + * A URI scheme is the initial part of the URI, up to but not including the `:`. + * For example, `http`, `ftp` or `sip`. + * + * Returns: (transfer full) (nullable): [iface@Gio.AppInfo] for given + * @uri_scheme or `NULL` on error. */ GAppInfo * g_app_info_get_default_for_uri_scheme (const char *uri_scheme) @@ -4751,10 +4752,10 @@ g_app_info_get_default_for_uri_scheme (const char *uri_scheme) * Gets all applications that implement @interface. * * An application implements an interface if that interface is listed in - * the Implements= line of the desktop file of the application. + * the `Implements` line of the desktop file of the application. * - * Returns: (element-type GDesktopAppInfo) (transfer full): a list of #GDesktopAppInfo - * objects. + * Returns: (element-type GDesktopAppInfo) (transfer full): a list of + * [class@Gio.DesktopAppInfo] objects. * * Since: 2.42 **/ @@ -4807,15 +4808,15 @@ g_desktop_app_info_get_implementations (const gchar *interface) * any time. * * None of the search results are subjected to the normal validation - * checks performed by g_desktop_app_info_new() (for example, checking that + * checks performed by [ctor@Gio.DesktopAppInfo.new] (for example, checking that * the executable referenced by a result exists), and so it is possible for - * g_desktop_app_info_new() to return %NULL when passed an app ID returned by - * this function. It is expected that calling code will do this when - * subsequently creating a #GDesktopAppInfo for each result. + * [ctor@Gio.DesktopAppInfo.new] to return `NULL` when passed an app ID returned + * by this function. It is expected that calling code will do this when + * subsequently creating a [class@Gio.DesktopAppInfo] for each result. * * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a - * list of strvs. Free each item with g_strfreev() and free the outer - * list with g_free(). + * list of strvs. Free each item with [func@GLib.strfreev] and free the outer + * list with [func@GLib.free]. */ gchar *** g_desktop_app_info_search (const gchar *search_string) @@ -4946,8 +4947,8 @@ g_app_info_get_all (void) * #GDesktopAppInfoLookup is an opaque data structure and can only be accessed * using the following functions. * - * Deprecated: 2.28: The #GDesktopAppInfoLookup interface is deprecated and - * unused by GIO. + * Deprecated: 2.28: The [iface@Gio.DesktopAppInfoLookup] interface is + * deprecated and unused by GIO. **/ G_GNUC_BEGIN_IGNORE_DEPRECATIONS @@ -4964,23 +4965,24 @@ g_desktop_app_info_lookup_default_init (GDesktopAppInfoLookupInterface *iface) /** * g_desktop_app_info_lookup_get_default_for_uri_scheme: - * @lookup: a #GDesktopAppInfoLookup + * @lookup: a [iface@Gio.DesktopAppInfoLookup] * @uri_scheme: a string containing a URI scheme. * * Gets the default application for launching applications - * using this URI scheme for a particular #GDesktopAppInfoLookup + * using this URI scheme for a particular [iface@Gio.DesktopAppInfoLookup] * implementation. * - * The #GDesktopAppInfoLookup interface and this function is used - * to implement g_app_info_get_default_for_uri_scheme() backends + * The [iface@Gio.DesktopAppInfoLookup] interface and this function is used + * to implement [func@Gio.AppInfo.get_default_for_uri_scheme] backends * in a GIO module. There is no reason for applications to use it - * directly. Applications should use g_app_info_get_default_for_uri_scheme(). + * directly. Applications should use + * [func@Gio.AppInfo.get_default_for_uri_scheme]. * - * Returns: (transfer full) (nullable): #GAppInfo for given @uri_scheme or - * %NULL on error. + * Returns: (transfer full) (nullable): [iface@Gio.AppInfo] for given + * @uri_scheme or `NULL` on error. * - * Deprecated: 2.28: The #GDesktopAppInfoLookup interface is deprecated and - * unused by GIO. + * Deprecated: 2.28: The [iface@Gio.DesktopAppInfoLookup] interface is + * deprecated and unused by GIO. */ GAppInfo * g_desktop_app_info_lookup_get_default_for_uri_scheme (GDesktopAppInfoLookup *lookup, @@ -5001,14 +5003,14 @@ G_GNUC_END_IGNORE_DEPRECATIONS /** * g_desktop_app_info_get_startup_wm_class: - * @info: a #GDesktopAppInfo that supports startup notify + * @info: a [class@Gio.DesktopAppInfo] that supports startup notify * - * Retrieves the StartupWMClass field from @info. This represents the - * WM_CLASS property of the main window of the application, if launched + * Retrieves the `StartupWMClass` field from @info. This represents the + * `WM_CLASS` property of the main window of the application, if launched * through @info. * - * Returns: (nullable) (transfer none): the startup WM class, or %NULL if none is set - * in the desktop file. + * Returns: (nullable) (transfer none): the startup WM class, or `NULL` if none + * is set in the desktop file. * * Since: 2.34 */ @@ -5022,15 +5024,15 @@ g_desktop_app_info_get_startup_wm_class (GDesktopAppInfo *info) /** * g_desktop_app_info_get_string: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * @key: the key to look up * * Looks up a string value in the keyfile backing @info. * - * The @key is looked up in the "Desktop Entry" group. + * The @key is looked up in the `Desktop Entry` group. * - * Returns: (nullable): a newly allocated string, or %NULL if the key - * is not found + * Returns: (nullable): a newly allocated string, or `NULL` if the key is not + * found * * Since: 2.36 */ @@ -5046,16 +5048,16 @@ g_desktop_app_info_get_string (GDesktopAppInfo *info, /** * g_desktop_app_info_get_locale_string: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * @key: the key to look up * * Looks up a localized string value in the keyfile backing @info * translated to the current locale. * - * The @key is looked up in the "Desktop Entry" group. + * The @key is looked up in the `Desktop Entry` group. * - * Returns: (nullable): a newly allocated string, or %NULL if the key - * is not found + * Returns: (nullable): a newly allocated string, or `NULL` if the key is not + * found * * Since: 2.56 */ @@ -5073,15 +5075,14 @@ g_desktop_app_info_get_locale_string (GDesktopAppInfo *info, /** * g_desktop_app_info_get_boolean: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * @key: the key to look up * * Looks up a boolean value in the keyfile backing @info. * - * The @key is looked up in the "Desktop Entry" group. + * The @key is looked up in the `Desktop Entry` group. * - * Returns: the boolean value, or %FALSE if the key - * is not found + * Returns: the boolean value, or `FALSE` if the key is not found * * Since: 2.36 */ @@ -5097,17 +5098,18 @@ g_desktop_app_info_get_boolean (GDesktopAppInfo *info, /** * g_desktop_app_info_get_string_list: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * @key: the key to look up - * @length: (out) (optional): return location for the number of returned strings, or %NULL + * @length: (out) (optional): return location for the number of returned + * strings, or `NULL` * * Looks up a string list value in the keyfile backing @info. * - * The @key is looked up in the "Desktop Entry" group. + * The @key is looked up in the `Desktop Entry` group. * * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): - * a %NULL-terminated string array or %NULL if the specified - * key cannot be found. The array should be freed with g_strfreev(). + * a `NULL`-terminated string array or `NULL` if the specified + * key cannot be found. The array should be freed with [func@GLib.strfreev]. * * Since: 2.60 */ @@ -5124,13 +5126,13 @@ g_desktop_app_info_get_string_list (GDesktopAppInfo *info, /** * g_desktop_app_info_has_key: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * @key: the key to look up * - * Returns whether @key exists in the "Desktop Entry" group + * Returns whether @key exists in the `Desktop Entry` group * of the keyfile backing @info. * - * Returns: %TRUE if the @key exists + * Returns: `TRUE` if the @key exists * * Since: 2.36 */ @@ -5148,15 +5150,16 @@ g_desktop_app_info_has_key (GDesktopAppInfo *info, /** * g_desktop_app_info_list_actions: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * - * Returns the list of "additional application actions" supported on the + * Returns the list of ‘additional application actions’ supported on the * desktop file, as per the desktop file specification. * * As per the specification, this is the list of actions that are - * explicitly listed in the "Actions" key of the [Desktop Entry] group. + * explicitly listed in the `Actions` key of the `Desktop Entry` group. * - * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a list of strings, always non-%NULL + * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a + * list of strings, always non-`NULL` * * Since: 2.38 **/ @@ -5183,14 +5186,14 @@ app_info_has_action (GDesktopAppInfo *info, /** * g_desktop_app_info_get_action_name: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * @action_name: the name of the action as from - * g_desktop_app_info_list_actions() + * [method@Gio.DesktopAppInfo.list_actions] * - * Gets the user-visible display name of the "additional application - * action" specified by @action_name. + * Gets the user-visible display name of the ‘additional application + * action’ specified by @action_name. * - * This corresponds to the "Name" key within the keyfile group for the + * This corresponds to the `Name` key within the keyfile group for the * action. * * Returns: (transfer full): the locale-specific action name @@ -5225,25 +5228,25 @@ g_desktop_app_info_get_action_name (GDesktopAppInfo *info, /** * g_desktop_app_info_launch_action: - * @info: a #GDesktopAppInfo + * @info: a [class@Gio.DesktopAppInfo] * @action_name: the name of the action as from - * g_desktop_app_info_list_actions() - * @launch_context: (nullable): a #GAppLaunchContext + * [method@Gio.DesktopAppInfo.list_actions] + * @launch_context: (nullable): a [class@Gio.AppLaunchContext] * * Activates the named application action. * * You may only call this function on action names that were - * returned from g_desktop_app_info_list_actions(). + * returned from [method@Gio.DesktopAppInfo.list_actions]. * * Note that if the main entry of the desktop file indicates that the * application supports startup notification, and @launch_context is - * non-%NULL, then startup notification will be used when activating the + * non-`NULL`, then startup notification will be used when activating the * action (and as such, invocation of the action on the receiving side * must signal the end of startup notification when it is completed). * This is the expected behaviour of applications declaring additional * actions, as per the desktop file specification. * - * As with g_app_info_launch() there is no way to detect failures that + * As with [method@Gio.AppInfo.launch] there is no way to detect failures that * occur while using this function. * * Since: 2.38 From d1945c7abb639326e447a435bcc2f1d55e3b4f07 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 24 Jul 2024 14:37:18 +0200 Subject: [PATCH 2/6] gdesktopappinfo: Add additional links to the Desktop Entry Spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Might as well make it easy for people to look up what we’re talking about. Signed-off-by: Philip Withnall --- gio/gdesktopappinfo.c | 58 +++++++++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 19 deletions(-) diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c index 7276a79d0..ffffa8ca8 100644 --- a/gio/gdesktopappinfo.c +++ b/gio/gdesktopappinfo.c @@ -2250,8 +2250,9 @@ g_desktop_app_info_get_display_name (GAppInfo *appinfo) * g_desktop_app_info_get_is_hidden: * @info: a [class@Gio.DesktopAppInfo]. * - * A desktop file is hidden if the `Hidden` key in it is - * set to `True`. + * A desktop file is hidden if the + * [`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) + * in it is set to `True`. * * Returns: `TRUE` if hidden, `FALSE` otherwise. **/ @@ -2317,7 +2318,9 @@ g_desktop_app_info_get_icon (GAppInfo *appinfo) * * Gets the categories from the desktop file. * - * Returns: (nullable): The unparsed `Categories` key from the desktop file; + * Returns: (nullable): The unparsed + * [`Categories` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-categories) + * from the desktop file; * i.e. no attempt is made to split it by `;` or validate it. */ const char * @@ -2332,7 +2335,8 @@ g_desktop_app_info_get_categories (GDesktopAppInfo *info) * * Gets the keywords from the desktop file. * - * Returns: (transfer none): The value of the `Keywords` key + * Returns: (transfer none): The value of the + * [`Keywords` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-keywords) * * Since: 2.32 */ @@ -2348,7 +2352,8 @@ g_desktop_app_info_get_keywords (GDesktopAppInfo *info) * * Gets the generic name from the desktop file. * - * Returns: (nullable): The value of the `GenericName` key + * Returns: (nullable): The value of the + * [`GenericName` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-genericname) */ const char * g_desktop_app_info_get_generic_name (GDesktopAppInfo *info) @@ -2360,8 +2365,9 @@ g_desktop_app_info_get_generic_name (GDesktopAppInfo *info) * g_desktop_app_info_get_nodisplay: * @info: a [class@Gio.DesktopAppInfo] * - * Gets the value of the `NoDisplay` key, which helps determine if the - * application info should be shown in menus. See + * Gets the value of the + * [`NoDisplay` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) + * which helps determine if the application info should be shown in menus. See * `G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY` and [method@Gio.AppInfo.should_show]. * * Returns: The value of the `NoDisplay` key @@ -2381,7 +2387,9 @@ g_desktop_app_info_get_nodisplay (GDesktopAppInfo *info) * * Checks if the application info should be shown in menus that list available * applications for a specific name of the desktop, based on the - * `OnlyShowIn` and `NotShowIn` keys. + * [`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) + * and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin) + * keys. * * @desktop_env should typically be given as `NULL`, in which case the * `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want @@ -3661,7 +3669,9 @@ g_desktop_app_info_launch_uris_as_manager (GDesktopAppInfo *appinfo, * * This is used by [method@Gio.AppInfo.should_show] and * [method@Gio.DesktopAppInfo.get_show_in] to evaluate the - * `OnlyShowIn` and `NotShowIn` desktop entry fields. + * [`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) + * and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin) + * keys. * * Should be called only once; subsequent calls are ignored. * @@ -4328,7 +4338,9 @@ g_desktop_app_info_delete (GAppInfo *appinfo) * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) * are applied. For example, if the @commandline contains * percent-encoded URIs, the percent-character must be doubled in order to prevent it from - * being swallowed by `Exec` key unquoting. See the specification for exact quoting rules. + * being swallowed by `Exec` key unquoting. See + * [the specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s07.html) + * for exact quoting rules. * * Returns: (transfer full): new [iface@Gio.AppInfo] for given command. **/ @@ -4900,10 +4912,15 @@ g_desktop_app_info_search (const gchar *search_string) * on this system. * * For desktop files, this includes applications that have - * `NoDisplay=true` set or are excluded from display by means - * of `OnlyShowIn` or `NotShowIn`. See [method@Gio.AppInfo.should_show]. - * The returned list does not include applications which have - * the `Hidden` key set. + * [`NoDisplay=true`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) + * set or are excluded from display by means of + * [`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) + * or [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin). + * See [method@Gio.AppInfo.should_show]. + * + * The returned list does not include applications which have the + * [`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) + * set. * * Returns: (element-type GAppInfo) (transfer full): a newly allocated * list of references to [iface@Gio.AppInfo]s. @@ -5152,8 +5169,9 @@ g_desktop_app_info_has_key (GDesktopAppInfo *info, * g_desktop_app_info_list_actions: * @info: a [class@Gio.DesktopAppInfo] * - * Returns the list of ‘additional application actions’ supported on the - * desktop file, as per the desktop file specification. + * Returns the list of + * [‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html) + * supported on the desktop file, as per the desktop file specification. * * As per the specification, this is the list of actions that are * explicitly listed in the `Actions` key of the `Desktop Entry` group. @@ -5190,8 +5208,9 @@ app_info_has_action (GDesktopAppInfo *info, * @action_name: the name of the action as from * [method@Gio.DesktopAppInfo.list_actions] * - * Gets the user-visible display name of the ‘additional application - * action’ specified by @action_name. + * Gets the user-visible display name of the + * [‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html) + * specified by @action_name. * * This corresponds to the `Name` key within the keyfile group for the * action. @@ -5244,7 +5263,8 @@ g_desktop_app_info_get_action_name (GDesktopAppInfo *info, * action (and as such, invocation of the action on the receiving side * must signal the end of startup notification when it is completed). * This is the expected behaviour of applications declaring additional - * actions, as per the desktop file specification. + * actions, as per the + * [desktop file specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html). * * As with [method@Gio.AppInfo.launch] there is no way to detect failures that * occur while using this function. From 21fdb3be245f5bd8e907e32e595b98477ee989d4 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 24 Jul 2024 15:00:12 +0200 Subject: [PATCH 3/6] gappinfo: Move all platform-independent API docs to gappinfo.c Previously, some of the doc comments for platform-independent APIs were in `gdesktopappinfo.c`, which is only built on Unix systems. This meant the introspection annotations for those APIs were not used on non-Unix systems, which caused platform differences in `Gio-2.0.gir`. So, move those doc comments to `gappinfo.c` and put them next to some new platform-independent wrapper functions which provide a consistent entry point and location for the API preconditions. Signed-off-by: Philip Withnall Helps: #3399 --- gio/gappinfo.c | 182 ++++++++++++++++++++++++++++++++++++++++++ gio/gappinfoprivate.h | 13 +++ gio/gdesktopappinfo.c | 142 +++----------------------------- gio/gosxappinfo.m | 25 +++--- gio/gwin32appinfo.c | 25 +++--- 5 files changed, 234 insertions(+), 153 deletions(-) diff --git a/gio/gappinfo.c b/gio/gappinfo.c index dd2f75695..c54fc677b 100644 --- a/gio/gappinfo.c +++ b/gio/gappinfo.c @@ -116,6 +116,38 @@ g_app_info_default_init (GAppInfoInterface *iface) { } +/** + * g_app_info_create_from_commandline: + * @commandline: (type filename): the command line to use + * @application_name: (nullable): the application name, or `NULL` to use @commandline + * @flags: flags that can specify details of the created [iface@Gio.AppInfo] + * @error: a [type@GLib.Error] location to store the error occurring, + * `NULL` to ignore. + * + * Creates a new [iface@Gio.AppInfo] from the given information. + * + * Note that for @commandline, the quoting rules of the `Exec` key of the + * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) + * are applied. For example, if the @commandline contains + * percent-encoded URIs, the percent-character must be doubled in order to prevent it from + * being swallowed by `Exec` key unquoting. See + * [the specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s07.html) + * for exact quoting rules. + * + * Returns: (transfer full): new [iface@Gio.AppInfo] for given command. + **/ +GAppInfo * +g_app_info_create_from_commandline (const char *commandline, + const char *application_name, + GAppInfoCreateFlags flags, + GError **error) +{ + g_return_val_if_fail (commandline, NULL); + g_return_val_if_fail (error == NULL || *error == NULL, NULL); + + return g_app_info_create_from_commandline_impl (commandline, application_name, + flags, error); +} /** * g_app_info_dup: @@ -374,6 +406,156 @@ g_app_info_set_as_last_used_for_type (GAppInfo *appinfo, return FALSE; } +/** + * g_app_info_get_all: + * + * Gets a list of all of the applications currently registered + * on this system. + * + * For desktop files, this includes applications that have + * [`NoDisplay=true`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) + * set or are excluded from display by means of + * [`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) + * or [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin). + * See [method@Gio.AppInfo.should_show]. + * + * The returned list does not include applications which have the + * [`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) + * set. + * + * Returns: (element-type GAppInfo) (transfer full): a newly allocated + * list of references to [iface@Gio.AppInfo]s. + **/ +GList * +g_app_info_get_all (void) +{ + return g_app_info_get_all_impl (); +} + +/** + * g_app_info_get_recommended_for_type: + * @content_type: the content type to find a [iface@Gio.AppInfo] for + * + * Gets a list of recommended [iface@Gio.AppInfo]s for a given content type, + * i.e. those applications which claim to support the given content type + * exactly, and not by MIME type subclassing. + * + * Note that the first application of the list is the last used one, i.e. + * the last one for which [method@Gio.AppInfo.set_as_last_used_for_type] has + * been called. + * + * Returns: (element-type GAppInfo) (transfer full): list of + * [iface@Gio.AppInfo]s for given @content_type or `NULL` on error. + * + * Since: 2.28 + **/ +GList * +g_app_info_get_recommended_for_type (const gchar *content_type) +{ + g_return_val_if_fail (content_type != NULL, NULL); + + return g_app_info_get_recommended_for_type_impl (content_type); +} + +/** + * g_app_info_get_fallback_for_type: + * @content_type: the content type to find a [iface@Gio.AppInfo] for + * + * Gets a list of fallback [iface@Gio.AppInfo]s for a given content type, i.e. + * those applications which claim to support the given content type by MIME + * type subclassing and not directly. + * + * Returns: (element-type GAppInfo) (transfer full): list of [iface@Gio.AppInfo]s + * for given @content_type or `NULL` on error. + * + * Since: 2.28 + **/ +GList * +g_app_info_get_fallback_for_type (const gchar *content_type) +{ + g_return_val_if_fail (content_type != NULL, NULL); + + return g_app_info_get_fallback_for_type_impl (content_type); +} + +/** + * g_app_info_get_all_for_type: + * @content_type: the content type to find a [iface@Gio.AppInfo] for + * + * Gets a list of all [iface@Gio.AppInfo]s for a given content type, + * including the recommended and fallback [iface@Gio.AppInfo]s. See + * [func@Gio.AppInfo.get_recommended_for_type] and + * [func@Gio.AppInfo.get_fallback_for_type]. + * + * Returns: (element-type GAppInfo) (transfer full): list of + * [iface@Gio.AppInfo]s for given @content_type. + **/ +GList * +g_app_info_get_all_for_type (const char *content_type) +{ + g_return_val_if_fail (content_type != NULL, NULL); + + return g_app_info_get_all_for_type_impl (content_type); +} + +/** + * g_app_info_reset_type_associations: + * @content_type: a content type + * + * Removes all changes to the type associations done by + * [method@Gio.AppInfo.set_as_default_for_type], + * [method@Gio.AppInfo.set_as_default_for_extension], + * [method@Gio.AppInfo.add_supports_type] or + * [method@Gio.AppInfo.remove_supports_type]. + * + * Since: 2.20 + */ +void +g_app_info_reset_type_associations (const char *content_type) +{ + g_app_info_reset_type_associations_impl (content_type); +} + +/** + * g_app_info_get_default_for_type: + * @content_type: the content type to find a [iface@Gio.AppInfo] for + * @must_support_uris: if `TRUE`, the [iface@Gio.AppInfo] is expected to + * support URIs + * + * Gets the default [iface@Gio.AppInfo] for a given content type. + * + * Returns: (transfer full) (nullable): [iface@Gio.AppInfo] for given + * @content_type or `NULL` on error. + */ +GAppInfo * +g_app_info_get_default_for_type (const char *content_type, + gboolean must_support_uris) +{ + g_return_val_if_fail (content_type != NULL, NULL); + + return g_app_info_get_default_for_type_impl (content_type, must_support_uris); +} + +/** + * g_app_info_get_default_for_uri_scheme: + * @uri_scheme: a string containing a URI scheme. + * + * Gets the default application for handling URIs with the given URI scheme. + * + * A URI scheme is the initial part of the URI, up to but not including the `:`. + * For example, `http`, `ftp` or `sip`. + * + * Returns: (transfer full) (nullable): [iface@Gio.AppInfo] for given + * @uri_scheme or `NULL` on error. + */ +GAppInfo * +g_app_info_get_default_for_uri_scheme (const char *uri_scheme) +{ + g_return_val_if_fail (uri_scheme != NULL && *uri_scheme != '\0', NULL); + + return g_app_info_get_default_for_uri_scheme_impl (uri_scheme); +} + /** * g_app_info_set_as_default_for_extension: * @appinfo: the app info diff --git a/gio/gappinfoprivate.h b/gio/gappinfoprivate.h index dbf46c22a..df6a2d3bf 100644 --- a/gio/gappinfoprivate.h +++ b/gio/gappinfoprivate.h @@ -25,4 +25,17 @@ void g_app_info_monitor_fire (void); +GAppInfo *g_app_info_create_from_commandline_impl (const char *commandline, + const char *application_name, + GAppInfoCreateFlags flags, + GError **error); +GList *g_app_info_get_recommended_for_type_impl (const gchar *content_type); +GList *g_app_info_get_fallback_for_type_impl (const gchar *content_type); +GList *g_app_info_get_all_for_type_impl (const char *content_type); +void g_app_info_reset_type_associations_impl (const char *content_type); +GAppInfo *g_app_info_get_default_for_type_impl (const char *content_type, + gboolean must_support_uris); +GAppInfo *g_app_info_get_default_for_uri_scheme_impl (const char *uri_scheme); +GList *g_app_info_get_all_impl (void); + #endif /* __G_APP_INFO_PRIVATE_H__ */ diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c index ffffa8ca8..343f30949 100644 --- a/gio/gdesktopappinfo.c +++ b/gio/gdesktopappinfo.c @@ -4324,31 +4324,12 @@ g_desktop_app_info_delete (GAppInfo *appinfo) } /* Create for commandline {{{2 */ -/** - * g_app_info_create_from_commandline: - * @commandline: (type filename): the command line to use - * @application_name: (nullable): the application name, or `NULL` to use @commandline - * @flags: flags that can specify details of the created [iface@Gio.AppInfo] - * @error: a [type@GLib.Error] location to store the error occurring, - * `NULL` to ignore. - * - * Creates a new [iface@Gio.AppInfo] from the given information. - * - * Note that for @commandline, the quoting rules of the `Exec` key of the - * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) - * are applied. For example, if the @commandline contains - * percent-encoded URIs, the percent-character must be doubled in order to prevent it from - * being swallowed by `Exec` key unquoting. See - * [the specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s07.html) - * for exact quoting rules. - * - * Returns: (transfer full): new [iface@Gio.AppInfo] for given command. - **/ + GAppInfo * -g_app_info_create_from_commandline (const char *commandline, - const char *application_name, - GAppInfoCreateFlags flags, - GError **error) +g_app_info_create_from_commandline_impl (const char *commandline, + const char *application_name, + GAppInfoCreateFlags flags, + GError **error) { char **split; char *basename; @@ -4497,25 +4478,8 @@ g_desktop_app_info_get_desktop_ids_for_content_type (const gchar *content_type, return (gchar **) g_ptr_array_free (hits, FALSE); } -/** - * g_app_info_get_recommended_for_type: - * @content_type: the content type to find a [iface@Gio.AppInfo] for - * - * Gets a list of recommended [iface@Gio.AppInfo]s for a given content type, - * i.e. those applications which claim to support the given content type - * exactly, and not by MIME type subclassing. - * - * Note that the first application of the list is the last used one, i.e. - * the last one for which [method@Gio.AppInfo.set_as_last_used_for_type] has - * been called. - * - * Returns: (element-type GAppInfo) (transfer full): list of - * [iface@Gio.AppInfo]s for given @content_type or `NULL` on error. - * - * Since: 2.28 - **/ GList * -g_app_info_get_recommended_for_type (const gchar *content_type) +g_app_info_get_recommended_for_type_impl (const gchar *content_type) { gchar **desktop_ids; GList *infos; @@ -4540,21 +4504,8 @@ g_app_info_get_recommended_for_type (const gchar *content_type) return g_list_reverse (infos); } -/** - * g_app_info_get_fallback_for_type: - * @content_type: the content type to find a [iface@Gio.AppInfo] for - * - * Gets a list of fallback [iface@Gio.AppInfo]s for a given content type, i.e. - * those applications which claim to support the given content type by MIME - * type subclassing and not directly. - * - * Returns: (element-type GAppInfo) (transfer full): list of [iface@Gio.AppInfo]s - * for given @content_type or `NULL` on error. - * - * Since: 2.28 - **/ GList * -g_app_info_get_fallback_for_type (const gchar *content_type) +g_app_info_get_fallback_for_type_impl (const gchar *content_type) { gchar **recommended_ids; gchar **all_ids; @@ -4592,20 +4543,8 @@ g_app_info_get_fallback_for_type (const gchar *content_type) return g_list_reverse (infos); } -/** - * g_app_info_get_all_for_type: - * @content_type: the content type to find a [iface@Gio.AppInfo] for - * - * Gets a list of all [iface@Gio.AppInfo]s for a given content type, - * including the recommended and fallback [iface@Gio.AppInfo]s. See - * [func@Gio.AppInfo.get_recommended_for_type] and - * [func@Gio.AppInfo.get_fallback_for_type]. - * - * Returns: (element-type GAppInfo) (transfer full): list of - * [iface@Gio.AppInfo]s for given @content_type. - **/ GList * -g_app_info_get_all_for_type (const char *content_type) +g_app_info_get_all_for_type_impl (const char *content_type) { gchar **desktop_ids; GList *infos; @@ -4630,40 +4569,17 @@ g_app_info_get_all_for_type (const char *content_type) return g_list_reverse (infos); } -/** - * g_app_info_reset_type_associations: - * @content_type: a content type - * - * Removes all changes to the type associations done by - * [method@Gio.AppInfo.set_as_default_for_type], - * [method@Gio.AppInfo.set_as_default_for_extension], - * [method@Gio.AppInfo.add_supports_type] or - * [method@Gio.AppInfo.remove_supports_type]. - * - * Since: 2.20 - */ void -g_app_info_reset_type_associations (const char *content_type) +g_app_info_reset_type_associations_impl (const char *content_type) { update_mimeapps_list (NULL, content_type, UPDATE_MIME_NONE, NULL); } -/** - * g_app_info_get_default_for_type: - * @content_type: the content type to find a [iface@Gio.AppInfo] for - * @must_support_uris: if `TRUE`, the [iface@Gio.AppInfo] is expected to - * support URIs - * - * Gets the default [iface@Gio.AppInfo] for a given content type. - * - * Returns: (transfer full) (nullable): [iface@Gio.AppInfo] for given - * @content_type or `NULL` on error. - */ GAppInfo * -g_app_info_get_default_for_type (const char *content_type, - gboolean must_support_uris) +g_app_info_get_default_for_type_impl (const char *content_type, + gboolean must_support_uris) { GPtrArray *blocklist; GPtrArray *results; @@ -4726,20 +4642,8 @@ out: return info; } -/** - * g_app_info_get_default_for_uri_scheme: - * @uri_scheme: a string containing a URI scheme. - * - * Gets the default application for handling URIs with the given URI scheme. - * - * A URI scheme is the initial part of the URI, up to but not including the `:`. - * For example, `http`, `ftp` or `sip`. - * - * Returns: (transfer full) (nullable): [iface@Gio.AppInfo] for given - * @uri_scheme or `NULL` on error. - */ GAppInfo * -g_app_info_get_default_for_uri_scheme (const char *uri_scheme) +g_app_info_get_default_for_uri_scheme_impl (const char *uri_scheme) { GAppInfo *app_info; char *content_type, *scheme_down; @@ -4905,28 +4809,8 @@ g_desktop_app_info_search (const gchar *search_string) return results; } -/** - * g_app_info_get_all: - * - * Gets a list of all of the applications currently registered - * on this system. - * - * For desktop files, this includes applications that have - * [`NoDisplay=true`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) - * set or are excluded from display by means of - * [`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) - * or [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin). - * See [method@Gio.AppInfo.should_show]. - * - * The returned list does not include applications which have the - * [`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) - * set. - * - * Returns: (element-type GAppInfo) (transfer full): a newly allocated - * list of references to [iface@Gio.AppInfo]s. - **/ GList * -g_app_info_get_all (void) +g_app_info_get_all_impl (void) { GHashTable *apps; GHashTableIter iter; diff --git a/gio/gosxappinfo.m b/gio/gosxappinfo.m index 50b08e0be..6de647d6b 100644 --- a/gio/gosxappinfo.m +++ b/gio/gosxappinfo.m @@ -22,6 +22,7 @@ #include "config.h" #include "gappinfo.h" +#include "gappinfoprivate.h" #include "gosxappinfo.h" #include "gcontenttype.h" #include "gfile.h" @@ -577,10 +578,10 @@ g_osx_app_info_iface_init (GAppInfoIface *iface) } GAppInfo * -g_app_info_create_from_commandline (const char *commandline, - const char *application_name, - GAppInfoCreateFlags flags, - GError **error) +g_app_info_create_from_commandline_impl (const char *commandline, + const char *application_name, + GAppInfoCreateFlags flags, + GError **error) { g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED, "Creating an app info from a command line not currently supported"); @@ -622,7 +623,7 @@ g_osx_app_info_get_all_for_scheme (const char *cscheme) } GList * -g_app_info_get_all_for_type (const char *content_type) +g_app_info_get_all_for_type_impl (const char *content_type) { gchar *mime_type; CFArrayRef bundle_list; @@ -667,20 +668,20 @@ g_app_info_get_all_for_type (const char *content_type) } GList * -g_app_info_get_recommended_for_type (const char *content_type) +g_app_info_get_recommended_for_type_impl (const char *content_type) { return g_app_info_get_all_for_type (content_type); } GList * -g_app_info_get_fallback_for_type (const char *content_type) +g_app_info_get_fallback_for_type_impl (const char *content_type) { return g_app_info_get_all_for_type (content_type); } GAppInfo * -g_app_info_get_default_for_type (const char *content_type, - gboolean must_support_uris) +g_app_info_get_default_for_type_impl (const char *content_type, + gboolean must_support_uris) { gchar *mime_type; CFStringRef type; @@ -731,7 +732,7 @@ g_app_info_get_default_for_type (const char *content_type, } GAppInfo * -g_app_info_get_default_for_uri_scheme (const char *uri_scheme) +g_app_info_get_default_for_uri_scheme_impl (const char *uri_scheme) { CFStringRef scheme, bundle_id; NSBundle *bundle; @@ -756,7 +757,7 @@ g_app_info_get_default_for_uri_scheme (const char *uri_scheme) } GList * -g_app_info_get_all (void) +g_app_info_get_all_impl (void) { /* There is no API for this afaict * could manually do it... @@ -765,6 +766,6 @@ g_app_info_get_all (void) } void -g_app_info_reset_type_associations (const char *content_type) +g_app_info_reset_type_associations_impl (const char *content_type) { } diff --git a/gio/gwin32appinfo.c b/gio/gwin32appinfo.c index 0b179d877..f2b9cf346 100644 --- a/gio/gwin32appinfo.c +++ b/gio/gwin32appinfo.c @@ -29,6 +29,7 @@ #include #include "gcontenttype.h" +#include "gappinfoprivate.h" #include "gwin32appinfo.h" #include "gappinfo.h" #include "gioerror.h" @@ -5671,10 +5672,10 @@ g_win32_app_info_get_supported_types (GAppInfo *appinfo) } GAppInfo * -g_app_info_create_from_commandline (const char *commandline, - const char *application_name, - GAppInfoCreateFlags flags, - GError **error) +g_app_info_create_from_commandline_impl (const char *commandline, + const char *application_name, + GAppInfoCreateFlags flags, + GError **error) { GWin32AppInfo *info; GWin32AppInfoApplication *app; @@ -5754,7 +5755,7 @@ g_win32_app_info_iface_init (GAppInfoIface *iface) } GAppInfo * -g_app_info_get_default_for_uri_scheme (const char *uri_scheme) +g_app_info_get_default_for_uri_scheme_impl (const char *uri_scheme) { GWin32AppInfoURLSchema *scheme = NULL; char *scheme_down; @@ -5796,8 +5797,8 @@ g_app_info_get_default_for_uri_scheme (const char *uri_scheme) } GAppInfo * -g_app_info_get_default_for_type (const char *content_type, - gboolean must_support_uris) +g_app_info_get_default_for_type_impl (const char *content_type, + gboolean must_support_uris) { GWin32AppInfoFileExtension *ext = NULL; char *ext_down; @@ -5858,7 +5859,7 @@ g_app_info_get_default_for_type (const char *content_type, } GList * -g_app_info_get_all (void) +g_app_info_get_all_impl (void) { GHashTableIter iter; gpointer value; @@ -5887,7 +5888,7 @@ g_app_info_get_all (void) } GList * -g_app_info_get_all_for_type (const char *content_type) +g_app_info_get_all_for_type_impl (const char *content_type) { GWin32AppInfoFileExtension *ext = NULL; char *ext_down; @@ -5957,21 +5958,21 @@ g_app_info_get_all_for_type (const char *content_type) } GList * -g_app_info_get_fallback_for_type (const gchar *content_type) +g_app_info_get_fallback_for_type_impl (const gchar *content_type) { /* TODO: fix this once gcontenttype support is improved */ return g_app_info_get_all_for_type (content_type); } GList * -g_app_info_get_recommended_for_type (const gchar *content_type) +g_app_info_get_recommended_for_type_impl (const gchar *content_type) { /* TODO: fix this once gcontenttype support is improved */ return g_app_info_get_all_for_type (content_type); } void -g_app_info_reset_type_associations (const char *content_type) +g_app_info_reset_type_associations_impl (const char *content_type) { /* nothing to do */ } From bf630dd4fdc963f9a366b472afacfe479a6548f5 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 24 Jul 2024 15:05:35 +0200 Subject: [PATCH 4/6] gio: Rename gosxcontenttype.m to gcontenttype-osx.m To make it consistent with the other platform-specific content type implementations. Signed-off-by: Philip Withnall Helps: #3399 --- gio/{gosxcontenttype.m => gcontenttype-osx.m} | 0 gio/meson.build | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename gio/{gosxcontenttype.m => gcontenttype-osx.m} (100%) diff --git a/gio/gosxcontenttype.m b/gio/gcontenttype-osx.m similarity index 100% rename from gio/gosxcontenttype.m rename to gio/gcontenttype-osx.m diff --git a/gio/meson.build b/gio/meson.build index a1c0ae36b..21c409a1d 100644 --- a/gio/meson.build +++ b/gio/meson.build @@ -392,7 +392,7 @@ if host_system != 'windows' if glib_have_cocoa settings_sources += files('gnextstepsettingsbackend.m') - contenttype_sources += files('gosxcontenttype.m') + contenttype_sources += files('gcontenttype-osx.m') unix_sources += files('gosxappinfo.m') framework_dep = dependency('appleframeworks', modules : ['Foundation', 'CoreFoundation', 'AppKit']) platform_deps += [framework_dep] From 7bec6327a2b7d9ea1b0a30b8d6f91d80ef6d323a Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 24 Jul 2024 15:12:56 +0200 Subject: [PATCH 5/6] gio: Rename gcontenttype.c to gcontenttype-fdo.c MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This reflects its status as actually platform-dependent: it’s only built on systems using the freedesktop.org content type system. It makes the file naming match up with other platform-specific implementations, such as `gcontenttype-win32.c` and `gcontenttype-osx.m`. A subsequent commit will introduce a platform-independent high level API wrapper so that the introspection annotations from this file can be reused between platforms. Signed-off-by: Philip Withnall Helps: #3399 --- gio/{gcontenttype.c => gcontenttype-fdo.c} | 0 gio/meson.build | 2 +- po/POTFILES.in | 2 +- tools/glib.supp | 2 +- 4 files changed, 3 insertions(+), 3 deletions(-) rename gio/{gcontenttype.c => gcontenttype-fdo.c} (100%) diff --git a/gio/gcontenttype.c b/gio/gcontenttype-fdo.c similarity index 100% rename from gio/gcontenttype.c rename to gio/gcontenttype-fdo.c diff --git a/gio/meson.build b/gio/meson.build index 21c409a1d..6870dbce8 100644 --- a/gio/meson.build +++ b/gio/meson.build @@ -405,7 +405,7 @@ if host_system != 'windows' ) application_headers += files('gosxappinfo.h') else - contenttype_sources += files('gcontenttype.c') + contenttype_sources += files('gcontenttype-fdo.c') unix_sources += files('gdesktopappinfo.c') gio_unix_include_headers += files('gdesktopappinfo.h') launch_desktop_sources = files('gio-launch-desktop.c') diff --git a/po/POTFILES.in b/po/POTFILES.in index 8be46bf29..bfe244769 100644 --- a/po/POTFILES.in +++ b/po/POTFILES.in @@ -12,7 +12,7 @@ gio/gbufferedoutputstream.c gio/gbytesicon.c gio/gcancellable.c gio/gcharsetconverter.c -gio/gcontenttype.c +gio/gcontenttype-fdo.c gio/gcontenttype-win32.c gio/gconverter.c gio/gconverterinputstream.c diff --git a/tools/glib.supp b/tools/glib.supp index bddfe603e..5e4fbd23e 100644 --- a/tools/glib.supp +++ b/tools/glib.supp @@ -896,7 +896,7 @@ fun:g_get_home_dir } -# gcontenttype.c caches a one-time allocation global array of @global_mime_dirs. +# gcontenttype-fdo.c caches a one-time allocation global array of @global_mime_dirs. { content_type_mime_dirs_realloc Memcheck:Leak From 460d284fce6c34fa631dc43d8229634b44653794 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 24 Jul 2024 15:58:39 +0200 Subject: [PATCH 6/6] gcontenttype: Add platform-independent top level API file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This file doesn’t contain any real implementation, it just call the `impl` functions from the platform-specific files `gcontenttype-{fdo,osx,win32}.[cm]`. It serves as a location for the doc comments, introspection annotations and API preconditions, and will be built on every platform. In particular, this means that we get consistent GIR output for the `g_content_type_*()` APIs regardless of whether GLib was built on Linux or Windows or macOS. Signed-off-by: Philip Withnall Helps: #3399 --- gio/gcontenttype-fdo.c | 268 +++------------------------ gio/gcontenttype-osx.m | 45 ++--- gio/gcontenttype-win32.c | 54 +++--- gio/gcontenttype.c | 380 ++++++++++++++++++++++++++++++++++++++ gio/gcontenttypeprivate.h | 23 +++ gio/meson.build | 1 + 6 files changed, 472 insertions(+), 299 deletions(-) create mode 100644 gio/gcontenttype.c diff --git a/gio/gcontenttype-fdo.c b/gio/gcontenttype-fdo.c index de9e5a739..230cea182 100644 --- a/gio/gcontenttype-fdo.c +++ b/gio/gcontenttype-fdo.c @@ -36,21 +36,6 @@ #include "glibintl.h" #include "glib-private.h" - -/** - * GContentType: - * - * A content type is a platform specific string that defines the type - * of a file. On UNIX it is a - * [MIME type](http://www.wikipedia.org/wiki/Internet_media_type) - * like `text/plain` or `image/png`. - * On Win32 it is an extension string like `.doc`, `.txt` or a perceived - * string like `audio`. Such strings can be looked up in the registry at - * `HKEY_CLASSES_ROOT`. - * On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier) - * such as `com.apple.application`. - **/ - #include #define XDG_PREFIX _gio_xdg @@ -154,61 +139,18 @@ _g_content_type_set_mime_dirs_locked (const char * const *dirs) tree_magic_schedule_reload (); } -/** - * g_content_type_set_mime_dirs: - * @dirs: (array zero-terminated=1) (nullable): %NULL-terminated list of - * directories to load MIME data from, including any `mime/` subdirectory, - * and with the first directory to try listed first - * - * Set the list of directories used by GIO to load the MIME database. - * If @dirs is %NULL, the directories used are the default: - * - * - the `mime` subdirectory of the directory in `$XDG_DATA_HOME` - * - the `mime` subdirectory of every directory in `$XDG_DATA_DIRS` - * - * This function is intended to be used when writing tests that depend on - * information stored in the MIME database, in order to control the data. - * - * Typically, in case your tests use %G_TEST_OPTION_ISOLATE_DIRS, but they - * depend on the system’s MIME database, you should call this function - * with @dirs set to %NULL before calling g_test_init(), for instance: - * - * |[ - * // Load MIME data from the system - * g_content_type_set_mime_dirs (NULL); - * // Isolate the environment - * g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL); - * - * … - * - * return g_test_run (); - * ]| - * - * Since: 2.60 - */ /*< private >*/ void -g_content_type_set_mime_dirs (const gchar * const *dirs) +g_content_type_set_mime_dirs_impl (const gchar * const *dirs) { G_LOCK (global_mime_dirs); _g_content_type_set_mime_dirs_locked (dirs); G_UNLOCK (global_mime_dirs); } -/** - * g_content_type_get_mime_dirs: - * - * Get the list of directories which MIME data is loaded from. See - * g_content_type_set_mime_dirs() for details. - * - * Returns: (transfer none) (array zero-terminated=1): %NULL-terminated list of - * directories to load MIME data from, including any `mime/` subdirectory, - * and with the first directory to try listed first - * Since: 2.60 - */ /*< private >*/ const gchar * const * -g_content_type_get_mime_dirs (void) +g_content_type_get_mime_dirs_impl (void) { const gchar * const *mime_dirs; @@ -225,19 +167,9 @@ g_content_type_get_mime_dirs (void) return mime_dirs; } -/** - * g_content_type_equals: - * @type1: a content type string - * @type2: a content type string - * - * Compares two content types for equality. - * - * Returns: %TRUE if the two strings are identical or equivalent, - * %FALSE otherwise. - */ gboolean -g_content_type_equals (const gchar *type1, - const gchar *type2) +g_content_type_equals_impl (const gchar *type1, + const gchar *type2) { gboolean res; @@ -253,19 +185,9 @@ g_content_type_equals (const gchar *type1, return res; } -/** - * g_content_type_is_a: - * @type: a content type string - * @supertype: a content type string - * - * Determines if @type is a subset of @supertype. - * - * Returns: %TRUE if @type is a kind of @supertype, - * %FALSE otherwise. - */ gboolean -g_content_type_is_a (const gchar *type, - const gchar *supertype) +g_content_type_is_a_impl (const gchar *type, + const gchar *supertype) { gboolean res; @@ -281,39 +203,15 @@ g_content_type_is_a (const gchar *type, return res; } -/** - * g_content_type_is_mime_type: - * @type: a content type string - * @mime_type: a mime type string - * - * Determines if @type is a subset of @mime_type. - * Convenience wrapper around g_content_type_is_a(). - * - * Returns: %TRUE if @type is a kind of @mime_type, - * %FALSE otherwise. - * - * Since: 2.52 - */ gboolean -g_content_type_is_mime_type (const gchar *type, - const gchar *mime_type) +g_content_type_is_mime_type_impl (const gchar *type, + const gchar *mime_type) { return g_content_type_is_a (type, mime_type); } -/** - * g_content_type_is_unknown: - * @type: a content type string - * - * Checks if the content type is the generic "unknown" type. - * On UNIX this is the "application/octet-stream" mimetype, - * while on win32 it is "*" and on OSX it is a dynamic type - * or octet-stream. - * - * Returns: %TRUE if the type is the unknown type. - */ gboolean -g_content_type_is_unknown (const gchar *type) +g_content_type_is_unknown_impl (const gchar *type) { g_return_val_if_fail (type != NULL, FALSE); @@ -470,17 +368,8 @@ load_comment_for_mime (const char *mimetype) return g_strdup_printf (_("%s type"), mimetype); } -/** - * g_content_type_get_description: - * @type: a content type string - * - * Gets the human readable description of the content type. - * - * Returns: a short description of the content type @type. Free the - * returned string with g_free() - */ gchar * -g_content_type_get_description (const gchar *type) +g_content_type_get_description_impl (const gchar *type) { static GHashTable *type_comment_cache = NULL; gchar *type_copy = NULL; @@ -519,17 +408,8 @@ g_content_type_get_description (const gchar *type) return g_steal_pointer (&comment); } -/** - * g_content_type_get_mime_type: - * @type: a content type string - * - * Gets the mime type for the content type, if one is registered. - * - * Returns: (nullable) (transfer full): the registered mime type for the - * given @type, or %NULL if unknown; free with g_free(). - */ char * -g_content_type_get_mime_type (const char *type) +g_content_type_get_mime_type_impl (const char *type) { g_return_val_if_fail (type != NULL, NULL); @@ -589,55 +469,20 @@ g_content_type_get_icon_internal (const gchar *type, return themed_icon; } -/** - * g_content_type_get_icon: - * @type: a content type string - * - * Gets the icon for a content type. - * - * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned - * object with g_object_unref() - */ GIcon * -g_content_type_get_icon (const gchar *type) +g_content_type_get_icon_impl (const gchar *type) { return g_content_type_get_icon_internal (type, FALSE); } -/** - * g_content_type_get_symbolic_icon: - * @type: a content type string - * - * Gets the symbolic icon for a content type. - * - * Returns: (transfer full): symbolic #GIcon corresponding to the content type. - * Free the returned object with g_object_unref() - * - * Since: 2.34 - */ GIcon * -g_content_type_get_symbolic_icon (const gchar *type) +g_content_type_get_symbolic_icon_impl (const gchar *type) { return g_content_type_get_icon_internal (type, TRUE); } -/** - * g_content_type_get_generic_icon_name: - * @type: a content type string - * - * Gets the generic icon name for a content type. - * - * See the - * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) - * specification for more on the generic icon name. - * - * Returns: (nullable): the registered generic icon name for the given @type, - * or %NULL if unknown. Free with g_free() - * - * Since: 2.34 - */ gchar * -g_content_type_get_generic_icon_name (const gchar *type) +g_content_type_get_generic_icon_name_impl (const gchar *type) { const gchar *xdg_icon_name; gchar *icon_name; @@ -672,18 +517,8 @@ g_content_type_get_generic_icon_name (const gchar *type) return icon_name; } -/** - * g_content_type_can_be_executable: - * @type: a content type string - * - * Checks if a content type can be executable. Note that for instance - * things like text files can be executables (i.e. scripts and batch files). - * - * Returns: %TRUE if the file type corresponds to a type that - * can be executable, %FALSE otherwise. - */ gboolean -g_content_type_can_be_executable (const gchar *type) +g_content_type_can_be_executable_impl (const gchar *type) { g_return_val_if_fail (type != NULL, FALSE); @@ -712,19 +547,8 @@ looks_like_text (const guchar *data, gsize data_size) return TRUE; } -/** - * g_content_type_from_mime_type: - * @mime_type: a mime type string - * - * Tries to find a content type based on the mime type name. - * - * Returns: (nullable): Newly allocated string with content type or - * %NULL. Free with g_free() - * - * Since: 2.18 - **/ gchar * -g_content_type_from_mime_type (const gchar *mime_type) +g_content_type_from_mime_type_impl (const gchar *mime_type) { char *umime; @@ -740,27 +564,11 @@ g_content_type_from_mime_type (const gchar *mime_type) return umime; } -/** - * g_content_type_guess: - * @filename: (nullable) (type filename): a path, or %NULL - * @data: (nullable) (array length=data_size): a stream of data, or %NULL - * @data_size: the size of @data - * @result_uncertain: (out) (optional): return location for the certainty - * of the result, or %NULL - * - * Guesses the content type based on example data. If the function is - * uncertain, @result_uncertain will be set to %TRUE. Either @filename - * or @data may be %NULL, in which case the guess will be based solely - * on the other argument. - * - * Returns: a string indicating a guessed content type for the - * given data. Free with g_free() - */ gchar * -g_content_type_guess (const gchar *filename, - const guchar *data, - gsize data_size, - gboolean *result_uncertain) +g_content_type_guess_impl (const gchar *filename, + const guchar *data, + gsize data_size, + gboolean *result_uncertain) { char *basename; const char *name_mimetypes[10], *sniffed_mimetype; @@ -933,18 +741,8 @@ enumerate_mimetypes_dir (const char *dir, } } -/** - * g_content_types_get_registered: - * - * Gets a list of strings containing all the registered content types - * known to the system. The list and its data should be freed using - * `g_list_free_full (list, g_free)`. - * - * Returns: (element-type utf8) (transfer full): list of the registered - * content types - */ GList * -g_content_types_get_registered (void) +g_content_types_get_registered_impl (void) { const char * const *dirs; GHashTable *mimetypes; @@ -1533,30 +1331,8 @@ match_match (TreeMatch *match, } } -/** - * g_content_type_guess_for_tree: - * @root: the root of the tree to guess a type for - * - * Tries to guess the type of the tree with root @root, by - * looking at the files it contains. The result is an array - * of content types, with the best guess coming first. - * - * The types returned all have the form x-content/foo, e.g. - * x-content/audio-cdda (for audio CDs) or x-content/image-dcf - * (for a camera memory card). See the - * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) - * specification for more on x-content types. - * - * This function is useful in the implementation of - * g_mount_guess_content_type(). - * - * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated - * array of zero or more content types. Free with g_strfreev() - * - * Since: 2.18 - */ gchar ** -g_content_type_guess_for_tree (GFile *root) +g_content_type_guess_for_tree_impl (GFile *root) { GPtrArray *types; GList *l; diff --git a/gio/gcontenttype-osx.m b/gio/gcontenttype-osx.m index 4d7a650c7..b498380cd 100644 --- a/gio/gcontenttype-osx.m +++ b/gio/gcontenttype-osx.m @@ -20,6 +20,7 @@ #include "config.h" #include "gcontenttype.h" +#include "gcontenttypeprivate.h" #include "gicon.h" #include "gthemedicon.h" @@ -107,22 +108,22 @@ create_cstr_from_cfstring_with_fallback (CFStringRef str, /*< private >*/ void -g_content_type_set_mime_dirs (const gchar * const *dirs) +g_content_type_set_mime_dirs_impl (const gchar * const *dirs) { /* noop on macOS */ } /*< private >*/ const gchar * const * -g_content_type_get_mime_dirs (void) +g_content_type_get_mime_dirs_impl (void) { const gchar * const *mime_dirs = { NULL }; return mime_dirs; } gboolean -g_content_type_equals (const gchar *type1, - const gchar *type2) +g_content_type_equals_impl (const gchar *type1, + const gchar *type2) { CFStringRef str1, str2; gboolean ret; @@ -145,8 +146,8 @@ g_content_type_equals (const gchar *type1, } gboolean -g_content_type_is_a (const gchar *ctype, - const gchar *csupertype) +g_content_type_is_a_impl (const gchar *ctype, + const gchar *csupertype) { CFStringRef type, supertype; gboolean ret; @@ -166,8 +167,8 @@ g_content_type_is_a (const gchar *ctype, } gboolean -g_content_type_is_mime_type (const gchar *type, - const gchar *mime_type) +g_content_type_is_mime_type_impl (const gchar *type, + const gchar *mime_type) { gchar *content_type; gboolean ret; @@ -183,7 +184,7 @@ g_content_type_is_mime_type (const gchar *type, } gboolean -g_content_type_is_unknown (const gchar *type) +g_content_type_is_unknown_impl (const gchar *type) { g_return_val_if_fail (type != NULL, FALSE); @@ -198,7 +199,7 @@ g_content_type_is_unknown (const gchar *type) } gchar * -g_content_type_get_description (const gchar *type) +g_content_type_get_description_impl (const gchar *type) { CFStringRef str; CFStringRef desc_str; @@ -327,25 +328,25 @@ g_content_type_get_icon_internal (const gchar *uti, } GIcon * -g_content_type_get_icon (const gchar *type) +g_content_type_get_icon_impl (const gchar *type) { return g_content_type_get_icon_internal (type, FALSE); } GIcon * -g_content_type_get_symbolic_icon (const gchar *type) +g_content_type_get_symbolic_icon_impl (const gchar *type) { return g_content_type_get_icon_internal (type, TRUE); } gchar * -g_content_type_get_generic_icon_name (const gchar *type) +g_content_type_get_generic_icon_name_impl (const gchar *type) { return NULL; } gboolean -g_content_type_can_be_executable (const gchar *type) +g_content_type_can_be_executable_impl (const gchar *type) { CFStringRef uti; gboolean ret = FALSE; @@ -369,7 +370,7 @@ g_content_type_can_be_executable (const gchar *type) } gchar * -g_content_type_from_mime_type (const gchar *mime_type) +g_content_type_from_mime_type_impl (const gchar *mime_type) { CFStringRef mime_str; CFStringRef uti_str; @@ -437,7 +438,7 @@ g_content_type_from_mime_type (const gchar *mime_type) } gchar * -g_content_type_get_mime_type (const gchar *type) +g_content_type_get_mime_type_impl (const gchar *type) { CFStringRef uti_str; CFStringRef mime_str; @@ -489,10 +490,10 @@ looks_like_text (const guchar *data, } gchar * -g_content_type_guess (const gchar *filename, - const guchar *data, - gsize data_size, - gboolean *result_uncertain) +g_content_type_guess_impl (const gchar *filename, + const guchar *data, + gsize data_size, + gboolean *result_uncertain) { CFStringRef uti = NULL; gchar *cextension; @@ -595,14 +596,14 @@ g_content_type_guess (const gchar *filename, } GList * -g_content_types_get_registered (void) +g_content_types_get_registered_impl (void) { /* TODO: UTTypeCreateAllIdentifiersForTag? */ return NULL; } gchar ** -g_content_type_guess_for_tree (GFile *root) +g_content_type_guess_for_tree_impl (GFile *root) { return NULL; } diff --git a/gio/gcontenttype-win32.c b/gio/gcontenttype-win32.c index d227d599e..a81a86976 100644 --- a/gio/gcontenttype-win32.c +++ b/gio/gcontenttype-win32.c @@ -28,6 +28,7 @@ #include #include #include "gcontenttype.h" +#include "gcontenttypeprivate.h" #include "gthemedicon.h" #include "gicon.h" #include "glibintl.h" @@ -87,22 +88,22 @@ get_registry_classes_key (const char *subdir, /*< private >*/ void -g_content_type_set_mime_dirs (const gchar * const *dirs) +g_content_type_set_mime_dirs_impl (const gchar * const *dirs) { /* noop on Windows */ } /*< private >*/ const gchar * const * -g_content_type_get_mime_dirs (void) +g_content_type_get_mime_dirs_impl (void) { const gchar * const *mime_dirs = { NULL }; return mime_dirs; } gboolean -g_content_type_equals (const gchar *type1, - const gchar *type2) +g_content_type_equals_impl (const gchar *type1, + const gchar *type2) { char *progid1, *progid2; gboolean res; @@ -126,8 +127,8 @@ g_content_type_equals (const gchar *type1, } gboolean -g_content_type_is_a (const gchar *type, - const gchar *supertype) +g_content_type_is_a_impl (const gchar *type, + const gchar *supertype) { gboolean res; char *perceived_type; @@ -152,8 +153,8 @@ g_content_type_is_a (const gchar *type, } gboolean -g_content_type_is_mime_type (const gchar *type, - const gchar *mime_type) +g_content_type_is_mime_type_impl (const gchar *type, + const gchar *mime_type) { gchar *content_type; gboolean ret; @@ -169,7 +170,7 @@ g_content_type_is_mime_type (const gchar *type, } gboolean -g_content_type_is_unknown (const gchar *type) +g_content_type_is_unknown_impl (const gchar *type) { g_return_val_if_fail (type != NULL, FALSE); @@ -177,7 +178,7 @@ g_content_type_is_unknown (const gchar *type) } gchar * -g_content_type_get_description (const gchar *type) +g_content_type_get_description_impl (const gchar *type) { char *progid; char *description; @@ -201,7 +202,7 @@ g_content_type_get_description (const gchar *type) } gchar * -g_content_type_get_mime_type (const gchar *type) +g_content_type_get_mime_type_impl (const gchar *type) { char *mime; @@ -224,17 +225,8 @@ g_content_type_get_mime_type (const gchar *type) G_LOCK_DEFINE_STATIC (_type_icons); static GHashTable *_type_icons = NULL; -/** - * g_content_type_get_icon: - * @type: a content type string - * - * Gets the icon for a content type. - * - * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned - * object with g_object_unref() - */ GIcon * -g_content_type_get_icon (const gchar *type) +g_content_type_get_icon_impl (const gchar *type) { GIcon *themed_icon; char *name = NULL; @@ -292,19 +284,19 @@ g_content_type_get_icon (const gchar *type) } GIcon * -g_content_type_get_symbolic_icon (const gchar *type) +g_content_type_get_symbolic_icon_impl (const gchar *type) { return g_content_type_get_icon (type); } gchar * -g_content_type_get_generic_icon_name (const gchar *type) +g_content_type_get_generic_icon_name_impl (const gchar *type) { return NULL; } gboolean -g_content_type_can_be_executable (const gchar *type) +g_content_type_can_be_executable_impl (const gchar *type) { g_return_val_if_fail (type != NULL, FALSE); @@ -343,7 +335,7 @@ looks_like_text (const guchar *data, } gchar * -g_content_type_from_mime_type (const gchar *mime_type) +g_content_type_from_mime_type_impl (const gchar *mime_type) { char *key, *content_type; @@ -362,10 +354,10 @@ g_content_type_from_mime_type (const gchar *mime_type) } gchar * -g_content_type_guess (const gchar *filename, - const guchar *data, - gsize data_size, - gboolean *result_uncertain) +g_content_type_guess_impl (const gchar *filename, + const guchar *data, + gsize data_size, + gboolean *result_uncertain) { char *basename; char *type; @@ -410,7 +402,7 @@ g_content_type_guess (const gchar *filename, } GList * -g_content_types_get_registered (void) +g_content_types_get_registered_impl (void) { DWORD index; wchar_t keyname[256]; @@ -446,7 +438,7 @@ g_content_types_get_registered (void) } gchar ** -g_content_type_guess_for_tree (GFile *root) +g_content_type_guess_for_tree_impl (GFile *root) { /* FIXME: implement */ return NULL; diff --git a/gio/gcontenttype.c b/gio/gcontenttype.c new file mode 100644 index 000000000..aa8f4040a --- /dev/null +++ b/gio/gcontenttype.c @@ -0,0 +1,380 @@ +/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */ + +/* GIO - GLib Input, Output and Streaming Library + * + * Copyright (C) 2006-2007 Red Hat, Inc. + * + * SPDX-License-Identifier: LGPL-2.1-or-later + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General + * Public License along with this library; if not, see . + * + * Author: Alexander Larsson + */ + +#include "config.h" +#include "gcontenttypeprivate.h" +#include "gfile.h" + + +/** + * GContentType: + * + * A content type is a platform specific string that defines the type + * of a file. On UNIX it is a + * [MIME type](http://www.wikipedia.org/wiki/Internet_media_type) + * like `text/plain` or `image/png`. + * On Win32 it is an extension string like `.doc`, `.txt` or a perceived + * string like `audio`. Such strings can be looked up in the registry at + * `HKEY_CLASSES_ROOT`. + * On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier) + * such as `com.apple.application`. + **/ + +/** + * g_content_type_set_mime_dirs: + * @dirs: (array zero-terminated=1) (nullable): %NULL-terminated list of + * directories to load MIME data from, including any `mime/` subdirectory, + * and with the first directory to try listed first + * + * Set the list of directories used by GIO to load the MIME database. + * If @dirs is %NULL, the directories used are the default: + * + * - the `mime` subdirectory of the directory in `$XDG_DATA_HOME` + * - the `mime` subdirectory of every directory in `$XDG_DATA_DIRS` + * + * This function is intended to be used when writing tests that depend on + * information stored in the MIME database, in order to control the data. + * + * Typically, in case your tests use %G_TEST_OPTION_ISOLATE_DIRS, but they + * depend on the system’s MIME database, you should call this function + * with @dirs set to %NULL before calling g_test_init(), for instance: + * + * |[ + * // Load MIME data from the system + * g_content_type_set_mime_dirs (NULL); + * // Isolate the environment + * g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL); + * + * … + * + * return g_test_run (); + * ]| + * + * Since: 2.60 + */ +void +g_content_type_set_mime_dirs (const gchar * const *dirs) +{ + g_content_type_set_mime_dirs_impl (dirs); +} + +/** + * g_content_type_get_mime_dirs: + * + * Get the list of directories which MIME data is loaded from. See + * g_content_type_set_mime_dirs() for details. + * + * Returns: (transfer none) (array zero-terminated=1): %NULL-terminated list of + * directories to load MIME data from, including any `mime/` subdirectory, + * and with the first directory to try listed first + * Since: 2.60 + */ +const gchar * const * +g_content_type_get_mime_dirs (void) +{ + return g_content_type_get_mime_dirs_impl (); +} + +/** + * g_content_type_equals: + * @type1: a content type string + * @type2: a content type string + * + * Compares two content types for equality. + * + * Returns: %TRUE if the two strings are identical or equivalent, + * %FALSE otherwise. + */ +gboolean +g_content_type_equals (const gchar *type1, + const gchar *type2) +{ + g_return_val_if_fail (type1 != NULL, FALSE); + g_return_val_if_fail (type2 != NULL, FALSE); + + return g_content_type_equals_impl (type1, type2); +} + +/** + * g_content_type_is_a: + * @type: a content type string + * @supertype: a content type string + * + * Determines if @type is a subset of @supertype. + * + * Returns: %TRUE if @type is a kind of @supertype, + * %FALSE otherwise. + */ +gboolean +g_content_type_is_a (const gchar *type, + const gchar *supertype) +{ + g_return_val_if_fail (type != NULL, FALSE); + g_return_val_if_fail (supertype != NULL, FALSE); + + return g_content_type_is_a_impl (type, supertype); +} + +/** + * g_content_type_is_mime_type: + * @type: a content type string + * @mime_type: a mime type string + * + * Determines if @type is a subset of @mime_type. + * Convenience wrapper around g_content_type_is_a(). + * + * Returns: %TRUE if @type is a kind of @mime_type, + * %FALSE otherwise. + * + * Since: 2.52 + */ +gboolean +g_content_type_is_mime_type (const gchar *type, + const gchar *mime_type) +{ + g_return_val_if_fail (type != NULL, FALSE); + g_return_val_if_fail (mime_type != NULL, FALSE); + + return g_content_type_is_mime_type_impl (type, mime_type); +} + +/** + * g_content_type_is_unknown: + * @type: a content type string + * + * Checks if the content type is the generic "unknown" type. + * On UNIX this is the "application/octet-stream" mimetype, + * while on win32 it is "*" and on OSX it is a dynamic type + * or octet-stream. + * + * Returns: %TRUE if the type is the unknown type. + */ +gboolean +g_content_type_is_unknown (const gchar *type) +{ + g_return_val_if_fail (type != NULL, FALSE); + + return g_content_type_is_unknown_impl (type); +} + +/** + * g_content_type_get_description: + * @type: a content type string + * + * Gets the human readable description of the content type. + * + * Returns: a short description of the content type @type. Free the + * returned string with g_free() + */ +gchar * +g_content_type_get_description (const gchar *type) +{ + g_return_val_if_fail (type != NULL, NULL); + + return g_content_type_get_description_impl (type); +} + +/** + * g_content_type_get_mime_type: + * @type: a content type string + * + * Gets the mime type for the content type, if one is registered. + * + * Returns: (nullable) (transfer full): the registered mime type for the + * given @type, or %NULL if unknown; free with g_free(). + */ +char * +g_content_type_get_mime_type (const char *type) +{ + g_return_val_if_fail (type != NULL, NULL); + + return g_content_type_get_mime_type_impl (type); +} + +/** + * g_content_type_get_icon: + * @type: a content type string + * + * Gets the icon for a content type. + * + * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned + * object with g_object_unref() + */ +GIcon * +g_content_type_get_icon (const gchar *type) +{ + g_return_val_if_fail (type != NULL, NULL); + + return g_content_type_get_icon_impl (type); +} + +/** + * g_content_type_get_symbolic_icon: + * @type: a content type string + * + * Gets the symbolic icon for a content type. + * + * Returns: (transfer full): symbolic #GIcon corresponding to the content type. + * Free the returned object with g_object_unref() + * + * Since: 2.34 + */ +GIcon * +g_content_type_get_symbolic_icon (const gchar *type) +{ + g_return_val_if_fail (type != NULL, NULL); + + return g_content_type_get_symbolic_icon_impl (type); +} + +/** + * g_content_type_get_generic_icon_name: + * @type: a content type string + * + * Gets the generic icon name for a content type. + * + * See the + * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) + * specification for more on the generic icon name. + * + * Returns: (nullable): the registered generic icon name for the given @type, + * or %NULL if unknown. Free with g_free() + * + * Since: 2.34 + */ +gchar * +g_content_type_get_generic_icon_name (const gchar *type) +{ + g_return_val_if_fail (type != NULL, NULL); + + return g_content_type_get_generic_icon_name_impl (type); +} + +/** + * g_content_type_can_be_executable: + * @type: a content type string + * + * Checks if a content type can be executable. Note that for instance + * things like text files can be executables (i.e. scripts and batch files). + * + * Returns: %TRUE if the file type corresponds to a type that + * can be executable, %FALSE otherwise. + */ +gboolean +g_content_type_can_be_executable (const gchar *type) +{ + g_return_val_if_fail (type != NULL, FALSE); + + return g_content_type_can_be_executable_impl (type); +} + +/** + * g_content_type_from_mime_type: + * @mime_type: a mime type string + * + * Tries to find a content type based on the mime type name. + * + * Returns: (nullable): Newly allocated string with content type or + * %NULL. Free with g_free() + * + * Since: 2.18 + **/ +gchar * +g_content_type_from_mime_type (const gchar *mime_type) +{ + g_return_val_if_fail (mime_type != NULL, NULL); + + return g_content_type_from_mime_type_impl (mime_type); +} + +/** + * g_content_type_guess: + * @filename: (nullable) (type filename): a path, or %NULL + * @data: (nullable) (array length=data_size): a stream of data, or %NULL + * @data_size: the size of @data + * @result_uncertain: (out) (optional): return location for the certainty + * of the result, or %NULL + * + * Guesses the content type based on example data. If the function is + * uncertain, @result_uncertain will be set to %TRUE. Either @filename + * or @data may be %NULL, in which case the guess will be based solely + * on the other argument. + * + * Returns: a string indicating a guessed content type for the + * given data. Free with g_free() + */ +gchar * +g_content_type_guess (const gchar *filename, + const guchar *data, + gsize data_size, + gboolean *result_uncertain) +{ + return g_content_type_guess_impl (filename, data, data_size, result_uncertain); +} + +/** + * g_content_types_get_registered: + * + * Gets a list of strings containing all the registered content types + * known to the system. The list and its data should be freed using + * `g_list_free_full (list, g_free)`. + * + * Returns: (element-type utf8) (transfer full): list of the registered + * content types + */ +GList * +g_content_types_get_registered (void) +{ + return g_content_types_get_registered_impl (); +} + +/** + * g_content_type_guess_for_tree: + * @root: the root of the tree to guess a type for + * + * Tries to guess the type of the tree with root @root, by + * looking at the files it contains. The result is an array + * of content types, with the best guess coming first. + * + * The types returned all have the form x-content/foo, e.g. + * x-content/audio-cdda (for audio CDs) or x-content/image-dcf + * (for a camera memory card). See the + * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) + * specification for more on x-content types. + * + * This function is useful in the implementation of + * g_mount_guess_content_type(). + * + * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated + * array of zero or more content types. Free with g_strfreev() + * + * Since: 2.18 + */ +gchar ** +g_content_type_guess_for_tree (GFile *root) +{ + g_return_val_if_fail (G_IS_FILE (root), NULL); + + return g_content_type_guess_for_tree_impl (root); +} diff --git a/gio/gcontenttypeprivate.h b/gio/gcontenttypeprivate.h index d3d671b91..a642b63b8 100644 --- a/gio/gcontenttypeprivate.h +++ b/gio/gcontenttypeprivate.h @@ -31,6 +31,29 @@ gsize _g_unix_content_type_get_sniff_len (void); char * _g_unix_content_type_unalias (const char *type); char **_g_unix_content_type_get_parents (const char *type); +void g_content_type_set_mime_dirs_impl (const gchar * const *dirs); +const gchar * const *g_content_type_get_mime_dirs_impl (void); +gboolean g_content_type_equals_impl (const gchar *type1, + const gchar *type2); +gboolean g_content_type_is_a_impl (const gchar *type, + const gchar *supertype); +gboolean g_content_type_is_mime_type_impl (const gchar *type, + const gchar *mime_type); +gboolean g_content_type_is_unknown_impl (const gchar *type); +gchar *g_content_type_get_description_impl (const gchar *type); +char *g_content_type_get_mime_type_impl (const char *type); +GIcon *g_content_type_get_icon_impl (const gchar *type); +GIcon *g_content_type_get_symbolic_icon_impl (const gchar *type); +gchar *g_content_type_get_generic_icon_name_impl (const gchar *type); +gboolean g_content_type_can_be_executable_impl (const gchar *type); +gchar *g_content_type_from_mime_type_impl (const gchar *mime_type); +gchar *g_content_type_guess_impl (const gchar *filename, + const guchar *data, + gsize data_size, + gboolean *result_uncertain); +GList *g_content_types_get_registered_impl (void); +gchar **g_content_type_guess_for_tree_impl (GFile *root); + G_END_DECLS #endif /* __G_CONTENT_TYPE_PRIVATE_H__ */ diff --git a/gio/meson.build b/gio/meson.build index 6870dbce8..3da7a6e47 100644 --- a/gio/meson.build +++ b/gio/meson.build @@ -489,6 +489,7 @@ gio_base_sources = files( 'gbytesicon.c', 'gcancellable.c', 'gcharsetconverter.c', + 'gcontenttype.c', 'gcontextspecificgroup.c', 'gconverter.c', 'gconverterinputstream.c',