Adding upstream version 3.38.1.upstream/3.38.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 942 insertions, 0 deletions

diff --git a/lib/gs-plugin-vfuncs.h b/lib/gs-plugin-vfuncs.h
new file mode 100644
index 0000000..05772f2
--- /dev/null
+++ b/lib/gs-plugin-vfuncs.h
@@ -0,0 +1,942 @@
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*-
+ * vi:set noexpandtab tabstop=8 shiftwidth=8:
+ *
+ * Copyright (C) 2012-2017 Richard Hughes <richard@hughsie.com>
+ *
+ * SPDX-License-Identifier: GPL-2.0+
+ */
+
+#pragma once
+
+/**
+ * SECTION:gs-plugin-vfuncs
+ * @title: GsPlugin Exports
+ * @include: gnome-software.h
+ * @stability: Unstable
+ * @short_description: Vfuncs that plugins can implement
+ */
+
+#include <appstream-glib.h>
+#include <glib-object.h>
+#include <gmodule.h>
+#include <gio/gio.h>
+#include <libsoup/soup.h>
+
+#include "gs-app.h"
+#include "gs-app-list.h"
+#include "gs-category.h"
+
+G_BEGIN_DECLS
+
+/**
+ * gs_plugin_initialize:
+ * @plugin: a #GsPlugin
+ *
+ * Checks if the plugin should run, and if initializes it. If the plugin should
+ * not be run then gs_plugin_set_enabled() should be called.
+ * This is also the place to call gs_plugin_alloc_data() if private data is
+ * required for the plugin.
+ *
+ * NOTE: Do not do any failable actions in this function; use gs_plugin_setup()
+ * instead.
+ **/
+void		 gs_plugin_initialize			(GsPlugin	*plugin);
+
+/**
+ * gs_plugin_destroy:
+ * @plugin: a #GsPlugin
+ *
+ * Called when the plugin should destroy any private data.
+ **/
+void		 gs_plugin_destroy			(GsPlugin	*plugin);
+
+/**
+ * gs_plugin_adopt_app:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ *
+ * 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.
+ **/
+void		 gs_plugin_adopt_app			(GsPlugin	*plugin,
+							 GsApp		*app);
+
+/**
+ * gs_plugin_add_search:
+ * @plugin: a #GsPlugin
+ * @values: a NULL terminated list of search terms, e.g. [ "gnome", "software" ]
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Get search results for a specific query.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_search			(GsPlugin	*plugin,
+							 gchar		**values,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_search_files:
+ * @plugin: a #GsPlugin
+ * @values: a list of filenames, e.g. [ "/usr/share/help/gimp/index.html" ]
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Called when searching for an application that provides a specific filename
+ * on the filesystem.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_search_files		(GsPlugin	*plugin,
+							 gchar		**values,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_search_what_provides
+ * @plugin: a list of tags, e.g. [ "text/rtf" ]
+ * @values: a #GStrv
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Called when searching for an application that provides specific defined tags,
+ * for instance a codec string or mime-type.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_search_what_provides	(GsPlugin	*plugin,
+							 gchar		**values,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_alternates
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Called when trying to find alternates to a specific app, for instance
+ * finding a flatpak version of an existing distro packaged application.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_alternates		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_setup:
+ * @plugin: a #GsPlugin
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Called when the plugin should set up the initial state, and with the write
+ * lock held.
+ *
+ * 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.
+ *
+ * This function will also not be called if gs_plugin_initialize() self-disabled.
+ *
+ * Returns: %TRUE for success
+ **/
+gboolean	 gs_plugin_setup			(GsPlugin	*plugin,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_installed:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Get the list of installed applications.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_installed		(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_updates:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_updates			(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_distro_upgrades:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Get the list of distribution upgrades. Due to the download size, these
+ * should not be downloaded until the user has explicitly opted-in.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add() of type
+ * %AS_APP_KIND_OS_UPGRADE.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_distro_upgrades		(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_sources:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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_APP_KIND_SOURCE.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_sources			(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_updates_historical
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_updates_historical	(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_categories:
+ * @plugin: a #GsPlugin
+ * @list: (element-type GsCategory): a #GPtrArray
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Get the category tree, for instance Games->Action or Internet->Email.
+ *
+ * Plugins are expected to add new categories using g_ptr_array_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_categories		(GsPlugin	*plugin,
+							 GPtrArray	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_category_apps:
+ * @plugin: a #GsPlugin
+ * @category: a #GsCategory
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Get all the applications that match a specific category.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_category_apps		(GsPlugin	*plugin,
+							 GsCategory	*category,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_recent:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @age: a number of seconds
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Return all the applications that have had upstream releases recently.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_recent			(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 guint64	 age,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_popular:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Get popular applications that should be featured on the main page as
+ * "Editors Picks".
+ * This is expected to be a curated list of applications that are high quality
+ * and feature-complete.
+ *
+ * The returned list of popular applications are not sorted, but each #GsApp has
+ * to be valid, for instance having a known state and a valid icon.
+ * If an insufficient number of applications are added by plugins then the
+ * section on the overview shell may be hidden.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_popular			(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_featured:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Get applications that should be featured as a large full-width banner on the
+ * overview page.
+ * This is expected to be a curated list of applications that are high quality
+ * and feature-complete.
+ *
+ * The returned list of popular applications are randomized in a way so that
+ * the same application is featured for the entire calendar day.
+ *
+ * NOTE: The UI code may expect that applications have additional metadata set on
+ * results, for instance <code>GnomeSoftware::FeatureTile-css</code>.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_featured			(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_unvoted_reviews:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Gets the list of unvoted reviews. Only applications should be returned where
+ * there are reviews, and where the user has not previously moderated them.
+ * This function is supposed to be used to display a moderation panel for
+ * reviewers.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_unvoted_reviews		(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_refine:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @flags: a #GsPluginRefineFlags, e.g. %GS_PLUGIN_REFINE_FLAGS_REQUIRE_LICENSE
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Adds required information to a list of #GsApp's. It allows requests to be
+ * batched up, which allows better performance than individual calls per app.
+ *
+ * An example for when this is useful would be in the PackageKit plugin where
+ * we want to do one transaction of GetDetails with multiple source-ids rather
+ * than scheduling a large number of pending requests.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_refine			(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 GsPluginRefineFlags flags,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_refine_wildcard:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @list: a #GsAppList
+ * @flags: a #GsPluginRefineFlags, e.g. %GS_PLUGIN_REFINE_FLAGS_REQUIRE_LICENSE
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Adds applications that match the wildcard specified in @app.
+ *
+ * The general idea is that plugins create and add *new* applications rather
+ * than all trying to fight over the wildcard application.
+ * This allows the plugin loader to filter using the #GsApp priority value.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_refine_wildcard		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GsAppList	*list,
+							 GsPluginRefineFlags flags,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_launch:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_launch			(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_shortcut:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Adds a shortcut for the application in a desktop-defined location.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_shortcut			(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_remove_shortcut:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Removes a shortcut for the application in a desktop-defined location.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_remove_shortcut		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_update_cancel:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Cancels the offline update of @app.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_update_cancel		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_app_install:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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 %AS_APP_STATE_INSTALLED.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_app_install			(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_app_remove:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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 %AS_APP_STATE_AVAILABLE or %AS_APP_STATE_UNKNOWN if not known.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_app_remove			(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_app_set_rating:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Gets any ratings for the applications.
+ *
+ * Plugins are expected to call gs_app_set_rating() on @app.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_app_set_rating		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_update_app:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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 %AS_APP_STATE_INSTALLED or %AS_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.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_update_app			(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_download_app:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_download_app			(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_download:
+ * @plugin: a #GsPlugin
+ * @apps: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_download			(GsPlugin	*plugin,
+							 GsAppList	*apps,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_app_upgrade_download:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp, with kind %AS_APP_KIND_OS_UPGRADE
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_app_upgrade_download		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_app_upgrade_trigger:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp, with kind %AS_APP_KIND_OS_UPGRADE
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Triggers the distribution upgrade to be installed on next boot.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_app_upgrade_trigger		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_review_submit:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @review: a #AsReview
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Submits a new end-user application review.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_review_submit		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 AsReview	*review,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_review_upvote:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @review: a #AsReview
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Upvote a specific review to indicate the review is helpful.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_review_upvote		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 AsReview	*review,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_review_downvote:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @review: a #AsReview
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Downvote a specific review to indicate the review is unhelpful.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_review_downvote		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 AsReview	*review,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_review_report:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @review: a #AsReview
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Report a review that is not suitable in some way.
+ * It is expected that this action flags a review to be checked by a moderator
+ * and that the review won't be shown to any users until this happens.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_review_report		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 AsReview	*review,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_review_remove:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @review: a #AsReview
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Remove a review that the user wrote.
+ * NOTE: Users should only be able to remove reviews with %AS_REVIEW_FLAG_SELF.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_review_remove		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 AsReview	*review,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_review_dismiss:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @review: a #AsReview
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Dismisses a review, i.e. hide it from future moderated views.
+ * This action is useful when the moderator is unable to speak the language of
+ * the review for example.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_review_dismiss		(GsPlugin	*plugin,
+							 GsApp		*app,
+							 AsReview	*review,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_refresh:
+ * @plugin: a #GsPlugin
+ * @cache_age: the acceptable cache age in seconds, or MAXUINT for "any"
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Refreshes the state of all the plugins. Plugins should make sure
+ * there's enough metadata to start the application, for example lists of
+ * available applications.
+ *
+ * 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.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_refresh			(GsPlugin	*plugin,
+							 guint		 cache_age,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_file_to_app:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @file: a #GFile
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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_APP_KIND_UNKNOWN but that in some cases it will be further refined
+ * into a %AS_APP_KIND_DESKTOP (with all the extra metadata) by the appstream
+ * plugin.
+ *
+ * Plugins are expected to add new apps using gs_app_list_add().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_file_to_app			(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 GFile		*file,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_url_to_app:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @url: a #URL, e.g. "apt://gimp"
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * 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().
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_url_to_app			(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 const gchar	*url,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_update:
+ * @plugin: a #GsPlugin
+ * @apps: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Updates a list of applications, typically scheduling them for offline update.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_update			(GsPlugin	*plugin,
+							 GsAppList	*apps,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+/**
+ * gs_plugin_add_langpacks:
+ * @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 a list of language packs, as per input language code or locale.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
+gboolean	 gs_plugin_add_langpacks		(GsPlugin	*plugin,
+							 GsAppList	*list,
+							 const gchar    *locale,
+							 GCancellable	*cancellable,
+							 GError		**error);
+
+G_END_DECLS