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 (e.g. "src_%d"). This version only
1051  * retrieves 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 /* Not static because GstBin has manual state handling too */
2321 void
2322 _priv_gst_element_state_changed (GstElement * element, GstState oldstate,
2323     GstState newstate, GstState pending)
2324 {
2325   GstElementClass *klass = GST_ELEMENT_GET_CLASS (element);
2326   GstMessage *message;
2327
2328   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2329       "notifying about state-changed %s to %s (%s pending)",
2330       gst_element_state_get_name (oldstate),
2331       gst_element_state_get_name (newstate),
2332       gst_element_state_get_name (pending));
2333
2334   if (klass->state_changed)
2335     klass->state_changed (element, oldstate, newstate, pending);
2336
2337   message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2338       oldstate, newstate, pending);
2339   gst_element_post_message (element, message);
2340 }
2341
2342 /**
2343  * gst_element_continue_state:
2344  * @element: a #GstElement to continue the state change of.
2345  * @ret: The previous state return value
2346  *
2347  * Commit the state change of the element and proceed to the next
2348  * pending state if any. This function is used
2349  * by elements that do asynchronous state changes.
2350  * The core will normally call this method automatically when an
2351  * element returned %GST_STATE_CHANGE_SUCCESS from the state change function.
2352  *
2353  * If after calling this method the element still has not reached
2354  * the pending state, the next state change is performed.
2355  *
2356  * This method is used internally and should normally not be called by plugins
2357  * or applications.
2358  *
2359  * Returns: The result of the commit state change.
2360  *
2361  * MT safe.
2362  */
2363 GstStateChangeReturn
2364 gst_element_continue_state (GstElement * element, GstStateChangeReturn ret)
2365 {
2366   GstStateChangeReturn old_ret;
2367   GstState old_state, old_next;
2368   GstState current, next, pending;
2369   GstStateChange transition;
2370
2371   GST_OBJECT_LOCK (element);
2372   old_ret = GST_STATE_RETURN (element);
2373   GST_STATE_RETURN (element) = ret;
2374   pending = GST_STATE_PENDING (element);
2375
2376   /* check if there is something to commit */
2377   if (pending == GST_STATE_VOID_PENDING)
2378     goto nothing_pending;
2379
2380   old_state = GST_STATE (element);
2381   /* this is the state we should go to next */
2382   old_next = GST_STATE_NEXT (element);
2383   /* update current state */
2384   current = GST_STATE (element) = old_next;
2385
2386   /* see if we reached the final state */
2387   if (pending == current)
2388     goto complete;
2389
2390   next = GST_STATE_GET_NEXT (current, pending);
2391   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2392
2393   GST_STATE_NEXT (element) = next;
2394   /* mark busy */
2395   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2396   GST_OBJECT_UNLOCK (element);
2397
2398   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2399       "committing state from %s to %s, pending %s, next %s",
2400       gst_element_state_get_name (old_state),
2401       gst_element_state_get_name (old_next),
2402       gst_element_state_get_name (pending), gst_element_state_get_name (next));
2403
2404   _priv_gst_element_state_changed (element, old_state, old_next, pending);
2405
2406   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2407       "continue state change %s to %s, final %s",
2408       gst_element_state_get_name (current),
2409       gst_element_state_get_name (next), gst_element_state_get_name (pending));
2410
2411   ret = gst_element_change_state (element, transition);
2412
2413   return ret;
2414
2415 nothing_pending:
2416   {
2417     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "nothing pending");
2418     GST_OBJECT_UNLOCK (element);
2419     return ret;
2420   }
2421 complete:
2422   {
2423     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2424     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2425
2426     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2427         "completed state change to %s", gst_element_state_get_name (pending));
2428     GST_OBJECT_UNLOCK (element);
2429
2430     /* don't post silly messages with the same state. This can happen
2431      * when an element state is changed to what it already was. For bins
2432      * this can be the result of a lost state, which we check with the
2433      * previous return value.
2434      * We do signal the cond though as a _get_state() might be blocking
2435      * on it. */
2436     if (old_state != old_next || old_ret == GST_STATE_CHANGE_ASYNC)
2437       _priv_gst_element_state_changed (element, old_state, old_next,
2438           GST_STATE_VOID_PENDING);
2439
2440     GST_STATE_BROADCAST (element);
2441
2442     return ret;
2443   }
2444 }
2445
2446 /**
2447  * gst_element_lost_state_full:
2448  * @element: a #GstElement the state is lost of
2449  * @new_base_time: if a new base time should be distributed
2450  *
2451  * Brings the element to the lost state. The current state of the
2452  * element is copied to the pending state so that any call to
2453  * gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC.
2454  *
2455  * An ASYNC_START message is posted with indication to distribute a new
2456  * base_time to the element when @new_base_time is %TRUE.
2457  * If the element was PLAYING, it will go to PAUSED. The element
2458  * will be restored to its PLAYING state by the parent pipeline when it
2459  * prerolls again.
2460  *
2461  * This is mostly used for elements that lost their preroll buffer
2462  * in the %GST_STATE_PAUSED or %GST_STATE_PLAYING state after a flush,
2463  * they will go to their pending state again when a new preroll buffer is
2464  * queued. This function can only be called when the element is currently
2465  * not in error or an async state change.
2466  *
2467  * This function is used internally and should normally not be called from
2468  * plugins or applications.
2469  *
2470  * MT safe.
2471  *
2472  * Since: 0.10.24
2473  */
2474 void
2475 gst_element_lost_state_full (GstElement * element, gboolean new_base_time)
2476 {
2477   GstState old_state, new_state;
2478   GstMessage *message;
2479
2480   g_return_if_fail (GST_IS_ELEMENT (element));
2481
2482   GST_OBJECT_LOCK (element);
2483   if (GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2484     goto nothing_lost;
2485
2486   if (GST_STATE_PENDING (element) != GST_STATE_VOID_PENDING)
2487     goto only_async_start;
2488
2489   old_state = GST_STATE (element);
2490
2491   /* when we were PLAYING, the new state is PAUSED. We will also not
2492    * automatically go to PLAYING but let the parent bin(s) set us to PLAYING
2493    * when we preroll. */
2494   if (old_state > GST_STATE_PAUSED)
2495     new_state = GST_STATE_PAUSED;
2496   else
2497     new_state = old_state;
2498
2499   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2500       "lost state of %s to %s", gst_element_state_get_name (old_state),
2501       gst_element_state_get_name (new_state));
2502
2503   GST_STATE (element) = new_state;
2504   GST_STATE_NEXT (element) = new_state;
2505   GST_STATE_PENDING (element) = new_state;
2506   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2507   if (new_base_time)
2508     GST_ELEMENT_START_TIME (element) = 0;
2509   GST_OBJECT_UNLOCK (element);
2510
2511   _priv_gst_element_state_changed (element, new_state, new_state, new_state);
2512
2513   message =
2514       gst_message_new_async_start (GST_OBJECT_CAST (element), new_base_time);
2515   gst_element_post_message (element, message);
2516
2517   return;
2518
2519 nothing_lost:
2520   {
2521     GST_OBJECT_UNLOCK (element);
2522     return;
2523   }
2524 only_async_start:
2525   {
2526     GST_OBJECT_UNLOCK (element);
2527
2528     message = gst_message_new_async_start (GST_OBJECT_CAST (element), TRUE);
2529     gst_element_post_message (element, message);
2530     return;
2531   }
2532 }
2533
2534 /**
2535  * gst_element_lost_state:
2536  * @element: a #GstElement the state is lost of
2537  *
2538  * Brings the element to the lost state. This function calls
2539  * gst_element_lost_state_full() with the new_base_time set to %TRUE.
2540  *
2541  * This function is used internally and should normally not be called from
2542  * plugins or applications.
2543  *
2544  * MT safe.
2545  */
2546 void
2547 gst_element_lost_state (GstElement * element)
2548 {
2549   gst_element_lost_state_full (element, TRUE);
2550 }
2551
2552 /**
2553  * gst_element_set_state:
2554  * @element: a #GstElement to change state of.
2555  * @state: the element's new #GstState.
2556  *
2557  * Sets the state of the element. This function will try to set the
2558  * requested state by going through all the intermediary states and calling
2559  * the class's state change function for each.
2560  *
2561  * This function can return #GST_STATE_CHANGE_ASYNC, in which case the
2562  * element will perform the remainder of the state change asynchronously in
2563  * another thread.
2564  * An application can use gst_element_get_state() to wait for the completion
2565  * of the state change or it can wait for a state change message on the bus.
2566  *
2567  * State changes to %GST_STATE_READY or %GST_STATE_NULL never return
2568  * #GST_STATE_CHANGE_ASYNC.
2569  *
2570  * Returns: Result of the state change using #GstStateChangeReturn.
2571  *
2572  * MT safe.
2573  */
2574 GstStateChangeReturn
2575 gst_element_set_state (GstElement * element, GstState state)
2576 {
2577   GstElementClass *oclass;
2578   GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2579
2580   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2581
2582   oclass = GST_ELEMENT_GET_CLASS (element);
2583
2584   if (oclass->set_state)
2585     result = (oclass->set_state) (element, state);
2586
2587   return result;
2588 }
2589
2590 /*
2591  * default set state function, calculates the next state based
2592  * on current state and calls the change_state function
2593  */
2594 static GstStateChangeReturn
2595 gst_element_set_state_func (GstElement * element, GstState state)
2596 {
2597   GstState current, next, old_pending;
2598   GstStateChangeReturn ret;
2599   GstStateChange transition;
2600   GstStateChangeReturn old_ret;
2601
2602   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2603
2604   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "set_state to %s",
2605       gst_element_state_get_name (state));
2606
2607   /* state lock is taken to protect the set_state() and get_state()
2608    * procedures, it does not lock any variables. */
2609   GST_STATE_LOCK (element);
2610
2611   /* now calculate how to get to the new state */
2612   GST_OBJECT_LOCK (element);
2613   old_ret = GST_STATE_RETURN (element);
2614   /* previous state change returned an error, remove all pending
2615    * and next states */
2616   if (old_ret == GST_STATE_CHANGE_FAILURE) {
2617     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2618     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2619     GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
2620   }
2621
2622   current = GST_STATE (element);
2623   next = GST_STATE_NEXT (element);
2624   old_pending = GST_STATE_PENDING (element);
2625
2626   /* this is the (new) state we should go to. TARGET is the last state we set on
2627    * the element. */
2628   if (state != GST_STATE_TARGET (element)) {
2629     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2630         "setting target state to %s", gst_element_state_get_name (state));
2631     GST_STATE_TARGET (element) = state;
2632     /* increment state cookie so that we can track each state change. We only do
2633      * this if this is actually a new state change. */
2634     element->state_cookie++;
2635   }
2636   GST_STATE_PENDING (element) = state;
2637
2638   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2639       "current %s, old_pending %s, next %s, old return %s",
2640       gst_element_state_get_name (current),
2641       gst_element_state_get_name (old_pending),
2642       gst_element_state_get_name (next),
2643       gst_element_state_change_return_get_name (old_ret));
2644
2645   /* if the element was busy doing a state change, we just update the
2646    * target state, it'll get to it async then. */
2647   if (old_pending != GST_STATE_VOID_PENDING) {
2648     /* upwards state change will happen ASYNC */
2649     if (old_pending <= state)
2650       goto was_busy;
2651     /* element is going to this state already */
2652     else if (next == state)
2653       goto was_busy;
2654     /* element was performing an ASYNC upward state change and
2655      * we request to go downward again. Start from the next pending
2656      * state then. */
2657     else if (next > state
2658         && GST_STATE_RETURN (element) == GST_STATE_CHANGE_ASYNC) {
2659       current = next;
2660     }
2661   }
2662   next = GST_STATE_GET_NEXT (current, state);
2663   /* now we store the next state */
2664   GST_STATE_NEXT (element) = next;
2665   /* mark busy, we need to check that there is actually a state change
2666    * to be done else we could accidentally override SUCCESS/NO_PREROLL and
2667    * the default element change_state function has no way to know what the
2668    * old value was... could consider this a FIXME...*/
2669   if (current != next)
2670     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2671
2672   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2673
2674   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2675       "%s: setting state from %s to %s",
2676       (next != state ? "intermediate" : "final"),
2677       gst_element_state_get_name (current), gst_element_state_get_name (next));
2678
2679   /* now signal any waiters, they will error since the cookie was incremented */
2680   GST_STATE_BROADCAST (element);
2681
2682   GST_OBJECT_UNLOCK (element);
2683
2684   ret = gst_element_change_state (element, transition);
2685
2686   GST_STATE_UNLOCK (element);
2687
2688   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "returned %s",
2689       gst_element_state_change_return_get_name (ret));
2690
2691   return ret;
2692
2693 was_busy:
2694   {
2695     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2696     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2697         "element was busy with async state change");
2698     GST_OBJECT_UNLOCK (element);
2699
2700     GST_STATE_UNLOCK (element);
2701
2702     return GST_STATE_CHANGE_ASYNC;
2703   }
2704 }
2705
2706 /**
2707  * gst_element_change_state:
2708  * @element: a #GstElement
2709  * @transition: the requested transition
2710  *
2711  * Perform @transition on @element.
2712  *
2713  * This function must be called with STATE_LOCK held and is mainly used
2714  * internally.
2715  *
2716  * Returns: the #GstStateChangeReturn of the state transition.
2717  */
2718 GstStateChangeReturn
2719 gst_element_change_state (GstElement * element, GstStateChange transition)
2720 {
2721   GstElementClass *oclass;
2722   GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
2723
2724   oclass = GST_ELEMENT_GET_CLASS (element);
2725
2726   /* call the state change function so it can set the state */
2727   if (oclass->change_state)
2728     ret = (oclass->change_state) (element, transition);
2729   else
2730     ret = GST_STATE_CHANGE_FAILURE;
2731
2732   switch (ret) {
2733     case GST_STATE_CHANGE_FAILURE:
2734       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2735           "have FAILURE change_state return");
2736       /* state change failure */
2737       gst_element_abort_state (element);
2738       break;
2739     case GST_STATE_CHANGE_ASYNC:
2740     {
2741       GstState target;
2742
2743       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2744           "element will change state ASYNC");
2745
2746       target = GST_STATE_TARGET (element);
2747
2748       if (target > GST_STATE_READY)
2749         goto async;
2750
2751       /* else we just continue the state change downwards */
2752       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2753           "forcing commit state %s <= %s",
2754           gst_element_state_get_name (target),
2755           gst_element_state_get_name (GST_STATE_READY));
2756
2757       ret = gst_element_continue_state (element, GST_STATE_CHANGE_SUCCESS);
2758       break;
2759     }
2760     case GST_STATE_CHANGE_SUCCESS:
2761       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2762           "element changed state SUCCESS");
2763       /* we can commit the state now which will proceeed to
2764        * the next state */
2765       ret = gst_element_continue_state (element, ret);
2766       break;
2767     case GST_STATE_CHANGE_NO_PREROLL:
2768       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2769           "element changed state NO_PREROLL");
2770       /* we can commit the state now which will proceeed to
2771        * the next state */
2772       ret = gst_element_continue_state (element, ret);
2773       break;
2774     default:
2775       goto invalid_return;
2776   }
2777
2778   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit state change %d", ret);
2779
2780   return ret;
2781
2782 async:
2783   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit async state change %d",
2784       ret);
2785
2786   return ret;
2787
2788   /* ERROR */
2789 invalid_return:
2790   {
2791     GST_OBJECT_LOCK (element);
2792     /* somebody added a GST_STATE_ and forgot to do stuff here ! */
2793     g_critical ("%s: unknown return value %d from a state change function",
2794         GST_ELEMENT_NAME (element), ret);
2795
2796     /* we are in error now */
2797     ret = GST_STATE_CHANGE_FAILURE;
2798     GST_STATE_RETURN (element) = ret;
2799     GST_OBJECT_UNLOCK (element);
2800
2801     return ret;
2802   }
2803 }
2804
2805 /* gst_iterator_fold functions for pads_activate
2806  * Stop the iterator if activating one pad failed. */
2807 static gboolean
2808 activate_pads (GstPad * pad, GValue * ret, gboolean * active)
2809 {
2810   gboolean cont = TRUE;
2811
2812   if (!(cont = gst_pad_set_active (pad, *active)))
2813     g_value_set_boolean (ret, FALSE);
2814
2815   /* unref the object that was reffed for us by _fold */
2816   gst_object_unref (pad);
2817   return cont;
2818 }
2819
2820 /* set the caps on the pad to NULL */
2821 static gboolean
2822 clear_caps (GstPad * pad, GValue * ret, gboolean * active)
2823 {
2824   gst_pad_set_caps (pad, NULL);
2825   gst_object_unref (pad);
2826   return TRUE;
2827 }
2828
2829 /* returns false on error or early cutout of the fold, true if all
2830  * pads in @iter were (de)activated successfully. */
2831 static gboolean
2832 iterator_activate_fold_with_resync (GstIterator * iter,
2833     GstIteratorFoldFunction func, gpointer user_data)
2834 {
2835   GstIteratorResult ires;
2836   GValue ret = { 0 };
2837
2838   /* no need to unset this later, it's just a boolean */
2839   g_value_init (&ret, G_TYPE_BOOLEAN);
2840   g_value_set_boolean (&ret, TRUE);
2841
2842   while (1) {
2843     ires = gst_iterator_fold (iter, func, &ret, user_data);
2844     switch (ires) {
2845       case GST_ITERATOR_RESYNC:
2846         /* need to reset the result again */
2847         g_value_set_boolean (&ret, TRUE);
2848         gst_iterator_resync (iter);
2849         break;
2850       case GST_ITERATOR_DONE:
2851         /* all pads iterated, return collected value */
2852         goto done;
2853       default:
2854         /* iterator returned _ERROR or premature end with _OK,
2855          * mark an error and exit */
2856         g_value_set_boolean (&ret, FALSE);
2857         goto done;
2858     }
2859   }
2860 done:
2861   /* return collected value */
2862   return g_value_get_boolean (&ret);
2863 }
2864
2865 /* is called with STATE_LOCK
2866  *
2867  * Pads are activated from source pads to sinkpads.
2868  */
2869 static gboolean
2870 gst_element_pads_activate (GstElement * element, gboolean active)
2871 {
2872   GstIterator *iter;
2873   gboolean res;
2874
2875   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2876       "pads_activate with active %d", active);
2877
2878   iter = gst_element_iterate_src_pads (element);
2879   res =
2880       iterator_activate_fold_with_resync (iter,
2881       (GstIteratorFoldFunction) activate_pads, &active);
2882   gst_iterator_free (iter);
2883   if (G_UNLIKELY (!res))
2884     goto src_failed;
2885
2886   iter = gst_element_iterate_sink_pads (element);
2887   res =
2888       iterator_activate_fold_with_resync (iter,
2889       (GstIteratorFoldFunction) activate_pads, &active);
2890   gst_iterator_free (iter);
2891   if (G_UNLIKELY (!res))
2892     goto sink_failed;
2893
2894   if (!active) {
2895     /* clear the caps on all pads, this should never fail */
2896     iter = gst_element_iterate_pads (element);
2897     res =
2898         iterator_activate_fold_with_resync (iter,
2899         (GstIteratorFoldFunction) clear_caps, &active);
2900     gst_iterator_free (iter);
2901     if (G_UNLIKELY (!res))
2902       goto caps_failed;
2903   }
2904
2905   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2906       "pads_activate successful");
2907
2908   return TRUE;
2909
2910   /* ERRORS */
2911 src_failed:
2912   {
2913     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2914         "source pads_activate failed");
2915     return FALSE;
2916   }
2917 sink_failed:
2918   {
2919     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2920         "sink pads_activate failed");
2921     return FALSE;
2922   }
2923 caps_failed:
2924   {
2925     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2926         "failed to clear caps on pads");
2927     return FALSE;
2928   }
2929 }
2930
2931 /* is called with STATE_LOCK */
2932 static GstStateChangeReturn
2933 gst_element_change_state_func (GstElement * element, GstStateChange transition)
2934 {
2935   GstState state, next;
2936   GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
2937   GstClock **clock_p;
2938
2939   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2940
2941   state = (GstState) GST_STATE_TRANSITION_CURRENT (transition);
2942   next = GST_STATE_TRANSITION_NEXT (transition);
2943
2944   /* if the element already is in the given state, we just return success */
2945   if (next == GST_STATE_VOID_PENDING || state == next)
2946     goto was_ok;
2947
2948   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element,
2949       "default handler tries setting state from %s to %s (%04x)",
2950       gst_element_state_get_name (state),
2951       gst_element_state_get_name (next), transition);
2952
2953   switch (transition) {
2954     case GST_STATE_CHANGE_NULL_TO_READY:
2955       break;
2956     case GST_STATE_CHANGE_READY_TO_PAUSED:
2957       if (!gst_element_pads_activate (element, TRUE)) {
2958         result = GST_STATE_CHANGE_FAILURE;
2959       }
2960       break;
2961     case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
2962       break;
2963     case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
2964       break;
2965     case GST_STATE_CHANGE_PAUSED_TO_READY:
2966     case GST_STATE_CHANGE_READY_TO_NULL:
2967       /* deactivate pads in both cases, since they are activated on
2968          ready->paused but the element might not have made it to paused */
2969       if (!gst_element_pads_activate (element, FALSE)) {
2970         result = GST_STATE_CHANGE_FAILURE;
2971       } else {
2972         gst_element_set_base_time (element, 0);
2973       }
2974
2975       /* In null state release the reference to the clock */
2976       GST_OBJECT_LOCK (element);
2977       clock_p = &element->clock;
2978       gst_object_replace ((GstObject **) clock_p, NULL);
2979       GST_OBJECT_UNLOCK (element);
2980       break;
2981     default:
2982       /* this will catch real but unhandled state changes;
2983        * can only be caused by:
2984        * - a new state was added
2985        * - somehow the element was asked to jump across an intermediate state
2986        */
2987       g_warning ("Unhandled state change from %s to %s",
2988           gst_element_state_get_name (state),
2989           gst_element_state_get_name (next));
2990       break;
2991   }
2992   return result;
2993
2994 was_ok:
2995   {
2996     GST_OBJECT_LOCK (element);
2997     result = GST_STATE_RETURN (element);
2998     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2999         "element is already in the %s state",
3000         gst_element_state_get_name (state));
3001     GST_OBJECT_UNLOCK (element);
3002
3003     return result;
3004   }
3005 }
3006
3007 /**
3008  * gst_element_get_factory:
3009  * @element: a #GstElement to request the element factory of.
3010  *
3011  * Retrieves the factory that was used to create this element.
3012  *
3013  * Returns: (transfer none): the #GstElementFactory used for creating this
3014  *     element. no refcounting is needed.
3015  */
3016 GstElementFactory *
3017 gst_element_get_factory (GstElement * element)
3018 {
3019   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
3020
3021   return GST_ELEMENT_GET_CLASS (element)->elementfactory;
3022 }
3023
3024 static void
3025 gst_element_dispose (GObject * object)
3026 {
3027   GstElement *element = GST_ELEMENT_CAST (object);
3028   GstClock **clock_p;
3029   GstBus **bus_p;
3030
3031   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "dispose");
3032
3033   if (GST_STATE (element) != GST_STATE_NULL)
3034     goto not_null;
3035
3036   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
3037       "removing %d pads", g_list_length (element->pads));
3038   /* first we break all our links with the outside */
3039   while (element->pads && element->pads->data) {
3040     /* don't call _remove_pad with NULL */
3041     gst_element_remove_pad (element, GST_PAD_CAST (element->pads->data));
3042   }
3043   if (G_UNLIKELY (element->pads != NULL)) {
3044     g_critical ("could not remove pads from element %s",
3045         GST_STR_NULL (GST_OBJECT_NAME (object)));
3046   }
3047
3048   GST_OBJECT_LOCK (element);
3049   clock_p = &element->clock;
3050   bus_p = &element->bus;
3051   gst_object_replace ((GstObject **) clock_p, NULL);
3052   gst_object_replace ((GstObject **) bus_p, NULL);
3053   GST_OBJECT_UNLOCK (element);
3054
3055   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "parent class dispose");
3056
3057   G_OBJECT_CLASS (parent_class)->dispose (object);
3058
3059   return;
3060
3061   /* ERRORS */
3062 not_null:
3063   {
3064     gboolean is_locked;
3065
3066     is_locked = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
3067     g_critical
3068         ("\nTrying to dispose element %s, but it is in %s%s instead of the NULL"
3069         " state.\n"
3070         "You need to explicitly set elements to the NULL state before\n"
3071         "dropping the final reference, to allow them to clean up.\n"
3072         "This problem may also be caused by a refcounting bug in the\n"
3073         "application or some element.\n",
3074         GST_OBJECT_NAME (element),
3075         gst_element_state_get_name (GST_STATE (element)),
3076         is_locked ? " (locked)" : "");
3077     return;
3078   }
3079 }
3080
3081 static void
3082 gst_element_finalize (GObject * object)
3083 {
3084   GstElement *element = GST_ELEMENT_CAST (object);
3085
3086   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize");
3087
3088   GST_STATE_LOCK (element);
3089   if (element->state_cond)
3090     g_cond_free (element->state_cond);
3091   element->state_cond = NULL;
3092   GST_STATE_UNLOCK (element);
3093   g_static_rec_mutex_free (element->state_lock);
3094   g_slice_free (GStaticRecMutex, element->state_lock);
3095   element->state_lock = NULL;
3096
3097   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize parent");
3098
3099   G_OBJECT_CLASS (parent_class)->finalize (object);
3100 }
3101
3102 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
3103 /**
3104  * gst_element_save_thyself:
3105  * @element: a #GstElement to save.
3106  * @parent: the xml parent node.
3107  *
3108  * Saves the element as part of the given XML structure.
3109  *
3110  * Returns: the new #xmlNodePtr.
3111  */
3112 static xmlNodePtr
3113 gst_element_save_thyself (GstObject * object, xmlNodePtr parent)
3114 {
3115   GList *pads;
3116   GstElementClass *oclass;
3117   GParamSpec **specs, *spec;
3118   guint nspecs;
3119   guint i;
3120   GValue value = { 0, };
3121   GstElement *element;
3122
3123   g_return_val_if_fail (GST_IS_ELEMENT (object), parent);
3124
3125   element = GST_ELEMENT_CAST (object);
3126
3127   oclass = GST_ELEMENT_GET_CLASS (element);
3128
3129   xmlNewChild (parent, NULL, (xmlChar *) "name",
3130       (xmlChar *) GST_ELEMENT_NAME (element));
3131
3132   if (oclass->elementfactory != NULL) {
3133     GstElementFactory *factory = (GstElementFactory *) oclass->elementfactory;
3134
3135     xmlNewChild (parent, NULL, (xmlChar *) "type",
3136         (xmlChar *) GST_PLUGIN_FEATURE (factory)->name);
3137   }
3138
3139   /* params */
3140   specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (object), &nspecs);
3141
3142   for (i = 0; i < nspecs; i++) {
3143     spec = specs[i];
3144     if (spec->flags & G_PARAM_READABLE) {
3145       xmlNodePtr param;
3146       char *contents;
3147
3148       g_value_init (&value, spec->value_type);
3149
3150       g_object_get_property (G_OBJECT (element), spec->name, &value);
3151       param = xmlNewChild (parent, NULL, (xmlChar *) "param", NULL);
3152       xmlNewChild (param, NULL, (xmlChar *) "name", (xmlChar *) spec->name);
3153
3154       if (G_IS_PARAM_SPEC_STRING (spec))
3155         contents = g_value_dup_string (&value);
3156       else if (G_IS_PARAM_SPEC_ENUM (spec))
3157         contents = g_strdup_printf ("%d", g_value_get_enum (&value));
3158       else if (G_IS_PARAM_SPEC_INT64 (spec))
3159         contents = g_strdup_printf ("%" G_GINT64_FORMAT,
3160             g_value_get_int64 (&value));
3161       else if (GST_VALUE_HOLDS_STRUCTURE (&value)) {
3162         if (g_value_get_boxed (&value) != NULL) {
3163           contents = g_strdup_value_contents (&value);
3164         } else {
3165           contents = g_strdup ("NULL");
3166         }
3167       } else
3168         contents = g_strdup_value_contents (&value);
3169
3170       xmlNewChild (param, NULL, (xmlChar *) "value", (xmlChar *) contents);
3171       g_free (contents);
3172
3173       g_value_unset (&value);
3174     }
3175   }
3176
3177   g_free (specs);
3178
3179   pads = g_list_last (GST_ELEMENT_PADS (element));
3180
3181   while (pads) {
3182     GstPad *pad = GST_PAD_CAST (pads->data);
3183
3184     /* figure out if it's a direct pad or a ghostpad */
3185     if (GST_ELEMENT_CAST (GST_OBJECT_PARENT (pad)) == element) {
3186       xmlNodePtr padtag = xmlNewChild (parent, NULL, (xmlChar *) "pad", NULL);
3187
3188       gst_object_save_thyself (GST_OBJECT_CAST (pad), padtag);
3189     }
3190     pads = g_list_previous (pads);
3191   }
3192
3193   return parent;
3194 }
3195
3196 static void
3197 gst_element_restore_thyself (GstObject * object, xmlNodePtr self)
3198 {
3199   xmlNodePtr children;
3200   GstElement *element;
3201   gchar *name = NULL;
3202   gchar *value = NULL;
3203
3204   element = GST_ELEMENT_CAST (object);
3205   g_return_if_fail (element != NULL);
3206
3207   /* parameters */
3208   children = self->xmlChildrenNode;
3209   while (children) {
3210     if (!strcmp ((char *) children->name, "param")) {
3211       xmlNodePtr child = children->xmlChildrenNode;
3212
3213       while (child) {
3214         if (!strcmp ((char *) child->name, "name")) {
3215           name = (gchar *) xmlNodeGetContent (child);
3216         } else if (!strcmp ((char *) child->name, "value")) {
3217           value = (gchar *) xmlNodeGetContent (child);
3218         }
3219         child = child->next;
3220       }
3221       /* FIXME: can this just be g_object_set ? */
3222       gst_util_set_object_arg (G_OBJECT (element), name, value);
3223       /* g_object_set (G_OBJECT (element), name, value, NULL); */
3224       g_free (name);
3225       g_free (value);
3226     }
3227     children = children->next;
3228   }
3229
3230   /* pads */
3231   children = self->xmlChildrenNode;
3232   while (children) {
3233     if (!strcmp ((char *) children->name, "pad")) {
3234       gst_pad_load_and_link (children, GST_OBJECT_CAST (element));
3235     }
3236     children = children->next;
3237   }
3238
3239   if (GST_OBJECT_CLASS (parent_class)->restore_thyself)
3240     (GST_OBJECT_CLASS (parent_class)->restore_thyself) (object, self);
3241 }
3242 #endif /* GST_DISABLE_LOADSAVE */
3243
3244 static void
3245 gst_element_set_bus_func (GstElement * element, GstBus * bus)
3246 {
3247   GstBus **bus_p;
3248
3249   g_return_if_fail (GST_IS_ELEMENT (element));
3250
3251   GST_CAT_DEBUG_OBJECT (GST_CAT_PARENTAGE, element, "setting bus to %p", bus);
3252
3253   GST_OBJECT_LOCK (element);
3254   bus_p = &GST_ELEMENT_BUS (element);
3255   gst_object_replace ((GstObject **) bus_p, GST_OBJECT_CAST (bus));
3256   GST_OBJECT_UNLOCK (element);
3257 }
3258
3259 /**
3260  * gst_element_set_bus:
3261  * @element: a #GstElement to set the bus of.
3262  * @bus: (transfer none): the #GstBus to set.
3263  *
3264  * Sets the bus of the element. Increases the refcount on the bus.
3265  * For internal use only, unless you're testing elements.
3266  *
3267  * MT safe.
3268  */
3269 void
3270 gst_element_set_bus (GstElement * element, GstBus * bus)
3271 {
3272   GstElementClass *oclass;
3273
3274   g_return_if_fail (GST_IS_ELEMENT (element));
3275
3276   oclass = GST_ELEMENT_GET_CLASS (element);
3277
3278   if (oclass->set_bus)
3279     oclass->set_bus (element, bus);
3280 }
3281
3282 /**
3283  * gst_element_get_bus:
3284  * @element: a #GstElement to get the bus of.
3285  *
3286  * Returns the bus of the element. Note that only a #GstPipeline will provide a
3287  * bus for the application.
3288  *
3289  * Returns: (transfer full): the element's #GstBus. unref after usage.
3290  *
3291  * MT safe.
3292  */
3293 GstBus *
3294 gst_element_get_bus (GstElement * element)
3295 {
3296   GstBus *result = NULL;
3297
3298   g_return_val_if_fail (GST_IS_ELEMENT (element), result);
3299
3300   GST_OBJECT_LOCK (element);
3301   if ((result = GST_ELEMENT_BUS (element)))
3302     gst_object_ref (result);
3303   GST_OBJECT_UNLOCK (element);
3304
3305   GST_CAT_DEBUG_OBJECT (GST_CAT_BUS, element, "got bus %" GST_PTR_FORMAT,
3306       result);
3307
3308   return result;
3309 }