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
1184   return _gst_element_request_pad (element, templ, name, caps);
1185 }
1186
1187 /**
1188  * gst_element_get_pad:
1189  * @element: a #GstElement.
1190  * @name: the name of the pad to retrieve.
1191  *
1192  * Retrieves a pad from @element by name. Tries gst_element_get_static_pad()
1193  * first, then gst_element_get_request_pad().
1194  *
1195  * Deprecated: This function is deprecated as it's unclear if the reference
1196  * to the result pad should be released with gst_object_unref() in case of a static pad
1197  * or gst_element_release_request_pad() in case of a request pad.
1198  * Use gst_element_get_static_pad() or gst_element_get_request_pad() instead.
1199  *
1200  * Returns: (transfer full): the #GstPad if found, otherwise %NULL. Unref or Release after usage,
1201  * depending on the type of the pad.
1202  */
1203 #ifndef GST_REMOVE_DEPRECATED
1204 #ifdef GST_DISABLE_DEPRECATED
1205 GstPad *gst_element_get_pad (GstElement * element, const gchar * name);
1206 #endif
1207 GstPad *
1208 gst_element_get_pad (GstElement * element, const gchar * name)
1209 {
1210   GstPad *pad;
1211
1212   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1213   g_return_val_if_fail (name != NULL, NULL);
1214
1215   pad = gst_element_get_static_pad (element, name);
1216   if (!pad)
1217     pad = gst_element_get_request_pad (element, name);
1218
1219   return pad;
1220 }
1221 #endif /* GST_REMOVE_DEPRECATED */
1222
1223 static GstIteratorItem
1224 iterate_pad (GstIterator * it, GstPad * pad)
1225 {
1226   gst_object_ref (pad);
1227   return GST_ITERATOR_ITEM_PASS;
1228 }
1229
1230 static GstIterator *
1231 gst_element_iterate_pad_list (GstElement * element, GList ** padlist)
1232 {
1233   GstIterator *result;
1234
1235   GST_OBJECT_LOCK (element);
1236   gst_object_ref (element);
1237   result = gst_iterator_new_list (GST_TYPE_PAD,
1238       GST_OBJECT_GET_LOCK (element),
1239       &element->pads_cookie,
1240       padlist,
1241       element,
1242       (GstIteratorItemFunction) iterate_pad,
1243       (GstIteratorDisposeFunction) gst_object_unref);
1244   GST_OBJECT_UNLOCK (element);
1245
1246   return result;
1247 }
1248
1249 /**
1250  * gst_element_iterate_pads:
1251  * @element: a #GstElement to iterate pads of.
1252  *
1253  * Retrieves an iterator of @element's pads. The iterator should
1254  * be freed after usage. Also more specialized iterators exists such as
1255  * gst_element_iterate_src_pads() or gst_element_iterate_sink_pads().
1256  *
1257  * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1258  *     after use.
1259  *
1260  * MT safe.
1261  */
1262 GstIterator *
1263 gst_element_iterate_pads (GstElement * element)
1264 {
1265   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1266
1267   return gst_element_iterate_pad_list (element, &element->pads);
1268 }
1269
1270 /**
1271  * gst_element_iterate_src_pads:
1272  * @element: a #GstElement.
1273  *
1274  * Retrieves an iterator of @element's source pads.
1275  *
1276  * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1277  *     after use.
1278  *
1279  * MT safe.
1280  */
1281 GstIterator *
1282 gst_element_iterate_src_pads (GstElement * element)
1283 {
1284   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1285
1286   return gst_element_iterate_pad_list (element, &element->srcpads);
1287 }
1288
1289 /**
1290  * gst_element_iterate_sink_pads:
1291  * @element: a #GstElement.
1292  *
1293  * Retrieves an iterator of @element's sink pads.
1294  *
1295  * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1296  *     after use.
1297  *
1298  * MT safe.
1299  */
1300 GstIterator *
1301 gst_element_iterate_sink_pads (GstElement * element)
1302 {
1303   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1304
1305   return gst_element_iterate_pad_list (element, &element->sinkpads);
1306 }
1307
1308 /**
1309  * gst_element_class_add_pad_template:
1310  * @klass: the #GstElementClass to add the pad template to.
1311  * @templ: (transfer none): a #GstPadTemplate to add to the element class.
1312  *
1313  * Adds a padtemplate to an element class. This is mainly used in the _base_init
1314  * functions of classes.
1315  */
1316 void
1317 gst_element_class_add_pad_template (GstElementClass * klass,
1318     GstPadTemplate * templ)
1319 {
1320   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1321   g_return_if_fail (GST_IS_PAD_TEMPLATE (templ));
1322
1323   /* FIXME 0.11: allow replacing the pad templates by
1324    * calling this with the same name as an already existing pad
1325    * template. For this we _must_ _not_ ref the added pad template
1326    * a second time and _must_ document that this function takes
1327    * ownership of the pad template. Otherwise we will leak pad templates
1328    * or the caller unref's the pad template and it disappears */
1329   /* avoid registering pad templates with the same name */
1330   g_return_if_fail (gst_element_class_get_pad_template (klass,
1331           templ->name_template) == NULL);
1332
1333   klass->padtemplates = g_list_append (klass->padtemplates,
1334       gst_object_ref (templ));
1335   klass->numpadtemplates++;
1336 }
1337
1338 /**
1339  * gst_element_class_add_static_pad_template:
1340  * @klass: the #GstElementClass to add the pad template to.
1341  * @templ: (transfer none): a #GstStaticPadTemplate describing the pad
1342  * to add to the element class.
1343  *
1344  * Adds a padtemplate to an element class. This is mainly used in the _base_init
1345  * functions of classes.
1346  *
1347  * Since: 0.10.36
1348  */
1349 void
1350 gst_element_class_add_static_pad_template (GstElementClass * klass,
1351     GstStaticPadTemplate * templ)
1352 {
1353   GstPadTemplate *pt;
1354
1355   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1356
1357   pt = gst_static_pad_template_get (templ);
1358   gst_element_class_add_pad_template (klass, pt);
1359   gst_object_unref (pt);
1360 }
1361
1362 static void
1363 gst_element_class_add_meta_data (GstElementClass * klass,
1364     const gchar * key, const gchar * value)
1365 {
1366   if (!klass->meta_data) {
1367     /* FIXME: use a quark for "metadata" */
1368     klass->meta_data = gst_structure_empty_new ("metadata");
1369   }
1370
1371   gst_structure_set ((GstStructure *) klass->meta_data,
1372       key, G_TYPE_STRING, value, NULL);
1373 }
1374
1375 /**
1376  * gst_element_class_set_documentation_uri:
1377  * @klass: class to set details for
1378  * @uri: uri of element documentation
1379  *
1380  * Set uri pointing to user documentation. Applications can use this to show
1381  * help for e.g. effects to users.
1382  *
1383  * Since: 0.10.31
1384  */
1385 void
1386 gst_element_class_set_documentation_uri (GstElementClass * klass,
1387     const gchar * uri)
1388 {
1389   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1390
1391   gst_element_class_add_meta_data (klass, "doc-uri", uri);
1392 }
1393
1394 /**
1395  * gst_element_class_set_icon_name:
1396  * @klass: class to set details for
1397  * @name: name of an icon
1398  *
1399  * Elements that bridge to certain other products can include an icon of that
1400  * used product. Application can show the icon in menus/selectors to help
1401  * identifying specific elements.
1402  *
1403  * Since: 0.10.31
1404  */
1405 void
1406 gst_element_class_set_icon_name (GstElementClass * klass, const gchar * name)
1407 {
1408   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1409
1410   gst_element_class_add_meta_data (klass, "icon-name", name);
1411 }
1412
1413 /* FIXME-0.11: deprecate and remove gst_element_class_set_details*() */
1414 /**
1415  * gst_element_class_set_details:
1416  * @klass: class to set details for
1417  * @details: details to set
1418  *
1419  * Sets the detailed information for a #GstElementClass.
1420  * <note>This function is for use in _base_init functions only.</note>
1421  *
1422  * The @details are copied.
1423  *
1424  * Deprecated: Use gst_element_class_set_details_simple() instead.
1425  */
1426 #ifndef GST_REMOVE_DEPRECATED
1427 #ifdef GST_DISABLE_DEPRECATED
1428 void gst_element_class_set_details (GstElementClass * klass,
1429     const GstElementDetails * details);
1430 #endif
1431 void
1432 gst_element_class_set_details (GstElementClass * klass,
1433     const GstElementDetails * details)
1434 {
1435   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1436   g_return_if_fail (GST_IS_ELEMENT_DETAILS (details));
1437
1438   __gst_element_details_copy (&klass->details, details);
1439 }
1440 #endif
1441
1442 /**
1443  * gst_element_class_set_details_simple:
1444  * @klass: class to set details for
1445  * @longname: The long English name of the element. E.g. "File Sink"
1446  * @classification: String describing the type of element, as an unordered list
1447  * separated with slashes ('/'). See draft-klass.txt of the design docs
1448  * for more details and common types. E.g: "Sink/File"
1449  * @description: Sentence describing the purpose of the element.
1450  * E.g: "Write stream to a file"
1451  * @author: Name and contact details of the author(s). Use \n to separate
1452  * multiple author details. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
1453  *
1454  * Sets the detailed information for a #GstElementClass. Simpler version of
1455  * gst_element_class_set_details() that generates less linker overhead.
1456  * <note>This function is for use in _base_init functions only.</note>
1457  *
1458  * The detail parameter strings are copied into the #GstElementDetails for
1459  * the element class.
1460  *
1461  * Since: 0.10.14
1462  */
1463 void
1464 gst_element_class_set_details_simple (GstElementClass * klass,
1465     const gchar * longname, const gchar * classification,
1466     const gchar * description, const gchar * author)
1467 {
1468   const GstElementDetails details =
1469       GST_ELEMENT_DETAILS ((gchar *) longname, (gchar *) classification,
1470       (gchar *) description, (gchar *) author);
1471
1472   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1473
1474   __gst_element_details_copy (&klass->details, &details);
1475 }
1476
1477 /**
1478  * gst_element_class_get_pad_template_list:
1479  * @element_class: a #GstElementClass to get pad templates of.
1480  *
1481  * Retrieves a list of the pad templates associated with @element_class. The
1482  * list must not be modified by the calling code.
1483  * <note>If you use this function in the #GInstanceInitFunc of an object class
1484  * that has subclasses, make sure to pass the g_class parameter of the
1485  * #GInstanceInitFunc here.</note>
1486  *
1487  * Returns: (transfer none) (element-type Gst.PadTemplate): the #GList of
1488  *     pad templates.
1489  */
1490 GList *
1491 gst_element_class_get_pad_template_list (GstElementClass * element_class)
1492 {
1493   g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1494
1495   return element_class->padtemplates;
1496 }
1497
1498 /**
1499  * gst_element_class_get_pad_template:
1500  * @element_class: a #GstElementClass to get the pad template of.
1501  * @name: the name of the #GstPadTemplate to get.
1502  *
1503  * Retrieves a padtemplate from @element_class with the given name.
1504  * <note>If you use this function in the #GInstanceInitFunc of an object class
1505  * that has subclasses, make sure to pass the g_class parameter of the
1506  * #GInstanceInitFunc here.</note>
1507  *
1508  * Returns: (transfer none): the #GstPadTemplate with the given name, or %NULL
1509  *     if none was found. No unreferencing is necessary.
1510  */
1511 GstPadTemplate *
1512 gst_element_class_get_pad_template (GstElementClass *
1513     element_class, const gchar * name)
1514 {
1515   GList *padlist;
1516
1517   g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1518   g_return_val_if_fail (name != NULL, NULL);
1519
1520   padlist = element_class->padtemplates;
1521
1522   while (padlist) {
1523     GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
1524
1525     if (strcmp (padtempl->name_template, name) == 0)
1526       return padtempl;
1527
1528     padlist = g_list_next (padlist);
1529   }
1530
1531   return NULL;
1532 }
1533
1534 static GstPadTemplate *
1535 gst_element_class_get_request_pad_template (GstElementClass *
1536     element_class, const gchar * name)
1537 {
1538   GstPadTemplate *tmpl;
1539
1540   tmpl = gst_element_class_get_pad_template (element_class, name);
1541   if (tmpl != NULL && tmpl->presence == GST_PAD_REQUEST)
1542     return tmpl;
1543
1544   return NULL;
1545 }
1546
1547 /* get a random pad on element of the given direction.
1548  * The pad is random in a sense that it is the first pad that is (optionaly) linked.
1549  */
1550 static GstPad *
1551 gst_element_get_random_pad (GstElement * element,
1552     gboolean need_linked, GstPadDirection dir)
1553 {
1554   GstPad *result = NULL;
1555   GList *pads;
1556
1557   GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "getting a random pad");
1558
1559   switch (dir) {
1560     case GST_PAD_SRC:
1561       GST_OBJECT_LOCK (element);
1562       pads = element->srcpads;
1563       break;
1564     case GST_PAD_SINK:
1565       GST_OBJECT_LOCK (element);
1566       pads = element->sinkpads;
1567       break;
1568     default:
1569       goto wrong_direction;
1570   }
1571   for (; pads; pads = g_list_next (pads)) {
1572     GstPad *pad = GST_PAD_CAST (pads->data);
1573
1574     GST_OBJECT_LOCK (pad);
1575     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "checking pad %s:%s",
1576         GST_DEBUG_PAD_NAME (pad));
1577
1578     if (need_linked && !GST_PAD_IS_LINKED (pad)) {
1579       /* if we require a linked pad, and it is not linked, continue the
1580        * search */
1581       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is not linked",
1582           GST_DEBUG_PAD_NAME (pad));
1583       GST_OBJECT_UNLOCK (pad);
1584       continue;
1585     } else {
1586       /* found a pad, stop search */
1587       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
1588           GST_DEBUG_PAD_NAME (pad));
1589       GST_OBJECT_UNLOCK (pad);
1590       result = pad;
1591       break;
1592     }
1593   }
1594   if (result)
1595     gst_object_ref (result);
1596
1597   GST_OBJECT_UNLOCK (element);
1598
1599   return result;
1600
1601   /* ERROR handling */
1602 wrong_direction:
1603   {
1604     g_warning ("unknown pad direction %d", dir);
1605     return NULL;
1606   }
1607 }
1608
1609 static gboolean
1610 gst_element_default_send_event (GstElement * element, GstEvent * event)
1611 {
1612   gboolean result = FALSE;
1613   GstPad *pad;
1614
1615   pad = GST_EVENT_IS_DOWNSTREAM (event) ?
1616       gst_element_get_random_pad (element, TRUE, GST_PAD_SRC) :
1617       gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1618
1619   if (pad) {
1620     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1621         "pushing %s event to random %s pad %s:%s",
1622         GST_EVENT_TYPE_NAME (event),
1623         (GST_PAD_DIRECTION (pad) == GST_PAD_SRC ? "src" : "sink"),
1624         GST_DEBUG_PAD_NAME (pad));
1625
1626     result = gst_pad_push_event (pad, event);
1627     gst_object_unref (pad);
1628   } else {
1629     GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "can't send %s event on element %s",
1630         GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1631     gst_event_unref (event);
1632   }
1633   return result;
1634 }
1635
1636 /**
1637  * gst_element_send_event:
1638  * @element: a #GstElement to send the event to.
1639  * @event: (transfer full): the #GstEvent to send to the element.
1640  *
1641  * Sends an event to an element. If the element doesn't implement an
1642  * event handler, the event will be pushed on a random linked sink pad for
1643  * upstream events or a random linked source pad for downstream events.
1644  *
1645  * This function takes owership of the provided event so you should
1646  * gst_event_ref() it if you want to reuse the event after this call.
1647  *
1648  * Returns: %TRUE if the event was handled.
1649  *
1650  * MT safe.
1651  */
1652 gboolean
1653 gst_element_send_event (GstElement * element, GstEvent * event)
1654 {
1655   GstElementClass *oclass;
1656   gboolean result = FALSE;
1657
1658   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1659   g_return_val_if_fail (event != NULL, FALSE);
1660
1661   oclass = GST_ELEMENT_GET_CLASS (element);
1662
1663   GST_STATE_LOCK (element);
1664   if (oclass->send_event) {
1665     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send %s event on element %s",
1666         GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1667     result = oclass->send_event (element, event);
1668   } else {
1669     result = gst_element_default_send_event (element, event);
1670   }
1671   GST_STATE_UNLOCK (element);
1672
1673   return result;
1674 }
1675
1676 /**
1677  * gst_element_seek:
1678  * @element: a #GstElement to send the event to.
1679  * @rate: The new playback rate
1680  * @format: The format of the seek values
1681  * @flags: The optional seek flags.
1682  * @cur_type: The type and flags for the new current position
1683  * @cur: The value of the new current position
1684  * @stop_type: The type and flags for the new stop position
1685  * @stop: The value of the new stop position
1686  *
1687  * Sends a seek event to an element. See gst_event_new_seek() for the details of
1688  * the parameters. The seek event is sent to the element using
1689  * gst_element_send_event().
1690  *
1691  * Returns: %TRUE if the event was handled.
1692  *
1693  * MT safe.
1694  */
1695 gboolean
1696 gst_element_seek (GstElement * element, gdouble rate, GstFormat format,
1697     GstSeekFlags flags, GstSeekType cur_type, gint64 cur,
1698     GstSeekType stop_type, gint64 stop)
1699 {
1700   GstEvent *event;
1701   gboolean result;
1702
1703   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1704
1705   event =
1706       gst_event_new_seek (rate, format, flags, cur_type, cur, stop_type, stop);
1707   result = gst_element_send_event (element, event);
1708
1709   return result;
1710 }
1711
1712 /**
1713  * gst_element_get_query_types:
1714  * @element: a #GstElement to query
1715  *
1716  * Get an array of query types from the element.
1717  * If the element doesn't implement a query types function,
1718  * the query will be forwarded to the peer of a random linked sink pad.
1719  *
1720  * Returns: An array of #GstQueryType elements that should not
1721  * be freed or modified.
1722  *
1723  * MT safe.
1724  */
1725 const GstQueryType *
1726 gst_element_get_query_types (GstElement * element)
1727 {
1728   GstElementClass *oclass;
1729   const GstQueryType *result = NULL;
1730
1731   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1732
1733   oclass = GST_ELEMENT_GET_CLASS (element);
1734
1735   if (oclass->get_query_types) {
1736     result = oclass->get_query_types (element);
1737   } else {
1738     GstPad *pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1739
1740     if (pad) {
1741       GstPad *peer = gst_pad_get_peer (pad);
1742
1743       if (peer) {
1744         result = gst_pad_get_query_types (peer);
1745
1746         gst_object_unref (peer);
1747       }
1748       gst_object_unref (pad);
1749     }
1750   }
1751   return result;
1752 }
1753
1754 static gboolean
1755 gst_element_default_query (GstElement * element, GstQuery * query)
1756 {
1757   gboolean result = FALSE;
1758   GstPad *pad;
1759
1760   pad = gst_element_get_random_pad (element, FALSE, GST_PAD_SRC);
1761   if (pad) {
1762     result = gst_pad_query (pad, query);
1763
1764     gst_object_unref (pad);
1765   } else {
1766     pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1767     if (pad) {
1768       GstPad *peer = gst_pad_get_peer (pad);
1769
1770       if (peer) {
1771         result = gst_pad_query (peer, query);
1772
1773         gst_object_unref (peer);
1774       }
1775       gst_object_unref (pad);
1776     }
1777   }
1778   return result;
1779 }
1780
1781 /**
1782  * gst_element_query:
1783  * @element: a #GstElement to perform the query on.
1784  * @query: (transfer none): the #GstQuery.
1785  *
1786  * Performs a query on the given element.
1787  *
1788  * For elements that don't implement a query handler, this function
1789  * forwards the query to a random srcpad or to the peer of a
1790  * random linked sinkpad of this element.
1791  *
1792  * Please note that some queries might need a running pipeline to work.
1793  *
1794  * Returns: TRUE if the query could be performed.
1795  *
1796  * MT safe.
1797  */
1798 gboolean
1799 gst_element_query (GstElement * element, GstQuery * query)
1800 {
1801   GstElementClass *oclass;
1802   gboolean result = FALSE;
1803
1804   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1805   g_return_val_if_fail (query != NULL, FALSE);
1806
1807   oclass = GST_ELEMENT_GET_CLASS (element);
1808
1809   if (oclass->query) {
1810     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send query on element %s",
1811         GST_ELEMENT_NAME (element));
1812     result = oclass->query (element, query);
1813   } else {
1814     result = gst_element_default_query (element, query);
1815   }
1816   return result;
1817 }
1818
1819 /**
1820  * gst_element_post_message:
1821  * @element: a #GstElement posting the message
1822  * @message: (transfer full): a #GstMessage to post
1823  *
1824  * Post a message on the element's #GstBus. This function takes ownership of the
1825  * message; if you want to access the message after this call, you should add an
1826  * additional reference before calling.
1827  *
1828  * Returns: %TRUE if the message was successfully posted. The function returns
1829  * %FALSE if the element did not have a bus.
1830  *
1831  * MT safe.
1832  */
1833 gboolean
1834 gst_element_post_message (GstElement * element, GstMessage * message)
1835 {
1836   GstBus *bus;
1837   gboolean result = FALSE;
1838
1839   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1840   g_return_val_if_fail (message != NULL, FALSE);
1841
1842   GST_OBJECT_LOCK (element);
1843   bus = element->bus;
1844
1845   if (G_UNLIKELY (bus == NULL))
1846     goto no_bus;
1847
1848   gst_object_ref (bus);
1849   GST_OBJECT_UNLOCK (element);
1850
1851   /* we release the element lock when posting the message so that any
1852    * (synchronous) message handlers can operate on the element */
1853   result = gst_bus_post (bus, message);
1854   gst_object_unref (bus);
1855
1856   return result;
1857
1858   /* ERRORS */
1859 no_bus:
1860   {
1861     GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element,
1862         "not posting message %p: no bus", message);
1863     GST_OBJECT_UNLOCK (element);
1864     gst_message_unref (message);
1865     return FALSE;
1866   }
1867 }
1868
1869 /**
1870  * _gst_element_error_printf:
1871  * @format: the printf-like format to use, or %NULL
1872  *
1873  * This function is only used internally by the gst_element_error() macro.
1874  *
1875  * Returns: (transfer full): a newly allocated string, or %NULL if the format
1876  *     was %NULL or ""
1877  *
1878  * MT safe.
1879  */
1880 gchar *
1881 _gst_element_error_printf (const gchar * format, ...)
1882 {
1883   va_list args;
1884   gchar *buffer;
1885
1886   if (format == NULL)
1887     return NULL;
1888   if (format[0] == 0)
1889     return NULL;
1890
1891   va_start (args, format);
1892   buffer = g_strdup_vprintf (format, args);
1893   va_end (args);
1894   return buffer;
1895 }
1896
1897 /**
1898  * gst_element_message_full:
1899  * @element:  a #GstElement to send message from
1900  * @type:     the #GstMessageType
1901  * @domain:   the GStreamer GError domain this message belongs to
1902  * @code:     the GError code belonging to the domain
1903  * @text:     (allow-none) (transfer full): an allocated text string to be used
1904  *            as a replacement for the default message connected to code,
1905  *            or %NULL
1906  * @debug:    (allow-none) (transfer full): an allocated debug message to be
1907  *            used as a replacement for the default debugging information,
1908  *            or %NULL
1909  * @file:     the source code file where the error was generated
1910  * @function: the source code function where the error was generated
1911  * @line:     the source code line where the error was generated
1912  *
1913  * Post an error, warning or info message on the bus from inside an element.
1914  *
1915  * @type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or
1916  * #GST_MESSAGE_INFO.
1917  *
1918  * MT safe.
1919  */
1920 void gst_element_message_full
1921     (GstElement * element, GstMessageType type,
1922     GQuark domain, gint code, gchar * text,
1923     gchar * debug, const gchar * file, const gchar * function, gint line)
1924 {
1925   GError *gerror = NULL;
1926   gchar *name;
1927   gchar *sent_text;
1928   gchar *sent_debug;
1929   gboolean has_debug = TRUE;
1930   GstMessage *message = NULL;
1931
1932   /* checks */
1933   GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element, "start");
1934   g_return_if_fail (GST_IS_ELEMENT (element));
1935   g_return_if_fail ((type == GST_MESSAGE_ERROR) ||
1936       (type == GST_MESSAGE_WARNING) || (type == GST_MESSAGE_INFO));
1937
1938   /* check if we send the given text or the default error text */
1939   if ((text == NULL) || (text[0] == 0)) {
1940     /* text could have come from g_strdup_printf (""); */
1941     g_free (text);
1942     sent_text = gst_error_get_message (domain, code);
1943   } else
1944     sent_text = text;
1945
1946   /* construct a sent_debug with extra information from source */
1947   if ((debug == NULL) || (debug[0] == 0)) {
1948     /* debug could have come from g_strdup_printf (""); */
1949     has_debug = FALSE;
1950   }
1951
1952   name = gst_object_get_path_string (GST_OBJECT_CAST (element));
1953   if (has_debug)
1954     sent_debug = g_strdup_printf ("%s(%d): %s (): %s:\n%s",
1955         file, line, function, name, debug);
1956   else
1957     sent_debug = g_strdup_printf ("%s(%d): %s (): %s",
1958         file, line, function, name);
1959   g_free (name);
1960   g_free (debug);
1961
1962   /* create gerror and post message */
1963   GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posting message: %s",
1964       sent_text);
1965   gerror = g_error_new_literal (domain, code, sent_text);
1966
1967   switch (type) {
1968     case GST_MESSAGE_ERROR:
1969       message =
1970           gst_message_new_error (GST_OBJECT_CAST (element), gerror, sent_debug);
1971       break;
1972     case GST_MESSAGE_WARNING:
1973       message = gst_message_new_warning (GST_OBJECT_CAST (element), gerror,
1974           sent_debug);
1975       break;
1976     case GST_MESSAGE_INFO:
1977       message = gst_message_new_info (GST_OBJECT_CAST (element), gerror,
1978           sent_debug);
1979       break;
1980     default:
1981       g_assert_not_reached ();
1982       break;
1983   }
1984   gst_element_post_message (element, message);
1985
1986   GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posted %s message: %s",
1987       (type == GST_MESSAGE_ERROR ? "error" : "warning"), sent_text);
1988
1989   /* cleanup */
1990   g_error_free (gerror);
1991   g_free (sent_debug);
1992   g_free (sent_text);
1993 }
1994
1995 /**
1996  * gst_element_is_locked_state:
1997  * @element: a #GstElement.
1998  *
1999  * Checks if the state of an element is locked.
2000  * If the state of an element is locked, state changes of the parent don't
2001  * affect the element.
2002  * This way you can leave currently unused elements inside bins. Just lock their
2003  * state before changing the state from #GST_STATE_NULL.
2004  *
2005  * MT safe.
2006  *
2007  * Returns: TRUE, if the element's state is locked.
2008  */
2009 gboolean
2010 gst_element_is_locked_state (GstElement * element)
2011 {
2012   gboolean result;
2013
2014   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2015
2016   GST_OBJECT_LOCK (element);
2017   result = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
2018   GST_OBJECT_UNLOCK (element);
2019
2020   return result;
2021 }
2022
2023 /**
2024  * gst_element_set_locked_state:
2025  * @element: a #GstElement
2026  * @locked_state: TRUE to lock the element's state
2027  *
2028  * Locks the state of an element, so state changes of the parent don't affect
2029  * this element anymore.
2030  *
2031  * MT safe.
2032  *
2033  * Returns: TRUE if the state was changed, FALSE if bad parameters were given
2034  * or the elements state-locking needed no change.
2035  */
2036 gboolean
2037 gst_element_set_locked_state (GstElement * element, gboolean locked_state)
2038 {
2039   gboolean old;
2040
2041   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2042
2043   GST_OBJECT_LOCK (element);
2044   old = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
2045
2046   if (G_UNLIKELY (old == locked_state))
2047     goto was_ok;
2048
2049   if (locked_state) {
2050     GST_CAT_DEBUG (GST_CAT_STATES, "locking state of element %s",
2051         GST_ELEMENT_NAME (element));
2052     GST_OBJECT_FLAG_SET (element, GST_ELEMENT_LOCKED_STATE);
2053   } else {
2054     GST_CAT_DEBUG (GST_CAT_STATES, "unlocking state of element %s",
2055         GST_ELEMENT_NAME (element));
2056     GST_OBJECT_FLAG_UNSET (element, GST_ELEMENT_LOCKED_STATE);
2057   }
2058   GST_OBJECT_UNLOCK (element);
2059
2060   return TRUE;
2061
2062 was_ok:
2063   {
2064     GST_CAT_DEBUG (GST_CAT_STATES,
2065         "elements %s was already in locked state %d",
2066         GST_ELEMENT_NAME (element), old);
2067     GST_OBJECT_UNLOCK (element);
2068
2069     return FALSE;
2070   }
2071 }
2072
2073 /**
2074  * gst_element_sync_state_with_parent:
2075  * @element: a #GstElement.
2076  *
2077  * Tries to change the state of the element to the same as its parent.
2078  * If this function returns FALSE, the state of element is undefined.
2079  *
2080  * Returns: TRUE, if the element's state could be synced to the parent's state.
2081  *
2082  * MT safe.
2083  */
2084 gboolean
2085 gst_element_sync_state_with_parent (GstElement * element)
2086 {
2087   GstElement *parent;
2088   GstState target;
2089   GstStateChangeReturn ret;
2090
2091   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2092
2093   if ((parent = GST_ELEMENT_CAST (gst_element_get_parent (element)))) {
2094     GstState parent_current, parent_pending;
2095
2096     GST_OBJECT_LOCK (parent);
2097     parent_current = GST_STATE (parent);
2098     parent_pending = GST_STATE_PENDING (parent);
2099     GST_OBJECT_UNLOCK (parent);
2100
2101     /* set to pending if there is one, else we set it to the current state of
2102      * the parent */
2103     if (parent_pending != GST_STATE_VOID_PENDING)
2104       target = parent_pending;
2105     else
2106       target = parent_current;
2107
2108     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2109         "syncing state (%s) to parent %s %s (%s, %s)",
2110         gst_element_state_get_name (GST_STATE (element)),
2111         GST_ELEMENT_NAME (parent), gst_element_state_get_name (target),
2112         gst_element_state_get_name (parent_current),
2113         gst_element_state_get_name (parent_pending));
2114
2115     ret = gst_element_set_state (element, target);
2116     if (ret == GST_STATE_CHANGE_FAILURE)
2117       goto failed;
2118
2119     gst_object_unref (parent);
2120
2121     return TRUE;
2122   } else {
2123     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "element has no parent");
2124   }
2125   return FALSE;
2126
2127   /* ERROR */
2128 failed:
2129   {
2130     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2131         "syncing state failed (%s)",
2132         gst_element_state_change_return_get_name (ret));
2133     gst_object_unref (parent);
2134     return FALSE;
2135   }
2136 }
2137
2138 /* MT safe */
2139 static GstStateChangeReturn
2140 gst_element_get_state_func (GstElement * element,
2141     GstState * state, GstState * pending, GstClockTime timeout)
2142 {
2143   GstStateChangeReturn ret = GST_STATE_CHANGE_FAILURE;
2144   GstState old_pending;
2145
2146   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "getting state, timeout %"
2147       GST_TIME_FORMAT, GST_TIME_ARGS (timeout));
2148
2149   GST_OBJECT_LOCK (element);
2150   ret = GST_STATE_RETURN (element);
2151   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "RETURN is %s",
2152       gst_element_state_change_return_get_name (ret));
2153
2154   /* we got an error, report immediately */
2155   if (ret == GST_STATE_CHANGE_FAILURE)
2156     goto done;
2157
2158   /* we got no_preroll, report immediately */
2159   if (ret == GST_STATE_CHANGE_NO_PREROLL)
2160     goto done;
2161
2162   /* no need to wait async if we are not async */
2163   if (ret != GST_STATE_CHANGE_ASYNC)
2164     goto done;
2165
2166   old_pending = GST_STATE_PENDING (element);
2167   if (old_pending != GST_STATE_VOID_PENDING) {
2168     GTimeVal *timeval, abstimeout;
2169     guint32 cookie;
2170
2171     if (timeout != GST_CLOCK_TIME_NONE) {
2172       glong add = timeout / 1000;
2173
2174       if (add == 0)
2175         goto done;
2176
2177       /* make timeout absolute */
2178       g_get_current_time (&abstimeout);
2179       g_time_val_add (&abstimeout, add);
2180       timeval = &abstimeout;
2181     } else {
2182       timeval = NULL;
2183     }
2184     /* get cookie to detect state changes during waiting */
2185     cookie = element->state_cookie;
2186
2187     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2188         "waiting for element to commit state");
2189
2190     /* we have a pending state change, wait for it to complete */
2191     if (!GST_STATE_TIMED_WAIT (element, timeval)) {
2192       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "timed out");
2193       /* timeout triggered */
2194       ret = GST_STATE_CHANGE_ASYNC;
2195     } else {
2196       if (cookie != element->state_cookie)
2197         goto interrupted;
2198
2199       /* could be success or failure */
2200       if (old_pending == GST_STATE (element)) {
2201         GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got success");
2202         ret = GST_STATE_CHANGE_SUCCESS;
2203       } else {
2204         GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got failure");
2205         ret = GST_STATE_CHANGE_FAILURE;
2206       }
2207     }
2208     /* if nothing is pending anymore we can return SUCCESS */
2209     if (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING) {
2210       GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "nothing pending");
2211       ret = GST_STATE_CHANGE_SUCCESS;
2212     }
2213   }
2214
2215 done:
2216   if (state)
2217     *state = GST_STATE (element);
2218   if (pending)
2219     *pending = GST_STATE_PENDING (element);
2220
2221   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2222       "state current: %s, pending: %s, result: %s",
2223       gst_element_state_get_name (GST_STATE (element)),
2224       gst_element_state_get_name (GST_STATE_PENDING (element)),
2225       gst_element_state_change_return_get_name (ret));
2226   GST_OBJECT_UNLOCK (element);
2227
2228   return ret;
2229
2230 interrupted:
2231   {
2232     if (state)
2233       *state = GST_STATE_VOID_PENDING;
2234     if (pending)
2235       *pending = GST_STATE_VOID_PENDING;
2236
2237     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "interruped");
2238
2239     GST_OBJECT_UNLOCK (element);
2240
2241     return GST_STATE_CHANGE_FAILURE;
2242   }
2243 }
2244
2245 /**
2246  * gst_element_get_state:
2247  * @element: a #GstElement to get the state of.
2248  * @state: (out) (allow-none): a pointer to #GstState to hold the state.
2249  *     Can be %NULL.
2250  * @pending: (out) (allow-none): a pointer to #GstState to hold the pending
2251  *     state. Can be %NULL.
2252  * @timeout: a #GstClockTime to specify the timeout for an async
2253  *           state change or %GST_CLOCK_TIME_NONE for infinite timeout.
2254  *
2255  * Gets the state of the element.
2256  *
2257  * For elements that performed an ASYNC state change, as reported by
2258  * gst_element_set_state(), this function will block up to the
2259  * specified timeout value for the state change to complete.
2260  * If the element completes the state change or goes into
2261  * an error, this function returns immediately with a return value of
2262  * %GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively.
2263  *
2264  * For elements that did not return %GST_STATE_CHANGE_ASYNC, this function
2265  * returns the current and pending state immediately.
2266  *
2267  * This function returns %GST_STATE_CHANGE_NO_PREROLL if the element
2268  * successfully changed its state but is not able to provide data yet.
2269  * This mostly happens for live sources that only produce data in
2270  * %GST_STATE_PLAYING. While the state change return is equivalent to
2271  * %GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that
2272  * some sink elements might not be able to complete their state change because
2273  * an element is not producing data to complete the preroll. When setting the
2274  * element to playing, the preroll will complete and playback will start.
2275  *
2276  * Returns: %GST_STATE_CHANGE_SUCCESS if the element has no more pending state
2277  *          and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the
2278  *          element is still performing a state change or
2279  *          %GST_STATE_CHANGE_FAILURE if the last state change failed.
2280  *
2281  * MT safe.
2282  */
2283 GstStateChangeReturn
2284 gst_element_get_state (GstElement * element,
2285     GstState * state, GstState * pending, GstClockTime timeout)
2286 {
2287   GstElementClass *oclass;
2288   GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2289
2290   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2291
2292   oclass = GST_ELEMENT_GET_CLASS (element);
2293
2294   if (oclass->get_state)
2295     result = (oclass->get_state) (element, state, pending, timeout);
2296
2297   return result;
2298 }
2299
2300 /**
2301  * gst_element_abort_state:
2302  * @element: a #GstElement to abort the state of.
2303  *
2304  * Abort the state change of the element. This function is used
2305  * by elements that do asynchronous state changes and find out
2306  * something is wrong.
2307  *
2308  * This function should be called with the STATE_LOCK held.
2309  *
2310  * MT safe.
2311  */
2312 void
2313 gst_element_abort_state (GstElement * element)
2314 {
2315   GstState pending;
2316
2317 #ifndef GST_DISABLE_GST_DEBUG
2318   GstState old_state;
2319 #endif
2320
2321   g_return_if_fail (GST_IS_ELEMENT (element));
2322
2323   GST_OBJECT_LOCK (element);
2324   pending = GST_STATE_PENDING (element);
2325
2326   if (pending == GST_STATE_VOID_PENDING ||
2327       GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2328     goto nothing_aborted;
2329
2330 #ifndef GST_DISABLE_GST_DEBUG
2331   old_state = GST_STATE (element);
2332
2333   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2334       "aborting state from %s to %s", gst_element_state_get_name (old_state),
2335       gst_element_state_get_name (pending));
2336 #endif
2337
2338   /* flag error */
2339   GST_STATE_RETURN (element) = GST_STATE_CHANGE_FAILURE;
2340
2341   GST_STATE_BROADCAST (element);
2342   GST_OBJECT_UNLOCK (element);
2343
2344   return;
2345
2346 nothing_aborted:
2347   {
2348     GST_OBJECT_UNLOCK (element);
2349     return;
2350   }
2351 }
2352
2353 /* Not static because GstBin has manual state handling too */
2354 void
2355 _priv_gst_element_state_changed (GstElement * element, GstState oldstate,
2356     GstState newstate, GstState pending)
2357 {
2358   GstElementClass *klass = GST_ELEMENT_GET_CLASS (element);
2359   GstMessage *message;
2360
2361   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2362       "notifying about state-changed %s to %s (%s pending)",
2363       gst_element_state_get_name (oldstate),
2364       gst_element_state_get_name (newstate),
2365       gst_element_state_get_name (pending));
2366
2367   if (klass->state_changed)
2368     klass->state_changed (element, oldstate, newstate, pending);
2369
2370   message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2371       oldstate, newstate, pending);
2372   gst_element_post_message (element, message);
2373 }
2374
2375 /**
2376  * gst_element_continue_state:
2377  * @element: a #GstElement to continue the state change of.
2378  * @ret: The previous state return value
2379  *
2380  * Commit the state change of the element and proceed to the next
2381  * pending state if any. This function is used
2382  * by elements that do asynchronous state changes.
2383  * The core will normally call this method automatically when an
2384  * element returned %GST_STATE_CHANGE_SUCCESS from the state change function.
2385  *
2386  * If after calling this method the element still has not reached
2387  * the pending state, the next state change is performed.
2388  *
2389  * This method is used internally and should normally not be called by plugins
2390  * or applications.
2391  *
2392  * Returns: The result of the commit state change.
2393  *
2394  * MT safe.
2395  */
2396 GstStateChangeReturn
2397 gst_element_continue_state (GstElement * element, GstStateChangeReturn ret)
2398 {
2399   GstStateChangeReturn old_ret;
2400   GstState old_state, old_next;
2401   GstState current, next, pending;
2402   GstStateChange transition;
2403
2404   GST_OBJECT_LOCK (element);
2405   old_ret = GST_STATE_RETURN (element);
2406   GST_STATE_RETURN (element) = ret;
2407   pending = GST_STATE_PENDING (element);
2408
2409   /* check if there is something to commit */
2410   if (pending == GST_STATE_VOID_PENDING)
2411     goto nothing_pending;
2412
2413   old_state = GST_STATE (element);
2414   /* this is the state we should go to next */
2415   old_next = GST_STATE_NEXT (element);
2416   /* update current state */
2417   current = GST_STATE (element) = old_next;
2418
2419   /* see if we reached the final state */
2420   if (pending == current)
2421     goto complete;
2422
2423   next = GST_STATE_GET_NEXT (current, pending);
2424   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2425
2426   GST_STATE_NEXT (element) = next;
2427   /* mark busy */
2428   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2429   GST_OBJECT_UNLOCK (element);
2430
2431   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2432       "committing state from %s to %s, pending %s, next %s",
2433       gst_element_state_get_name (old_state),
2434       gst_element_state_get_name (old_next),
2435       gst_element_state_get_name (pending), gst_element_state_get_name (next));
2436
2437   _priv_gst_element_state_changed (element, old_state, old_next, pending);
2438
2439   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2440       "continue state change %s to %s, final %s",
2441       gst_element_state_get_name (current),
2442       gst_element_state_get_name (next), gst_element_state_get_name (pending));
2443
2444   ret = gst_element_change_state (element, transition);
2445
2446   return ret;
2447
2448 nothing_pending:
2449   {
2450     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "nothing pending");
2451     GST_OBJECT_UNLOCK (element);
2452     return ret;
2453   }
2454 complete:
2455   {
2456     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2457     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2458
2459     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2460         "completed state change to %s", gst_element_state_get_name (pending));
2461     GST_OBJECT_UNLOCK (element);
2462
2463     /* don't post silly messages with the same state. This can happen
2464      * when an element state is changed to what it already was. For bins
2465      * this can be the result of a lost state, which we check with the
2466      * previous return value.
2467      * We do signal the cond though as a _get_state() might be blocking
2468      * on it. */
2469     if (old_state != old_next || old_ret == GST_STATE_CHANGE_ASYNC)
2470       _priv_gst_element_state_changed (element, old_state, old_next,
2471           GST_STATE_VOID_PENDING);
2472
2473     GST_STATE_BROADCAST (element);
2474
2475     return ret;
2476   }
2477 }
2478
2479 /**
2480  * gst_element_lost_state_full:
2481  * @element: a #GstElement the state is lost of
2482  * @new_base_time: if a new base time should be distributed
2483  *
2484  * Brings the element to the lost state. The current state of the
2485  * element is copied to the pending state so that any call to
2486  * gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC.
2487  *
2488  * An ASYNC_START message is posted with indication to distribute a new
2489  * base_time to the element when @new_base_time is %TRUE.
2490  * If the element was PLAYING, it will go to PAUSED. The element
2491  * will be restored to its PLAYING state by the parent pipeline when it
2492  * prerolls again.
2493  *
2494  * This is mostly used for elements that lost their preroll buffer
2495  * in the %GST_STATE_PAUSED or %GST_STATE_PLAYING state after a flush,
2496  * they will go to their pending state again when a new preroll buffer is
2497  * queued. This function can only be called when the element is currently
2498  * not in error or an async state change.
2499  *
2500  * This function is used internally and should normally not be called from
2501  * plugins or applications.
2502  *
2503  * MT safe.
2504  *
2505  * Since: 0.10.24
2506  */
2507 void
2508 gst_element_lost_state_full (GstElement * element, gboolean new_base_time)
2509 {
2510   GstState old_state, new_state;
2511   GstMessage *message;
2512
2513   g_return_if_fail (GST_IS_ELEMENT (element));
2514
2515   GST_OBJECT_LOCK (element);
2516   if (GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2517     goto nothing_lost;
2518
2519   if (GST_STATE_PENDING (element) != GST_STATE_VOID_PENDING)
2520     goto only_async_start;
2521
2522   old_state = GST_STATE (element);
2523
2524   /* when we were PLAYING, the new state is PAUSED. We will also not
2525    * automatically go to PLAYING but let the parent bin(s) set us to PLAYING
2526    * when we preroll. */
2527   if (old_state > GST_STATE_PAUSED)
2528     new_state = GST_STATE_PAUSED;
2529   else
2530     new_state = old_state;
2531
2532   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2533       "lost state of %s to %s", gst_element_state_get_name (old_state),
2534       gst_element_state_get_name (new_state));
2535
2536   GST_STATE (element) = new_state;
2537   GST_STATE_NEXT (element) = new_state;
2538   GST_STATE_PENDING (element) = new_state;
2539   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2540   if (new_base_time)
2541     GST_ELEMENT_START_TIME (element) = 0;
2542   GST_OBJECT_UNLOCK (element);
2543
2544   _priv_gst_element_state_changed (element, new_state, new_state, new_state);
2545
2546   message =
2547       gst_message_new_async_start (GST_OBJECT_CAST (element), new_base_time);
2548   gst_element_post_message (element, message);
2549
2550   return;
2551
2552 nothing_lost:
2553   {
2554     GST_OBJECT_UNLOCK (element);
2555     return;
2556   }
2557 only_async_start:
2558   {
2559     GST_OBJECT_UNLOCK (element);
2560
2561     message = gst_message_new_async_start (GST_OBJECT_CAST (element), TRUE);
2562     gst_element_post_message (element, message);
2563     return;
2564   }
2565 }
2566
2567 /**
2568  * gst_element_lost_state:
2569  * @element: a #GstElement the state is lost of
2570  *
2571  * Brings the element to the lost state. This function calls
2572  * gst_element_lost_state_full() with the new_base_time set to %TRUE.
2573  *
2574  * This function is used internally and should normally not be called from
2575  * plugins or applications.
2576  *
2577  * MT safe.
2578  */
2579 void
2580 gst_element_lost_state (GstElement * element)
2581 {
2582   gst_element_lost_state_full (element, TRUE);
2583 }
2584
2585 /**
2586  * gst_element_set_state:
2587  * @element: a #GstElement to change state of.
2588  * @state: the element's new #GstState.
2589  *
2590  * Sets the state of the element. This function will try to set the
2591  * requested state by going through all the intermediary states and calling
2592  * the class's state change function for each.
2593  *
2594  * This function can return #GST_STATE_CHANGE_ASYNC, in which case the
2595  * element will perform the remainder of the state change asynchronously in
2596  * another thread.
2597  * An application can use gst_element_get_state() to wait for the completion
2598  * of the state change or it can wait for a state change message on the bus.
2599  *
2600  * State changes to %GST_STATE_READY or %GST_STATE_NULL never return
2601  * #GST_STATE_CHANGE_ASYNC.
2602  *
2603  * Returns: Result of the state change using #GstStateChangeReturn.
2604  *
2605  * MT safe.
2606  */
2607 GstStateChangeReturn
2608 gst_element_set_state (GstElement * element, GstState state)
2609 {
2610   GstElementClass *oclass;
2611   GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2612
2613   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2614
2615   oclass = GST_ELEMENT_GET_CLASS (element);
2616
2617   if (oclass->set_state)
2618     result = (oclass->set_state) (element, state);
2619
2620   return result;
2621 }
2622
2623 /*
2624  * default set state function, calculates the next state based
2625  * on current state and calls the change_state function
2626  */
2627 static GstStateChangeReturn
2628 gst_element_set_state_func (GstElement * element, GstState state)
2629 {
2630   GstState current, next, old_pending;
2631   GstStateChangeReturn ret;
2632   GstStateChange transition;
2633   GstStateChangeReturn old_ret;
2634
2635   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2636
2637   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "set_state to %s",
2638       gst_element_state_get_name (state));
2639
2640   /* state lock is taken to protect the set_state() and get_state()
2641    * procedures, it does not lock any variables. */
2642   GST_STATE_LOCK (element);
2643
2644   /* now calculate how to get to the new state */
2645   GST_OBJECT_LOCK (element);
2646   old_ret = GST_STATE_RETURN (element);
2647   /* previous state change returned an error, remove all pending
2648    * and next states */
2649   if (old_ret == GST_STATE_CHANGE_FAILURE) {
2650     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2651     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2652     GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
2653   }
2654
2655   current = GST_STATE (element);
2656   next = GST_STATE_NEXT (element);
2657   old_pending = GST_STATE_PENDING (element);
2658
2659   /* this is the (new) state we should go to. TARGET is the last state we set on
2660    * the element. */
2661   if (state != GST_STATE_TARGET (element)) {
2662     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2663         "setting target state to %s", gst_element_state_get_name (state));
2664     GST_STATE_TARGET (element) = state;
2665     /* increment state cookie so that we can track each state change. We only do
2666      * this if this is actually a new state change. */
2667     element->state_cookie++;
2668   }
2669   GST_STATE_PENDING (element) = state;
2670
2671   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2672       "current %s, old_pending %s, next %s, old return %s",
2673       gst_element_state_get_name (current),
2674       gst_element_state_get_name (old_pending),
2675       gst_element_state_get_name (next),
2676       gst_element_state_change_return_get_name (old_ret));
2677
2678   /* if the element was busy doing a state change, we just update the
2679    * target state, it'll get to it async then. */
2680   if (old_pending != GST_STATE_VOID_PENDING) {
2681     /* upwards state change will happen ASYNC */
2682     if (old_pending <= state)
2683       goto was_busy;
2684     /* element is going to this state already */
2685     else if (next == state)
2686       goto was_busy;
2687     /* element was performing an ASYNC upward state change and
2688      * we request to go downward again. Start from the next pending
2689      * state then. */
2690     else if (next > state
2691         && GST_STATE_RETURN (element) == GST_STATE_CHANGE_ASYNC) {
2692       current = next;
2693     }
2694   }
2695   next = GST_STATE_GET_NEXT (current, state);
2696   /* now we store the next state */
2697   GST_STATE_NEXT (element) = next;
2698   /* mark busy, we need to check that there is actually a state change
2699    * to be done else we could accidentally override SUCCESS/NO_PREROLL and
2700    * the default element change_state function has no way to know what the
2701    * old value was... could consider this a FIXME...*/
2702   if (current != next)
2703     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2704
2705   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2706
2707   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2708       "%s: setting state from %s to %s",
2709       (next != state ? "intermediate" : "final"),
2710       gst_element_state_get_name (current), gst_element_state_get_name (next));
2711
2712   /* now signal any waiters, they will error since the cookie was incremented */
2713   GST_STATE_BROADCAST (element);
2714
2715   GST_OBJECT_UNLOCK (element);
2716
2717   ret = gst_element_change_state (element, transition);
2718
2719   GST_STATE_UNLOCK (element);
2720
2721   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "returned %s",
2722       gst_element_state_change_return_get_name (ret));
2723
2724   return ret;
2725
2726 was_busy:
2727   {
2728     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2729     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2730         "element was busy with async state change");
2731     GST_OBJECT_UNLOCK (element);
2732
2733     GST_STATE_UNLOCK (element);
2734
2735     return GST_STATE_CHANGE_ASYNC;
2736   }
2737 }
2738
2739 /**
2740  * gst_element_change_state:
2741  * @element: a #GstElement
2742  * @transition: the requested transition
2743  *
2744  * Perform @transition on @element.
2745  *
2746  * This function must be called with STATE_LOCK held and is mainly used
2747  * internally.
2748  *
2749  * Returns: the #GstStateChangeReturn of the state transition.
2750  */
2751 GstStateChangeReturn
2752 gst_element_change_state (GstElement * element, GstStateChange transition)
2753 {
2754   GstElementClass *oclass;
2755   GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
2756
2757   oclass = GST_ELEMENT_GET_CLASS (element);
2758
2759   /* call the state change function so it can set the state */
2760   if (oclass->change_state)
2761     ret = (oclass->change_state) (element, transition);
2762   else
2763     ret = GST_STATE_CHANGE_FAILURE;
2764
2765   switch (ret) {
2766     case GST_STATE_CHANGE_FAILURE:
2767       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2768           "have FAILURE change_state return");
2769       /* state change failure */
2770       gst_element_abort_state (element);
2771       break;
2772     case GST_STATE_CHANGE_ASYNC:
2773     {
2774       GstState target;
2775
2776       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2777           "element will change state ASYNC");
2778
2779       target = GST_STATE_TARGET (element);
2780
2781       if (target > GST_STATE_READY)
2782         goto async;
2783
2784       /* else we just continue the state change downwards */
2785       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2786           "forcing commit state %s <= %s",
2787           gst_element_state_get_name (target),
2788           gst_element_state_get_name (GST_STATE_READY));
2789
2790       ret = gst_element_continue_state (element, GST_STATE_CHANGE_SUCCESS);
2791       break;
2792     }
2793     case GST_STATE_CHANGE_SUCCESS:
2794       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2795           "element changed state SUCCESS");
2796       /* we can commit the state now which will proceeed to
2797        * the next state */
2798       ret = gst_element_continue_state (element, ret);
2799       break;
2800     case GST_STATE_CHANGE_NO_PREROLL:
2801       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2802           "element changed state NO_PREROLL");
2803       /* we can commit the state now which will proceeed to
2804        * the next state */
2805       ret = gst_element_continue_state (element, ret);
2806       break;
2807     default:
2808       goto invalid_return;
2809   }
2810
2811   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit state change %d", ret);
2812
2813   return ret;
2814
2815 async:
2816   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit async state change %d",
2817       ret);
2818
2819   return ret;
2820
2821   /* ERROR */
2822 invalid_return:
2823   {
2824     GST_OBJECT_LOCK (element);
2825     /* somebody added a GST_STATE_ and forgot to do stuff here ! */
2826     g_critical ("%s: unknown return value %d from a state change function",
2827         GST_ELEMENT_NAME (element), ret);
2828
2829     /* we are in error now */
2830     ret = GST_STATE_CHANGE_FAILURE;
2831     GST_STATE_RETURN (element) = ret;
2832     GST_OBJECT_UNLOCK (element);
2833
2834     return ret;
2835   }
2836 }
2837
2838 /* gst_iterator_fold functions for pads_activate
2839  * Stop the iterator if activating one pad failed. */
2840 static gboolean
2841 activate_pads (GstPad * pad, GValue * ret, gboolean * active)
2842 {
2843   gboolean cont = TRUE;
2844
2845   if (!(cont = gst_pad_set_active (pad, *active)))
2846     g_value_set_boolean (ret, FALSE);
2847
2848   /* unref the object that was reffed for us by _fold */
2849   gst_object_unref (pad);
2850   return cont;
2851 }
2852
2853 /* set the caps on the pad to NULL */
2854 static gboolean
2855 clear_caps (GstPad * pad, GValue * ret, gboolean * active)
2856 {
2857   gst_pad_set_caps (pad, NULL);
2858   gst_object_unref (pad);
2859   return TRUE;
2860 }
2861
2862 /* returns false on error or early cutout of the fold, true if all
2863  * pads in @iter were (de)activated successfully. */
2864 static gboolean
2865 iterator_activate_fold_with_resync (GstIterator * iter,
2866     GstIteratorFoldFunction func, gpointer user_data)
2867 {
2868   GstIteratorResult ires;
2869   GValue ret = { 0 };
2870
2871   /* no need to unset this later, it's just a boolean */
2872   g_value_init (&ret, G_TYPE_BOOLEAN);
2873   g_value_set_boolean (&ret, TRUE);
2874
2875   while (1) {
2876     ires = gst_iterator_fold (iter, func, &ret, user_data);
2877     switch (ires) {
2878       case GST_ITERATOR_RESYNC:
2879         /* need to reset the result again */
2880         g_value_set_boolean (&ret, TRUE);
2881         gst_iterator_resync (iter);
2882         break;
2883       case GST_ITERATOR_DONE:
2884         /* all pads iterated, return collected value */
2885         goto done;
2886       default:
2887         /* iterator returned _ERROR or premature end with _OK,
2888          * mark an error and exit */
2889         g_value_set_boolean (&ret, FALSE);
2890         goto done;
2891     }
2892   }
2893 done:
2894   /* return collected value */
2895   return g_value_get_boolean (&ret);
2896 }
2897
2898 /* is called with STATE_LOCK
2899  *
2900  * Pads are activated from source pads to sinkpads.
2901  */
2902 static gboolean
2903 gst_element_pads_activate (GstElement * element, gboolean active)
2904 {
2905   GstIterator *iter;
2906   gboolean res;
2907
2908   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2909       "pads_activate with active %d", active);
2910
2911   iter = gst_element_iterate_src_pads (element);
2912   res =
2913       iterator_activate_fold_with_resync (iter,
2914       (GstIteratorFoldFunction) activate_pads, &active);
2915   gst_iterator_free (iter);
2916   if (G_UNLIKELY (!res))
2917     goto src_failed;
2918
2919   iter = gst_element_iterate_sink_pads (element);
2920   res =
2921       iterator_activate_fold_with_resync (iter,
2922       (GstIteratorFoldFunction) activate_pads, &active);
2923   gst_iterator_free (iter);
2924   if (G_UNLIKELY (!res))
2925     goto sink_failed;
2926
2927   if (!active) {
2928     /* clear the caps on all pads, this should never fail */
2929     iter = gst_element_iterate_pads (element);
2930     res =
2931         iterator_activate_fold_with_resync (iter,
2932         (GstIteratorFoldFunction) clear_caps, &active);
2933     gst_iterator_free (iter);
2934     if (G_UNLIKELY (!res))
2935       goto caps_failed;
2936   }
2937
2938   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2939       "pads_activate successful");
2940
2941   return TRUE;
2942
2943   /* ERRORS */
2944 src_failed:
2945   {
2946     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2947         "source pads_activate failed");
2948     return FALSE;
2949   }
2950 sink_failed:
2951   {
2952     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2953         "sink pads_activate failed");
2954     return FALSE;
2955   }
2956 caps_failed:
2957   {
2958     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2959         "failed to clear caps on pads");
2960     return FALSE;
2961   }
2962 }
2963
2964 /* is called with STATE_LOCK */
2965 static GstStateChangeReturn
2966 gst_element_change_state_func (GstElement * element, GstStateChange transition)
2967 {
2968   GstState state, next;
2969   GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
2970   GstClock **clock_p;
2971
2972   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2973
2974   state = (GstState) GST_STATE_TRANSITION_CURRENT (transition);
2975   next = GST_STATE_TRANSITION_NEXT (transition);
2976
2977   /* if the element already is in the given state, we just return success */
2978   if (next == GST_STATE_VOID_PENDING || state == next)
2979     goto was_ok;
2980
2981   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element,
2982       "default handler tries setting state from %s to %s (%04x)",
2983       gst_element_state_get_name (state),
2984       gst_element_state_get_name (next), transition);
2985
2986   switch (transition) {
2987     case GST_STATE_CHANGE_NULL_TO_READY:
2988       break;
2989     case GST_STATE_CHANGE_READY_TO_PAUSED:
2990       if (!gst_element_pads_activate (element, TRUE)) {
2991         result = GST_STATE_CHANGE_FAILURE;
2992       }
2993       break;
2994     case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
2995       break;
2996     case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
2997       break;
2998     case GST_STATE_CHANGE_PAUSED_TO_READY:
2999     case GST_STATE_CHANGE_READY_TO_NULL:
3000       /* deactivate pads in both cases, since they are activated on
3001          ready->paused but the element might not have made it to paused */
3002       if (!gst_element_pads_activate (element, FALSE)) {
3003         result = GST_STATE_CHANGE_FAILURE;
3004       } else {
3005         gst_element_set_base_time (element, 0);
3006       }
3007
3008       /* In null state release the reference to the clock */
3009       GST_OBJECT_LOCK (element);
3010       clock_p = &element->clock;
3011       gst_object_replace ((GstObject **) clock_p, NULL);
3012       GST_OBJECT_UNLOCK (element);
3013       break;
3014     default:
3015       /* this will catch real but unhandled state changes;
3016        * can only be caused by:
3017        * - a new state was added
3018        * - somehow the element was asked to jump across an intermediate state
3019        */
3020       g_warning ("Unhandled state change from %s to %s",
3021           gst_element_state_get_name (state),
3022           gst_element_state_get_name (next));
3023       break;
3024   }
3025   return result;
3026
3027 was_ok:
3028   {
3029     GST_OBJECT_LOCK (element);
3030     result = GST_STATE_RETURN (element);
3031     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
3032         "element is already in the %s state",
3033         gst_element_state_get_name (state));
3034     GST_OBJECT_UNLOCK (element);
3035
3036     return result;
3037   }
3038 }
3039
3040 /**
3041  * gst_element_get_factory:
3042  * @element: a #GstElement to request the element factory of.
3043  *
3044  * Retrieves the factory that was used to create this element.
3045  *
3046  * Returns: (transfer none): the #GstElementFactory used for creating this
3047  *     element. no refcounting is needed.
3048  */
3049 GstElementFactory *
3050 gst_element_get_factory (GstElement * element)
3051 {
3052   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
3053
3054   return GST_ELEMENT_GET_CLASS (element)->elementfactory;
3055 }
3056
3057 static void
3058 gst_element_dispose (GObject * object)
3059 {
3060   GstElement *element = GST_ELEMENT_CAST (object);
3061   GstClock **clock_p;
3062   GstBus **bus_p;
3063
3064   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "dispose");
3065
3066   if (GST_STATE (element) != GST_STATE_NULL)
3067     goto not_null;
3068
3069   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
3070       "removing %d pads", g_list_length (element->pads));
3071   /* first we break all our links with the outside */
3072   while (element->pads && element->pads->data) {
3073     /* don't call _remove_pad with NULL */
3074     gst_element_remove_pad (element, GST_PAD_CAST (element->pads->data));
3075   }
3076   if (G_UNLIKELY (element->pads != NULL)) {
3077     g_critical ("could not remove pads from element %s",
3078         GST_STR_NULL (GST_OBJECT_NAME (object)));
3079   }
3080
3081   GST_OBJECT_LOCK (element);
3082   clock_p = &element->clock;
3083   bus_p = &element->bus;
3084   gst_object_replace ((GstObject **) clock_p, NULL);
3085   gst_object_replace ((GstObject **) bus_p, NULL);
3086   GST_OBJECT_UNLOCK (element);
3087
3088   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "parent class dispose");
3089
3090   G_OBJECT_CLASS (parent_class)->dispose (object);
3091
3092   return;
3093
3094   /* ERRORS */
3095 not_null:
3096   {
3097     gboolean is_locked;
3098
3099     is_locked = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
3100     g_critical
3101         ("\nTrying to dispose element %s, but it is in %s%s instead of the NULL"
3102         " state.\n"
3103         "You need to explicitly set elements to the NULL state before\n"
3104         "dropping the final reference, to allow them to clean up.\n"
3105         "This problem may also be caused by a refcounting bug in the\n"
3106         "application or some element.\n",
3107         GST_OBJECT_NAME (element),
3108         gst_element_state_get_name (GST_STATE (element)),
3109         is_locked ? " (locked)" : "");
3110     return;
3111   }
3112 }
3113
3114 static void
3115 gst_element_finalize (GObject * object)
3116 {
3117   GstElement *element = GST_ELEMENT_CAST (object);
3118
3119   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize");
3120
3121   GST_STATE_LOCK (element);
3122   if (element->state_cond)
3123     g_cond_free (element->state_cond);
3124   element->state_cond = NULL;
3125   GST_STATE_UNLOCK (element);
3126   g_static_rec_mutex_free (element->state_lock);
3127   g_slice_free (GStaticRecMutex, element->state_lock);
3128   element->state_lock = NULL;
3129
3130   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize parent");
3131
3132   G_OBJECT_CLASS (parent_class)->finalize (object);
3133 }
3134
3135 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
3136 /**
3137  * gst_element_save_thyself:
3138  * @element: a #GstElement to save.
3139  * @parent: the xml parent node.
3140  *
3141  * Saves the element as part of the given XML structure.
3142  *
3143  * Returns: the new #xmlNodePtr.
3144  */
3145 static xmlNodePtr
3146 gst_element_save_thyself (GstObject * object, xmlNodePtr parent)
3147 {
3148   GList *pads;
3149   GstElementClass *oclass;
3150   GParamSpec **specs, *spec;
3151   guint nspecs;
3152   guint i;
3153   GValue value = { 0, };
3154   GstElement *element;
3155
3156   g_return_val_if_fail (GST_IS_ELEMENT (object), parent);
3157
3158   element = GST_ELEMENT_CAST (object);
3159
3160   oclass = GST_ELEMENT_GET_CLASS (element);
3161
3162   xmlNewChild (parent, NULL, (xmlChar *) "name",
3163       (xmlChar *) GST_ELEMENT_NAME (element));
3164
3165   if (oclass->elementfactory != NULL) {
3166     GstElementFactory *factory = (GstElementFactory *) oclass->elementfactory;
3167
3168     xmlNewChild (parent, NULL, (xmlChar *) "type",
3169         (xmlChar *) GST_PLUGIN_FEATURE (factory)->name);
3170   }
3171
3172   /* params */
3173   specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (object), &nspecs);
3174
3175   for (i = 0; i < nspecs; i++) {
3176     spec = specs[i];
3177     if (spec->flags & G_PARAM_READABLE) {
3178       xmlNodePtr param;
3179       char *contents;
3180
3181       g_value_init (&value, spec->value_type);
3182
3183       g_object_get_property (G_OBJECT (element), spec->name, &value);
3184       param = xmlNewChild (parent, NULL, (xmlChar *) "param", NULL);
3185       xmlNewChild (param, NULL, (xmlChar *) "name", (xmlChar *) spec->name);
3186
3187       if (G_IS_PARAM_SPEC_STRING (spec))
3188         contents = g_value_dup_string (&value);
3189       else if (G_IS_PARAM_SPEC_ENUM (spec))
3190         contents = g_strdup_printf ("%d", g_value_get_enum (&value));
3191       else if (G_IS_PARAM_SPEC_INT64 (spec))
3192         contents = g_strdup_printf ("%" G_GINT64_FORMAT,
3193             g_value_get_int64 (&value));
3194       else if (GST_VALUE_HOLDS_STRUCTURE (&value)) {
3195         if (g_value_get_boxed (&value) != NULL) {
3196           contents = g_strdup_value_contents (&value);
3197         } else {
3198           contents = g_strdup ("NULL");
3199         }
3200       } else
3201         contents = g_strdup_value_contents (&value);
3202
3203       xmlNewChild (param, NULL, (xmlChar *) "value", (xmlChar *) contents);
3204       g_free (contents);
3205
3206       g_value_unset (&value);
3207     }
3208   }
3209
3210   g_free (specs);
3211
3212   pads = g_list_last (GST_ELEMENT_PADS (element));
3213
3214   while (pads) {
3215     GstPad *pad = GST_PAD_CAST (pads->data);
3216
3217     /* figure out if it's a direct pad or a ghostpad */
3218     if (GST_ELEMENT_CAST (GST_OBJECT_PARENT (pad)) == element) {
3219       xmlNodePtr padtag = xmlNewChild (parent, NULL, (xmlChar *) "pad", NULL);
3220
3221       gst_object_save_thyself (GST_OBJECT_CAST (pad), padtag);
3222     }
3223     pads = g_list_previous (pads);
3224   }
3225
3226   return parent;
3227 }
3228
3229 static void
3230 gst_element_restore_thyself (GstObject * object, xmlNodePtr self)
3231 {
3232   xmlNodePtr children;
3233   GstElement *element;
3234   gchar *name = NULL;
3235   gchar *value = NULL;
3236
3237   element = GST_ELEMENT_CAST (object);
3238   g_return_if_fail (element != NULL);
3239
3240   /* parameters */
3241   children = self->xmlChildrenNode;
3242   while (children) {
3243     if (!strcmp ((char *) children->name, "param")) {
3244       xmlNodePtr child = children->xmlChildrenNode;
3245
3246       while (child) {
3247         if (!strcmp ((char *) child->name, "name")) {
3248           name = (gchar *) xmlNodeGetContent (child);
3249         } else if (!strcmp ((char *) child->name, "value")) {
3250           value = (gchar *) xmlNodeGetContent (child);
3251         }
3252         child = child->next;
3253       }
3254       /* FIXME: can this just be g_object_set ? */
3255       gst_util_set_object_arg (G_OBJECT (element), name, value);
3256       /* g_object_set (G_OBJECT (element), name, value, NULL); */
3257       g_free (name);
3258       g_free (value);
3259     }
3260     children = children->next;
3261   }
3262
3263   /* pads */
3264   children = self->xmlChildrenNode;
3265   while (children) {
3266     if (!strcmp ((char *) children->name, "pad")) {
3267       gst_pad_load_and_link (children, GST_OBJECT_CAST (element));
3268     }
3269     children = children->next;
3270   }
3271
3272   if (GST_OBJECT_CLASS (parent_class)->restore_thyself)
3273     (GST_OBJECT_CLASS (parent_class)->restore_thyself) (object, self);
3274 }
3275 #endif /* GST_DISABLE_LOADSAVE */
3276
3277 static void
3278 gst_element_set_bus_func (GstElement * element, GstBus * bus)
3279 {
3280   GstBus **bus_p;
3281
3282   g_return_if_fail (GST_IS_ELEMENT (element));
3283
3284   GST_CAT_DEBUG_OBJECT (GST_CAT_PARENTAGE, element, "setting bus to %p", bus);
3285
3286   GST_OBJECT_LOCK (element);
3287   bus_p = &GST_ELEMENT_BUS (element);
3288   gst_object_replace ((GstObject **) bus_p, GST_OBJECT_CAST (bus));
3289   GST_OBJECT_UNLOCK (element);
3290 }
3291
3292 /**
3293  * gst_element_set_bus:
3294  * @element: a #GstElement to set the bus of.
3295  * @bus: (transfer none): the #GstBus to set.
3296  *
3297  * Sets the bus of the element. Increases the refcount on the bus.
3298  * For internal use only, unless you're testing elements.
3299  *
3300  * MT safe.
3301  */
3302 void
3303 gst_element_set_bus (GstElement * element, GstBus * bus)
3304 {
3305   GstElementClass *oclass;
3306
3307   g_return_if_fail (GST_IS_ELEMENT (element));
3308
3309   oclass = GST_ELEMENT_GET_CLASS (element);
3310
3311   if (oclass->set_bus)
3312     oclass->set_bus (element, bus);
3313 }
3314
3315 /**
3316  * gst_element_get_bus:
3317  * @element: a #GstElement to get the bus of.
3318  *
3319  * Returns the bus of the element. Note that only a #GstPipeline will provide a
3320  * bus for the application.
3321  *
3322  * Returns: (transfer full): the element's #GstBus. unref after usage.
3323  *
3324  * MT safe.
3325  */
3326 GstBus *
3327 gst_element_get_bus (GstElement * element)
3328 {
3329   GstBus *result = NULL;
3330
3331   g_return_val_if_fail (GST_IS_ELEMENT (element), result);
3332
3333   GST_OBJECT_LOCK (element);
3334   if ((result = GST_ELEMENT_BUS (element)))
3335     gst_object_ref (result);
3336   GST_OBJECT_UNLOCK (element);
3337
3338   GST_CAT_DEBUG_OBJECT (GST_CAT_BUS, element, "got bus %" GST_PTR_FORMAT,
3339       result);
3340
3341   return result;
3342 }