Plugin loader and global functions

Plugin loader and global functions — Writing a plugin, or loading plugins

Synopsis

#include <mission-control-plugins/mission-control-plugins.h>

GObject *           mcp_plugin_ref_nth_object           (guint n);
#define             MCP_PLUGIN_REF_NTH_OBJECT_SYMBOL
void                mcp_set_debug                       (gboolean debug);
void                mcp_add_object                      (gpointer object);
void                mcp_read_dir                        (const gchar *path);
const GList *       mcp_list_objects                    (void);

Description

To write plugins for Mission Control, build a GModule whose name starts with "mcp-" and ends with G_MODULE_SUFFIX, for instance mcp-testplugin.so on Linux or mcp-testplugin.dll on Windows. It must be installed in the directory given by the ${plugindir} variable in the mission-control-plugins pkg-config file.

Each plugin must contain an extern (public) function called mcp_plugin_ref_nth_object() which behaves as documented here. Mission Control will call that function to load the plugin.

Mission Control also uses functions from this part of the library, to load the plugins.

Details

mcp_plugin_ref_nth_object ()

GObject *           mcp_plugin_ref_nth_object           (guint n);

Implemented by each plugin (not implemented in this library!) as a hook point; it will be called repeatedly with an increasing argument, and must return a GObject reference each time, until it returns NULL.

Mission Control will query each object for the GInterfaces it implements, and behave accordingly; for instance, the objects might implement McpRequestPolicy and/or McpDispatchOperationPolicy.

As currently implemented, these objects are never unreferenced.

`n` :	object number, starting from 0
Returns :	a new reference to a GObject, or `NULL` if `n` is at least the number of objects supported by this plugin

MCP_PLUGIN_REF_NTH_OBJECT_SYMBOL

#define MCP_PLUGIN_REF_NTH_OBJECT_SYMBOL "mcp_plugin_ref_nth_object"

A string constant whose value is the name mcp_plugin_ref_nth_object().

mcp_set_debug ()

void                mcp_set_debug                       (gboolean debug);

Set whether debug output will be produced via g_debug() for the plugin loader. Plugins shouldn't normally need to call this function.

debug :

whether to log debug output

mcp_add_object ()

void                mcp_add_object                      (gpointer object);

Add an object to the list of "plugin objects". Mission Control does this automatically for the objects returned by mcp_plugin_ref_nth_object(), so you should only need to use this if you're embedding part of Mission Control in a larger process.

As currently implemented, these objects are never unreferenced.

Mission Control uses this function to load its plugins; plugins shouldn't call it.

object :

an object implementing one or more plugin interfaces

mcp_read_dir ()

void                mcp_read_dir                        (const gchar *path);

Read plugins from the given path. Any file with prefix "mcp-" and suffix G_MODULE_SUFFIX is considered as a potential plugin, and loaded; if it contains the symbol mcp_plugin_ref_nth_object(), the plugin is made resident, then that symbol is called as a function until it returns NULL.

Mission Control uses this function to load its plugins; plugins shouldn't call it.

path :

full path to a plugins directory

mcp_list_objects ()

const GList *       mcp_list_objects                    (void);

Return a list of objects that might implement plugin interfaces.

Mission Control uses this function to iterate through the loaded plugin objects; plugins shouldn't need to call it.

Returns :

a constant list of plugin objects