## Plugin loader and global functions

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

## Functions

GObject * | mcp_plugin_ref_nth_object ()
void | mcp_set_debug ()
void | mcp_add_object ()
void | mcp_read_dir ()
const GList * | mcp_list_objects ()

## Types and Values

#define | MCP_PLUGIN_REF_NTH_OBJECT_SYMBOL

## Includes

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

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

## Functions

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

## Types and Values

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