luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-02 17:26:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

gappinfo: Move all platform-independent API docs to gappinfo.c

Browse Source 
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 <pwithnall@gnome.org>

Helps: #3399
This commit is contained in:
Philip Withnall 2024-07-24 15:00:12 +02:00
parent d1945c7abb
commit 21fdb3be24
No known key found for this signature in database
GPG Key ID: DCDF5885B1F3ED73
5 changed files with 234 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
gio/gappinfo.c
View File

@ -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: * g_app_info_dup:
@ -374,6 +406,156 @@ g_app_info_set_as_last_used_for_type (GAppInfo *appinfo,
return FALSE; 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: * g_app_info_set_as_default_for_extension:
* @appinfo: the app info * @appinfo: the app info

13
gio/gappinfoprivate.h
View File

@ -25,4 +25,17 @@
void g_app_info_monitor_fire (void); 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__ */ #endif /* __G_APP_INFO_PRIVATE_H__ */

134
gio/gdesktopappinfo.c
View File

@ -4324,28 +4324,9 @@ g_desktop_app_info_delete (GAppInfo *appinfo)
} }
/* Create for commandline {{{2 */ /* 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 * GAppInfo *
g_app_info_create_from_commandline (const char *commandline, g_app_info_create_from_commandline_impl (const char *commandline,
const char *application_name, const char *application_name,
GAppInfoCreateFlags flags, GAppInfoCreateFlags flags,
GError **error) GError **error)
@ -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); 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 * 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; gchar **desktop_ids;
GList *infos; GList *infos;
@ -4540,21 +4504,8 @@ g_app_info_get_recommended_for_type (const gchar *content_type)
return g_list_reverse (infos); 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 * 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 **recommended_ids;
gchar **all_ids; gchar **all_ids;
@ -4592,20 +4543,8 @@ g_app_info_get_fallback_for_type (const gchar *content_type)
return g_list_reverse (infos); 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 * 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; gchar **desktop_ids;
GList *infos; GList *infos;
@ -4630,39 +4569,16 @@ g_app_info_get_all_for_type (const char *content_type)
return g_list_reverse (infos); 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 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_mimeapps_list (NULL, content_type,
UPDATE_MIME_NONE, UPDATE_MIME_NONE,
NULL); 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 * GAppInfo *
g_app_info_get_default_for_type (const char *content_type, g_app_info_get_default_for_type_impl (const char *content_type,
gboolean must_support_uris) gboolean must_support_uris)
{ {
GPtrArray *blocklist; GPtrArray *blocklist;
@ -4726,20 +4642,8 @@ out:
return info; 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 * 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; GAppInfo *app_info;
char *content_type, *scheme_down; char *content_type, *scheme_down;
@ -4905,28 +4809,8 @@ g_desktop_app_info_search (const gchar *search_string)
return results; 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 * GList *
g_app_info_get_all (void) g_app_info_get_all_impl (void)
{ {
GHashTable *apps; GHashTable *apps;
GHashTableIter iter; GHashTableIter iter;

17
gio/gosxappinfo.m
View File

@ -22,6 +22,7 @@
#include "config.h" #include "config.h"
#include "gappinfo.h" #include "gappinfo.h"
#include "gappinfoprivate.h"
#include "gosxappinfo.h" #include "gosxappinfo.h"
#include "gcontenttype.h" #include "gcontenttype.h"
#include "gfile.h" #include "gfile.h"
@ -577,7 +578,7 @@ g_osx_app_info_iface_init (GAppInfoIface *iface)
} }
GAppInfo * GAppInfo *
g_app_info_create_from_commandline (const char *commandline, g_app_info_create_from_commandline_impl (const char *commandline,
const char *application_name, const char *application_name,
GAppInfoCreateFlags flags, GAppInfoCreateFlags flags,
GError **error) GError **error)
@ -622,7 +623,7 @@ g_osx_app_info_get_all_for_scheme (const char *cscheme)
} }
GList * 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; gchar *mime_type;
CFArrayRef bundle_list; CFArrayRef bundle_list;
@ -667,19 +668,19 @@ g_app_info_get_all_for_type (const char *content_type)
} }
GList * 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); return g_app_info_get_all_for_type (content_type);
} }
GList * 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); return g_app_info_get_all_for_type (content_type);
} }
GAppInfo * GAppInfo *
g_app_info_get_default_for_type (const char *content_type, g_app_info_get_default_for_type_impl (const char *content_type,
gboolean must_support_uris) gboolean must_support_uris)
{ {
gchar *mime_type; gchar *mime_type;
@ -731,7 +732,7 @@ g_app_info_get_default_for_type (const char *content_type,
} }
GAppInfo * 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; CFStringRef scheme, bundle_id;
NSBundle *bundle; NSBundle *bundle;
@ -756,7 +757,7 @@ g_app_info_get_default_for_uri_scheme (const char *uri_scheme)
} }
GList * GList *
g_app_info_get_all (void) g_app_info_get_all_impl (void)
{ {
/* There is no API for this afaict /* There is no API for this afaict
* could manually do it... * could manually do it...
@ -765,6 +766,6 @@ g_app_info_get_all (void)
} }
void void
g_app_info_reset_type_associations (const char *content_type) g_app_info_reset_type_associations_impl (const char *content_type)
{ {
} }

17
gio/gwin32appinfo.c
View File

@ -29,6 +29,7 @@
#include <string.h> #include <string.h>
#include "gcontenttype.h" #include "gcontenttype.h"
#include "gappinfoprivate.h"
#include "gwin32appinfo.h" #include "gwin32appinfo.h"
#include "gappinfo.h" #include "gappinfo.h"
#include "gioerror.h" #include "gioerror.h"
@ -5671,7 +5672,7 @@ g_win32_app_info_get_supported_types (GAppInfo *appinfo)
} }
GAppInfo * GAppInfo *
g_app_info_create_from_commandline (const char *commandline, g_app_info_create_from_commandline_impl (const char *commandline,
const char *application_name, const char *application_name,
GAppInfoCreateFlags flags, GAppInfoCreateFlags flags,
GError **error) GError **error)
@ -5754,7 +5755,7 @@ g_win32_app_info_iface_init (GAppInfoIface *iface)
} }
GAppInfo * 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; GWin32AppInfoURLSchema *scheme = NULL;
char *scheme_down; char *scheme_down;
@ -5796,7 +5797,7 @@ g_app_info_get_default_for_uri_scheme (const char *uri_scheme)
} }
GAppInfo * GAppInfo *
g_app_info_get_default_for_type (const char *content_type, g_app_info_get_default_for_type_impl (const char *content_type,
gboolean must_support_uris) gboolean must_support_uris)
{ {
GWin32AppInfoFileExtension *ext = NULL; GWin32AppInfoFileExtension *ext = NULL;
@ -5858,7 +5859,7 @@ g_app_info_get_default_for_type (const char *content_type,
} }
GList * GList *
g_app_info_get_all (void) g_app_info_get_all_impl (void)
{ {
GHashTableIter iter; GHashTableIter iter;
gpointer value; gpointer value;
@ -5887,7 +5888,7 @@ g_app_info_get_all (void)
} }
GList * 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; GWin32AppInfoFileExtension *ext = NULL;
char *ext_down; char *ext_down;
@ -5957,21 +5958,21 @@ g_app_info_get_all_for_type (const char *content_type)
} }
GList * 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 */ /* TODO: fix this once gcontenttype support is improved */
return g_app_info_get_all_for_type (content_type); return g_app_info_get_all_for_type (content_type);
} }
GList * 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 */ /* TODO: fix this once gcontenttype support is improved */
return g_app_info_get_all_for_type (content_type); return g_app_info_get_all_for_type (content_type);
} }
void 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 */ /* nothing to do */
} }