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