gst/gstelement.c

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