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