## 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_language ()
SoupSession * | gs_plugin_get_soup_session ()
void | gs_plugin_set_soup_session ()
void | gs_plugin_add_rule ()
GBytes * | gs_plugin_download_data ()
gboolean | gs_plugin_download_file ()
gchar * | gs_plugin_download_rewrite_resource ()
gboolean | gs_plugin_check_distro_id ()
GsApp * | gs_plugin_cache_lookup ()
void | gs_plugin_cache_lookup_by_state ()
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 ()
gboolean | gs_plugin_get_network_available ()
void | gs_plugin_basic_auth_start ()
void | gs_plugin_repository_changed ()
void | gs_plugin_update_cache_state_for_repository ()
gboolean | gs_plugin_get_action_supported ()

## Types and Values

#define | GS_TYPE_PLUGIN
struct | GsPluginClass
typedef | GsPluginData
#define | GS_PLUGIN_ERROR
| 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 bytes

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

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 `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_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_get_soup_session ()

    SoupSession *
    gs_plugin_get_soup_session (GsPlugin *plugin);

Gets the soup session that this plugin can use when downloading.

#### Parameters

plugin | a GsPlugin |

#### Returns

the SoupSession

Since: 3.22

### gs_plugin_set_soup_session ()

    void
    gs_plugin_set_soup_session (GsPlugin *plugin,
                                SoupSession *soup_session);

Sets the soup session that this plugin will use when downloading.

#### Parameters

plugin | a GsPlugin |
soup_session | a SoupSession |

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

    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.

#### Parameters

plugin | a GsPlugin |
app | a GsApp, or `NULL` |
resource | the CSS resource |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` for success

Since: 3.26

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

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

    gboolean
    gs_plugin_get_action_supported (GsPlugin *plugin,
                                    GsPluginAction action);

Checks whether the `plugin` supports `action` , meaning whether the `plugin` can execute the `action` .

#### Parameters

plugin | a GsPlugin |
action | a GsPluginAction |

#### Returns

Whether the `plugin` supports the `action`

Since: 41

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

### GsPluginData

    typedef struct GsPluginData GsPluginData;

### GS_PLUGIN_ERROR

    #define GS_PLUGIN_ERROR					gs_plugin_error_quark ()

### GsPlugin

    typedef struct _GsPlugin GsPlugin;