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