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     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 /* this function can be called in the GCC constructor extension, before
 160  * the _gst_plugin_initialize() was called. In that case, we store the
 161  * plugin description in a list to initialize it when we open the main
 162  * module later on.
 163  * When the main module is known, we can register the plugin right away.
 164  */
 165 void
 166 _gst_plugin_register_static (GstPluginDesc * desc)
 167 {
 168   if (!_gst_plugin_inited) {
 169     if (GST_CAT_DEFAULT)
 170       GST_LOG ("queueing static plugin \"%s\" for loading later on",
 171           desc->name);
 172     _gst_plugin_static = g_list_prepend (_gst_plugin_static, desc);
 173   } else {
 174     GstPlugin *plugin;
 175
 176     if (GST_CAT_DEFAULT)
 177       GST_LOG ("attempting to load static plugin \"%s\" now...", desc->name);
 178     plugin = g_object_new (GST_TYPE_PLUGIN, NULL);
 179     if (gst_plugin_register_func (plugin, desc)) {
 180       if (GST_CAT_DEFAULT)
 181         GST_INFO ("loaded static plugin \"%s\"", desc->name);
 182       gst_default_registry_add_plugin (plugin);
 183     }
 184   }
 185 }
 186
 187 void
 188 _gst_plugin_initialize (void)
 189 {
 190   _gst_plugin_inited = TRUE;
 191
 192   /* now register all static plugins */
 193   g_list_foreach (_gst_plugin_static, (GFunc) _gst_plugin_register_static,
 194       NULL);
 195 }
 196
 197 /* this function could be extended to check if the plugin license matches the
 198  * applications license (would require the app to register its license somehow).
 199  * We'll wait for someone who's interested in it to code it :)
 200  */
 201 static gboolean
 202 gst_plugin_check_license (const gchar * license)
 203 {
 204   const gchar **check_license = valid_licenses;
 205
 206   g_assert (check_license);
 207
 208   while (*check_license) {
 209     if (strcmp (license, *check_license) == 0)
 210       return TRUE;
 211     check_license++;
 212   }
 213   return FALSE;
 214 }
 215
 216 static gboolean
 217 gst_plugin_check_version (gint major, gint minor)
 218 {
 219   /* return NULL if the major and minor version numbers are not compatible */
 220   /* with ours. */
 221   if (major != GST_VERSION_MAJOR || minor != GST_VERSION_MINOR)
 222     return FALSE;
 223
 224   return TRUE;
 225 }
 226
 227 static GstPlugin *
 228 gst_plugin_register_func (GstPlugin * plugin, GstPluginDesc * desc)
 229 {
 230   if (!gst_plugin_check_version (desc->major_version, desc->minor_version)) {
 231     if (GST_CAT_DEFAULT)
 232       GST_WARNING ("plugin \"%s\" has incompatible version, not loading",
 233           plugin->filename);
 234     return NULL;
 235   }
 236
 237   if (!desc->license || !desc->description || !desc->source ||
 238       !desc->package || !desc->origin) {
 239     if (GST_CAT_DEFAULT)
 240       GST_WARNING ("plugin \"%s\" has incorrect GstPluginDesc, not loading",
 241           plugin->filename);
 242     return NULL;
 243   }
 244
 245   if (!gst_plugin_check_license (desc->license)) {
 246     if (GST_CAT_DEFAULT)
 247       GST_WARNING ("plugin \"%s\" has invalid license \"%s\", not loading",
 248           plugin->filename, desc->license);
 249     return NULL;
 250   }
 251
 252   if (GST_CAT_DEFAULT)
 253     GST_LOG ("plugin \"%s\" looks good", GST_STR_NULL (plugin->filename));
 254
 255   gst_plugin_desc_copy (&plugin->desc, desc);
 256
 257   if (!((desc->plugin_init) (plugin))) {
 258     if (GST_CAT_DEFAULT)
 259       GST_WARNING ("plugin \"%s\" failed to initialise", plugin->filename);
 260     plugin->module = NULL;
 261     return NULL;
 262   }
 263
 264   if (GST_CAT_DEFAULT)
 265     GST_LOG ("plugin \"%s\" initialised", GST_STR_NULL (plugin->filename));
 266
 267   return plugin;
 268 }
 269
 270 #ifdef HAVE_SIGACTION
 271 static struct sigaction oldaction;
 272
 273 /*
 274  * _gst_plugin_fault_handler_restore:
 275  * segfault handler restorer
 276  */
 277 static void
 278 _gst_plugin_fault_handler_restore (void)
 279 {
 280   if (!_gst_plugin_fault_handler_is_setup)
 281     return;
 282
 283   _gst_plugin_fault_handler_is_setup = FALSE;
 284
 285   sigaction (SIGSEGV, &oldaction, NULL);
 286 }
 287
 288 /*
 289  * _gst_plugin_fault_handler_sighandler:
 290  * segfault handler implementation
 291  */
 292 static void
 293 _gst_plugin_fault_handler_sighandler (int signum)
 294 {
 295   /* We need to restore the fault handler or we'll keep getting it */
 296   _gst_plugin_fault_handler_restore ();
 297
 298   switch (signum) {
 299     case SIGSEGV:
 300       g_print ("\nERROR: ");
 301       g_print ("Caught a segmentation fault while loading plugin file:\n");
 302       g_print ("%s\n\n", _gst_plugin_fault_handler_filename);
 303       g_print ("Please either:\n");
 304       g_print ("- remove it and restart.\n");
 305       g_print ("- run with --gst-disable-segtrap and debug.\n");
 306       exit (-1);
 307       break;
 308     default:
 309       g_print ("Caught unhandled signal on plugin loading\n");
 310       break;
 311   }
 312 }
 313
 314 /*
 315  * _gst_plugin_fault_handler_setup:
 316  * sets up the segfault handler
 317  */
 318 static void
 319 _gst_plugin_fault_handler_setup (void)
 320 {
 321   struct sigaction action;
 322
 323   /* if asked to leave segfaults alone, just return */
 324   if (!gst_segtrap_is_enabled ())
 325     return;
 326
 327   if (_gst_plugin_fault_handler_is_setup)
 328     return;
 329
 330   _gst_plugin_fault_handler_is_setup = TRUE;
 331
 332   memset (&action, 0, sizeof (action));
 333   action.sa_handler = _gst_plugin_fault_handler_sighandler;
 334
 335   sigaction (SIGSEGV, &action, &oldaction);
 336 }
 337 #else
 338 static void
 339 _gst_plugin_fault_handler_restore (void)
 340 {
 341 }
 342
 343 static void
 344 _gst_plugin_fault_handler_setup (void)
 345 {
 346 }
 347 #endif
 348
 349 static void _gst_plugin_fault_handler_setup ();
 350
 351 static GStaticMutex gst_plugin_loading_mutex = G_STATIC_MUTEX_INIT;
 352
 353 /**
 354  * gst_plugin_load_file:
 355  * @filename: the plugin filename to load
 356  * @error: pointer to a NULL-valued GError
 357  *
 358  * Loads the given plugin and refs it.  Caller needs to unref after use.
 359  *
 360  * Returns: a reference to the existing loaded GstPlugin, a reference to the
 361  * newly-loaded GstPlugin, or NULL if an error occurred.
 362  */
 363 GstPlugin *
 364 gst_plugin_load_file (const gchar * filename, GError ** error)
 365 {
 366   GstPlugin *plugin;
 367   GModule *module;
 368   gboolean ret;
 369   gpointer ptr;
 370   struct stat file_status;
 371   GstRegistry *registry;
 372
 373   g_return_val_if_fail (filename != NULL, NULL);
 374
 375   registry = gst_registry_get_default ();
 376   g_static_mutex_lock (&gst_plugin_loading_mutex);
 377
 378   plugin = gst_registry_lookup (registry, filename);
 379   if (plugin) {
 380     if (plugin->module) {
 381       g_static_mutex_unlock (&gst_plugin_loading_mutex);
 382       return plugin;
 383     } else {
 384       gst_object_unref (plugin);
 385       plugin = NULL;
 386     }
 387   }
 388
 389   GST_CAT_DEBUG (GST_CAT_PLUGIN_LOADING, "attempt to load plugin \"%s\"",
 390       filename);
 391
 392   if (g_module_supported () == FALSE) {
 393     GST_CAT_DEBUG (GST_CAT_PLUGIN_LOADING, "module loading not supported");
 394     g_set_error (error,
 395         GST_PLUGIN_ERROR,
 396         GST_PLUGIN_ERROR_MODULE, "Dynamic loading not supported");
 397     goto return_error;
 398   }
 399
 400   if (g_stat (filename, &file_status)) {
 401     GST_CAT_DEBUG (GST_CAT_PLUGIN_LOADING, "problem accessing file");
 402     g_set_error (error,
 403         GST_PLUGIN_ERROR,
 404         GST_PLUGIN_ERROR_MODULE, "Problem accessing file %s: %s", filename,
 405         g_strerror (errno));
 406     goto return_error;
 407   }
 408
 409   module = g_module_open (filename, G_MODULE_BIND_LOCAL);
 410   if (module == NULL) {
 411     GST_CAT_WARNING (GST_CAT_PLUGIN_LOADING, "module_open failed: %s",
 412         g_module_error ());
 413     g_set_error (error,
 414         GST_PLUGIN_ERROR, GST_PLUGIN_ERROR_MODULE, "Opening module failed: %s",
 415         g_module_error ());
 416     /* If we failed to open the shared object, then it's probably because a
 417      * plugin is linked against the wrong libraries. Print out an easy-to-see
 418      * message in this case. */
 419     g_warning ("Failed to load plugin '%s': %s", filename, g_module_error ());
 420     goto return_error;
 421   }
 422
 423   plugin = g_object_new (GST_TYPE_PLUGIN, NULL);
 424
 425   plugin->module = module;
 426   plugin->filename = g_strdup (filename);
 427   plugin->basename = g_path_get_basename (filename);
 428   plugin->file_mtime = file_status.st_mtime;
 429   plugin->file_size = file_status.st_size;
 430
 431   ret = g_module_symbol (module, "gst_plugin_desc", &ptr);
 432   if (!ret) {
 433     GST_DEBUG ("Could not find plugin entry point in \"%s\"", filename);
 434     g_set_error (error,
 435         GST_PLUGIN_ERROR,
 436         GST_PLUGIN_ERROR_MODULE,
 437         "File \"%s\" is not a GStreamer plugin", filename);
 438     g_module_close (module);
 439     goto return_error;
 440   }
 441   plugin->orig_desc = (GstPluginDesc *) ptr;
 442
 443   GST_LOG ("Plugin %p for file \"%s\" prepared, calling entry function...",
 444       plugin, filename);
 445
 446   /* this is where we load the actual .so, so let's trap SIGSEGV */
 447   _gst_plugin_fault_handler_setup ();
 448   _gst_plugin_fault_handler_filename = plugin->filename;
 449
 450   GST_LOG ("Plugin %p for file \"%s\" prepared, registering...",
 451       plugin, filename);
 452
 453   if (!gst_plugin_register_func (plugin, plugin->orig_desc)) {
 454     /* remove signal handler */
 455     _gst_plugin_fault_handler_restore ();
 456     GST_DEBUG ("gst_plugin_register_func failed for plugin \"%s\"", filename);
 457     /* plugin == NULL */
 458     g_set_error (error,
 459         GST_PLUGIN_ERROR,
 460         GST_PLUGIN_ERROR_MODULE,
 461         "File \"%s\" appears to be a GStreamer plugin, but it failed to initialize",
 462         filename);
 463     g_module_close (module);
 464     goto return_error;
 465   }
 466
 467   /* remove signal handler */
 468   _gst_plugin_fault_handler_restore ();
 469   _gst_plugin_fault_handler_filename = NULL;
 470   GST_INFO ("plugin \"%s\" loaded", plugin->filename);
 471
 472   gst_object_ref (plugin);
 473   gst_default_registry_add_plugin (plugin);
 474
 475   g_static_mutex_unlock (&gst_plugin_loading_mutex);
 476   return plugin;
 477
 478 return_error:
 479   {
 480     if (plugin)
 481       gst_object_unref (plugin);
 482     g_static_mutex_unlock (&gst_plugin_loading_mutex);
 483     return NULL;
 484   }
 485 }
 486
 487 static void
 488 gst_plugin_desc_copy (GstPluginDesc * dest, const GstPluginDesc * src)
 489 {
 490   dest->major_version = src->major_version;
 491   dest->minor_version = src->minor_version;
 492   dest->name = g_intern_string (src->name);
 493   /* maybe intern the description too, just for convenience? */
 494   dest->description = g_strdup (src->description);
 495   dest->plugin_init = src->plugin_init;
 496   dest->version = g_intern_string (src->version);
 497   dest->license = g_intern_string (src->license);
 498   dest->source = g_intern_string (src->source);
 499   dest->package = g_intern_string (src->package);
 500   dest->origin = g_intern_string (src->origin);
 501 }
 502
 503 /* unused */
 504 static void
 505 gst_plugin_desc_free (GstPluginDesc * desc)
 506 {
 507   g_free (desc->description);
 508   memset (desc, 0, sizeof (GstPluginDesc));
 509 }
 510
 511 /**
 512  * gst_plugin_get_name:
 513  * @plugin: plugin to get the name of
 514  *
 515  * Get the short name of the plugin
 516  *
 517  * Returns: the name of the plugin
 518  */
 519 const gchar *
 520 gst_plugin_get_name (GstPlugin * plugin)
 521 {
 522   g_return_val_if_fail (plugin != NULL, NULL);
 523
 524   return plugin->desc.name;
 525 }
 526
 527 /**
 528  * gst_plugin_get_description:
 529  * @plugin: plugin to get long name of
 530  *
 531  * Get the long descriptive name of the plugin
 532  *
 533  * Returns: the long name of the plugin
 534  */
 535 G_CONST_RETURN gchar *
 536 gst_plugin_get_description (GstPlugin * plugin)
 537 {
 538   g_return_val_if_fail (plugin != NULL, NULL);
 539
 540   return plugin->desc.description;
 541 }
 542
 543 /**
 544  * gst_plugin_get_filename:
 545  * @plugin: plugin to get the filename of
 546  *
 547  * get the filename of the plugin
 548  *
 549  * Returns: the filename of the plugin
 550  */
 551 G_CONST_RETURN gchar *
 552 gst_plugin_get_filename (GstPlugin * plugin)
 553 {
 554   g_return_val_if_fail (plugin != NULL, NULL);
 555
 556   return plugin->filename;
 557 }
 558
 559 /**
 560  * gst_plugin_get_version:
 561  * @plugin: plugin to get the version of
 562  *
 563  * get the version of the plugin
 564  *
 565  * Returns: the version of the plugin
 566  */
 567 G_CONST_RETURN gchar *
 568 gst_plugin_get_version (GstPlugin * plugin)
 569 {
 570   g_return_val_if_fail (plugin != NULL, NULL);
 571
 572   return plugin->desc.version;
 573 }
 574
 575 /**
 576  * gst_plugin_get_license:
 577  * @plugin: plugin to get the license of
 578  *
 579  * get the license of the plugin
 580  *
 581  * Returns: the license of the plugin
 582  */
 583 G_CONST_RETURN gchar *
 584 gst_plugin_get_license (GstPlugin * plugin)
 585 {
 586   g_return_val_if_fail (plugin != NULL, NULL);
 587
 588   return plugin->desc.license;
 589 }
 590
 591 /**
 592  * gst_plugin_get_source:
 593  * @plugin: plugin to get the source of
 594  *
 595  * get the source module the plugin belongs to.
 596  *
 597  * Returns: the source of the plugin
 598  */
 599 G_CONST_RETURN gchar *
 600 gst_plugin_get_source (GstPlugin * plugin)
 601 {
 602   g_return_val_if_fail (plugin != NULL, NULL);
 603
 604   return plugin->desc.source;
 605 }
 606
 607 /**
 608  * gst_plugin_get_package:
 609  * @plugin: plugin to get the package of
 610  *
 611  * get the package the plugin belongs to.
 612  *
 613  * Returns: the package of the plugin
 614  */
 615 G_CONST_RETURN gchar *
 616 gst_plugin_get_package (GstPlugin * plugin)
 617 {
 618   g_return_val_if_fail (plugin != NULL, NULL);
 619
 620   return plugin->desc.package;
 621 }
 622
 623 /**
 624  * gst_plugin_get_origin:
 625  * @plugin: plugin to get the origin of
 626  *
 627  * get the URL where the plugin comes from
 628  *
 629  * Returns: the origin of the plugin
 630  */
 631 G_CONST_RETURN gchar *
 632 gst_plugin_get_origin (GstPlugin * plugin)
 633 {
 634   g_return_val_if_fail (plugin != NULL, NULL);
 635
 636   return plugin->desc.origin;
 637 }
 638
 639 /**
 640  * gst_plugin_get_module:
 641  * @plugin: plugin to query
 642  *
 643  * Gets the #GModule of the plugin. If the plugin isn't loaded yet, NULL is
 644  * returned.
 645  *
 646  * Returns: module belonging to the plugin or NULL if the plugin isn't
 647  *          loaded yet.
 648  */
 649 GModule *
 650 gst_plugin_get_module (GstPlugin * plugin)
 651 {
 652   g_return_val_if_fail (plugin != NULL, NULL);
 653
 654   return plugin->module;
 655 }
 656
 657 /**
 658  * gst_plugin_is_loaded:
 659  * @plugin: plugin to query
 660  *
 661  * queries if the plugin is loaded into memory
 662  *
 663  * Returns: TRUE is loaded, FALSE otherwise
 664  */
 665 gboolean
 666 gst_plugin_is_loaded (GstPlugin * plugin)
 667 {
 668   g_return_val_if_fail (plugin != NULL, FALSE);
 669
 670   return (plugin->module != NULL || plugin->filename == NULL);
 671 }
 672
 673 #if 0
 674 /**
 675  * gst_plugin_feature_list:
 676  * @plugin: plugin to query
 677  * @filter: the filter to use
 678  * @first: only return first match
 679  * @user_data: user data passed to the filter function
 680  *
 681  * Runs a filter against all plugin features and returns a GList with
 682  * the results. If the first flag is set, only the first match is
 683  * returned (as a list with a single object).
 684  *
 685  * Returns: a GList of features, g_list_free after use.
 686  */
 687 GList *
 688 gst_plugin_feature_filter (GstPlugin * plugin,
 689     GstPluginFeatureFilter filter, gboolean first, gpointer user_data)
 690 {
 691   GList *list;
 692   GList *g;
 693
 694   list = gst_filter_run (plugin->features, (GstFilterFunc) filter, first,
 695       user_data);
 696   for (g = list; g; g = g->next) {
 697     gst_object_ref (plugin);
 698   }
 699
 700   return list;
 701 }
 702
 703 typedef struct
 704 {
 705   GstPluginFeatureFilter filter;
 706   gboolean first;
 707   gpointer user_data;
 708   GList *result;
 709 }
 710 FeatureFilterData;
 711
 712 static gboolean
 713 _feature_filter (GstPlugin * plugin, gpointer user_data)
 714 {
 715   GList *result;
 716   FeatureFilterData *data = (FeatureFilterData *) user_data;
 717
 718   result = gst_plugin_feature_filter (plugin, data->filter, data->first,
 719       data->user_data);
 720   if (result) {
 721     data->result = g_list_concat (data->result, result);
 722     return TRUE;
 723   }
 724   return FALSE;
 725 }
 726
 727 /**
 728  * gst_plugin_list_feature_filter:
 729  * @list: a #GList of plugins to query
 730  * @filter: the filter function to use
 731  * @first: only return first match
 732  * @user_data: user data passed to the filter function
 733  *
 734  * Runs a filter against all plugin features of the plugins in the given
 735  * list and returns a GList with the results.
 736  * If the first flag is set, only the first match is
 737  * returned (as a list with a single object).
 738  *
 739  * Returns: a GList of features, g_list_free after use.
 740  */
 741 GList *
 742 gst_plugin_list_feature_filter (GList * list,
 743     GstPluginFeatureFilter filter, gboolean first, gpointer user_data)
 744 {
 745   FeatureFilterData data;
 746   GList *result;
 747
 748   data.filter = filter;
 749   data.first = first;
 750   data.user_data = user_data;
 751   data.result = NULL;
 752
 753   result = gst_filter_run (list, (GstFilterFunc) _feature_filter, first, &data);
 754   g_list_free (result);
 755
 756   return data.result;
 757 }
 758 #endif
 759
 760 /**
 761  * gst_plugin_name_filter:
 762  * @plugin: the plugin to check
 763  * @name: the name of the plugin
 764  *
 765  * A standard filter that returns TRUE when the plugin is of the
 766  * given name.
 767  *
 768  * Returns: TRUE if the plugin is of the given name.
 769  */
 770 gboolean
 771 gst_plugin_name_filter (GstPlugin * plugin, const gchar * name)
 772 {
 773   return (plugin->desc.name && !strcmp (plugin->desc.name, name));
 774 }
 775
 776 #if 0
 777 /**
 778  * gst_plugin_find_feature:
 779  * @plugin: plugin to get the feature from
 780  * @name: The name of the feature to find
 781  * @type: The type of the feature to find
 782  *
 783  * Find a feature of the given name and type in the given plugin.
 784  *
 785  * Returns: a GstPluginFeature or NULL if the feature was not found.
 786  */
 787 GstPluginFeature *
 788 gst_plugin_find_feature (GstPlugin * plugin, const gchar * name, GType type)
 789 {
 790   GList *walk;
 791   GstPluginFeature *result = NULL;
 792   GstTypeNameData data;
 793
 794   g_return_val_if_fail (name != NULL, NULL);
 795
 796   data.type = type;
 797   data.name = name;
 798
 799   walk = gst_filter_run (plugin->features,
 800       (GstFilterFunc) gst_plugin_feature_type_name_filter, TRUE, &data);
 801
 802   if (walk) {
 803     result = GST_PLUGIN_FEATURE (walk->data);
 804
 805     gst_object_ref (result);
 806     gst_plugin_feature_list_free (walk);
 807   }
 808
 809   return result;
 810 }
 811 #endif
 812
 813 #if 0
 814 static gboolean
 815 gst_plugin_feature_name_filter (GstPluginFeature * feature, const gchar * name)
 816 {
 817   return !strcmp (name, GST_PLUGIN_FEATURE_NAME (feature));
 818 }
 819 #endif
 820
 821 #if 0
 822 /**
 823  * gst_plugin_find_feature_by_name:
 824  * @plugin: plugin to get the feature from
 825  * @name: The name of the feature to find
 826  *
 827  * Find a feature of the given name in the given plugin.
 828  *
 829  * Returns: a GstPluginFeature or NULL if the feature was not found.
 830  */
 831 GstPluginFeature *
 832 gst_plugin_find_feature_by_name (GstPlugin * plugin, const gchar * name)
 833 {
 834   GList *walk;
 835   GstPluginFeature *result = NULL;
 836
 837   g_return_val_if_fail (name != NULL, NULL);
 838
 839   walk = gst_filter_run (plugin->features,
 840       (GstFilterFunc) gst_plugin_feature_name_filter, TRUE, (void *) name);
 841
 842   if (walk) {
 843     result = GST_PLUGIN_FEATURE (walk->data);
 844
 845     gst_object_ref (result);
 846     gst_plugin_feature_list_free (walk);
 847   }
 848
 849   return result;
 850 }
 851 #endif
 852
 853 /**
 854  * gst_plugin_load_by_name:
 855  * @name: name of plugin to load
 856  *
 857  * Load the named plugin. Refs the plugin.
 858  *
 859  * Returns: A reference to a loaded plugin, or NULL on error.
 860  */
 861 GstPlugin *
 862 gst_plugin_load_by_name (const gchar * name)
 863 {
 864   GstPlugin *plugin, *newplugin;
 865   GError *error = NULL;
 866
 867   GST_DEBUG ("looking up plugin %s in default registry", name);
 868   plugin = gst_registry_find_plugin (gst_registry_get_default (), name);
 869   if (plugin) {
 870     GST_DEBUG ("loading plugin %s from file %s", name, plugin->filename);
 871     newplugin = gst_plugin_load_file (plugin->filename, &error);
 872     gst_object_unref (plugin);
 873
 874     if (!newplugin) {
 875       GST_WARNING ("load_plugin error: %s", error->message);
 876       g_error_free (error);
 877       return NULL;
 878     }
 879     /* newplugin was reffed by load_file */
 880     return newplugin;
 881   }
 882
 883   GST_DEBUG ("Could not find plugin %s in registry", name);
 884   return NULL;
 885 }
 886
 887 /**
 888  * gst_plugin_load:
 889  * @plugin: plugin to load
 890  *
 891  * Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is
 892  * untouched. The normal use pattern of this function goes like this:
 893  *
 894  * <programlisting>
 895  * GstPlugin *loaded_plugin;
 896  * loaded_plugin = gst_plugin_load (plugin);
 897  * // presumably, we're no longer interested in the potentially-unloaded plugin
 898  * gst_object_unref (plugin);
 899  * plugin = loaded_plugin;
 900  * </programlisting>
 901  *
 902  * Returns: A reference to a loaded plugin, or NULL on error.
 903  */
 904 GstPlugin *
 905 gst_plugin_load (GstPlugin * plugin)
 906 {
 907   GError *error = NULL;
 908   GstPlugin *newplugin;
 909
 910   if (gst_plugin_is_loaded (plugin)) {
 911     return plugin;
 912   }
 913
 914   if (!(newplugin = gst_plugin_load_file (plugin->filename, &error)))
 915     goto load_error;
 916
 917   return newplugin;
 918
 919 load_error:
 920   {
 921     GST_WARNING ("load_plugin error: %s", error->message);
 922     g_error_free (error);
 923     return NULL;
 924   }
 925 }
 926
 927 /**
 928  * gst_plugin_list_free:
 929  * @list: list of #GstPlugin
 930  *
 931  * Unrefs each member of @list, then frees the list.
 932  */
 933 void
 934 gst_plugin_list_free (GList * list)
 935 {
 936   GList *g;
 937
 938   for (g = list; g; g = g->next) {
 939     gst_object_unref (GST_PLUGIN_CAST (g->data));
 940   }
 941   g_list_free (list);
 942 }