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