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