## go-plugin

go-plugin

## Synopsis

                        GOPlugin;
    void                go_plugin_init                      (GOPlugin *plugin,
                                                             GOCmdContext *cc);
    void                go_plugin_shutdown                  (GOPlugin *plugin,
                                                             GOCmdContext *cc);
    void                go_plugin_activate                  (GOPlugin *plugin,
                                                             GOErrorInfo **ret_error);
    void                go_plugin_deactivate                (GOPlugin *plugin,
                                                             GOErrorInfo **ret_error);
    gboolean            go_plugin_is_active                 (GOPlugin *plugin);
    gboolean            go_plugin_can_deactivate            (GOPlugin *plugin);
    GOPluginLoader *    go_plugin_get_loader                (GOPlugin *plugin);
    void                go_plugin_load_service              (GOPlugin *plugin,
                                                             GOPluginService *service,
                                                             GOErrorInfo **ret_error);
    void                go_plugin_unload_service            (GOPlugin *plugin,
                                                             GOPluginService *service,
                                                             GOErrorInfo **ret_error);
    gboolean            go_plugin_is_loaded                 (GOPlugin *plugin);
    void                go_plugin_use_ref                   (GOPlugin *plugin);
    void                go_plugin_use_unref                 (GOPlugin *plugin);
    GTypeModule *       go_plugin_get_type_module           (GOPlugin *plugin);
    char const  *       go_plugin_get_dir_name              (GOPlugin *plugin);
    char const  *       go_plugin_get_id                    (GOPlugin *plugin);
    char const  *       go_plugin_get_name                  (GOPlugin *plugin);
    char const  *       go_plugin_get_description           (GOPlugin *plugin);
    char const  *       go_plugin_get_textdomain            (GOPlugin *plugin);
    GSList *            go_plugin_get_services              (GOPlugin *plugin);
    GSList *            go_plugin_get_dependencies_ids      (GOPlugin *plugin);
    void                go_plugins_init                     (GOCmdContext *context,
                                                             GSList const *known_states,
                                                             GSList const *active_plugins,
                                                             GSList *plugin_dirs,
                                                             gboolean activate_new_plugins,
                                                             GType default_loader_type);
    GSList *            go_plugins_shutdown                 (void);
    void                go_plugins_add                      (GOCmdContext *context,
                                                             GSList const *known_states,
                                                             GSList const *active_plugins,
                                                             GSList *plugin_dirs,
                                                             GType default_loader_type);
    void                go_plugins_register_loader          (const gchar *id_str,
                                                             GOPluginService *service);
    void                go_plugins_unregister_loader        (const gchar *id_str);
    GOPlugin *          go_plugins_get_plugin_by_id         (const gchar *plugin_id);
    GSList *            go_plugins_get_available_plugins    (void);
    GSList *            go_plugins_get_active_plugins       (void);
    void                go_plugins_rescan                   (GOErrorInfo **ret_error,
                                                             GSList **ret_new_plugins);
    char *              go_plugins_get_plugin_dir           (void);
    void                go_plugin_db_mark_plugin_for_deactivation
                                                            (GOPlugin *plugin,
                                                             gboolean mark);
    gboolean            go_plugin_db_is_plugin_marked_for_deactivation
                                                            (GOPlugin *plugin);
    void                go_plugin_db_activate_plugin_list   (GSList *plugins,
                                                             GOErrorInfo **ret_error);
    void                go_plugin_db_deactivate_plugin_list (GSList *plugins,
                                                             GOErrorInfo **ret_error);

## Object Hierarchy

      GObject
       +----GOPlugin

## Signals

      "can-deactivate-changed"                         : Run Last
      "state-changed"                                  : Run Last

## Description

## Details

### GOPlugin

    typedef struct _GOPlugin GOPlugin;

### go_plugin_init ()

    void                go_plugin_init                      (GOPlugin *plugin,
                                                             GOCmdContext *cc);

`plugin` : |
`cc` : |

### go_plugin_shutdown ()

    void                go_plugin_shutdown                  (GOPlugin *plugin,
                                                             GOCmdContext *cc);

`plugin` : |
`cc` : |

### go_plugin_activate ()

    void                go_plugin_activate                  (GOPlugin *plugin,
                                                             GOErrorInfo **ret_error);

Activates `plugin` together with all its dependencies. In case of error the plugin won't be activated and detailed error information will be returned using `ret_error`.

`plugin` : | GOPlugin
`ret_error` : | Pointer used to report errors

### go_plugin_deactivate ()

    void                go_plugin_deactivate                (GOPlugin *plugin,
                                                             GOErrorInfo **ret_error);

Dectivates `plugin`. Its dependencies will NOT be automatically deactivated. In case of error the plugin won't be deactivated and detailed error information will be returned using `ret_error`.

`plugin` : | GOPlugin
`ret_error` : | Pointer used to report errors

### go_plugin_is_active ()

    gboolean            go_plugin_is_active                 (GOPlugin *plugin);

`plugin` : | GOPlugin
Returns : | TRUE if `plugin` is active and FALSE otherwise.

### go_plugin_can_deactivate ()

    gboolean            go_plugin_can_deactivate            (GOPlugin *plugin);

Tells if the plugin can be deactivated using go_plugin_deactivate.

`plugin` : | GOPlugin
Returns : | TRUE if `plugin` can be deactivated and FALSE otherwise.

### go_plugin_get_loader ()

    GOPluginLoader *    go_plugin_get_loader                (GOPlugin *plugin);

`plugin` : | GOPlugin
Returns : | The loader.

### go_plugin_load_service ()

    void                go_plugin_load_service              (GOPlugin *plugin,
                                                             GOPluginService *service,
                                                             GOErrorInfo **ret_error);

Loads base part of the plugin if it is not loaded and then loads given plugin service (prepares necessary part of the plugin for direct use). This function is intended for use by GOPluginService objects.

`plugin` : | GOPlugin
`service` : | Plugin service
`ret_error` : | Pointer used to report errors

### go_plugin_unload_service ()

    void                go_plugin_unload_service            (GOPlugin *plugin,
                                                             GOPluginService *service,
                                                             GOErrorInfo **ret_error);

... This function is intended for use by GOPluginService objects.

`plugin` : | GOPlugin
`service` : | Plugin service
`ret_error` : | Pointer used to report errors

### go_plugin_is_loaded ()

    gboolean            go_plugin_is_loaded                 (GOPlugin *plugin);

`plugin` : | GOPlugin
Returns : | TRUE if `plugin` is loaded and FALSE otherwise.

### go_plugin_use_ref ()

    void                go_plugin_use_ref                   (GOPlugin *plugin);

`plugin` : | GOPlugin

### go_plugin_use_unref ()

    void                go_plugin_use_unref                 (GOPlugin *plugin);

`plugin` : | GOPlugin

### go_plugin_get_type_module ()

    GTypeModule *       go_plugin_get_type_module           (GOPlugin *plugin);

`plugin` : | GOPlugin
Returns : | the GTypeModule associated with the plugin creating it if necessary.

### go_plugin_get_dir_name ()

    char const  *       go_plugin_get_dir_name              (GOPlugin *plugin);

`plugin` : | GOPlugin
Returns : | the name of the directory in which `plugin` is located. Returned string is != NULL and stays valid during `plugin`'s lifetime.

### go_plugin_get_id ()

    char const  *       go_plugin_get_id                    (GOPlugin *plugin);

`plugin` : | GOPlugin
Returns : | the ID of `plugin` (unique string used for idenfification of plugin). Returned string is != NULL and stays valid during `plugin`'s lifetime.

### go_plugin_get_name ()

    char const  *       go_plugin_get_name                  (GOPlugin *plugin);

`plugin` : | GOPlugin
Returns : | textual name of `plugin`. If the real name is not available for some reason, automatically generated string will be returned. Returned string is != NULL and stays valid during `plugin`'s lifetime.

### go_plugin_get_description ()

    char const  *       go_plugin_get_description           (GOPlugin *plugin);

`plugin` : | GOPlugin
Returns : | textual description of `plugin` or NULL if description is not available. Returned string stays valid during `plugin`'s lifetime.

### go_plugin_get_textdomain ()

    char const  *       go_plugin_get_textdomain            (GOPlugin *plugin);

`plugin` : | GOPlugin
Returns : | plugin's textdomain for use with textdomain(3) and d*gettext(3) functions.

### go_plugin_get_services ()

    GSList *            go_plugin_get_services              (GOPlugin *plugin);

`plugin` : | GOPlugin
Returns : | A list of services. The list must not be freed or changed.

### go_plugin_get_dependencies_ids ()

    GSList *            go_plugin_get_dependencies_ids      (GOPlugin *plugin);

`plugin` : | GOPlugin
Returns : | the list of identifiers of plugins that `plugin` depends on. All these plugins will be automatically activated before activating the `plugin` itself. The caller must free the returned list together with the strings it points to (use go_slist_free_custom (list, g_free) to do this).

### go_plugins_init ()

    void                go_plugins_init                     (GOCmdContext *context,
                                                             GSList const *known_states,
                                                             GSList const *active_plugins,
                                                             GSList *plugin_dirs,
                                                             gboolean activate_new_plugins,
                                                             GType default_loader_type);

Initializes the plugin subsystem. Don't call this function more than once.

`context` : | GOCmdContext used to report errors
`known_states` : | A list of known states (defined how ?)
`active_plugins` : | A list of active plugins
`plugin_dirs` : | a list of directories to search for plugins
`activate_new_plugins` : | activate plugins we have no seen before.
`default_loader_type` : | importer to use by default.

### go_plugins_shutdown ()

    GSList *            go_plugins_shutdown                 (void);

Returns : |

### go_plugins_add ()

    void                go_plugins_add                      (GOCmdContext *context,
                                                             GSList const *known_states,
                                                             GSList const *active_plugins,
                                                             GSList *plugin_dirs,
                                                             GType default_loader_type);

### Warning

`go_plugins_add` is deprecated and should not be used in newly-written code. this function is deprecated and should not be used at all. It will be removed during next development cycle. Use `go_plugins_init()` instead.

Adds new plugins to currently used plugins.

`context` : | GOCmdContext used to report errors
`known_states` : | A list of known states (defined how ?)
`active_plugins` : | A list of active plugins
`plugin_dirs` : | a list of directories to search for plugins
`default_loader_type` : | importer to use by default.

### go_plugins_register_loader ()

    void                go_plugins_register_loader          (const gchar *id_str,
                                                             GOPluginService *service);

`id_str` : |
`service` : |

### go_plugins_unregister_loader ()

    void                go_plugins_unregister_loader        (const gchar *id_str);

`id_str` : |

### go_plugins_get_plugin_by_id ()

    GOPlugin *          go_plugins_get_plugin_by_id         (const gchar *plugin_id);

`plugin_id` : |
Returns : |

### go_plugins_get_available_plugins ()

    GSList *            go_plugins_get_available_plugins    (void);

Returns : |

### go_plugins_get_active_plugins ()

    GSList *            go_plugins_get_active_plugins       (void);

Returns : |

### go_plugins_rescan ()

    void                go_plugins_rescan                   (GOErrorInfo **ret_error,
                                                             GSList **ret_new_plugins);

`ret_error` : |
`ret_new_plugins` : |

### go_plugins_get_plugin_dir ()

    char *              go_plugins_get_plugin_dir           (void);

Returns : |

### go_plugin_db_mark_plugin_for_deactivation ()

    void                go_plugin_db_mark_plugin_for_deactivation
                                                            (GOPlugin *plugin,
                                                             gboolean mark);

`plugin` : |
`mark` : |

### go_plugin_db_is_plugin_marked_for_deactivation ()

    gboolean            go_plugin_db_is_plugin_marked_for_deactivation
                                                            (GOPlugin *plugin);

`plugin` : |
Returns : |

### go_plugin_db_activate_plugin_list ()

    void                go_plugin_db_activate_plugin_list   (GSList *plugins,
                                                             GOErrorInfo **ret_error);

`plugins` : |
`ret_error` : |

### go_plugin_db_deactivate_plugin_list ()

    void                go_plugin_db_deactivate_plugin_list (GSList *plugins,
                                                             GOErrorInfo **ret_error);

`plugins` : |
`ret_error` : |

## Signal Details

### The `"can-deactivate-changed"` signal

    void                user_function                      (GOPlugin *goplugin,
                                                            gpointer  user_data)      : Run Last

`goplugin` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"state-changed"` signal

    void                user_function                      (GOPlugin *goplugin,
                                                            gpointer  user_data)      : Run Last

`goplugin` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.