Manager API

Manager API — API for managing plugins

Functions

Signals

void load-plugin-failed Run Last
void loaded-plugin Run Last
gboolean loading-plugin Run Last
void unload-plugin-failed Run Last
void unloaded-plugin Run Last
gboolean unloading-plugin Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── GPluginManager

Description

The manager is used to manager all plugins in GPlugin. This includes loading, unloading, querying, checking for new plugins, and so on.

Functions

GPluginManagerForeachFunc ()

void
(*GPluginManagerForeachFunc) (const gchar *id,
                              GSList *plugins,
                              gpointer data);

A callback function for gplugin_manager_foreach().

Parameters

id

The id of the plugin.

 

plugins

A GSList of each plugin that has the id id .

 

data

User data passed to gplugin_manager_foreach().

 

gplugin_manager_append_path ()

void
gplugin_manager_append_path (GPluginManager *manager,
                             const gchar *path);

Adds path to the end of the list of paths to search for plugins.

Parameters

manager

The GPluginManager instance.

 

path

A path to add to the end of the plugin search paths.

 

gplugin_manager_prepend_path ()

void
gplugin_manager_prepend_path (GPluginManager *manager,
                              const gchar *path);

Adds path to the beginning of the list of paths to search for plugins.

Parameters

manager

The GPluginManager instance.

 

path

A path to add to the beginning of the plugin search paths.

 

gplugin_manager_remove_path ()

void
gplugin_manager_remove_path (GPluginManager *manager,
                             const gchar *path);

Removes path from the list of paths to search for plugins.

Parameters

manager

The GPluginManager instance.

 

path

A path to remove from the plugin search paths.

 

gplugin_manager_remove_paths ()

void
gplugin_manager_remove_paths (GPluginManager *manager);

Clears all paths that are set to search for plugins.

Parameters

manager

The GPluginManager instance.

 

gplugin_manager_add_default_paths ()

void
gplugin_manager_add_default_paths (GPluginManager *manager);

Adds the path that GPlugin was installed to to the plugin search path, as well as ${XDG_CONFIG_HOME}/gplugin so users can install additional loaders themselves.

Parameters

manager

The GPluginManager instance.

 

gplugin_manager_add_app_paths ()

void
gplugin_manager_add_app_paths (GPluginManager *manager,
                               const gchar *prefix,
                               const gchar *appname);

Adds the application installation path for appname . This will add @prefix/@appname/plugins to the list as well as ${XDG_CONFIG_HOME}/@appname/plugins.

Parameters

manager

The GPluginManager instance.

 

prefix

The installation prefix for the application.

 

appname

The name of the application whose paths to add.

 

gplugin_manager_get_paths ()

GList *
gplugin_manager_get_paths (GPluginManager *manager);

Gets the list of paths which will be searched for plugins.

Parameters

manager

The GPluginManager instance.

 

Returns

The list of paths which will be searched for plugins.

[element-type utf8][transfer none]


gplugin_manager_register_loader ()

gboolean
gplugin_manager_register_loader (GPluginManager *manager,
                                 GType type,
                                 GError **error);

Registers type as an available loader.

Parameters

manager

The GPluginManager instance.

 

type

GType of a GPluginLoader.

 

error

The return address for a GError.

[out][nullable]

Returns

TRUE if the loader was successfully register, FALSE otherwise with error set.


gplugin_manager_unregister_loader ()

gboolean
gplugin_manager_unregister_loader (GPluginManager *manager,
                                   GType type,
                                   GError **error);

Unregisters type as an available loader.

Parameters

manager

The GPluginManager instance.

 

type

GType of a GPluginLoader.

 

error

The return address for a GError.

[out][nullable]

Returns

TRUE if the loader was successfully unregistered, FALSE otherwise with error set.


gplugin_manager_get_loaders ()

GSList *
gplugin_manager_get_loaders (GPluginManager *manager);

Returns a list of all registered GPluginLoader's.

Parameters

manager

The GPluginManager instance.

 

Returns

Returns a list of all registered loaders.

[element-type GPlugin.Loader][transfer full]


gplugin_manager_refresh ()

void
gplugin_manager_refresh (GPluginManager *manager);

Forces a refresh of all plugins found in the search paths.

Parameters

manager

The GPluginManager instance.

 

gplugin_manager_foreach ()

void
gplugin_manager_foreach (GPluginManager *manager,
                         GPluginManagerForeachFunc func,
                         gpointer data);

Calls func for each plugin that is known.

Parameters

manager

The GPluginManager instance.

 

func

The GPluginManagerForeachFunc to call.

[scope call]

data

User data to pass to func.

 

gplugin_manager_find_plugins ()

GSList *
gplugin_manager_find_plugins (GPluginManager *manager,
                              const gchar *id);

Finds all plugins matching id .

Parameters

manager

The GPluginManager instance.

 

id

id string of the plugin to find.

 

Returns

A GSList of referenced GPluginPlugin's matching id . Call g_slist_free_full() with a DestroyNotify of g_object_unref() on the returned value when you're done with it.

[element-type GPlugin.Plugin][transfer full]


gplugin_manager_find_plugins_with_version ()

GSList *
gplugin_manager_find_plugins_with_version
                               (GPluginManager *manager,
                                const gchar *id,
                                const gchar *op,
                                const gchar *version);

Similar to gplugin_manager_find_plugins() but only returns plugins whose versions match op and version . This is primarily used for dependency loading where a plugin may depend on a specific range of versions of another plugin.

Parameters

manager

The GPluginManager instance.

 

id

The ID of the plugin to find.

 

op

one of <, <=, =, ==, >=, >.

 

version

The version to compare against.

 

Returns

A GSList of referenced GPluginPlugin's matching id . Call g_slist_free_full() with a DestroyNotify of g_object_unref() on the returned value when you're done with it.

[element-type GPlugin.Plugin][transfer full]


gplugin_manager_find_plugins_with_state ()

GSList *
gplugin_manager_find_plugins_with_state
                               (GPluginManager *manager,
                                GPluginPluginState state);

Finds all plugins that currently have a state of state .

Parameters

manager

The GPluginManager instance.

 

state

The GPluginPluginState to look for.

 

Returns

A GSList of referenced GPluginPlugin's whose state is state . Call g_slist_free_full() with a DestroyNotify of g_object_unref() on the returned value when you're done with it.

[element-type GPlugin.Plugin][transfer full]


gplugin_manager_find_plugin ()

GPluginPlugin *
gplugin_manager_find_plugin (GPluginManager *manager,
                             const gchar *id);

Finds the first plugin matching id . This function uses gplugin_manager_find_plugins and returns the first plugin in the list.

Parameters

manager

The GPluginManager instance.

 

id

The id of the plugin to find.

 

Returns

A referenced GPluginPlugin instance or NULL if no plugin matching id was found.

[transfer full]


gplugin_manager_find_plugin_with_newest_version ()

GPluginPlugin *
gplugin_manager_find_plugin_with_newest_version
                               (GPluginManager *manager,
                                const gchar *id);

Calls gplugin_manager_find_plugins() with id , and then returns the plugins with the highest version number or NULL if no plugins with id are found.

Parameters

manager

The GPluginManager instance.

 

id

The id of the plugin to find.

 

Returns

The GPluginPlugin with an id of id that has the highest version number, or NULL if no plugins were found with id .

[transfer full]


gplugin_manager_get_plugin_dependencies ()

GSList *
gplugin_manager_get_plugin_dependencies
                               (GPluginManager *manager,
                                GPluginPlugin *plugin,
                                GError **error);

Returns a list of all the GPluginPlugin's that plugin depends on.

Parameters

manager

The GPluginManager instance.

 

plugin

The GPluginPlugin whose dependencies to get.

 

error

Return address for a GError.

[out][nullable]

Returns

A GSList of GPluginPlugin's that plugin depends on, or NULL on error with error set. Call g_slist_free_full() with a DestroyNotify of g_object_unref() on the returned value when you're done with it.

[element-type GPlugin.Plugin][transfer full]


gplugin_manager_load_plugin ()

gboolean
gplugin_manager_load_plugin (GPluginManager *manager,
                             GPluginPlugin *plugin,
                             GError **error);

Loads plugin and all of its dependencies. If a dependency can not be loaded, plugin will not be loaded either. However, any other plugins that plugin depends on that were loaded from this call, will not be unloaded.

Parameters

manager

The GPluginManager instance.

 

plugin

GPluginPlugin instance.

 

error

return location for a GError or NULL.

[out][nullable]

Returns

TRUE if plugin was loaded successfully or already loaded, FALSE otherwise.


gplugin_manager_unload_plugin ()

gboolean
gplugin_manager_unload_plugin (GPluginManager *manager,
                               GPluginPlugin *plugin,
                               GError **error);

Unloads plugin . If plugin has dependencies, they are not unloaded.

Parameters

manager

The GPluginManager instance.

 

plugin

GPluginPlugin instance.

 

error

Return location for a GError or NULL.

[out][nullable]

Returns

TRUE if plugin was unloaded successfully or not loaded, FALSE otherwise.


gplugin_manager_list_plugins ()

GList *
gplugin_manager_list_plugins (GPluginManager *manager);

Returns a GList of all plugin id's. Each id should be queried directly for more information.

Parameters

manager

The GPluginManager instance.

 

Returns

A GList of each unique plugin id.

[element-type utf8][transfer container]


gplugin_manager_get_default ()

GPluginManager *
gplugin_manager_get_default (void);

Gets the default GPluginManager in GPlugin.

Returns

The default GPluginManager instance.

[transfer none]

Since: 0.33.0

Types and Values

GPLUGIN_TYPE_MANAGER

#define GPLUGIN_TYPE_MANAGER (gplugin_manager_get_type())

struct GPluginManagerClass

struct GPluginManagerClass {
	gboolean (*loading_plugin)(
		GPluginManager *manager,
		GPluginPlugin *plugin,
		GError **error);
	void (*loaded_plugin)(GPluginManager *manager, GPluginPlugin *plugin);
	void (*load_failed)(GPluginManager *manager, GPluginPlugin *plugin);
	gboolean (*unloading_plugin)(
		GPluginManager *manager,
		GPluginPlugin *plugin,
		GError **error);
	void (*unloaded_plugin)(GPluginManager *manager, GPluginPlugin *plugin);
	void (
		*unload_plugin_failed)(GPluginManager *manager, GPluginPlugin *plugin);
};

Virtual function table for GPluginManager.

Members

loading_plugin ()

Signal emitted before a plugin is loaded.

 

loaded_plugin ()

Signal emitted after a plugin is loaded.

 

load_failed ()

Signal emitted when a plugin fails to load.

 

unloading_plugin ()

Signal emitted before a plugin is unloaded.

 

unloaded_plugin ()

Signal emitted after a plugin is unloaded.

 

unload_plugin_failed ()

Signal emitted when a plugin fails to unload.

 

GPluginManager

typedef struct _GPluginManager GPluginManager;

Signal Details

The “load-plugin-failed” signal

void
user_function (GPluginManager *manager,
               GObject        *plugin,
               gpointer        user_data)

emitted after a plugin fails to load.

Parameters

manager

The GPluginManager instance.

 

plugin

The GPluginPlugin that failed to load.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “loaded-plugin” signal

void
user_function (GPluginManager *manager,
               GObject        *plugin,
               gpointer        user_data)

emitted after a plugin is loaded.

Parameters

manager

the gpluginpluginmanager instance.

 

plugin

the gpluginplugin that's about to be loaded.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “loading-plugin” signal

gboolean
user_function (GPluginManager *manager,
               GObject        *plugin,
               gpointer        error,
               gpointer        user_data)

Emitted before plugin is loaded.

Return FALSE to stop loading

Parameters

manager

The GPluginManager instance.

 

plugin

The GPluginPlugin that's about to be loaded.

 

error

Return address for a GError.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “unload-plugin-failed” signal

void
user_function (GPluginManager *manager,
               GObject        *plugin,
               gpointer        user_data)

Emitted when manager was asked to unload plugin , but plugin returned FALSE when its unload function was called.

Parameters

manager

The GPluginManager instance.

 

plugin

The GPluginPlugin instance that failed to unload.

 

error

A GError instance.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “unloaded-plugin” signal

void
user_function (GPluginManager *manager,
               GObject        *plugin,
               gpointer        user_data)

emitted after a plugin is successfully unloaded.

Parameters

manager

the gpluginpluginmanager instance.

 

plugin

the gpluginplugin that's about to be loaded.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “unloading-plugin” signal

gboolean
user_function (GPluginManager *manager,
               GObject        *plugin,
               gpointer        error,
               gpointer        user_data)

emitted before a plugin is unloaded.

Return FALSE to stop unloading

Parameters

manager

the GPluginManager instance.

 

plugin

the GPluginPlugin that's about to be unloaded.

 

error

Return address for a GError.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last