Pileus Git - grits/blob - src/gis-plugin.c

   1 /*
   2  * Copyright (C) 2009-2010 Andy Spencer <andy753421@gmail.com>
   3  *
   4  * This program is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 3 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /**
  19  * SECTION:gis-plugin
  20  * @short_description: Plugin support
  21  *
  22  * A plugin in libgis is a GObject which implements the GisPlugin interface. Additionally, each
  23  * plugin is compiled to a separate shared object and loaded conditionally at runtime when the
  24  * plugin is enabled. Each such shared object should define a GisPluginConstructor() function named
  25  * gis_plugin_NAME_new which will be called when loading the plugin.
  26  *
  27  * Almost all libgis functionality is provided by a set of plugins. Each plugin can how however much
  28  * it likes. The interface between plugins and the rest of libgis is intentionally very thin. Since
  29  * libgis is the library, plugins must manually do everything. For instance, to draw something in
  30  * the world, the plugin must add an object to the viewer. Likewise, plugins need to register
  31  * callbacks on the viewer in order to receive updates, very little happens automagically.
  32  *
  33  * That being said, one thing that plugins do do automagically, is provide a configuration area.
  34  * Since the plugin doesn't know what application is is being loaded form, it is better for the
  35  * application to ask the plugin for it's confirmation area, not the other way around.
  36  */
  37
  38 #include <glib.h>
  39 #include <gmodule.h>
  40
  41 #include <string.h>
  42
  43 #include "gis-plugin.h"
  44
  45 /********************
  46  * Plugin interface *
  47  ********************/
  48 static void gis_plugin_base_init(gpointer g_class)
  49 {
  50         static gboolean is_initialized = FALSE;
  51         if (!is_initialized) {
  52                 /* add properties and signals to the interface here */
  53                 is_initialized = TRUE;
  54         }
  55 }
  56
  57 GType gis_plugin_get_type()
  58 {
  59         static GType type = 0;
  60         if (type == 0) {
  61                 static const GTypeInfo info = {
  62                         sizeof(GisPluginInterface),
  63                         gis_plugin_base_init,
  64                         NULL,
  65                 };
  66                 type = g_type_register_static(G_TYPE_INTERFACE,
  67                                 "GisPlugin", &info, 0);
  68         }
  69         return type;
  70 }
  71
  72 /**
  73  * gis_plugin_get_name:
  74  * @plugin: the plugin
  75  *
  76  * Get a short human readable name for a plugin, this is not necessarily the
  77  * same as the name of the shared object.
  78  *
  79  * Returns: a short name for the plugin
  80  */
  81 const gchar *gis_plugin_get_name(GisPlugin *plugin)
  82 {
  83         if (!GIS_IS_PLUGIN(plugin))
  84                 return NULL;
  85         return GIS_PLUGIN_GET_INTERFACE(plugin)->name;
  86 }
  87
  88 /**
  89  * gis_plugin_get_description:
  90  * @plugin: the plugin
  91  *
  92  * Get a description of a plugin
  93  *
  94  * Returns: a description of the plugin
  95  */
  96 const gchar *gis_plugin_get_description(GisPlugin *plugin)
  97 {
  98         if (!GIS_IS_PLUGIN(plugin))
  99                 return NULL;
 100         return GIS_PLUGIN_GET_INTERFACE(plugin)->description;
 101 }
 102
 103 /**
 104  * gis_plugin_get_config:
 105  * @plugin: the plugin
 106  *
 107  * Each plugin can provide a configuration area. Applications using libgis
 108  * should display this configuration area to the user so they can modify the
 109  * behavior of the plugin.
 110  *
 111  * Returns: a configuration widget for the plugin
 112  */
 113 GtkWidget *gis_plugin_get_config(GisPlugin *plugin)
 114 {
 115         if (!GIS_IS_PLUGIN(plugin))
 116                 return NULL;
 117         GisPluginInterface *iface = GIS_PLUGIN_GET_INTERFACE(plugin);
 118         return iface->get_config ? iface->get_config(plugin) : NULL;
 119 }
 120
 121
 122 /***************
 123  * Plugins API *
 124  ***************/
 125 typedef struct {
 126         gchar *name;
 127         GisPlugin *plugin;
 128 } GisPluginStore;
 129
 130 /**
 131  * gis_plugins_new:
 132  * @dir:   the directory to search for plugins in
 133  * @prefs: a #GisPrefs to save the state of plugins, or NULL
 134  *
 135  * Create a new plugin source. If @prefs is not %NULL, the state of the plugins
 136  * will be saved when they are either enabled or disabled.
 137  *
 138  * Returns: the new plugin source
 139  */
 140 GisPlugins *gis_plugins_new(const gchar *dir, GisPrefs *prefs)
 141 {
 142         g_debug("GisPlugins: new - dir=%s", dir);
 143         GisPlugins *plugins = g_new0(GisPlugins, 1);
 144         plugins->prefs = prefs;
 145         if (dir)
 146                 plugins->dir = g_strdup(dir);
 147         return plugins;
 148 }
 149
 150 /**
 151  * gis_plugins_free:
 152  * @plugins: the #GisPlugins to free
 153  *
 154  * Free data used by a plugin source
 155  */
 156 void gis_plugins_free(GisPlugins *plugins)
 157 {
 158         g_debug("GisPlugins: free");
 159         for (GList *cur = plugins->plugins; cur; cur = cur->next) {
 160                 GisPluginStore *store = cur->data;
 161                 g_debug("GisPlugin: freeing %s refs=%d->%d", store->name,
 162                         G_OBJECT(store->plugin)->ref_count,
 163                         G_OBJECT(store->plugin)->ref_count-1);
 164                 g_object_unref(store->plugin);
 165                 g_free(store->name);
 166                 g_free(store);
 167         }
 168         g_list_free(plugins->plugins);
 169         if (plugins->dir)
 170                 g_free(plugins->dir);
 171         g_free(plugins);
 172 }
 173
 174 /**
 175  * gis_plugins_available:
 176  * @plugins: the plugin source
 177  *
 178  * Search the plugin directory for shared objects which can be loaded as
 179  * plugins.
 180  *
 181  * Returns: the list of available plugins
 182  */
 183 GList *gis_plugins_available(GisPlugins *plugins)
 184 {
 185         g_debug("GisPlugins: available");
 186         GList *list = NULL;
 187         gchar *dirs[] = {plugins->dir, PLUGINSDIR};
 188         g_debug("pluginsdir=%s", PLUGINSDIR);
 189         for (int i = 0; i<2; i++) {
 190                 if (dirs[i] == NULL)
 191                         continue;
 192                 GDir *dir = g_dir_open(dirs[i], 0, NULL);
 193                 if (dir == NULL)
 194                         continue;
 195                 g_debug("            checking %s", dirs[i]);
 196                 const gchar *name;
 197                 while ((name = g_dir_read_name(dir))) {
 198                         if (g_pattern_match_simple("*." G_MODULE_SUFFIX, name)) {
 199                                 gchar **parts = g_strsplit(name, ".", 2);
 200                                 list = g_list_prepend(list, g_strdup(parts[0]));
 201                                 g_strfreev(parts);
 202                         }
 203                 }
 204                 g_dir_close(dir);
 205         }
 206         list = g_list_sort(list, (GCompareFunc)strcmp);
 207         for (GList *cur = list; cur; cur = cur->next)
 208                 while (cur->next && g_str_equal(cur->data,cur->next->data)) {
 209                         GList *tmp = cur->next;
 210                         list = g_list_remove_link(list, cur);
 211                         cur = tmp;
 212                 }
 213         return list;
 214 }
 215
 216 /**
 217  * gis_plugins_load:
 218  * @plugins: the plugins source
 219  * @name:    the name of the plugin to load
 220  * @viewer:  a #GisViewer to pass to the plugins constructor
 221  * @prefs:   a #GisPrefs to pass to the plugins constructor
 222  *
 223  * @name should be the name of the shared object without the file extension.
 224  * This is the same as what is returned by gis_plugins_available().
 225  *
 226  * When loading plugins, the @prefs argument is used, not the #GisPrefs stored
 227  * in @plugins.
 228  *
 229  * Returns: the new plugin
 230  */
 231 GisPlugin *gis_plugins_load(GisPlugins *plugins, const char *name,
 232                 GisViewer *viewer, GisPrefs *prefs)
 233 {
 234         g_debug("GisPlugins: load %s", name);
 235         gchar *path = g_strdup_printf("%s/%s.%s", plugins->dir, name, G_MODULE_SUFFIX);
 236         g_debug("GisPlugins: load - trying %s", path);
 237         if (!g_file_test(path, G_FILE_TEST_EXISTS)) {
 238                 g_free(path);
 239                 path = g_strdup_printf("%s/%s.%s", PLUGINSDIR, name, G_MODULE_SUFFIX);
 240         }
 241         g_debug("GisPlugins: load - trying %s", path);
 242         if (!g_file_test(path, G_FILE_TEST_EXISTS)) {
 243                 g_warning("Module %s not found", name);
 244                 g_free(path);
 245                 return NULL;
 246         }
 247         GModule *module = g_module_open(path, G_MODULE_BIND_LAZY);
 248         g_free(path);
 249         if (module == NULL) {
 250                 g_warning("Unable to load module %s: %s", name, g_module_error());
 251                 return NULL;
 252         }
 253
 254         gpointer constructor_ptr; // GCC 4.1 fix?
 255         gchar *constructor_str = g_strconcat("gis_plugin_", name, "_new", NULL);
 256         if (!g_module_symbol(module, constructor_str, &constructor_ptr)) {
 257                 g_warning("Unable to load symbol %s from %s: %s",
 258                                 constructor_str, name, g_module_error());
 259                 g_module_close(module);
 260                 g_free(constructor_str);
 261                 return NULL;
 262         }
 263         g_free(constructor_str);
 264         GisPluginConstructor constructor = constructor_ptr;
 265
 266         GisPluginStore *store = g_new0(GisPluginStore, 1);
 267         store->name = g_strdup(name);
 268         store->plugin = constructor(viewer, prefs);
 269         plugins->plugins = g_list_prepend(plugins->plugins, store);
 270         return store->plugin;
 271 }
 272
 273 /**
 274  * gis_plugins_enable:
 275  * @plugins: the plugins source
 276  * @name:    the name of the plugin to load
 277  * @viewer:  a #GisViewer to pass to the plugins constructor
 278  * @prefs:   a #GisPrefs to pass to the plugins constructor
 279  *
 280  * Load a plugin and save it's loaded/unloaded state in the #GisPrefs stored in
 281  * #plugins.
 282  *
 283  * See also: gis_plugins_load()
 284  *
 285  * Returns: the new plugin
 286  */
 287 GisPlugin *gis_plugins_enable(GisPlugins *plugins, const char *name,
 288                 GisViewer *viewer, GisPrefs *prefs)
 289 {
 290         GisPlugin *plugin = gis_plugins_load(plugins, name, viewer, prefs);
 291         gis_prefs_set_boolean_v(plugins->prefs, "plugins", name, TRUE);
 292         return plugin;
 293 }
 294
 295 /**
 296  * gis_plugins_load_enabled:
 297  * @plugins: the plugins source
 298  * @viewer:  a #GisViewer to pass to the plugins constructor
 299  * @prefs:   a #GisPrefs to pass to the plugins constructor
 300  *
 301  * Load all enabled which have previously been enabled.
 302  *
 303  * See also: gis_plugins_load()
 304  *
 305  * Returns: a list of all loaded plugins
 306  */
 307 GList *gis_plugins_load_enabled(GisPlugins *plugins,
 308                 GisViewer *viewer, GisPrefs *prefs)
 309 {
 310         GList *loaded = NULL;
 311         for (GList *cur = gis_plugins_available(plugins); cur; cur = cur->next) {
 312                 gchar *name = cur->data;
 313                 if (gis_prefs_get_boolean_v(plugins->prefs, "plugins", name, NULL)) {
 314                         GisPlugin *plugin = gis_plugins_load(plugins, name, viewer, prefs);
 315                         loaded = g_list_prepend(loaded, plugin);
 316                 }
 317         }
 318         return loaded;
 319 }
 320
 321 /**
 322  * gis_plugins_unload:
 323  * @plugins: the plugins source
 324  * @name:    the name of the plugin to unload
 325  *
 326  * Unload a plugin and free any associated data.
 327  *
 328  * Returns: %FALSE
 329  */
 330 gboolean gis_plugins_unload(GisPlugins *plugins, const char *name)
 331 {
 332         g_debug("GisPlugins: unload %s", name);
 333         for (GList *cur = plugins->plugins; cur; cur = cur->next) {
 334                 GisPluginStore *store = cur->data;
 335                 if (g_str_equal(store->name, name)) {
 336                         g_object_unref(store->plugin);
 337                         g_free(store->name);
 338                         g_free(store);
 339                         plugins->plugins = g_list_delete_link(plugins->plugins, cur);
 340                 }
 341         }
 342         return FALSE;
 343 }
 344
 345 /**
 346  * gis_plugins_disable:
 347  * @plugins: the plugins source
 348  * @name:    the name of the plugin to unload
 349  *
 350  * Unload a plugin and save it's loaded/unloaded state in the #GisPrefs stored
 351  * in #plugins.
 352  *
 353  * See also: gis_plugins_unload()
 354  *
 355  * Returns: %FALSE
 356  */
 357 gboolean gis_plugins_disable(GisPlugins *plugins, const char *name)
 358 {
 359         gis_prefs_set_boolean_v(plugins->prefs, "plugins", name, FALSE);
 360         gis_plugins_unload(plugins, name);
 361         return FALSE;
 362 }
 363
 364 /**
 365  * gis_plugins_foreach:
 366  * @plugins:   the plugins source
 367  * @callback:  a function to call on each plugin
 368  * @user_data: user data to pass to the function
 369  *
 370  * Iterate over all plugins loaded by the plugins source
 371  */
 372 void gis_plugins_foreach(GisPlugins *plugins, GCallback _callback, gpointer user_data)
 373 {
 374         g_debug("GisPlugins: foreach");
 375         if (plugins == NULL)
 376                 return;
 377         typedef void (*CBFunc)(GisPlugin *, const gchar *, gpointer);
 378         CBFunc callback = (CBFunc)_callback;
 379         for (GList *cur = plugins->plugins; cur; cur = cur->next) {
 380                 GisPluginStore *store = cur->data;
 381                 callback(store->plugin, store->name, user_data);
 382         }
 383 }