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_state() 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     gst_event_unref (event);
1599   }
1600   return result;
1601 }
1602
1603 /**
1604  * gst_element_send_event:
1605  * @element: a #GstElement to send the event to.
1606  * @event: (transfer full): the #GstEvent to send to the element.
1607  *
1608  * Sends an event to an element. If the element doesn't implement an
1609  * event handler, the event will be pushed on a random linked sink pad for
1610  * upstream events or a random linked source pad for downstream events.
1611  *
1612  * This function takes owership of the provided event so you should
1613  * gst_event_ref() it if you want to reuse the event after this call.
1614  *
1615  * Returns: %TRUE if the event was handled.
1616  *
1617  * MT safe.
1618  */
1619 gboolean
1620 gst_element_send_event (GstElement * element, GstEvent * event)
1621 {
1622   GstElementClass *oclass;
1623   gboolean result = FALSE;
1624
1625   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1626   g_return_val_if_fail (event != NULL, FALSE);
1627
1628   oclass = GST_ELEMENT_GET_CLASS (element);
1629
1630   GST_STATE_LOCK (element);
1631   if (oclass->send_event) {
1632     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send %s event on element %s",
1633         GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1634     result = oclass->send_event (element, event);
1635   } else {
1636     result = gst_element_default_send_event (element, event);
1637   }
1638   GST_STATE_UNLOCK (element);
1639
1640   return result;
1641 }
1642
1643 /**
1644  * gst_element_seek:
1645  * @element: a #GstElement to send the event to.
1646  * @rate: The new playback rate
1647  * @format: The format of the seek values
1648  * @flags: The optional seek flags.
1649  * @cur_type: The type and flags for the new current position
1650  * @cur: The value of the new current position
1651  * @stop_type: The type and flags for the new stop position
1652  * @stop: The value of the new stop position
1653  *
1654  * Sends a seek event to an element. See gst_event_new_seek() for the details of
1655  * the parameters. The seek event is sent to the element using
1656  * gst_element_send_event().
1657  *
1658  * Returns: %TRUE if the event was handled.
1659  *
1660  * MT safe.
1661  */
1662 gboolean
1663 gst_element_seek (GstElement * element, gdouble rate, GstFormat format,
1664     GstSeekFlags flags, GstSeekType cur_type, gint64 cur,
1665     GstSeekType stop_type, gint64 stop)
1666 {
1667   GstEvent *event;
1668   gboolean result;
1669
1670   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1671
1672   event =
1673       gst_event_new_seek (rate, format, flags, cur_type, cur, stop_type, stop);
1674   result = gst_element_send_event (element, event);
1675
1676   return result;
1677 }
1678
1679 /**
1680  * gst_element_get_query_types:
1681  * @element: a #GstElement to query
1682  *
1683  * Get an array of query types from the element.
1684  * If the element doesn't implement a query types function,
1685  * the query will be forwarded to the peer of a random linked sink pad.
1686  *
1687  * Returns: An array of #GstQueryType elements that should not
1688  * be freed or modified.
1689  *
1690  * MT safe.
1691  */
1692 const GstQueryType *
1693 gst_element_get_query_types (GstElement * element)
1694 {
1695   GstElementClass *oclass;
1696   const GstQueryType *result = NULL;
1697
1698   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1699
1700   oclass = GST_ELEMENT_GET_CLASS (element);
1701
1702   if (oclass->get_query_types) {
1703     result = oclass->get_query_types (element);
1704   } else {
1705     GstPad *pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1706
1707     if (pad) {
1708       GstPad *peer = gst_pad_get_peer (pad);
1709
1710       if (peer) {
1711         result = gst_pad_get_query_types (peer);
1712
1713         gst_object_unref (peer);
1714       }
1715       gst_object_unref (pad);
1716     }
1717   }
1718   return result;
1719 }
1720
1721 static gboolean
1722 gst_element_default_query (GstElement * element, GstQuery * query)
1723 {
1724   gboolean result = FALSE;
1725   GstPad *pad;
1726
1727   pad = gst_element_get_random_pad (element, FALSE, GST_PAD_SRC);
1728   if (pad) {
1729     result = gst_pad_query (pad, query);
1730
1731     gst_object_unref (pad);
1732   } else {
1733     pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1734     if (pad) {
1735       GstPad *peer = gst_pad_get_peer (pad);
1736
1737       if (peer) {
1738         result = gst_pad_query (peer, query);
1739
1740         gst_object_unref (peer);
1741       }
1742       gst_object_unref (pad);
1743     }
1744   }
1745   return result;
1746 }
1747
1748 /**
1749  * gst_element_query:
1750  * @element: a #GstElement to perform the query on.
1751  * @query: (transfer none): the #GstQuery.
1752  *
1753  * Performs a query on the given element.
1754  *
1755  * For elements that don't implement a query handler, this function
1756  * forwards the query to a random srcpad or to the peer of a
1757  * random linked sinkpad of this element.
1758  *
1759  * Please note that some queries might need a running pipeline to work.
1760  *
1761  * Returns: TRUE if the query could be performed.
1762  *
1763  * MT safe.
1764  */
1765 gboolean
1766 gst_element_query (GstElement * element, GstQuery * query)
1767 {
1768   GstElementClass *oclass;
1769   gboolean result = FALSE;
1770
1771   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1772   g_return_val_if_fail (query != NULL, FALSE);
1773
1774   oclass = GST_ELEMENT_GET_CLASS (element);
1775
1776   if (oclass->query) {
1777     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send query on element %s",
1778         GST_ELEMENT_NAME (element));
1779     result = oclass->query (element, query);
1780   } else {
1781     result = gst_element_default_query (element, query);
1782   }
1783   return result;
1784 }
1785
1786 /**
1787  * gst_element_post_message:
1788  * @element: a #GstElement posting the message
1789  * @message: (transfer full): a #GstMessage to post
1790  *
1791  * Post a message on the element's #GstBus. This function takes ownership of the
1792  * message; if you want to access the message after this call, you should add an
1793  * additional reference before calling.
1794  *
1795  * Returns: %TRUE if the message was successfully posted. The function returns
1796  * %FALSE if the element did not have a bus.
1797  *
1798  * MT safe.
1799  */
1800 gboolean
1801 gst_element_post_message (GstElement * element, GstMessage * message)
1802 {
1803   GstBus *bus;
1804   gboolean result = FALSE;
1805
1806   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1807   g_return_val_if_fail (message != NULL, FALSE);
1808
1809   GST_OBJECT_LOCK (element);
1810   bus = element->bus;
1811
1812   if (G_UNLIKELY (bus == NULL))
1813     goto no_bus;
1814
1815   gst_object_ref (bus);
1816   GST_OBJECT_UNLOCK (element);
1817
1818   /* we release the element lock when posting the message so that any
1819    * (synchronous) message handlers can operate on the element */
1820   result = gst_bus_post (bus, message);
1821   gst_object_unref (bus);
1822
1823   return result;
1824
1825   /* ERRORS */
1826 no_bus:
1827   {
1828     GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element,
1829         "not posting message %p: no bus", message);
1830     GST_OBJECT_UNLOCK (element);
1831     gst_message_unref (message);
1832     return FALSE;
1833   }
1834 }
1835
1836 /**
1837  * _gst_element_error_printf:
1838  * @format: the printf-like format to use, or %NULL
1839  *
1840  * This function is only used internally by the gst_element_error() macro.
1841  *
1842  * Returns: (transfer full): a newly allocated string, or %NULL if the format
1843  *     was %NULL or ""
1844  *
1845  * MT safe.
1846  */
1847 gchar *
1848 _gst_element_error_printf (const gchar * format, ...)
1849 {
1850   va_list args;
1851   gchar *buffer;
1852
1853   if (format == NULL)
1854     return NULL;
1855   if (format[0] == 0)
1856     return NULL;
1857
1858   va_start (args, format);
1859   buffer = g_strdup_vprintf (format, args);
1860   va_end (args);
1861   return buffer;
1862 }
1863
1864 /**
1865  * gst_element_message_full:
1866  * @element:  a #GstElement to send message from
1867  * @type:     the #GstMessageType
1868  * @domain:   the GStreamer GError domain this message belongs to
1869  * @code:     the GError code belonging to the domain
1870  * @text:     (allow-none) (transfer full): an allocated text string to be used
1871  *            as a replacement for the default message connected to code,
1872  *            or %NULL
1873  * @debug:    (allow-none) (transfer full): an allocated debug message to be
1874  *            used as a replacement for the default debugging information,
1875  *            or %NULL
1876  * @file:     the source code file where the error was generated
1877  * @function: the source code function where the error was generated
1878  * @line:     the source code line where the error was generated
1879  *
1880  * Post an error, warning or info message on the bus from inside an element.
1881  *
1882  * @type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or
1883  * #GST_MESSAGE_INFO.
1884  *
1885  * MT safe.
1886  */
1887 void gst_element_message_full
1888     (GstElement * element, GstMessageType type,
1889     GQuark domain, gint code, gchar * text,
1890     gchar * debug, const gchar * file, const gchar * function, gint line)
1891 {
1892   GError *gerror = NULL;
1893   gchar *name;
1894   gchar *sent_text;
1895   gchar *sent_debug;
1896   gboolean has_debug = TRUE;
1897   GstMessage *message = NULL;
1898
1899   /* checks */
1900   GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element, "start");
1901   g_return_if_fail (GST_IS_ELEMENT (element));
1902   g_return_if_fail ((type == GST_MESSAGE_ERROR) ||
1903       (type == GST_MESSAGE_WARNING) || (type == GST_MESSAGE_INFO));
1904
1905   /* check if we send the given text or the default error text */
1906   if ((text == NULL) || (text[0] == 0)) {
1907     /* text could have come from g_strdup_printf (""); */
1908     g_free (text);
1909     sent_text = gst_error_get_message (domain, code);
1910   } else
1911     sent_text = text;
1912
1913   /* construct a sent_debug with extra information from source */
1914   if ((debug == NULL) || (debug[0] == 0)) {
1915     /* debug could have come from g_strdup_printf (""); */
1916     has_debug = FALSE;
1917   }
1918
1919   name = gst_object_get_path_string (GST_OBJECT_CAST (element));
1920   if (has_debug)
1921     sent_debug = g_strdup_printf ("%s(%d): %s (): %s:\n%s",
1922         file, line, function, name, debug);
1923   else
1924     sent_debug = g_strdup_printf ("%s(%d): %s (): %s",
1925         file, line, function, name);
1926   g_free (name);
1927   g_free (debug);
1928
1929   /* create gerror and post message */
1930   GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posting message: %s",
1931       sent_text);
1932   gerror = g_error_new_literal (domain, code, sent_text);
1933
1934   switch (type) {
1935     case GST_MESSAGE_ERROR:
1936       message =
1937           gst_message_new_error (GST_OBJECT_CAST (element), gerror, sent_debug);
1938       break;
1939     case GST_MESSAGE_WARNING:
1940       message = gst_message_new_warning (GST_OBJECT_CAST (element), gerror,
1941           sent_debug);
1942       break;
1943     case GST_MESSAGE_INFO:
1944       message = gst_message_new_info (GST_OBJECT_CAST (element), gerror,
1945           sent_debug);
1946       break;
1947     default:
1948       g_assert_not_reached ();
1949       break;
1950   }
1951   gst_element_post_message (element, message);
1952
1953   GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posted %s message: %s",
1954       (type == GST_MESSAGE_ERROR ? "error" : "warning"), sent_text);
1955
1956   /* cleanup */
1957   g_error_free (gerror);
1958   g_free (sent_debug);
1959   g_free (sent_text);
1960 }
1961
1962 /**
1963  * gst_element_is_locked_state:
1964  * @element: a #GstElement.
1965  *
1966  * Checks if the state of an element is locked.
1967  * If the state of an element is locked, state changes of the parent don't
1968  * affect the element.
1969  * This way you can leave currently unused elements inside bins. Just lock their
1970  * state before changing the state from #GST_STATE_NULL.
1971  *
1972  * MT safe.
1973  *
1974  * Returns: TRUE, if the element's state is locked.
1975  */
1976 gboolean
1977 gst_element_is_locked_state (GstElement * element)
1978 {
1979   gboolean result;
1980
1981   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1982
1983   GST_OBJECT_LOCK (element);
1984   result = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
1985   GST_OBJECT_UNLOCK (element);
1986
1987   return result;
1988 }
1989
1990 /**
1991  * gst_element_set_locked_state:
1992  * @element: a #GstElement
1993  * @locked_state: TRUE to lock the element's state
1994  *
1995  * Locks the state of an element, so state changes of the parent don't affect
1996  * this element anymore.
1997  *
1998  * MT safe.
1999  *
2000  * Returns: TRUE if the state was changed, FALSE if bad parameters were given
2001  * or the elements state-locking needed no change.
2002  */
2003 gboolean
2004 gst_element_set_locked_state (GstElement * element, gboolean locked_state)
2005 {
2006   gboolean old;
2007
2008   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2009
2010   GST_OBJECT_LOCK (element);
2011   old = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
2012
2013   if (G_UNLIKELY (old == locked_state))
2014     goto was_ok;
2015
2016   if (locked_state) {
2017     GST_CAT_DEBUG (GST_CAT_STATES, "locking state of element %s",
2018         GST_ELEMENT_NAME (element));
2019     GST_OBJECT_FLAG_SET (element, GST_ELEMENT_LOCKED_STATE);
2020   } else {
2021     GST_CAT_DEBUG (GST_CAT_STATES, "unlocking state of element %s",
2022         GST_ELEMENT_NAME (element));
2023     GST_OBJECT_FLAG_UNSET (element, GST_ELEMENT_LOCKED_STATE);
2024   }
2025   GST_OBJECT_UNLOCK (element);
2026
2027   return TRUE;
2028
2029 was_ok:
2030   {
2031     GST_CAT_DEBUG (GST_CAT_STATES,
2032         "elements %s was already in locked state %d",
2033         GST_ELEMENT_NAME (element), old);
2034     GST_OBJECT_UNLOCK (element);
2035
2036     return FALSE;
2037   }
2038 }
2039
2040 /**
2041  * gst_element_sync_state_with_parent:
2042  * @element: a #GstElement.
2043  *
2044  * Tries to change the state of the element to the same as its parent.
2045  * If this function returns FALSE, the state of element is undefined.
2046  *
2047  * Returns: TRUE, if the element's state could be synced to the parent's state.
2048  *
2049  * MT safe.
2050  */
2051 gboolean
2052 gst_element_sync_state_with_parent (GstElement * element)
2053 {
2054   GstElement *parent;
2055   GstState target;
2056   GstStateChangeReturn ret;
2057
2058   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2059
2060   if ((parent = GST_ELEMENT_CAST (gst_element_get_parent (element)))) {
2061     GstState parent_current, parent_pending;
2062
2063     GST_OBJECT_LOCK (parent);
2064     parent_current = GST_STATE (parent);
2065     parent_pending = GST_STATE_PENDING (parent);
2066     GST_OBJECT_UNLOCK (parent);
2067
2068     /* set to pending if there is one, else we set it to the current state of
2069      * the parent */
2070     if (parent_pending != GST_STATE_VOID_PENDING)
2071       target = parent_pending;
2072     else
2073       target = parent_current;
2074
2075     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2076         "syncing state (%s) to parent %s %s (%s, %s)",
2077         gst_element_state_get_name (GST_STATE (element)),
2078         GST_ELEMENT_NAME (parent), gst_element_state_get_name (target),
2079         gst_element_state_get_name (parent_current),
2080         gst_element_state_get_name (parent_pending));
2081
2082     ret = gst_element_set_state (element, target);
2083     if (ret == GST_STATE_CHANGE_FAILURE)
2084       goto failed;
2085
2086     gst_object_unref (parent);
2087
2088     return TRUE;
2089   } else {
2090     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "element has no parent");
2091   }
2092   return FALSE;
2093
2094   /* ERROR */
2095 failed:
2096   {
2097     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2098         "syncing state failed (%s)",
2099         gst_element_state_change_return_get_name (ret));
2100     gst_object_unref (parent);
2101     return FALSE;
2102   }
2103 }
2104
2105 /* MT safe */
2106 static GstStateChangeReturn
2107 gst_element_get_state_func (GstElement * element,
2108     GstState * state, GstState * pending, GstClockTime timeout)
2109 {
2110   GstStateChangeReturn ret = GST_STATE_CHANGE_FAILURE;
2111   GstState old_pending;
2112
2113   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "getting state, timeout %"
2114       GST_TIME_FORMAT, GST_TIME_ARGS (timeout));
2115
2116   GST_OBJECT_LOCK (element);
2117   ret = GST_STATE_RETURN (element);
2118   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "RETURN is %s",
2119       gst_element_state_change_return_get_name (ret));
2120
2121   /* we got an error, report immediately */
2122   if (ret == GST_STATE_CHANGE_FAILURE)
2123     goto done;
2124
2125   /* we got no_preroll, report immediatly */
2126   if (ret == GST_STATE_CHANGE_NO_PREROLL)
2127     goto done;
2128
2129   /* no need to wait async if we are not async */
2130   if (ret != GST_STATE_CHANGE_ASYNC)
2131     goto done;
2132
2133   old_pending = GST_STATE_PENDING (element);
2134   if (old_pending != GST_STATE_VOID_PENDING) {
2135     GTimeVal *timeval, abstimeout;
2136     guint32 cookie;
2137
2138     if (timeout != GST_CLOCK_TIME_NONE) {
2139       glong add = timeout / 1000;
2140
2141       if (add == 0)
2142         goto done;
2143
2144       /* make timeout absolute */
2145       g_get_current_time (&abstimeout);
2146       g_time_val_add (&abstimeout, add);
2147       timeval = &abstimeout;
2148     } else {
2149       timeval = NULL;
2150     }
2151     /* get cookie to detect state changes during waiting */
2152     cookie = element->state_cookie;
2153
2154     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2155         "waiting for element to commit state");
2156
2157     /* we have a pending state change, wait for it to complete */
2158     if (!GST_STATE_TIMED_WAIT (element, timeval)) {
2159       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "timed out");
2160       /* timeout triggered */
2161       ret = GST_STATE_CHANGE_ASYNC;
2162     } else {
2163       if (cookie != element->state_cookie)
2164         goto interrupted;
2165
2166       /* could be success or failure */
2167       if (old_pending == GST_STATE (element)) {
2168         GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got success");
2169         ret = GST_STATE_CHANGE_SUCCESS;
2170       } else {
2171         GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got failure");
2172         ret = GST_STATE_CHANGE_FAILURE;
2173       }
2174     }
2175     /* if nothing is pending anymore we can return SUCCESS */
2176     if (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING) {
2177       GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "nothing pending");
2178       ret = GST_STATE_CHANGE_SUCCESS;
2179     }
2180   }
2181
2182 done:
2183   if (state)
2184     *state = GST_STATE (element);
2185   if (pending)
2186     *pending = GST_STATE_PENDING (element);
2187
2188   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2189       "state current: %s, pending: %s, result: %s",
2190       gst_element_state_get_name (GST_STATE (element)),
2191       gst_element_state_get_name (GST_STATE_PENDING (element)),
2192       gst_element_state_change_return_get_name (ret));
2193   GST_OBJECT_UNLOCK (element);
2194
2195   return ret;
2196
2197 interrupted:
2198   {
2199     if (state)
2200       *state = GST_STATE_VOID_PENDING;
2201     if (pending)
2202       *pending = GST_STATE_VOID_PENDING;
2203
2204     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "interruped");
2205
2206     GST_OBJECT_UNLOCK (element);
2207
2208     return GST_STATE_CHANGE_FAILURE;
2209   }
2210 }
2211
2212 /**
2213  * gst_element_get_state:
2214  * @element: a #GstElement to get the state of.
2215  * @state: (out) (allow-none): a pointer to #GstState to hold the state.
2216  *     Can be %NULL.
2217  * @pending: (out) (allow-none): a pointer to #GstState to hold the pending
2218  *     state. Can be %NULL.
2219  * @timeout: a #GstClockTime to specify the timeout for an async
2220  *           state change or %GST_CLOCK_TIME_NONE for infinite timeout.
2221  *
2222  * Gets the state of the element.
2223  *
2224  * For elements that performed an ASYNC state change, as reported by
2225  * gst_element_set_state(), this function will block up to the
2226  * specified timeout value for the state change to complete.
2227  * If the element completes the state change or goes into
2228  * an error, this function returns immediately with a return value of
2229  * %GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively.
2230  *
2231  * For elements that did not return %GST_STATE_CHANGE_ASYNC, this function
2232  * returns the current and pending state immediately.
2233  *
2234  * This function returns %GST_STATE_CHANGE_NO_PREROLL if the element
2235  * successfully changed its state but is not able to provide data yet.
2236  * This mostly happens for live sources that only produce data in
2237  * %GST_STATE_PLAYING. While the state change return is equivalent to
2238  * %GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that
2239  * some sink elements might not be able to complete their state change because
2240  * an element is not producing data to complete the preroll. When setting the
2241  * element to playing, the preroll will complete and playback will start.
2242  *
2243  * Returns: %GST_STATE_CHANGE_SUCCESS if the element has no more pending state
2244  *          and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the
2245  *          element is still performing a state change or
2246  *          %GST_STATE_CHANGE_FAILURE if the last state change failed.
2247  *
2248  * MT safe.
2249  */
2250 GstStateChangeReturn
2251 gst_element_get_state (GstElement * element,
2252     GstState * state, GstState * pending, GstClockTime timeout)
2253 {
2254   GstElementClass *oclass;
2255   GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2256
2257   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2258
2259   oclass = GST_ELEMENT_GET_CLASS (element);
2260
2261   if (oclass->get_state)
2262     result = (oclass->get_state) (element, state, pending, timeout);
2263
2264   return result;
2265 }
2266
2267 /**
2268  * gst_element_abort_state:
2269  * @element: a #GstElement to abort the state of.
2270  *
2271  * Abort the state change of the element. This function is used
2272  * by elements that do asynchronous state changes and find out
2273  * something is wrong.
2274  *
2275  * This function should be called with the STATE_LOCK held.
2276  *
2277  * MT safe.
2278  */
2279 void
2280 gst_element_abort_state (GstElement * element)
2281 {
2282   GstState pending;
2283
2284 #ifndef GST_DISABLE_GST_DEBUG
2285   GstState old_state;
2286 #endif
2287
2288   g_return_if_fail (GST_IS_ELEMENT (element));
2289
2290   GST_OBJECT_LOCK (element);
2291   pending = GST_STATE_PENDING (element);
2292
2293   if (pending == GST_STATE_VOID_PENDING ||
2294       GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2295     goto nothing_aborted;
2296
2297 #ifndef GST_DISABLE_GST_DEBUG
2298   old_state = GST_STATE (element);
2299
2300   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2301       "aborting state from %s to %s", gst_element_state_get_name (old_state),
2302       gst_element_state_get_name (pending));
2303 #endif
2304
2305   /* flag error */
2306   GST_STATE_RETURN (element) = GST_STATE_CHANGE_FAILURE;
2307
2308   GST_STATE_BROADCAST (element);
2309   GST_OBJECT_UNLOCK (element);
2310
2311   return;
2312
2313 nothing_aborted:
2314   {
2315     GST_OBJECT_UNLOCK (element);
2316     return;
2317   }
2318 }
2319
2320 /**
2321  * gst_element_continue_state:
2322  * @element: a #GstElement to continue the state change of.
2323  * @ret: The previous state return value
2324  *
2325  * Commit the state change of the element and proceed to the next
2326  * pending state if any. This function is used
2327  * by elements that do asynchronous state changes.
2328  * The core will normally call this method automatically when an
2329  * element returned %GST_STATE_CHANGE_SUCCESS from the state change function.
2330  *
2331  * If after calling this method the element still has not reached
2332  * the pending state, the next state change is performed.
2333  *
2334  * This method is used internally and should normally not be called by plugins
2335  * or applications.
2336  *
2337  * Returns: The result of the commit state change.
2338  *
2339  * MT safe.
2340  */
2341 GstStateChangeReturn
2342 gst_element_continue_state (GstElement * element, GstStateChangeReturn ret)
2343 {
2344   GstStateChangeReturn old_ret;
2345   GstState old_state, old_next;
2346   GstState current, next, pending;
2347   GstMessage *message;
2348   GstStateChange transition;
2349
2350   GST_OBJECT_LOCK (element);
2351   old_ret = GST_STATE_RETURN (element);
2352   GST_STATE_RETURN (element) = ret;
2353   pending = GST_STATE_PENDING (element);
2354
2355   /* check if there is something to commit */
2356   if (pending == GST_STATE_VOID_PENDING)
2357     goto nothing_pending;
2358
2359   old_state = GST_STATE (element);
2360   /* this is the state we should go to next */
2361   old_next = GST_STATE_NEXT (element);
2362   /* update current state */
2363   current = GST_STATE (element) = old_next;
2364
2365   /* see if we reached the final state */
2366   if (pending == current)
2367     goto complete;
2368
2369   next = GST_STATE_GET_NEXT (current, pending);
2370   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2371
2372   GST_STATE_NEXT (element) = next;
2373   /* mark busy */
2374   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2375   GST_OBJECT_UNLOCK (element);
2376
2377   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2378       "committing state from %s to %s, pending %s, next %s",
2379       gst_element_state_get_name (old_state),
2380       gst_element_state_get_name (old_next),
2381       gst_element_state_get_name (pending), gst_element_state_get_name (next));
2382
2383   message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2384       old_state, old_next, pending);
2385   gst_element_post_message (element, message);
2386
2387   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2388       "continue state change %s to %s, final %s",
2389       gst_element_state_get_name (current),
2390       gst_element_state_get_name (next), gst_element_state_get_name (pending));
2391
2392   ret = gst_element_change_state (element, transition);
2393
2394   return ret;
2395
2396 nothing_pending:
2397   {
2398     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "nothing pending");
2399     GST_OBJECT_UNLOCK (element);
2400     return ret;
2401   }
2402 complete:
2403   {
2404     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2405     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2406
2407     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2408         "completed state change to %s", gst_element_state_get_name (pending));
2409     GST_OBJECT_UNLOCK (element);
2410
2411     /* don't post silly messages with the same state. This can happen
2412      * when an element state is changed to what it already was. For bins
2413      * this can be the result of a lost state, which we check with the
2414      * previous return value.
2415      * We do signal the cond though as a _get_state() might be blocking
2416      * on it. */
2417     if (old_state != old_next || old_ret == GST_STATE_CHANGE_ASYNC) {
2418       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2419           "posting state-changed %s to %s",
2420           gst_element_state_get_name (old_state),
2421           gst_element_state_get_name (old_next));
2422       message =
2423           gst_message_new_state_changed (GST_OBJECT_CAST (element), old_state,
2424           old_next, GST_STATE_VOID_PENDING);
2425       gst_element_post_message (element, message);
2426     }
2427
2428     GST_STATE_BROADCAST (element);
2429
2430     return ret;
2431   }
2432 }
2433
2434 /**
2435  * gst_element_lost_state_full:
2436  * @element: a #GstElement the state is lost of
2437  * @new_base_time: if a new base time should be distributed
2438  *
2439  * Brings the element to the lost state. The current state of the
2440  * element is copied to the pending state so that any call to
2441  * gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC.
2442  *
2443  * An ASYNC_START message is posted with indication to distribute a new
2444  * base_time to the element when @new_base_time is %TRUE.
2445  * If the element was PLAYING, it will go to PAUSED. The element
2446  * will be restored to its PLAYING state by the parent pipeline when it
2447  * prerolls again.
2448  *
2449  * This is mostly used for elements that lost their preroll buffer
2450  * in the %GST_STATE_PAUSED or %GST_STATE_PLAYING state after a flush,
2451  * they will go to their pending state again when a new preroll buffer is
2452  * queued. This function can only be called when the element is currently
2453  * not in error or an async state change.
2454  *
2455  * This function is used internally and should normally not be called from
2456  * plugins or applications.
2457  *
2458  * MT safe.
2459  *
2460  * Since: 0.10.24
2461  */
2462 void
2463 gst_element_lost_state_full (GstElement * element, gboolean new_base_time)
2464 {
2465   GstState old_state, new_state;
2466   GstMessage *message;
2467
2468   g_return_if_fail (GST_IS_ELEMENT (element));
2469
2470   GST_OBJECT_LOCK (element);
2471   if (GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2472     goto nothing_lost;
2473
2474   if (GST_STATE_PENDING (element) != GST_STATE_VOID_PENDING)
2475     goto only_async_start;
2476
2477   old_state = GST_STATE (element);
2478
2479   /* when we were PLAYING, the new state is PAUSED. We will also not
2480    * automatically go to PLAYING but let the parent bin(s) set us to PLAYING
2481    * when we preroll. */
2482   if (old_state > GST_STATE_PAUSED)
2483     new_state = GST_STATE_PAUSED;
2484   else
2485     new_state = old_state;
2486
2487   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2488       "lost state of %s to %s", gst_element_state_get_name (old_state),
2489       gst_element_state_get_name (new_state));
2490
2491   GST_STATE (element) = new_state;
2492   GST_STATE_NEXT (element) = new_state;
2493   GST_STATE_PENDING (element) = new_state;
2494   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2495   if (new_base_time)
2496     GST_ELEMENT_START_TIME (element) = 0;
2497   GST_OBJECT_UNLOCK (element);
2498
2499   message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2500       new_state, new_state, new_state);
2501   gst_element_post_message (element, message);
2502
2503   message =
2504       gst_message_new_async_start (GST_OBJECT_CAST (element), new_base_time);
2505   gst_element_post_message (element, message);
2506
2507   return;
2508
2509 nothing_lost:
2510   {
2511     GST_OBJECT_UNLOCK (element);
2512     return;
2513   }
2514 only_async_start:
2515   {
2516     GST_OBJECT_UNLOCK (element);
2517
2518     message = gst_message_new_async_start (GST_OBJECT_CAST (element), TRUE);
2519     gst_element_post_message (element, message);
2520     return;
2521   }
2522 }
2523
2524 /**
2525  * gst_element_lost_state:
2526  * @element: a #GstElement the state is lost of
2527  *
2528  * Brings the element to the lost state. This function calls
2529  * gst_element_lost_state_full() with the new_base_time set to %TRUE.
2530  *
2531  * This function is used internally and should normally not be called from
2532  * plugins or applications.
2533  *
2534  * MT safe.
2535  */
2536 void
2537 gst_element_lost_state (GstElement * element)
2538 {
2539   gst_element_lost_state_full (element, TRUE);
2540 }
2541
2542 /**
2543  * gst_element_set_state:
2544  * @element: a #GstElement to change state of.
2545  * @state: the element's new #GstState.
2546  *
2547  * Sets the state of the element. This function will try to set the
2548  * requested state by going through all the intermediary states and calling
2549  * the class's state change function for each.
2550  *
2551  * This function can return #GST_STATE_CHANGE_ASYNC, in which case the
2552  * element will perform the remainder of the state change asynchronously in
2553  * another thread.
2554  * An application can use gst_element_get_state() to wait for the completion
2555  * of the state change or it can wait for a state change message on the bus.
2556  *
2557  * State changes to %GST_STATE_READY or %GST_STATE_NULL never return
2558  * #GST_STATE_CHANGE_ASYNC.
2559  *
2560  * Returns: Result of the state change using #GstStateChangeReturn.
2561  *
2562  * MT safe.
2563  */
2564 GstStateChangeReturn
2565 gst_element_set_state (GstElement * element, GstState state)
2566 {
2567   GstElementClass *oclass;
2568   GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2569
2570   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2571
2572   oclass = GST_ELEMENT_GET_CLASS (element);
2573
2574   if (oclass->set_state)
2575     result = (oclass->set_state) (element, state);
2576
2577   return result;
2578 }
2579
2580 /*
2581  * default set state function, calculates the next state based
2582  * on current state and calls the change_state function
2583  */
2584 static GstStateChangeReturn
2585 gst_element_set_state_func (GstElement * element, GstState state)
2586 {
2587   GstState current, next, old_pending;
2588   GstStateChangeReturn ret;
2589   GstStateChange transition;
2590   GstStateChangeReturn old_ret;
2591
2592   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2593
2594   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "set_state to %s",
2595       gst_element_state_get_name (state));
2596
2597   /* state lock is taken to protect the set_state() and get_state()
2598    * procedures, it does not lock any variables. */
2599   GST_STATE_LOCK (element);
2600
2601   /* now calculate how to get to the new state */
2602   GST_OBJECT_LOCK (element);
2603   old_ret = GST_STATE_RETURN (element);
2604   /* previous state change returned an error, remove all pending
2605    * and next states */
2606   if (old_ret == GST_STATE_CHANGE_FAILURE) {
2607     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2608     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2609     GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
2610   }
2611
2612   current = GST_STATE (element);
2613   next = GST_STATE_NEXT (element);
2614   old_pending = GST_STATE_PENDING (element);
2615
2616   /* this is the (new) state we should go to. TARGET is the last state we set on
2617    * the element. */
2618   if (state != GST_STATE_TARGET (element)) {
2619     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2620         "setting target state to %s", gst_element_state_get_name (state));
2621     GST_STATE_TARGET (element) = state;
2622     /* increment state cookie so that we can track each state change. We only do
2623      * this if this is actually a new state change. */
2624     element->state_cookie++;
2625   }
2626   GST_STATE_PENDING (element) = state;
2627
2628   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2629       "current %s, old_pending %s, next %s, old return %s",
2630       gst_element_state_get_name (current),
2631       gst_element_state_get_name (old_pending),
2632       gst_element_state_get_name (next),
2633       gst_element_state_change_return_get_name (old_ret));
2634
2635   /* if the element was busy doing a state change, we just update the
2636    * target state, it'll get to it async then. */
2637   if (old_pending != GST_STATE_VOID_PENDING) {
2638     /* upwards state change will happen ASYNC */
2639     if (old_pending <= state)
2640       goto was_busy;
2641     /* element is going to this state already */
2642     else if (next == state)
2643       goto was_busy;
2644     /* element was performing an ASYNC upward state change and
2645      * we request to go downward again. Start from the next pending
2646      * state then. */
2647     else if (next > state
2648         && GST_STATE_RETURN (element) == GST_STATE_CHANGE_ASYNC) {
2649       current = next;
2650     }
2651   }
2652   next = GST_STATE_GET_NEXT (current, state);
2653   /* now we store the next state */
2654   GST_STATE_NEXT (element) = next;
2655   /* mark busy, we need to check that there is actually a state change
2656    * to be done else we could accidentally override SUCCESS/NO_PREROLL and
2657    * the default element change_state function has no way to know what the
2658    * old value was... could consider this a FIXME...*/
2659   if (current != next)
2660     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2661
2662   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2663
2664   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2665       "%s: setting state from %s to %s",
2666       (next != state ? "intermediate" : "final"),
2667       gst_element_state_get_name (current), gst_element_state_get_name (next));
2668
2669   /* now signal any waiters, they will error since the cookie was incremented */
2670   GST_STATE_BROADCAST (element);
2671
2672   GST_OBJECT_UNLOCK (element);
2673
2674   ret = gst_element_change_state (element, transition);
2675
2676   GST_STATE_UNLOCK (element);
2677
2678   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "returned %s",
2679       gst_element_state_change_return_get_name (ret));
2680
2681   return ret;
2682
2683 was_busy:
2684   {
2685     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2686     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2687         "element was busy with async state change");
2688     GST_OBJECT_UNLOCK (element);
2689
2690     GST_STATE_UNLOCK (element);
2691
2692     return GST_STATE_CHANGE_ASYNC;
2693   }
2694 }
2695
2696 /**
2697  * gst_element_change_state:
2698  * @element: a #GstElement
2699  * @transition: the requested transition
2700  *
2701  * Perform @transition on @element.
2702  *
2703  * This function must be called with STATE_LOCK held and is mainly used
2704  * internally.
2705  *
2706  * Returns: the #GstStateChangeReturn of the state transition.
2707  */
2708 GstStateChangeReturn
2709 gst_element_change_state (GstElement * element, GstStateChange transition)
2710 {
2711   GstElementClass *oclass;
2712   GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
2713
2714   oclass = GST_ELEMENT_GET_CLASS (element);
2715
2716   /* call the state change function so it can set the state */
2717   if (oclass->change_state)
2718     ret = (oclass->change_state) (element, transition);
2719   else
2720     ret = GST_STATE_CHANGE_FAILURE;
2721
2722   switch (ret) {
2723     case GST_STATE_CHANGE_FAILURE:
2724       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2725           "have FAILURE change_state return");
2726       /* state change failure */
2727       gst_element_abort_state (element);
2728       break;
2729     case GST_STATE_CHANGE_ASYNC:
2730     {
2731       GstState target;
2732
2733       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2734           "element will change state ASYNC");
2735
2736       target = GST_STATE_TARGET (element);
2737
2738       if (target > GST_STATE_READY)
2739         goto async;
2740
2741       /* else we just continue the state change downwards */
2742       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2743           "forcing commit state %s <= %s",
2744           gst_element_state_get_name (target),
2745           gst_element_state_get_name (GST_STATE_READY));
2746
2747       ret = gst_element_continue_state (element, GST_STATE_CHANGE_SUCCESS);
2748       break;
2749     }
2750     case GST_STATE_CHANGE_SUCCESS:
2751       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2752           "element changed state SUCCESS");
2753       /* we can commit the state now which will proceeed to
2754        * the next state */
2755       ret = gst_element_continue_state (element, ret);
2756       break;
2757     case GST_STATE_CHANGE_NO_PREROLL:
2758       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2759           "element changed state NO_PREROLL");
2760       /* we can commit the state now which will proceeed to
2761        * the next state */
2762       ret = gst_element_continue_state (element, ret);
2763       break;
2764     default:
2765       goto invalid_return;
2766   }
2767
2768   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit state change %d", ret);
2769
2770   return ret;
2771
2772 async:
2773   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit async state change %d",
2774       ret);
2775
2776   return ret;
2777
2778   /* ERROR */
2779 invalid_return:
2780   {
2781     GST_OBJECT_LOCK (element);
2782     /* somebody added a GST_STATE_ and forgot to do stuff here ! */
2783     g_critical ("%s: unknown return value %d from a state change function",
2784         GST_ELEMENT_NAME (element), ret);
2785
2786     /* we are in error now */
2787     ret = GST_STATE_CHANGE_FAILURE;
2788     GST_STATE_RETURN (element) = ret;
2789     GST_OBJECT_UNLOCK (element);
2790
2791     return ret;
2792   }
2793 }
2794
2795 /* gst_iterator_fold functions for pads_activate
2796  * Note how we don't stop the iterator when we fail an activation. This is
2797  * probably a FIXME since when one pad activation fails, we don't want to
2798  * continue our state change. */
2799 static gboolean
2800 activate_pads (GstPad * pad, GValue * ret, gboolean * active)
2801 {
2802   if (!gst_pad_set_active (pad, *active))
2803     g_value_set_boolean (ret, FALSE);
2804
2805   /* unref the object that was reffed for us by _fold */
2806   gst_object_unref (pad);
2807   return TRUE;
2808 }
2809
2810 /* set the caps on the pad to NULL */
2811 static gboolean
2812 clear_caps (GstPad * pad, GValue * ret, gboolean * active)
2813 {
2814   gst_pad_set_caps (pad, NULL);
2815   gst_object_unref (pad);
2816   return TRUE;
2817 }
2818
2819 /* returns false on error or early cutout (will never happen because the fold
2820  * function always returns TRUE, see FIXME above) of the fold, true if all
2821  * pads in @iter were (de)activated successfully. */
2822 static gboolean
2823 iterator_activate_fold_with_resync (GstIterator * iter,
2824     GstIteratorFoldFunction func, gpointer user_data)
2825 {
2826   GstIteratorResult ires;
2827   GValue ret = { 0 };
2828
2829   /* no need to unset this later, it's just a boolean */
2830   g_value_init (&ret, G_TYPE_BOOLEAN);
2831   g_value_set_boolean (&ret, TRUE);
2832
2833   while (1) {
2834     ires = gst_iterator_fold (iter, func, &ret, user_data);
2835     switch (ires) {
2836       case GST_ITERATOR_RESYNC:
2837         /* need to reset the result again */
2838         g_value_set_boolean (&ret, TRUE);
2839         gst_iterator_resync (iter);
2840         break;
2841       case GST_ITERATOR_DONE:
2842         /* all pads iterated, return collected value */
2843         goto done;
2844       default:
2845         /* iterator returned _ERROR or premature end with _OK,
2846          * mark an error and exit */
2847         g_value_set_boolean (&ret, FALSE);
2848         goto done;
2849     }
2850   }
2851 done:
2852   /* return collected value */
2853   return g_value_get_boolean (&ret);
2854 }
2855
2856 /* is called with STATE_LOCK
2857  *
2858  * Pads are activated from source pads to sinkpads.
2859  */
2860 static gboolean
2861 gst_element_pads_activate (GstElement * element, gboolean active)
2862 {
2863   GstIterator *iter;
2864   gboolean res;
2865
2866   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2867       "pads_activate with active %d", active);
2868
2869   iter = gst_element_iterate_src_pads (element);
2870   res =
2871       iterator_activate_fold_with_resync (iter,
2872       (GstIteratorFoldFunction) activate_pads, &active);
2873   gst_iterator_free (iter);
2874   if (G_UNLIKELY (!res))
2875     goto src_failed;
2876
2877   iter = gst_element_iterate_sink_pads (element);
2878   res =
2879       iterator_activate_fold_with_resync (iter,
2880       (GstIteratorFoldFunction) activate_pads, &active);
2881   gst_iterator_free (iter);
2882   if (G_UNLIKELY (!res))
2883     goto sink_failed;
2884
2885   if (!active) {
2886     /* clear the caps on all pads, this should never fail */
2887     iter = gst_element_iterate_pads (element);
2888     res =
2889         iterator_activate_fold_with_resync (iter,
2890         (GstIteratorFoldFunction) clear_caps, &active);
2891     gst_iterator_free (iter);
2892     if (G_UNLIKELY (!res))
2893       goto caps_failed;
2894   }
2895
2896   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2897       "pads_activate successful");
2898
2899   return TRUE;
2900
2901   /* ERRORS */
2902 src_failed:
2903   {
2904     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2905         "source pads_activate failed");
2906     return FALSE;
2907   }
2908 sink_failed:
2909   {
2910     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2911         "sink pads_activate failed");
2912     return FALSE;
2913   }
2914 caps_failed:
2915   {
2916     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2917         "failed to clear caps on pads");
2918     return FALSE;
2919   }
2920 }
2921
2922 /* is called with STATE_LOCK */
2923 static GstStateChangeReturn
2924 gst_element_change_state_func (GstElement * element, GstStateChange transition)
2925 {
2926   GstState state, next;
2927   GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
2928   GstClock **clock_p;
2929
2930   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2931
2932   state = (GstState) GST_STATE_TRANSITION_CURRENT (transition);
2933   next = GST_STATE_TRANSITION_NEXT (transition);
2934
2935   /* if the element already is in the given state, we just return success */
2936   if (next == GST_STATE_VOID_PENDING || state == next)
2937     goto was_ok;
2938
2939   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element,
2940       "default handler tries setting state from %s to %s (%04x)",
2941       gst_element_state_get_name (state),
2942       gst_element_state_get_name (next), transition);
2943
2944   switch (transition) {
2945     case GST_STATE_CHANGE_NULL_TO_READY:
2946       break;
2947     case GST_STATE_CHANGE_READY_TO_PAUSED:
2948       if (!gst_element_pads_activate (element, TRUE)) {
2949         result = GST_STATE_CHANGE_FAILURE;
2950       }
2951       break;
2952     case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
2953       break;
2954     case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
2955       break;
2956     case GST_STATE_CHANGE_PAUSED_TO_READY:
2957     case GST_STATE_CHANGE_READY_TO_NULL:
2958       /* deactivate pads in both cases, since they are activated on
2959          ready->paused but the element might not have made it to paused */
2960       if (!gst_element_pads_activate (element, FALSE)) {
2961         result = GST_STATE_CHANGE_FAILURE;
2962       } else {
2963         gst_element_set_base_time (element, 0);
2964       }
2965
2966       /* In null state release the reference to the clock */
2967       GST_OBJECT_LOCK (element);
2968       clock_p = &element->clock;
2969       gst_object_replace ((GstObject **) clock_p, NULL);
2970       GST_OBJECT_UNLOCK (element);
2971       break;
2972     default:
2973       /* this will catch real but unhandled state changes;
2974        * can only be caused by:
2975        * - a new state was added
2976        * - somehow the element was asked to jump across an intermediate state
2977        */
2978       g_warning ("Unhandled state change from %s to %s",
2979           gst_element_state_get_name (state),
2980           gst_element_state_get_name (next));
2981       break;
2982   }
2983   return result;
2984
2985 was_ok:
2986   {
2987     GST_OBJECT_LOCK (element);
2988     result = GST_STATE_RETURN (element);
2989     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2990         "element is already in the %s state",
2991         gst_element_state_get_name (state));
2992     GST_OBJECT_UNLOCK (element);
2993
2994     return result;
2995   }
2996 }
2997
2998 /**
2999  * gst_element_get_factory:
3000  * @element: a #GstElement to request the element factory of.
3001  *
3002  * Retrieves the factory that was used to create this element.
3003  *
3004  * Returns: (transfer none): the #GstElementFactory used for creating this
3005  *     element. no refcounting is needed.
3006  */
3007 GstElementFactory *
3008 gst_element_get_factory (GstElement * element)
3009 {
3010   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
3011
3012   return GST_ELEMENT_GET_CLASS (element)->elementfactory;
3013 }
3014
3015 static void
3016 gst_element_dispose (GObject * object)
3017 {
3018   GstElement *element = GST_ELEMENT_CAST (object);
3019   GstClock **clock_p;
3020   GstBus **bus_p;
3021
3022   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "dispose");
3023
3024   if (GST_STATE (element) != GST_STATE_NULL)
3025     goto not_null;
3026
3027   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
3028       "removing %d pads", g_list_length (element->pads));
3029   /* first we break all our links with the outside */
3030   while (element->pads && element->pads->data) {
3031     /* don't call _remove_pad with NULL */
3032     gst_element_remove_pad (element, GST_PAD_CAST (element->pads->data));
3033   }
3034   if (G_UNLIKELY (element->pads != NULL)) {
3035     g_critical ("could not remove pads from element %s",
3036         GST_STR_NULL (GST_OBJECT_NAME (object)));
3037   }
3038
3039   GST_OBJECT_LOCK (element);
3040   clock_p = &element->clock;
3041   bus_p = &element->bus;
3042   gst_object_replace ((GstObject **) clock_p, NULL);
3043   gst_object_replace ((GstObject **) bus_p, NULL);
3044   GST_OBJECT_UNLOCK (element);
3045
3046   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "parent class dispose");
3047
3048   G_OBJECT_CLASS (parent_class)->dispose (object);
3049
3050   return;
3051
3052   /* ERRORS */
3053 not_null:
3054   {
3055     gboolean is_locked;
3056
3057     is_locked = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
3058     g_critical
3059         ("\nTrying to dispose element %s, but it is in %s%s instead of the NULL"
3060         " state.\n"
3061         "You need to explicitly set elements to the NULL state before\n"
3062         "dropping the final reference, to allow them to clean up.\n"
3063         "This problem may also be caused by a refcounting bug in the\n"
3064         "application or some element.\n",
3065         GST_OBJECT_NAME (element),
3066         gst_element_state_get_name (GST_STATE (element)),
3067         is_locked ? " (locked)" : "");
3068     return;
3069   }
3070 }
3071
3072 static void
3073 gst_element_finalize (GObject * object)
3074 {
3075   GstElement *element = GST_ELEMENT_CAST (object);
3076
3077   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize");
3078
3079   GST_STATE_LOCK (element);
3080   if (element->state_cond)
3081     g_cond_free (element->state_cond);
3082   element->state_cond = NULL;
3083   GST_STATE_UNLOCK (element);
3084   g_static_rec_mutex_free (element->state_lock);
3085   g_slice_free (GStaticRecMutex, element->state_lock);
3086   element->state_lock = NULL;
3087
3088   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize parent");
3089
3090   G_OBJECT_CLASS (parent_class)->finalize (object);
3091 }
3092
3093 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
3094 /**
3095  * gst_element_save_thyself:
3096  * @element: a #GstElement to save.
3097  * @parent: the xml parent node.
3098  *
3099  * Saves the element as part of the given XML structure.
3100  *
3101  * Returns: the new #xmlNodePtr.
3102  */
3103 static xmlNodePtr
3104 gst_element_save_thyself (GstObject * object, xmlNodePtr parent)
3105 {
3106   GList *pads;
3107   GstElementClass *oclass;
3108   GParamSpec **specs, *spec;
3109   guint nspecs;
3110   guint i;
3111   GValue value = { 0, };
3112   GstElement *element;
3113
3114   g_return_val_if_fail (GST_IS_ELEMENT (object), parent);
3115
3116   element = GST_ELEMENT_CAST (object);
3117
3118   oclass = GST_ELEMENT_GET_CLASS (element);
3119
3120   xmlNewChild (parent, NULL, (xmlChar *) "name",
3121       (xmlChar *) GST_ELEMENT_NAME (element));
3122
3123   if (oclass->elementfactory != NULL) {
3124     GstElementFactory *factory = (GstElementFactory *) oclass->elementfactory;
3125
3126     xmlNewChild (parent, NULL, (xmlChar *) "type",
3127         (xmlChar *) GST_PLUGIN_FEATURE (factory)->name);
3128   }
3129
3130   /* params */
3131   specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (object), &nspecs);
3132
3133   for (i = 0; i < nspecs; i++) {
3134     spec = specs[i];
3135     if (spec->flags & G_PARAM_READABLE) {
3136       xmlNodePtr param;
3137       char *contents;
3138
3139       g_value_init (&value, spec->value_type);
3140
3141       g_object_get_property (G_OBJECT (element), spec->name, &value);
3142       param = xmlNewChild (parent, NULL, (xmlChar *) "param", NULL);
3143       xmlNewChild (param, NULL, (xmlChar *) "name", (xmlChar *) spec->name);
3144
3145       if (G_IS_PARAM_SPEC_STRING (spec))
3146         contents = g_value_dup_string (&value);
3147       else if (G_IS_PARAM_SPEC_ENUM (spec))
3148         contents = g_strdup_printf ("%d", g_value_get_enum (&value));
3149       else if (G_IS_PARAM_SPEC_INT64 (spec))
3150         contents = g_strdup_printf ("%" G_GINT64_FORMAT,
3151             g_value_get_int64 (&value));
3152       else if (GST_VALUE_HOLDS_STRUCTURE (&value)) {
3153         if (g_value_get_boxed (&value) != NULL) {
3154           contents = g_strdup_value_contents (&value);
3155         } else {
3156           contents = g_strdup ("NULL");
3157         }
3158       } else
3159         contents = g_strdup_value_contents (&value);
3160
3161       xmlNewChild (param, NULL, (xmlChar *) "value", (xmlChar *) contents);
3162       g_free (contents);
3163
3164       g_value_unset (&value);
3165     }
3166   }
3167
3168   g_free (specs);
3169
3170   pads = g_list_last (GST_ELEMENT_PADS (element));
3171
3172   while (pads) {
3173     GstPad *pad = GST_PAD_CAST (pads->data);
3174
3175     /* figure out if it's a direct pad or a ghostpad */
3176     if (GST_ELEMENT_CAST (GST_OBJECT_PARENT (pad)) == element) {
3177       xmlNodePtr padtag = xmlNewChild (parent, NULL, (xmlChar *) "pad", NULL);
3178
3179       gst_object_save_thyself (GST_OBJECT_CAST (pad), padtag);
3180     }
3181     pads = g_list_previous (pads);
3182   }
3183
3184   return parent;
3185 }
3186
3187 static void
3188 gst_element_restore_thyself (GstObject * object, xmlNodePtr self)
3189 {
3190   xmlNodePtr children;
3191   GstElement *element;
3192   gchar *name = NULL;
3193   gchar *value = NULL;
3194
3195   element = GST_ELEMENT_CAST (object);
3196   g_return_if_fail (element != NULL);
3197
3198   /* parameters */
3199   children = self->xmlChildrenNode;
3200   while (children) {
3201     if (!strcmp ((char *) children->name, "param")) {
3202       xmlNodePtr child = children->xmlChildrenNode;
3203
3204       while (child) {
3205         if (!strcmp ((char *) child->name, "name")) {
3206           name = (gchar *) xmlNodeGetContent (child);
3207         } else if (!strcmp ((char *) child->name, "value")) {
3208           value = (gchar *) xmlNodeGetContent (child);
3209         }
3210         child = child->next;
3211       }
3212       /* FIXME: can this just be g_object_set ? */
3213       gst_util_set_object_arg (G_OBJECT (element), name, value);
3214       /* g_object_set (G_OBJECT (element), name, value, NULL); */
3215       g_free (name);
3216       g_free (value);
3217     }
3218     children = children->next;
3219   }
3220
3221   /* pads */
3222   children = self->xmlChildrenNode;
3223   while (children) {
3224     if (!strcmp ((char *) children->name, "pad")) {
3225       gst_pad_load_and_link (children, GST_OBJECT_CAST (element));
3226     }
3227     children = children->next;
3228   }
3229
3230   if (GST_OBJECT_CLASS (parent_class)->restore_thyself)
3231     (GST_OBJECT_CLASS (parent_class)->restore_thyself) (object, self);
3232 }
3233 #endif /* GST_DISABLE_LOADSAVE */
3234
3235 static void
3236 gst_element_set_bus_func (GstElement * element, GstBus * bus)
3237 {
3238   GstBus **bus_p;
3239
3240   g_return_if_fail (GST_IS_ELEMENT (element));
3241
3242   GST_CAT_DEBUG_OBJECT (GST_CAT_PARENTAGE, element, "setting bus to %p", bus);
3243
3244   GST_OBJECT_LOCK (element);
3245   bus_p = &GST_ELEMENT_BUS (element);
3246   gst_object_replace ((GstObject **) bus_p, GST_OBJECT_CAST (bus));
3247   GST_OBJECT_UNLOCK (element);
3248 }
3249
3250 /**
3251  * gst_element_set_bus:
3252  * @element: a #GstElement to set the bus of.
3253  * @bus: (transfer none): the #GstBus to set.
3254  *
3255  * Sets the bus of the element. Increases the refcount on the bus.
3256  * For internal use only, unless you're testing elements.
3257  *
3258  * MT safe.
3259  */
3260 void
3261 gst_element_set_bus (GstElement * element, GstBus * bus)
3262 {
3263   GstElementClass *oclass;
3264
3265   g_return_if_fail (GST_IS_ELEMENT (element));
3266
3267   oclass = GST_ELEMENT_GET_CLASS (element);
3268
3269   if (oclass->set_bus)
3270     oclass->set_bus (element, bus);
3271 }
3272
3273 /**
3274  * gst_element_get_bus:
3275  * @element: a #GstElement to get the bus of.
3276  *
3277  * Returns the bus of the element. Note that only a #GstPipeline will provide a
3278  * bus for the application.
3279  *
3280  * Returns: (transfer full): the element's #GstBus. unref after usage.
3281  *
3282  * MT safe.
3283  */
3284 GstBus *
3285 gst_element_get_bus (GstElement * element)
3286 {
3287   GstBus *result = NULL;
3288
3289   g_return_val_if_fail (GST_IS_ELEMENT (element), result);
3290
3291   GST_OBJECT_LOCK (element);
3292   if ((result = GST_ELEMENT_BUS (element)))
3293     gst_object_ref (result);
3294   GST_OBJECT_UNLOCK (element);
3295
3296   GST_CAT_DEBUG_OBJECT (GST_CAT_BUS, element, "got bus %" GST_PTR_FORMAT,
3297       result);
3298
3299   return result;
3300 }