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