gst/gstelement.c

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