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