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