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   gint n;
 990   const gchar *data;
 991   gchar *str, *endptr = NULL;
 992   GstElementClass *class;
 993
 994   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
 995   g_return_val_if_fail (name != NULL, NULL);
 996
 997   class = GST_ELEMENT_GET_CLASS (element);
 998
 999   /* if the name contains a %, we assume it's the complete template name. Get
1000    * the template and try to get a pad */
1001   if (strstr (name, "%")) {
1002     templ = gst_element_class_get_request_pad_template (class, name);
1003     req_name = NULL;
1004     if (templ)
1005       templ_found = TRUE;
1006   } else {
1007     /* there is no % in the name, try to find a matching template */
1008     list = class->padtemplates;
1009     while (!templ_found && list) {
1010       templ = (GstPadTemplate *) list->data;
1011       if (templ->presence == GST_PAD_REQUEST) {
1012         GST_CAT_DEBUG (GST_CAT_PADS, "comparing %s to %s", name,
1013             templ->name_template);
1014         /* see if we find an exact match */
1015         if (strcmp (name, templ->name_template) == 0) {
1016           templ_found = TRUE;
1017           req_name = name;
1018           break;
1019         }
1020         /* Because of sanity checks in gst_pad_template_new(), we know that %s
1021            and %d, occurring at the end of the name_template, are the only
1022            possibilities. */
1023         else if ((str = strchr (templ->name_template, '%'))
1024             && strncmp (templ->name_template, name,
1025                 str - templ->name_template) == 0
1026             && strlen (name) > str - templ->name_template) {
1027           data = name + (str - templ->name_template);
1028           if (*(str + 1) == 'd') {
1029             /* it's an int */
1030             n = (gint) strtol (data, &endptr, 10);
1031             if (endptr && *endptr == '\0') {
1032               templ_found = TRUE;
1033               req_name = name;
1034               break;
1035             }
1036           } else {
1037             /* it's a string */
1038             templ_found = TRUE;
1039             req_name = name;
1040             break;
1041           }
1042         }
1043       }
1044       list = list->next;
1045     }
1046   }
1047
1048   if (!templ_found)
1049     return NULL;
1050
1051   pad = gst_element_request_pad (element, templ, req_name);
1052
1053   return pad;
1054 }
1055
1056 /**
1057  * gst_element_get_pad:
1058  * @element: a #GstElement.
1059  * @name: the name of the pad to retrieve.
1060  *
1061  * Retrieves a pad from @element by name. Tries gst_element_get_static_pad()
1062  * first, then gst_element_get_request_pad().
1063  *
1064  * Deprecated: This function is deprecated as it's unclear if the reference
1065  * to the result pad should be released with gst_object_unref() in case of a static pad
1066  * or gst_element_release_request_pad() in case of a request pad.
1067  * Use gst_element_get_static_pad() or gst_element_get_request_pad() instead.
1068  *
1069  * Returns: the #GstPad if found, otherwise %NULL. Unref or Release after usage,
1070  * depending on the type of the pad.
1071  */
1072 #ifndef GST_REMOVE_DEPRECATED
1073 #ifdef GST_DISABLE_DEPRECATED
1074 GstPad *gst_element_get_pad (GstElement * element, const gchar * name);
1075 #endif
1076 GstPad *
1077 gst_element_get_pad (GstElement * element, const gchar * name)
1078 {
1079   GstPad *pad;
1080
1081   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1082   g_return_val_if_fail (name != NULL, NULL);
1083
1084   pad = gst_element_get_static_pad (element, name);
1085   if (!pad)
1086     pad = gst_element_get_request_pad (element, name);
1087
1088   return pad;
1089 }
1090 #endif /* GST_REMOVE_DEPRECATED */
1091
1092 static GstIteratorItem
1093 iterate_pad (GstIterator * it, GstPad * pad)
1094 {
1095   gst_object_ref (pad);
1096   return GST_ITERATOR_ITEM_PASS;
1097 }
1098
1099 static GstIterator *
1100 gst_element_iterate_pad_list (GstElement * element, GList ** padlist)
1101 {
1102   GstIterator *result;
1103
1104   GST_OBJECT_LOCK (element);
1105   gst_object_ref (element);
1106   result = gst_iterator_new_list (GST_TYPE_PAD,
1107       GST_OBJECT_GET_LOCK (element),
1108       &element->pads_cookie,
1109       padlist,
1110       element,
1111       (GstIteratorItemFunction) iterate_pad,
1112       (GstIteratorDisposeFunction) gst_object_unref);
1113   GST_OBJECT_UNLOCK (element);
1114
1115   return result;
1116 }
1117
1118 /**
1119  * gst_element_iterate_pads:
1120  * @element: a #GstElement to iterate pads of.
1121  *
1122  * Retrieves an iterattor of @element's pads. The iterator should
1123  * be freed after usage.
1124  *
1125  * Returns: the #GstIterator of #GstPad. Unref each pad after use.
1126  *
1127  * MT safe.
1128  */
1129 GstIterator *
1130 gst_element_iterate_pads (GstElement * element)
1131 {
1132   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1133
1134   return gst_element_iterate_pad_list (element, &element->pads);
1135 }
1136
1137 /**
1138  * gst_element_iterate_src_pads:
1139  * @element: a #GstElement.
1140  *
1141  * Retrieves an iterator of @element's source pads.
1142  *
1143  * Returns: the #GstIterator of #GstPad. Unref each pad after use.
1144  *
1145  * MT safe.
1146  */
1147 GstIterator *
1148 gst_element_iterate_src_pads (GstElement * element)
1149 {
1150   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1151
1152   return gst_element_iterate_pad_list (element, &element->srcpads);
1153 }
1154
1155 /**
1156  * gst_element_iterate_sink_pads:
1157  * @element: a #GstElement.
1158  *
1159  * Retrieves an iterator of @element's sink pads.
1160  *
1161  * Returns: the #GstIterator of #GstPad. Unref each pad after use.
1162  *
1163  * MT safe.
1164  */
1165 GstIterator *
1166 gst_element_iterate_sink_pads (GstElement * element)
1167 {
1168   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1169
1170   return gst_element_iterate_pad_list (element, &element->sinkpads);
1171 }
1172
1173 /**
1174  * gst_element_class_add_pad_template:
1175  * @klass: the #GstElementClass to add the pad template to.
1176  * @templ: a #GstPadTemplate to add to the element class.
1177  *
1178  * Adds a padtemplate to an element class. This is mainly used in the _base_init
1179  * functions of classes.
1180  */
1181 void
1182 gst_element_class_add_pad_template (GstElementClass * klass,
1183     GstPadTemplate * templ)
1184 {
1185   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1186   g_return_if_fail (GST_IS_PAD_TEMPLATE (templ));
1187
1188   /* FIXME 0.11: allow replacing the pad templates by
1189    * calling this with the same name as an already existing pad
1190    * template. For this we _must_ _not_ ref the added pad template
1191    * a second time and _must_ document that this function takes
1192    * ownership of the pad template. Otherwise we will leak pad templates
1193    * or the caller unref's the pad template and it disappears */
1194   /* avoid registering pad templates with the same name */
1195   g_return_if_fail (gst_element_class_get_pad_template (klass,
1196           templ->name_template) == NULL);
1197
1198   klass->padtemplates = g_list_append (klass->padtemplates,
1199       gst_object_ref (templ));
1200   klass->numpadtemplates++;
1201 }
1202
1203 /**
1204  * gst_element_class_set_details:
1205  * @klass: class to set details for
1206  * @details: details to set
1207  *
1208  * Sets the detailed information for a #GstElementClass.
1209  * <note>This function is for use in _base_init functions only.</note>
1210  *
1211  * The @details are copied.
1212  *
1213  * Deprecated: Use gst_element_class_set_details_simple() instead.
1214  */
1215 #ifndef GST_REMOVE_DEPRECATED
1216 #ifdef GST_DISABLE_DEPRECATED
1217 void
1218 gst_element_class_set_details (GstElementClass * klass,
1219     const GstElementDetails * details);
1220 #endif
1221 void
1222 gst_element_class_set_details (GstElementClass * klass,
1223     const GstElementDetails * details)
1224 {
1225   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1226   g_return_if_fail (GST_IS_ELEMENT_DETAILS (details));
1227
1228   __gst_element_details_copy (&klass->details, details);
1229 }
1230 #endif
1231
1232 /**
1233  * gst_element_class_set_details_simple:
1234  * @klass: class to set details for
1235  * @longname: The long English name of the element. E.g. "File Sink"
1236  * @classification: String describing the type of element, as an unordered list
1237  * separated with slashes ('/'). See draft-klass.txt of the design docs
1238  * for more details and common types. E.g: "Sink/File"
1239  * @description: Sentence describing the purpose of the element.
1240  * E.g: "Write stream to a file"
1241  * @author: Name and contact details of the author(s). Use \n to separate
1242  * multiple author details. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
1243  *
1244  * Sets the detailed information for a #GstElementClass. Simpler version of
1245  * gst_element_class_set_details() that generates less linker overhead.
1246  * <note>This function is for use in _base_init functions only.</note>
1247  *
1248  * The detail parameter strings are copied into the #GstElementDetails for
1249  * the element class.
1250  *
1251  * Since: 0.10.14
1252  */
1253 void
1254 gst_element_class_set_details_simple (GstElementClass * klass,
1255     const gchar * longname, const gchar * classification,
1256     const gchar * description, const gchar * author)
1257 {
1258   const GstElementDetails details =
1259       GST_ELEMENT_DETAILS ((gchar *) longname, (gchar *) classification,
1260       (gchar *) description, (gchar *) author);
1261
1262   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1263
1264   __gst_element_details_copy (&klass->details, &details);
1265 }
1266
1267 /**
1268  * gst_element_class_get_pad_template_list:
1269  * @element_class: a #GstElementClass to get pad templates of.
1270  *
1271  * Retrieves a list of the pad templates associated with @element_class. The
1272  * list must not be modified by the calling code.
1273  * <note>If you use this function in the #GInstanceInitFunc of an object class
1274  * that has subclasses, make sure to pass the g_class parameter of the
1275  * #GInstanceInitFunc here.</note>
1276  *
1277  * Returns: the #GList of padtemplates.
1278  */
1279 GList *
1280 gst_element_class_get_pad_template_list (GstElementClass * element_class)
1281 {
1282   g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1283
1284   return element_class->padtemplates;
1285 }
1286
1287 /**
1288  * gst_element_class_get_pad_template:
1289  * @element_class: a #GstElementClass to get the pad template of.
1290  * @name: the name of the #GstPadTemplate to get.
1291  *
1292  * Retrieves a padtemplate from @element_class with the given name.
1293  * <note>If you use this function in the #GInstanceInitFunc of an object class
1294  * that has subclasses, make sure to pass the g_class parameter of the
1295  * #GInstanceInitFunc here.</note>
1296  *
1297  * Returns: the #GstPadTemplate with the given name, or %NULL if none was found.
1298  * No unreferencing is necessary.
1299  */
1300 GstPadTemplate *
1301 gst_element_class_get_pad_template (GstElementClass * element_class,
1302     const gchar * name)
1303 {
1304   GList *padlist;
1305
1306   g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1307   g_return_val_if_fail (name != NULL, NULL);
1308
1309   padlist = element_class->padtemplates;
1310
1311   while (padlist) {
1312     GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
1313
1314     if (strcmp (padtempl->name_template, name) == 0)
1315       return padtempl;
1316
1317     padlist = g_list_next (padlist);
1318   }
1319
1320   return NULL;
1321 }
1322
1323 static GstPadTemplate *
1324 gst_element_class_get_request_pad_template (GstElementClass * element_class,
1325     const gchar * name)
1326 {
1327   GstPadTemplate *tmpl;
1328
1329   tmpl = gst_element_class_get_pad_template (element_class, name);
1330   if (tmpl != NULL && tmpl->presence == GST_PAD_REQUEST)
1331     return tmpl;
1332
1333   return NULL;
1334 }
1335
1336 /* get a random pad on element of the given direction.
1337  * The pad is random in a sense that it is the first pad that is (optionaly) linked.
1338  */
1339 static GstPad *
1340 gst_element_get_random_pad (GstElement * element, gboolean need_linked,
1341     GstPadDirection dir)
1342 {
1343   GstPad *result = NULL;
1344   GList *pads;
1345
1346   GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "getting a random pad");
1347
1348   switch (dir) {
1349     case GST_PAD_SRC:
1350       GST_OBJECT_LOCK (element);
1351       pads = element->srcpads;
1352       break;
1353     case GST_PAD_SINK:
1354       GST_OBJECT_LOCK (element);
1355       pads = element->sinkpads;
1356       break;
1357     default:
1358       goto wrong_direction;
1359   }
1360   for (; pads; pads = g_list_next (pads)) {
1361     GstPad *pad = GST_PAD_CAST (pads->data);
1362
1363     GST_OBJECT_LOCK (pad);
1364     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "checking pad %s:%s",
1365         GST_DEBUG_PAD_NAME (pad));
1366
1367     if (need_linked && !GST_PAD_IS_LINKED (pad)) {
1368       /* if we require a linked pad, and it is not linked, continue the
1369        * search */
1370       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is not linked",
1371           GST_DEBUG_PAD_NAME (pad));
1372       GST_OBJECT_UNLOCK (pad);
1373       continue;
1374     } else {
1375       /* found a pad, stop search */
1376       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
1377           GST_DEBUG_PAD_NAME (pad));
1378       GST_OBJECT_UNLOCK (pad);
1379       result = pad;
1380       break;
1381     }
1382   }
1383   if (result)
1384     gst_object_ref (result);
1385
1386   GST_OBJECT_UNLOCK (element);
1387
1388   return result;
1389
1390   /* ERROR handling */
1391 wrong_direction:
1392   {
1393     g_warning ("unknown pad direction %d", dir);
1394     return NULL;
1395   }
1396 }
1397
1398 static gboolean
1399 gst_element_default_send_event (GstElement * element, GstEvent * event)
1400 {
1401   gboolean result = FALSE;
1402   GstPad *pad;
1403
1404   pad = GST_EVENT_IS_DOWNSTREAM (event) ?
1405       gst_element_get_random_pad (element, TRUE, GST_PAD_SRC) :
1406       gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1407
1408   if (pad) {
1409     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1410         "pushing %s event to random %s pad %s:%s",
1411         GST_EVENT_TYPE_NAME (event),
1412         (GST_PAD_DIRECTION (pad) == GST_PAD_SRC ? "src" : "sink"),
1413         GST_DEBUG_PAD_NAME (pad));
1414
1415     result = gst_pad_push_event (pad, event);
1416     gst_object_unref (pad);
1417   } else {
1418     GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "can't send %s event on element %s",
1419         GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1420   }
1421   return result;
1422 }
1423
1424 /**
1425  * gst_element_send_event:
1426  * @element: a #GstElement to send the event to.
1427  * @event: the #GstEvent to send to the element.
1428  *
1429  * Sends an event to an element. If the element doesn't implement an
1430  * event handler, the event will be pushed on a random linked sink pad for
1431  * upstream events or a random linked source pad for downstream events.
1432  *
1433  * This function takes owership of the provided event so you should
1434  * gst_event_ref() it if you want to reuse the event after this call.
1435  *
1436  * Returns: %TRUE if the event was handled.
1437  *
1438  * MT safe.
1439  */
1440 gboolean
1441 gst_element_send_event (GstElement * element, GstEvent * event)
1442 {
1443   GstElementClass *oclass;
1444   gboolean result = FALSE;
1445
1446   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1447   g_return_val_if_fail (event != NULL, FALSE);
1448
1449   oclass = GST_ELEMENT_GET_CLASS (element);
1450
1451   GST_STATE_LOCK (element);
1452   if (oclass->send_event) {
1453     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send %s event on element %s",
1454         GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1455     result = oclass->send_event (element, event);
1456   } else {
1457     result = gst_element_default_send_event (element, event);
1458   }
1459   GST_STATE_UNLOCK (element);
1460
1461   return result;
1462 }
1463
1464 /**
1465  * gst_element_seek:
1466  * @element: a #GstElement to send the event to.
1467  * @rate: The new playback rate
1468  * @format: The format of the seek values
1469  * @flags: The optional seek flags.
1470  * @cur_type: The type and flags for the new current position
1471  * @cur: The value of the new current position
1472  * @stop_type: The type and flags for the new stop position
1473  * @stop: The value of the new stop position
1474  *
1475  * Sends a seek event to an element. See gst_event_new_seek() for the details of
1476  * the parameters. The seek event is sent to the element using
1477  * gst_element_send_event().
1478  *
1479  * Returns: %TRUE if the event was handled.
1480  *
1481  * MT safe.
1482  */
1483 gboolean
1484 gst_element_seek (GstElement * element, gdouble rate, GstFormat format,
1485     GstSeekFlags flags, GstSeekType cur_type, gint64 cur,
1486     GstSeekType stop_type, gint64 stop)
1487 {
1488   GstEvent *event;
1489   gboolean result;
1490
1491   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1492
1493   event =
1494       gst_event_new_seek (rate, format, flags, cur_type, cur, stop_type, stop);
1495   result = gst_element_send_event (element, event);
1496
1497   return result;
1498 }
1499
1500 /**
1501  * gst_element_get_query_types:
1502  * @element: a #GstElement to query
1503  *
1504  * Get an array of query types from the element.
1505  * If the element doesn't implement a query types function,
1506  * the query will be forwarded to the peer of a random linked sink pad.
1507  *
1508  * Returns: An array of #GstQueryType elements that should not
1509  * be freed or modified.
1510  *
1511  * MT safe.
1512  */
1513 const GstQueryType *
1514 gst_element_get_query_types (GstElement * element)
1515 {
1516   GstElementClass *oclass;
1517   const GstQueryType *result = NULL;
1518
1519   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1520
1521   oclass = GST_ELEMENT_GET_CLASS (element);
1522
1523   if (oclass->get_query_types) {
1524     result = oclass->get_query_types (element);
1525   } else {
1526     GstPad *pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1527
1528     if (pad) {
1529       GstPad *peer = gst_pad_get_peer (pad);
1530
1531       if (peer) {
1532         result = gst_pad_get_query_types (peer);
1533
1534         gst_object_unref (peer);
1535       }
1536       gst_object_unref (pad);
1537     }
1538   }
1539   return result;
1540 }
1541
1542 static gboolean
1543 gst_element_default_query (GstElement * element, GstQuery * query)
1544 {
1545   gboolean result = FALSE;
1546   GstPad *pad;
1547
1548   pad = gst_element_get_random_pad (element, FALSE, GST_PAD_SRC);
1549   if (pad) {
1550     result = gst_pad_query (pad, query);
1551
1552     gst_object_unref (pad);
1553   } else {
1554     pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1555     if (pad) {
1556       GstPad *peer = gst_pad_get_peer (pad);
1557
1558       if (peer) {
1559         result = gst_pad_query (peer, query);
1560
1561         gst_object_unref (peer);
1562       }
1563       gst_object_unref (pad);
1564     }
1565   }
1566   return result;
1567 }
1568
1569 /**
1570  * gst_element_query:
1571  * @element: a #GstElement to perform the query on.
1572  * @query: the #GstQuery.
1573  *
1574  * Performs a query on the given element.
1575  *
1576  * For elements that don't implement a query handler, this function
1577  * forwards the query to a random srcpad or to the peer of a
1578  * random linked sinkpad of this element.
1579  *
1580  * Returns: TRUE if the query could be performed.
1581  *
1582  * MT safe.
1583  */
1584 gboolean
1585 gst_element_query (GstElement * element, GstQuery * query)
1586 {
1587   GstElementClass *oclass;
1588   gboolean result = FALSE;
1589
1590   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1591   g_return_val_if_fail (query != NULL, FALSE);
1592
1593   oclass = GST_ELEMENT_GET_CLASS (element);
1594
1595   if (oclass->query) {
1596     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send query on element %s",
1597         GST_ELEMENT_NAME (element));
1598     result = oclass->query (element, query);
1599   } else {
1600     result = gst_element_default_query (element, query);
1601   }
1602   return result;
1603 }
1604
1605 /**
1606  * gst_element_post_message:
1607  * @element: a #GstElement posting the message
1608  * @message: a #GstMessage to post
1609  *
1610  * Post a message on the element's #GstBus. This function takes ownership of the
1611  * message; if you want to access the message after this call, you should add an
1612  * additional reference before calling.
1613  *
1614  * Returns: %TRUE if the message was successfully posted. The function returns
1615  * %FALSE if the element did not have a bus.
1616  *
1617  * MT safe.
1618  */
1619 gboolean
1620 gst_element_post_message (GstElement * element, GstMessage * message)
1621 {
1622   GstBus *bus;
1623   gboolean result = FALSE;
1624
1625   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1626   g_return_val_if_fail (message != NULL, FALSE);
1627
1628   GST_OBJECT_LOCK (element);
1629   bus = element->bus;
1630
1631   if (G_UNLIKELY (bus == NULL))
1632     goto no_bus;
1633
1634   gst_object_ref (bus);
1635   GST_OBJECT_UNLOCK (element);
1636
1637   /* we release the element lock when posting the message so that any
1638    * (synchronous) message handlers can operate on the element */
1639   result = gst_bus_post (bus, message);
1640   gst_object_unref (bus);
1641
1642   return result;
1643
1644   /* ERRORS */
1645 no_bus:
1646   {
1647     GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element,
1648         "not posting message %p: no bus", message);
1649     GST_OBJECT_UNLOCK (element);
1650     gst_message_unref (message);
1651     return FALSE;
1652   }
1653 }
1654
1655 /**
1656  * _gst_element_error_printf:
1657  * @format: the printf-like format to use, or %NULL
1658  *
1659  * This function is only used internally by the gst_element_error() macro.
1660  *
1661  * Returns: a newly allocated string, or %NULL if the format was %NULL or ""
1662  *
1663  * MT safe.
1664  */
1665 gchar *
1666 _gst_element_error_printf (const gchar * format, ...)
1667 {
1668   va_list args;
1669   gchar *buffer;
1670
1671   if (format == NULL)
1672     return NULL;
1673   if (format[0] == 0)
1674     return NULL;
1675
1676   va_start (args, format);
1677   buffer = g_strdup_vprintf (format, args);
1678   va_end (args);
1679   return buffer;
1680 }
1681
1682 /**
1683  * gst_element_message_full:
1684  * @element:  a #GstElement to send message from
1685  * @type:     the #GstMessageType
1686  * @domain:   the GStreamer GError domain this message belongs to
1687  * @code:     the GError code belonging to the domain
1688  * @text:     an allocated text string to be used as a replacement for the
1689  *            default message connected to code, or %NULL
1690  * @debug:    an allocated debug message to be used as a replacement for the
1691  *            default debugging information, or %NULL
1692  * @file:     the source code file where the error was generated
1693  * @function: the source code function where the error was generated
1694  * @line:     the source code line where the error was generated
1695  *
1696  * Post an error, warning or info message on the bus from inside an element.
1697  *
1698  * @type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or
1699  * #GST_MESSAGE_INFO.
1700  *
1701  * MT safe.
1702  */
1703 void gst_element_message_full
1704     (GstElement * element, GstMessageType type,
1705     GQuark domain, gint code, gchar * text,
1706     gchar * debug, const gchar * file, const gchar * function, gint line)
1707 {
1708   GError *gerror = NULL;
1709   gchar *name;
1710   gchar *sent_text;
1711   gchar *sent_debug;
1712   gboolean has_debug = TRUE;
1713   GstMessage *message = NULL;
1714
1715   /* checks */
1716   GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element, "start");
1717   g_return_if_fail (GST_IS_ELEMENT (element));
1718   g_return_if_fail ((type == GST_MESSAGE_ERROR) ||
1719       (type == GST_MESSAGE_WARNING) || (type == GST_MESSAGE_INFO));
1720
1721   /* check if we send the given text or the default error text */
1722   if ((text == NULL) || (text[0] == 0)) {
1723     /* text could have come from g_strdup_printf (""); */
1724     g_free (text);
1725     sent_text = gst_error_get_message (domain, code);
1726   } else
1727     sent_text = text;
1728
1729   /* construct a sent_debug with extra information from source */
1730   if ((debug == NULL) || (debug[0] == 0)) {
1731     /* debug could have come from g_strdup_printf (""); */
1732     has_debug = FALSE;
1733   }
1734
1735   name = gst_object_get_path_string (GST_OBJECT_CAST (element));
1736   if (has_debug)
1737     sent_debug = g_strdup_printf ("%s(%d): %s (): %s:\n%s",
1738         file, line, function, name, debug);
1739   else
1740     sent_debug = g_strdup_printf ("%s(%d): %s (): %s",
1741         file, line, function, name);
1742   g_free (name);
1743   g_free (debug);
1744
1745   /* create gerror and post message */
1746   GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posting message: %s",
1747       sent_text);
1748   gerror = g_error_new_literal (domain, code, sent_text);
1749
1750   switch (type) {
1751     case GST_MESSAGE_ERROR:
1752       message =
1753           gst_message_new_error (GST_OBJECT_CAST (element), gerror, sent_debug);
1754       break;
1755     case GST_MESSAGE_WARNING:
1756       message = gst_message_new_warning (GST_OBJECT_CAST (element), gerror,
1757           sent_debug);
1758       break;
1759     case GST_MESSAGE_INFO:
1760       message = gst_message_new_info (GST_OBJECT_CAST (element), gerror,
1761           sent_debug);
1762       break;
1763     default:
1764       g_assert_not_reached ();
1765       break;
1766   }
1767   gst_element_post_message (element, message);
1768
1769   GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posted %s message: %s",
1770       (type == GST_MESSAGE_ERROR ? "error" : "warning"), sent_text);
1771
1772   /* cleanup */
1773   g_error_free (gerror);
1774   g_free (sent_debug);
1775   g_free (sent_text);
1776 }
1777
1778 /**
1779  * gst_element_is_locked_state:
1780  * @element: a #GstElement.
1781  *
1782  * Checks if the state of an element is locked.
1783  * If the state of an element is locked, state changes of the parent don't
1784  * affect the element.
1785  * This way you can leave currently unused elements inside bins. Just lock their
1786  * state before changing the state from #GST_STATE_NULL.
1787  *
1788  * MT safe.
1789  *
1790  * Returns: TRUE, if the element's state is locked.
1791  */
1792 gboolean
1793 gst_element_is_locked_state (GstElement * element)
1794 {
1795   gboolean result;
1796
1797   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1798
1799   GST_OBJECT_LOCK (element);
1800   result = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
1801   GST_OBJECT_UNLOCK (element);
1802
1803   return result;
1804 }
1805
1806 /**
1807  * gst_element_set_locked_state:
1808  * @element: a #GstElement
1809  * @locked_state: TRUE to lock the element's state
1810  *
1811  * Locks the state of an element, so state changes of the parent don't affect
1812  * this element anymore.
1813  *
1814  * MT safe.
1815  *
1816  * Returns: TRUE if the state was changed, FALSE if bad parameters were given
1817  * or the elements state-locking needed no change.
1818  */
1819 gboolean
1820 gst_element_set_locked_state (GstElement * element, gboolean locked_state)
1821 {
1822   gboolean old;
1823
1824   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1825
1826   GST_OBJECT_LOCK (element);
1827   old = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
1828
1829   if (G_UNLIKELY (old == locked_state))
1830     goto was_ok;
1831
1832   if (locked_state) {
1833     GST_CAT_DEBUG (GST_CAT_STATES, "locking state of element %s",
1834         GST_ELEMENT_NAME (element));
1835     GST_OBJECT_FLAG_SET (element, GST_ELEMENT_LOCKED_STATE);
1836   } else {
1837     GST_CAT_DEBUG (GST_CAT_STATES, "unlocking state of element %s",
1838         GST_ELEMENT_NAME (element));
1839     GST_OBJECT_FLAG_UNSET (element, GST_ELEMENT_LOCKED_STATE);
1840   }
1841   GST_OBJECT_UNLOCK (element);
1842
1843   return TRUE;
1844
1845 was_ok:
1846   {
1847     GST_CAT_DEBUG (GST_CAT_STATES, "elements %s was already in locked state %d",
1848         GST_ELEMENT_NAME (element), old);
1849     GST_OBJECT_UNLOCK (element);
1850
1851     return FALSE;
1852   }
1853 }
1854
1855 /**
1856  * gst_element_sync_state_with_parent:
1857  * @element: a #GstElement.
1858  *
1859  * Tries to change the state of the element to the same as its parent.
1860  * If this function returns FALSE, the state of element is undefined.
1861  *
1862  * Returns: TRUE, if the element's state could be synced to the parent's state.
1863  *
1864  * MT safe.
1865  */
1866 gboolean
1867 gst_element_sync_state_with_parent (GstElement * element)
1868 {
1869   GstElement *parent;
1870   GstState target;
1871   GstStateChangeReturn ret;
1872
1873   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1874
1875   if ((parent = GST_ELEMENT_CAST (gst_element_get_parent (element)))) {
1876     GstState parent_current, parent_pending;
1877
1878     GST_OBJECT_LOCK (parent);
1879     parent_current = GST_STATE (parent);
1880     parent_pending = GST_STATE_PENDING (parent);
1881     GST_OBJECT_UNLOCK (parent);
1882
1883     /* set to pending if there is one, else we set it to the current state of
1884      * the parent */
1885     if (parent_pending != GST_STATE_VOID_PENDING)
1886       target = parent_pending;
1887     else
1888       target = parent_current;
1889
1890     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
1891         "syncing state (%s) to parent %s %s (%s, %s)",
1892         gst_element_state_get_name (GST_STATE (element)),
1893         GST_ELEMENT_NAME (parent), gst_element_state_get_name (target),
1894         gst_element_state_get_name (parent_current),
1895         gst_element_state_get_name (parent_pending));
1896
1897     ret = gst_element_set_state (element, target);
1898     if (ret == GST_STATE_CHANGE_FAILURE)
1899       goto failed;
1900
1901     gst_object_unref (parent);
1902
1903     return TRUE;
1904   } else {
1905     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "element has no parent");
1906   }
1907   return FALSE;
1908
1909   /* ERROR */
1910 failed:
1911   {
1912     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
1913         "syncing state failed (%s)",
1914         gst_element_state_change_return_get_name (ret));
1915     gst_object_unref (parent);
1916     return FALSE;
1917   }
1918 }
1919
1920 /* MT safe */
1921 static GstStateChangeReturn
1922 gst_element_get_state_func (GstElement * element,
1923     GstState * state, GstState * pending, GstClockTime timeout)
1924 {
1925   GstStateChangeReturn ret = GST_STATE_CHANGE_FAILURE;
1926   GstState old_pending;
1927
1928   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "getting state, timeout %"
1929       GST_TIME_FORMAT, GST_TIME_ARGS (timeout));
1930
1931   GST_OBJECT_LOCK (element);
1932   ret = GST_STATE_RETURN (element);
1933   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "RETURN is %s",
1934       gst_element_state_change_return_get_name (ret));
1935
1936   /* we got an error, report immediately */
1937   if (ret == GST_STATE_CHANGE_FAILURE)
1938     goto done;
1939
1940   /* we got no_preroll, report immediatly */
1941   if (ret == GST_STATE_CHANGE_NO_PREROLL)
1942     goto done;
1943
1944   /* no need to wait async if we are not async */
1945   if (ret != GST_STATE_CHANGE_ASYNC)
1946     goto done;
1947
1948   old_pending = GST_STATE_PENDING (element);
1949   if (old_pending != GST_STATE_VOID_PENDING) {
1950     GTimeVal *timeval, abstimeout;
1951     guint32 cookie;
1952
1953     if (timeout != GST_CLOCK_TIME_NONE) {
1954       glong add = timeout / 1000;
1955
1956       if (add == 0)
1957         goto done;
1958
1959       /* make timeout absolute */
1960       g_get_current_time (&abstimeout);
1961       g_time_val_add (&abstimeout, add);
1962       timeval = &abstimeout;
1963     } else {
1964       timeval = NULL;
1965     }
1966     /* get cookie to detect state changes during waiting */
1967     cookie = element->state_cookie;
1968
1969     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1970         "waiting for element to commit state");
1971
1972     /* we have a pending state change, wait for it to complete */
1973     if (!GST_STATE_TIMED_WAIT (element, timeval)) {
1974       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "timed out");
1975       /* timeout triggered */
1976       ret = GST_STATE_CHANGE_ASYNC;
1977     } else {
1978       if (cookie != element->state_cookie)
1979         goto interrupted;
1980
1981       /* could be success or failure */
1982       if (old_pending == GST_STATE (element)) {
1983         GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got success");
1984         ret = GST_STATE_CHANGE_SUCCESS;
1985       } else {
1986         GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got failure");
1987         ret = GST_STATE_CHANGE_FAILURE;
1988       }
1989     }
1990     /* if nothing is pending anymore we can return SUCCESS */
1991     if (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING) {
1992       GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "nothing pending");
1993       ret = GST_STATE_CHANGE_SUCCESS;
1994     }
1995   }
1996
1997 done:
1998   if (state)
1999     *state = GST_STATE (element);
2000   if (pending)
2001     *pending = GST_STATE_PENDING (element);
2002
2003   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2004       "state current: %s, pending: %s, result: %s",
2005       gst_element_state_get_name (GST_STATE (element)),
2006       gst_element_state_get_name (GST_STATE_PENDING (element)),
2007       gst_element_state_change_return_get_name (ret));
2008   GST_OBJECT_UNLOCK (element);
2009
2010   return ret;
2011
2012 interrupted:
2013   {
2014     if (state)
2015       *state = GST_STATE_VOID_PENDING;
2016     if (pending)
2017       *pending = GST_STATE_VOID_PENDING;
2018
2019     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "interruped");
2020
2021     GST_OBJECT_UNLOCK (element);
2022
2023     return GST_STATE_CHANGE_FAILURE;
2024   }
2025 }
2026
2027 /**
2028  * gst_element_get_state:
2029  * @element: a #GstElement to get the state of.
2030  * @state: (out): a pointer to #GstState to hold the state. Can be %NULL.
2031  * @pending: (out): a pointer to #GstState to hold the pending state.
2032  *                  Can be %NULL.
2033  * @timeout: a #GstClockTime to specify the timeout for an async
2034  *           state change or %GST_CLOCK_TIME_NONE for infinite timeout.
2035  *
2036  * Gets the state of the element.
2037  *
2038  * For elements that performed an ASYNC state change, as reported by
2039  * gst_element_set_state(), this function will block up to the
2040  * specified timeout value for the state change to complete.
2041  * If the element completes the state change or goes into
2042  * an error, this function returns immediately with a return value of
2043  * %GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively.
2044  *
2045  * For elements that did not return %GST_STATE_CHANGE_ASYNC, this function
2046  * returns the current and pending state immediately.
2047  *
2048  * This function returns %GST_STATE_CHANGE_NO_PREROLL if the element
2049  * successfully changed its state but is not able to provide data yet.
2050  * This mostly happens for live sources that only produce data in
2051  * %GST_STATE_PLAYING. While the state change return is equivalent to
2052  * %GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that
2053  * some sink elements might not be able to complete their state change because
2054  * an element is not producing data to complete the preroll. When setting the
2055  * element to playing, the preroll will complete and playback will start.
2056  *
2057  * Returns: %GST_STATE_CHANGE_SUCCESS if the element has no more pending state
2058  *          and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the
2059  *          element is still performing a state change or
2060  *          %GST_STATE_CHANGE_FAILURE if the last state change failed.
2061  *
2062  * MT safe.
2063  */
2064 GstStateChangeReturn
2065 gst_element_get_state (GstElement * element,
2066     GstState * state, GstState * pending, GstClockTime timeout)
2067 {
2068   GstElementClass *oclass;
2069   GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2070
2071   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2072
2073   oclass = GST_ELEMENT_GET_CLASS (element);
2074
2075   if (oclass->get_state)
2076     result = (oclass->get_state) (element, state, pending, timeout);
2077
2078   return result;
2079 }
2080
2081 /**
2082  * gst_element_abort_state:
2083  * @element: a #GstElement to abort the state of.
2084  *
2085  * Abort the state change of the element. This function is used
2086  * by elements that do asynchronous state changes and find out
2087  * something is wrong.
2088  *
2089  * This function should be called with the STATE_LOCK held.
2090  *
2091  * MT safe.
2092  */
2093 void
2094 gst_element_abort_state (GstElement * element)
2095 {
2096   GstState pending;
2097
2098 #ifndef GST_DISABLE_GST_DEBUG
2099   GstState old_state;
2100 #endif
2101
2102   g_return_if_fail (GST_IS_ELEMENT (element));
2103
2104   GST_OBJECT_LOCK (element);
2105   pending = GST_STATE_PENDING (element);
2106
2107   if (pending == GST_STATE_VOID_PENDING ||
2108       GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2109     goto nothing_aborted;
2110
2111 #ifndef GST_DISABLE_GST_DEBUG
2112   old_state = GST_STATE (element);
2113
2114   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2115       "aborting state from %s to %s", gst_element_state_get_name (old_state),
2116       gst_element_state_get_name (pending));
2117 #endif
2118
2119   /* flag error */
2120   GST_STATE_RETURN (element) = GST_STATE_CHANGE_FAILURE;
2121
2122   GST_STATE_BROADCAST (element);
2123   GST_OBJECT_UNLOCK (element);
2124
2125   return;
2126
2127 nothing_aborted:
2128   {
2129     GST_OBJECT_UNLOCK (element);
2130     return;
2131   }
2132 }
2133
2134 /**
2135  * gst_element_continue_state:
2136  * @element: a #GstElement to continue the state change of.
2137  * @ret: The previous state return value
2138  *
2139  * Commit the state change of the element and proceed to the next
2140  * pending state if any. This function is used
2141  * by elements that do asynchronous state changes.
2142  * The core will normally call this method automatically when an
2143  * element returned %GST_STATE_CHANGE_SUCCESS from the state change function.
2144  *
2145  * If after calling this method the element still has not reached
2146  * the pending state, the next state change is performed.
2147  *
2148  * This method is used internally and should normally not be called by plugins
2149  * or applications.
2150  *
2151  * Returns: The result of the commit state change.
2152  *
2153  * MT safe.
2154  */
2155 GstStateChangeReturn
2156 gst_element_continue_state (GstElement * element, GstStateChangeReturn ret)
2157 {
2158   GstStateChangeReturn old_ret;
2159   GstState old_state, old_next;
2160   GstState current, next, pending;
2161   GstMessage *message;
2162   GstStateChange transition;
2163
2164   GST_OBJECT_LOCK (element);
2165   old_ret = GST_STATE_RETURN (element);
2166   GST_STATE_RETURN (element) = ret;
2167   pending = GST_STATE_PENDING (element);
2168
2169   /* check if there is something to commit */
2170   if (pending == GST_STATE_VOID_PENDING)
2171     goto nothing_pending;
2172
2173   old_state = GST_STATE (element);
2174   /* this is the state we should go to next */
2175   old_next = GST_STATE_NEXT (element);
2176   /* update current state */
2177   current = GST_STATE (element) = old_next;
2178
2179   /* see if we reached the final state */
2180   if (pending == current)
2181     goto complete;
2182
2183   next = GST_STATE_GET_NEXT (current, pending);
2184   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2185
2186   GST_STATE_NEXT (element) = next;
2187   /* mark busy */
2188   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2189   GST_OBJECT_UNLOCK (element);
2190
2191   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2192       "committing state from %s to %s, pending %s, next %s",
2193       gst_element_state_get_name (old_state),
2194       gst_element_state_get_name (old_next),
2195       gst_element_state_get_name (pending), gst_element_state_get_name (next));
2196
2197   message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2198       old_state, old_next, pending);
2199   gst_element_post_message (element, message);
2200
2201   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2202       "continue state change %s to %s, final %s",
2203       gst_element_state_get_name (current),
2204       gst_element_state_get_name (next), gst_element_state_get_name (pending));
2205
2206   ret = gst_element_change_state (element, transition);
2207
2208   return ret;
2209
2210 nothing_pending:
2211   {
2212     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "nothing pending");
2213     GST_OBJECT_UNLOCK (element);
2214     return ret;
2215   }
2216 complete:
2217   {
2218     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2219     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2220
2221     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2222         "completed state change to %s", gst_element_state_get_name (pending));
2223     GST_OBJECT_UNLOCK (element);
2224
2225     /* don't post silly messages with the same state. This can happen
2226      * when an element state is changed to what it already was. For bins
2227      * this can be the result of a lost state, which we check with the
2228      * previous return value.
2229      * We do signal the cond though as a _get_state() might be blocking
2230      * on it. */
2231     if (old_state != old_next || old_ret == GST_STATE_CHANGE_ASYNC) {
2232       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2233           "posting state-changed %s to %s",
2234           gst_element_state_get_name (old_state),
2235           gst_element_state_get_name (old_next));
2236       message =
2237           gst_message_new_state_changed (GST_OBJECT_CAST (element), old_state,
2238           old_next, GST_STATE_VOID_PENDING);
2239       gst_element_post_message (element, message);
2240     }
2241
2242     GST_STATE_BROADCAST (element);
2243
2244     return ret;
2245   }
2246 }
2247
2248 /**
2249  * gst_element_lost_state_full:
2250  * @element: a #GstElement the state is lost of
2251  * @new_base_time: if a new base time should be distributed
2252  *
2253  * Brings the element to the lost state. The current state of the
2254  * element is copied to the pending state so that any call to
2255  * gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC.
2256  *
2257  * An ASYNC_START message is posted with indication to distribute a new
2258  * base_time to the element when @new_base_time is %TRUE.
2259  * If the element was PLAYING, it will go to PAUSED. The element
2260  * will be restored to its PLAYING state by the parent pipeline when it
2261  * prerolls again.
2262  *
2263  * This is mostly used for elements that lost their preroll buffer
2264  * in the %GST_STATE_PAUSED or %GST_STATE_PLAYING state after a flush,
2265  * they will go to their pending state again when a new preroll buffer is
2266  * queued. This function can only be called when the element is currently
2267  * not in error or an async state change.
2268  *
2269  * This function is used internally and should normally not be called from
2270  * plugins or applications.
2271  *
2272  * MT safe.
2273  *
2274  * Since: 0.10.24
2275  */
2276 void
2277 gst_element_lost_state_full (GstElement * element, gboolean new_base_time)
2278 {
2279   GstState old_state, new_state;
2280   GstMessage *message;
2281
2282   g_return_if_fail (GST_IS_ELEMENT (element));
2283
2284   GST_OBJECT_LOCK (element);
2285   if (GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2286     goto nothing_lost;
2287
2288   if (GST_STATE_PENDING (element) != GST_STATE_VOID_PENDING)
2289     goto only_async_start;
2290
2291   old_state = GST_STATE (element);
2292
2293   /* when we were PLAYING, the new state is PAUSED. We will also not
2294    * automatically go to PLAYING but let the parent bin(s) set us to PLAYING
2295    * when we preroll. */
2296   if (old_state > GST_STATE_PAUSED)
2297     new_state = GST_STATE_PAUSED;
2298   else
2299     new_state = old_state;
2300
2301   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2302       "lost state of %s to %s", gst_element_state_get_name (old_state),
2303       gst_element_state_get_name (new_state));
2304
2305   GST_STATE (element) = new_state;
2306   GST_STATE_NEXT (element) = new_state;
2307   GST_STATE_PENDING (element) = new_state;
2308   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2309   if (new_base_time)
2310     GST_ELEMENT_START_TIME (element) = 0;
2311   GST_OBJECT_UNLOCK (element);
2312
2313   message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2314       new_state, new_state, new_state);
2315   gst_element_post_message (element, message);
2316
2317   message =
2318       gst_message_new_async_start (GST_OBJECT_CAST (element), new_base_time);
2319   gst_element_post_message (element, message);
2320
2321   return;
2322
2323 nothing_lost:
2324   {
2325     GST_OBJECT_UNLOCK (element);
2326     return;
2327   }
2328 only_async_start:
2329   {
2330     GST_OBJECT_UNLOCK (element);
2331
2332     message = gst_message_new_async_start (GST_OBJECT_CAST (element), TRUE);
2333     gst_element_post_message (element, message);
2334     return;
2335   }
2336 }
2337
2338 /**
2339  * gst_element_lost_state:
2340  * @element: a #GstElement the state is lost of
2341  *
2342  * Brings the element to the lost state. This function calls
2343  * gst_element_lost_state_full() with the new_base_time set to %TRUE.
2344  *
2345  * This function is used internally and should normally not be called from
2346  * plugins or applications.
2347  *
2348  * MT safe.
2349  */
2350 void
2351 gst_element_lost_state (GstElement * element)
2352 {
2353   gst_element_lost_state_full (element, TRUE);
2354 }
2355
2356 /**
2357  * gst_element_set_state:
2358  * @element: a #GstElement to change state of.
2359  * @state: the element's new #GstState.
2360  *
2361  * Sets the state of the element. This function will try to set the
2362  * requested state by going through all the intermediary states and calling
2363  * the class's state change function for each.
2364  *
2365  * This function can return #GST_STATE_CHANGE_ASYNC, in which case the
2366  * element will perform the remainder of the state change asynchronously in
2367  * another thread.
2368  * An application can use gst_element_get_state() to wait for the completion
2369  * of the state change or it can wait for a state change message on the bus.
2370  *
2371  * State changes to %GST_STATE_READY or %GST_STATE_NULL never return
2372  * #GST_STATE_CHANGE_ASYNC.
2373  *
2374  * Returns: Result of the state change using #GstStateChangeReturn.
2375  *
2376  * MT safe.
2377  */
2378 GstStateChangeReturn
2379 gst_element_set_state (GstElement * element, GstState state)
2380 {
2381   GstElementClass *oclass;
2382   GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2383
2384   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2385
2386   oclass = GST_ELEMENT_GET_CLASS (element);
2387
2388   if (oclass->set_state)
2389     result = (oclass->set_state) (element, state);
2390
2391   return result;
2392 }
2393
2394 /*
2395  * default set state function, calculates the next state based
2396  * on current state and calls the change_state function
2397  */
2398 static GstStateChangeReturn
2399 gst_element_set_state_func (GstElement * element, GstState state)
2400 {
2401   GstState current, next, old_pending;
2402   GstStateChangeReturn ret;
2403   GstStateChange transition;
2404   GstStateChangeReturn old_ret;
2405
2406   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2407
2408   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "set_state to %s",
2409       gst_element_state_get_name (state));
2410
2411   /* state lock is taken to protect the set_state() and get_state()
2412    * procedures, it does not lock any variables. */
2413   GST_STATE_LOCK (element);
2414
2415   /* now calculate how to get to the new state */
2416   GST_OBJECT_LOCK (element);
2417   old_ret = GST_STATE_RETURN (element);
2418   /* previous state change returned an error, remove all pending
2419    * and next states */
2420   if (old_ret == GST_STATE_CHANGE_FAILURE) {
2421     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2422     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2423     GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
2424   }
2425
2426   current = GST_STATE (element);
2427   next = GST_STATE_NEXT (element);
2428   old_pending = GST_STATE_PENDING (element);
2429
2430   /* this is the (new) state we should go to. TARGET is the last state we set on
2431    * the element. */
2432   if (state != GST_STATE_TARGET (element)) {
2433     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2434         "setting target state to %s", gst_element_state_get_name (state));
2435     GST_STATE_TARGET (element) = state;
2436     /* increment state cookie so that we can track each state change. We only do
2437      * this if this is actually a new state change. */
2438     element->state_cookie++;
2439   }
2440   GST_STATE_PENDING (element) = state;
2441
2442   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2443       "current %s, old_pending %s, next %s, old return %s",
2444       gst_element_state_get_name (current),
2445       gst_element_state_get_name (old_pending),
2446       gst_element_state_get_name (next),
2447       gst_element_state_change_return_get_name (old_ret));
2448
2449   /* if the element was busy doing a state change, we just update the
2450    * target state, it'll get to it async then. */
2451   if (old_pending != GST_STATE_VOID_PENDING) {
2452     /* upwards state change will happen ASYNC */
2453     if (old_pending <= state)
2454       goto was_busy;
2455     /* element is going to this state already */
2456     else if (next == state)
2457       goto was_busy;
2458     /* element was performing an ASYNC upward state change and
2459      * we request to go downward again. Start from the next pending
2460      * state then. */
2461     else if (next > state
2462         && GST_STATE_RETURN (element) == GST_STATE_CHANGE_ASYNC) {
2463       current = next;
2464     }
2465   }
2466   next = GST_STATE_GET_NEXT (current, state);
2467   /* now we store the next state */
2468   GST_STATE_NEXT (element) = next;
2469   /* mark busy, we need to check that there is actually a state change
2470    * to be done else we could accidentally override SUCCESS/NO_PREROLL and
2471    * the default element change_state function has no way to know what the
2472    * old value was... could consider this a FIXME...*/
2473   if (current != next)
2474     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2475
2476   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2477
2478   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2479       "%s: setting state from %s to %s",
2480       (next != state ? "intermediate" : "final"),
2481       gst_element_state_get_name (current), gst_element_state_get_name (next));
2482
2483   /* now signal any waiters, they will error since the cookie was incremented */
2484   GST_STATE_BROADCAST (element);
2485
2486   GST_OBJECT_UNLOCK (element);
2487
2488   ret = gst_element_change_state (element, transition);
2489
2490   GST_STATE_UNLOCK (element);
2491
2492   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "returned %s",
2493       gst_element_state_change_return_get_name (ret));
2494
2495   return ret;
2496
2497 was_busy:
2498   {
2499     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2500     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2501         "element was busy with async state change");
2502     GST_OBJECT_UNLOCK (element);
2503
2504     GST_STATE_UNLOCK (element);
2505
2506     return GST_STATE_CHANGE_ASYNC;
2507   }
2508 }
2509
2510 /**
2511  * gst_element_change_state:
2512  * @element: a #GstElement
2513  * @transition: the requested transition
2514  *
2515  * Perform @transition on @element.
2516  *
2517  * This function must be called with STATE_LOCK held and is mainly used
2518  * internally.
2519  *
2520  * Returns: the #GstStateChangeReturn of the state transition.
2521  */
2522 GstStateChangeReturn
2523 gst_element_change_state (GstElement * element, GstStateChange transition)
2524 {
2525   GstElementClass *oclass;
2526   GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
2527
2528   oclass = GST_ELEMENT_GET_CLASS (element);
2529
2530   /* call the state change function so it can set the state */
2531   if (oclass->change_state)
2532     ret = (oclass->change_state) (element, transition);
2533   else
2534     ret = GST_STATE_CHANGE_FAILURE;
2535
2536   switch (ret) {
2537     case GST_STATE_CHANGE_FAILURE:
2538       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2539           "have FAILURE change_state return");
2540       /* state change failure */
2541       gst_element_abort_state (element);
2542       break;
2543     case GST_STATE_CHANGE_ASYNC:
2544     {
2545       GstState target;
2546
2547       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2548           "element will change state ASYNC");
2549
2550       target = GST_STATE_TARGET (element);
2551
2552       if (target > GST_STATE_READY)
2553         goto async;
2554
2555       /* else we just continue the state change downwards */
2556       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2557           "forcing commit state %s <= %s",
2558           gst_element_state_get_name (target),
2559           gst_element_state_get_name (GST_STATE_READY));
2560
2561       ret = gst_element_continue_state (element, GST_STATE_CHANGE_SUCCESS);
2562       break;
2563     }
2564     case GST_STATE_CHANGE_SUCCESS:
2565       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2566           "element changed state SUCCESS");
2567       /* we can commit the state now which will proceeed to
2568        * the next state */
2569       ret = gst_element_continue_state (element, ret);
2570       break;
2571     case GST_STATE_CHANGE_NO_PREROLL:
2572       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2573           "element changed state NO_PREROLL");
2574       /* we can commit the state now which will proceeed to
2575        * the next state */
2576       ret = gst_element_continue_state (element, ret);
2577       break;
2578     default:
2579       goto invalid_return;
2580   }
2581
2582   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit state change %d", ret);
2583
2584   return ret;
2585
2586 async:
2587   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit async state change %d",
2588       ret);
2589
2590   return ret;
2591
2592   /* ERROR */
2593 invalid_return:
2594   {
2595     GST_OBJECT_LOCK (element);
2596     /* somebody added a GST_STATE_ and forgot to do stuff here ! */
2597     g_critical ("%s: unknown return value %d from a state change function",
2598         GST_ELEMENT_NAME (element), ret);
2599
2600     /* we are in error now */
2601     ret = GST_STATE_CHANGE_FAILURE;
2602     GST_STATE_RETURN (element) = ret;
2603     GST_OBJECT_UNLOCK (element);
2604
2605     return ret;
2606   }
2607 }
2608
2609 /* gst_iterator_fold functions for pads_activate
2610  * Note how we don't stop the iterator when we fail an activation. This is
2611  * probably a FIXME since when one pad activation fails, we don't want to
2612  * continue our state change. */
2613 static gboolean
2614 activate_pads (GstPad * pad, GValue * ret, gboolean * active)
2615 {
2616   if (!gst_pad_set_active (pad, *active))
2617     g_value_set_boolean (ret, FALSE);
2618
2619   /* unref the object that was reffed for us by _fold */
2620   gst_object_unref (pad);
2621   return TRUE;
2622 }
2623
2624 /* set the caps on the pad to NULL */
2625 static gboolean
2626 clear_caps (GstPad * pad, GValue * ret, gboolean * active)
2627 {
2628   gst_pad_set_caps (pad, NULL);
2629   gst_object_unref (pad);
2630   return TRUE;
2631 }
2632
2633 /* returns false on error or early cutout (will never happen because the fold
2634  * function always returns TRUE, see FIXME above) of the fold, true if all
2635  * pads in @iter were (de)activated successfully. */
2636 static gboolean
2637 iterator_activate_fold_with_resync (GstIterator * iter,
2638     GstIteratorFoldFunction func, gpointer user_data)
2639 {
2640   GstIteratorResult ires;
2641   GValue ret = { 0 };
2642
2643   /* no need to unset this later, it's just a boolean */
2644   g_value_init (&ret, G_TYPE_BOOLEAN);
2645   g_value_set_boolean (&ret, TRUE);
2646
2647   while (1) {
2648     ires = gst_iterator_fold (iter, func, &ret, user_data);
2649     switch (ires) {
2650       case GST_ITERATOR_RESYNC:
2651         /* need to reset the result again */
2652         g_value_set_boolean (&ret, TRUE);
2653         gst_iterator_resync (iter);
2654         break;
2655       case GST_ITERATOR_DONE:
2656         /* all pads iterated, return collected value */
2657         goto done;
2658       default:
2659         /* iterator returned _ERROR or premature end with _OK,
2660          * mark an error and exit */
2661         g_value_set_boolean (&ret, FALSE);
2662         goto done;
2663     }
2664   }
2665 done:
2666   /* return collected value */
2667   return g_value_get_boolean (&ret);
2668 }
2669
2670 /* is called with STATE_LOCK
2671  *
2672  * Pads are activated from source pads to sinkpads.
2673  */
2674 static gboolean
2675 gst_element_pads_activate (GstElement * element, gboolean active)
2676 {
2677   GstIterator *iter;
2678   gboolean res;
2679
2680   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2681       "pads_activate with active %d", active);
2682
2683   iter = gst_element_iterate_src_pads (element);
2684   res =
2685       iterator_activate_fold_with_resync (iter,
2686       (GstIteratorFoldFunction) activate_pads, &active);
2687   gst_iterator_free (iter);
2688   if (G_UNLIKELY (!res))
2689     goto src_failed;
2690
2691   iter = gst_element_iterate_sink_pads (element);
2692   res =
2693       iterator_activate_fold_with_resync (iter,
2694       (GstIteratorFoldFunction) activate_pads, &active);
2695   gst_iterator_free (iter);
2696   if (G_UNLIKELY (!res))
2697     goto sink_failed;
2698
2699   if (!active) {
2700     /* clear the caps on all pads, this should never fail */
2701     iter = gst_element_iterate_pads (element);
2702     res =
2703         iterator_activate_fold_with_resync (iter,
2704         (GstIteratorFoldFunction) clear_caps, &active);
2705     gst_iterator_free (iter);
2706     if (G_UNLIKELY (!res))
2707       goto caps_failed;
2708   }
2709
2710   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2711       "pads_activate successful");
2712
2713   return TRUE;
2714
2715   /* ERRORS */
2716 src_failed:
2717   {
2718     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2719         "source pads_activate failed");
2720     return FALSE;
2721   }
2722 sink_failed:
2723   {
2724     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2725         "sink pads_activate failed");
2726     return FALSE;
2727   }
2728 caps_failed:
2729   {
2730     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2731         "failed to clear caps on pads");
2732     return FALSE;
2733   }
2734 }
2735
2736 /* is called with STATE_LOCK */
2737 static GstStateChangeReturn
2738 gst_element_change_state_func (GstElement * element, GstStateChange transition)
2739 {
2740   GstState state, next;
2741   GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
2742   GstClock **clock_p;
2743
2744   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2745
2746   state = (GstState) GST_STATE_TRANSITION_CURRENT (transition);
2747   next = GST_STATE_TRANSITION_NEXT (transition);
2748
2749   /* if the element already is in the given state, we just return success */
2750   if (next == GST_STATE_VOID_PENDING || state == next)
2751     goto was_ok;
2752
2753   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element,
2754       "default handler tries setting state from %s to %s (%04x)",
2755       gst_element_state_get_name (state),
2756       gst_element_state_get_name (next), transition);
2757
2758   switch (transition) {
2759     case GST_STATE_CHANGE_NULL_TO_READY:
2760       break;
2761     case GST_STATE_CHANGE_READY_TO_PAUSED:
2762       if (!gst_element_pads_activate (element, TRUE)) {
2763         result = GST_STATE_CHANGE_FAILURE;
2764       }
2765       break;
2766     case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
2767       break;
2768     case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
2769       break;
2770     case GST_STATE_CHANGE_PAUSED_TO_READY:
2771     case GST_STATE_CHANGE_READY_TO_NULL:
2772       /* deactivate pads in both cases, since they are activated on
2773          ready->paused but the element might not have made it to paused */
2774       if (!gst_element_pads_activate (element, FALSE)) {
2775         result = GST_STATE_CHANGE_FAILURE;
2776       } else {
2777         gst_element_set_base_time (element, 0);
2778       }
2779
2780       /* In null state release the reference to the clock */
2781       GST_OBJECT_LOCK (element);
2782       clock_p = &element->clock;
2783       gst_object_replace ((GstObject **) clock_p, NULL);
2784       GST_OBJECT_UNLOCK (element);
2785       break;
2786     default:
2787       /* this will catch real but unhandled state changes;
2788        * can only be caused by:
2789        * - a new state was added
2790        * - somehow the element was asked to jump across an intermediate state
2791        */
2792       g_warning ("Unhandled state change from %s to %s",
2793           gst_element_state_get_name (state),
2794           gst_element_state_get_name (next));
2795       break;
2796   }
2797   return result;
2798
2799 was_ok:
2800   {
2801     GST_OBJECT_LOCK (element);
2802     result = GST_STATE_RETURN (element);
2803     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2804         "element is already in the %s state",
2805         gst_element_state_get_name (state));
2806     GST_OBJECT_UNLOCK (element);
2807
2808     return result;
2809   }
2810 }
2811
2812 /**
2813  * gst_element_get_factory:
2814  * @element: a #GstElement to request the element factory of.
2815  *
2816  * Retrieves the factory that was used to create this element.
2817  *
2818  * Returns: the #GstElementFactory used for creating this element.
2819  * no refcounting is needed.
2820  */
2821 GstElementFactory *
2822 gst_element_get_factory (GstElement * element)
2823 {
2824   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
2825
2826   return GST_ELEMENT_GET_CLASS (element)->elementfactory;
2827 }
2828
2829 static void
2830 gst_element_dispose (GObject * object)
2831 {
2832   GstElement *element = GST_ELEMENT_CAST (object);
2833   GstClock **clock_p;
2834   GstBus **bus_p;
2835
2836   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "dispose");
2837
2838   if (GST_STATE (element) != GST_STATE_NULL)
2839     goto not_null;
2840
2841   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2842       "removing %d pads", g_list_length (element->pads));
2843   /* first we break all our links with the outside */
2844   while (element->pads && element->pads->data) {
2845     /* don't call _remove_pad with NULL */
2846     gst_element_remove_pad (element, GST_PAD_CAST (element->pads->data));
2847   }
2848   if (G_UNLIKELY (element->pads != NULL)) {
2849     g_critical ("could not remove pads from element %s",
2850         GST_STR_NULL (GST_OBJECT_NAME (object)));
2851   }
2852
2853   GST_OBJECT_LOCK (element);
2854   clock_p = &element->clock;
2855   bus_p = &element->bus;
2856   gst_object_replace ((GstObject **) clock_p, NULL);
2857   gst_object_replace ((GstObject **) bus_p, NULL);
2858   GST_OBJECT_UNLOCK (element);
2859
2860   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "parent class dispose");
2861
2862   G_OBJECT_CLASS (parent_class)->dispose (object);
2863
2864   return;
2865
2866   /* ERRORS */
2867 not_null:
2868   {
2869     gboolean is_locked;
2870
2871     is_locked = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
2872     g_critical
2873         ("\nTrying to dispose element %s, but it is in %s%s instead of the NULL"
2874         " state.\n"
2875         "You need to explicitly set elements to the NULL state before\n"
2876         "dropping the final reference, to allow them to clean up.\n"
2877         "This problem may also be caused by a refcounting bug in the\n"
2878         "application or some element.\n",
2879         GST_OBJECT_NAME (element),
2880         gst_element_state_get_name (GST_STATE (element)),
2881         is_locked ? " (locked)" : "");
2882     return;
2883   }
2884 }
2885
2886 static void
2887 gst_element_finalize (GObject * object)
2888 {
2889   GstElement *element = GST_ELEMENT_CAST (object);
2890
2891   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize");
2892
2893   GST_STATE_LOCK (element);
2894   if (element->state_cond)
2895     g_cond_free (element->state_cond);
2896   element->state_cond = NULL;
2897   GST_STATE_UNLOCK (element);
2898   g_static_rec_mutex_free (element->state_lock);
2899   g_slice_free (GStaticRecMutex, element->state_lock);
2900   element->state_lock = NULL;
2901
2902   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize parent");
2903
2904   G_OBJECT_CLASS (parent_class)->finalize (object);
2905 }
2906
2907 #ifndef GST_DISABLE_LOADSAVE
2908 /**
2909  * gst_element_save_thyself:
2910  * @element: a #GstElement to save.
2911  * @parent: the xml parent node.
2912  *
2913  * Saves the element as part of the given XML structure.
2914  *
2915  * Returns: the new #xmlNodePtr.
2916  */
2917 static xmlNodePtr
2918 gst_element_save_thyself (GstObject * object, xmlNodePtr parent)
2919 {
2920   GList *pads;
2921   GstElementClass *oclass;
2922   GParamSpec **specs, *spec;
2923   guint nspecs;
2924   guint i;
2925   GValue value = { 0, };
2926   GstElement *element;
2927
2928   g_return_val_if_fail (GST_IS_ELEMENT (object), parent);
2929
2930   element = GST_ELEMENT_CAST (object);
2931
2932   oclass = GST_ELEMENT_GET_CLASS (element);
2933
2934   xmlNewChild (parent, NULL, (xmlChar *) "name",
2935       (xmlChar *) GST_ELEMENT_NAME (element));
2936
2937   if (oclass->elementfactory != NULL) {
2938     GstElementFactory *factory = (GstElementFactory *) oclass->elementfactory;
2939
2940     xmlNewChild (parent, NULL, (xmlChar *) "type",
2941         (xmlChar *) GST_PLUGIN_FEATURE (factory)->name);
2942   }
2943
2944   /* params */
2945   specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (object), &nspecs);
2946
2947   for (i = 0; i < nspecs; i++) {
2948     spec = specs[i];
2949     if (spec->flags & G_PARAM_READABLE) {
2950       xmlNodePtr param;
2951       char *contents;
2952
2953       g_value_init (&value, spec->value_type);
2954
2955       g_object_get_property (G_OBJECT (element), spec->name, &value);
2956       param = xmlNewChild (parent, NULL, (xmlChar *) "param", NULL);
2957       xmlNewChild (param, NULL, (xmlChar *) "name", (xmlChar *) spec->name);
2958
2959       if (G_IS_PARAM_SPEC_STRING (spec))
2960         contents = g_value_dup_string (&value);
2961       else if (G_IS_PARAM_SPEC_ENUM (spec))
2962         contents = g_strdup_printf ("%d", g_value_get_enum (&value));
2963       else if (G_IS_PARAM_SPEC_INT64 (spec))
2964         contents = g_strdup_printf ("%" G_GINT64_FORMAT,
2965             g_value_get_int64 (&value));
2966       else if (GST_VALUE_HOLDS_STRUCTURE (&value)) {
2967         if (g_value_get_boxed (&value) != NULL) {
2968           contents = g_strdup_value_contents (&value);
2969         } else {
2970           contents = g_strdup ("NULL");
2971         }
2972       } else
2973         contents = g_strdup_value_contents (&value);
2974
2975       xmlNewChild (param, NULL, (xmlChar *) "value", (xmlChar *) contents);
2976       g_free (contents);
2977
2978       g_value_unset (&value);
2979     }
2980   }
2981
2982   g_free (specs);
2983
2984   pads = g_list_last (GST_ELEMENT_PADS (element));
2985
2986   while (pads) {
2987     GstPad *pad = GST_PAD_CAST (pads->data);
2988
2989     /* figure out if it's a direct pad or a ghostpad */
2990     if (GST_ELEMENT_CAST (GST_OBJECT_PARENT (pad)) == element) {
2991       xmlNodePtr padtag = xmlNewChild (parent, NULL, (xmlChar *) "pad", NULL);
2992
2993       gst_object_save_thyself (GST_OBJECT_CAST (pad), padtag);
2994     }
2995     pads = g_list_previous (pads);
2996   }
2997
2998   return parent;
2999 }
3000
3001 static void
3002 gst_element_restore_thyself (GstObject * object, xmlNodePtr self)
3003 {
3004   xmlNodePtr children;
3005   GstElement *element;
3006   gchar *name = NULL;
3007   gchar *value = NULL;
3008
3009   element = GST_ELEMENT_CAST (object);
3010   g_return_if_fail (element != NULL);
3011
3012   /* parameters */
3013   children = self->xmlChildrenNode;
3014   while (children) {
3015     if (!strcmp ((char *) children->name, "param")) {
3016       xmlNodePtr child = children->xmlChildrenNode;
3017
3018       while (child) {
3019         if (!strcmp ((char *) child->name, "name")) {
3020           name = (gchar *) xmlNodeGetContent (child);
3021         } else if (!strcmp ((char *) child->name, "value")) {
3022           value = (gchar *) xmlNodeGetContent (child);
3023         }
3024         child = child->next;
3025       }
3026       /* FIXME: can this just be g_object_set ? */
3027       gst_util_set_object_arg (G_OBJECT (element), name, value);
3028       /* g_object_set (G_OBJECT (element), name, value, NULL); */
3029       g_free (name);
3030       g_free (value);
3031     }
3032     children = children->next;
3033   }
3034
3035   /* pads */
3036   children = self->xmlChildrenNode;
3037   while (children) {
3038     if (!strcmp ((char *) children->name, "pad")) {
3039       gst_pad_load_and_link (children, GST_OBJECT_CAST (element));
3040     }
3041     children = children->next;
3042   }
3043
3044   if (GST_OBJECT_CLASS (parent_class)->restore_thyself)
3045     (GST_OBJECT_CLASS (parent_class)->restore_thyself) (object, self);
3046 }
3047 #endif /* GST_DISABLE_LOADSAVE */
3048
3049 static void
3050 gst_element_set_bus_func (GstElement * element, GstBus * bus)
3051 {
3052   GstBus **bus_p;
3053
3054   g_return_if_fail (GST_IS_ELEMENT (element));
3055
3056   GST_CAT_DEBUG_OBJECT (GST_CAT_PARENTAGE, element, "setting bus to %p", bus);
3057
3058   GST_OBJECT_LOCK (element);
3059   bus_p = &GST_ELEMENT_BUS (element);
3060   gst_object_replace ((GstObject **) bus_p, GST_OBJECT_CAST (bus));
3061   GST_OBJECT_UNLOCK (element);
3062 }
3063
3064 /**
3065  * gst_element_set_bus:
3066  * @element: a #GstElement to set the bus of.
3067  * @bus: the #GstBus to set.
3068  *
3069  * Sets the bus of the element. Increases the refcount on the bus.
3070  * For internal use only, unless you're testing elements.
3071  *
3072  * MT safe.
3073  */
3074 void
3075 gst_element_set_bus (GstElement * element, GstBus * bus)
3076 {
3077   GstElementClass *oclass;
3078
3079   g_return_if_fail (GST_IS_ELEMENT (element));
3080
3081   oclass = GST_ELEMENT_GET_CLASS (element);
3082
3083   if (oclass->set_bus)
3084     oclass->set_bus (element, bus);
3085 }
3086
3087 /**
3088  * gst_element_get_bus:
3089  * @element: a #GstElement to get the bus of.
3090  *
3091  * Returns the bus of the element. Note that only a #GstPipeline will provide a
3092  * bus for the application.
3093  *
3094  * Returns: the element's #GstBus. unref after usage.
3095  *
3096  * MT safe.
3097  */
3098 GstBus *
3099 gst_element_get_bus (GstElement * element)
3100 {
3101   GstBus *result = NULL;
3102
3103   g_return_val_if_fail (GST_IS_ELEMENT (element), result);
3104
3105   GST_OBJECT_LOCK (element);
3106   if ((result = GST_ELEMENT_BUS (element)))
3107     gst_object_ref (result);
3108   GST_OBJECT_UNLOCK (element);
3109
3110   GST_CAT_DEBUG_OBJECT (GST_CAT_BUS, element, "got bus %" GST_PTR_FORMAT,
3111       result);
3112
3113   return result;
3114 }