GDesktopAppInfo: GIO Reference Manual

## GDesktopAppInfo GDesktopAppInfo — Application information from desktop files |

## Functions

GDesktopAppInfo * | g_desktop_app_info_new_from_filename ()
GDesktopAppInfo * | g_desktop_app_info_new_from_keyfile ()
GDesktopAppInfo * | g_desktop_app_info_new ()
const char * | g_desktop_app_info_get_filename ()
gboolean | g_desktop_app_info_get_is_hidden ()
gboolean | g_desktop_app_info_get_nodisplay ()
gboolean | g_desktop_app_info_get_show_in ()
const char * | g_desktop_app_info_get_generic_name ()
const char * | g_desktop_app_info_get_categories ()
const char * const * | g_desktop_app_info_get_keywords ()
const char * | g_desktop_app_info_get_startup_wm_class ()
void | g_desktop_app_info_set_desktop_env ()
char * | g_desktop_app_info_get_string ()
char * | g_desktop_app_info_get_locale_string ()
gboolean | g_desktop_app_info_get_boolean ()
gchar ** | g_desktop_app_info_get_string_list ()
gboolean | g_desktop_app_info_has_key ()
void | (*GDesktopAppLaunchCallback) ()
gboolean | g_desktop_app_info_launch_uris_as_manager ()
gboolean | g_desktop_app_info_launch_uris_as_manager_with_fds ()
const gchar * const * | g_desktop_app_info_list_actions ()
gchar * | g_desktop_app_info_get_action_name ()
void | g_desktop_app_info_launch_action ()
gchar *** | g_desktop_app_info_search ()
GList * | g_desktop_app_info_get_implementations ()

## Properties

char * | filename | Read / Write / Construct Only

## Types and Values

| GDesktopAppInfo
| GDesktopAppInfoLookup
struct | GDesktopAppInfoLookupIface
#define | G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME

## Object Hierarchy

        GInterface
        ╰── GDesktopAppInfoLookup
        GObject
        ╰── GDesktopAppInfo

## Prerequisites

GDesktopAppInfoLookup requires GObject.

## Implemented Interfaces

GDesktopAppInfo implements GAppInfo.

## Includes

    #include <gio/gdesktopappinfo.h>

## Description

GDesktopAppInfo is an implementation of GAppInfo based on desktop files.

Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file when using it.

## Functions

### g_desktop_app_info_new_from_filename ()

    GDesktopAppInfo *
    g_desktop_app_info_new_from_filename (const char *filename);

Creates a new GDesktopAppInfo.

#### Parameters

filename | the path of a desktop file, in the GLib filename encoding. | [type filename]

#### Returns

a new GDesktopAppInfo or `NULL` on error.

[nullable]

### g_desktop_app_info_new_from_keyfile ()

    GDesktopAppInfo *
    g_desktop_app_info_new_from_keyfile (GKeyFile *key_file);

Creates a new GDesktopAppInfo.

#### Parameters

key_file | an opened GKeyFile |

#### Returns

a new GDesktopAppInfo or `NULL` on error.

[nullable]

Since: 2.18

### g_desktop_app_info_new ()

    GDesktopAppInfo *
    g_desktop_app_info_new (const char *desktop_id);

Creates a new GDesktopAppInfo 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 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 (i.e. a desktop id of kde-foo.desktop will match `/usr/share/applications/kde/foo.desktop`).

#### Parameters

desktop_id | the desktop file id |

#### Returns

a new GDesktopAppInfo, or `NULL` if no desktop file with that id exists.

[nullable]

### g_desktop_app_info_get_filename ()

    const char *
    g_desktop_app_info_get_filename (GDesktopAppInfo *info);

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`.

#### Parameters

info | a GDesktopAppInfo |

#### Returns

The full path to the file for `info` , or `NULL` if not known.

[nullable][type filename]

Since: 2.24

### g_desktop_app_info_get_is_hidden ()

    gboolean
    g_desktop_app_info_get_is_hidden (GDesktopAppInfo *info);

A desktop file is hidden if the Hidden key in it is set to True.

#### Parameters

info | a GDesktopAppInfo. |

#### Returns

`TRUE` if hidden, `FALSE` otherwise.

### g_desktop_app_info_get_nodisplay ()

    gboolean
    g_desktop_app_info_get_nodisplay (GDesktopAppInfo *info);

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()`.

#### Parameters

info | a GDesktopAppInfo |

#### Returns

The value of the NoDisplay key

Since: 2.30

### g_desktop_app_info_get_show_in ()

    gboolean
    g_desktop_app_info_get_show_in (GDesktopAppInfo *info,
                                    const gchar *desktop_env);

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 `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.

#### Parameters

info | a GDesktopAppInfo |
desktop_env | a string specifying a desktop name. | [nullable]

#### Returns

`TRUE` if the `info` should be shown in `desktop_env` according to the `OnlyShowIn` and `NotShowIn` keys, `FALSE` otherwise.

Since: 2.30

### g_desktop_app_info_get_generic_name ()

    const char *
    g_desktop_app_info_get_generic_name (GDesktopAppInfo *info);

Gets the generic name from the desktop file.

#### Parameters

info | a GDesktopAppInfo |

#### Returns

The value of the GenericName key.

[nullable]

### g_desktop_app_info_get_categories ()

    const char *
    g_desktop_app_info_get_categories (GDesktopAppInfo *info);

Gets the categories from the desktop file.

#### Parameters

info | a GDesktopAppInfo |

#### Returns

The unparsed Categories key from the desktop file; i.e. no attempt is made to split it by ';' or validate it.

[nullable]

### g_desktop_app_info_get_keywords ()

    const char * const *
    g_desktop_app_info_get_keywords (GDesktopAppInfo *info);

Gets the keywords from the desktop file.

#### Parameters

info | a GDesktopAppInfo |

#### Returns

The value of the Keywords key.

[transfer none]

Since: 2.32

### g_desktop_app_info_get_startup_wm_class ()

    const char *
    g_desktop_app_info_get_startup_wm_class
                                   (GDesktopAppInfo *info);

Retrieves the StartupWMClass field from `info` . This represents the WM_CLASS property of the main window of the application, if launched through `info` .

#### Parameters

info | a GDesktopAppInfo that supports startup notify |

#### Returns

the startup WM class, or `NULL` if none is set in the desktop file.

[nullable][transfer none]

Since: 2.34

### g_desktop_app_info_set_desktop_env ()

    void
    g_desktop_app_info_set_desktop_env (const char *desktop_env);

`g_desktop_app_info_set_desktop_env` has been deprecated since version 2.42 and should not be used in newly-written code.

do not use this API. Since 2.42 the value of the `XDG_CURRENT_DESKTOP` environment variable will be used.

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.

Should be called only once; subsequent calls are ignored.

#### Parameters

desktop_env | a string specifying what desktop this is |

### g_desktop_app_info_get_string ()

    char *
    g_desktop_app_info_get_string (GDesktopAppInfo *info,
                                   const char *key);

Looks up a string value in the keyfile backing `info` .

The `key` is looked up in the "Desktop Entry" group.

#### Parameters

info | a GDesktopAppInfo |
key | the key to look up |

#### Returns

a newly allocated string, or `NULL` if the key is not found.

[nullable]

Since: 2.36

### g_desktop_app_info_get_locale_string ()

    char *
    g_desktop_app_info_get_locale_string (GDesktopAppInfo *info,
                                          const char *key);

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.

#### Parameters

info | a GDesktopAppInfo |
key | the key to look up |

#### Returns

a newly allocated string, or `NULL` if the key is not found.

[nullable]

Since: 2.56

### g_desktop_app_info_get_boolean ()

    gboolean
    g_desktop_app_info_get_boolean (GDesktopAppInfo *info,
                                    const char *key);

Looks up a boolean value in the keyfile backing `info` .

The `key` is looked up in the "Desktop Entry" group.

#### Parameters

info | a GDesktopAppInfo |
key | the key to look up |

#### Returns

the boolean value, or `FALSE` if the key is not found

Since: 2.36

### g_desktop_app_info_get_string_list ()

    gchar **
    g_desktop_app_info_get_string_list (GDesktopAppInfo *info,
                                        const char *key,
                                        gsize *length);

Looks up a string list value in the keyfile backing `info` .

The `key` is looked up in the "Desktop Entry" group.

#### Parameters

info | a GDesktopAppInfo |
key | the key to look up |
length | return location for the number of returned strings, or `NULL`. | [out][optional]

#### Returns

a `NULL`-terminated string array or `NULL` if the specified key cannot be found. The array should be freed with `g_strfreev()`.

[array zero-terminated=1 length=length][element-type utf8][transfer full]

Since: 2.60

### g_desktop_app_info_has_key ()

    gboolean
    g_desktop_app_info_has_key (GDesktopAppInfo *info,
                                const char *key);

Returns whether `key` exists in the "Desktop Entry" group of the keyfile backing `info` .

#### Parameters

info | a GDesktopAppInfo |
key | the key to look up |

#### Returns

`TRUE` if the `key` exists

Since: 2.36

### GDesktopAppLaunchCallback ()

    void
    (*GDesktopAppLaunchCallback) (GDesktopAppInfo *appinfo,
                                  GPid pid,
                                  gpointer user_data);

During invocation, `g_desktop_app_info_launch_uris_as_manager()` may create one or more child processes. This callback is invoked once for each, providing the process ID.

#### Parameters

appinfo | a GDesktopAppInfo |
pid | Process identifier |
user_data | User data |

### g_desktop_app_info_launch_uris_as_manager ()

    gboolean
    g_desktop_app_info_launch_uris_as_manager
                                   (GDesktopAppInfo *appinfo,
                                    GList *uris,
                                    GAppLaunchContext *launch_context,
                                    GSpawnFlags spawn_flags,
                                    GSpawnChildSetupFunc user_setup,
                                    gpointer user_setup_data,
                                    GDesktopAppLaunchCallback pid_callback,
                                    gpointer pid_callback_data,
                                    GError **error);

This function performs the equivalent of `g_app_info_launch_uris()`, but is intended primarily for operating system components that launch applications. Ordinary applications should use `g_app_info_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()`. 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.

If application launching occurs via some other mechanism (eg: D-Bus activation) then `spawn_flags` , `user_setup` , `user_setup_data` , `pid_callback` and `pid_callback_data` are ignored.

#### Parameters

appinfo | a GDesktopAppInfo |
uris | List of URIs. | [element-type utf8]
launch_context | a GAppLaunchContext. | [nullable]
spawn_flags | GSpawnFlags, used for each process |
user_setup | a GSpawnChildSetupFunc, used once for each process. | [scope async][nullable]
user_setup_data | User data for `user_setup` . | [closure user_setup][nullable]
pid_callback | Callback for child processes. | [scope call][nullable]
pid_callback_data | User data for `callback` . | [closure pid_callback][nullable]
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on successful launch, `FALSE` otherwise.

### g_desktop_app_info_launch_uris_as_manager_with_fds ()

    gboolean
    g_desktop_app_info_launch_uris_as_manager_with_fds
                                   (GDesktopAppInfo *appinfo,
                                    GList *uris,
                                    GAppLaunchContext *launch_context,
                                    GSpawnFlags spawn_flags,
                                    GSpawnChildSetupFunc user_setup,
                                    gpointer user_setup_data,
                                    GDesktopAppLaunchCallback pid_callback,
                                    gpointer pid_callback_data,
                                    gint stdin_fd,
                                    gint stdout_fd,
                                    gint stderr_fd,
                                    GError **error);

Equivalent to `g_desktop_app_info_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.

#### Parameters

appinfo | a GDesktopAppInfo |
uris | List of URIs. | [element-type utf8]
launch_context | a GAppLaunchContext. | [nullable]
spawn_flags | GSpawnFlags, used for each process |
user_setup | a GSpawnChildSetupFunc, used once for each process. | [scope async][nullable][closure user_setup_data]
user_setup_data | User data for `user_setup` |
pid_callback | Callback for child processes. | [scope call][nullable][closure pid_callback_data]
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` |

#### Returns

`TRUE` on successful launch, `FALSE` otherwise.

Since: 2.58

### g_desktop_app_info_list_actions ()

    const gchar * const *
    g_desktop_app_info_list_actions (GDesktopAppInfo *info);

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.

#### Parameters

info | a GDesktopAppInfo |

#### Returns

a list of strings, always non-`NULL`.

[array zero-terminated=1][element-type utf8][transfer none]

Since: 2.38

### g_desktop_app_info_get_action_name ()

    gchar *
    g_desktop_app_info_get_action_name (GDesktopAppInfo *info,
                                        const gchar *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 action.

#### Parameters

info | a GDesktopAppInfo |
action_name | the name of the action as from `g_desktop_app_info_list_actions()` |

#### Returns

the locale-specific action name.

[transfer full]

Since: 2.38

### g_desktop_app_info_launch_action ()

    void
    g_desktop_app_info_launch_action (GDesktopAppInfo *info,
                                      const gchar *action_name,
                                      GAppLaunchContext *launch_context);

Activates the named application action.

You may only call this function on action names that were returned from `g_desktop_app_info_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 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 occur while using this function.

#### Parameters

info | a GDesktopAppInfo |
action_name | the name of the action as from `g_desktop_app_info_list_actions()` |
launch_context | a GAppLaunchContext. | [nullable]

Since: 2.38

### g_desktop_app_info_search ()

    gchar ***
    g_desktop_app_info_search (const gchar *search_string);

Searches desktop files for ones that match `search_string` .

The return value is an array of strvs. Each strv contains a list of applications that matched `search_string` with an equal score. The outer list is sorted by score so that the first strv contains the best-matching applications, and so on. The algorithm for determining matches is undefined and may change at 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 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.

#### Parameters

search_string | the search string to use |

#### Returns

a list of strvs. Free each item with `g_strfreev()` and free the outer list with `g_free()`.

[array zero-terminated=1][element-type GStrv][transfer full]

### g_desktop_app_info_get_implementations ()

    GList *
    g_desktop_app_info_get_implementations
                                   (const gchar *interface);

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.

#### Parameters

interface | the name of the interface |

#### Returns

a list of GDesktopAppInfo objects.

[element-type GDesktopAppInfo][transfer full]

Since: 2.42

## Types and Values

### GDesktopAppInfo

    typedef struct _GDesktopAppInfo GDesktopAppInfo;

Information about an installed application from a desktop file.

### GDesktopAppInfoLookup

    typedef struct _GDesktopAppInfoLookup GDesktopAppInfoLookup;

`GDesktopAppInfoLookup` has been deprecated since version 2.28 and should not be used in newly-written code.

The GDesktopAppInfoLookup interface is deprecated and unused by GIO.

GDesktopAppInfoLookup is an opaque data structure and can only be accessed using the following functions.

### struct GDesktopAppInfoLookupIface

    struct GDesktopAppInfoLookupIface {
      GTypeInterface g_iface;

      GAppInfo * (* get_default_for_uri_scheme) (GDesktopAppInfoLookup *lookup,
                                                 const char            *uri_scheme);
    };

Interface that is used by backends to associate default handlers with URI schemes.

#### Members

`get_default_for_uri_scheme` () | Virtual method for `g_desktop_app_info_lookup_get_default_for_uri_scheme()`. |

### G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME

    #define G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME "gio-desktop-app-info-lookup" GIO_DEPRECATED_MACRO_IN_2_28

`G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME` has been deprecated since version 2.28 and should not be used in newly-written code.

The GDesktopAppInfoLookup interface is deprecated and unused by GIO.

Extension point for default handler to URI association. See Extending GIO.

## Property Details

### The `“filename”` property

      “filename”                 char *

The origin filename of this GDesktopAppInfo

Owner: GDesktopAppInfo

Flags: Read / Write / Construct Only

Default value: NULL