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