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