gst/gstelement.c

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