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