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