gst/gstelement.c

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