gst/gstelement.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2004 Wim Taymans <wim@fluendo.com>
   4  *
   5  * gstelement.c: The base element, all elements derive from this
   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:gstelement
  25  * @short_description: Abstract base class for all pipeline elements
  26  * @see_also: #GstElementFactory, #GstPad
  27  *
  28  * GstElement is the abstract base class needed to construct an element that
  29  * can be used in a GStreamer pipeline. Please refer to the plugin writers
  30  * guide for more information on creating #GstElement subclasses.
  31  *
  32  * The name of a #GstElement can be get with gst_element_get_name() and set with
  33  * gst_element_set_name().  For speed, GST_ELEMENT_NAME() can be used in the
  34  * core when using the appropriate locking. Do not use this in plug-ins or
  35  * applications in order to retain ABI compatibility.
  36  *
  37  * All elements have pads (of the type #GstPad).  These pads link to pads on
  38  * other elements.  #GstBuffer flow between these linked pads.
  39  * A #GstElement has a #GList of #GstPad structures for all their input (or sink)
  40  * and output (or source) pads.
  41  * Core and plug-in writers can add and remove pads with gst_element_add_pad()
  42  * and gst_element_remove_pad().
  43  *
  44  * A pad of an element can be retrieved by name with gst_element_get_pad().
  45  * An iterator of all pads can be retrieved with gst_element_iterate_pads().
  46  *
  47  * Elements can be linked through their pads.
  48  * If the link is straightforward, use the gst_element_link()
  49  * convenience function to link two elements, or gst_element_link_many()
  50  * for more elements in a row.
  51  * Use gst_element_link_filtered() to link two elements constrained by
  52  * a specified set of #GstCaps.
  53  * For finer control, use gst_element_link_pads() and
  54  * gst_element_link_pads_filtered() to specify the pads to link on
  55  * each element by name.
  56  *
  57  * Each element has a state (see #GstState).  You can get and set the state
  58  * of an element with gst_element_get_state() and gst_element_set_state().
  59  * Setting a state triggers a #GstStateChange. To get a string representation
  60  * of a #GstState, use gst_element_state_get_name().
  61  *
  62  * You can get and set a #GstClock on an element using gst_element_get_clock()
  63  * and gst_element_set_clock().
  64  * Some elements can provide a clock for the pipeline if
  65  * gst_element_provides_clock() returns %TRUE. With the
  66  * gst_element_provide_clock() method one can retrieve the clock provided by
  67  * such an element.
  68  * Not all elements require a clock to operate correctly. If
  69  * gst_element_requires_clock() returns %TRUE, a clock should be set on the
  70  * element with gst_element_set_clock().
  71  *
  72  * Note that clock slection and distribution is normally handled by the
  73  * toplevel #GstPipeline so the clock functions are only to be used in very
  74  * specific situations.
  75  *
  76  * Last reviewed on 2009-05-29 (0.10.24)
  77  */
  78
  79 #include "gst_private.h"
  80 #include <glib.h>
  81 #include <stdarg.h>
  82 #include <gobject/gvaluecollector.h>
  83
  84 #include "gstelement.h"
  85 #include "gstelementdetails.h"
  86 #include "gstenumtypes.h"
  87 #include "gstbus.h"
  88 #include "gstmarshal.h"
  89 #include "gsterror.h"
  90 #include "gstevent.h"
  91 #include "gstutils.h"
  92 #include "gstinfo.h"
  93 #include "gstvalue.h"
  94 #include "gst-i18n-lib.h"
  95
  96 /* Element signals and args */
  97 enum
  98 {
  99   PAD_ADDED,
 100   PAD_REMOVED,
 101   NO_MORE_PADS,
 102   /* add more above */
 103   LAST_SIGNAL
 104 };
 105
 106 enum
 107 {
 108   ARG_0
 109       /* FILL ME */
 110 };
 111
 112 #ifdef GST_DISABLE_DEPRECATED
 113 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
 114 #include <libxml/parser.h>
 115 xmlNodePtr gst_object_save_thyself (const GstObject * object,
 116     xmlNodePtr parent);
 117 GstObject *gst_object_load_thyself (xmlNodePtr parent);
 118 void gst_pad_load_and_link (xmlNodePtr self, GstObject * parent);
 119 #endif
 120 #endif
 121
 122 static void gst_element_class_init (GstElementClass * klass);
 123 static void gst_element_init (GstElement * element);
 124 static void gst_element_base_class_init (gpointer g_class);
 125 static void gst_element_base_class_finalize (gpointer g_class);
 126
 127 static void gst_element_dispose (GObject * object);
 128 static void gst_element_finalize (GObject * object);
 129
 130 static GstStateChangeReturn gst_element_change_state_func (GstElement * element,
 131     GstStateChange transition);
 132 static GstStateChangeReturn gst_element_get_state_func (GstElement * element,
 133     GstState * state, GstState * pending, GstClockTime timeout);
 134 static GstStateChangeReturn gst_element_set_state_func (GstElement * element,
 135     GstState state);
 136 static void gst_element_set_bus_func (GstElement * element, GstBus * bus);
 137
 138 static gboolean gst_element_default_send_event (GstElement * element,
 139     GstEvent * event);
 140 static gboolean gst_element_default_query (GstElement * element,
 141     GstQuery * query);
 142
 143 static GstPadTemplate
 144     * gst_element_class_get_request_pad_template (GstElementClass *
 145     element_class, const gchar * name);
 146
 147 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
 148 static xmlNodePtr gst_element_save_thyself (GstObject * object,
 149     xmlNodePtr parent);
 150 static void gst_element_restore_thyself (GstObject * parent, xmlNodePtr self);
 151 #endif
 152
 153 static GstObjectClass *parent_class = NULL;
 154 static guint gst_element_signals[LAST_SIGNAL] = { 0 };
 155
 156 /* this is used in gstelementfactory.c:gst_element_register() */
 157 GQuark _gst_elementclass_factory = 0;
 158
 159 GType
 160 gst_element_get_type (void)
 161 {
 162   static volatile gsize gst_element_type = 0;
 163
 164   if (g_once_init_enter (&gst_element_type)) {
 165     GType _type;
 166     static const GTypeInfo element_info = {
 167       sizeof (GstElementClass),
 168       gst_element_base_class_init,
 169       gst_element_base_class_finalize,
 170       (GClassInitFunc) gst_element_class_init,
 171       NULL,
 172       NULL,
 173       sizeof (GstElement),
 174       0,
 175       (GInstanceInitFunc) gst_element_init,
 176       NULL
 177     };
 178
 179     _type = g_type_register_static (GST_TYPE_OBJECT, "GstElement",
 180         &element_info, G_TYPE_FLAG_ABSTRACT);
 181
 182     _gst_elementclass_factory =
 183         g_quark_from_static_string ("GST_ELEMENTCLASS_FACTORY");
 184     g_once_init_leave (&gst_element_type, _type);
 185   }
 186   return gst_element_type;
 187 }
 188
 189 static void
 190 gst_element_class_init (GstElementClass * klass)
 191 {
 192   GObjectClass *gobject_class;
 193   GstObjectClass *gstobject_class;
 194
 195   gobject_class = (GObjectClass *) klass;
 196   gstobject_class = (GstObjectClass *) klass;
 197
 198   parent_class = g_type_class_peek_parent (klass);
 199
 200   /**
 201    * GstElement::pad-added:
 202    * @gstelement: the object which received the signal
 203    * @new_pad: the pad that has been added
 204    *
 205    * a new #GstPad has been added to the element. Note that this signal will
 206    * usually be emitted from the context of the streaming thread. Also keep in
 207    * mind that if you add new elements to the pipeline in the signal handler
 208    * you will need to set them to the desired target state with
 209    * gst_element_set() or gst_element_sync_state_with_parent().
 210    */
 211   gst_element_signals[PAD_ADDED] =
 212       g_signal_new ("pad-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 213       G_STRUCT_OFFSET (GstElementClass, pad_added), NULL, NULL,
 214       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
 215   /**
 216    * GstElement::pad-removed:
 217    * @gstelement: the object which received the signal
 218    * @old_pad: the pad that has been removed
 219    *
 220    * a #GstPad has been removed from the element
 221    */
 222   gst_element_signals[PAD_REMOVED] =
 223       g_signal_new ("pad-removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 224       G_STRUCT_OFFSET (GstElementClass, pad_removed), NULL, NULL,
 225       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
 226   /**
 227    * GstElement::no-more-pads:
 228    * @gstelement: the object which received the signal
 229    *
 230    * This signals that the element will not generate more dynamic pads.
 231    * Note that this signal will usually be emitted from the context of
 232    * the streaming thread.
 233    */
 234   gst_element_signals[NO_MORE_PADS] =
 235       g_signal_new ("no-more-pads", G_TYPE_FROM_CLASS (klass),
 236       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstElementClass, no_more_pads), NULL,
 237       NULL, gst_marshal_VOID__VOID, G_TYPE_NONE, 0);
 238
 239   gobject_class->dispose = gst_element_dispose;
 240   gobject_class->finalize = gst_element_finalize;
 241
 242 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
 243   gstobject_class->save_thyself =
 244       ((gpointer (*)(GstObject * object,
 245               gpointer self)) * GST_DEBUG_FUNCPTR (gst_element_save_thyself));
 246   gstobject_class->restore_thyself =
 247       ((void (*)(GstObject * object,
 248               gpointer self)) *GST_DEBUG_FUNCPTR (gst_element_restore_thyself));
 249 #endif
 250
 251   klass->change_state = GST_DEBUG_FUNCPTR (gst_element_change_state_func);
 252   klass->set_state = GST_DEBUG_FUNCPTR (gst_element_set_state_func);
 253   klass->get_state = GST_DEBUG_FUNCPTR (gst_element_get_state_func);
 254   klass->set_bus = GST_DEBUG_FUNCPTR (gst_element_set_bus_func);
 255   klass->query = GST_DEBUG_FUNCPTR (gst_element_default_query);
 256   klass->send_event = GST_DEBUG_FUNCPTR (gst_element_default_send_event);
 257   klass->numpadtemplates = 0;
 258
 259   klass->elementfactory = NULL;
 260 }
 261
 262 static void
 263 gst_element_base_class_init (gpointer g_class)
 264 {
 265   GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);
 266
 267   /* FIXME 0.11: Copy the element details and instead of clearing the
 268    * pad template list copy the list and increase the refcount of
 269    * the pad templates by one.
 270    *
 271    * This will make it possible to add pad templates and set element
 272    * details in the class_init functions and is the real GObject way
 273    * of doing things.
 274    * See http://bugzilla.gnome.org/show_bug.cgi?id=491501
 275    */
 276   memset (&element_class->details, 0, sizeof (GstElementDetails));
 277   element_class->meta_data = NULL;
 278   element_class->padtemplates = NULL;
 279
 280   /* set the factory, see gst_element_register() */
 281   element_class->elementfactory =
 282       g_type_get_qdata (G_TYPE_FROM_CLASS (element_class),
 283       _gst_elementclass_factory);
 284   GST_DEBUG ("type %s : factory %p", G_OBJECT_CLASS_NAME (element_class),
 285       element_class->elementfactory);
 286 }
 287
 288 static void
 289 gst_element_base_class_finalize (gpointer g_class)
 290 {
 291   GstElementClass *klass = GST_ELEMENT_CLASS (g_class);
 292
 293   g_list_foreach (klass->padtemplates, (GFunc) gst_object_unref, NULL);
 294   g_list_free (klass->padtemplates);
 295   __gst_element_details_clear (&klass->details);
 296   if (klass->meta_data) {
 297     gst_structure_free (klass->meta_data);
 298     klass->meta_data = NULL;
 299   }
 300 }
 301
 302 static void
 303 gst_element_init (GstElement * element)
 304 {
 305   GST_STATE (element) = GST_STATE_NULL;
 306   GST_STATE_TARGET (element) = GST_STATE_NULL;
 307   GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
 308   GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
 309   GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
 310
 311   /* FIXME 0.11: Store this directly in the instance struct */
 312   element->state_lock = g_slice_new (GStaticRecMutex);
 313   g_static_rec_mutex_init (element->state_lock);
 314   element->state_cond = g_cond_new ();
 315 }
 316
 317 /**
 318  * gst_element_release_request_pad:
 319  * @element: a #GstElement to release the request pad of.
 320  * @pad: the #GstPad to release.
 321  *
 322  * Makes the element free the previously requested pad as obtained
 323  * with gst_element_get_request_pad().
 324  *
 325  * This does not unref the pad. If the pad was created by using
 326  * gst_element_get_request_pad(), gst_element_release_request_pad() needs to be
 327  * followed by gst_object_unref() to free the @pad.
 328  *
 329  * MT safe.
 330  */
 331 void
 332 gst_element_release_request_pad (GstElement * element, GstPad * pad)
 333 {
 334   GstElementClass *oclass;
 335
 336   g_return_if_fail (GST_IS_ELEMENT (element));
 337   g_return_if_fail (GST_IS_PAD (pad));
 338
 339   oclass = GST_ELEMENT_GET_CLASS (element);
 340
 341   /* if the element implements a custom release function we call that, else we
 342    * simply remove the pad from the element */
 343   if (oclass->release_pad)
 344     (oclass->release_pad) (element, pad);
 345   else
 346     gst_element_remove_pad (element, pad);
 347 }
 348
 349 /**
 350  * gst_element_requires_clock:
 351  * @element: a #GstElement to query
 352  *
 353  * Query if the element requires a clock.
 354  *
 355  * Returns: %TRUE if the element requires a clock
 356  *
 357  * MT safe.
 358  */
 359 gboolean
 360 gst_element_requires_clock (GstElement * element)
 361 {
 362   gboolean result;
 363
 364   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
 365
 366   result = (GST_ELEMENT_GET_CLASS (element)->set_clock != NULL);
 367
 368   return result;
 369 }
 370
 371 /**
 372  * gst_element_provides_clock:
 373  * @element: a #GstElement to query
 374  *
 375  * Query if the element provides a clock. A #GstClock provided by an
 376  * element can be used as the global #GstClock for the pipeline.
 377  * An element that can provide a clock is only required to do so in the PAUSED
 378  * state, this means when it is fully negotiated and has allocated the resources
 379  * to operate the clock.
 380  *
 381  * Returns: %TRUE if the element provides a clock
 382  *
 383  * MT safe.
 384  */
 385 gboolean
 386 gst_element_provides_clock (GstElement * element)
 387 {
 388   gboolean result;
 389
 390   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
 391
 392   result = (GST_ELEMENT_GET_CLASS (element)->provide_clock != NULL);
 393
 394   return result;
 395 }
 396
 397 /**
 398  * gst_element_provide_clock:
 399  * @element: a #GstElement to query
 400  *
 401  * Get the clock provided by the given element.
 402  * <note>An element is only required to provide a clock in the PAUSED
 403  * state. Some elements can provide a clock in other states.</note>
 404  *
 405  * Returns: (transfer full): the GstClock provided by the element or %NULL
 406  * if no clock could be provided.  Unref after usage.
 407  *
 408  * MT safe.
 409  */
 410 GstClock *
 411 gst_element_provide_clock (GstElement * element)
 412 {
 413   GstClock *result = NULL;
 414   GstElementClass *oclass;
 415
 416   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 417
 418   oclass = GST_ELEMENT_GET_CLASS (element);
 419
 420   if (oclass->provide_clock)
 421     result = oclass->provide_clock (element);
 422
 423   return result;
 424 }
 425
 426 /**
 427  * gst_element_set_clock:
 428  * @element: a #GstElement to set the clock for.
 429  * @clock: the #GstClock to set for the element.
 430  *
 431  * Sets the clock for the element. This function increases the
 432  * refcount on the clock. Any previously set clock on the object
 433  * is unreffed.
 434  *
 435  * Returns: %TRUE if the element accepted the clock. An element can refuse a
 436  * clock when it, for example, is not able to slave its internal clock to the
 437  * @clock or when it requires a specific clock to operate.
 438  *
 439  * MT safe.
 440  */
 441 gboolean
 442 gst_element_set_clock (GstElement * element, GstClock * clock)
 443 {
 444   GstElementClass *oclass;
 445   gboolean res = TRUE;
 446   GstClock **clock_p;
 447
 448   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
 449   g_return_val_if_fail (clock == NULL || GST_IS_CLOCK (clock), FALSE);
 450
 451   oclass = GST_ELEMENT_GET_CLASS (element);
 452
 453   GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element, "setting clock %p", clock);
 454
 455   if (oclass->set_clock)
 456     res = oclass->set_clock (element, clock);
 457
 458   if (res) {
 459     /* only update the clock pointer if the element accepted the clock */
 460     GST_OBJECT_LOCK (element);
 461     clock_p = &element->clock;
 462     gst_object_replace ((GstObject **) clock_p, (GstObject *) clock);
 463     GST_OBJECT_UNLOCK (element);
 464   }
 465   return res;
 466 }
 467
 468 /**
 469  * gst_element_get_clock:
 470  * @element: a #GstElement to get the clock of.
 471  *
 472  * Gets the currently configured clock of the element. This is the clock as was
 473  * last set with gst_element_set_clock().
 474  *
 475  * Returns: (transfer full): the #GstClock of the element. unref after usage.
 476  *
 477  * MT safe.
 478  */
 479 GstClock *
 480 gst_element_get_clock (GstElement * element)
 481 {
 482   GstClock *result;
 483
 484   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 485
 486   GST_OBJECT_LOCK (element);
 487   if ((result = element->clock))
 488     gst_object_ref (result);
 489   GST_OBJECT_UNLOCK (element);
 490
 491   return result;
 492 }
 493
 494 /**
 495  * gst_element_set_base_time:
 496  * @element: a #GstElement.
 497  * @time: the base time to set.
 498  *
 499  * Set the base time of an element. See gst_element_get_base_time().
 500  *
 501  * MT safe.
 502  */
 503 void
 504 gst_element_set_base_time (GstElement * element, GstClockTime time)
 505 {
 506   GstClockTime old;
 507
 508   g_return_if_fail (GST_IS_ELEMENT (element));
 509
 510   GST_OBJECT_LOCK (element);
 511   old = element->base_time;
 512   element->base_time = time;
 513   GST_OBJECT_UNLOCK (element);
 514
 515   GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element,
 516       "set base_time=%" GST_TIME_FORMAT ", old %" GST_TIME_FORMAT,
 517       GST_TIME_ARGS (time), GST_TIME_ARGS (old));
 518 }
 519
 520 /**
 521  * gst_element_get_base_time:
 522  * @element: a #GstElement.
 523  *
 524  * Returns the base time of the element. The base time is the
 525  * absolute time of the clock when this element was last put to
 526  * PLAYING. Subtracting the base time from the clock time gives
 527  * the running time of the element.
 528  *
 529  * Returns: the base time of the element.
 530  *
 531  * MT safe.
 532  */
 533 GstClockTime
 534 gst_element_get_base_time (GstElement * element)
 535 {
 536   GstClockTime result;
 537
 538   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_CLOCK_TIME_NONE);
 539
 540   GST_OBJECT_LOCK (element);
 541   result = element->base_time;
 542   GST_OBJECT_UNLOCK (element);
 543
 544   return result;
 545 }
 546
 547 /**
 548  * gst_element_set_start_time:
 549  * @element: a #GstElement.
 550  * @time: the base time to set.
 551  *
 552  * Set the start time of an element. The start time of the element is the
 553  * running time of the element when it last went to the PAUSED state. In READY
 554  * or after a flushing seek, it is set to 0.
 555  *
 556  * Toplevel elements like #GstPipeline will manage the start_time and
 557  * base_time on its children. Setting the start_time to #GST_CLOCK_TIME_NONE
 558  * on such a toplevel element will disable the distribution of the base_time to
 559  * the children and can be useful if the application manages the base_time
 560  * itself, for example if you want to synchronize capture from multiple
 561  * pipelines, and you can also ensure that the pipelines have the same clock.
 562  *
 563  * MT safe.
 564  *
 565  * Since: 0.10.24
 566  */
 567 void
 568 gst_element_set_start_time (GstElement * element, GstClockTime time)
 569 {
 570   GstClockTime old;
 571
 572   g_return_if_fail (GST_IS_ELEMENT (element));
 573
 574   GST_OBJECT_LOCK (element);
 575   old = GST_ELEMENT_START_TIME (element);
 576   GST_ELEMENT_START_TIME (element) = time;
 577   GST_OBJECT_UNLOCK (element);
 578
 579   GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element,
 580       "set start_time=%" GST_TIME_FORMAT ", old %" GST_TIME_FORMAT,
 581       GST_TIME_ARGS (time), GST_TIME_ARGS (old));
 582 }
 583
 584 /**
 585  * gst_element_get_start_time:
 586  * @element: a #GstElement.
 587  *
 588  * Returns the start time of the element. The start time is the
 589  * running time of the clock when this element was last put to PAUSED.
 590  *
 591  * Usually the start_time is managed by a toplevel element such as
 592  * #GstPipeline.
 593  *
 594  * MT safe.
 595  *
 596  * Returns: the start time of the element.
 597  *
 598  * Since: 0.10.24
 599  */
 600 GstClockTime
 601 gst_element_get_start_time (GstElement * element)
 602 {
 603   GstClockTime result;
 604
 605   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_CLOCK_TIME_NONE);
 606
 607   GST_OBJECT_LOCK (element);
 608   result = GST_ELEMENT_START_TIME (element);
 609   GST_OBJECT_UNLOCK (element);
 610
 611   return result;
 612 }
 613
 614 /**
 615  * gst_element_is_indexable:
 616  * @element: a #GstElement.
 617  *
 618  * Queries if the element can be indexed.
 619  *
 620  * Returns: TRUE if the element can be indexed.
 621  *
 622  * MT safe.
 623  */
 624 gboolean
 625 gst_element_is_indexable (GstElement * element)
 626 {
 627   gboolean result;
 628
 629   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
 630
 631   result = (GST_ELEMENT_GET_CLASS (element)->set_index != NULL);
 632
 633   return result;
 634 }
 635
 636 /**
 637  * gst_element_set_index:
 638  * @element: a #GstElement.
 639  * @index: (transfer none): a #GstIndex.
 640  *
 641  * Set @index on the element. The refcount of the index
 642  * will be increased, any previously set index is unreffed.
 643  *
 644  * MT safe.
 645  */
 646 void
 647 gst_element_set_index (GstElement * element, GstIndex * index)
 648 {
 649   GstElementClass *oclass;
 650
 651   g_return_if_fail (GST_IS_ELEMENT (element));
 652   g_return_if_fail (index == NULL || GST_IS_INDEX (index));
 653
 654   oclass = GST_ELEMENT_GET_CLASS (element);
 655
 656   if (oclass->set_index)
 657     oclass->set_index (element, index);
 658 }
 659
 660 /**
 661  * gst_element_get_index:
 662  * @element: a #GstElement.
 663  *
 664  * Gets the index from the element.
 665  *
 666  * Returns: (transfer full): a #GstIndex or %NULL when no index was set on the
 667  * element. unref after usage.
 668  *
 669  * MT safe.
 670  */
 671 GstIndex *
 672 gst_element_get_index (GstElement * element)
 673 {
 674   GstElementClass *oclass;
 675   GstIndex *result = NULL;
 676
 677   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 678
 679   oclass = GST_ELEMENT_GET_CLASS (element);
 680
 681   if (oclass->get_index)
 682     result = oclass->get_index (element);
 683
 684   return result;
 685 }
 686
 687 /**
 688  * gst_element_add_pad:
 689  * @element: a #GstElement to add the pad to.
 690  * @pad: (transfer full): the #GstPad to add to the element.
 691  *
 692  * Adds a pad (link point) to @element. @pad's parent will be set to @element;
 693  * see gst_object_set_parent() for refcounting information.
 694  *
 695  * Pads are not automatically activated so elements should perform the needed
 696  * steps to activate the pad in case this pad is added in the PAUSED or PLAYING
 697  * state. See gst_pad_set_active() for more information about activating pads.
 698  *
 699  * The pad and the element should be unlocked when calling this function.
 700  *
 701  * This function will emit the #GstElement::pad-added signal on the element.
 702  *
 703  * Returns: %TRUE if the pad could be added. This function can fail when
 704  * a pad with the same name already existed or the pad already had another
 705  * parent.
 706  *
 707  * MT safe.
 708  */
 709 gboolean
 710 gst_element_add_pad (GstElement * element, GstPad * pad)
 711 {
 712   gchar *pad_name;
 713   gboolean flushing;
 714
 715   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
 716   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 717
 718   /* locking pad to look at the name */
 719   GST_OBJECT_LOCK (pad);
 720   pad_name = g_strdup (GST_PAD_NAME (pad));
 721   GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element, "adding pad '%s'",
 722       GST_STR_NULL (pad_name));
 723   flushing = GST_PAD_IS_FLUSHING (pad);
 724   GST_OBJECT_UNLOCK (pad);
 725
 726   /* then check to see if there's already a pad by that name here */
 727   GST_OBJECT_LOCK (element);
 728   if (G_UNLIKELY (!gst_object_check_uniqueness (element->pads, pad_name)))
 729     goto name_exists;
 730
 731   /* try to set the pad's parent */
 732   if (G_UNLIKELY (!gst_object_set_parent (GST_OBJECT_CAST (pad),
 733               GST_OBJECT_CAST (element))))
 734     goto had_parent;
 735
 736   /* check for flushing pads */
 737   if (flushing && (GST_STATE (element) > GST_STATE_READY ||
 738           GST_STATE_NEXT (element) == GST_STATE_PAUSED)) {
 739     g_warning ("adding flushing pad '%s' to running element '%s', you need to "
 740         "use gst_pad_set_active(pad,TRUE) before adding it.",
 741         GST_STR_NULL (pad_name), GST_ELEMENT_NAME (element));
 742     /* unset flushing */
 743     GST_OBJECT_LOCK (pad);
 744     GST_PAD_UNSET_FLUSHING (pad);
 745     GST_OBJECT_UNLOCK (pad);
 746   }
 747
 748   g_free (pad_name);
 749
 750   /* add it to the list */
 751   switch (gst_pad_get_direction (pad)) {
 752     case GST_PAD_SRC:
 753       element->srcpads = g_list_prepend (element->srcpads, pad);
 754       element->numsrcpads++;
 755       break;
 756     case GST_PAD_SINK:
 757       element->sinkpads = g_list_prepend (element->sinkpads, pad);
 758       element->numsinkpads++;
 759       break;
 760     default:
 761       goto no_direction;
 762   }
 763   element->pads = g_list_prepend (element->pads, pad);
 764   element->numpads++;
 765   element->pads_cookie++;
 766   GST_OBJECT_UNLOCK (element);
 767
 768   /* emit the PAD_ADDED signal */
 769   g_signal_emit (element, gst_element_signals[PAD_ADDED], 0, pad);
 770
 771   return TRUE;
 772
 773   /* ERROR cases */
 774 name_exists:
 775   {
 776     g_critical ("Padname %s is not unique in element %s, not adding",
 777         pad_name, GST_ELEMENT_NAME (element));
 778     GST_OBJECT_UNLOCK (element);
 779     g_free (pad_name);
 780     return FALSE;
 781   }
 782 had_parent:
 783   {
 784     g_critical
 785         ("Pad %s already has parent when trying to add to element %s",
 786         pad_name, GST_ELEMENT_NAME (element));
 787     GST_OBJECT_UNLOCK (element);
 788     g_free (pad_name);
 789     return FALSE;
 790   }
 791 no_direction:
 792   {
 793     GST_OBJECT_LOCK (pad);
 794     g_critical
 795         ("Trying to add pad %s to element %s, but it has no direction",
 796         GST_OBJECT_NAME (pad), GST_ELEMENT_NAME (element));
 797     GST_OBJECT_UNLOCK (pad);
 798     GST_OBJECT_UNLOCK (element);
 799     return FALSE;
 800   }
 801 }
 802
 803 /**
 804  * gst_element_remove_pad:
 805  * @element: a #GstElement to remove pad from.
 806  * @pad: (transfer none): the #GstPad to remove from the element.
 807  *
 808  * Removes @pad from @element. @pad will be destroyed if it has not been
 809  * referenced elsewhere using gst_object_unparent().
 810  *
 811  * This function is used by plugin developers and should not be used
 812  * by applications. Pads that were dynamically requested from elements
 813  * with gst_element_get_request_pad() should be released with the
 814  * gst_element_release_request_pad() function instead.
 815  *
 816  * Pads are not automatically deactivated so elements should perform the needed
 817  * steps to deactivate the pad in case this pad is removed in the PAUSED or
 818  * PLAYING state. See gst_pad_set_active() for more information about
 819  * deactivating pads.
 820  *
 821  * The pad and the element should be unlocked when calling this function.
 822  *
 823  * This function will emit the #GstElement::pad-removed signal on the element.
 824  *
 825  * Returns: %TRUE if the pad could be removed. Can return %FALSE if the
 826  * pad does not belong to the provided element.
 827  *
 828  * MT safe.
 829  */
 830 gboolean
 831 gst_element_remove_pad (GstElement * element, GstPad * pad)
 832 {
 833   GstPad *peer;
 834
 835   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
 836   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 837
 838   /* locking pad to look at the name and parent */
 839   GST_OBJECT_LOCK (pad);
 840   GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element, "removing pad '%s'",
 841       GST_STR_NULL (GST_PAD_NAME (pad)));
 842
 843   if (G_UNLIKELY (GST_PAD_PARENT (pad) != element))
 844     goto not_our_pad;
 845   GST_OBJECT_UNLOCK (pad);
 846
 847   /* unlink */
 848   if ((peer = gst_pad_get_peer (pad))) {
 849     /* window for MT unsafeness, someone else could unlink here
 850      * and then we call unlink with wrong pads. The unlink
 851      * function would catch this and safely return failed. */
 852     if (GST_PAD_IS_SRC (pad))
 853       gst_pad_unlink (pad, peer);
 854     else
 855       gst_pad_unlink (peer, pad);
 856
 857     gst_object_unref (peer);
 858   }
 859
 860   GST_OBJECT_LOCK (element);
 861   /* remove it from the list */
 862   switch (gst_pad_get_direction (pad)) {
 863     case GST_PAD_SRC:
 864       element->srcpads = g_list_remove (element->srcpads, pad);
 865       element->numsrcpads--;
 866       break;
 867     case GST_PAD_SINK:
 868       element->sinkpads = g_list_remove (element->sinkpads, pad);
 869       element->numsinkpads--;
 870       break;
 871     default:
 872       g_critical ("Removing pad without direction???");
 873       break;
 874   }
 875   element->pads = g_list_remove (element->pads, pad);
 876   element->numpads--;
 877   element->pads_cookie++;
 878   GST_OBJECT_UNLOCK (element);
 879
 880   /* emit the PAD_REMOVED signal before unparenting and losing the last ref. */
 881   g_signal_emit (element, gst_element_signals[PAD_REMOVED], 0, pad);
 882
 883   gst_object_unparent (GST_OBJECT_CAST (pad));
 884
 885   return TRUE;
 886
 887   /* ERRORS */
 888 not_our_pad:
 889   {
 890     /* FIXME, locking order? */
 891     GST_OBJECT_LOCK (element);
 892     g_critical ("Padname %s:%s does not belong to element %s when removing",
 893         GST_DEBUG_PAD_NAME (pad), GST_ELEMENT_NAME (element));
 894     GST_OBJECT_UNLOCK (element);
 895     GST_OBJECT_UNLOCK (pad);
 896     return FALSE;
 897   }
 898 }
 899
 900 /**
 901  * gst_element_no_more_pads:
 902  * @element: a #GstElement
 903  *
 904  * Use this function to signal that the element does not expect any more pads
 905  * to show up in the current pipeline. This function should be called whenever
 906  * pads have been added by the element itself. Elements with #GST_PAD_SOMETIMES
 907  * pad templates use this in combination with autopluggers to figure out that
 908  * the element is done initializing its pads.
 909  *
 910  * This function emits the #GstElement::no-more-pads signal.
 911  *
 912  * MT safe.
 913  */
 914 void
 915 gst_element_no_more_pads (GstElement * element)
 916 {
 917   g_return_if_fail (GST_IS_ELEMENT (element));
 918
 919   g_signal_emit (element, gst_element_signals[NO_MORE_PADS], 0);
 920 }
 921
 922 static gint
 923 pad_compare_name (GstPad * pad1, const gchar * name)
 924 {
 925   gint result;
 926
 927   GST_OBJECT_LOCK (pad1);
 928   result = strcmp (GST_PAD_NAME (pad1), name);
 929   GST_OBJECT_UNLOCK (pad1);
 930
 931   return result;
 932 }
 933
 934 /**
 935  * gst_element_get_static_pad:
 936  * @element: a #GstElement to find a static pad of.
 937  * @name: the name of the static #GstPad to retrieve.
 938  *
 939  * Retrieves a pad from @element by name. This version only retrieves
 940  * already-existing (i.e. 'static') pads.
 941  *
 942  * Returns: (transfer full): the requested #GstPad if found, otherwise %NULL.
 943  *     unref after usage.
 944  *
 945  * MT safe.
 946  */
 947 GstPad *
 948 gst_element_get_static_pad (GstElement * element, const gchar * name)
 949 {
 950   GList *find;
 951   GstPad *result = NULL;
 952
 953   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 954   g_return_val_if_fail (name != NULL, NULL);
 955
 956   GST_OBJECT_LOCK (element);
 957   find =
 958       g_list_find_custom (element->pads, name, (GCompareFunc) pad_compare_name);
 959   if (find) {
 960     result = GST_PAD_CAST (find->data);
 961     gst_object_ref (result);
 962   }
 963
 964   if (result == NULL) {
 965     GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "no such pad '%s' in element \"%s\"",
 966         name, GST_ELEMENT_NAME (element));
 967   } else {
 968     GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
 969         GST_ELEMENT_NAME (element), name);
 970   }
 971   GST_OBJECT_UNLOCK (element);
 972
 973   return result;
 974 }
 975
 976 static GstPad *
 977 _gst_element_request_pad (GstElement * element, GstPadTemplate * templ,
 978     const gchar * name, const GstCaps * caps)
 979 {
 980   GstPad *newpad = NULL;
 981   GstElementClass *oclass;
 982
 983   oclass = GST_ELEMENT_GET_CLASS (element);
 984
 985 #ifndef G_DISABLE_CHECKS
 986   /* Some sanity checking here */
 987   if (name) {
 988     GstPad *pad;
 989
 990     /* Is this the template name? */
 991     if (strstr (name, "%") || !strchr (templ->name_template, '%')) {
 992       g_return_val_if_fail (strcmp (name, templ->name_template) == 0, NULL);
 993     } else {
 994       const gchar *str, *data;
 995       gchar *endptr;
 996
 997       /* Otherwise check if it's a valid name for the name template */
 998       str = strchr (templ->name_template, '%');
 999       g_return_val_if_fail (str != NULL, NULL);
1000       g_return_val_if_fail (strncmp (templ->name_template, name,
1001               str - templ->name_template) == 0, NULL);
1002       g_return_val_if_fail (strlen (name) > str - templ->name_template, NULL);
1003
1004       data = name + (str - templ->name_template);
1005
1006       /* Can either be %s or %d or %u, do sanity checking for %d */
1007       if (*(str + 1) == 'd') {
1008         gint64 tmp;
1009
1010         /* it's an int */
1011         tmp = g_ascii_strtoll (data, &endptr, 10);
1012         g_return_val_if_fail (tmp >= G_MININT && tmp <= G_MAXINT
1013             && *endptr == '\0', NULL);
1014       } else if (*(str + 1) == 'u') {
1015         guint64 tmp;
1016
1017         /* it's an int */
1018         tmp = g_ascii_strtoull (data, &endptr, 10);
1019         g_return_val_if_fail (tmp <= G_MAXUINT && *endptr == '\0', NULL);
1020       }
1021     }
1022
1023     pad = gst_element_get_static_pad (element, name);
1024     if (pad) {
1025       gst_object_unref (pad);
1026       /* FIXME 0.11: Change this to g_return_val_if_fail() */
1027       g_critical ("Element %s already has a pad named %s, the behaviour of "
1028           " gst_element_get_request_pad() for existing pads is undefined!",
1029           GST_ELEMENT_NAME (element), name);
1030     }
1031   }
1032 #endif
1033
1034   if (oclass->request_new_pad_full)
1035     newpad = (oclass->request_new_pad_full) (element, templ, name, caps);
1036   else if (oclass->request_new_pad)
1037     newpad = (oclass->request_new_pad) (element, templ, name);
1038
1039   if (newpad)
1040     gst_object_ref (newpad);
1041
1042   return newpad;
1043 }
1044
1045 /**
1046  * gst_element_get_request_pad:
1047  * @element: a #GstElement to find a request pad of.
1048  * @name: the name of the request #GstPad to retrieve.
1049  *
1050  * Retrieves a pad from the element by name. This version only retrieves
1051  * request pads. The pad should be released with
1052  * gst_element_release_request_pad().
1053  *
1054  * This method is slow and will be deprecated in the future. New code should
1055  * use gst_element_request_pad() with the requested template.
1056  *
1057  * Returns: (transfer full): requested #GstPad if found, otherwise %NULL.
1058  *     Release after usage.
1059  */
1060 GstPad *
1061 gst_element_get_request_pad (GstElement * element, const gchar * name)
1062 {
1063   GstPadTemplate *templ = NULL;
1064   GstPad *pad;
1065   const gchar *req_name = NULL;
1066   gboolean templ_found = FALSE;
1067   GList *list;
1068   const gchar *data;
1069   gchar *str, *endptr = NULL;
1070   GstElementClass *class;
1071
1072   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1073   g_return_val_if_fail (name != NULL, NULL);
1074
1075   class = GST_ELEMENT_GET_CLASS (element);
1076
1077   /* if the name contains a %, we assume it's the complete template name. Get
1078    * the template and try to get a pad */
1079   if (strstr (name, "%")) {
1080     templ = gst_element_class_get_request_pad_template (class, name);
1081     req_name = NULL;
1082     if (templ)
1083       templ_found = TRUE;
1084   } else {
1085     /* there is no % in the name, try to find a matching template */
1086     list = class->padtemplates;
1087     while (!templ_found && list) {
1088       templ = (GstPadTemplate *) list->data;
1089       if (templ->presence == GST_PAD_REQUEST) {
1090         GST_CAT_DEBUG (GST_CAT_PADS, "comparing %s to %s", name,
1091             templ->name_template);
1092         /* see if we find an exact match */
1093         if (strcmp (name, templ->name_template) == 0) {
1094           templ_found = TRUE;
1095           req_name = name;
1096           break;
1097         }
1098         /* Because of sanity checks in gst_pad_template_new(), we know that %s
1099            and %d and %u, occurring at the end of the name_template, are the only
1100            possibilities. */
1101         else if ((str = strchr (templ->name_template, '%'))
1102             && strncmp (templ->name_template, name,
1103                 str - templ->name_template) == 0
1104             && strlen (name) > str - templ->name_template) {
1105           data = name + (str - templ->name_template);
1106           if (*(str + 1) == 'd') {
1107             glong tmp;
1108
1109             /* it's an int */
1110             tmp = strtol (data, &endptr, 10);
1111             if (tmp != G_MINLONG && tmp != G_MAXLONG && endptr &&
1112                 *endptr == '\0') {
1113               templ_found = TRUE;
1114               req_name = name;
1115               break;
1116             }
1117           } else if (*(str + 1) == 'u') {
1118             gulong tmp;
1119
1120             /* it's an int */
1121             tmp = strtoul (data, &endptr, 10);
1122             if (tmp != G_MAXULONG && endptr && *endptr == '\0') {
1123               templ_found = TRUE;
1124               req_name = name;
1125               break;
1126             }
1127           } else {
1128             /* it's a string */
1129             templ_found = TRUE;
1130             req_name = name;
1131             break;
1132           }
1133         }
1134       }
1135       list = list->next;
1136     }
1137   }
1138
1139   if (!templ_found)
1140     return NULL;
1141
1142   pad = _gst_element_request_pad (element, templ, req_name, NULL);
1143
1144   return pad;
1145 }
1146
1147 /**
1148  * gst_element_request_pad:
1149  * @element: a #GstElement to find a request pad of.
1150  * @templ: a #GstPadTemplate of which we want a pad of.
1151  * @name: (transfer none) (allow-none): the name of the request #GstPad
1152  * to retrieve. Can be %NULL.
1153  * @caps: (transfer none) (allow-none): the caps of the pad we want to
1154  * request. Can be %NULL.
1155  *
1156  * Retrieves a request pad from the element according to the provided template.
1157  *
1158  * If the @caps are specified and the element implements thew new
1159  * request_new_pad_full virtual method, the element will use them to select
1160  * which pad to create.
1161  *
1162  * The pad should be released with gst_element_release_request_pad().
1163  *
1164  * Returns: (transfer full): requested #GstPad if found, otherwise %NULL.
1165  *     Release after usage.
1166  *
1167  * Since: 0.10.32
1168  */
1169 GstPad *
1170 gst_element_request_pad (GstElement * element,
1171     GstPadTemplate * templ, const gchar * name, const GstCaps * caps)
1172 {
1173   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1174   g_return_val_if_fail (templ != NULL, NULL);
1175
1176   return _gst_element_request_pad (element, templ, name, caps);
1177 }
1178
1179 /**
1180  * gst_element_get_pad:
1181  * @element: a #GstElement.
1182  * @name: the name of the pad to retrieve.
1183  *
1184  * Retrieves a pad from @element by name. Tries gst_element_get_static_pad()
1185  * first, then gst_element_get_request_pad().
1186  *
1187  * Deprecated: This function is deprecated as it's unclear if the reference
1188  * to the result pad should be released with gst_object_unref() in case of a static pad
1189  * or gst_element_release_request_pad() in case of a request pad.
1190  * Use gst_element_get_static_pad() or gst_element_get_request_pad() instead.
1191  *
1192  * Returns: (transfer full): the #GstPad if found, otherwise %NULL. Unref or Release after usage,
1193  * depending on the type of the pad.
1194  */
1195 #ifndef GST_REMOVE_DEPRECATED
1196 #ifdef GST_DISABLE_DEPRECATED
1197 GstPad *gst_element_get_pad (GstElement * element, const gchar * name);
1198 #endif
1199 GstPad *
1200 gst_element_get_pad (GstElement * element, const gchar * name)
1201 {
1202   GstPad *pad;
1203
1204   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1205   g_return_val_if_fail (name != NULL, NULL);
1206
1207   pad = gst_element_get_static_pad (element, name);
1208   if (!pad)
1209     pad = gst_element_get_request_pad (element, name);
1210
1211   return pad;
1212 }
1213 #endif /* GST_REMOVE_DEPRECATED */
1214
1215 static GstIteratorItem
1216 iterate_pad (GstIterator * it, GstPad * pad)
1217 {
1218   gst_object_ref (pad);
1219   return GST_ITERATOR_ITEM_PASS;
1220 }
1221
1222 static GstIterator *
1223 gst_element_iterate_pad_list (GstElement * element, GList ** padlist)
1224 {
1225   GstIterator *result;
1226
1227   GST_OBJECT_LOCK (element);
1228   gst_object_ref (element);
1229   result = gst_iterator_new_list (GST_TYPE_PAD,
1230       GST_OBJECT_GET_LOCK (element),
1231       &element->pads_cookie,
1232       padlist,
1233       element,
1234       (GstIteratorItemFunction) iterate_pad,
1235       (GstIteratorDisposeFunction) gst_object_unref);
1236   GST_OBJECT_UNLOCK (element);
1237
1238   return result;
1239 }
1240
1241 /**
1242  * gst_element_iterate_pads:
1243  * @element: a #GstElement to iterate pads of.
1244  *
1245  * Retrieves an iterattor of @element's pads. The iterator should
1246  * be freed after usage.
1247  *
1248  * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1249  *     after use.
1250  *
1251  * MT safe.
1252  */
1253 GstIterator *
1254 gst_element_iterate_pads (GstElement * element)
1255 {
1256   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1257
1258   return gst_element_iterate_pad_list (element, &element->pads);
1259 }
1260
1261 /**
1262  * gst_element_iterate_src_pads:
1263  * @element: a #GstElement.
1264  *
1265  * Retrieves an iterator of @element's source pads.
1266  *
1267  * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1268  *     after use.
1269  *
1270  * MT safe.
1271  */
1272 GstIterator *
1273 gst_element_iterate_src_pads (GstElement * element)
1274 {
1275   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1276
1277   return gst_element_iterate_pad_list (element, &element->srcpads);
1278 }
1279
1280 /**
1281  * gst_element_iterate_sink_pads:
1282  * @element: a #GstElement.
1283  *
1284  * Retrieves an iterator of @element's sink pads.
1285  *
1286  * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1287  *     after use.
1288  *
1289  * MT safe.
1290  */
1291 GstIterator *
1292 gst_element_iterate_sink_pads (GstElement * element)
1293 {
1294   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1295
1296   return gst_element_iterate_pad_list (element, &element->sinkpads);
1297 }
1298
1299 /**
1300  * gst_element_class_add_pad_template:
1301  * @klass: the #GstElementClass to add the pad template to.
1302  * @templ: (transfer none): a #GstPadTemplate to add to the element class.
1303  *
1304  * Adds a padtemplate to an element class. This is mainly used in the _base_init
1305  * functions of classes.
1306  */
1307 void
1308 gst_element_class_add_pad_template (GstElementClass * klass,
1309     GstPadTemplate * templ)
1310 {
1311   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1312   g_return_if_fail (GST_IS_PAD_TEMPLATE (templ));
1313
1314   /* FIXME 0.11: allow replacing the pad templates by
1315    * calling this with the same name as an already existing pad
1316    * template. For this we _must_ _not_ ref the added pad template
1317    * a second time and _must_ document that this function takes
1318    * ownership of the pad template. Otherwise we will leak pad templates
1319    * or the caller unref's the pad template and it disappears */
1320   /* avoid registering pad templates with the same name */
1321   g_return_if_fail (gst_element_class_get_pad_template (klass,
1322           templ->name_template) == NULL);
1323
1324   klass->padtemplates = g_list_append (klass->padtemplates,
1325       gst_object_ref (templ));
1326   klass->numpadtemplates++;
1327 }
1328
1329 static void
1330 gst_element_class_add_meta_data (GstElementClass * klass,
1331     const gchar * key, const gchar * value)
1332 {
1333   if (!klass->meta_data) {
1334     /* FIXME: use a quark for "metadata" */
1335     klass->meta_data = gst_structure_empty_new ("metadata");
1336   }
1337
1338   gst_structure_set ((GstStructure *) klass->meta_data,
1339       key, G_TYPE_STRING, value, NULL);
1340 }
1341
1342 /**
1343  * gst_element_class_set_documentation_uri:
1344  * @klass: class to set details for
1345  * @uri: uri of element documentation
1346  *
1347  * Set uri pointing to user documentation. Applications can use this to show
1348  * help for e.g. effects to users.
1349  *
1350  * Since: 0.10.31
1351  */
1352 void
1353 gst_element_class_set_documentation_uri (GstElementClass * klass,
1354     const gchar * uri)
1355 {
1356   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1357
1358   gst_element_class_add_meta_data (klass, "doc-uri", uri);
1359 }
1360
1361 /**
1362  * gst_element_class_set_icon_name:
1363  * @klass: class to set details for
1364  * @name: name of an icon
1365  *
1366  * Elements that bridge to certain other products can include an icon of that
1367  * used product. Application can show the icon in menus/selectors to help
1368  * identifying specific elements.
1369  *
1370  * Since: 0.10.31
1371  */
1372 void
1373 gst_element_class_set_icon_name (GstElementClass * klass, const gchar * name)
1374 {
1375   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1376
1377   gst_element_class_add_meta_data (klass, "icon-name", name);
1378 }
1379
1380 /* FIXME-0.11: deprecate and remove gst_element_class_set_details*() */
1381 /**
1382  * gst_element_class_set_details:
1383  * @klass: class to set details for
1384  * @details: details to set
1385  *
1386  * Sets the detailed information for a #GstElementClass.
1387  * <note>This function is for use in _base_init functions only.</note>
1388  *
1389  * The @details are copied.
1390  *
1391  * Deprecated: Use gst_element_class_set_details_simple() instead.
1392  */
1393 #ifndef GST_REMOVE_DEPRECATED
1394 #ifdef GST_DISABLE_DEPRECATED
1395 void gst_element_class_set_details (GstElementClass * klass,
1396     const GstElementDetails * details);
1397 #endif
1398 void
1399 gst_element_class_set_details (GstElementClass * klass,
1400     const GstElementDetails * details)
1401 {
1402   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1403   g_return_if_fail (GST_IS_ELEMENT_DETAILS (details));
1404
1405   __gst_element_details_copy (&klass->details, details);
1406 }
1407 #endif
1408
1409 /**
1410  * gst_element_class_set_details_simple:
1411  * @klass: class to set details for
1412  * @longname: The long English name of the element. E.g. "File Sink"
1413  * @classification: String describing the type of element, as an unordered list
1414  * separated with slashes ('/'). See draft-klass.txt of the design docs
1415  * for more details and common types. E.g: "Sink/File"
1416  * @description: Sentence describing the purpose of the element.
1417  * E.g: "Write stream to a file"
1418  * @author: Name and contact details of the author(s). Use \n to separate
1419  * multiple author details. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
1420  *
1421  * Sets the detailed information for a #GstElementClass. Simpler version of
1422  * gst_element_class_set_details() that generates less linker overhead.
1423  * <note>This function is for use in _base_init functions only.</note>
1424  *
1425  * The detail parameter strings are copied into the #GstElementDetails for
1426  * the element class.
1427  *
1428  * Since: 0.10.14
1429  */
1430 void
1431 gst_element_class_set_details_simple (GstElementClass * klass,
1432     const gchar * longname, const gchar * classification,
1433     const gchar * description, const gchar * author)
1434 {
1435   const GstElementDetails details =
1436       GST_ELEMENT_DETAILS ((gchar *) longname, (gchar *) classification,
1437       (gchar *) description, (gchar *) author);
1438
1439   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1440
1441   __gst_element_details_copy (&klass->details, &details);
1442 }
1443
1444 /**
1445  * gst_element_class_get_pad_template_list:
1446  * @element_class: a #GstElementClass to get pad templates of.
1447  *
1448  * Retrieves a list of the pad templates associated with @element_class. The
1449  * list must not be modified by the calling code.
1450  * <note>If you use this function in the #GInstanceInitFunc of an object class
1451  * that has subclasses, make sure to pass the g_class parameter of the
1452  * #GInstanceInitFunc here.</note>
1453  *
1454  * Returns: (transfer none) (element-type Gst.PadTemplate): the #GList of
1455  *     pad templates.
1456  */
1457 GList *
1458 gst_element_class_get_pad_template_list (GstElementClass * element_class)
1459 {
1460   g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1461
1462   return element_class->padtemplates;
1463 }
1464
1465 /**
1466  * gst_element_class_get_pad_template:
1467  * @element_class: a #GstElementClass to get the pad template of.
1468  * @name: the name of the #GstPadTemplate to get.
1469  *
1470  * Retrieves a padtemplate from @element_class with the given name.
1471  * <note>If you use this function in the #GInstanceInitFunc of an object class
1472  * that has subclasses, make sure to pass the g_class parameter of the
1473  * #GInstanceInitFunc here.</note>
1474  *
1475  * Returns: (transfer none): the #GstPadTemplate with the given name, or %NULL
1476  *     if none was found. No unreferencing is necessary.
1477  */
1478 GstPadTemplate *
1479 gst_element_class_get_pad_template (GstElementClass *
1480     element_class, const gchar * name)
1481 {
1482   GList *padlist;
1483
1484   g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1485   g_return_val_if_fail (name != NULL, NULL);
1486
1487   padlist = element_class->padtemplates;
1488
1489   while (padlist) {
1490     GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
1491
1492     if (strcmp (padtempl->name_template, name) == 0)
1493       return padtempl;
1494
1495     padlist = g_list_next (padlist);
1496   }
1497
1498   return NULL;
1499 }
1500
1501 static GstPadTemplate *
1502 gst_element_class_get_request_pad_template (GstElementClass *
1503     element_class, const gchar * name)
1504 {
1505   GstPadTemplate *tmpl;
1506
1507   tmpl = gst_element_class_get_pad_template (element_class, name);
1508   if (tmpl != NULL && tmpl->presence == GST_PAD_REQUEST)
1509     return tmpl;
1510
1511   return NULL;
1512 }
1513
1514 /* get a random pad on element of the given direction.
1515  * The pad is random in a sense that it is the first pad that is (optionaly) linked.
1516  */
1517 static GstPad *
1518 gst_element_get_random_pad (GstElement * element,
1519     gboolean need_linked, GstPadDirection dir)
1520 {
1521   GstPad *result = NULL;
1522   GList *pads;
1523
1524   GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "getting a random pad");
1525
1526   switch (dir) {
1527     case GST_PAD_SRC:
1528       GST_OBJECT_LOCK (element);
1529       pads = element->srcpads;
1530       break;
1531     case GST_PAD_SINK:
1532       GST_OBJECT_LOCK (element);
1533       pads = element->sinkpads;
1534       break;
1535     default:
1536       goto wrong_direction;
1537   }
1538   for (; pads; pads = g_list_next (pads)) {
1539     GstPad *pad = GST_PAD_CAST (pads->data);
1540
1541     GST_OBJECT_LOCK (pad);
1542     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "checking pad %s:%s",
1543         GST_DEBUG_PAD_NAME (pad));
1544
1545     if (need_linked && !GST_PAD_IS_LINKED (pad)) {
1546       /* if we require a linked pad, and it is not linked, continue the
1547        * search */
1548       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is not linked",
1549           GST_DEBUG_PAD_NAME (pad));
1550       GST_OBJECT_UNLOCK (pad);
1551       continue;
1552     } else {
1553       /* found a pad, stop search */
1554       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
1555           GST_DEBUG_PAD_NAME (pad));
1556       GST_OBJECT_UNLOCK (pad);
1557       result = pad;
1558       break;
1559     }
1560   }
1561   if (result)
1562     gst_object_ref (result);
1563
1564   GST_OBJECT_UNLOCK (element);
1565
1566   return result;
1567
1568   /* ERROR handling */
1569 wrong_direction:
1570   {
1571     g_warning ("unknown pad direction %d", dir);
1572     return NULL;
1573   }
1574 }
1575
1576 static gboolean
1577 gst_element_default_send_event (GstElement * element, GstEvent * event)
1578 {
1579   gboolean result = FALSE;
1580   GstPad *pad;
1581
1582   pad = GST_EVENT_IS_DOWNSTREAM (event) ?
1583       gst_element_get_random_pad (element, TRUE, GST_PAD_SRC) :
1584       gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1585
1586   if (pad) {
1587     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1588         "pushing %s event to random %s pad %s:%s",
1589         GST_EVENT_TYPE_NAME (event),
1590         (GST_PAD_DIRECTION (pad) == GST_PAD_SRC ? "src" : "sink"),
1591         GST_DEBUG_PAD_NAME (pad));
1592
1593     result = gst_pad_push_event (pad, event);
1594     gst_object_unref (pad);
1595   } else {
1596     GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "can't send %s event on element %s",
1597         GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1598   }
1599   return result;
1600 }
1601
1602 /**
1603  * gst_element_send_event:
1604  * @element: a #GstElement to send the event to.
1605  * @event: (transfer full): the #GstEvent to send to the element.
1606  *
1607  * Sends an event to an element. If the element doesn't implement an
1608  * event handler, the event will be pushed on a random linked sink pad for
1609  * upstream events or a random linked source pad for downstream events.
1610  *
1611  * This function takes owership of the provided event so you should
1612  * gst_event_ref() it if you want to reuse the event after this call.
1613  *
1614  * Returns: %TRUE if the event was handled.
1615  *
1616  * MT safe.
1617  */
1618 gboolean
1619 gst_element_send_event (GstElement * element, GstEvent * event)
1620 {
1621   GstElementClass *oclass;
1622   gboolean result = FALSE;
1623
1624   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1625   g_return_val_if_fail (event != NULL, FALSE);
1626
1627   oclass = GST_ELEMENT_GET_CLASS (element);
1628
1629   GST_STATE_LOCK (element);
1630   if (oclass->send_event) {
1631     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send %s event on element %s",
1632         GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1633     result = oclass->send_event (element, event);
1634   } else {
1635     result = gst_element_default_send_event (element, event);
1636   }
1637   GST_STATE_UNLOCK (element);
1638
1639   return result;
1640 }
1641
1642 /**
1643  * gst_element_seek:
1644  * @element: a #GstElement to send the event to.
1645  * @rate: The new playback rate
1646  * @format: The format of the seek values
1647  * @flags: The optional seek flags.
1648  * @cur_type: The type and flags for the new current position
1649  * @cur: The value of the new current position
1650  * @stop_type: The type and flags for the new stop position
1651  * @stop: The value of the new stop position
1652  *
1653  * Sends a seek event to an element. See gst_event_new_seek() for the details of
1654  * the parameters. The seek event is sent to the element using
1655  * gst_element_send_event().
1656  *
1657  * Returns: %TRUE if the event was handled.
1658  *
1659  * MT safe.
1660  */
1661 gboolean
1662 gst_element_seek (GstElement * element, gdouble rate, GstFormat format,
1663     GstSeekFlags flags, GstSeekType cur_type, gint64 cur,
1664     GstSeekType stop_type, gint64 stop)
1665 {
1666   GstEvent *event;
1667   gboolean result;
1668
1669   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1670
1671   event =
1672       gst_event_new_seek (rate, format, flags, cur_type, cur, stop_type, stop);
1673   result = gst_element_send_event (element, event);
1674
1675   return result;
1676 }
1677
1678 /**
1679  * gst_element_get_query_types:
1680  * @element: a #GstElement to query
1681  *
1682  * Get an array of query types from the element.
1683  * If the element doesn't implement a query types function,
1684  * the query will be forwarded to the peer of a random linked sink pad.
1685  *
1686  * Returns: An array of #GstQueryType elements that should not
1687  * be freed or modified.
1688  *
1689  * MT safe.
1690  */
1691 const GstQueryType *
1692 gst_element_get_query_types (GstElement * element)
1693 {
1694   GstElementClass *oclass;
1695   const GstQueryType *result = NULL;
1696
1697   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1698
1699   oclass = GST_ELEMENT_GET_CLASS (element);
1700
1701   if (oclass->get_query_types) {
1702     result = oclass->get_query_types (element);
1703   } else {
1704     GstPad *pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1705
1706     if (pad) {
1707       GstPad *peer = gst_pad_get_peer (pad);
1708
1709       if (peer) {
1710         result = gst_pad_get_query_types (peer);
1711
1712         gst_object_unref (peer);
1713       }
1714       gst_object_unref (pad);
1715     }
1716   }
1717   return result;
1718 }
1719
1720 static gboolean
1721 gst_element_default_query (GstElement * element, GstQuery * query)
1722 {
1723   gboolean result = FALSE;
1724   GstPad *pad;
1725
1726   pad = gst_element_get_random_pad (element, FALSE, GST_PAD_SRC);
1727   if (pad) {
1728     result = gst_pad_query (pad, query);
1729
1730     gst_object_unref (pad);
1731   } else {
1732     pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1733     if (pad) {
1734       GstPad *peer = gst_pad_get_peer (pad);
1735
1736       if (peer) {
1737         result = gst_pad_query (peer, query);
1738
1739         gst_object_unref (peer);
1740       }
1741       gst_object_unref (pad);
1742     }
1743   }
1744   return result;
1745 }
1746
1747 /**
1748  * gst_element_query:
1749  * @element: a #GstElement to perform the query on.
1750  * @query: (transfer none): the #GstQuery.
1751  *
1752  * Performs a query on the given element.
1753  *
1754  * For elements that don't implement a query handler, this function
1755  * forwards the query to a random srcpad or to the peer of a
1756  * random linked sinkpad of this element.
1757  *
1758  * Please note that some queries might need a running pipeline to work.
1759  *
1760  * Returns: TRUE if the query could be performed.
1761  *
1762  * MT safe.
1763  */
1764 gboolean
1765 gst_element_query (GstElement * element, GstQuery * query)
1766 {
1767   GstElementClass *oclass;
1768   gboolean result = FALSE;
1769
1770   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1771   g_return_val_if_fail (query != NULL, FALSE);
1772
1773   oclass = GST_ELEMENT_GET_CLASS (element);
1774
1775   if (oclass->query) {
1776     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send query on element %s",
1777         GST_ELEMENT_NAME (element));
1778     result = oclass->query (element, query);
1779   } else {
1780     result = gst_element_default_query (element, query);
1781   }
1782   return result;
1783 }
1784
1785 /**
1786  * gst_element_post_message:
1787  * @element: a #GstElement posting the message
1788  * @message: (transfer full): a #GstMessage to post
1789  *
1790  * Post a message on the element's #GstBus. This function takes ownership of the
1791  * message; if you want to access the message after this call, you should add an
1792  * additional reference before calling.
1793  *
1794  * Returns: %TRUE if the message was successfully posted. The function returns
1795  * %FALSE if the element did not have a bus.
1796  *
1797  * MT safe.
1798  */
1799 gboolean
1800 gst_element_post_message (GstElement * element, GstMessage * message)
1801 {
1802   GstBus *bus;
1803   gboolean result = FALSE;
1804
1805   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1806   g_return_val_if_fail (message != NULL, FALSE);
1807
1808   GST_OBJECT_LOCK (element);
1809   bus = element->bus;
1810
1811   if (G_UNLIKELY (bus == NULL))
1812     goto no_bus;
1813
1814   gst_object_ref (bus);
1815   GST_OBJECT_UNLOCK (element);
1816
1817   /* we release the element lock when posting the message so that any
1818    * (synchronous) message handlers can operate on the element */
1819   result = gst_bus_post (bus, message);
1820   gst_object_unref (bus);
1821
1822   return result;
1823
1824   /* ERRORS */
1825 no_bus:
1826   {
1827     GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element,
1828         "not posting message %p: no bus", message);
1829     GST_OBJECT_UNLOCK (element);
1830     gst_message_unref (message);
1831     return FALSE;
1832   }
1833 }
1834
1835 /**
1836  * _gst_element_error_printf:
1837  * @format: the printf-like format to use, or %NULL
1838  *
1839  * This function is only used internally by the gst_element_error() macro.
1840  *
1841  * Returns: (transfer full): a newly allocated string, or %NULL if the format
1842  *     was %NULL or ""
1843  *
1844  * MT safe.
1845  */
1846 gchar *
1847 _gst_element_error_printf (const gchar * format, ...)
1848 {
1849   va_list args;
1850   gchar *buffer;
1851
1852   if (format == NULL)
1853     return NULL;
1854   if (format[0] == 0)
1855     return NULL;
1856
1857   va_start (args, format);
1858   buffer = g_strdup_vprintf (format, args);
1859   va_end (args);
1860   return buffer;
1861 }
1862
1863 /**
1864  * gst_element_message_full:
1865  * @element:  a #GstElement to send message from
1866  * @type:     the #GstMessageType
1867  * @domain:   the GStreamer GError domain this message belongs to
1868  * @code:     the GError code belonging to the domain
1869  * @text:     (allow-none) (transfer full): an allocated text string to be used
1870  *            as a replacement for the default message connected to code,
1871  *            or %NULL
1872  * @debug:    (allow-none) (transfer full): an allocated debug message to be
1873  *            used as a replacement for the default debugging information,
1874  *            or %NULL
1875  * @file:     the source code file where the error was generated
1876  * @function: the source code function where the error was generated
1877  * @line:     the source code line where the error was generated
1878  *
1879  * Post an error, warning or info message on the bus from inside an element.
1880  *
1881  * @type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or
1882  * #GST_MESSAGE_INFO.
1883  *
1884  * MT safe.
1885  */
1886 void gst_element_message_full
1887     (GstElement * element, GstMessageType type,
1888     GQuark domain, gint code, gchar * text,
1889     gchar * debug, const gchar * file, const gchar * function, gint line)
1890 {
1891   GError *gerror = NULL;
1892   gchar *name;
1893   gchar *sent_text;
1894   gchar *sent_debug;
1895   gboolean has_debug = TRUE;
1896   GstMessage *message = NULL;
1897
1898   /* checks */
1899   GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element, "start");
1900   g_return_if_fail (GST_IS_ELEMENT (element));
1901   g_return_if_fail ((type == GST_MESSAGE_ERROR) ||
1902       (type == GST_MESSAGE_WARNING) || (type == GST_MESSAGE_INFO));
1903
1904   /* check if we send the given text or the default error text */
1905   if ((text == NULL) || (text[0] == 0)) {
1906     /* text could have come from g_strdup_printf (""); */
1907     g_free (text);
1908     sent_text = gst_error_get_message (domain, code);
1909   } else
1910     sent_text = text;
1911
1912   /* construct a sent_debug with extra information from source */
1913   if ((debug == NULL) || (debug[0] == 0)) {
1914     /* debug could have come from g_strdup_printf (""); */
1915     has_debug = FALSE;
1916   }
1917
1918   name = gst_object_get_path_string (GST_OBJECT_CAST (element));
1919   if (has_debug)
1920     sent_debug = g_strdup_printf ("%s(%d): %s (): %s:\n%s",
1921         file, line, function, name, debug);
1922   else
1923     sent_debug = g_strdup_printf ("%s(%d): %s (): %s",
1924         file, line, function, name);
1925   g_free (name);
1926   g_free (debug);
1927
1928   /* create gerror and post message */
1929   GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posting message: %s",
1930       sent_text);
1931   gerror = g_error_new_literal (domain, code, sent_text);
1932
1933   switch (type) {
1934     case GST_MESSAGE_ERROR:
1935       message =
1936           gst_message_new_error (GST_OBJECT_CAST (element), gerror, sent_debug);
1937       break;
1938     case GST_MESSAGE_WARNING:
1939       message = gst_message_new_warning (GST_OBJECT_CAST (element), gerror,
1940           sent_debug);
1941       break;
1942     case GST_MESSAGE_INFO:
1943       message = gst_message_new_info (GST_OBJECT_CAST (element), gerror,
1944           sent_debug);
1945       break;
1946     default:
1947       g_assert_not_reached ();
1948       break;
1949   }
1950   gst_element_post_message (element, message);
1951
1952   GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posted %s message: %s",
1953       (type == GST_MESSAGE_ERROR ? "error" : "warning"), sent_text);
1954
1955   /* cleanup */
1956   g_error_free (gerror);
1957   g_free (sent_debug);
1958   g_free (sent_text);
1959 }
1960
1961 /**
1962  * gst_element_is_locked_state:
1963  * @element: a #GstElement.
1964  *
1965  * Checks if the state of an element is locked.
1966  * If the state of an element is locked, state changes of the parent don't
1967  * affect the element.
1968  * This way you can leave currently unused elements inside bins. Just lock their
1969  * state before changing the state from #GST_STATE_NULL.
1970  *
1971  * MT safe.
1972  *
1973  * Returns: TRUE, if the element's state is locked.
1974  */
1975 gboolean
1976 gst_element_is_locked_state (GstElement * element)
1977 {
1978   gboolean result;
1979
1980   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1981
1982   GST_OBJECT_LOCK (element);
1983   result = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
1984   GST_OBJECT_UNLOCK (element);
1985
1986   return result;
1987 }
1988
1989 /**
1990  * gst_element_set_locked_state:
1991  * @element: a #GstElement
1992  * @locked_state: TRUE to lock the element's state
1993  *
1994  * Locks the state of an element, so state changes of the parent don't affect
1995  * this element anymore.
1996  *
1997  * MT safe.
1998  *
1999  * Returns: TRUE if the state was changed, FALSE if bad parameters were given
2000  * or the elements state-locking needed no change.
2001  */
2002 gboolean
2003 gst_element_set_locked_state (GstElement * element, gboolean locked_state)
2004 {
2005   gboolean old;
2006
2007   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2008
2009   GST_OBJECT_LOCK (element);
2010   old = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
2011
2012   if (G_UNLIKELY (old == locked_state))
2013     goto was_ok;
2014
2015   if (locked_state) {
2016     GST_CAT_DEBUG (GST_CAT_STATES, "locking state of element %s",
2017         GST_ELEMENT_NAME (element));
2018     GST_OBJECT_FLAG_SET (element, GST_ELEMENT_LOCKED_STATE);
2019   } else {
2020     GST_CAT_DEBUG (GST_CAT_STATES, "unlocking state of element %s",
2021         GST_ELEMENT_NAME (element));
2022     GST_OBJECT_FLAG_UNSET (element, GST_ELEMENT_LOCKED_STATE);
2023   }
2024   GST_OBJECT_UNLOCK (element);
2025
2026   return TRUE;
2027
2028 was_ok:
2029   {
2030     GST_CAT_DEBUG (GST_CAT_STATES,
2031         "elements %s was already in locked state %d",
2032         GST_ELEMENT_NAME (element), old);
2033     GST_OBJECT_UNLOCK (element);
2034
2035     return FALSE;
2036   }
2037 }
2038
2039 /**
2040  * gst_element_sync_state_with_parent:
2041  * @element: a #GstElement.
2042  *
2043  * Tries to change the state of the element to the same as its parent.
2044  * If this function returns FALSE, the state of element is undefined.
2045  *
2046  * Returns: TRUE, if the element's state could be synced to the parent's state.
2047  *
2048  * MT safe.
2049  */
2050 gboolean
2051 gst_element_sync_state_with_parent (GstElement * element)
2052 {
2053   GstElement *parent;
2054   GstState target;
2055   GstStateChangeReturn ret;
2056
2057   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2058
2059   if ((parent = GST_ELEMENT_CAST (gst_element_get_parent (element)))) {
2060     GstState parent_current, parent_pending;
2061
2062     GST_OBJECT_LOCK (parent);
2063     parent_current = GST_STATE (parent);
2064     parent_pending = GST_STATE_PENDING (parent);
2065     GST_OBJECT_UNLOCK (parent);
2066
2067     /* set to pending if there is one, else we set it to the current state of
2068      * the parent */
2069     if (parent_pending != GST_STATE_VOID_PENDING)
2070       target = parent_pending;
2071     else
2072       target = parent_current;
2073
2074     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2075         "syncing state (%s) to parent %s %s (%s, %s)",
2076         gst_element_state_get_name (GST_STATE (element)),
2077         GST_ELEMENT_NAME (parent), gst_element_state_get_name (target),
2078         gst_element_state_get_name (parent_current),
2079         gst_element_state_get_name (parent_pending));
2080
2081     ret = gst_element_set_state (element, target);
2082     if (ret == GST_STATE_CHANGE_FAILURE)
2083       goto failed;
2084
2085     gst_object_unref (parent);
2086
2087     return TRUE;
2088   } else {
2089     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "element has no parent");
2090   }
2091   return FALSE;
2092
2093   /* ERROR */
2094 failed:
2095   {
2096     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2097         "syncing state failed (%s)",
2098         gst_element_state_change_return_get_name (ret));
2099     gst_object_unref (parent);
2100     return FALSE;
2101   }
2102 }
2103
2104 /* MT safe */
2105 static GstStateChangeReturn
2106 gst_element_get_state_func (GstElement * element,
2107     GstState * state, GstState * pending, GstClockTime timeout)
2108 {
2109   GstStateChangeReturn ret = GST_STATE_CHANGE_FAILURE;
2110   GstState old_pending;
2111
2112   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "getting state, timeout %"
2113       GST_TIME_FORMAT, GST_TIME_ARGS (timeout));
2114
2115   GST_OBJECT_LOCK (element);
2116   ret = GST_STATE_RETURN (element);
2117   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "RETURN is %s",
2118       gst_element_state_change_return_get_name (ret));
2119
2120   /* we got an error, report immediately */
2121   if (ret == GST_STATE_CHANGE_FAILURE)
2122     goto done;
2123
2124   /* we got no_preroll, report immediatly */
2125   if (ret == GST_STATE_CHANGE_NO_PREROLL)
2126     goto done;
2127
2128   /* no need to wait async if we are not async */
2129   if (ret != GST_STATE_CHANGE_ASYNC)
2130     goto done;
2131
2132   old_pending = GST_STATE_PENDING (element);
2133   if (old_pending != GST_STATE_VOID_PENDING) {
2134     GTimeVal *timeval, abstimeout;
2135     guint32 cookie;
2136
2137     if (timeout != GST_CLOCK_TIME_NONE) {
2138       glong add = timeout / 1000;
2139
2140       if (add == 0)
2141         goto done;
2142
2143       /* make timeout absolute */
2144       g_get_current_time (&abstimeout);
2145       g_time_val_add (&abstimeout, add);
2146       timeval = &abstimeout;
2147     } else {
2148       timeval = NULL;
2149     }
2150     /* get cookie to detect state changes during waiting */
2151     cookie = element->state_cookie;
2152
2153     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2154         "waiting for element to commit state");
2155
2156     /* we have a pending state change, wait for it to complete */
2157     if (!GST_STATE_TIMED_WAIT (element, timeval)) {
2158       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "timed out");
2159       /* timeout triggered */
2160       ret = GST_STATE_CHANGE_ASYNC;
2161     } else {
2162       if (cookie != element->state_cookie)
2163         goto interrupted;
2164
2165       /* could be success or failure */
2166       if (old_pending == GST_STATE (element)) {
2167         GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got success");
2168         ret = GST_STATE_CHANGE_SUCCESS;
2169       } else {
2170         GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got failure");
2171         ret = GST_STATE_CHANGE_FAILURE;
2172       }
2173     }
2174     /* if nothing is pending anymore we can return SUCCESS */
2175     if (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING) {
2176       GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "nothing pending");
2177       ret = GST_STATE_CHANGE_SUCCESS;
2178     }
2179   }
2180
2181 done:
2182   if (state)
2183     *state = GST_STATE (element);
2184   if (pending)
2185     *pending = GST_STATE_PENDING (element);
2186
2187   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2188       "state current: %s, pending: %s, result: %s",
2189       gst_element_state_get_name (GST_STATE (element)),
2190       gst_element_state_get_name (GST_STATE_PENDING (element)),
2191       gst_element_state_change_return_get_name (ret));
2192   GST_OBJECT_UNLOCK (element);
2193
2194   return ret;
2195
2196 interrupted:
2197   {
2198     if (state)
2199       *state = GST_STATE_VOID_PENDING;
2200     if (pending)
2201       *pending = GST_STATE_VOID_PENDING;
2202
2203     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "interruped");
2204
2205     GST_OBJECT_UNLOCK (element);
2206
2207     return GST_STATE_CHANGE_FAILURE;
2208   }
2209 }
2210
2211 /**
2212  * gst_element_get_state:
2213  * @element: a #GstElement to get the state of.
2214  * @state: (out) (allow-none): a pointer to #GstState to hold the state.
2215  *     Can be %NULL.
2216  * @pending: (out) (allow-none): a pointer to #GstState to hold the pending
2217  *     state. Can be %NULL.
2218  * @timeout: a #GstClockTime to specify the timeout for an async
2219  *           state change or %GST_CLOCK_TIME_NONE for infinite timeout.
2220  *
2221  * Gets the state of the element.
2222  *
2223  * For elements that performed an ASYNC state change, as reported by
2224  * gst_element_set_state(), this function will block up to the
2225  * specified timeout value for the state change to complete.
2226  * If the element completes the state change or goes into
2227  * an error, this function returns immediately with a return value of
2228  * %GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively.
2229  *
2230  * For elements that did not return %GST_STATE_CHANGE_ASYNC, this function
2231  * returns the current and pending state immediately.
2232  *
2233  * This function returns %GST_STATE_CHANGE_NO_PREROLL if the element
2234  * successfully changed its state but is not able to provide data yet.
2235  * This mostly happens for live sources that only produce data in
2236  * %GST_STATE_PLAYING. While the state change return is equivalent to
2237  * %GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that
2238  * some sink elements might not be able to complete their state change because
2239  * an element is not producing data to complete the preroll. When setting the
2240  * element to playing, the preroll will complete and playback will start.
2241  *
2242  * Returns: %GST_STATE_CHANGE_SUCCESS if the element has no more pending state
2243  *          and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the
2244  *          element is still performing a state change or
2245  *          %GST_STATE_CHANGE_FAILURE if the last state change failed.
2246  *
2247  * MT safe.
2248  */
2249 GstStateChangeReturn
2250 gst_element_get_state (GstElement * element,
2251     GstState * state, GstState * pending, GstClockTime timeout)
2252 {
2253   GstElementClass *oclass;
2254   GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2255
2256   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2257
2258   oclass = GST_ELEMENT_GET_CLASS (element);
2259
2260   if (oclass->get_state)
2261     result = (oclass->get_state) (element, state, pending, timeout);
2262
2263   return result;
2264 }
2265
2266 /**
2267  * gst_element_abort_state:
2268  * @element: a #GstElement to abort the state of.
2269  *
2270  * Abort the state change of the element. This function is used
2271  * by elements that do asynchronous state changes and find out
2272  * something is wrong.
2273  *
2274  * This function should be called with the STATE_LOCK held.
2275  *
2276  * MT safe.
2277  */
2278 void
2279 gst_element_abort_state (GstElement * element)
2280 {
2281   GstState pending;
2282
2283 #ifndef GST_DISABLE_GST_DEBUG
2284   GstState old_state;
2285 #endif
2286
2287   g_return_if_fail (GST_IS_ELEMENT (element));
2288
2289   GST_OBJECT_LOCK (element);
2290   pending = GST_STATE_PENDING (element);
2291
2292   if (pending == GST_STATE_VOID_PENDING ||
2293       GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2294     goto nothing_aborted;
2295
2296 #ifndef GST_DISABLE_GST_DEBUG
2297   old_state = GST_STATE (element);
2298
2299   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2300       "aborting state from %s to %s", gst_element_state_get_name (old_state),
2301       gst_element_state_get_name (pending));
2302 #endif
2303
2304   /* flag error */
2305   GST_STATE_RETURN (element) = GST_STATE_CHANGE_FAILURE;
2306
2307   GST_STATE_BROADCAST (element);
2308   GST_OBJECT_UNLOCK (element);
2309
2310   return;
2311
2312 nothing_aborted:
2313   {
2314     GST_OBJECT_UNLOCK (element);
2315     return;
2316   }
2317 }
2318
2319 /**
2320  * gst_element_continue_state:
2321  * @element: a #GstElement to continue the state change of.
2322  * @ret: The previous state return value
2323  *
2324  * Commit the state change of the element and proceed to the next
2325  * pending state if any. This function is used
2326  * by elements that do asynchronous state changes.
2327  * The core will normally call this method automatically when an
2328  * element returned %GST_STATE_CHANGE_SUCCESS from the state change function.
2329  *
2330  * If after calling this method the element still has not reached
2331  * the pending state, the next state change is performed.
2332  *
2333  * This method is used internally and should normally not be called by plugins
2334  * or applications.
2335  *
2336  * Returns: The result of the commit state change.
2337  *
2338  * MT safe.
2339  */
2340 GstStateChangeReturn
2341 gst_element_continue_state (GstElement * element, GstStateChangeReturn ret)
2342 {
2343   GstStateChangeReturn old_ret;
2344   GstState old_state, old_next;
2345   GstState current, next, pending;
2346   GstMessage *message;
2347   GstStateChange transition;
2348
2349   GST_OBJECT_LOCK (element);
2350   old_ret = GST_STATE_RETURN (element);
2351   GST_STATE_RETURN (element) = ret;
2352   pending = GST_STATE_PENDING (element);
2353
2354   /* check if there is something to commit */
2355   if (pending == GST_STATE_VOID_PENDING)
2356     goto nothing_pending;
2357
2358   old_state = GST_STATE (element);
2359   /* this is the state we should go to next */
2360   old_next = GST_STATE_NEXT (element);
2361   /* update current state */
2362   current = GST_STATE (element) = old_next;
2363
2364   /* see if we reached the final state */
2365   if (pending == current)
2366     goto complete;
2367
2368   next = GST_STATE_GET_NEXT (current, pending);
2369   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2370
2371   GST_STATE_NEXT (element) = next;
2372   /* mark busy */
2373   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2374   GST_OBJECT_UNLOCK (element);
2375
2376   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2377       "committing state from %s to %s, pending %s, next %s",
2378       gst_element_state_get_name (old_state),
2379       gst_element_state_get_name (old_next),
2380       gst_element_state_get_name (pending), gst_element_state_get_name (next));
2381
2382   message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2383       old_state, old_next, pending);
2384   gst_element_post_message (element, message);
2385
2386   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2387       "continue state change %s to %s, final %s",
2388       gst_element_state_get_name (current),
2389       gst_element_state_get_name (next), gst_element_state_get_name (pending));
2390
2391   ret = gst_element_change_state (element, transition);
2392
2393   return ret;
2394
2395 nothing_pending:
2396   {
2397     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "nothing pending");
2398     GST_OBJECT_UNLOCK (element);
2399     return ret;
2400   }
2401 complete:
2402   {
2403     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2404     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2405
2406     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2407         "completed state change to %s", gst_element_state_get_name (pending));
2408     GST_OBJECT_UNLOCK (element);
2409
2410     /* don't post silly messages with the same state. This can happen
2411      * when an element state is changed to what it already was. For bins
2412      * this can be the result of a lost state, which we check with the
2413      * previous return value.
2414      * We do signal the cond though as a _get_state() might be blocking
2415      * on it. */
2416     if (old_state != old_next || old_ret == GST_STATE_CHANGE_ASYNC) {
2417       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2418           "posting state-changed %s to %s",
2419           gst_element_state_get_name (old_state),
2420           gst_element_state_get_name (old_next));
2421       message =
2422           gst_message_new_state_changed (GST_OBJECT_CAST (element), old_state,
2423           old_next, GST_STATE_VOID_PENDING);
2424       gst_element_post_message (element, message);
2425     }
2426
2427     GST_STATE_BROADCAST (element);
2428
2429     return ret;
2430   }
2431 }
2432
2433 /**
2434  * gst_element_lost_state_full:
2435  * @element: a #GstElement the state is lost of
2436  * @new_base_time: if a new base time should be distributed
2437  *
2438  * Brings the element to the lost state. The current state of the
2439  * element is copied to the pending state so that any call to
2440  * gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC.
2441  *
2442  * An ASYNC_START message is posted with indication to distribute a new
2443  * base_time to the element when @new_base_time is %TRUE.
2444  * If the element was PLAYING, it will go to PAUSED. The element
2445  * will be restored to its PLAYING state by the parent pipeline when it
2446  * prerolls again.
2447  *
2448  * This is mostly used for elements that lost their preroll buffer
2449  * in the %GST_STATE_PAUSED or %GST_STATE_PLAYING state after a flush,
2450  * they will go to their pending state again when a new preroll buffer is
2451  * queued. This function can only be called when the element is currently
2452  * not in error or an async state change.
2453  *
2454  * This function is used internally and should normally not be called from
2455  * plugins or applications.
2456  *
2457  * MT safe.
2458  *
2459  * Since: 0.10.24
2460  */
2461 void
2462 gst_element_lost_state_full (GstElement * element, gboolean new_base_time)
2463 {
2464   GstState old_state, new_state;
2465   GstMessage *message;
2466
2467   g_return_if_fail (GST_IS_ELEMENT (element));
2468
2469   GST_OBJECT_LOCK (element);
2470   if (GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2471     goto nothing_lost;
2472
2473   if (GST_STATE_PENDING (element) != GST_STATE_VOID_PENDING)
2474     goto only_async_start;
2475
2476   old_state = GST_STATE (element);
2477
2478   /* when we were PLAYING, the new state is PAUSED. We will also not
2479    * automatically go to PLAYING but let the parent bin(s) set us to PLAYING
2480    * when we preroll. */
2481   if (old_state > GST_STATE_PAUSED)
2482     new_state = GST_STATE_PAUSED;
2483   else
2484     new_state = old_state;
2485
2486   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2487       "lost state of %s to %s", gst_element_state_get_name (old_state),
2488       gst_element_state_get_name (new_state));
2489
2490   GST_STATE (element) = new_state;
2491   GST_STATE_NEXT (element) = new_state;
2492   GST_STATE_PENDING (element) = new_state;
2493   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2494   if (new_base_time)
2495     GST_ELEMENT_START_TIME (element) = 0;
2496   GST_OBJECT_UNLOCK (element);
2497
2498   message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2499       new_state, new_state, new_state);
2500   gst_element_post_message (element, message);
2501
2502   message =
2503       gst_message_new_async_start (GST_OBJECT_CAST (element), new_base_time);
2504   gst_element_post_message (element, message);
2505
2506   return;
2507
2508 nothing_lost:
2509   {
2510     GST_OBJECT_UNLOCK (element);
2511     return;
2512   }
2513 only_async_start:
2514   {
2515     GST_OBJECT_UNLOCK (element);
2516
2517     message = gst_message_new_async_start (GST_OBJECT_CAST (element), TRUE);
2518     gst_element_post_message (element, message);
2519     return;
2520   }
2521 }
2522
2523 /**
2524  * gst_element_lost_state:
2525  * @element: a #GstElement the state is lost of
2526  *
2527  * Brings the element to the lost state. This function calls
2528  * gst_element_lost_state_full() with the new_base_time set to %TRUE.
2529  *
2530  * This function is used internally and should normally not be called from
2531  * plugins or applications.
2532  *
2533  * MT safe.
2534  */
2535 void
2536 gst_element_lost_state (GstElement * element)
2537 {
2538   gst_element_lost_state_full (element, TRUE);
2539 }
2540
2541 /**
2542  * gst_element_set_state:
2543  * @element: a #GstElement to change state of.
2544  * @state: the element's new #GstState.
2545  *
2546  * Sets the state of the element. This function will try to set the
2547  * requested state by going through all the intermediary states and calling
2548  * the class's state change function for each.
2549  *
2550  * This function can return #GST_STATE_CHANGE_ASYNC, in which case the
2551  * element will perform the remainder of the state change asynchronously in
2552  * another thread.
2553  * An application can use gst_element_get_state() to wait for the completion
2554  * of the state change or it can wait for a state change message on the bus.
2555  *
2556  * State changes to %GST_STATE_READY or %GST_STATE_NULL never return
2557  * #GST_STATE_CHANGE_ASYNC.
2558  *
2559  * Returns: Result of the state change using #GstStateChangeReturn.
2560  *
2561  * MT safe.
2562  */
2563 GstStateChangeReturn
2564 gst_element_set_state (GstElement * element, GstState state)
2565 {
2566   GstElementClass *oclass;
2567   GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2568
2569   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2570
2571   oclass = GST_ELEMENT_GET_CLASS (element);
2572
2573   if (oclass->set_state)
2574     result = (oclass->set_state) (element, state);
2575
2576   return result;
2577 }
2578
2579 /*
2580  * default set state function, calculates the next state based
2581  * on current state and calls the change_state function
2582  */
2583 static GstStateChangeReturn
2584 gst_element_set_state_func (GstElement * element, GstState state)
2585 {
2586   GstState current, next, old_pending;
2587   GstStateChangeReturn ret;
2588   GstStateChange transition;
2589   GstStateChangeReturn old_ret;
2590
2591   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2592
2593   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "set_state to %s",
2594       gst_element_state_get_name (state));
2595
2596   /* state lock is taken to protect the set_state() and get_state()
2597    * procedures, it does not lock any variables. */
2598   GST_STATE_LOCK (element);
2599
2600   /* now calculate how to get to the new state */
2601   GST_OBJECT_LOCK (element);
2602   old_ret = GST_STATE_RETURN (element);
2603   /* previous state change returned an error, remove all pending
2604    * and next states */
2605   if (old_ret == GST_STATE_CHANGE_FAILURE) {
2606     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2607     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2608     GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
2609   }
2610
2611   current = GST_STATE (element);
2612   next = GST_STATE_NEXT (element);
2613   old_pending = GST_STATE_PENDING (element);
2614
2615   /* this is the (new) state we should go to. TARGET is the last state we set on
2616    * the element. */
2617   if (state != GST_STATE_TARGET (element)) {
2618     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2619         "setting target state to %s", gst_element_state_get_name (state));
2620     GST_STATE_TARGET (element) = state;
2621     /* increment state cookie so that we can track each state change. We only do
2622      * this if this is actually a new state change. */
2623     element->state_cookie++;
2624   }
2625   GST_STATE_PENDING (element) = state;
2626
2627   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2628       "current %s, old_pending %s, next %s, old return %s",
2629       gst_element_state_get_name (current),
2630       gst_element_state_get_name (old_pending),
2631       gst_element_state_get_name (next),
2632       gst_element_state_change_return_get_name (old_ret));
2633
2634   /* if the element was busy doing a state change, we just update the
2635    * target state, it'll get to it async then. */
2636   if (old_pending != GST_STATE_VOID_PENDING) {
2637     /* upwards state change will happen ASYNC */
2638     if (old_pending <= state)
2639       goto was_busy;
2640     /* element is going to this state already */
2641     else if (next == state)
2642       goto was_busy;
2643     /* element was performing an ASYNC upward state change and
2644      * we request to go downward again. Start from the next pending
2645      * state then. */
2646     else if (next > state
2647         && GST_STATE_RETURN (element) == GST_STATE_CHANGE_ASYNC) {
2648       current = next;
2649     }
2650   }
2651   next = GST_STATE_GET_NEXT (current, state);
2652   /* now we store the next state */
2653   GST_STATE_NEXT (element) = next;
2654   /* mark busy, we need to check that there is actually a state change
2655    * to be done else we could accidentally override SUCCESS/NO_PREROLL and
2656    * the default element change_state function has no way to know what the
2657    * old value was... could consider this a FIXME...*/
2658   if (current != next)
2659     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2660
2661   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2662
2663   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2664       "%s: setting state from %s to %s",
2665       (next != state ? "intermediate" : "final"),
2666       gst_element_state_get_name (current), gst_element_state_get_name (next));
2667
2668   /* now signal any waiters, they will error since the cookie was incremented */
2669   GST_STATE_BROADCAST (element);
2670
2671   GST_OBJECT_UNLOCK (element);
2672
2673   ret = gst_element_change_state (element, transition);
2674
2675   GST_STATE_UNLOCK (element);
2676
2677   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "returned %s",
2678       gst_element_state_change_return_get_name (ret));
2679
2680   return ret;
2681
2682 was_busy:
2683   {
2684     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2685     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2686         "element was busy with async state change");
2687     GST_OBJECT_UNLOCK (element);
2688
2689     GST_STATE_UNLOCK (element);
2690
2691     return GST_STATE_CHANGE_ASYNC;
2692   }
2693 }
2694
2695 /**
2696  * gst_element_change_state:
2697  * @element: a #GstElement
2698  * @transition: the requested transition
2699  *
2700  * Perform @transition on @element.
2701  *
2702  * This function must be called with STATE_LOCK held and is mainly used
2703  * internally.
2704  *
2705  * Returns: the #GstStateChangeReturn of the state transition.
2706  */
2707 GstStateChangeReturn
2708 gst_element_change_state (GstElement * element, GstStateChange transition)
2709 {
2710   GstElementClass *oclass;
2711   GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
2712
2713   oclass = GST_ELEMENT_GET_CLASS (element);
2714
2715   /* call the state change function so it can set the state */
2716   if (oclass->change_state)
2717     ret = (oclass->change_state) (element, transition);
2718   else
2719     ret = GST_STATE_CHANGE_FAILURE;
2720
2721   switch (ret) {
2722     case GST_STATE_CHANGE_FAILURE:
2723       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2724           "have FAILURE change_state return");
2725       /* state change failure */
2726       gst_element_abort_state (element);
2727       break;
2728     case GST_STATE_CHANGE_ASYNC:
2729     {
2730       GstState target;
2731
2732       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2733           "element will change state ASYNC");
2734
2735       target = GST_STATE_TARGET (element);
2736
2737       if (target > GST_STATE_READY)
2738         goto async;
2739
2740       /* else we just continue the state change downwards */
2741       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2742           "forcing commit state %s <= %s",
2743           gst_element_state_get_name (target),
2744           gst_element_state_get_name (GST_STATE_READY));
2745
2746       ret = gst_element_continue_state (element, GST_STATE_CHANGE_SUCCESS);
2747       break;
2748     }
2749     case GST_STATE_CHANGE_SUCCESS:
2750       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2751           "element changed state SUCCESS");
2752       /* we can commit the state now which will proceeed to
2753        * the next state */
2754       ret = gst_element_continue_state (element, ret);
2755       break;
2756     case GST_STATE_CHANGE_NO_PREROLL:
2757       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2758           "element changed state NO_PREROLL");
2759       /* we can commit the state now which will proceeed to
2760        * the next state */
2761       ret = gst_element_continue_state (element, ret);
2762       break;
2763     default:
2764       goto invalid_return;
2765   }
2766
2767   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit state change %d", ret);
2768
2769   return ret;
2770
2771 async:
2772   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit async state change %d",
2773       ret);
2774
2775   return ret;
2776
2777   /* ERROR */
2778 invalid_return:
2779   {
2780     GST_OBJECT_LOCK (element);
2781     /* somebody added a GST_STATE_ and forgot to do stuff here ! */
2782     g_critical ("%s: unknown return value %d from a state change function",
2783         GST_ELEMENT_NAME (element), ret);
2784
2785     /* we are in error now */
2786     ret = GST_STATE_CHANGE_FAILURE;
2787     GST_STATE_RETURN (element) = ret;
2788     GST_OBJECT_UNLOCK (element);
2789
2790     return ret;
2791   }
2792 }
2793
2794 /* gst_iterator_fold functions for pads_activate
2795  * Note how we don't stop the iterator when we fail an activation. This is
2796  * probably a FIXME since when one pad activation fails, we don't want to
2797  * continue our state change. */
2798 static gboolean
2799 activate_pads (GstPad * pad, GValue * ret, gboolean * active)
2800 {
2801   if (!gst_pad_set_active (pad, *active))
2802     g_value_set_boolean (ret, FALSE);
2803
2804   /* unref the object that was reffed for us by _fold */
2805   gst_object_unref (pad);
2806   return TRUE;
2807 }
2808
2809 /* set the caps on the pad to NULL */
2810 static gboolean
2811 clear_caps (GstPad * pad, GValue * ret, gboolean * active)
2812 {
2813   gst_pad_set_caps (pad, NULL);
2814   gst_object_unref (pad);
2815   return TRUE;
2816 }
2817
2818 /* returns false on error or early cutout (will never happen because the fold
2819  * function always returns TRUE, see FIXME above) of the fold, true if all
2820  * pads in @iter were (de)activated successfully. */
2821 static gboolean
2822 iterator_activate_fold_with_resync (GstIterator * iter,
2823     GstIteratorFoldFunction func, gpointer user_data)
2824 {
2825   GstIteratorResult ires;
2826   GValue ret = { 0 };
2827
2828   /* no need to unset this later, it's just a boolean */
2829   g_value_init (&ret, G_TYPE_BOOLEAN);
2830   g_value_set_boolean (&ret, TRUE);
2831
2832   while (1) {
2833     ires = gst_iterator_fold (iter, func, &ret, user_data);
2834     switch (ires) {
2835       case GST_ITERATOR_RESYNC:
2836         /* need to reset the result again */
2837         g_value_set_boolean (&ret, TRUE);
2838         gst_iterator_resync (iter);
2839         break;
2840       case GST_ITERATOR_DONE:
2841         /* all pads iterated, return collected value */
2842         goto done;
2843       default:
2844         /* iterator returned _ERROR or premature end with _OK,
2845          * mark an error and exit */
2846         g_value_set_boolean (&ret, FALSE);
2847         goto done;
2848     }
2849   }
2850 done:
2851   /* return collected value */
2852   return g_value_get_boolean (&ret);
2853 }
2854
2855 /* is called with STATE_LOCK
2856  *
2857  * Pads are activated from source pads to sinkpads.
2858  */
2859 static gboolean
2860 gst_element_pads_activate (GstElement * element, gboolean active)
2861 {
2862   GstIterator *iter;
2863   gboolean res;
2864
2865   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2866       "pads_activate with active %d", active);
2867
2868   iter = gst_element_iterate_src_pads (element);
2869   res =
2870       iterator_activate_fold_with_resync (iter,
2871       (GstIteratorFoldFunction) activate_pads, &active);
2872   gst_iterator_free (iter);
2873   if (G_UNLIKELY (!res))
2874     goto src_failed;
2875
2876   iter = gst_element_iterate_sink_pads (element);
2877   res =
2878       iterator_activate_fold_with_resync (iter,
2879       (GstIteratorFoldFunction) activate_pads, &active);
2880   gst_iterator_free (iter);
2881   if (G_UNLIKELY (!res))
2882     goto sink_failed;
2883
2884   if (!active) {
2885     /* clear the caps on all pads, this should never fail */
2886     iter = gst_element_iterate_pads (element);
2887     res =
2888         iterator_activate_fold_with_resync (iter,
2889         (GstIteratorFoldFunction) clear_caps, &active);
2890     gst_iterator_free (iter);
2891     if (G_UNLIKELY (!res))
2892       goto caps_failed;
2893   }
2894
2895   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2896       "pads_activate successful");
2897
2898   return TRUE;
2899
2900   /* ERRORS */
2901 src_failed:
2902   {
2903     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2904         "source pads_activate failed");
2905     return FALSE;
2906   }
2907 sink_failed:
2908   {
2909     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2910         "sink pads_activate failed");
2911     return FALSE;
2912   }
2913 caps_failed:
2914   {
2915     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2916         "failed to clear caps on pads");
2917     return FALSE;
2918   }
2919 }
2920
2921 /* is called with STATE_LOCK */
2922 static GstStateChangeReturn
2923 gst_element_change_state_func (GstElement * element, GstStateChange transition)
2924 {
2925   GstState state, next;
2926   GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
2927   GstClock **clock_p;
2928
2929   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2930
2931   state = (GstState) GST_STATE_TRANSITION_CURRENT (transition);
2932   next = GST_STATE_TRANSITION_NEXT (transition);
2933
2934   /* if the element already is in the given state, we just return success */
2935   if (next == GST_STATE_VOID_PENDING || state == next)
2936     goto was_ok;
2937
2938   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element,
2939       "default handler tries setting state from %s to %s (%04x)",
2940       gst_element_state_get_name (state),
2941       gst_element_state_get_name (next), transition);
2942
2943   switch (transition) {
2944     case GST_STATE_CHANGE_NULL_TO_READY:
2945       break;
2946     case GST_STATE_CHANGE_READY_TO_PAUSED:
2947       if (!gst_element_pads_activate (element, TRUE)) {
2948         result = GST_STATE_CHANGE_FAILURE;
2949       }
2950       break;
2951     case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
2952       break;
2953     case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
2954       break;
2955     case GST_STATE_CHANGE_PAUSED_TO_READY:
2956     case GST_STATE_CHANGE_READY_TO_NULL:
2957       /* deactivate pads in both cases, since they are activated on
2958          ready->paused but the element might not have made it to paused */
2959       if (!gst_element_pads_activate (element, FALSE)) {
2960         result = GST_STATE_CHANGE_FAILURE;
2961       } else {
2962         gst_element_set_base_time (element, 0);
2963       }
2964
2965       /* In null state release the reference to the clock */
2966       GST_OBJECT_LOCK (element);
2967       clock_p = &element->clock;
2968       gst_object_replace ((GstObject **) clock_p, NULL);
2969       GST_OBJECT_UNLOCK (element);
2970       break;
2971     default:
2972       /* this will catch real but unhandled state changes;
2973        * can only be caused by:
2974        * - a new state was added
2975        * - somehow the element was asked to jump across an intermediate state
2976        */
2977       g_warning ("Unhandled state change from %s to %s",
2978           gst_element_state_get_name (state),
2979           gst_element_state_get_name (next));
2980       break;
2981   }
2982   return result;
2983
2984 was_ok:
2985   {
2986     GST_OBJECT_LOCK (element);
2987     result = GST_STATE_RETURN (element);
2988     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2989         "element is already in the %s state",
2990         gst_element_state_get_name (state));
2991     GST_OBJECT_UNLOCK (element);
2992
2993     return result;
2994   }
2995 }
2996
2997 /**
2998  * gst_element_get_factory:
2999  * @element: a #GstElement to request the element factory of.
3000  *
3001  * Retrieves the factory that was used to create this element.
3002  *
3003  * Returns: (transfer none): the #GstElementFactory used for creating this
3004  *     element. no refcounting is needed.
3005  */
3006 GstElementFactory *
3007 gst_element_get_factory (GstElement * element)
3008 {
3009   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
3010
3011   return GST_ELEMENT_GET_CLASS (element)->elementfactory;
3012 }
3013
3014 static void
3015 gst_element_dispose (GObject * object)
3016 {
3017   GstElement *element = GST_ELEMENT_CAST (object);
3018   GstClock **clock_p;
3019   GstBus **bus_p;
3020
3021   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "dispose");
3022
3023   if (GST_STATE (element) != GST_STATE_NULL)
3024     goto not_null;
3025
3026   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
3027       "removing %d pads", g_list_length (element->pads));
3028   /* first we break all our links with the outside */
3029   while (element->pads && element->pads->data) {
3030     /* don't call _remove_pad with NULL */
3031     gst_element_remove_pad (element, GST_PAD_CAST (element->pads->data));
3032   }
3033   if (G_UNLIKELY (element->pads != NULL)) {
3034     g_critical ("could not remove pads from element %s",
3035         GST_STR_NULL (GST_OBJECT_NAME (object)));
3036   }
3037
3038   GST_OBJECT_LOCK (element);
3039   clock_p = &element->clock;
3040   bus_p = &element->bus;
3041   gst_object_replace ((GstObject **) clock_p, NULL);
3042   gst_object_replace ((GstObject **) bus_p, NULL);
3043   GST_OBJECT_UNLOCK (element);
3044
3045   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "parent class dispose");
3046
3047   G_OBJECT_CLASS (parent_class)->dispose (object);
3048
3049   return;
3050
3051   /* ERRORS */
3052 not_null:
3053   {
3054     gboolean is_locked;
3055
3056     is_locked = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
3057     g_critical
3058         ("\nTrying to dispose element %s, but it is in %s%s instead of the NULL"
3059         " state.\n"
3060         "You need to explicitly set elements to the NULL state before\n"
3061         "dropping the final reference, to allow them to clean up.\n"
3062         "This problem may also be caused by a refcounting bug in the\n"
3063         "application or some element.\n",
3064         GST_OBJECT_NAME (element),
3065         gst_element_state_get_name (GST_STATE (element)),
3066         is_locked ? " (locked)" : "");
3067     return;
3068   }
3069 }
3070
3071 static void
3072 gst_element_finalize (GObject * object)
3073 {
3074   GstElement *element = GST_ELEMENT_CAST (object);
3075
3076   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize");
3077
3078   GST_STATE_LOCK (element);
3079   if (element->state_cond)
3080     g_cond_free (element->state_cond);
3081   element->state_cond = NULL;
3082   GST_STATE_UNLOCK (element);
3083   g_static_rec_mutex_free (element->state_lock);
3084   g_slice_free (GStaticRecMutex, element->state_lock);
3085   element->state_lock = NULL;
3086
3087   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize parent");
3088
3089   G_OBJECT_CLASS (parent_class)->finalize (object);
3090 }
3091
3092 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
3093 /**
3094  * gst_element_save_thyself:
3095  * @element: a #GstElement to save.
3096  * @parent: the xml parent node.
3097  *
3098  * Saves the element as part of the given XML structure.
3099  *
3100  * Returns: the new #xmlNodePtr.
3101  */
3102 static xmlNodePtr
3103 gst_element_save_thyself (GstObject * object, xmlNodePtr parent)
3104 {
3105   GList *pads;
3106   GstElementClass *oclass;
3107   GParamSpec **specs, *spec;
3108   guint nspecs;
3109   guint i;
3110   GValue value = { 0, };
3111   GstElement *element;
3112
3113   g_return_val_if_fail (GST_IS_ELEMENT (object), parent);
3114
3115   element = GST_ELEMENT_CAST (object);
3116
3117   oclass = GST_ELEMENT_GET_CLASS (element);
3118
3119   xmlNewChild (parent, NULL, (xmlChar *) "name",
3120       (xmlChar *) GST_ELEMENT_NAME (element));
3121
3122   if (oclass->elementfactory != NULL) {
3123     GstElementFactory *factory = (GstElementFactory *) oclass->elementfactory;
3124
3125     xmlNewChild (parent, NULL, (xmlChar *) "type",
3126         (xmlChar *) GST_PLUGIN_FEATURE (factory)->name);
3127   }
3128
3129   /* params */
3130   specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (object), &nspecs);
3131
3132   for (i = 0; i < nspecs; i++) {
3133     spec = specs[i];
3134     if (spec->flags & G_PARAM_READABLE) {
3135       xmlNodePtr param;
3136       char *contents;
3137
3138       g_value_init (&value, spec->value_type);
3139
3140       g_object_get_property (G_OBJECT (element), spec->name, &value);
3141       param = xmlNewChild (parent, NULL, (xmlChar *) "param", NULL);
3142       xmlNewChild (param, NULL, (xmlChar *) "name", (xmlChar *) spec->name);
3143
3144       if (G_IS_PARAM_SPEC_STRING (spec))
3145         contents = g_value_dup_string (&value);
3146       else if (G_IS_PARAM_SPEC_ENUM (spec))
3147         contents = g_strdup_printf ("%d", g_value_get_enum (&value));
3148       else if (G_IS_PARAM_SPEC_INT64 (spec))
3149         contents = g_strdup_printf ("%" G_GINT64_FORMAT,
3150             g_value_get_int64 (&value));
3151       else if (GST_VALUE_HOLDS_STRUCTURE (&value)) {
3152         if (g_value_get_boxed (&value) != NULL) {
3153           contents = g_strdup_value_contents (&value);
3154         } else {
3155           contents = g_strdup ("NULL");
3156         }
3157       } else
3158         contents = g_strdup_value_contents (&value);
3159
3160       xmlNewChild (param, NULL, (xmlChar *) "value", (xmlChar *) contents);
3161       g_free (contents);
3162
3163       g_value_unset (&value);
3164     }
3165   }
3166
3167   g_free (specs);
3168
3169   pads = g_list_last (GST_ELEMENT_PADS (element));
3170
3171   while (pads) {
3172     GstPad *pad = GST_PAD_CAST (pads->data);
3173
3174     /* figure out if it's a direct pad or a ghostpad */
3175     if (GST_ELEMENT_CAST (GST_OBJECT_PARENT (pad)) == element) {
3176       xmlNodePtr padtag = xmlNewChild (parent, NULL, (xmlChar *) "pad", NULL);
3177
3178       gst_object_save_thyself (GST_OBJECT_CAST (pad), padtag);
3179     }
3180     pads = g_list_previous (pads);
3181   }
3182
3183   return parent;
3184 }
3185
3186 static void
3187 gst_element_restore_thyself (GstObject * object, xmlNodePtr self)
3188 {
3189   xmlNodePtr children;
3190   GstElement *element;
3191   gchar *name = NULL;
3192   gchar *value = NULL;
3193
3194   element = GST_ELEMENT_CAST (object);
3195   g_return_if_fail (element != NULL);
3196
3197   /* parameters */
3198   children = self->xmlChildrenNode;
3199   while (children) {
3200     if (!strcmp ((char *) children->name, "param")) {
3201       xmlNodePtr child = children->xmlChildrenNode;
3202
3203       while (child) {
3204         if (!strcmp ((char *) child->name, "name")) {
3205           name = (gchar *) xmlNodeGetContent (child);
3206         } else if (!strcmp ((char *) child->name, "value")) {
3207           value = (gchar *) xmlNodeGetContent (child);
3208         }
3209         child = child->next;
3210       }
3211       /* FIXME: can this just be g_object_set ? */
3212       gst_util_set_object_arg (G_OBJECT (element), name, value);
3213       /* g_object_set (G_OBJECT (element), name, value, NULL); */
3214       g_free (name);
3215       g_free (value);
3216     }
3217     children = children->next;
3218   }
3219
3220   /* pads */
3221   children = self->xmlChildrenNode;
3222   while (children) {
3223     if (!strcmp ((char *) children->name, "pad")) {
3224       gst_pad_load_and_link (children, GST_OBJECT_CAST (element));
3225     }
3226     children = children->next;
3227   }
3228
3229   if (GST_OBJECT_CLASS (parent_class)->restore_thyself)
3230     (GST_OBJECT_CLASS (parent_class)->restore_thyself) (object, self);
3231 }
3232 #endif /* GST_DISABLE_LOADSAVE */
3233
3234 static void
3235 gst_element_set_bus_func (GstElement * element, GstBus * bus)
3236 {
3237   GstBus **bus_p;
3238
3239   g_return_if_fail (GST_IS_ELEMENT (element));
3240
3241   GST_CAT_DEBUG_OBJECT (GST_CAT_PARENTAGE, element, "setting bus to %p", bus);
3242
3243   GST_OBJECT_LOCK (element);
3244   bus_p = &GST_ELEMENT_BUS (element);
3245   gst_object_replace ((GstObject **) bus_p, GST_OBJECT_CAST (bus));
3246   GST_OBJECT_UNLOCK (element);
3247 }
3248
3249 /**
3250  * gst_element_set_bus:
3251  * @element: a #GstElement to set the bus of.
3252  * @bus: (transfer none): the #GstBus to set.
3253  *
3254  * Sets the bus of the element. Increases the refcount on the bus.
3255  * For internal use only, unless you're testing elements.
3256  *
3257  * MT safe.
3258  */
3259 void
3260 gst_element_set_bus (GstElement * element, GstBus * bus)
3261 {
3262   GstElementClass *oclass;
3263
3264   g_return_if_fail (GST_IS_ELEMENT (element));
3265
3266   oclass = GST_ELEMENT_GET_CLASS (element);
3267
3268   if (oclass->set_bus)
3269     oclass->set_bus (element, bus);
3270 }
3271
3272 /**
3273  * gst_element_get_bus:
3274  * @element: a #GstElement to get the bus of.
3275  *
3276  * Returns the bus of the element. Note that only a #GstPipeline will provide a
3277  * bus for the application.
3278  *
3279  * Returns: (transfer full): the element's #GstBus. unref after usage.
3280  *
3281  * MT safe.
3282  */
3283 GstBus *
3284 gst_element_get_bus (GstElement * element)
3285 {
3286   GstBus *result = NULL;
3287
3288   g_return_val_if_fail (GST_IS_ELEMENT (element), result);
3289
3290   GST_OBJECT_LOCK (element);
3291   if ((result = GST_ELEMENT_BUS (element)))
3292     gst_object_ref (result);
3293   GST_OBJECT_UNLOCK (element);
3294
3295   GST_CAT_DEBUG_OBJECT (GST_CAT_BUS, element, "got bus %" GST_PTR_FORMAT,
3296       result);
3297
3298   return result;
3299 }