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