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