gst/gstelementfactory.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *                    2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
   5  *
   6  * gstelementfactory.c: GstElementFactory object, support routines
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 #include "gst_private.h"
  25
  26 #include "gstelement.h"
  27 #include "gstregistrypool.h"
  28 #include "gstinfo.h"
  29 #include "gsturi.h"
  30
  31 GST_DEBUG_CATEGORY_STATIC (element_factory_debug);
  32 #define GST_CAT_DEFAULT element_factory_debug
  33
  34 static void             gst_element_factory_class_init          (GstElementFactoryClass *klass);
  35 static void             gst_element_factory_init                (GstElementFactory *factory);
  36
  37 static void             gst_element_factory_unload_thyself      (GstPluginFeature *feature);
  38
  39 static GstPluginFeatureClass *parent_class = NULL;
  40 /* static guint gst_element_factory_signals[LAST_SIGNAL] = { 0 }; */
  41
  42 GType
  43 gst_element_factory_get_type (void)
  44 {
  45   static GType elementfactory_type = 0;
  46
  47   if (!elementfactory_type) {
  48     static const GTypeInfo elementfactory_info = {
  49       sizeof (GstElementFactoryClass),
  50       NULL,
  51       NULL,
  52       (GClassInitFunc) gst_element_factory_class_init,
  53       NULL,
  54       NULL,
  55       sizeof(GstElementFactory),
  56       0,
  57       (GInstanceInitFunc) gst_element_factory_init,
  58       NULL
  59     };
  60     elementfactory_type = g_type_register_static (GST_TYPE_PLUGIN_FEATURE,
  61                                                   "GstElementFactory", &elementfactory_info, 0);
  62     GST_DEBUG_CATEGORY_INIT (element_factory_debug, "GST_ELEMENT_FACTORY",
  63             GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_RED,
  64             "element factories keep information about installed elements");
  65   }
  66   return elementfactory_type;
  67 }
  68 static void
  69 gst_element_factory_class_init (GstElementFactoryClass *klass)
  70 {
  71   GObjectClass *gobject_class;
  72   GstObjectClass *gstobject_class;
  73   GstPluginFeatureClass *gstpluginfeature_class;
  74
  75   gobject_class = (GObjectClass*)klass;
  76   gstobject_class = (GstObjectClass*)klass;
  77   gstpluginfeature_class = (GstPluginFeatureClass*) klass;
  78
  79   parent_class = g_type_class_peek_parent (klass);
  80
  81   gstpluginfeature_class->unload_thyself =      GST_DEBUG_FUNCPTR (gst_element_factory_unload_thyself);
  82 }
  83 static void
  84 gst_element_factory_init (GstElementFactory *factory)
  85 {
  86   factory->padtemplates = NULL;
  87   factory->numpadtemplates = 0;
  88
  89   factory->uri_type = GST_URI_UNKNOWN;
  90   factory->uri_protocols = NULL;
  91
  92   factory->interfaces = NULL;
  93 }
  94 /**
  95  * gst_element_factory_find:
  96  * @name: name of factory to find
  97  *
  98  * Search for an element factory of the given name.
  99  *
 100  * Returns: #GstElementFactory if found, NULL otherwise
 101  */
 102 GstElementFactory*
 103 gst_element_factory_find (const gchar *name)
 104 {
 105   GstPluginFeature *feature;
 106
 107   g_return_val_if_fail(name != NULL, NULL);
 108
 109   feature = gst_registry_pool_find_feature (name, GST_TYPE_ELEMENT_FACTORY);
 110   if (feature)
 111     return GST_ELEMENT_FACTORY (feature);
 112
 113   /* this should be an ERROR */
 114   GST_DEBUG ("no such elementfactory \"%s\"", name);
 115   return NULL;
 116 }
 117
 118 void
 119 __gst_element_details_clear (GstElementDetails *dp)
 120 {
 121   g_free (dp->longname);
 122   dp->longname = NULL;
 123   g_free (dp->klass);
 124   dp->klass = NULL;
 125   g_free (dp->description);
 126   dp->description = NULL;
 127   g_free (dp->author);
 128   dp->author = NULL;
 129 }
 130 void
 131 __gst_element_details_set (GstElementDetails *dest, const GstElementDetails *src)
 132 {
 133   dest->longname = g_strdup (src->longname);
 134   dest->klass = g_strdup (src->klass);
 135   dest->description = g_strdup (src->description);
 136   dest->author = g_strdup (src->author);
 137 }
 138 void
 139 __gst_element_details_copy (GstElementDetails *dest, const GstElementDetails *src)
 140 {
 141   __gst_element_details_clear (dest);
 142   __gst_element_details_set (dest, src);
 143 }
 144 static void
 145 gst_element_factory_cleanup (GstElementFactory *factory)
 146 {
 147   __gst_element_details_clear (&factory->details);
 148   if (factory->type) {
 149     g_type_class_unref (g_type_class_peek (factory->type));
 150     factory->type = 0;
 151   }
 152
 153   g_list_foreach (factory->padtemplates, (GFunc) g_object_unref, NULL);
 154   g_list_free (factory->padtemplates);
 155   factory->padtemplates = NULL;
 156   factory->numpadtemplates = 0;
 157   factory->uri_type = GST_URI_UNKNOWN;
 158   if (factory->uri_protocols) {
 159     g_strfreev (factory->uri_protocols);
 160     factory->uri_protocols = NULL;
 161   }
 162
 163   g_list_foreach (factory->interfaces, (GFunc) g_free, NULL);
 164   g_list_free (factory->interfaces);
 165   factory->interfaces = NULL;
 166 }
 167 /**
 168  * gst_element_register:
 169  * @plugin:
 170  * @name: name of elements of this type
 171  * @rank: rank of element (higher rank means more importance when autoplugging)
 172  * @type: GType of element to register
 173  *
 174  * Create a new elementfactory capable of insantiating objects of the
 175  * given type.
 176  *
 177  * Returns: TRUE, if the registering succeeded, FALSE on error
 178  */
 179 gboolean
 180 gst_element_register (GstPlugin *plugin, const gchar *name, guint rank, GType type)
 181 {
 182   GstElementFactory *factory;
 183   GType *interfaces;
 184   guint n_interfaces, i;
 185   GstElementClass *klass;
 186
 187   g_return_val_if_fail (name != NULL, FALSE);
 188   g_return_val_if_fail (g_type_is_a (type, GST_TYPE_ELEMENT), FALSE);
 189
 190   factory = gst_element_factory_find (name);
 191
 192   if (!factory) {
 193     klass = GST_ELEMENT_CLASS (g_type_class_ref (type));
 194     factory = GST_ELEMENT_FACTORY (g_object_new (GST_TYPE_ELEMENT_FACTORY, NULL));
 195     gst_plugin_feature_set_name (GST_PLUGIN_FEATURE (factory), name);
 196     GST_LOG_OBJECT (factory, "Created new elementfactory for type %s", g_type_name (type));
 197   } else {
 198     g_return_val_if_fail (factory->type == 0, FALSE);
 199     klass = GST_ELEMENT_CLASS (g_type_class_ref (type));
 200     gst_element_factory_cleanup (factory);
 201     GST_LOG_OBJECT (factory, "Reuse existing elementfactory for type %s", g_type_name (type));
 202   }
 203
 204   factory->type = type;
 205   __gst_element_details_copy (&factory->details, &klass->details);
 206   factory->padtemplates = g_list_copy (klass->padtemplates);
 207   g_list_foreach (factory->padtemplates, (GFunc) g_object_ref, NULL);
 208   factory->numpadtemplates = klass->numpadtemplates;
 209
 210   /* special stuff for URI handling */
 211   if (g_type_is_a (type, GST_TYPE_URI_HANDLER)) {
 212     GstURIHandlerInterface *iface = (GstURIHandlerInterface *)
 213             g_type_interface_peek (klass, GST_TYPE_URI_HANDLER);
 214     if (!iface || !iface->get_type || !iface->get_protocols)
 215       goto error;
 216     factory->uri_type = iface->get_type ();
 217     if (!GST_URI_TYPE_IS_VALID (factory->uri_type))
 218       goto error;
 219     factory->uri_protocols = g_strdupv (iface->get_protocols ());
 220     if (!factory->uri_protocols)
 221       goto error;
 222   }
 223
 224   interfaces = g_type_interfaces (type, &n_interfaces);
 225   for (i = 0; i < n_interfaces; i++) {
 226     __gst_element_factory_add_interface (factory, g_type_name (interfaces[i]));
 227   }
 228   g_free (interfaces);
 229
 230   gst_plugin_feature_set_rank (GST_PLUGIN_FEATURE (factory), rank);
 231   gst_plugin_add_feature (plugin, GST_PLUGIN_FEATURE (factory));
 232
 233   return TRUE;
 234
 235 error:
 236   gst_element_factory_cleanup (factory);
 237   return FALSE;
 238 }
 239 /**
 240  * gst_element_factory_create:
 241  * @factory: factory to instantiate
 242  * @name: name of new element
 243  *
 244  * Create a new element of the type defined by the given elementfactory.
 245  * It will be given the name supplied, since all elements require a name as
 246  * their first argument.
 247  *
 248  * Returns: new #GstElement or NULL if the element couldn't be created
 249  */
 250 GstElement*
 251 gst_element_factory_create (GstElementFactory *factory,
 252                            const gchar *name)
 253 {
 254   GstElement *element;
 255   GstElementClass *oclass;
 256
 257   g_return_val_if_fail (factory != NULL, NULL);
 258
 259   if (!gst_plugin_feature_ensure_loaded (GST_PLUGIN_FEATURE (factory))) {
 260     GST_INFO ("could not load element factory for element \"%s\"", name);
 261     return NULL;
 262   }
 263
 264   GST_LOG_OBJECT (factory, "creating element (name \"%s\", type %d)",
 265            GST_STR_NULL (name), (gint) factory->type);
 266
 267   if (factory->type == 0) {
 268       g_critical ("Factory for `%s' has no type",
 269                   GST_PLUGIN_FEATURE_NAME (factory));
 270       return NULL;
 271   }
 272
 273   oclass = GST_ELEMENT_CLASS (g_type_class_ref (factory->type));
 274   if (oclass->elementfactory == NULL) {
 275     GST_DEBUG ("class %s", GST_PLUGIN_FEATURE_NAME (factory));
 276     oclass->elementfactory = factory;
 277   }
 278
 279   /* create an instance of the element */
 280   element = GST_ELEMENT (g_object_new (factory->type, NULL));
 281   g_assert (element != NULL);
 282
 283   g_type_class_unref (oclass);
 284
 285   gst_object_set_name (GST_OBJECT (element), name);
 286
 287   return element;
 288 }
 289 /**
 290  * gst_element_factory_make:
 291  * @factoryname: a named factory to instantiate
 292  * @name: name of new element
 293  *
 294  * Create a new element of the type defined by the given element factory.
 295  * If name is NULL, then the element will receive a guaranteed unique name,
 296  * consisting of the element factory name and a number.
 297  * If name is given, it will be given the name supplied.
 298  *
 299  * Returns: new #GstElement or NULL if unable to create element
 300  */
 301 GstElement*
 302 gst_element_factory_make (const gchar *factoryname, const gchar *name)
 303 {
 304   GstElementFactory *factory;
 305   GstElement *element;
 306
 307   g_return_val_if_fail (factoryname != NULL, NULL);
 308
 309   GST_LOG ("gstelementfactory: make \"%s\" \"%s\"",
 310            factoryname, GST_STR_NULL (name));
 311
 312   /* gst_plugin_load_element_factory (factoryname); */
 313   factory = gst_element_factory_find (factoryname);
 314   if (factory == NULL) {
 315     GST_INFO ("no such element factory \"%s\"!",
 316               factoryname);
 317     return NULL;
 318   }
 319   element = gst_element_factory_create (factory, name);
 320   if (element == NULL) {
 321     GST_INFO_OBJECT (factory, "couldn't create instance!");
 322     return NULL;
 323   }
 324
 325   return element;
 326 }
 327 void
 328 __gst_element_factory_add_pad_template (GstElementFactory *factory,
 329                                         GstPadTemplate *templ)
 330 {
 331   g_return_if_fail (factory != NULL);
 332   g_return_if_fail (templ != NULL);
 333
 334   gst_object_ref (GST_OBJECT (templ));
 335   gst_object_sink (GST_OBJECT (templ));
 336
 337   factory->padtemplates = g_list_append (factory->padtemplates, templ);
 338   factory->numpadtemplates++;
 339 }
 340 /**
 341  * gst_element_factory_get_element_type:
 342  * @factory: factory to get managed #GType from
 343  *
 344  * Get the #GType for elements managed by this factory
 345  *
 346  * Returns: the #GType for elements managed by this factory
 347  */
 348 GType
 349 gst_element_factory_get_element_type (GstElementFactory *factory)
 350 {
 351   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), 0);
 352
 353   return factory->type;
 354 }
 355 /**
 356  * gst_element_factory_get_longname:
 357  * @factory: a #GstElementFactory
 358  *
 359  * Gets the longname for this factory
 360  *
 361  * Returns: the longname
 362  */
 363 G_CONST_RETURN gchar *
 364 gst_element_factory_get_longname (GstElementFactory *factory)
 365 {
 366   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 367
 368   return factory->details.longname;
 369 }
 370 /**
 371  * gst_element_factory_get_class:
 372  * @factory: a #GstElementFactory
 373  *
 374  * Gets the class for this factory.
 375  *
 376  * Returns: the class
 377  */
 378 G_CONST_RETURN gchar *
 379 gst_element_factory_get_klass (GstElementFactory *factory)
 380 {
 381   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 382
 383   return factory->details.klass;
 384 }
 385 /**
 386  * gst_element_factory_get_description:
 387  * @factory: a #GstElementFactory
 388  *
 389  * Gets the description for this factory.
 390  *
 391  * Returns: the description
 392  */
 393 G_CONST_RETURN gchar *
 394 gst_element_factory_get_description (GstElementFactory *factory)
 395 {
 396   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 397
 398   return factory->details.description;
 399 }
 400 /**
 401  * gst_element_factory_get_author:
 402  * @factory: a #GstElementFactory
 403  *
 404  * Gets the author for this factory.
 405  *
 406  * Returns: the author
 407  */
 408 G_CONST_RETURN gchar *
 409 gst_element_factory_get_author (GstElementFactory *factory)
 410 {
 411   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 412
 413   return factory->details.author;
 414 }
 415 /**
 416  * gst_element_factory_get_num_pad_templates:
 417  * @factory: a #GstElementFactory
 418  *
 419  * Gets the number of pad_templates in this factory.
 420  *
 421  * Returns: the number of pad_templates
 422  */
 423 guint
 424 gst_element_factory_get_num_pad_templates (GstElementFactory *factory)
 425 {
 426   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), 0);
 427
 428   return factory->numpadtemplates;
 429 }
 430 /**
 431  * __gst_element_factory_add_interface:
 432  * @elementfactory: The elementfactory to add the interface to
 433  * @interfacename: Name of the interface
 434  *
 435  * Adds the given interfacename to the list of implemented interfaces of the
 436  * element.
 437  */
 438 void
 439 __gst_element_factory_add_interface (GstElementFactory *elementfactory, const gchar *interfacename)
 440 {
 441   g_return_if_fail (GST_IS_ELEMENT_FACTORY (elementfactory));
 442   g_return_if_fail (interfacename != NULL);
 443   g_return_if_fail (interfacename[0] != '\0'); /* no empty string */
 444
 445   elementfactory->interfaces = g_list_prepend (elementfactory->interfaces, g_strdup (interfacename));
 446 }
 447 /**
 448  * gst_element_factory_get_pad_templates:
 449  * @factory: a #GstElementFactory
 450  *
 451  * Gets the #GList of padtemplates for this factory.
 452  *
 453  * Returns: the padtemplates
 454  */
 455 G_CONST_RETURN GList *
 456 gst_element_factory_get_pad_templates (GstElementFactory *factory)
 457 {
 458   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 459
 460   return factory->padtemplates;
 461 }
 462 /**
 463  * gst_element_factory_get_uri_type:
 464  * @factory: a #GstElementFactory
 465  *
 466  * Gets the type of URIs the element supports or GST_URI_UNKNOWN if none.
 467  *
 468  * Returns: type of URIs this element supports
 469  */
 470 guint
 471 gst_element_factory_get_uri_type (GstElementFactory *factory)
 472 {
 473   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), GST_URI_UNKNOWN);
 474
 475   return factory->uri_type;
 476 }
 477 /**
 478  * gst_element_factory_get_uri_protocols:
 479  * @factory: a #GstElementFactory
 480  *
 481  * Gets a NULL-terminated array of protocols this element supports or NULL, if
 482  * no protocols are supported. You may not change the contents of the returned
 483  * array as it is still ownt by the element factory. Use g_strdupv() if you want to.
 484  *
 485  * Returns: the supported protocols or NULL
 486  */
 487 gchar **
 488 gst_element_factory_get_uri_protocols (GstElementFactory *factory)
 489 {
 490   g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), NULL);
 491
 492   return factory->uri_protocols;
 493 }
 494 /**
 495  * gst_element_factory_can_src_caps :
 496  * @factory: factory to query
 497  * @caps: the caps to check
 498  *
 499  * Checks if the factory can source the given capability.
 500  *
 501  * Returns: true if it can src the capabilities
 502  */
 503 gboolean
 504 gst_element_factory_can_src_caps (GstElementFactory *factory,
 505                                  const GstCaps *caps)
 506 {
 507   GList *templates;
 508
 509   g_return_val_if_fail(factory != NULL, FALSE);
 510   g_return_val_if_fail(caps != NULL, FALSE);
 511
 512   templates = factory->padtemplates;
 513
 514   while (templates) {
 515     GstPadTemplate *template = (GstPadTemplate *)templates->data;
 516
 517     if (template->direction == GST_PAD_SRC) {
 518       if (gst_caps_is_always_compatible (GST_PAD_TEMPLATE_CAPS (template), caps))
 519         return TRUE;
 520     }
 521     templates = g_list_next (templates);
 522   }
 523
 524   return FALSE;
 525 }
 526 /**
 527  * gst_element_factory_can_sink_caps :
 528  * @factory: factory to query
 529  * @caps: the caps to check
 530  *
 531  * Checks if the factory can sink the given capability.
 532  *
 533  * Returns: true if it can sink the capabilities
 534  */
 535 gboolean
 536 gst_element_factory_can_sink_caps (GstElementFactory *factory,
 537                                   const GstCaps *caps)
 538 {
 539   GList *templates;
 540
 541   g_return_val_if_fail(factory != NULL, FALSE);
 542   g_return_val_if_fail(caps != NULL, FALSE);
 543
 544   templates = factory->padtemplates;
 545
 546   while (templates) {
 547     GstPadTemplate *template = (GstPadTemplate *)templates->data;
 548
 549     if (template->direction == GST_PAD_SINK) {
 550       if (gst_caps_is_always_compatible (caps, GST_PAD_TEMPLATE_CAPS (template)))
 551         return TRUE;
 552     }
 553     templates = g_list_next (templates);
 554   }
 555
 556   return FALSE;
 557 }
 558 static void
 559 gst_element_factory_unload_thyself (GstPluginFeature *feature)
 560 {
 561   GstElementFactory *factory;
 562
 563   factory = GST_ELEMENT_FACTORY (feature);
 564
 565   if (factory->type) {
 566     g_type_class_unref (g_type_class_peek (factory->type));
 567     factory->type = 0;
 568   }
 569 }