gst/gstplugin.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstplugin.c: Plugin subsystem for loading elements, types, and libs
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 /**
  24  * SECTION:gstplugin
  25  * @short_description: Container for features loaded from a shared object module
  26  * @see_also: #GstPluginFeature, #GstElementFactory
  27  *
  28  * GStreamer is extensible, so #GstElement instances can be loaded at runtime.
  29  * A plugin system can provide one or more of the basic
  30  * <application>GStreamer</application> #GstPluginFeature subclasses.
  31  *
  32  * A plugin should export a symbol <symbol>gst_plugin_desc</symbol> that is a
  33  * struct of type #GstPluginDesc.
  34  * the plugin loader will check the version of the core library the plugin was
  35  * linked against and will create a new #GstPlugin. It will then call the
  36  * #GstPluginInitFunc function that was provided in the
  37  * <symbol>gst_plugin_desc</symbol>.
  38  *
  39  * Once you have a handle to a #GstPlugin (e.g. from the #GstRegistryPool), you
  40  * can add any object that subclasses #GstPluginFeature.
  41  *
  42  * Use gst_plugin_find_feature() and gst_plugin_get_feature_list() to find
  43  * features in a plugin.
  44  *
  45  * Usually plugins are always automaticlly loaded so you don't need to call
  46  * gst_plugin_load() explicitly to bring it into memory. There are options to
  47  * statically link plugins to an app or even use GStreamer without a plugin
  48  * repository in which case gst_plugin_load() can be needed to bring the plugin
  49  * into memory.
  50  */
  51
  52 #ifdef HAVE_CONFIG_H
  53 #include "config.h"
  54 #endif
  55 #include <glib/gstdio.h>
  56 #include <sys/types.h>
  57 #ifdef HAVE_DIRENT_H
  58 #include <dirent.h>
  59 #endif
  60 #ifdef HAVE_UNISTD_H
  61 #include <unistd.h>
  62 #endif
  63 #include <signal.h>
  64 #include <errno.h>
  65
  66 #include "gst_private.h"
  67 #include "glib-compat-private.h"
  68
  69 #include <gst/gst.h>
  70
  71 #define GST_CAT_DEFAULT GST_CAT_PLUGIN_LOADING
  72
  73 static GList *_gst_plugin_static = NULL;
  74 static gboolean _gst_plugin_inited;
  75
  76 /* static variables for segfault handling of plugin loading */
  77 static char *_gst_plugin_fault_handler_filename = NULL;
  78
  79 #ifndef HAVE_WIN32
  80 static gboolean _gst_plugin_fault_handler_is_setup = FALSE;
  81 #endif
  82
  83 /* list of valid licenses.
  84  * One of these must be specified or the plugin won't be loaded
  85  * Contact gstreamer-devel@lists.sourceforge.net if your license should be
  86  * added.
  87  *
  88  * GPL: http://www.gnu.org/copyleft/gpl.html
  89  * LGPL: http://www.gnu.org/copyleft/lesser.html
  90  * QPL: http://www.trolltech.com/licenses/qpl.html
  91  * MPL: http://www.opensource.org/licenses/mozilla1.1.php
  92  * MIT/X11: http://www.opensource.org/licenses/mit-license.php
  93  * 3-clause BSD: http://www.opensource.org/licenses/bsd-license.php
  94  */
  95 static const gchar *valid_licenses[] = {
  96   "LGPL",                       /* GNU Lesser General Public License */
  97   "GPL",                        /* GNU General Public License */
  98   "QPL",                        /* Trolltech Qt Public License */
  99   "GPL/QPL",                    /* Combi-license of GPL + QPL */
 100   "MPL",                        /* MPL 1.1 license */
 101   "BSD",                        /* 3-clause BSD license */
 102   "MIT/X11",                    /* MIT/X11 license */
 103   "Proprietary",                /* Proprietary license */
 104   GST_LICENSE_UNKNOWN,          /* some other license */
 105   NULL
 106 };
 107
 108 static GstPlugin *gst_plugin_register_func (GstPlugin * plugin,
 109     const GstPluginDesc * desc);
 110 static void gst_plugin_desc_copy (GstPluginDesc * dest,
 111     const GstPluginDesc * src);
 112 static void gst_plugin_desc_free (GstPluginDesc * desc);
 113
 114
 115 G_DEFINE_TYPE (GstPlugin, gst_plugin, GST_TYPE_OBJECT);
 116
 117 static void
 118 gst_plugin_init (GstPlugin * plugin)
 119 {
 120   /* do nothing, needed because of G_DEFINE_TYPE */
 121 }
 122
 123 static void
 124 gst_plugin_finalize (GObject * object)
 125 {
 126   GstPlugin *plugin = GST_PLUGIN_CAST (object);
 127   GstRegistry *registry = gst_registry_get_default ();
 128   GList *g;
 129
 130   GST_DEBUG ("finalizing plugin %p", plugin);
 131   for (g = registry->plugins; g; g = g->next) {
 132     if (g->data == (gpointer) plugin) {
 133       g_warning ("removing plugin that is still in registry");
 134     }
 135   }
 136   g_free (plugin->filename);
 137   g_free (plugin->basename);
 138   gst_plugin_desc_free (&plugin->desc);
 139
 140   G_OBJECT_CLASS (gst_plugin_parent_class)->finalize (object);
 141 }
 142
 143 static void
 144 gst_plugin_class_init (GstPluginClass * klass)
 145 {
 146   G_OBJECT_CLASS (klass)->finalize = GST_DEBUG_FUNCPTR (gst_plugin_finalize);
 147 }
 148
 149 GQuark
 150 gst_plugin_error_quark (void)
 151 {
 152   static GQuark quark = 0;
 153
 154   if (!quark)
 155     quark = g_quark_from_static_string ("gst_plugin_error");
 156   return quark;
 157 }
 158
 159 #ifndef GST_REMOVE_DEPRECATED
 160 /* this function can be called in the GCC constructor extension, before
 161  * the _gst_plugin_initialize() was called. In that case, we store the
 162  * plugin description in a list to initialize it when we open the main
 163  * module later on.
 164  * When the main module is known, we can register the plugin right away.
 165  */
 166 void
 167 _gst_plugin_register_static (GstPluginDesc * desc)
 168 {
 169   g_return_if_fail (desc != NULL);
 170
 171   if (!_gst_plugin_inited) {
 172     /* Must call g_thread_init() before calling GLib functions such as
 173      * g_list_prepend() ... */
 174     if (!g_thread_supported ())
 175       g_thread_init (NULL);
 176
 177     if (GST_CAT_DEFAULT)
 178       GST_LOG ("queueing static plugin \"%s\" for loading later on",
 179           desc->name);
 180     _gst_plugin_static = g_list_prepend (_gst_plugin_static, desc);
 181   } else {
 182     gst_plugin_register_static (desc);
 183   }
 184 }
 185 #endif
 186
 187 /**
 188  * gst_plugin_register_static:
 189  * @desc: a #GstPluginDesc describing the plugin.
 190  *
 191  * Registers a static plugin, ie. a plugin which is private to an application
 192  * or library and contained within the application or library (as opposed to
 193  * being shipped as a separate module file).
 194  *
 195  * You must make sure that GStreamer has been initialised (with gst_init() or
 196  * via gst_init_get_option_group()) before calling this function.
 197  *
 198  * Returns: TRUE if the plugin was registered correctly, otherwise FALSE.
 199  *
 200  * Since: 0.10.16
 201  */
 202 gboolean
 203 gst_plugin_register_static (const GstPluginDesc * desc)
 204 {
 205   GstPlugin *plugin;
 206   gboolean res = FALSE;
 207
 208   g_return_val_if_fail (desc != NULL, FALSE);
 209
 210   /* make sure gst_init() has been called */
 211   g_return_val_if_fail (_gst_plugin_inited != FALSE, FALSE);
 212
 213   GST_LOG ("attempting to load static plugin \"%s\" now...", desc->name);
 214   plugin = g_object_new (GST_TYPE_PLUGIN, NULL);
 215   if (gst_plugin_register_func (plugin, desc) != NULL) {
 216     GST_INFO ("loaded static plugin \"%s\"", desc->name);
 217     res = gst_default_registry_add_plugin (plugin);
 218   }
 219   return res;
 220 }
 221
 222 void
 223 _gst_plugin_initialize (void)
 224 {
 225   _gst_plugin_inited = TRUE;
 226
 227   /* now register all static plugins */
 228   g_list_foreach (_gst_plugin_static, (GFunc) gst_plugin_register_static, NULL);
 229 }
 230
 231 /* this function could be extended to check if the plugin license matches the
 232  * applications license (would require the app to register its license somehow).
 233  * We'll wait for someone who's interested in it to code it :)
 234  */
 235 static gboolean
 236 gst_plugin_check_license (const gchar * license)
 237 {
 238   const gchar **check_license = valid_licenses;
 239
 240   g_assert (check_license);
 241
 242   while (*check_license) {
 243     if (strcmp (license, *check_license) == 0)
 244       return TRUE;
 245     check_license++;
 246   }
 247   return FALSE;
 248 }
 249
 250 static gboolean
 251 gst_plugin_check_version (gint major, gint minor)
 252 {
 253   /* return NULL if the major and minor version numbers are not compatible */
 254   /* with ours. */
 255   if (major != GST_VERSION_MAJOR || minor != GST_VERSION_MINOR)
 256     return FALSE;
 257
 258   return TRUE;
 259 }
 260
 261 static GstPlugin *
 262 gst_plugin_register_func (GstPlugin * plugin, const GstPluginDesc * desc)
 263 {
 264   if (!gst_plugin_check_version (desc->major_version, desc->minor_version)) {
 265     if (GST_CAT_DEFAULT)
 266       GST_WARNING ("plugin \"%s\" has incompatible version, not loading",
 267           plugin->filename);
 268     return NULL;
 269   }
 270
 271   if (!desc->license || !desc->description || !desc->source ||
 272       !desc->package || !desc->origin) {
 273     if (GST_CAT_DEFAULT)
 274       GST_WARNING ("plugin \"%s\" has incorrect GstPluginDesc, not loading",
 275           plugin->filename);
 276     return NULL;
 277   }
 278
 279   if (!gst_plugin_check_license (desc->license)) {
 280     if (GST_CAT_DEFAULT)
 281       GST_WARNING ("plugin \"%s\" has invalid license \"%s\", not loading",
 282           plugin->filename, desc->license);
 283     return NULL;
 284   }
 285
 286   if (GST_CAT_DEFAULT)
 287     GST_LOG ("plugin \"%s\" looks good", GST_STR_NULL (plugin->filename));
 288
 289   gst_plugin_desc_copy (&plugin->desc, desc);
 290
 291   if (!((desc->plugin_init) (plugin))) {
 292     if (GST_CAT_DEFAULT)
 293       GST_WARNING ("plugin \"%s\" failed to initialise", plugin->filename);
 294     plugin->module = NULL;
 295     return NULL;
 296   }
 297
 298   if (GST_CAT_DEFAULT)
 299     GST_LOG ("plugin \"%s\" initialised", GST_STR_NULL (plugin->filename));
 300
 301   return plugin;
 302 }
 303
 304 #ifdef HAVE_SIGACTION
 305 static struct sigaction oldaction;
 306
 307 /*
 308  * _gst_plugin_fault_handler_restore:
 309  * segfault handler restorer
 310  */
 311 static void
 312 _gst_plugin_fault_handler_restore (void)
 313 {
 314   if (!_gst_plugin_fault_handler_is_setup)
 315     return;
 316
 317   _gst_plugin_fault_handler_is_setup = FALSE;
 318
 319   sigaction (SIGSEGV, &oldaction, NULL);
 320 }
 321
 322 /*
 323  * _gst_plugin_fault_handler_sighandler:
 324  * segfault handler implementation
 325  */
 326 static void
 327 _gst_plugin_fault_handler_sighandler (int signum)
 328 {
 329   /* We need to restore the fault handler or we'll keep getting it */
 330   _gst_plugin_fault_handler_restore ();
 331
 332   switch (signum) {
 333     case SIGSEGV:
 334       g_print ("\nERROR: ");
 335       g_print ("Caught a segmentation fault while loading plugin file:\n");
 336       g_print ("%s\n\n", _gst_plugin_fault_handler_filename);
 337       g_print ("Please either:\n");
 338       g_print ("- remove it and restart.\n");
 339       g_print ("- run with --gst-disable-segtrap and debug.\n");
 340       exit (-1);
 341       break;
 342     default:
 343       g_print ("Caught unhandled signal on plugin loading\n");
 344       break;
 345   }
 346 }
 347
 348 /*
 349  * _gst_plugin_fault_handler_setup:
 350  * sets up the segfault handler
 351  */
 352 static void
 353 _gst_plugin_fault_handler_setup (void)
 354 {
 355   struct sigaction action;
 356
 357   /* if asked to leave segfaults alone, just return */
 358   if (!gst_segtrap_is_enabled ())
 359     return;
 360
 361   if (_gst_plugin_fault_handler_is_setup)
 362     return;
 363
 364   _gst_plugin_fault_handler_is_setup = TRUE;
 365
 366   memset (&action, 0, sizeof (action));
 367   action.sa_handler = _gst_plugin_fault_handler_sighandler;
 368
 369   sigaction (SIGSEGV, &action, &oldaction);
 370 }
 371 #else
 372 static void
 373 _gst_plugin_fault_handler_restore (void)
 374 {
 375 }
 376
 377 static void
 378 _gst_plugin_fault_handler_setup (void)
 379 {
 380 }
 381 #endif
 382
 383 static void _gst_plugin_fault_handler_setup ();
 384
 385 static GStaticMutex gst_plugin_loading_mutex = G_STATIC_MUTEX_INIT;
 386
 387 /**
 388  * gst_plugin_load_file:
 389  * @filename: the plugin filename to load
 390  * @error: pointer to a NULL-valued GError
 391  *
 392  * Loads the given plugin and refs it.  Caller needs to unref after use.
 393  *
 394  * Returns: a reference to the existing loaded GstPlugin, a reference to the
 395  * newly-loaded GstPlugin, or NULL if an error occurred.
 396  */
 397 GstPlugin *
 398 gst_plugin_load_file (const gchar * filename, GError ** error)
 399 {
 400   GstPlugin *plugin;
 401   GModule *module;
 402   gboolean ret;
 403   gpointer ptr;
 404   struct stat file_status;
 405   GstRegistry *registry;
 406
 407   g_return_val_if_fail (filename != NULL, NULL);
 408
 409   registry = gst_registry_get_default ();
 410   g_static_mutex_lock (&gst_plugin_loading_mutex);
 411
 412   plugin = gst_registry_lookup (registry, filename);
 413   if (plugin) {
 414     if (plugin->module) {
 415       g_static_mutex_unlock (&gst_plugin_loading_mutex);
 416       return plugin;
 417     } else {
 418       gst_object_unref (plugin);
 419       plugin = NULL;
 420     }
 421   }
 422
 423   GST_CAT_DEBUG (GST_CAT_PLUGIN_LOADING, "attempt to load plugin \"%s\"",
 424       filename);
 425
 426   if (g_module_supported () == FALSE) {
 427     GST_CAT_DEBUG (GST_CAT_PLUGIN_LOADING, "module loading not supported");
 428     g_set_error (error,
 429         GST_PLUGIN_ERROR,
 430         GST_PLUGIN_ERROR_MODULE, "Dynamic loading not supported");
 431     goto return_error;
 432   }
 433
 434   if (g_stat (filename, &file_status)) {
 435     GST_CAT_DEBUG (GST_CAT_PLUGIN_LOADING, "problem accessing file");
 436     g_set_error (error,
 437         GST_PLUGIN_ERROR,
 438         GST_PLUGIN_ERROR_MODULE, "Problem accessing file %s: %s", filename,
 439         g_strerror (errno));
 440     goto return_error;
 441   }
 442
 443   module = g_module_open (filename, G_MODULE_BIND_LOCAL);
 444   if (module == NULL) {
 445     GST_CAT_WARNING (GST_CAT_PLUGIN_LOADING, "module_open failed: %s",
 446         g_module_error ());
 447     g_set_error (error,
 448         GST_PLUGIN_ERROR, GST_PLUGIN_ERROR_MODULE, "Opening module failed: %s",
 449         g_module_error ());
 450     /* If we failed to open the shared object, then it's probably because a
 451      * plugin is linked against the wrong libraries. Print out an easy-to-see
 452      * message in this case. */
 453     g_warning ("Failed to load plugin '%s': %s", filename, g_module_error ());
 454     goto return_error;
 455   }
 456
 457   plugin = g_object_new (GST_TYPE_PLUGIN, NULL);
 458
 459   plugin->module = module;
 460   plugin->filename = g_strdup (filename);
 461   plugin->basename = g_path_get_basename (filename);
 462   plugin->file_mtime = file_status.st_mtime;
 463   plugin->file_size = file_status.st_size;
 464
 465   ret = g_module_symbol (module, "gst_plugin_desc", &ptr);
 466   if (!ret) {
 467     GST_DEBUG ("Could not find plugin entry point in \"%s\"", filename);
 468     g_set_error (error,
 469         GST_PLUGIN_ERROR,
 470         GST_PLUGIN_ERROR_MODULE,
 471         "File \"%s\" is not a GStreamer plugin", filename);
 472     g_module_close (module);
 473     goto return_error;
 474   }
 475   plugin->orig_desc = (GstPluginDesc *) ptr;
 476
 477   GST_LOG ("Plugin %p for file \"%s\" prepared, calling entry function...",
 478       plugin, filename);
 479
 480   /* this is where we load the actual .so, so let's trap SIGSEGV */
 481   _gst_plugin_fault_handler_setup ();
 482   _gst_plugin_fault_handler_filename = plugin->filename;
 483
 484   GST_LOG ("Plugin %p for file \"%s\" prepared, registering...",
 485       plugin, filename);
 486
 487   if (!gst_plugin_register_func (plugin, plugin->orig_desc)) {
 488     /* remove signal handler */
 489     _gst_plugin_fault_handler_restore ();
 490     GST_DEBUG ("gst_plugin_register_func failed for plugin \"%s\"", filename);
 491     /* plugin == NULL */
 492     g_set_error (error,
 493         GST_PLUGIN_ERROR,
 494         GST_PLUGIN_ERROR_MODULE,
 495         "File \"%s\" appears to be a GStreamer plugin, but it failed to initialize",
 496         filename);
 497     g_module_close (module);
 498     goto return_error;
 499   }
 500
 501   /* remove signal handler */
 502   _gst_plugin_fault_handler_restore ();
 503   _gst_plugin_fault_handler_filename = NULL;
 504   GST_INFO ("plugin \"%s\" loaded", plugin->filename);
 505
 506   gst_object_ref (plugin);
 507   gst_default_registry_add_plugin (plugin);
 508
 509   g_static_mutex_unlock (&gst_plugin_loading_mutex);
 510   return plugin;
 511
 512 return_error:
 513   {
 514     if (plugin)
 515       gst_object_unref (plugin);
 516     g_static_mutex_unlock (&gst_plugin_loading_mutex);
 517     return NULL;
 518   }
 519 }
 520
 521 static void
 522 gst_plugin_desc_copy (GstPluginDesc * dest, const GstPluginDesc * src)
 523 {
 524   dest->major_version = src->major_version;
 525   dest->minor_version = src->minor_version;
 526   dest->name = g_intern_string (src->name);
 527   /* maybe intern the description too, just for convenience? */
 528   dest->description = g_strdup (src->description);
 529   dest->plugin_init = src->plugin_init;
 530   dest->version = g_intern_string (src->version);
 531   dest->license = g_intern_string (src->license);
 532   dest->source = g_intern_string (src->source);
 533   dest->package = g_intern_string (src->package);
 534   dest->origin = g_intern_string (src->origin);
 535 }
 536
 537 /* unused */
 538 static void
 539 gst_plugin_desc_free (GstPluginDesc * desc)
 540 {
 541   g_free (desc->description);
 542   memset (desc, 0, sizeof (GstPluginDesc));
 543 }
 544
 545 /**
 546  * gst_plugin_get_name:
 547  * @plugin: plugin to get the name of
 548  *
 549  * Get the short name of the plugin
 550  *
 551  * Returns: the name of the plugin
 552  */
 553 const gchar *
 554 gst_plugin_get_name (GstPlugin * plugin)
 555 {
 556   g_return_val_if_fail (plugin != NULL, NULL);
 557
 558   return plugin->desc.name;
 559 }
 560
 561 /**
 562  * gst_plugin_get_description:
 563  * @plugin: plugin to get long name of
 564  *
 565  * Get the long descriptive name of the plugin
 566  *
 567  * Returns: the long name of the plugin
 568  */
 569 G_CONST_RETURN gchar *
 570 gst_plugin_get_description (GstPlugin * plugin)
 571 {
 572   g_return_val_if_fail (plugin != NULL, NULL);
 573
 574   return plugin->desc.description;
 575 }
 576
 577 /**
 578  * gst_plugin_get_filename:
 579  * @plugin: plugin to get the filename of
 580  *
 581  * get the filename of the plugin
 582  *
 583  * Returns: the filename of the plugin
 584  */
 585 G_CONST_RETURN gchar *
 586 gst_plugin_get_filename (GstPlugin * plugin)
 587 {
 588   g_return_val_if_fail (plugin != NULL, NULL);
 589
 590   return plugin->filename;
 591 }
 592
 593 /**
 594  * gst_plugin_get_version:
 595  * @plugin: plugin to get the version of
 596  *
 597  * get the version of the plugin
 598  *
 599  * Returns: the version of the plugin
 600  */
 601 G_CONST_RETURN gchar *
 602 gst_plugin_get_version (GstPlugin * plugin)
 603 {
 604   g_return_val_if_fail (plugin != NULL, NULL);
 605
 606   return plugin->desc.version;
 607 }
 608
 609 /**
 610  * gst_plugin_get_license:
 611  * @plugin: plugin to get the license of
 612  *
 613  * get the license of the plugin
 614  *
 615  * Returns: the license of the plugin
 616  */
 617 G_CONST_RETURN gchar *
 618 gst_plugin_get_license (GstPlugin * plugin)
 619 {
 620   g_return_val_if_fail (plugin != NULL, NULL);
 621
 622   return plugin->desc.license;
 623 }
 624
 625 /**
 626  * gst_plugin_get_source:
 627  * @plugin: plugin to get the source of
 628  *
 629  * get the source module the plugin belongs to.
 630  *
 631  * Returns: the source of the plugin
 632  */
 633 G_CONST_RETURN gchar *
 634 gst_plugin_get_source (GstPlugin * plugin)
 635 {
 636   g_return_val_if_fail (plugin != NULL, NULL);
 637
 638   return plugin->desc.source;
 639 }
 640
 641 /**
 642  * gst_plugin_get_package:
 643  * @plugin: plugin to get the package of
 644  *
 645  * get the package the plugin belongs to.
 646  *
 647  * Returns: the package of the plugin
 648  */
 649 G_CONST_RETURN gchar *
 650 gst_plugin_get_package (GstPlugin * plugin)
 651 {
 652   g_return_val_if_fail (plugin != NULL, NULL);
 653
 654   return plugin->desc.package;
 655 }
 656
 657 /**
 658  * gst_plugin_get_origin:
 659  * @plugin: plugin to get the origin of
 660  *
 661  * get the URL where the plugin comes from
 662  *
 663  * Returns: the origin of the plugin
 664  */
 665 G_CONST_RETURN gchar *
 666 gst_plugin_get_origin (GstPlugin * plugin)
 667 {
 668   g_return_val_if_fail (plugin != NULL, NULL);
 669
 670   return plugin->desc.origin;
 671 }
 672
 673 /**
 674  * gst_plugin_get_module:
 675  * @plugin: plugin to query
 676  *
 677  * Gets the #GModule of the plugin. If the plugin isn't loaded yet, NULL is
 678  * returned.
 679  *
 680  * Returns: module belonging to the plugin or NULL if the plugin isn't
 681  *          loaded yet.
 682  */
 683 GModule *
 684 gst_plugin_get_module (GstPlugin * plugin)
 685 {
 686   g_return_val_if_fail (plugin != NULL, NULL);
 687
 688   return plugin->module;
 689 }
 690
 691 /**
 692  * gst_plugin_is_loaded:
 693  * @plugin: plugin to query
 694  *
 695  * queries if the plugin is loaded into memory
 696  *
 697  * Returns: TRUE is loaded, FALSE otherwise
 698  */
 699 gboolean
 700 gst_plugin_is_loaded (GstPlugin * plugin)
 701 {
 702   g_return_val_if_fail (plugin != NULL, FALSE);
 703
 704   return (plugin->module != NULL || plugin->filename == NULL);
 705 }
 706
 707 #if 0
 708 /**
 709  * gst_plugin_feature_list:
 710  * @plugin: plugin to query
 711  * @filter: the filter to use
 712  * @first: only return first match
 713  * @user_data: user data passed to the filter function
 714  *
 715  * Runs a filter against all plugin features and returns a GList with
 716  * the results. If the first flag is set, only the first match is
 717  * returned (as a list with a single object).
 718  *
 719  * Returns: a GList of features, g_list_free after use.
 720  */
 721 GList *
 722 gst_plugin_feature_filter (GstPlugin * plugin,
 723     GstPluginFeatureFilter filter, gboolean first, gpointer user_data)
 724 {
 725   GList *list;
 726   GList *g;
 727
 728   list = gst_filter_run (plugin->features, (GstFilterFunc) filter, first,
 729       user_data);
 730   for (g = list; g; g = g->next) {
 731     gst_object_ref (plugin);
 732   }
 733
 734   return list;
 735 }
 736
 737 typedef struct
 738 {
 739   GstPluginFeatureFilter filter;
 740   gboolean first;
 741   gpointer user_data;
 742   GList *result;
 743 }
 744 FeatureFilterData;
 745
 746 static gboolean
 747 _feature_filter (GstPlugin * plugin, gpointer user_data)
 748 {
 749   GList *result;
 750   FeatureFilterData *data = (FeatureFilterData *) user_data;
 751
 752   result = gst_plugin_feature_filter (plugin, data->filter, data->first,
 753       data->user_data);
 754   if (result) {
 755     data->result = g_list_concat (data->result, result);
 756     return TRUE;
 757   }
 758   return FALSE;
 759 }
 760
 761 /**
 762  * gst_plugin_list_feature_filter:
 763  * @list: a #GList of plugins to query
 764  * @filter: the filter function to use
 765  * @first: only return first match
 766  * @user_data: user data passed to the filter function
 767  *
 768  * Runs a filter against all plugin features of the plugins in the given
 769  * list and returns a GList with the results.
 770  * If the first flag is set, only the first match is
 771  * returned (as a list with a single object).
 772  *
 773  * Returns: a GList of features, g_list_free after use.
 774  */
 775 GList *
 776 gst_plugin_list_feature_filter (GList * list,
 777     GstPluginFeatureFilter filter, gboolean first, gpointer user_data)
 778 {
 779   FeatureFilterData data;
 780   GList *result;
 781
 782   data.filter = filter;
 783   data.first = first;
 784   data.user_data = user_data;
 785   data.result = NULL;
 786
 787   result = gst_filter_run (list, (GstFilterFunc) _feature_filter, first, &data);
 788   g_list_free (result);
 789
 790   return data.result;
 791 }
 792 #endif
 793
 794 /**
 795  * gst_plugin_name_filter:
 796  * @plugin: the plugin to check
 797  * @name: the name of the plugin
 798  *
 799  * A standard filter that returns TRUE when the plugin is of the
 800  * given name.
 801  *
 802  * Returns: TRUE if the plugin is of the given name.
 803  */
 804 gboolean
 805 gst_plugin_name_filter (GstPlugin * plugin, const gchar * name)
 806 {
 807   return (plugin->desc.name && !strcmp (plugin->desc.name, name));
 808 }
 809
 810 #if 0
 811 /**
 812  * gst_plugin_find_feature:
 813  * @plugin: plugin to get the feature from
 814  * @name: The name of the feature to find
 815  * @type: The type of the feature to find
 816  *
 817  * Find a feature of the given name and type in the given plugin.
 818  *
 819  * Returns: a GstPluginFeature or NULL if the feature was not found.
 820  */
 821 GstPluginFeature *
 822 gst_plugin_find_feature (GstPlugin * plugin, const gchar * name, GType type)
 823 {
 824   GList *walk;
 825   GstPluginFeature *result = NULL;
 826   GstTypeNameData data;
 827
 828   g_return_val_if_fail (name != NULL, NULL);
 829
 830   data.type = type;
 831   data.name = name;
 832
 833   walk = gst_filter_run (plugin->features,
 834       (GstFilterFunc) gst_plugin_feature_type_name_filter, TRUE, &data);
 835
 836   if (walk) {
 837     result = GST_PLUGIN_FEATURE (walk->data);
 838
 839     gst_object_ref (result);
 840     gst_plugin_feature_list_free (walk);
 841   }
 842
 843   return result;
 844 }
 845 #endif
 846
 847 #if 0
 848 static gboolean
 849 gst_plugin_feature_name_filter (GstPluginFeature * feature, const gchar * name)
 850 {
 851   return !strcmp (name, GST_PLUGIN_FEATURE_NAME (feature));
 852 }
 853 #endif
 854
 855 #if 0
 856 /**
 857  * gst_plugin_find_feature_by_name:
 858  * @plugin: plugin to get the feature from
 859  * @name: The name of the feature to find
 860  *
 861  * Find a feature of the given name in the given plugin.
 862  *
 863  * Returns: a GstPluginFeature or NULL if the feature was not found.
 864  */
 865 GstPluginFeature *
 866 gst_plugin_find_feature_by_name (GstPlugin * plugin, const gchar * name)
 867 {
 868   GList *walk;
 869   GstPluginFeature *result = NULL;
 870
 871   g_return_val_if_fail (name != NULL, NULL);
 872
 873   walk = gst_filter_run (plugin->features,
 874       (GstFilterFunc) gst_plugin_feature_name_filter, TRUE, (void *) name);
 875
 876   if (walk) {
 877     result = GST_PLUGIN_FEATURE (walk->data);
 878
 879     gst_object_ref (result);
 880     gst_plugin_feature_list_free (walk);
 881   }
 882
 883   return result;
 884 }
 885 #endif
 886
 887 /**
 888  * gst_plugin_load_by_name:
 889  * @name: name of plugin to load
 890  *
 891  * Load the named plugin. Refs the plugin.
 892  *
 893  * Returns: A reference to a loaded plugin, or NULL on error.
 894  */
 895 GstPlugin *
 896 gst_plugin_load_by_name (const gchar * name)
 897 {
 898   GstPlugin *plugin, *newplugin;
 899   GError *error = NULL;
 900
 901   GST_DEBUG ("looking up plugin %s in default registry", name);
 902   plugin = gst_registry_find_plugin (gst_registry_get_default (), name);
 903   if (plugin) {
 904     GST_DEBUG ("loading plugin %s from file %s", name, plugin->filename);
 905     newplugin = gst_plugin_load_file (plugin->filename, &error);
 906     gst_object_unref (plugin);
 907
 908     if (!newplugin) {
 909       GST_WARNING ("load_plugin error: %s", error->message);
 910       g_error_free (error);
 911       return NULL;
 912     }
 913     /* newplugin was reffed by load_file */
 914     return newplugin;
 915   }
 916
 917   GST_DEBUG ("Could not find plugin %s in registry", name);
 918   return NULL;
 919 }
 920
 921 /**
 922  * gst_plugin_load:
 923  * @plugin: plugin to load
 924  *
 925  * Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is
 926  * untouched. The normal use pattern of this function goes like this:
 927  *
 928  * <programlisting>
 929  * GstPlugin *loaded_plugin;
 930  * loaded_plugin = gst_plugin_load (plugin);
 931  * // presumably, we're no longer interested in the potentially-unloaded plugin
 932  * gst_object_unref (plugin);
 933  * plugin = loaded_plugin;
 934  * </programlisting>
 935  *
 936  * Returns: A reference to a loaded plugin, or NULL on error.
 937  */
 938 GstPlugin *
 939 gst_plugin_load (GstPlugin * plugin)
 940 {
 941   GError *error = NULL;
 942   GstPlugin *newplugin;
 943
 944   if (gst_plugin_is_loaded (plugin)) {
 945     return plugin;
 946   }
 947
 948   if (!(newplugin = gst_plugin_load_file (plugin->filename, &error)))
 949     goto load_error;
 950
 951   return newplugin;
 952
 953 load_error:
 954   {
 955     GST_WARNING ("load_plugin error: %s", error->message);
 956     g_error_free (error);
 957     return NULL;
 958   }
 959 }
 960
 961 /**
 962  * gst_plugin_list_free:
 963  * @list: list of #GstPlugin
 964  *
 965  * Unrefs each member of @list, then frees the list.
 966  */
 967 void
 968 gst_plugin_list_free (GList * list)
 969 {
 970   GList *g;
 971
 972   for (g = list; g; g = g->next) {
 973     gst_object_unref (GST_PLUGIN_CAST (g->data));
 974   }
 975   g_list_free (list);
 976 }