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