GsPlugin Helpers: GNOME Software Reference Manual

## GsPlugin Helpers GsPlugin Helpers — Runtime-loaded modules providing functionality |

## Stability Level

Unstable, unless otherwise indicated

## Functions

GQuark | gs_plugin_error_quark ()
GsPluginData * | gs_plugin_alloc_data ()
GsPluginData * | gs_plugin_get_data ()
const gchar * | gs_plugin_get_name ()
const gchar * | gs_plugin_get_appstream_id ()
void | gs_plugin_set_appstream_id ()
gboolean | gs_plugin_get_enabled ()
void | gs_plugin_set_enabled ()
gboolean | gs_plugin_has_flags ()
void | gs_plugin_add_flags ()
void | gs_plugin_remove_flags ()
guint | gs_plugin_get_scale ()
const gchar * | gs_plugin_get_locale ()
const gchar * | gs_plugin_get_language ()
AsProfile * | gs_plugin_get_profile ()
SoupSession * | gs_plugin_get_soup_session ()
void | gs_plugin_add_auth ()
GsAuth * | gs_plugin_get_auth_by_id ()
void | gs_plugin_add_rule ()
GBytes * | gs_plugin_download_data ()
gboolean | gs_plugin_download_file ()
gboolean | gs_plugin_check_distro_id ()
GsApp * | gs_plugin_cache_lookup ()
void | gs_plugin_cache_add ()
void | gs_plugin_cache_remove ()
void | gs_plugin_cache_invalidate ()
void | gs_plugin_status_update ()
gboolean | gs_plugin_app_launch ()
void | gs_plugin_updates_changed ()
void | gs_plugin_reload ()
const gchar * | gs_plugin_status_to_string ()
void | gs_plugin_report_event ()
void | gs_plugin_set_allow_updates ()

## Properties

guint64 | flags | Read / Write

## Signals

void | allow-updates | Run Last
void | reload | Run Last
void | report-event | Run Last
void | status-changed | Run Last
void | updates-changed | Run Last

## Types and Values

#define | GS_TYPE_PLUGIN
struct | GsPluginClass
typedef | GsPluginData
#define | GS_PLUGIN_ERROR
| GsPlugin

## Object Hierarchy

        GObject
        ╰── GsPlugin

## 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_alloc_data ()

    GsPluginData *
    gs_plugin_alloc_data (GsPlugin *plugin,
                          gsize sz);

Allocates a private data area for the plugin which can be retrieved using `gs_plugin_get_data()`. This is normally called in `gs_plugin_initialize()` and the data should not be manually freed.

#### Parameters

plugin | a GsPlugin |
sz | the size of data to allocate, e.g. `sizeof(FooPluginPrivate)` |

#### Returns

the GsPluginData, cleared to NUL butes

Since: 3.22

### gs_plugin_get_data ()

    GsPluginData *
    gs_plugin_get_data (GsPlugin *plugin);

Gets the private data for the plugin if `gs_plugin_alloc_data()` has been called.

#### Parameters

plugin | a GsPlugin |

#### Returns

the GsPluginData, or `NULL`

Since: 3.22

### 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);

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_set_appstream_id ()

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

### 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 `gs_plugin_initialize()`.

#### 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_RUNNING_SELF` |

#### 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_RUNNING_SELF` |

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_RUNNING_SELF` |

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_locale ()

    const gchar *
    gs_plugin_get_locale (GsPlugin *plugin);

Gets the user locale.

#### Parameters

plugin | a GsPlugin |

#### Returns

the locale string, e.g. "en_GB"

Since: 3.22

### gs_plugin_get_language ()

    const gchar *
    gs_plugin_get_language (GsPlugin *plugin);

Gets the user language from the locale.

#### Parameters

plugin | a GsPlugin |

#### Returns

the language string, e.g. "fr"

Since: 3.22

### gs_plugin_get_profile ()

    AsProfile *
    gs_plugin_get_profile (GsPlugin *plugin);

Gets the profile object to be used for the plugin. This can be used to make plugin actions appear in the global profile output.

#### Parameters

plugin | a GsPlugin |

#### Returns

the AsProfile

Since: 3.22

### gs_plugin_get_soup_session ()

    SoupSession *
    gs_plugin_get_soup_session (GsPlugin *plugin);

Gets the soup session that plugins can use when downloading.

#### Parameters

plugin | a GsPlugin |

#### Returns

the SoupSession

Since: 3.22

### gs_plugin_add_auth ()

    void
    gs_plugin_add_auth (GsPlugin *plugin,
                        GsAuth *auth);

Adds an authentication object that can be used for all the plugins.

#### Parameters

plugin | a GsPlugin |
auth | a GsAuth |

Since: 3.22

### gs_plugin_get_auth_by_id ()

    GsAuth *
    gs_plugin_get_auth_by_id (GsPlugin *plugin,
                              const gchar *provider_id);

Gets a specific authentication object.

#### Parameters

plugin | a GsPlugin |
provider_id | an ID, e.g. "dummy-sso" |

#### Returns

the GsAuth, or `NULL` if not found

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_download_data ()

    GBytes *
    gs_plugin_download_data (GsPlugin *plugin,
                             GsApp *app,
                             const gchar *uri,
                             GCancellable *cancellable,
                             GError **error);

Downloads data.

#### Parameters

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

#### Returns

the downloaded data, or `NULL`

Since: 3.22

### gs_plugin_download_file ()

    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.

#### Parameters

plugin | a GsPlugin |
app | a GsApp, or `NULL` |
uri | a remote URI |
filename | a local filename |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success

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_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 funtion; if a suitable cache key is being used the old cache item can remain.

#### Parameters

plugin | a GsPlugin |

Since: 3.22

### 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

### 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

status | a GsPluginStatus, e.g. `GS_PLUGIN_STATUS_DOWNLOADING` |

#### 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

## 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);
    	gpointer		 padding[26];
    };

### GsPluginData

    typedef struct GsPluginData GsPluginData;

### GS_PLUGIN_ERROR

    #define GS_PLUGIN_ERROR					gs_plugin_error_quark ()

### GsPlugin

    typedef struct _GsPlugin GsPlugin;

## Property Details

### The `“flags”` property

      “flags”                    guint64

Flags: Read / Write

Default value: 0

## Signal Details

### The `“allow-updates”` signal

    void
    user_function (GsPlugin *gsplugin,
                   gboolean  arg1,
                   gpointer  user_data)

Flags: Run Last

### The `“reload”` signal

    void
    user_function (GsPlugin *gsplugin,
                   gpointer  user_data)

Flags: Run Last

### The `“report-event”` signal

    void
    user_function (GsPlugin      *gsplugin,
                   GsPluginEvent *arg1,
                   gpointer       user_data)

Flags: Run Last

### The `“status-changed”` signal

    void
    user_function (GsPlugin *gsplugin,
                   GsApp    *arg1,
                   guint     arg2,
                   gpointer  user_data)

Flags: Run Last

### The `“updates-changed”` signal

    void
    user_function (GsPlugin *gsplugin,
                   gpointer  user_data)

Flags: Run Last