GsApp: GNOME Software Reference Manual

## GsApp GsApp — An application that is either installed or that can be installed |

## Stability Level

Unstable, unless otherwise indicated

## Functions

GsApp * | gs_app_new ()
GsApp * | gs_app_new_from_unique_id ()
gchar * | gs_app_to_string ()
const gchar * | gs_app_get_id ()
void | gs_app_set_id ()
AsAppKind | gs_app_get_kind ()
void | gs_app_set_kind ()
AsAppState | gs_app_get_state ()
void | gs_app_set_state ()
AsAppScope | gs_app_get_scope ()
void | gs_app_set_scope ()
AsBundleKind | gs_app_get_bundle_kind ()
void | gs_app_set_bundle_kind ()
void | gs_app_set_state_recover ()
guint | gs_app_get_progress ()
void | gs_app_set_progress ()
const gchar * | gs_app_get_unique_id ()
const gchar * | gs_app_get_branch ()
void | gs_app_set_branch ()
const gchar * | gs_app_get_name ()
void | gs_app_set_name ()
const gchar * | gs_app_get_source_default ()
void | gs_app_add_source ()
GPtrArray * | gs_app_get_sources ()
void | gs_app_set_sources ()
const gchar * | gs_app_get_source_id_default ()
void | gs_app_add_source_id ()
GPtrArray * | gs_app_get_source_ids ()
void | gs_app_set_source_ids ()
void | gs_app_clear_source_ids ()
const gchar * | gs_app_get_project_group ()
void | gs_app_set_project_group ()
const gchar * | gs_app_get_version ()
const gchar * | gs_app_get_version_ui ()
void | gs_app_set_version ()
const gchar * | gs_app_get_summary ()
void | gs_app_set_summary ()
const gchar * | gs_app_get_summary_missing ()
void | gs_app_set_summary_missing ()
const gchar * | gs_app_get_description ()
void | gs_app_set_description ()
const gchar * | gs_app_get_url ()
void | gs_app_set_url ()
const gchar * | gs_app_get_license ()
gboolean | gs_app_get_license_is_free ()
void | gs_app_set_license ()
gchar ** | gs_app_get_menu_path ()
void | gs_app_set_menu_path ()
const gchar * | gs_app_get_origin ()
void | gs_app_set_origin ()
const gchar * | gs_app_get_origin_ui ()
void | gs_app_set_origin_ui ()
const gchar * | gs_app_get_origin_hostname ()
void | gs_app_set_origin_hostname ()
GPtrArray * | gs_app_get_screenshots ()
void | gs_app_add_screenshot ()
const gchar * | gs_app_get_update_version ()
const gchar * | gs_app_get_update_version_ui ()
void | gs_app_set_update_version ()
const gchar * | gs_app_get_update_details ()
void | gs_app_set_update_details ()
AsUrgencyKind | gs_app_get_update_urgency ()
void | gs_app_set_update_urgency ()
GsApp * | gs_app_get_update_runtime ()
void | gs_app_set_update_runtime ()
const gchar * | gs_app_get_management_plugin ()
void | gs_app_set_management_plugin ()
GdkPixbuf * | gs_app_get_pixbuf ()
void | gs_app_set_pixbuf ()
GPtrArray * | gs_app_get_icons ()
void | gs_app_add_icon ()
GFile * | gs_app_get_local_file ()
void | gs_app_set_local_file ()
AsContentRating * | gs_app_get_content_rating ()
void | gs_app_set_content_rating ()
GsApp * | gs_app_get_runtime ()
void | gs_app_set_runtime ()
const gchar * | gs_app_get_metadata_item ()
void | gs_app_set_metadata ()
gint | gs_app_get_rating ()
void | gs_app_set_rating ()
GArray * | gs_app_get_review_ratings ()
void | gs_app_set_review_ratings ()
GPtrArray * | gs_app_get_reviews ()
void | gs_app_add_review ()
void | gs_app_remove_review ()
GPtrArray * | gs_app_get_provides ()
void | gs_app_add_provide ()
guint64 | gs_app_get_size_installed ()
void | gs_app_set_size_installed ()
guint64 | gs_app_get_size_download ()
void | gs_app_set_size_download ()
GPtrArray * | gs_app_get_addons ()
void | gs_app_add_addon ()
GPtrArray * | gs_app_get_related ()
void | gs_app_add_related ()
GPtrArray * | gs_app_get_history ()
void | gs_app_add_history ()
guint64 | gs_app_get_install_date ()
void | gs_app_set_install_date ()
GPtrArray * | gs_app_get_categories ()
void | gs_app_set_categories ()
GPtrArray * | gs_app_get_key_colors ()
void | gs_app_set_key_colors ()
void | gs_app_add_key_color ()
gboolean | gs_app_has_category ()
void | gs_app_add_category ()
gboolean | gs_app_remove_category ()
GPtrArray * | gs_app_get_keywords ()
void | gs_app_set_keywords ()
void | gs_app_add_kudo ()
gboolean | gs_app_has_kudo ()
guint64 | gs_app_get_kudos ()
guint | gs_app_get_kudos_percentage ()
gboolean | gs_app_get_to_be_installed ()
void | gs_app_set_to_be_installed ()
void | gs_app_set_match_value ()
guint | gs_app_get_match_value ()
gboolean | gs_app_has_quirk ()
void | gs_app_add_quirk ()
void | gs_app_remove_quirk ()
gboolean | gs_app_is_installed ()
gboolean | gs_app_is_updatable ()

## Properties

gchar * | description | Read / Write / Construct
gchar * | id | Read / Write / Construct
guint64 | install-date | Read / Write / Construct
guint | kind | Read / Write / Construct
gchar * | name | Read / Write / Construct
guint | progress | Read / Write / Construct
guint64 | quirk | Read / Write / Construct
gint | rating | Read / Write / Construct
guint | state | Read / Write / Construct
gchar * | summary | Read / Write / Construct
gchar * | version | Read / Write / Construct

## Types and Values

#define | GS_TYPE_APP
enum | GsAppKudo
#define | GS_APP_INSTALL_DATE_UNSET
#define | GS_APP_INSTALL_DATE_UNKNOWN
#define | GS_APP_SIZE_UNKNOWABLE
enum | GsAppQuality
| GsApp

## Object Hierarchy

        GObject
        ╰── GsApp

## Includes

    #include <gnome-software.h>

## Description

This object represents a 1:1 mapping to a .desktop file. The design is such so you can't have different GsApp's for different versions or architectures of a package. This rule really only applies to GsApps of kind `AS_APP_KIND_DESKTOP` and `AS_APP_KIND_GENERIC`. We allow GsApps of kind `AS_APP_KIND_OS_UPDATE` or `AS_APP_KIND_GENERIC`, which don't correspond to desktop files, but instead represent a system update and its individual components.

The GsPluginLoader de-duplicates the GsApp instances that are produced by plugins to ensure that there is a single instance of GsApp for each id, making the id the primary key for this object. This ensures that actions triggered on a GsApp in different parts of gnome-software can be observed by connecting to signals on the GsApp.

Information about other GsApp objects can be stored in this object, for instance in the `gs_app_add_related()` method or `gs_app_get_history()`.

## Functions

### gs_app_new ()

    GsApp *
    gs_app_new (const gchar *id);

Creates a new application object.

The ID should only be set when the application ID (with optional prefix) is known; it is perfectly valid to use `gs_app_new()` with an `id` of `NULL`, and then relying on another plugin to set the `id` using `gs_app_set_id()` based on some other information.

For instance, a GsApp is created with no ID when returning results from the packagekit plugin, but with the default source name set as the package name. The source name is read by the appstream plugin, and if matched in the AppStream XML the correct ID is set, along with other higher quality data like the application icon and long description.

#### Parameters

id | an application ID, or `NULL`, e.g. "org.gnome.Software.desktop" |

#### Returns

a new GsApp

Since: 3.22

### gs_app_new_from_unique_id ()

    GsApp *
    gs_app_new_from_unique_id (const gchar *unique_id);

Creates a new application object.

The unique ID will be parsed to set some information in the application such as the scope, bundle kind, id, etc. Unlike `gs_app_new()`, it cannot take a `NULL` argument.

#### Parameters

unique_id | an application unique ID, e.g. `system/flatpak/gnome/desktop/org.gnome.Software.desktop/master` |

#### Returns

a new GsApp

Since: 3.22

### gs_app_to_string ()

    gchar *
    gs_app_to_string (GsApp *app);

Converts the application to a string. This is not designed to serialize the object but to produce a string suitable for debugging.

#### Parameters

app | a GsApp |

#### Returns

A multi-line string

Since: 3.22

### gs_app_get_id ()

    const gchar *
    gs_app_get_id (GsApp *app);

Gets the application ID.

#### Parameters

app | a GsApp |

#### Returns

The whole ID, e.g. "gimp.desktop"

Since: 3.22

### gs_app_set_id ()

    void
    gs_app_set_id (GsApp *app,
                   const gchar *id);

Sets the application ID.

#### Parameters

app | a GsApp |
id | a application ID, e.g. "gimp.desktop" |

### gs_app_get_kind ()

    AsAppKind
    gs_app_get_kind (GsApp *app);

Gets the kind of the application.

#### Parameters

app | a GsApp |

#### Returns

the AsAppKind, e.g. `AS_APP_KIND_UNKNOWN`

Since: 3.22

### gs_app_set_kind ()

    void
    gs_app_set_kind (GsApp *app,
                     AsAppKind kind);

This sets the kind of the application. The following state diagram explains the typical states. All applications start with kind `AS_APP_KIND_UNKNOWN`.

    1
    2
    3
    PACKAGE --> NORMAL
    PACKAGE --> SYSTEM
    NORMAL  --> SYSTEM

#### Parameters

app | a GsApp |
kind | a AsAppKind, e.g. AS_APP_KIND_DESKTOP |

Since: 3.22

### gs_app_get_state ()

    AsAppState
    gs_app_get_state (GsApp *app);

Gets the state of the application.

#### Parameters

app | a GsApp |

#### Returns

the AsAppState, e.g. `AS_APP_STATE_INSTALLED`

Since: 3.22

### gs_app_set_state ()

    void
    gs_app_set_state (GsApp *app,
                      AsAppState state);

This sets the state of the application. The following state diagram explains the typical states. All applications start in state `AS_APP_STATE_UNKNOWN`, but the frontend is not supposed to see GsApps with this state.

Plugins are reponsible for changing the state to one of the other states before the GsApp is passed to the frontend.

    1
    2
    3
    4
    5
    6
    UPDATABLE --> INSTALLING --> INSTALLED
    UPDATABLE --> REMOVING   --> AVAILABLE
    INSTALLED --> REMOVING   --> AVAILABLE
    AVAILABLE --> INSTALLING --> INSTALLED
    AVAILABLE <--> QUEUED --> INSTALLING --> INSTALLED
    UNKNOWN   --> UNAVAILABLE

#### Parameters

app | a GsApp |
state | a AsAppState, e.g. AS_APP_STATE_UPDATABLE_LIVE |

Since: 3.22

### gs_app_get_scope ()

    AsAppScope
    gs_app_get_scope (GsApp *app);

Gets the scope of the application.

#### Parameters

app | a GsApp |

#### Returns

the AsAppScope, e.g. `AS_APP_SCOPE_USER`

Since: 3.22

### gs_app_set_scope ()

    void
    gs_app_set_scope (GsApp *app,
                      AsAppScope scope);

This sets the scope of the application.

#### Parameters

app | a GsApp |
scope | a AsAppScope, e.g. AS_APP_SCOPE_SYSTEM |

Since: 3.22

### gs_app_get_bundle_kind ()

    AsBundleKind
    gs_app_get_bundle_kind (GsApp *app);

Gets the bundle kind of the application.

#### Parameters

app | a GsApp |

#### Returns

the AsAppScope, e.g. `AS_BUNDLE_KIND_FLATPAK`

Since: 3.22

### gs_app_set_bundle_kind ()

    void
    gs_app_set_bundle_kind (GsApp *app,
                            AsBundleKind bundle_kind);

This sets the bundle kind of the application.

#### Parameters

app | a GsApp |
bundle_kind | a AsAppScope, e.g. AS_BUNDLE_KIND_FLATPAK |

Since: 3.22

### gs_app_set_state_recover ()

    void
    gs_app_set_state_recover (GsApp *app);

Sets the application state to the last status value that was not transient.

#### Parameters

app | a GsApp |

Since: 3.22

### gs_app_get_progress ()

    guint
    gs_app_get_progress (GsApp *app);

Gets the percentage completion.

#### Parameters

app | a GsApp |

#### Returns

the percentage completion, or 0 for unknown

Since: 3.22

### gs_app_set_progress ()

    void
    gs_app_set_progress (GsApp *app,
                         guint percentage);

This sets the progress completion of the application. If called more than once with the same value then subsequent calls will be ignored.

#### Parameters

app | a GsApp |
percentage | a percentage progress |

Since: 3.22

### gs_app_get_unique_id ()

    const gchar *
    gs_app_get_unique_id (GsApp *app);

Gets the unique application ID used for de-duplication. If nothing has been set the value from `gs_app_get_id()` will be used.

#### Parameters

app | a GsApp |

#### Returns

The unique ID, e.g. `system/package/fedora/desktop/gimp.desktop/i386/master`, or `NULL`

Since: 3.22

### gs_app_get_branch ()

    const gchar *
    gs_app_get_branch (GsApp *app);

Gets the application branch.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_branch ()

    void
    gs_app_set_branch (GsApp *app,
                       const gchar *branch);

Sets the application branch.

#### Parameters

app | a GsApp |
branch | The branch, e.g. "master" |

Since: 3.22

### gs_app_get_name ()

    const gchar *
    gs_app_get_name (GsApp *app);

Gets the application name.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_name ()

    void
    gs_app_set_name (GsApp *app,
                     GsAppQuality quality,
                     const gchar *name);

Sets the application name.

#### Parameters

app | a GsApp |
quality | A GsAppQuality, e.g. `GS_APP_QUALITY_LOWEST` |
name | The short localized name, e.g. "Calculator" |

Since: 3.22

### gs_app_get_source_default ()

    const gchar *
    gs_app_get_source_default (GsApp *app);

Gets the default source.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL`

Since: 3.22

### gs_app_add_source ()

    void
    gs_app_add_source (GsApp *app,
                       const gchar *source);

Adds a source name for the application.

#### Parameters

app | a GsApp |
source | a source name |

Since: 3.22

### gs_app_get_sources ()

    GPtrArray *
    gs_app_get_sources (GsApp *app);

Gets the list of sources for the application.

#### Parameters

app | a GsApp |

#### Returns

a list.

[element-type utf8][transfer none]

Since: 3.22

### gs_app_set_sources ()

    void
    gs_app_set_sources (GsApp *app,
                        GPtrArray *sources);

This name is used for the update page if the application is collected into the 'OS Updates' group. It is typically the package names, although this should not be relied upon.

#### Parameters

app | a GsApp |
sources | The non-localized short names, e.g. ["gnome-calculator"] |

Since: 3.22

### gs_app_get_source_id_default ()

    const gchar *
    gs_app_get_source_id_default (GsApp *app);

Gets the default source ID.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_add_source_id ()

    void
    gs_app_add_source_id (GsApp *app,
                          const gchar *source_id);

Adds a source ID to the application.

#### Parameters

app | a GsApp |
source_id | a source ID, e.g. "gnome-calculator;0.134;fedora" |

Since: 3.22

### gs_app_get_source_ids ()

    GPtrArray *
    gs_app_get_source_ids (GsApp *app);

Gets the list of source IDs.

#### Parameters

app | a GsApp |

#### Returns

a list.

[element-type utf8][transfer none]

Since: 3.22

### gs_app_set_source_ids ()

    void
    gs_app_set_source_ids (GsApp *app,
                           GPtrArray *source_ids);

This ID is used internally to the controlling plugin.

#### Parameters

app | a GsApp |
source_ids | The source-id, e.g. ["gnome-calculator;0.134;fedora"] or ["/home/hughsie/.local/share/applications/0ad.desktop"] |

Since: 3.22

### gs_app_clear_source_ids ()

    void
    gs_app_clear_source_ids (GsApp *app);

Clear the list of source IDs.

#### Parameters

app | a GsApp |

Since: 3.22

### gs_app_get_project_group ()

    const gchar *
    gs_app_get_project_group (GsApp *app);

Gets a project group for the application. Applications belonging to other project groups may not be shown in this software center.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_project_group ()

    void
    gs_app_set_project_group (GsApp *app,
                              const gchar *project_group);

Sets a project group for the application.

#### Parameters

app | a GsApp |
project_group | The non-localized project group, e.g. "GNOME" or "KDE" |

Since: 3.22

### gs_app_get_version ()

    const gchar *
    gs_app_get_version (GsApp *app);

Gets the exact version for the application.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_get_version_ui ()

    const gchar *
    gs_app_get_version_ui (GsApp *app);

Gets a version string that can be displayed in a UI.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_version ()

    void
    gs_app_set_version (GsApp *app,
                        const gchar *version);

This saves the version after stripping out any non-friendly parts, such as distro tags, git revisions and that kind of thing.

#### Parameters

app | a GsApp |
version | The version, e.g. "2:1.2.3.fc19" |

Since: 3.22

### gs_app_get_summary ()

    const gchar *
    gs_app_get_summary (GsApp *app);

Gets the single-line description of the application.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_summary ()

    void
    gs_app_set_summary (GsApp *app,
                        GsAppQuality quality,
                        const gchar *summary);

The medium length one-line localized name.

#### Parameters

app | a GsApp |
quality | a GsAppQuality, e.g. `GS_APP_QUALITY_LOWEST` |
summary | a string, e.g. "A graphical calculator for GNOME" |

Since: 3.22

### gs_app_get_summary_missing ()

    const gchar *
    gs_app_get_summary_missing (GsApp *app);

Gets the one-line summary to use when this application is missing.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_summary_missing ()

    void
    gs_app_set_summary_missing (GsApp *app,
                                const gchar *summary_missing);

Sets the one-line summary to use when this application is missing.

#### Parameters

app | a GsApp |
summary_missing | a string, or `NULL` |

Since: 3.22

### gs_app_get_description ()

    const gchar *
    gs_app_get_description (GsApp *app);

Gets the long multi-line description of the application.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_description ()

    void
    gs_app_set_description (GsApp *app,
                            GsAppQuality quality,
                            const gchar *description);

Sets the long multi-line description of the application.

#### Parameters

app | a GsApp |
quality | a GsAppQuality, e.g. `GS_APP_QUALITY_LOWEST` |
description | a string, e.g. "GNOME Calculator is a graphical calculator for GNOME..." |

Since: 3.22

### gs_app_get_url ()

    const gchar *
    gs_app_get_url (GsApp *app,
                    AsUrlKind kind);

Gets a web address of a specific type.

#### Parameters

app | a GsApp |
kind | a AsUrlKind, e.g. `AS_URL_KIND_HOMEPAGE` |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_url ()

    void
    gs_app_set_url (GsApp *app,
                    AsUrlKind kind,
                    const gchar *url);

Sets a web address of a specific type.

#### Parameters

app | a GsApp |
kind | a AsUrlKind, e.g. `AS_URL_KIND_HOMEPAGE` |
url | a web URL, e.g. "http://www.hughsie.com/" |

Since: 3.22

### gs_app_get_license ()

    const gchar *
    gs_app_get_license (GsApp *app);

Gets the project license of the application.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_get_license_is_free ()

    gboolean
    gs_app_get_license_is_free (GsApp *app);

Returns if the application is free software.

#### Parameters

app | a GsApp |

#### Returns

`TRUE` if the application is free software

Since: 3.22

### gs_app_set_license ()

    void
    gs_app_set_license (GsApp *app,
                        GsAppQuality quality,
                        const gchar *license);

Sets the project licenses used in the application.

#### Parameters

app | a GsApp |
quality | a GsAppQuality, e.g. `GS_APP_QUALITY_NORMAL` |
license | a SPDX license string, e.g. "GPL-3.0 AND LGPL-2.0+" |

Since: 3.22

### gs_app_get_menu_path ()

    gchar **
    gs_app_get_menu_path (GsApp *app);

Returns the menu path which is an array of path elements. The resulting array is an internal structure and must not be modified or freed.

#### Parameters

app | a GsApp |

#### Returns

a `NULL`-terminated array of strings

Since: 3.22

### gs_app_set_menu_path ()

    void
    gs_app_set_menu_path (GsApp *app,
                          gchar **menu_path);

Sets the new menu path. The menu path is an array of path elements. This function creates a deep copy of the path.

#### Parameters

app | a GsApp |
menu_path | a `NULL`-terminated array of strings |

Since: 3.22

### gs_app_get_origin ()

    const gchar *
    gs_app_get_origin (GsApp *app);

Gets the origin for the application, e.g. "fedora".

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_origin ()

    void
    gs_app_set_origin (GsApp *app,
                       const gchar *origin);

The origin is the original source of the application e.g. "fedora-updates"

#### Parameters

app | a GsApp |
origin | a string, or `NULL` |

Since: 3.22

### gs_app_get_origin_ui ()

    const gchar *
    gs_app_get_origin_ui (GsApp *app);

Gets the UI-visible origin used to install the application, e.g. "Fedora".

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_origin_ui ()

    void
    gs_app_set_origin_ui (GsApp *app,
                          const gchar *origin_ui);

The origin is the original source of the application to show in the UI, e.g. "Fedora"

#### Parameters

app | a GsApp |
origin_ui | a string, or `NULL` |

Since: 3.22

### gs_app_get_origin_hostname ()

    const gchar *
    gs_app_get_origin_hostname (GsApp *app);

Gets the hostname of the origin used to install the application, e.g. "fedoraproject.org" or "sdk.gnome.org".

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_origin_hostname ()

    void
    gs_app_set_origin_hostname (GsApp *app,
                                const gchar *origin_hostname);

The origin is the hostname of the source used to install the application e.g. "fedoraproject.org"

You can also use a full URL as `origin_hostname` and this will be parsed and the hostname extracted. This process will also remove any unnecessary DNS prefixes like "download" or "mirrors".

#### Parameters

app | a GsApp |
origin_hostname | a string, or `NULL` |

Since: 3.22

### gs_app_get_screenshots ()

    GPtrArray *
    gs_app_get_screenshots (GsApp *app);

Gets the list of screenshots.

#### Parameters

app | a GsApp |

#### Returns

a list.

[element-type AsScreenshot][transfer none]

Since: 3.22

### gs_app_add_screenshot ()

    void
    gs_app_add_screenshot (GsApp *app,
                           AsScreenshot *screenshot);

Adds a screenshot to the applicaton.

#### Parameters

app | a GsApp |
screenshot | a AsScreenshot |

Since: 3.22

### gs_app_get_update_version ()

    const gchar *
    gs_app_get_update_version (GsApp *app);

Gets the newest update version.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_get_update_version_ui ()

    const gchar *
    gs_app_get_update_version_ui (GsApp *app);

Gets the update version for the UI.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_update_version ()

    void
    gs_app_set_update_version (GsApp *app,
                               const gchar *update_version);

Sets the new version number of the update.

#### Parameters

app | a GsApp |
update_version | a string, e.g. "0.1.2.3" |

Since: 3.22

### gs_app_get_update_details ()

    const gchar *
    gs_app_get_update_details (GsApp *app);

Gets the multi-line description for the update.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_update_details ()

    void
    gs_app_set_update_details (GsApp *app,
                               const gchar *update_details);

Sets the multi-line description for the update.

#### Parameters

app | a GsApp |
update_details | a string |

Since: 3.22

### gs_app_get_update_urgency ()

    AsUrgencyKind
    gs_app_get_update_urgency (GsApp *app);

Gets the update urgency.

#### Parameters

app | a GsApp |

#### Returns

a AsUrgencyKind, or `AS_URGENCY_KIND_UNKNOWN` for unset

Since: 3.22

### gs_app_set_update_urgency ()

    void
    gs_app_set_update_urgency (GsApp *app,
                               AsUrgencyKind update_urgency);

Sets the update urgency.

#### Parameters

app | a GsApp |
update_urgency | a AsUrgencyKind |

Since: 3.22

### gs_app_get_update_runtime ()

    GsApp *
    gs_app_get_update_runtime (GsApp *app);

Gets the runtime required for the application update.

#### Parameters

app | a GsApp |

#### Returns

a GsApp, or `NULL` for unset.

[transfer none]

Since: 3.24

### gs_app_set_update_runtime ()

    void
    gs_app_set_update_runtime (GsApp *app,
                               GsApp *runtime);

Sets the runtime that the application update requires.

#### Parameters

app | a GsApp |
runtime | a GsApp |

Since: 3.24

### gs_app_get_management_plugin ()

    const gchar *
    gs_app_get_management_plugin (GsApp *app);

Gets the management plugin. This is some metadata about the application which is used to work out which plugin should handle the install, remove or upgrade actions.

Typically plugins will just set this to the plugin name using `gs_plugin_get_name()`.

#### Parameters

app | a GsApp |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_management_plugin ()

    void
    gs_app_set_management_plugin (GsApp *app,
                                  const gchar *management_plugin);

The management plugin is the plugin that can handle doing install and remove operations on the GsApp. Typical values include "packagekit" and "flatpak"

It is an error to attempt to change the management plugin once it has been previously set or to try to use this function on a wildcard application.

#### Parameters

app | a GsApp |
management_plugin | a string, or `NULL`, e.g. "fwupd" |

Since: 3.22

### gs_app_get_pixbuf ()

    GdkPixbuf *
    gs_app_get_pixbuf (GsApp *app);

Gets a pixbuf to represent the application.

#### Parameters

app | a GsApp |

#### Returns

a GdkPixbuf, or `NULL`.

[transfer none]

Since: 3.22

### gs_app_set_pixbuf ()

    void
    gs_app_set_pixbuf (GsApp *app,
                       GdkPixbuf *pixbuf);

Sets a pixbuf used to represent the application.

#### Parameters

app | a GsApp |
pixbuf | a GdkPixbuf, or `NULL` |

Since: 3.22

### gs_app_get_icons ()

    GPtrArray *
    gs_app_get_icons (GsApp *app);

Gets the icons for the application.

#### Parameters

app | a GsApp |

#### Returns

an array of icons.

[transfer none][element-type AsIcon]

Since: 3.22

### gs_app_add_icon ()

    void
    gs_app_add_icon (GsApp *app,
                     AsIcon *icon);

Adds an icon to use for the application. If the first icon added cannot be loaded then the next one is tried.

#### Parameters

app | a GsApp |
icon | a AsIcon, or `NULL` to remove all icons |

Since: 3.22

### gs_app_get_local_file ()

    GFile *
    gs_app_get_local_file (GsApp *app);

Gets the file that backs this application, for instance this might be a local file in ~/Downloads that we are installing.

#### Parameters

app | a GsApp |

#### Returns

a GFile, or `NULL`.

[transfer none]

Since: 3.22

### gs_app_set_local_file ()

    void
    gs_app_set_local_file (GsApp *app,
                           GFile *local_file);

Sets the file that backs this application, for instance this might be a local file in ~/Downloads that we are installing.

#### Parameters

app | a GsApp |
local_file | a GFile, or `NULL` |

Since: 3.22

### gs_app_get_content_rating ()

    AsContentRating *
    gs_app_get_content_rating (GsApp *app);

Gets the content rating for this application.

#### Parameters

app | a GsApp |

#### Returns

a AsContentRating, or `NULL`.

[transfer none]

Since: 3.24

### gs_app_set_content_rating ()

    void
    gs_app_set_content_rating (GsApp *app,
                               AsContentRating *content_rating);

Sets the content rating for this application.

#### Parameters

app | a GsApp |
content_rating | a AsContentRating, or `NULL` |

Since: 3.24

### gs_app_get_runtime ()

    GsApp *
    gs_app_get_runtime (GsApp *app);

Gets the runtime for the installed application if the application is already installed, or the runtime for the available application otherwise.

#### Parameters

app | a GsApp |

#### Returns

a GsApp, or `NULL` for unset.

[transfer none]

Since: 3.22

### gs_app_set_runtime ()

    void
    gs_app_set_runtime (GsApp *app,
                        GsApp *runtime);

Sets the runtime that the installed application requires.

#### Parameters

app | a GsApp |
runtime | a GsApp |

Since: 3.22

### gs_app_get_metadata_item ()

    const gchar *
    gs_app_get_metadata_item (GsApp *app,
                              const gchar *key);

Gets some metadata for the application. Is is expected that plugins namespace any plugin-specific metadata, for example `fwupd::device-id`.

#### Parameters

app | a GsApp |
key | a string, e.g. "fwupd::device-id" |

#### Returns

a string, or `NULL` for unset

Since: 3.22

### gs_app_set_metadata ()

    void
    gs_app_set_metadata (GsApp *app,
                         const gchar *key,
                         const gchar *value);

Sets some metadata for the application. Is is expected that plugins namespace any plugin-specific metadata, for example `fwupd::device-id`.

#### Parameters

app | a GsApp |
key | a string, e.g. "fwupd::device-id" |
value | a string, e.g. "fubar" |

Since: 3.22

### gs_app_get_rating ()

    gint
    gs_app_get_rating (GsApp *app);

Gets the percentage rating of the application, where 100 is 5 stars.

#### Parameters

app | a GsApp |

#### Returns

a percentage, or -1 for unset

Since: 3.22

### gs_app_set_rating ()

    void
    gs_app_set_rating (GsApp *app,
                       gint rating);

Gets the percentage rating of the application.

#### Parameters

app | a GsApp |
rating | a percentage, or -1 for invalid |

Since: 3.22

### gs_app_get_review_ratings ()

    GArray *
    gs_app_get_review_ratings (GsApp *app);

Gets the review ratings.

#### Parameters

app | a GsApp |

#### Returns

a list.

[element-type gint][transfer none]

Since: 3.22

### gs_app_set_review_ratings ()

    void
    gs_app_set_review_ratings (GsApp *app,
                               GArray *review_ratings);

Sets the review ratings.

#### Parameters

app | a GsApp |
review_ratings | a list. | [element-type gint]

Since: 3.22

### gs_app_get_reviews ()

    GPtrArray *
    gs_app_get_reviews (GsApp *app);

Gets all the user-submitted reviews for the application.

#### Parameters

app | a GsApp |

#### Returns

the list of reviews.

[element-type AsReview][transfer none]

Since: 3.22

### gs_app_add_review ()

    void
    gs_app_add_review (GsApp *app,
                       AsReview *review);

Adds a user-submitted review to the application.

#### Parameters

app | a GsApp |
review | a AsReview |

Since: 3.22

### gs_app_remove_review ()

    void
    gs_app_remove_review (GsApp *app,
                          AsReview *review);

Removes a user-submitted review to the application.

#### Parameters

app | a GsApp |
review | a AsReview |

Since: 3.22

### gs_app_get_provides ()

    GPtrArray *
    gs_app_get_provides (GsApp *app);

Gets all the provides for the application.

#### Parameters

app | a GsApp |

#### Returns

the list of provides.

[element-type AsProvide][transfer none]

Since: 3.22

### gs_app_add_provide ()

    void
    gs_app_add_provide (GsApp *app,
                        AsProvide *provide);

Adds a provide to the application.

#### Parameters

app | a GsApp |
provide | a AsProvide |

Since: 3.22

### gs_app_get_size_installed ()

    guint64
    gs_app_get_size_installed (GsApp *app);

Gets the size on disk, either for an existing application of one that could be installed.

If there is a runtime not yet installed then this is also added.

#### Parameters

app | a GsApp |

#### Returns

size in bytes, 0 for unknown, or `GS_APP_SIZE_UNKNOWABLE` for invalid.

Since: 3.22

### gs_app_set_size_installed ()

    void
    gs_app_set_size_installed (GsApp *app,
                               guint64 size_installed);

Sets the installed size of the application.

#### Parameters

app | a GsApp |
size_installed | size in bytes, or `GS_APP_SIZE_UNKNOWABLE` for invalid |

Since: 3.22

### gs_app_get_size_download ()

    guint64
    gs_app_get_size_download (GsApp *app);

Gets the size of the total download needed to either install an available application, or update an already installed one.

If there is a runtime not yet installed then this is also added.

#### Parameters

app | A GsApp |

#### Returns

number of bytes, 0 for unknown, or `GS_APP_SIZE_UNKNOWABLE` for invalid

Since: 3.22

### gs_app_set_size_download ()

    void
    gs_app_set_size_download (GsApp *app,
                              guint64 size_download);

Sets the download size of the application, not including any required runtime.

#### Parameters

app | a GsApp |
size_download | size in bytes, or `GS_APP_SIZE_UNKNOWABLE` for invalid |

Since: 3.22

### gs_app_get_addons ()

    GPtrArray *
    gs_app_get_addons (GsApp *app);

Gets the list of addons for the application.

#### Parameters

app | a GsApp |

#### Returns

a list of addons.

[element-type GsApp][transfer none]

Since: 3.22

### gs_app_add_addon ()

    void
    gs_app_add_addon (GsApp *app,
                      GsApp *addon);

Adds an addon to the list of application addons.

#### Parameters

app | a GsApp |
addon | a GsApp |

Since: 3.22

### gs_app_get_related ()

    GPtrArray *
    gs_app_get_related (GsApp *app);

Gets any related applications.

#### Parameters

app | a GsApp |

#### Returns

a list of applications.

[element-type GsApp][transfer none]

Since: 3.22

### gs_app_add_related ()

    void
    gs_app_add_related (GsApp *app,
                        GsApp *app2);

Adds a related application.

#### Parameters

app | a GsApp |
app2 | a GsApp |

Since: 3.22

### gs_app_get_history ()

    GPtrArray *
    gs_app_get_history (GsApp *app);

Gets the history of this application.

#### Parameters

app | a GsApp |

#### Returns

a list.

[element-type GsApp][transfer none]

Since: 3.22

### gs_app_add_history ()

    void
    gs_app_add_history (GsApp *app,
                        GsApp *app2);

Adds a history item for this package.

#### Parameters

app | a GsApp |
app2 | a GsApp |

Since: 3.22

### gs_app_get_install_date ()

    guint64
    gs_app_get_install_date (GsApp *app);

Gets the date that an application was installed.

#### Parameters

app | a GsApp |

#### Returns

A UNIX epoch, or 0 for unset

Since: 3.22

### gs_app_set_install_date ()

    void
    gs_app_set_install_date (GsApp *app,
                             guint64 install_date);

Sets the date that an application was installed.

#### Parameters

app | a GsApp |
install_date | an epoch, or `GS_APP_INSTALL_DATE_UNKNOWN` |

Since: 3.22

### gs_app_get_categories ()

    GPtrArray *
    gs_app_get_categories (GsApp *app);

Gets the list of categories for an application.

#### Parameters

app | a GsApp |

#### Returns

a list.

[element-type utf8][transfer none]

Since: 3.22

### gs_app_set_categories ()

    void
    gs_app_set_categories (GsApp *app,
                           GPtrArray *categories);

Set the list of categories for an application.

#### Parameters

app | a GsApp |
categories | a set of categories |

Since: 3.22

### gs_app_get_key_colors ()

    GPtrArray *
    gs_app_get_key_colors (GsApp *app);

Gets the key colors used in the application icon.

#### Parameters

app | a GsApp |

#### Returns

a list.

[element-type GdkRGBA][transfer none]

Since: 3.22

### gs_app_set_key_colors ()

    void
    gs_app_set_key_colors (GsApp *app,
                           GPtrArray *key_colors);

Sets the key colors used in the application icon.

#### Parameters

app | a GsApp |
key_colors | a set of key colors. | [element-type GdkRGBA]

Since: 3.22

### gs_app_add_key_color ()

    void
    gs_app_add_key_color (GsApp *app,
                          GdkRGBA *key_color);

Adds a key colors used in the application icon.

#### Parameters

app | a GsApp |
key_color | a GdkRGBA |

Since: 3.22

### gs_app_has_category ()

    gboolean
    gs_app_has_category (GsApp *app,
                         const gchar *category);

Checks if the application is in a specific category.

#### Parameters

app | a GsApp |
category | a category ID, e.g. "AudioVideo" |

#### Returns

`TRUE` for success

Since: 3.22

### gs_app_add_category ()

    void
    gs_app_add_category (GsApp *app,
                         const gchar *category);

Adds a category ID to an application.

#### Parameters

app | a GsApp |
category | a category ID, e.g. "AudioVideo" |

Since: 3.22

### gs_app_remove_category ()

    gboolean
    gs_app_remove_category (GsApp *app,
                            const gchar *category);

Removes an category ID from an application, it exists.

#### Parameters

app | a GsApp |
category | a category ID, e.g. "AudioVideo" |

#### Returns

`TRUE` for success

Since: 3.24

### gs_app_get_keywords ()

    GPtrArray *
    gs_app_get_keywords (GsApp *app);

Gets the list of application keywords in the users locale.

#### Parameters

app | a GsApp |

#### Returns

a list.

[element-type utf8][transfer none]

Since: 3.22

### gs_app_set_keywords ()

    void
    gs_app_set_keywords (GsApp *app,
                         GPtrArray *keywords);

Sets the list of application keywords in the users locale.

#### Parameters

app | a GsApp |
keywords | a set of keywords. | [element-type utf8]

Since: 3.22

### gs_app_add_kudo ()

    void
    gs_app_add_kudo (GsApp *app,
                     GsAppKudo kudo);

Adds a kudo to the application.

#### Parameters

app | a GsApp |
kudo | a GsAppKudo, e.g. `GS_APP_KUDO_MY_LANGUAGE` |

Since: 3.22

### gs_app_has_kudo ()

    gboolean
    gs_app_has_kudo (GsApp *app,
                     GsAppKudo kudo);

Finds out if a kudo has been awarded by the application.

#### Parameters

app | a GsApp |
kudo | a GsAppKudo, e.g. `GS_APP_KUDO_MY_LANGUAGE` |

#### Returns

`TRUE` if the app has the specified kudo

Since: 3.22

### gs_app_get_kudos ()

    guint64
    gs_app_get_kudos (GsApp *app);

Gets all the kudos the application has been awarded.

#### Parameters

app | a GsApp |

#### Returns

the kudos, as a bitfield

Since: 3.22

### gs_app_get_kudos_percentage ()

    guint
    gs_app_get_kudos_percentage (GsApp *app);

Gets the kudos, as a percentage value.

#### Parameters

app | a GsApp |

#### Returns

a percentage, with 0 for no kudos and a maximum of 100.

Since: 3.22

### gs_app_get_to_be_installed ()

    gboolean
    gs_app_get_to_be_installed (GsApp *app);

Gets if the application is queued for installation.

This is only set for addons when the user has selected some addons to be installed before installing the main application. Plugins should check all the addons for this property when installing main applications so that the chosen set of addons is also installed at the same time. This is never set when applications do not have addons.

#### Parameters

app | a GsApp |

#### Returns

`TRUE` for success

Since: 3.22

### gs_app_set_to_be_installed ()

    void
    gs_app_set_to_be_installed (GsApp *app,
                                gboolean to_be_installed);

Sets if the application is queued for installation.

#### Parameters

app | a GsApp |
to_be_installed | if the app is due to be installed |

Since: 3.22

### gs_app_set_match_value ()

    void
    gs_app_set_match_value (GsApp *app,
                            guint match_value);

Set a match quality value, where higher values correspond to a "better" search match, and should be shown above lower results.

#### Parameters

app | a GsApp |
match_value | a value |

Since: 3.22

### gs_app_get_match_value ()

    guint
    gs_app_get_match_value (GsApp *app);

Get a match quality value, where higher values correspond to a "better" search match, and should be shown above lower results.

Note: This value is only valid when processing the result set and may be overwritten on subsequent searches if the plugin is using a cache.

#### Parameters

app | a GsApp |

#### Returns

a value, where higher is better

Since: 3.22

### gs_app_has_quirk ()

    gboolean
    gs_app_has_quirk (GsApp *app,
                      AsAppQuirk quirk);

Finds out if an application has a specific quirk.

#### Parameters

app | a GsApp |
quirk | a AsAppQuirk, e.g. `AS_APP_QUIRK_COMPULSORY` |

#### Returns

`TRUE` for success

Since: 3.22

### gs_app_add_quirk ()

    void
    gs_app_add_quirk (GsApp *app,
                      AsAppQuirk quirk);

Adds a quirk to an application.

#### Parameters

app | a GsApp |
quirk | a AsAppQuirk, e.g. `AS_APP_QUIRK_COMPULSORY` |

Since: 3.22

### gs_app_remove_quirk ()

    void
    gs_app_remove_quirk (GsApp *app,
                         AsAppQuirk quirk);

Removes a quirk from an application.

#### Parameters

app | a GsApp |
quirk | a AsAppQuirk, e.g. `AS_APP_QUIRK_COMPULSORY` |

Since: 3.22

### gs_app_is_installed ()

    gboolean
    gs_app_is_installed (GsApp *app);

Gets whether the app is installed or not.

#### Parameters

app | a GsApp |

#### Returns

`TRUE` if the app is installed, `FALSE` otherwise.

Since: 3.22

### gs_app_is_updatable ()

    gboolean
    gs_app_is_updatable (GsApp *app);

Gets whether the app is updatable or not.

#### Parameters

app | a GsApp |

#### Returns

`TRUE` if the app is updatable, `FALSE` otherwise.

Since: 3.22

## Types and Values

### GS_TYPE_APP

    #define GS_TYPE_APP (gs_app_get_type ())

### enum GsAppKudo

Any awards given to the application.

#### Members

GS_APP_KUDO_MY_LANGUAGE | Localised in my language |
GS_APP_KUDO_RECENT_RELEASE | Released recently |
GS_APP_KUDO_FEATURED_RECOMMENDED | Chosen for the front page |
GS_APP_KUDO_MODERN_TOOLKIT | Uses a modern toolkit |
GS_APP_KUDO_SEARCH_PROVIDER | Provides a search provider |
GS_APP_KUDO_INSTALLS_USER_DOCS | Installs user docs |
GS_APP_KUDO_USES_NOTIFICATIONS | Registers notifications |
GS_APP_KUDO_HAS_KEYWORDS | Has at least 1 keyword |
GS_APP_KUDO_USES_APP_MENU | Uses an AppMenu for navigation |
GS_APP_KUDO_HAS_SCREENSHOTS | Supplies screenshots |
GS_APP_KUDO_POPULAR | Is popular |
GS_APP_KUDO_PERFECT_SCREENSHOTS | Supplies perfect screenshots |
GS_APP_KUDO_HIGH_CONTRAST | Installs a high contrast icon |
GS_APP_KUDO_HI_DPI_ICON | Installs a HiDPI icon |
GS_APP_KUDO_SANDBOXED | Application is sandboxed |
GS_APP_KUDO_SANDBOXED_SECURE | Application is sandboxed securely |

### GS_APP_INSTALL_DATE_UNSET

    #define GS_APP_INSTALL_DATE_UNSET		0

### GS_APP_INSTALL_DATE_UNKNOWN

    #define GS_APP_INSTALL_DATE_UNKNOWN		1 /* 1s past the epoch */

### GS_APP_SIZE_UNKNOWABLE

    #define GS_APP_SIZE_UNKNOWABLE			G_MAXUINT64

### enum GsAppQuality

Any awards given to the application.

#### Members

GS_APP_QUALITY_UNKNOWN | The quality value is unknown |
GS_APP_QUALITY_LOWEST | Lowest quality |
GS_APP_QUALITY_NORMAL | Normal quality |
GS_APP_QUALITY_HIGHEST | Highest quality |

### GsApp

    typedef struct _GsApp GsApp;

## Property Details

### The `“description”` property

      “description”              gchar *

Flags: Read / Write / Construct

Default value: NULL

### The `“id”` property

      “id”                       gchar *

Flags: Read / Write / Construct

Default value: NULL

### The `“install-date”` property

      “install-date”             guint64

Flags: Read / Write / Construct

Default value: 0

### The `“kind”` property

      “kind”                     guint

Flags: Read / Write / Construct

Allowed values: <= 17

Default value: 0

### The `“name”` property

      “name”                     gchar *

Flags: Read / Write / Construct

Default value: NULL

### The `“progress”` property

      “progress”                 guint

Flags: Read / Write / Construct

Allowed values: <= 100

Default value: 0

### The `“quirk”` property

      “quirk”                    guint64

Flags: Read / Write / Construct

Default value: 0

### The `“rating”` property

      “rating”                   gint

Flags: Read / Write / Construct

Allowed values: [-1,100]

Default value: -1

### The `“state”` property

      “state”                    guint

Flags: Read / Write / Construct

Allowed values: <= 12

Default value: 0

### The `“summary”` property

      “summary”                  gchar *

Flags: Read / Write / Construct

Default value: NULL

### The `“version”` property

      “version”                  gchar *

Flags: Read / Write / Construct

Default value: NULL