gst/gstelement.c

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