GsPlugin Helpers

GsPlugin Helpers — Runtime-loaded modules providing functionality

Stability Level

Unstable, unless otherwise indicated

Functions

Types and Values

Includes

#include <gnome-software.h>

Description

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.

Functions

gs_plugin_error_quark ()

GQuark
gs_plugin_error_quark (void);

gs_plugin_get_name ()

const gchar *
gs_plugin_get_name (GsPlugin *plugin);

Gets the plugin name.

Parameters

plugin

a GsPlugin

 

Returns

a string, e.g. "fwupd"

Since: 3.22


gs_plugin_get_appstream_id ()

const gchar *
gs_plugin_get_appstream_id (GsPlugin *plugin);

Gets the plugin AppStream ID.

Parameters

plugin

a GsPlugin

 

Returns

a string, e.g. org.gnome.Software.Plugin.Epiphany

Since: 3.24


gs_plugin_set_appstream_id ()

void
gs_plugin_set_appstream_id (GsPlugin *plugin,
                            const gchar *appstream_id);

Sets the plugin AppStream ID.

Parameters

plugin

a GsPlugin

 

appstream_id

an appstream ID, e.g. org.gnome.Software.Plugin.Epiphany

 

Since: 3.24


gs_plugin_get_enabled ()

gboolean
gs_plugin_get_enabled (GsPlugin *plugin);

Gets if the plugin is enabled.

Parameters

plugin

a GsPlugin

 

Returns

TRUE if enabled

Since: 3.22


gs_plugin_set_enabled ()

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.

Parameters

plugin

a GsPlugin

 

enabled

the enabled state

 

Since: 3.22


gs_plugin_has_flags ()

gboolean
gs_plugin_has_flags (GsPlugin *plugin,
                     GsPluginFlags flags);

Finds out if a plugin has a specific flag set.

Parameters

plugin

a GsPlugin

 

flags

a GsPluginFlags, e.g. GS_PLUGIN_FLAGS_INTERACTIVE

 

Returns

TRUE if the flag is set

Since: 3.22


gs_plugin_add_flags ()

void
gs_plugin_add_flags (GsPlugin *plugin,
                     GsPluginFlags flags);

Adds specific flags to the plugin.

Parameters

plugin

a GsPlugin

 

flags

a GsPluginFlags, e.g. GS_PLUGIN_FLAGS_INTERACTIVE

 

Since: 3.22


gs_plugin_remove_flags ()

void
gs_plugin_remove_flags (GsPlugin *plugin,
                        GsPluginFlags flags);

Removes specific flags from the plugin.

Parameters

plugin

a GsPlugin

 

flags

a GsPluginFlags, e.g. GS_PLUGIN_FLAGS_INTERACTIVE

 

Since: 3.22


gs_plugin_get_scale ()

guint
gs_plugin_get_scale (GsPlugin *plugin);

Gets the window scale factor.

Parameters

plugin

a GsPlugin

 

Returns

the factor, usually 1 for standard screens or 2 for HiDPI

Since: 3.22


gs_plugin_get_language ()

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.

Parameters

plugin

a GsPlugin

 

Returns

the language string, e.g. fr

Since: 3.22


gs_plugin_add_rule ()

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.

Parameters

plugin

a GsPlugin

 

rule

a GsPluginRule, e.g. GS_PLUGIN_RULE_CONFLICTS

 

name

a plugin name, e.g. "appstream"

 

Since: 3.22


gs_plugin_check_distro_id ()

gboolean
gs_plugin_check_distro_id (GsPlugin *plugin,
                           const gchar *distro_id);

Checks if the distro is compatible.

Parameters

plugin

a GsPlugin

 

distro_id

a distro ID, e.g. "fedora"

 

Returns

TRUE if compatible

Since: 3.22


gs_plugin_cache_lookup ()

GsApp *
gs_plugin_cache_lookup (GsPlugin *plugin,
                        const gchar *key);

Looks up an application object from the per-plugin cache

Parameters

plugin

a GsPlugin

 

key

a string

 

Returns

the GsApp, or NULL.

[transfer full][nullable]

Since: 3.22


gs_plugin_cache_lookup_by_state ()

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.

Parameters

plugin

a GsPlugin

 

list

a GsAppList to add applications to

 

state

a GsAppState

 

Since: 40


gs_plugin_cache_add ()

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.

Parameters

plugin

a GsPlugin

 

key

a string, or NULL if the unique ID should be used

 

app

a GsApp

 

Since: 3.22


gs_plugin_cache_remove ()

void
gs_plugin_cache_remove (GsPlugin *plugin,
                        const gchar *key);

Removes an application from the per-plugin cache.

Parameters

plugin

a GsPlugin

 

key

a key which matches

 

Since: 3.22


gs_plugin_cache_invalidate ()

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.

Parameters

plugin

a GsPlugin

 

Since: 3.22


gs_plugin_list_cached ()

GsAppList *
gs_plugin_list_cached (GsPlugin *plugin);

Lists all apps cached by the plugin .

Parameters

plugin

a GsPlugin

 

Returns

a GsAppList with all currently cached apps.

[transfer full]

Since: 46


gs_plugin_status_update ()

void
gs_plugin_status_update (GsPlugin *plugin,
                         GsApp *app,
                         GsPluginStatus status);

Update the state of the plugin so any UI can be updated.

Parameters

plugin

a GsPlugin

 

app

a GsApp, or NULL

 

status

a GsPluginStatus, e.g. GS_PLUGIN_STATUS_DOWNLOADING

 

Since: 3.22


gs_plugin_app_launch ()

gboolean
gs_plugin_app_launch (GsPlugin *plugin,
                      GsApp *app,
                      GError **error);

Launches the application using GAppInfo.

Parameters

plugin

a GsPlugin

 

app

a GsApp

 

error

a GError, or NULL

 

Returns

TRUE for success

Since: 3.22


GsPluginPickDesktopFileCallback ()

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 .

Parameters

plugin

a GsPlugin

 

app

a GsApp

 

filename

a .desktop file name

 

key_file

a GKeyFile with filename loaded

 

Returns

TRUE, when the key_file should be used, FALSE to continue searching.

Since: 43


gs_plugin_app_launch_filtered ()

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).

Parameters

plugin

a GsPlugin

 

app

a GsApp to launch

 

cb

a callback to pick the correct .desktop file

 

user_data

user data for the cb .

[closure cb][scope call]

error

a GError, or NULL

 

Returns

TRUE on success

Since: 43


gs_plugin_updates_changed ()

void
gs_plugin_updates_changed (GsPlugin *plugin);

Emit a signal that tells the plugin loader that the list of updates may have changed.

Parameters

plugin

a GsPlugin

 

Since: 3.22


gs_plugin_reload ()

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.

Parameters

plugin

a GsPlugin

 

Since: 3.22


gs_plugin_status_to_string ()

const gchar *
gs_plugin_status_to_string (GsPluginStatus status);

Converts the GsPluginStatus enum to a string.

Parameters

Returns

the string representation, or "unknown"

Since: 3.22


gs_plugin_report_event ()

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.

Parameters

plugin

a GsPlugin

 

event

a GsPluginEvent

 

Since: 3.24


gs_plugin_set_allow_updates ()

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.

Parameters

plugin

a GsPlugin

 

allow_updates

boolean

 

Since: 3.24


gs_plugin_get_network_available ()

gboolean
gs_plugin_get_network_available (GsPlugin *plugin);

Gets whether a network connectivity is available.

Parameters

plugin

a GsPlugin

 

Returns

TRUE if a network is available.

Since: 3.28


gs_plugin_basic_auth_start ()

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.

Parameters

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


gs_plugin_repository_changed ()

void
gs_plugin_repository_changed (GsPlugin *plugin,
                              GsApp *repository);

Emit the "repository-changed" signal in the main thread.

Parameters

plugin

a GsPlugin

 

repository

a GsApp representing the repository

 

Since: 40


gs_plugin_update_cache_state_for_repository ()

void
gs_plugin_update_cache_state_for_repository
                               (GsPlugin *plugin,
                                GsApp *repository);

Update state of the all cached GsApp instances related to the repository .

Parameters

plugin

a GsPlugin

 

repository

a GsApp representing a repository, which changed

 

Since: 40


gs_plugin_ask_untrusted ()

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.

Parameters

plugin

a GsPlugin

 

title

the title for the question

 

msg

the message for the question

 

details

the detailed error message, or NULL for none.

[nullable]

accept_label

a label of the 'accept' button, or NULL to use 'Accept'.

[nullable]

Returns

whether the user accepted the question

Since: 42


gs_plugin_get_session_bus_connection ()

GDBusConnection *
gs_plugin_get_session_bus_connection (GsPlugin *self);

Get the D-Bus session bus connection in use by the plugin.

Parameters

self

a GsPlugin

 

Returns

a D-Bus connection.

[transfer none][not nullable]

Since: 43


gs_plugin_get_system_bus_connection ()

GDBusConnection *
gs_plugin_get_system_bus_connection (GsPlugin *self);

Get the D-Bus system bus connection in use by the plugin.

Parameters

self

a GsPlugin

 

Returns

a D-Bus connection.

[transfer none][not nullable]

Since: 43

Types and Values

GS_TYPE_PLUGIN

#define GS_TYPE_PLUGIN (gs_plugin_get_type ())

struct GsPluginClass

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.

Members

updates_changed ()

   

status_changed ()

   

reload ()

   

report_event ()

   

allow_updates ()

   

basic_auth_start ()

   

repository_changed ()

   

ask_untrusted ()

   

setup_async ()

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 NULL if the plugin doesn’t need to be explicitly shut down. It is not called if the plugin is disabled during construction.

[nullable]

setup_finish ()

Finish method for setup_async . Must be implemented if setup_async is implemented. If this returns an error, the plugin will be disabled.

[nullable]

shutdown_async ()

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 NULL if the plugin doesn’t need to be explicitly shut down.

[nullable]

shutdown_finish ()

Finish method for shutdown_async . Must be implemented if shutdown_async is implemented.

[nullable]

refine_async ()

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]

refine_finish ()

Finish method for refine_async . Must be implemented if refine_async is implemented. (Since: 43).

[nullable]

list_apps_async ()

List apps matching a given query. (Since: 43).

[nullable]

list_apps_finish ()

Finish method for list_apps_async . Must be implemented if list_apps_async is implemented. (Since: 43).

[nullable]

refresh_metadata_async ()

Refresh plugin metadata. (Since: 43).

[nullable]

refresh_metadata_finish ()

Finish method for refresh_metadata_async . Must be implemented if refresh_metadata_async is implemented. (Since: 43).

[nullable]

list_distro_upgrades_async ()

List available distro upgrades. (Since: 43).

[nullable]

list_distro_upgrades_finish ()

Finish method for list_distro_upgrades_async . Must be implemented if.

[nullable]

install_repository_async ()

Install repository. (Since: 43).

[nullable]

install_repository_finish ()

Finish method for install_repository_async . Must be implemented if.

[nullable]

remove_repository_async ()

Remove repository. (Since: 43).

[nullable]

remove_repository_finish ()

Finish method for remove_repository_async . Must be implemented if.

[nullable]

enable_repository_async ()

Enable repository. (Since: 43).

[nullable]

enable_repository_finish ()

Finish method for enable_repository_async . Must be implemented if.

[nullable]

disable_repository_async ()

Disable repository. (Since: 43).

[nullable]

disable_repository_finish ()

Finish method for disable_repository_async . Must be implemented if.

[nullable]

refine_categories_async ()

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]

refine_categories_finish ()

Finish method for refine_categories_async . Must be implemented if refine_categories_async is implemented. (Since: 43).

[nullable]

update_apps_async ()

Update apps or the OS, or download updates ready for installation. (Since: 44).

[nullable]

update_apps_finish ()

Finish method for update_apps_async . Must be implemented if update_apps_async is implemented. (Since: 44).

[nullable]

gpointer padding[23];

   

GS_PLUGIN_ERROR

#define GS_PLUGIN_ERROR					gs_plugin_error_quark ()

GsPlugin

typedef struct _GsPlugin GsPlugin;