Plugin loader and global functions

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