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