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