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