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