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