gst/gstelement.c

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