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 #define CHECK_PLUGIN_DESC_FIELD(desc,field,fn)                               \
 434   if (G_UNLIKELY ((desc)->field == NULL)) {                                  \
 435     GST_ERROR ("GstPluginDesc for '%s' has no %s", fn, G_STRINGIFY (field)); \
 436   }
 437
 438 /**
 439  * gst_plugin_load_file:
 440  * @filename: the plugin filename to load
 441  * @error: pointer to a NULL-valued GError
 442  *
 443  * Loads the given plugin and refs it.  Caller needs to unref after use.
 444  *
 445  * Returns: a reference to the existing loaded GstPlugin, a reference to the
 446  * newly-loaded GstPlugin, or NULL if an error occurred.
 447  */
 448 GstPlugin *
 449 gst_plugin_load_file (const gchar * filename, GError ** error)
 450 {
 451   GstPlugin *plugin;
 452   GModule *module;
 453   gboolean ret;
 454   gpointer ptr;
 455   struct stat file_status;
 456   GstRegistry *registry;
 457
 458   g_return_val_if_fail (filename != NULL, NULL);
 459
 460   registry = gst_registry_get_default ();
 461   g_static_mutex_lock (&gst_plugin_loading_mutex);
 462
 463   plugin = gst_registry_lookup (registry, filename);
 464   if (plugin) {
 465     if (plugin->module) {
 466       g_static_mutex_unlock (&gst_plugin_loading_mutex);
 467       return plugin;
 468     } else {
 469       gst_object_unref (plugin);
 470       plugin = NULL;
 471     }
 472   }
 473
 474   GST_CAT_DEBUG (GST_CAT_PLUGIN_LOADING, "attempt to load plugin \"%s\"",
 475       filename);
 476
 477   if (g_module_supported () == FALSE) {
 478     GST_CAT_DEBUG (GST_CAT_PLUGIN_LOADING, "module loading not supported");
 479     g_set_error (error,
 480         GST_PLUGIN_ERROR,
 481         GST_PLUGIN_ERROR_MODULE, "Dynamic loading not supported");
 482     goto return_error;
 483   }
 484
 485   if (g_stat (filename, &file_status)) {
 486     GST_CAT_DEBUG (GST_CAT_PLUGIN_LOADING, "problem accessing file");
 487     g_set_error (error,
 488         GST_PLUGIN_ERROR,
 489         GST_PLUGIN_ERROR_MODULE, "Problem accessing file %s: %s", filename,
 490         g_strerror (errno));
 491     goto return_error;
 492   }
 493
 494   module = g_module_open (filename, G_MODULE_BIND_LOCAL);
 495   if (module == NULL) {
 496     GST_CAT_WARNING (GST_CAT_PLUGIN_LOADING, "module_open failed: %s",
 497         g_module_error ());
 498     g_set_error (error,
 499         GST_PLUGIN_ERROR, GST_PLUGIN_ERROR_MODULE, "Opening module failed: %s",
 500         g_module_error ());
 501     /* If we failed to open the shared object, then it's probably because a
 502      * plugin is linked against the wrong libraries. Print out an easy-to-see
 503      * message in this case. */
 504     g_warning ("Failed to load plugin '%s': %s", filename, g_module_error ());
 505     goto return_error;
 506   }
 507
 508   plugin = g_object_new (GST_TYPE_PLUGIN, NULL);
 509
 510   plugin->module = module;
 511   plugin->filename = g_strdup (filename);
 512   plugin->basename = g_path_get_basename (filename);
 513   plugin->file_mtime = file_status.st_mtime;
 514   plugin->file_size = file_status.st_size;
 515
 516   ret = g_module_symbol (module, "gst_plugin_desc", &ptr);
 517   if (!ret) {
 518     GST_DEBUG ("Could not find plugin entry point in \"%s\"", filename);
 519     g_set_error (error,
 520         GST_PLUGIN_ERROR,
 521         GST_PLUGIN_ERROR_MODULE,
 522         "File \"%s\" is not a GStreamer plugin", filename);
 523     g_module_close (module);
 524     goto return_error;
 525   }
 526   plugin->orig_desc = (GstPluginDesc *) ptr;
 527
 528   /* check plugin description: complain about bad values but accept them, to
 529    * maintain backwards compatibility (FIXME: 0.11) */
 530   CHECK_PLUGIN_DESC_FIELD (plugin->orig_desc, name, filename);
 531   CHECK_PLUGIN_DESC_FIELD (plugin->orig_desc, description, filename);
 532   CHECK_PLUGIN_DESC_FIELD (plugin->orig_desc, version, filename);
 533   CHECK_PLUGIN_DESC_FIELD (plugin->orig_desc, license, filename);
 534   CHECK_PLUGIN_DESC_FIELD (plugin->orig_desc, source, filename);
 535   CHECK_PLUGIN_DESC_FIELD (plugin->orig_desc, package, filename);
 536   CHECK_PLUGIN_DESC_FIELD (plugin->orig_desc, origin, filename);
 537
 538   GST_LOG ("Plugin %p for file \"%s\" prepared, calling entry function...",
 539       plugin, filename);
 540
 541   /* this is where we load the actual .so, so let's trap SIGSEGV */
 542   _gst_plugin_fault_handler_setup ();
 543   _gst_plugin_fault_handler_filename = plugin->filename;
 544
 545   GST_LOG ("Plugin %p for file \"%s\" prepared, registering...",
 546       plugin, filename);
 547
 548   if (!gst_plugin_register_func (plugin, plugin->orig_desc)) {
 549     /* remove signal handler */
 550     _gst_plugin_fault_handler_restore ();
 551     GST_DEBUG ("gst_plugin_register_func failed for plugin \"%s\"", filename);
 552     /* plugin == NULL */
 553     g_set_error (error,
 554         GST_PLUGIN_ERROR,
 555         GST_PLUGIN_ERROR_MODULE,
 556         "File \"%s\" appears to be a GStreamer plugin, but it failed to initialize",
 557         filename);
 558     g_module_close (module);
 559     goto return_error;
 560   }
 561
 562   /* remove signal handler */
 563   _gst_plugin_fault_handler_restore ();
 564   _gst_plugin_fault_handler_filename = NULL;
 565   GST_INFO ("plugin \"%s\" loaded", plugin->filename);
 566
 567   gst_object_ref (plugin);
 568   gst_default_registry_add_plugin (plugin);
 569
 570   g_static_mutex_unlock (&gst_plugin_loading_mutex);
 571   return plugin;
 572
 573 return_error:
 574   {
 575     if (plugin)
 576       gst_object_unref (plugin);
 577     g_static_mutex_unlock (&gst_plugin_loading_mutex);
 578     return NULL;
 579   }
 580 }
 581
 582 static void
 583 gst_plugin_desc_copy (GstPluginDesc * dest, const GstPluginDesc * src)
 584 {
 585   dest->major_version = src->major_version;
 586   dest->minor_version = src->minor_version;
 587   dest->name = g_intern_string (src->name);
 588   /* maybe intern the description too, just for convenience? */
 589   dest->description = g_strdup (src->description);
 590   dest->plugin_init = src->plugin_init;
 591   dest->version = g_intern_string (src->version);
 592   dest->license = g_intern_string (src->license);
 593   dest->source = g_intern_string (src->source);
 594   dest->package = g_intern_string (src->package);
 595   dest->origin = g_intern_string (src->origin);
 596 }
 597
 598 /* unused */
 599 static void
 600 gst_plugin_desc_free (GstPluginDesc * desc)
 601 {
 602   g_free (desc->description);
 603   memset (desc, 0, sizeof (GstPluginDesc));
 604 }
 605
 606 /**
 607  * gst_plugin_get_name:
 608  * @plugin: plugin to get the name of
 609  *
 610  * Get the short name of the plugin
 611  *
 612  * Returns: the name of the plugin
 613  */
 614 const gchar *
 615 gst_plugin_get_name (GstPlugin * plugin)
 616 {
 617   g_return_val_if_fail (plugin != NULL, NULL);
 618
 619   return plugin->desc.name;
 620 }
 621
 622 /**
 623  * gst_plugin_get_description:
 624  * @plugin: plugin to get long name of
 625  *
 626  * Get the long descriptive name of the plugin
 627  *
 628  * Returns: the long name of the plugin
 629  */
 630 G_CONST_RETURN gchar *
 631 gst_plugin_get_description (GstPlugin * plugin)
 632 {
 633   g_return_val_if_fail (plugin != NULL, NULL);
 634
 635   return plugin->desc.description;
 636 }
 637
 638 /**
 639  * gst_plugin_get_filename:
 640  * @plugin: plugin to get the filename of
 641  *
 642  * get the filename of the plugin
 643  *
 644  * Returns: the filename of the plugin
 645  */
 646 G_CONST_RETURN gchar *
 647 gst_plugin_get_filename (GstPlugin * plugin)
 648 {
 649   g_return_val_if_fail (plugin != NULL, NULL);
 650
 651   return plugin->filename;
 652 }
 653
 654 /**
 655  * gst_plugin_get_version:
 656  * @plugin: plugin to get the version of
 657  *
 658  * get the version of the plugin
 659  *
 660  * Returns: the version of the plugin
 661  */
 662 G_CONST_RETURN gchar *
 663 gst_plugin_get_version (GstPlugin * plugin)
 664 {
 665   g_return_val_if_fail (plugin != NULL, NULL);
 666
 667   return plugin->desc.version;
 668 }
 669
 670 /**
 671  * gst_plugin_get_license:
 672  * @plugin: plugin to get the license of
 673  *
 674  * get the license of the plugin
 675  *
 676  * Returns: the license of the plugin
 677  */
 678 G_CONST_RETURN gchar *
 679 gst_plugin_get_license (GstPlugin * plugin)
 680 {
 681   g_return_val_if_fail (plugin != NULL, NULL);
 682
 683   return plugin->desc.license;
 684 }
 685
 686 /**
 687  * gst_plugin_get_source:
 688  * @plugin: plugin to get the source of
 689  *
 690  * get the source module the plugin belongs to.
 691  *
 692  * Returns: the source of the plugin
 693  */
 694 G_CONST_RETURN gchar *
 695 gst_plugin_get_source (GstPlugin * plugin)
 696 {
 697   g_return_val_if_fail (plugin != NULL, NULL);
 698
 699   return plugin->desc.source;
 700 }
 701
 702 /**
 703  * gst_plugin_get_package:
 704  * @plugin: plugin to get the package of
 705  *
 706  * get the package the plugin belongs to.
 707  *
 708  * Returns: the package of the plugin
 709  */
 710 G_CONST_RETURN gchar *
 711 gst_plugin_get_package (GstPlugin * plugin)
 712 {
 713   g_return_val_if_fail (plugin != NULL, NULL);
 714
 715   return plugin->desc.package;
 716 }
 717
 718 /**
 719  * gst_plugin_get_origin:
 720  * @plugin: plugin to get the origin of
 721  *
 722  * get the URL where the plugin comes from
 723  *
 724  * Returns: the origin of the plugin
 725  */
 726 G_CONST_RETURN gchar *
 727 gst_plugin_get_origin (GstPlugin * plugin)
 728 {
 729   g_return_val_if_fail (plugin != NULL, NULL);
 730
 731   return plugin->desc.origin;
 732 }
 733
 734 /**
 735  * gst_plugin_get_module:
 736  * @plugin: plugin to query
 737  *
 738  * Gets the #GModule of the plugin. If the plugin isn't loaded yet, NULL is
 739  * returned.
 740  *
 741  * Returns: module belonging to the plugin or NULL if the plugin isn't
 742  *          loaded yet.
 743  */
 744 GModule *
 745 gst_plugin_get_module (GstPlugin * plugin)
 746 {
 747   g_return_val_if_fail (plugin != NULL, NULL);
 748
 749   return plugin->module;
 750 }
 751
 752 /**
 753  * gst_plugin_is_loaded:
 754  * @plugin: plugin to query
 755  *
 756  * queries if the plugin is loaded into memory
 757  *
 758  * Returns: TRUE is loaded, FALSE otherwise
 759  */
 760 gboolean
 761 gst_plugin_is_loaded (GstPlugin * plugin)
 762 {
 763   g_return_val_if_fail (plugin != NULL, FALSE);
 764
 765   return (plugin->module != NULL || plugin->filename == NULL);
 766 }
 767
 768 #if 0
 769 /**
 770  * gst_plugin_feature_list:
 771  * @plugin: plugin to query
 772  * @filter: the filter to use
 773  * @first: only return first match
 774  * @user_data: user data passed to the filter function
 775  *
 776  * Runs a filter against all plugin features and returns a GList with
 777  * the results. If the first flag is set, only the first match is
 778  * returned (as a list with a single object).
 779  *
 780  * Returns: a GList of features, g_list_free after use.
 781  */
 782 GList *
 783 gst_plugin_feature_filter (GstPlugin * plugin,
 784     GstPluginFeatureFilter filter, gboolean first, gpointer user_data)
 785 {
 786   GList *list;
 787   GList *g;
 788
 789   list = gst_filter_run (plugin->features, (GstFilterFunc) filter, first,
 790       user_data);
 791   for (g = list; g; g = g->next) {
 792     gst_object_ref (plugin);
 793   }
 794
 795   return list;
 796 }
 797
 798 typedef struct
 799 {
 800   GstPluginFeatureFilter filter;
 801   gboolean first;
 802   gpointer user_data;
 803   GList *result;
 804 }
 805 FeatureFilterData;
 806
 807 static gboolean
 808 _feature_filter (GstPlugin * plugin, gpointer user_data)
 809 {
 810   GList *result;
 811   FeatureFilterData *data = (FeatureFilterData *) user_data;
 812
 813   result = gst_plugin_feature_filter (plugin, data->filter, data->first,
 814       data->user_data);
 815   if (result) {
 816     data->result = g_list_concat (data->result, result);
 817     return TRUE;
 818   }
 819   return FALSE;
 820 }
 821
 822 /**
 823  * gst_plugin_list_feature_filter:
 824  * @list: a #GList of plugins to query
 825  * @filter: the filter function to use
 826  * @first: only return first match
 827  * @user_data: user data passed to the filter function
 828  *
 829  * Runs a filter against all plugin features of the plugins in the given
 830  * list and returns a GList with the results.
 831  * If the first flag is set, only the first match is
 832  * returned (as a list with a single object).
 833  *
 834  * Returns: a GList of features, g_list_free after use.
 835  */
 836 GList *
 837 gst_plugin_list_feature_filter (GList * list,
 838     GstPluginFeatureFilter filter, gboolean first, gpointer user_data)
 839 {
 840   FeatureFilterData data;
 841   GList *result;
 842
 843   data.filter = filter;
 844   data.first = first;
 845   data.user_data = user_data;
 846   data.result = NULL;
 847
 848   result = gst_filter_run (list, (GstFilterFunc) _feature_filter, first, &data);
 849   g_list_free (result);
 850
 851   return data.result;
 852 }
 853 #endif
 854
 855 /**
 856  * gst_plugin_name_filter:
 857  * @plugin: the plugin to check
 858  * @name: the name of the plugin
 859  *
 860  * A standard filter that returns TRUE when the plugin is of the
 861  * given name.
 862  *
 863  * Returns: TRUE if the plugin is of the given name.
 864  */
 865 gboolean
 866 gst_plugin_name_filter (GstPlugin * plugin, const gchar * name)
 867 {
 868   return (plugin->desc.name && !strcmp (plugin->desc.name, name));
 869 }
 870
 871 #if 0
 872 /**
 873  * gst_plugin_find_feature:
 874  * @plugin: plugin to get the feature from
 875  * @name: The name of the feature to find
 876  * @type: The type of the feature to find
 877  *
 878  * Find a feature of the given name and type in the given plugin.
 879  *
 880  * Returns: a GstPluginFeature or NULL if the feature was not found.
 881  */
 882 GstPluginFeature *
 883 gst_plugin_find_feature (GstPlugin * plugin, const gchar * name, GType type)
 884 {
 885   GList *walk;
 886   GstPluginFeature *result = NULL;
 887   GstTypeNameData data;
 888
 889   g_return_val_if_fail (name != NULL, NULL);
 890
 891   data.type = type;
 892   data.name = name;
 893
 894   walk = gst_filter_run (plugin->features,
 895       (GstFilterFunc) gst_plugin_feature_type_name_filter, TRUE, &data);
 896
 897   if (walk) {
 898     result = GST_PLUGIN_FEATURE (walk->data);
 899
 900     gst_object_ref (result);
 901     gst_plugin_feature_list_free (walk);
 902   }
 903
 904   return result;
 905 }
 906 #endif
 907
 908 #if 0
 909 static gboolean
 910 gst_plugin_feature_name_filter (GstPluginFeature * feature, const gchar * name)
 911 {
 912   return !strcmp (name, GST_PLUGIN_FEATURE_NAME (feature));
 913 }
 914 #endif
 915
 916 #if 0
 917 /**
 918  * gst_plugin_find_feature_by_name:
 919  * @plugin: plugin to get the feature from
 920  * @name: The name of the feature to find
 921  *
 922  * Find a feature of the given name in the given plugin.
 923  *
 924  * Returns: a GstPluginFeature or NULL if the feature was not found.
 925  */
 926 GstPluginFeature *
 927 gst_plugin_find_feature_by_name (GstPlugin * plugin, const gchar * name)
 928 {
 929   GList *walk;
 930   GstPluginFeature *result = NULL;
 931
 932   g_return_val_if_fail (name != NULL, NULL);
 933
 934   walk = gst_filter_run (plugin->features,
 935       (GstFilterFunc) gst_plugin_feature_name_filter, TRUE, (void *) name);
 936
 937   if (walk) {
 938     result = GST_PLUGIN_FEATURE (walk->data);
 939
 940     gst_object_ref (result);
 941     gst_plugin_feature_list_free (walk);
 942   }
 943
 944   return result;
 945 }
 946 #endif
 947
 948 /**
 949  * gst_plugin_load_by_name:
 950  * @name: name of plugin to load
 951  *
 952  * Load the named plugin. Refs the plugin.
 953  *
 954  * Returns: A reference to a loaded plugin, or NULL on error.
 955  */
 956 GstPlugin *
 957 gst_plugin_load_by_name (const gchar * name)
 958 {
 959   GstPlugin *plugin, *newplugin;
 960   GError *error = NULL;
 961
 962   GST_DEBUG ("looking up plugin %s in default registry", name);
 963   plugin = gst_registry_find_plugin (gst_registry_get_default (), name);
 964   if (plugin) {
 965     GST_DEBUG ("loading plugin %s from file %s", name, plugin->filename);
 966     newplugin = gst_plugin_load_file (plugin->filename, &error);
 967     gst_object_unref (plugin);
 968
 969     if (!newplugin) {
 970       GST_WARNING ("load_plugin error: %s", error->message);
 971       g_error_free (error);
 972       return NULL;
 973     }
 974     /* newplugin was reffed by load_file */
 975     return newplugin;
 976   }
 977
 978   GST_DEBUG ("Could not find plugin %s in registry", name);
 979   return NULL;
 980 }
 981
 982 /**
 983  * gst_plugin_load:
 984  * @plugin: plugin to load
 985  *
 986  * Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is
 987  * untouched. The normal use pattern of this function goes like this:
 988  *
 989  * <programlisting>
 990  * GstPlugin *loaded_plugin;
 991  * loaded_plugin = gst_plugin_load (plugin);
 992  * // presumably, we're no longer interested in the potentially-unloaded plugin
 993  * gst_object_unref (plugin);
 994  * plugin = loaded_plugin;
 995  * </programlisting>
 996  *
 997  * Returns: A reference to a loaded plugin, or NULL on error.
 998  */
 999 GstPlugin *
1000 gst_plugin_load (GstPlugin * plugin)
1001 {
1002   GError *error = NULL;
1003   GstPlugin *newplugin;
1004
1005   if (gst_plugin_is_loaded (plugin)) {
1006     return plugin;
1007   }
1008
1009   if (!(newplugin = gst_plugin_load_file (plugin->filename, &error)))
1010     goto load_error;
1011
1012   return newplugin;
1013
1014 load_error:
1015   {
1016     GST_WARNING ("load_plugin error: %s", error->message);
1017     g_error_free (error);
1018     return NULL;
1019   }
1020 }
1021
1022 /**
1023  * gst_plugin_list_free:
1024  * @list: list of #GstPlugin
1025  *
1026  * Unrefs each member of @list, then frees the list.
1027  */
1028 void
1029 gst_plugin_list_free (GList * list)
1030 {
1031   GList *g;
1032
1033   for (g = list; g; g = g->next) {
1034     gst_object_unref (GST_PLUGIN_CAST (g->data));
1035   }
1036   g_list_free (list);
1037 }