[gnome-software] trivial: Add some more markup for the plugin vfuncs
- From: Richard Hughes <rhughes src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-software] trivial: Add some more markup for the plugin vfuncs
- Date: Thu, 19 May 2016 16:00:16 +0000 (UTC)
commit d5d69723530dea6250b0391011505d732970286d
Author: Richard Hughes <richard hughsie com>
Date: Thu May 19 15:48:00 2016 +0100
trivial: Add some more markup for the plugin vfuncs
src/gs-app-list.c | 3 +
src/gs-app.c | 38 +++-
src/gs-plugin.c | 7 +-
src/gs-plugin.h | 648 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
src/gs-review.c | 3 +
src/gs-utils.c | 3 +
6 files changed, 695 insertions(+), 7 deletions(-)
---
diff --git a/src/gs-app-list.c b/src/gs-app-list.c
index 69fc42b..4fcdc23 100644
--- a/src/gs-app-list.c
+++ b/src/gs-app-list.c
@@ -21,6 +21,9 @@
/**
* SECTION:gs-app-list
+ * @title: GsAppList
+ * @include: gnome-software.h
+ * @stability: Unstable
* @short_description: An application list
*
* These functions provide a refcounted list of #GsApp objects.
diff --git a/src/gs-app.c b/src/gs-app.c
index a8a97e5..a089207 100644
--- a/src/gs-app.c
+++ b/src/gs-app.c
@@ -22,20 +22,23 @@
/**
* SECTION:gs-app
+ * @title: GsApp
+ * @include: gnome-software.h
+ * @stability: Unstable
* @short_description: An application that is either installed or that can be installed
*
* 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
+ * 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.
+ * 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().
@@ -158,6 +161,13 @@ gs_app_kv_printf (GString *str, const gchar *key, const gchar *fmt, ...)
/**
* gs_app_to_string:
+ * @app: a #GsApp
+ *
+ * Converts the application to a string.
+ * This is not designed to serialize the object but to produce a string suitable
+ * for debugging.
+ *
+ * Returns: A multi-line string
**/
gchar *
gs_app_to_string (GsApp *app)
@@ -397,6 +407,11 @@ gs_app_queue_notify (GsApp *app, const gchar *property_name)
/**
* gs_app_get_id:
+ * @app: a #GsApp
+ *
+ * Gets the application ID.
+ *
+ * Returns: The whole ID, e.g. "gimp.desktop" or "flatpak:org.gnome.Gimp.desktop"
**/
const gchar *
gs_app_get_id (GsApp *app)
@@ -407,6 +422,11 @@ gs_app_get_id (GsApp *app)
/**
* gs_app_get_id_no_prefix:
+ * @app: a #GsApp
+ *
+ * Gets the application ID without any prefix set.
+ *
+ * Returns: The whole ID, e.g. gimp.desktop" or "org.gnome.Gimp.desktop"
**/
const gchar *
gs_app_get_id_no_prefix (GsApp *app)
@@ -423,6 +443,10 @@ gs_app_get_id_no_prefix (GsApp *app)
/**
* gs_app_set_id:
+ * @app: a #GsApp
+ * @id: a application ID, e.g. "gimp.desktop"
+ *
+ * Sets the application ID.
*/
void
gs_app_set_id (GsApp *app, const gchar *id)
@@ -644,12 +668,14 @@ gs_app_set_progress (GsApp *app, guint percentage)
* Plugins are reponsible for changing the state to one of the other
* states before the GsApp is passed to the frontend.
*
+ * |[
* UPDATABLE --> INSTALLING --> INSTALLED
* UPDATABLE --> REMOVING --> AVAILABLE
* INSTALLED --> REMOVING --> AVAILABLE
* AVAILABLE --> INSTALLING --> INSTALLED
* AVAILABLE <--> QUEUED --> INSTALLING --> INSTALLED
* UNKNOWN --> UNAVAILABLE
+ * ]|
**/
void
gs_app_set_state (GsApp *app, AsAppState state)
@@ -684,9 +710,11 @@ gs_app_get_kind (GsApp *app)
* The following state diagram explains the typical states.
* All applications start with kind %AS_APP_KIND_UNKNOWN.
*
+ * |[
* PACKAGE --> NORMAL
* PACKAGE --> SYSTEM
* NORMAL --> SYSTEM
+ * ]|
**/
void
gs_app_set_kind (GsApp *app, AsAppKind kind)
diff --git a/src/gs-plugin.c b/src/gs-plugin.c
index b73720e..d5027f6 100644
--- a/src/gs-plugin.c
+++ b/src/gs-plugin.c
@@ -19,7 +19,12 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
-/* Introduction:
+/**
+ * SECTION:gs-plugin
+ * @title: GsPlugin
+ * @include: gnome-software.h
+ * @stability: Unstable
+ * @short_description: Runtime-loaded modules providing functionality
*
* Plugins are modules that are loaded at runtime to provide information
* about requests and to service user actions like installing, removing
diff --git a/src/gs-plugin.h b/src/gs-plugin.h
index 1015567..7b5766e 100644
--- a/src/gs-plugin.h
+++ b/src/gs-plugin.h
@@ -243,167 +243,813 @@ gboolean gs_plugin_app_launch (GsPlugin *plugin,
void gs_plugin_updates_changed (GsPlugin *plugin);
const gchar *gs_plugin_status_to_string (GsPluginStatus status);
-/* vfuncs */
+/**
+ * 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_order_after:
+ * @plugin: a #GsPlugin
+ *
+ * Any plugin names returned with this method will be ordered after this plugin.
+ *
+ * NOTE: If depsolving fails then gnome-software will not start.
+ *
+ * Returns: (element-type utf8): A list of deps
+ **/
const gchar **gs_plugin_order_after (GsPlugin *plugin);
+
+/**
+ * gs_plugin_order_before:
+ * @plugin: a #GsPlugin
+ *
+ * Any plugin names returned with this method will be ordered before this plugin.
+ *
+ * NOTE: If depsolving fails then gnome-software will not start.
+ *
+ * Returns: (element-type utf8): A list of deps
+ **/
const gchar **gs_plugin_order_before (GsPlugin *plugin);
+
+/**
+ * gs_plugin_get_conflicts:
+ * @plugin: a #GsPlugin
+ *
+ * Any plugin names returned with this method will be disabled if this plugin
+ * is enabled.
+ *
+ * NOTE: The depsolver is iterative and may not solve overly-complicated rules.
+ *
+ * Returns: (element-type utf8): A list of deps
+ **/
const gchar **gs_plugin_get_conflicts (GsPlugin *plugin);
+
+/**
+ * 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_plugin_progress_update() 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 pre-downloaded, pre-checked updates, with the write lock
+ * held.
+ *
+ * NOTE: Actually downloading the updates is normally done in
+ * gs_plugin_refresh() when called with %GS_PLUGIN_REFRESH_FLAGS_PAYLOAD.
+ *
+ * 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_popular:
+ * @plugin: a #GsPlugin
+ * @list: a #GsAppList
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Get popular 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_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.
+ *
+ * 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.
+ * This function is only really required when "batching up" requests, and most
+ * plugins are better using the per-app gs_plugin_refine_app() function.
+ *
+ * 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_app:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @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 @app.
+ *
+ * The general idea for @flags is that this indicates what the UI needs at the
+ * moment. This doesn't mean you can't add more information if you have it,
+ * for example, if we requested %GS_PLUGIN_REFINE_FLAGS_REQUIRE_LICENSE and had
+ * to do some IO to get a blob of data, we can use gs_app_set_license() *and*
+ * gs_app_set_origin() even though only the first thing was specified.
+ *
+ * If the plugin can't handle applications of the specific kind, or if the
+ * plugin knows not of the #GsApp ID then it should just ignore the request and
+ * return FALSE.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
gboolean gs_plugin_refine_app (GsPlugin *plugin,
GsApp *app,
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_plugin_progress_update() using the passed in @app.
+ *
+ * All functions can block, but should sent progress notifications, e.g. using
+ * gs_plugin_progress_update() if they will take more than tens of milliseconds
+ * to complete.
+ *
+ * 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_plugin_progress_update() using the passed in @app.
+ *
+ * All functions can block, but should sent progress notifications, e.g. using
+ * gs_plugin_progress_update() if they will take more than tens of milliseconds
+ * to complete.
+ *
+ * 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_plugin_progress_update() using the passed in @app.
+ *
+ * All functions can block, but should sent progress notifications, e.g. using
+ * gs_plugin_progress_update() if they will take more than tens of milliseconds
+ * to complete.
+ *
+ * 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.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
gboolean gs_plugin_update_app (GsPlugin *plugin,
GsApp *app,
GCancellable *cancellable,
GError **error);
+
+/**
+ * gs_plugin_add_source:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp, with kind %AS_ID_KIND_SOURCE
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Adds a specific source to the system.
+ *
+ * Adding a source means that applications can be installed from that source,
+ * along with any new search results.
+ * A new entry is also shown in the "Sources" dialog.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
gboolean gs_plugin_add_source (GsPlugin *plugin,
GsApp *app,
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_plugin_progress_update() 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 #GsReview
+ * @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,
GsReview *review,
GCancellable *cancellable,
GError **error);
+
+/**
+ * gs_plugin_review_upvote:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @review: a #GsReview
+ * @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,
GsReview *review,
GCancellable *cancellable,
GError **error);
+
+/**
+ * gs_plugin_review_downvote:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @review: a #GsReview
+ * @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,
GsReview *review,
GCancellable *cancellable,
GError **error);
+
+/**
+ * gs_plugin_review_report:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @review: a #GsReview
+ * @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,
GsReview *review,
GCancellable *cancellable,
GError **error);
+
+/**
+ * gs_plugin_review_remove:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @review: a #GsReview
+ * @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 %GS_REVIEW_FLAG_SELF.
+ *
+ * Returns: %TRUE for success or if not relevant
+ **/
gboolean gs_plugin_review_remove (GsPlugin *plugin,
GsApp *app,
GsReview *review,
GCancellable *cancellable,
GError **error);
+
+/**
+ * gs_plugin_review_dismiss:
+ * @plugin: a #GsPlugin
+ * @app: a #GsApp
+ * @review: a #GsReview
+ * @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,
GsReview *review,
GCancellable *cancellable,
GError **error);
+
+/**
+ * gs_plugin_refresh:
+ * @plugin: a #GsPlugin
+ * @cache_age: the acceptable cache age in seconds, or MAXUINT for "any"
+ * @flags: a bitfield of #GsPluginRefreshFlags, e.g. %GS_PLUGIN_REFRESH_FLAGS_METADATA
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Refreshes the state of all the plugins.
+ *
+ * The %GS_PLUGIN_REFRESH_FLAGS_METADATA flag can be used to make sure
+ * there's enough metadata to start the application, for example lists of
+ * available applications.
+ *
+ * The %GS_PLUGIN_REFRESH_FLAGS_PAYLOAD flag should only be used when
+ * the session is idle and bandwidth is unmetered as the amount of data
+ * and IO may be large.
+ * This is used to pre-download package updates and firmware.
+ *
+ * All functions can block, but should sent progress notifications, e.g. using
+ * gs_plugin_progress_update() 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,
GsPluginRefreshFlags flags,
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 futher 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_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,
diff --git a/src/gs-review.c b/src/gs-review.c
index 3e1a438..7ff8638 100644
--- a/src/gs-review.c
+++ b/src/gs-review.c
@@ -21,6 +21,9 @@
/**
* SECTION:gs-review
+ * @title: GsReview
+ * @include: gnome-software.h
+ * @stability: Unstable
* @short_description: An application user review
*
* This object represents a user-submitted application review.
diff --git a/src/gs-utils.c b/src/gs-utils.c
index 28949cf..12d03ea 100644
--- a/src/gs-utils.c
+++ b/src/gs-utils.c
@@ -21,6 +21,9 @@
/**
* SECTION:gs-utils
+ * @title: GsUtils
+ * @include: gnome-software.h
+ * @stability: Unstable
* @short_description: Utilities that plugins can use
*
* These functions provide useful functionality that makes it easy to
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
