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