GsPlugin Exports: GNOME Software Reference Manual

## GsPlugin Exports GsPlugin Exports — Vfuncs that plugins can implement |

## Stability Level

Unstable, unless otherwise indicated

## Functions

GType | gs_plugin_query_type ()
void | gs_plugin_adopt_app ()
gboolean | gs_plugin_add_updates ()
gboolean | gs_plugin_add_sources ()
gboolean | gs_plugin_add_updates_historical ()
gboolean | gs_plugin_launch ()
gboolean | gs_plugin_update_cancel ()
gboolean | gs_plugin_app_install ()
gboolean | gs_plugin_app_remove ()
gboolean | gs_plugin_update_app ()
gboolean | gs_plugin_download_app ()
gboolean | gs_plugin_download ()
gboolean | gs_plugin_app_upgrade_download ()
gboolean | gs_plugin_app_upgrade_trigger ()
gboolean | gs_plugin_file_to_app ()
gboolean | gs_plugin_url_to_app ()
gboolean | gs_plugin_update ()
gboolean | gs_plugin_add_langpacks ()

## Includes

    #include <gnome-software.h>

## Description

## Functions

### gs_plugin_query_type ()

    GType
    gs_plugin_query_type (void);

Returns the GType for a subclass of GsPlugin provided by this plugin module. It should not do any other computation.

The init function for that type should initialize the plugin. If the plugin should not be run then `gs_plugin_set_enabled()` should be called from the init function.

NOTE: Do not do any failable actions in the plugin class’ init function; use GsPluginClass.setup_async instead.

Since: 42

### gs_plugin_adopt_app ()

    void
    gs_plugin_adopt_app (GsPlugin *plugin,
                         GsApp *app);

Called when an GsApp has not been claimed (i.e. a management plugin has not been set).

A claimed application means other plugins will not try to perform actions such as install, remove or update. Most applications are claimed when they are created.

If a plugin can adopt this application then it should call `gs_app_set_management_plugin()` on `app` .

#### Parameters

plugin | a GsPlugin |
app | a GsApp |

### gs_plugin_add_updates ()

    gboolean
    gs_plugin_add_updates (GsPlugin *plugin,
                           GsAppList *list,
                           GCancellable *cancellable,
                           GError **error);

Get the list of updates.

NOTE: Actually downloading the updates can be done in `gs_plugin_download_app()` or in `gs_plugin_download()`.

Plugins are expected to add new apps using `gs_app_list_add()`.

#### Parameters

plugin | a GsPlugin |
list | a GsAppList |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_add_sources ()

    gboolean
    gs_plugin_add_sources (GsPlugin *plugin,
                           GsAppList *list,
                           GCancellable *cancellable,
                           GError **error);

Get the list of sources, for example the repos listed in /etc/yum.repos.d or the remotes configured in flatpak.

Plugins are expected to add new apps using `gs_app_list_add()` of type `AS_COMPONENT_KIND_REPOSITORY`.

#### Parameters

plugin | a GsPlugin |
list | a GsAppList |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_add_updates_historical ()

    gboolean
    gs_plugin_add_updates_historical (GsPlugin *plugin,
                                      GsAppList *list,
                                      GCancellable *cancellable,
                                      GError **error);

Get the list of historical updates, i.e. the updates that have just been installed.

Plugins are expected to add new apps using `gs_app_list_add()`.

#### Parameters

plugin | a GsPlugin |
list | a GsAppList |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_launch ()

    gboolean
    gs_plugin_launch (GsPlugin *plugin,
                      GsApp *app,
                      GCancellable *cancellable,
                      GError **error);

Launch the specified application using a plugin-specific method. This is normally setting some environment or launching a specific binary.

Plugins can simply use `gs_plugin_app_launch()` if no plugin-specific functionality is required.

#### Parameters

plugin | a GsPlugin |
app | a GsApp |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_update_cancel ()

    gboolean
    gs_plugin_update_cancel (GsPlugin *plugin,
                             GsApp *app,
                             GCancellable *cancellable,
                             GError **error);

Cancels the offline update of `app` .

#### Parameters

plugin | a GsPlugin |
app | a GsApp |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_app_install ()

    gboolean
    gs_plugin_app_install (GsPlugin *plugin,
                           GsApp *app,
                           GCancellable *cancellable,
                           GError **error);

Install the application.

Plugins are expected to send progress notifications to the UI using `gs_app_set_progress()` using the passed in `app` .

All functions can block, but should sent progress notifications, e.g. using `gs_app_set_progress()` if they will take more than tens of milliseconds to complete.

On failure the error message returned will usually only be shown on the console, but they can also be retrieved using `gs_plugin_loader_get_events()`.

NOTE: Once the action is complete, the plugin must set the new state of `app` to `GS_APP_STATE_INSTALLED`.

#### Parameters

plugin | a GsPlugin |
app | a GsApp |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_app_remove ()

    gboolean
    gs_plugin_app_remove (GsPlugin *plugin,
                          GsApp *app,
                          GCancellable *cancellable,
                          GError **error);

Remove the application.

Plugins are expected to send progress notifications to the UI using `gs_app_set_progress()` using the passed in `app` .

All functions can block, but should sent progress notifications, e.g. using `gs_app_set_progress()` if they will take more than tens of milliseconds to complete.

On failure the error message returned will usually only be shown on the console, but they can also be retrieved using `gs_plugin_loader_get_events()`.

NOTE: Once the action is complete, the plugin must set the new state of `app` to `GS_APP_STATE_AVAILABLE` or `GS_APP_STATE_UNKNOWN` if not known.

#### Parameters

plugin | a GsPlugin |
app | a GsApp |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_update_app ()

    gboolean
    gs_plugin_update_app (GsPlugin *plugin,
                          GsApp *app,
                          GCancellable *cancellable,
                          GError **error);

Update the application live.

Plugins are expected to send progress notifications to the UI using `gs_app_set_progress()` using the passed in `app` .

All functions can block, but should sent progress notifications, e.g. using `gs_app_set_progress()` if they will take more than tens of milliseconds to complete.

On failure the error message returned will usually only be shown on the console, but they can also be retrieved using `gs_plugin_loader_get_events()`.

NOTE: Once the action is complete, the plugin must set the new state of `app` to `GS_APP_STATE_INSTALLED` or `GS_APP_STATE_UNKNOWN` if not known.

If `GS_APP_QUIRK_IS_PROXY` is set on the application then the actual GsApp set in `app` will be the related application of the parent. Plugins do not need to manually iterate on the related list of applications.

#### Parameters

plugin | a GsPlugin |
app | a GsApp |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_download_app ()

    gboolean
    gs_plugin_download_app (GsPlugin *plugin,
                            GsApp *app,
                            GCancellable *cancellable,
                            GError **error);

Downloads the application and any dependencies ready to be installed or updated.

Plugins are expected to schedule downloads using the system download scheduler if appropriate (if the download is not guaranteed to be under a few hundred kilobytes, for example), so that the user’s metered data preferences are honoured.

Plugins are expected to send progress notifications to the UI using `gs_app_set_progress()` using the passed in `app` .

All functions can block, but should sent progress notifications, e.g. using `gs_app_set_progress()` if they will take more than tens of milliseconds to complete.

If the `app` is already downloaded, do not return an error and return `TRUE`.

On failure the error message returned will usually only be shown on the console, but they can also be retrieved using `gs_plugin_loader_get_events()`.

#### Parameters

plugin | a GsPlugin |
app | a GsApp |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_download ()

    gboolean
    gs_plugin_download (GsPlugin *plugin,
                        GsAppList *apps,
                        GCancellable *cancellable,
                        GError **error);

Downloads a list of applications ready to be installed or updated.

Plugins are expected to schedule downloads using the system download scheduler if appropriate (if the download is not guaranteed to be under a few hundred kilobytes, for example), so that the user’s metered data preferences are honoured.

#### Parameters

plugin | a GsPlugin |
apps | a GsAppList |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_app_upgrade_download ()

    gboolean
    gs_plugin_app_upgrade_download (GsPlugin *plugin,
                                    GsApp *app,
                                    GCancellable *cancellable,
                                    GError **error);

Starts downloading a distribution upgrade in the background.

All functions can block, but should sent progress notifications, e.g. using `gs_app_set_progress()` if they will take more than tens of milliseconds to complete.

#### Parameters

plugin | a GsPlugin |
app | a GsApp, with kind `AS_COMPONENT_KIND_OPERATING_SYSTEM` |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_app_upgrade_trigger ()

    gboolean
    gs_plugin_app_upgrade_trigger (GsPlugin *plugin,
                                   GsApp *app,
                                   GCancellable *cancellable,
                                   GError **error);

Triggers the distribution upgrade to be installed on next boot.

#### Parameters

plugin | a GsPlugin |
app | a GsApp, with kind `AS_COMPONENT_KIND_OPERATING_SYSTEM` |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_file_to_app ()

    gboolean
    gs_plugin_file_to_app (GsPlugin *plugin,
                           GsAppList *list,
                           GFile *file,
                           GCancellable *cancellable,
                           GError **error);

Converts a local file to a GsApp. It's expected that only one plugin will match the mimetype of `file` and that a single GsApp will be in the returned list. If no plugins can handle the file, the list will be empty.

For example, the PackageKit plugin can turn a .rpm file into a application of kind `AS_COMPONENT_KIND_UNKNOWN` but that in some cases it will be further refined into a `AS_COMPONENT_KIND_DESKTOP_APP` (with all the extra metadata) by the appstream plugin.

Plugins are expected to add new apps using `gs_app_list_add()`.

#### Parameters

plugin | a GsPlugin |
list | a GsAppList |
file | a GFile |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_url_to_app ()

    gboolean
    gs_plugin_url_to_app (GsPlugin *plugin,
                          GsAppList *list,
                          const gchar *url,
                          GCancellable *cancellable,
                          GError **error);

Converts a URL to a GsApp. It's expected that only one plugin will match the scheme of `url` and that a single GsApp will be in the returned list. If no plugins can handle the file, the list will be empty.

For example, the apt plugin can turn apt://gimp into a application.

Plugins are expected to add new apps using `gs_app_list_add()`.

#### Parameters

plugin | a GsPlugin |
list | a GsAppList |
url | a URL, e.g. "apt://gimp" |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_update ()

    gboolean
    gs_plugin_update (GsPlugin *plugin,
                      GsAppList *apps,
                      GCancellable *cancellable,
                      GError **error);

Updates a list of applications, typically scheduling them for offline update.

#### Parameters

plugin | a GsPlugin |
apps | a GsAppList |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant

### gs_plugin_add_langpacks ()

    gboolean
    gs_plugin_add_langpacks (GsPlugin *plugin,
                             GsAppList *list,
                             const gchar *locale,
                             GCancellable *cancellable,
                             GError **error);

Returns a list of language packs, as per input language code or locale.

#### Parameters

plugin | a GsPlugin |
list | a GsAppList |
locale | a LANGUAGE_CODE or LOCALE, e.g. "ja" or "ja_JP" |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success or if not relevant