Top | ![]() |
![]() |
![]() |
![]() |
Plugins are modules that are loaded at runtime to provide information about requests and to service user actions like installing, removing and updating. This allows different distributions to pick and choose how the application installer gathers data.
Plugins also have a priority system where the largest number gets run first. That means if one plugin requires some property or metadata set by another plugin then it **must** depend on the other plugin to be run in the correct order.
As a general rule, try to make plugins as small and self-contained as possible and remember to cache as much data as possible for speed. Memory is cheap, time less so.
const gchar *
gs_plugin_get_name (GsPlugin *plugin
);
Gets the plugin name.
Since: 3.22
const gchar *
gs_plugin_get_appstream_id (GsPlugin *plugin
);
Gets the plugin AppStream ID.
Since: 3.24
void gs_plugin_set_appstream_id (GsPlugin *plugin
,const gchar *appstream_id
);
Sets the plugin AppStream ID.
Since: 3.24
gboolean
gs_plugin_get_enabled (GsPlugin *plugin
);
Gets if the plugin is enabled.
Since: 3.22
void gs_plugin_set_enabled (GsPlugin *plugin
,gboolean enabled
);
Enables or disables a plugin. This is normally only called from the init function for a GsPlugin instance.
Since: 3.22
gboolean gs_plugin_has_flags (GsPlugin *plugin
,GsPluginFlags flags
);
Finds out if a plugin has a specific flag set.
Since: 3.22
void gs_plugin_add_flags (GsPlugin *plugin
,GsPluginFlags flags
);
Adds specific flags to the plugin.
Since: 3.22
void gs_plugin_remove_flags (GsPlugin *plugin
,GsPluginFlags flags
);
Removes specific flags from the plugin.
Since: 3.22
guint
gs_plugin_get_scale (GsPlugin *plugin
);
Gets the window scale factor.
Since: 3.22
const gchar *
gs_plugin_get_language (GsPlugin *plugin
);
Gets the user language from the locale. This is the first component of the locale.
Typically you should use the full locale rather than the language, as the same language can be used quite differently in different territories.
Since: 3.22
void gs_plugin_add_rule (GsPlugin *plugin
,GsPluginRule rule
,const gchar *name
);
If the plugin name is found, the rule will be used to sort the plugin list,
for example the plugin specified by name
will be ordered after this plugin
when GS_PLUGIN_RULE_RUN_AFTER
is used.
NOTE: The depsolver is iterative and may not solve overly-complicated rules; If depsolving fails then gnome-software will not start.
plugin |
a GsPlugin |
|
rule |
a GsPluginRule, e.g. |
|
name |
a plugin name, e.g. "appstream" |
Since: 3.22
gboolean gs_plugin_download_file (GsPlugin *plugin
,GsApp *app
,const gchar *uri
,const gchar *filename
,GCancellable *cancellable
,GError **error
);
Downloads data and saves it to a file.
Since: 3.22
gchar * gs_plugin_download_rewrite_resource (GsPlugin *plugin
,GsApp *app
,const gchar *resource
,GCancellable *cancellable
,GError **error
);
Downloads remote assets and rewrites a CSS resource to use cached local URIs.
Since: 3.26
gboolean gs_plugin_check_distro_id (GsPlugin *plugin
,const gchar *distro_id
);
Checks if the distro is compatible.
Since: 3.22
GsApp * gs_plugin_cache_lookup (GsPlugin *plugin
,const gchar *key
);
Looks up an application object from the per-plugin cache
Since: 3.22
void gs_plugin_cache_lookup_by_state (GsPlugin *plugin
,GsAppList *list
,GsAppState state
);
Adds each cached GsApp with state state
into the list
.
When the state is GS_APP_STATE_UNKNOWN
, then adds all
cached applications.
Since: 40
void gs_plugin_cache_add (GsPlugin *plugin
,const gchar *key
,GsApp *app
);
Adds an application to the per-plugin cache. This is optional, and the plugin can use the cache however it likes.
Since: 3.22
void gs_plugin_cache_remove (GsPlugin *plugin
,const gchar *key
);
Removes an application from the per-plugin cache.
Since: 3.22
void
gs_plugin_cache_invalidate (GsPlugin *plugin
);
Invalidate the per-plugin cache by marking all entries as invalid. This is optional, and the plugin can evict the cache whenever it likes. Using this function may mean the front-end and the plugin may be operating on a different GsApp with the same cache ID.
Most plugins do not need to call this function; if a suitable cache key is being used the old cache item can remain.
Since: 3.22
void gs_plugin_status_update (GsPlugin *plugin
,GsApp *app
,GsPluginStatus status
);
Update the state of the plugin so any UI can be updated.
Since: 3.22
gboolean gs_plugin_app_launch (GsPlugin *plugin
,GsApp *app
,GError **error
);
Launches the application using GAppInfo.
Since: 3.22
gboolean (*GsPluginPickDesktopFileCallback) (GsPlugin *plugin
,GsApp *app
,const gchar *filename
,GKeyFile *key_file
);
A callback used by gs_plugin_app_launch_filtered()
to filter which
of the candidate .desktop files should be used to launch the app
.
Since: 43
gboolean gs_plugin_app_launch_filtered (GsPlugin *plugin
,GsApp *app
,GsPluginPickDesktopFileCallback cb
,gpointer user_data
,GError **error
);
Launches application app
, using the .desktop file picked by the cb
.
This can help in case multiple versions of the app
are installed
in the system (like a Flatpak and RPM versions).
Since: 43
void
gs_plugin_updates_changed (GsPlugin *plugin
);
Emit a signal that tells the plugin loader that the list of updates may have changed.
Since: 3.22
void
gs_plugin_reload (GsPlugin *plugin
);
Plugins that call this function should expect that all panels will reload after a small delay, causing mush flashing, wailing and gnashing of teeth.
Plugins should not call this unless absolutely required.
Since: 3.22
const gchar *
gs_plugin_status_to_string (GsPluginStatus status
);
Converts the GsPluginStatus enum to a string.
Since: 3.22
void gs_plugin_report_event (GsPlugin *plugin
,GsPluginEvent *event
);
Report a non-fatal event to the UI. Plugins should not assume that a specific event is actually shown to the user as it may be ignored automatically.
Since: 3.24
void gs_plugin_set_allow_updates (GsPlugin *plugin
,gboolean allow_updates
);
This allows plugins to inhibit the showing of the updates panel. This will typically be used when the required permissions are not possible to obtain, or when a LiveUSB image is low on space.
By default, the updates panel is shown so plugins do not need to call this
function unless they called gs_plugin_set_allow_updates()
with FALSE
.
Since: 3.24
gboolean
gs_plugin_get_network_available (GsPlugin *plugin
);
Gets whether a network connectivity is available.
Since: 3.28
void gs_plugin_basic_auth_start (GsPlugin *plugin
,const gchar *remote
,const gchar *realm
,GCallback callback
,gpointer user_data
);
Emit the basic-auth-start signal in the main thread.
plugin |
a GsPlugin |
|
remote |
a string |
|
realm |
a string |
|
callback |
callback to invoke to submit the user/password |
|
user_data |
callback data to pass to the callback |
Since: 3.38
void gs_plugin_repository_changed (GsPlugin *plugin
,GsApp *repository
);
Emit the "repository-changed" signal in the main thread.
Since: 40
void gs_plugin_update_cache_state_for_repository (GsPlugin *plugin
,GsApp *repository
);
Update state of the all cached GsApp instances related
to the repository
.
Since: 40
gboolean gs_plugin_ask_untrusted (GsPlugin *plugin
,const gchar *title
,const gchar *msg
,const gchar *details
,const gchar *accept_label
);
Asks the user whether he/she accepts an untrusted package install/download/update,
as described by title
and msg
, eventually with the details
.
Note: This is a blocking call and can be called only from the main/GUI thread.
Since: 42
GDBusConnection *
gs_plugin_get_session_bus_connection (GsPlugin *self
);
Get the D-Bus session bus connection in use by the plugin.
Since: 43
GDBusConnection *
gs_plugin_get_system_bus_connection (GsPlugin *self
);
Get the D-Bus system bus connection in use by the plugin.
Since: 43
struct GsPluginClass { GObjectClass parent_class; void (*updates_changed) (GsPlugin *plugin); void (*status_changed) (GsPlugin *plugin, GsApp *app, guint status); void (*reload) (GsPlugin *plugin); void (*report_event) (GsPlugin *plugin, GsPluginEvent *event); void (*allow_updates) (GsPlugin *plugin, gboolean allow_updates); void (*basic_auth_start) (GsPlugin *plugin, const gchar *remote, const gchar *realm, GCallback callback, gpointer user_data); void (*repository_changed) (GsPlugin *plugin, GsApp *repository); gboolean (*ask_untrusted) (GsPlugin *plugin, const gchar *title, const gchar *msg, const gchar *details, const gchar *accept_label); void (*setup_async) (GsPlugin *plugin, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (*setup_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); void (*shutdown_async) (GsPlugin *plugin, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (*shutdown_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); void (*refine_async) (GsPlugin *plugin, GsAppList *list, GsPluginRefineFlags flags, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (*refine_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); void (*list_apps_async) (GsPlugin *plugin, GsAppQuery *query, GsPluginListAppsFlags flags, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); GsAppList * (*list_apps_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); void (*refresh_metadata_async) (GsPlugin *plugin, guint64 cache_age_secs, GsPluginRefreshMetadataFlags flags, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (*refresh_metadata_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); void (*list_distro_upgrades_async) (GsPlugin *plugin, GsPluginListDistroUpgradesFlags flags, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); GsAppList * (*list_distro_upgrades_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); void (*install_repository_async) (GsPlugin *plugin, GsApp *repository, GsPluginManageRepositoryFlags flags, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (*install_repository_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); void (*remove_repository_async) (GsPlugin *plugin, GsApp *repository, GsPluginManageRepositoryFlags flags, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (*remove_repository_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); void (*enable_repository_async) (GsPlugin *plugin, GsApp *repository, GsPluginManageRepositoryFlags flags, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (*enable_repository_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); void (*disable_repository_async) (GsPlugin *plugin, GsApp *repository, GsPluginManageRepositoryFlags flags, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (*disable_repository_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); void (*refine_categories_async) (GsPlugin *plugin, GPtrArray *list, GsPluginRefineCategoriesFlags flags, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (*refine_categories_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); void (*update_apps_async) (GsPlugin *plugin, GsAppList *apps, GsPluginUpdateAppsFlags flags, GsPluginProgressCallback progress_callback, gpointer progress_user_data, GsPluginAppNeedsUserActionCallback app_needs_user_action_callback, gpointer app_needs_user_action_data, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (*update_apps_finish) (GsPlugin *plugin, GAsyncResult *result, GError **error); gpointer padding[23]; };
The class structure for a GsPlugin. Virtual methods here should be implemented by plugin implementations derived from GsPlugin to provide their plugin-specific behaviour.
Setup method for the plugin. This is called after
the GsPlugin object is constructed, before it’s used for anything. It
should do any long-running setup operations which the plugin needs, such as
file or network access. It may be |
[nullable] | |
Finish method for |
[nullable] | |
Shutdown method for the plugin. This is called
by the GsPluginLoader when the process is terminating or the
GsPluginLoader is being destroyed. It should be used to cancel or stop any
ongoing operations or threads in the plugin. It may be |
[nullable] | |
Finish method for |
[nullable] | |
Refining looks up and adds data to GsApps. The apps to refine are provided in a list, and the flags specify what data to look up and add. Refining certain kinds of data can be very expensive (for example, requiring network requests), which is why it’s not all loaded by default. By refining multiple apps at once, data requests can be batched by the plugin where possible. (Since: 43). |
[nullable] | |
Finish method for |
[nullable] | |
List apps matching a given query. (Since: 43). |
[nullable] | |
Finish method for |
[nullable] | |
Refresh plugin metadata. (Since: 43). |
[nullable] | |
Finish method for
|
[nullable] | |
List available distro upgrades. (Since: 43). |
[nullable] | |
Finish method for
|
[nullable] | |
Install repository. (Since: 43). |
[nullable] | |
Finish method for
|
[nullable] | |
Remove repository. (Since: 43). |
[nullable] | |
Finish method for
|
[nullable] | |
Enable repository. (Since: 43). |
[nullable] | |
Finish method for
|
[nullable] | |
Disable repository. (Since: 43). |
[nullable] | |
Finish method for
|
[nullable] | |
Refining looks up and adds data to GsCategorys. The categories to refine are provided in a list, and the flags specify what data to look up and add. Refining certain kinds of data can be very expensive (for example, requiring network requests), which is why it’s not all loaded by default. By refining multiple categories at once, data requests can be batched by the plugin where possible. (Since: 43). |
[nullable] | |
Finish method for
|
[nullable] | |
Update apps or the OS, or download updates ready for installation. (Since: 44). |
[nullable] | |
Finish method for |
[nullable] | |
gpointer |