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_prepend (element->srcpads, pad);
 672       element->numsrcpads++;
 673       break;
 674     case GST_PAD_SINK:
 675       element->sinkpads = g_list_prepend (element->sinkpads, pad);
 676       element->numsinkpads++;
 677       break;
 678     default:
 679       goto no_direction;
 680   }
 681   element->pads = g_list_prepend (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  * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1118  *     after use.
1119  *
1120  * MT safe.
1121  */
1122 GstIterator *
1123 gst_element_iterate_pads (GstElement * element)
1124 {
1125   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1126
1127   return gst_element_iterate_pad_list (element, &element->pads);
1128 }
1129
1130 /**
1131  * gst_element_iterate_src_pads:
1132  * @element: a #GstElement.
1133  *
1134  * Retrieves an iterator of @element's source pads.
1135  *
1136  * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1137  *     after use.
1138  *
1139  * MT safe.
1140  */
1141 GstIterator *
1142 gst_element_iterate_src_pads (GstElement * element)
1143 {
1144   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1145
1146   return gst_element_iterate_pad_list (element, &element->srcpads);
1147 }
1148
1149 /**
1150  * gst_element_iterate_sink_pads:
1151  * @element: a #GstElement.
1152  *
1153  * Retrieves an iterator of @element's sink pads.
1154  *
1155  * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1156  *     after use.
1157  *
1158  * MT safe.
1159  */
1160 GstIterator *
1161 gst_element_iterate_sink_pads (GstElement * element)
1162 {
1163   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1164
1165   return gst_element_iterate_pad_list (element, &element->sinkpads);
1166 }
1167
1168 /**
1169  * gst_element_class_add_pad_template:
1170  * @klass: the #GstElementClass to add the pad template to.
1171  * @templ: (transfer full): a #GstPadTemplate to add to the element class.
1172  *
1173  * Adds a padtemplate to an element class. This is mainly used in the _class_init
1174  * functions of classes. If a pad template with the same name as an already
1175  * existing one is added the old one is replaced by the new one.
1176  *
1177  */
1178 void
1179 gst_element_class_add_pad_template (GstElementClass * klass,
1180     GstPadTemplate * templ)
1181 {
1182   GList *template_list = klass->padtemplates;
1183
1184   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1185   g_return_if_fail (GST_IS_PAD_TEMPLATE (templ));
1186
1187   /* If we already have a pad template with the same name replace the
1188    * old one. */
1189   while (template_list) {
1190     GstPadTemplate *padtempl = (GstPadTemplate *) template_list->data;
1191
1192     /* Found pad with the same name, replace and return */
1193     if (strcmp (templ->name_template, padtempl->name_template) == 0) {
1194       gst_object_unref (padtempl);
1195       template_list->data = templ;
1196       return;
1197     }
1198     template_list = g_list_next (template_list);
1199   }
1200
1201   /* Take ownership of the floating ref */
1202   gst_object_ref_sink (templ);
1203
1204   klass->padtemplates = g_list_append (klass->padtemplates, templ);
1205   klass->numpadtemplates++;
1206 }
1207
1208 /**
1209  * gst_element_class_add_metadata:
1210  * @klass: class to set metadata for
1211  * @key: the key to set
1212  * @value: the value to set
1213  *
1214  * Set @key with @value as metadata in @klass.
1215  */
1216 void
1217 gst_element_class_add_metadata (GstElementClass * klass,
1218     const gchar * key, const gchar * value)
1219 {
1220   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1221   g_return_if_fail (key != NULL);
1222   g_return_if_fail (value != NULL);
1223
1224   gst_structure_set ((GstStructure *) klass->metadata,
1225       key, G_TYPE_STRING, value, NULL);
1226 }
1227
1228 /**
1229  * gst_element_class_add_static_metadata:
1230  * @klass: class to set metadata for
1231  * @key: the key to set
1232  * @value: the value to set
1233  *
1234  * Set @key with @value as metadata in @klass.
1235  *
1236  * Same as gst_element_class_add_metadata(), but @value must be a static string
1237  * or an inlined string, as it will not be copied. (GStreamer plugins will
1238  * be made resident once loaded, so this function can be used even from
1239  * dynamically loaded plugins.)
1240  */
1241 void
1242 gst_element_class_add_static_metadata (GstElementClass * klass,
1243     const gchar * key, const gchar * value)
1244 {
1245   GValue val = G_VALUE_INIT;
1246
1247   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1248   g_return_if_fail (key != NULL);
1249   g_return_if_fail (value != NULL);
1250
1251   g_value_init (&val, G_TYPE_STRING);
1252   g_value_set_static_string (&val, value);
1253   gst_structure_take_value ((GstStructure *) klass->metadata, key, &val);
1254 }
1255
1256 /**
1257  * gst_element_class_set_metadata:
1258  * @klass: class to set metadata for
1259  * @longname: The long English name of the element. E.g. "File Sink"
1260  * @classification: String describing the type of element, as an unordered list
1261  * separated with slashes ('/'). See draft-klass.txt of the design docs
1262  * for more details and common types. E.g: "Sink/File"
1263  * @description: Sentence describing the purpose of the element.
1264  * E.g: "Write stream to a file"
1265  * @author: Name and contact details of the author(s). Use \n to separate
1266  * multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
1267  *
1268  * Sets the detailed information for a #GstElementClass.
1269  * <note>This function is for use in _class_init functions only.</note>
1270  */
1271 void
1272 gst_element_class_set_metadata (GstElementClass * klass,
1273     const gchar * longname, const gchar * classification,
1274     const gchar * description, const gchar * author)
1275 {
1276   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1277
1278   gst_structure_id_set ((GstStructure *) klass->metadata,
1279       GST_QUARK (ELEMENT_METADATA_LONGNAME), G_TYPE_STRING, longname,
1280       GST_QUARK (ELEMENT_METADATA_KLASS), G_TYPE_STRING, classification,
1281       GST_QUARK (ELEMENT_METADATA_DESCRIPTION), G_TYPE_STRING, description,
1282       GST_QUARK (ELEMENT_METADATA_AUTHOR), G_TYPE_STRING, author, NULL);
1283 }
1284
1285 /**
1286  * gst_element_class_set_static_metadata:
1287  * @klass: class to set metadata for
1288  * @longname: The long English name of the element. E.g. "File Sink"
1289  * @classification: String describing the type of element, as an unordered list
1290  * separated with slashes ('/'). See draft-klass.txt of the design docs
1291  * for more details and common types. E.g: "Sink/File"
1292  * @description: Sentence describing the purpose of the element.
1293  * E.g: "Write stream to a file"
1294  * @author: Name and contact details of the author(s). Use \n to separate
1295  * multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
1296  *
1297  * Sets the detailed information for a #GstElementClass.
1298  * <note>This function is for use in _class_init functions only.</note>
1299  *
1300  * Same as gst_element_class_set_metadata(), but @longname, @classification,
1301  * @description, and @author must be static strings or inlined strings, as
1302  * they will not be copied. (GStreamer plugins will be made resident once
1303  * loaded, so this function can be used even from dynamically loaded plugins.)
1304  */
1305 void
1306 gst_element_class_set_static_metadata (GstElementClass * klass,
1307     const gchar * longname, const gchar * classification,
1308     const gchar * description, const gchar * author)
1309 {
1310   GstStructure *s = (GstStructure *) klass->metadata;
1311   GValue val = G_VALUE_INIT;
1312
1313   g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1314
1315   g_value_init (&val, G_TYPE_STRING);
1316
1317   g_value_set_static_string (&val, longname);
1318   gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_LONGNAME), &val);
1319
1320   g_value_set_static_string (&val, classification);
1321   gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_KLASS), &val);
1322
1323   g_value_set_static_string (&val, description);
1324   gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_DESCRIPTION),
1325       &val);
1326
1327   g_value_set_static_string (&val, author);
1328   gst_structure_id_take_value (s, GST_QUARK (ELEMENT_METADATA_AUTHOR), &val);
1329 }
1330
1331 /**
1332  * gst_element_class_get_metadata:
1333  * @klass: class to get metadata for
1334  * @key: the key to get
1335  *
1336  * Get metadata with @key in @klass.
1337  *
1338  * Returns: the metadata for @key.
1339  */
1340 const gchar *
1341 gst_element_class_get_metadata (GstElementClass * klass, const gchar * key)
1342 {
1343   g_return_val_if_fail (GST_IS_ELEMENT_CLASS (klass), NULL);
1344   g_return_val_if_fail (key != NULL, NULL);
1345
1346   return gst_structure_get_string ((GstStructure *) klass->metadata, key);
1347 }
1348
1349 /**
1350  * gst_element_class_get_pad_template_list:
1351  * @element_class: a #GstElementClass to get pad templates of.
1352  *
1353  * Retrieves a list of the pad templates associated with @element_class. The
1354  * list must not be modified by the calling code.
1355  * <note>If you use this function in the #GInstanceInitFunc of an object class
1356  * that has subclasses, make sure to pass the g_class parameter of the
1357  * #GInstanceInitFunc here.</note>
1358  *
1359  * Returns: (transfer none) (element-type Gst.PadTemplate): the #GList of
1360  *     pad templates.
1361  */
1362 GList *
1363 gst_element_class_get_pad_template_list (GstElementClass * element_class)
1364 {
1365   g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1366
1367   return element_class->padtemplates;
1368 }
1369
1370 /**
1371  * gst_element_class_get_pad_template:
1372  * @element_class: a #GstElementClass to get the pad template of.
1373  * @name: the name of the #GstPadTemplate to get.
1374  *
1375  * Retrieves a padtemplate from @element_class with the given name.
1376  * <note>If you use this function in the #GInstanceInitFunc of an object class
1377  * that has subclasses, make sure to pass the g_class parameter of the
1378  * #GInstanceInitFunc here.</note>
1379  *
1380  * Returns: (transfer none): the #GstPadTemplate with the given name, or %NULL
1381  *     if none was found. No unreferencing is necessary.
1382  */
1383 GstPadTemplate *
1384 gst_element_class_get_pad_template (GstElementClass *
1385     element_class, const gchar * name)
1386 {
1387   GList *padlist;
1388
1389   g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1390   g_return_val_if_fail (name != NULL, NULL);
1391
1392   padlist = element_class->padtemplates;
1393
1394   while (padlist) {
1395     GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
1396
1397     if (strcmp (padtempl->name_template, name) == 0)
1398       return padtempl;
1399
1400     padlist = g_list_next (padlist);
1401   }
1402
1403   return NULL;
1404 }
1405
1406 static GstPadTemplate *
1407 gst_element_class_get_request_pad_template (GstElementClass *
1408     element_class, const gchar * name)
1409 {
1410   GstPadTemplate *tmpl;
1411
1412   tmpl = gst_element_class_get_pad_template (element_class, name);
1413   if (tmpl != NULL && tmpl->presence == GST_PAD_REQUEST)
1414     return tmpl;
1415
1416   return NULL;
1417 }
1418
1419 /* get a random pad on element of the given direction.
1420  * The pad is random in a sense that it is the first pad that is (optionaly) linked.
1421  */
1422 static GstPad *
1423 gst_element_get_random_pad (GstElement * element,
1424     gboolean need_linked, GstPadDirection dir)
1425 {
1426   GstPad *result = NULL;
1427   GList *pads;
1428
1429   GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "getting a random pad");
1430
1431   switch (dir) {
1432     case GST_PAD_SRC:
1433       GST_OBJECT_LOCK (element);
1434       pads = element->srcpads;
1435       break;
1436     case GST_PAD_SINK:
1437       GST_OBJECT_LOCK (element);
1438       pads = element->sinkpads;
1439       break;
1440     default:
1441       goto wrong_direction;
1442   }
1443   for (; pads; pads = g_list_next (pads)) {
1444     GstPad *pad = GST_PAD_CAST (pads->data);
1445
1446     GST_OBJECT_LOCK (pad);
1447     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "checking pad %s:%s",
1448         GST_DEBUG_PAD_NAME (pad));
1449
1450     if (need_linked && !GST_PAD_IS_LINKED (pad)) {
1451       /* if we require a linked pad, and it is not linked, continue the
1452        * search */
1453       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is not linked",
1454           GST_DEBUG_PAD_NAME (pad));
1455       GST_OBJECT_UNLOCK (pad);
1456       continue;
1457     } else {
1458       /* found a pad, stop search */
1459       GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
1460           GST_DEBUG_PAD_NAME (pad));
1461       GST_OBJECT_UNLOCK (pad);
1462       result = pad;
1463       break;
1464     }
1465   }
1466   if (result)
1467     gst_object_ref (result);
1468
1469   GST_OBJECT_UNLOCK (element);
1470
1471   return result;
1472
1473   /* ERROR handling */
1474 wrong_direction:
1475   {
1476     g_warning ("unknown pad direction %d", dir);
1477     return NULL;
1478   }
1479 }
1480
1481 static gboolean
1482 gst_element_default_send_event (GstElement * element, GstEvent * event)
1483 {
1484   gboolean result = FALSE;
1485   GstPad *pad;
1486
1487   pad = GST_EVENT_IS_DOWNSTREAM (event) ?
1488       gst_element_get_random_pad (element, TRUE, GST_PAD_SRC) :
1489       gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1490
1491   if (pad) {
1492     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1493         "pushing %s event to random %s pad %s:%s",
1494         GST_EVENT_TYPE_NAME (event),
1495         (GST_PAD_DIRECTION (pad) == GST_PAD_SRC ? "src" : "sink"),
1496         GST_DEBUG_PAD_NAME (pad));
1497
1498     result = gst_pad_push_event (pad, event);
1499     gst_object_unref (pad);
1500   } else {
1501     GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "can't send %s event on element %s",
1502         GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1503     gst_event_unref (event);
1504   }
1505   return result;
1506 }
1507
1508 /**
1509  * gst_element_send_event:
1510  * @element: a #GstElement to send the event to.
1511  * @event: (transfer full): the #GstEvent to send to the element.
1512  *
1513  * Sends an event to an element. If the element doesn't implement an
1514  * event handler, the event will be pushed on a random linked sink pad for
1515  * upstream events or a random linked source pad for downstream events.
1516  *
1517  * This function takes owership of the provided event so you should
1518  * gst_event_ref() it if you want to reuse the event after this call.
1519  *
1520  * MT safe.
1521  *
1522  * Returns: %TRUE if the event was handled. Events that trigger a preroll (such
1523  * as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE.
1524  */
1525 gboolean
1526 gst_element_send_event (GstElement * element, GstEvent * event)
1527 {
1528   GstElementClass *oclass;
1529   gboolean result = FALSE;
1530
1531   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1532   g_return_val_if_fail (event != NULL, FALSE);
1533
1534   oclass = GST_ELEMENT_GET_CLASS (element);
1535
1536   GST_STATE_LOCK (element);
1537   if (oclass->send_event) {
1538     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send %s event on element %s",
1539         GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1540     result = oclass->send_event (element, event);
1541   }
1542   GST_STATE_UNLOCK (element);
1543
1544   return result;
1545 }
1546
1547 /**
1548  * gst_element_seek:
1549  * @element: a #GstElement to send the event to.
1550  * @rate: The new playback rate
1551  * @format: The format of the seek values
1552  * @flags: The optional seek flags.
1553  * @start_type: The type and flags for the new start position
1554  * @start: The value of the new start position
1555  * @stop_type: The type and flags for the new stop position
1556  * @stop: The value of the new stop position
1557  *
1558  * Sends a seek event to an element. See gst_event_new_seek() for the details of
1559  * the parameters. The seek event is sent to the element using
1560  * gst_element_send_event().
1561  *
1562  * MT safe.
1563  *
1564  * Returns: %TRUE if the event was handled. Flushing seeks will trigger a
1565  * preroll, which will emit %GST_MESSAGE_ASYNC_DONE.
1566  */
1567 gboolean
1568 gst_element_seek (GstElement * element, gdouble rate, GstFormat format,
1569     GstSeekFlags flags, GstSeekType start_type, gint64 start,
1570     GstSeekType stop_type, gint64 stop)
1571 {
1572   GstEvent *event;
1573   gboolean result;
1574
1575   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1576
1577   event =
1578       gst_event_new_seek (rate, format, flags, start_type, start, stop_type,
1579       stop);
1580   result = gst_element_send_event (element, event);
1581
1582   return result;
1583 }
1584
1585 static gboolean
1586 gst_element_default_query (GstElement * element, GstQuery * query)
1587 {
1588   gboolean result = FALSE;
1589   GstPad *pad;
1590
1591   pad = gst_element_get_random_pad (element, FALSE, GST_PAD_SRC);
1592   if (pad) {
1593     result = gst_pad_query (pad, query);
1594
1595     gst_object_unref (pad);
1596   } else {
1597     pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1598     if (pad) {
1599       GstPad *peer = gst_pad_get_peer (pad);
1600
1601       if (peer) {
1602         result = gst_pad_query (peer, query);
1603
1604         gst_object_unref (peer);
1605       }
1606       gst_object_unref (pad);
1607     }
1608   }
1609   return result;
1610 }
1611
1612 /**
1613  * gst_element_query:
1614  * @element: a #GstElement to perform the query on.
1615  * @query: (transfer none): the #GstQuery.
1616  *
1617  * Performs a query on the given element.
1618  *
1619  * For elements that don't implement a query handler, this function
1620  * forwards the query to a random srcpad or to the peer of a
1621  * random linked sinkpad of this element.
1622  *
1623  * Please note that some queries might need a running pipeline to work.
1624  *
1625  * Returns: TRUE if the query could be performed.
1626  *
1627  * MT safe.
1628  */
1629 gboolean
1630 gst_element_query (GstElement * element, GstQuery * query)
1631 {
1632   GstElementClass *oclass;
1633   gboolean result = FALSE;
1634
1635   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1636   g_return_val_if_fail (query != NULL, FALSE);
1637
1638   oclass = GST_ELEMENT_GET_CLASS (element);
1639
1640   if (oclass->query) {
1641     GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send query on element %s",
1642         GST_ELEMENT_NAME (element));
1643     result = oclass->query (element, query);
1644   }
1645   return result;
1646 }
1647
1648 /**
1649  * gst_element_post_message:
1650  * @element: a #GstElement posting the message
1651  * @message: (transfer full): a #GstMessage to post
1652  *
1653  * Post a message on the element's #GstBus. This function takes ownership of the
1654  * message; if you want to access the message after this call, you should add an
1655  * additional reference before calling.
1656  *
1657  * Returns: %TRUE if the message was successfully posted. The function returns
1658  * %FALSE if the element did not have a bus.
1659  *
1660  * MT safe.
1661  */
1662 gboolean
1663 gst_element_post_message (GstElement * element, GstMessage * message)
1664 {
1665   GstBus *bus;
1666   gboolean result = FALSE;
1667
1668   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1669   g_return_val_if_fail (message != NULL, FALSE);
1670
1671   GST_OBJECT_LOCK (element);
1672   bus = element->bus;
1673
1674   if (G_UNLIKELY (bus == NULL))
1675     goto no_bus;
1676
1677   gst_object_ref (bus);
1678   GST_OBJECT_UNLOCK (element);
1679
1680   /* we release the element lock when posting the message so that any
1681    * (synchronous) message handlers can operate on the element */
1682   result = gst_bus_post (bus, message);
1683   gst_object_unref (bus);
1684
1685   return result;
1686
1687   /* ERRORS */
1688 no_bus:
1689   {
1690     GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element,
1691         "not posting message %p: no bus", message);
1692     GST_OBJECT_UNLOCK (element);
1693     gst_message_unref (message);
1694     return FALSE;
1695   }
1696 }
1697
1698 /**
1699  * _gst_element_error_printf:
1700  * @format: the printf-like format to use, or %NULL
1701  *
1702  * This function is only used internally by the gst_element_error() macro.
1703  *
1704  * Returns: (transfer full): a newly allocated string, or %NULL if the format
1705  *     was %NULL or ""
1706  *
1707  * MT safe.
1708  */
1709 gchar *
1710 _gst_element_error_printf (const gchar * format, ...)
1711 {
1712   va_list args;
1713   gchar *buffer;
1714
1715   if (format == NULL)
1716     return NULL;
1717   if (format[0] == 0)
1718     return NULL;
1719
1720   va_start (args, format);
1721   buffer = g_strdup_vprintf (format, args);
1722   va_end (args);
1723   return buffer;
1724 }
1725
1726 /**
1727  * gst_element_message_full:
1728  * @element:  a #GstElement to send message from
1729  * @type:     the #GstMessageType
1730  * @domain:   the GStreamer GError domain this message belongs to
1731  * @code:     the GError code belonging to the domain
1732  * @text:     (allow-none) (transfer full): an allocated text string to be used
1733  *            as a replacement for the default message connected to code,
1734  *            or %NULL
1735  * @debug:    (allow-none) (transfer full): an allocated debug message to be
1736  *            used as a replacement for the default debugging information,
1737  *            or %NULL
1738  * @file:     the source code file where the error was generated
1739  * @function: the source code function where the error was generated
1740  * @line:     the source code line where the error was generated
1741  *
1742  * Post an error, warning or info message on the bus from inside an element.
1743  *
1744  * @type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or
1745  * #GST_MESSAGE_INFO.
1746  *
1747  * MT safe.
1748  */
1749 void gst_element_message_full
1750     (GstElement * element, GstMessageType type,
1751     GQuark domain, gint code, gchar * text,
1752     gchar * debug, const gchar * file, const gchar * function, gint line)
1753 {
1754   GError *gerror = NULL;
1755   gchar *name;
1756   gchar *sent_text;
1757   gchar *sent_debug;
1758   gboolean has_debug = TRUE;
1759   GstMessage *message = NULL;
1760
1761   /* checks */
1762   GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element, "start");
1763   g_return_if_fail (GST_IS_ELEMENT (element));
1764   g_return_if_fail ((type == GST_MESSAGE_ERROR) ||
1765       (type == GST_MESSAGE_WARNING) || (type == GST_MESSAGE_INFO));
1766
1767   /* check if we send the given text or the default error text */
1768   if ((text == NULL) || (text[0] == 0)) {
1769     /* text could have come from g_strdup_printf (""); */
1770     g_free (text);
1771     sent_text = gst_error_get_message (domain, code);
1772   } else
1773     sent_text = text;
1774
1775   /* construct a sent_debug with extra information from source */
1776   if ((debug == NULL) || (debug[0] == 0)) {
1777     /* debug could have come from g_strdup_printf (""); */
1778     has_debug = FALSE;
1779   }
1780
1781   name = gst_object_get_path_string (GST_OBJECT_CAST (element));
1782   if (has_debug)
1783     sent_debug = g_strdup_printf ("%s(%d): %s (): %s:\n%s",
1784         file, line, function, name, debug);
1785   else
1786     sent_debug = g_strdup_printf ("%s(%d): %s (): %s",
1787         file, line, function, name);
1788   g_free (name);
1789   g_free (debug);
1790
1791   /* create gerror and post message */
1792   GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posting message: %s",
1793       sent_text);
1794   gerror = g_error_new_literal (domain, code, sent_text);
1795
1796   switch (type) {
1797     case GST_MESSAGE_ERROR:
1798       message =
1799           gst_message_new_error (GST_OBJECT_CAST (element), gerror, sent_debug);
1800       break;
1801     case GST_MESSAGE_WARNING:
1802       message = gst_message_new_warning (GST_OBJECT_CAST (element), gerror,
1803           sent_debug);
1804       break;
1805     case GST_MESSAGE_INFO:
1806       message = gst_message_new_info (GST_OBJECT_CAST (element), gerror,
1807           sent_debug);
1808       break;
1809     default:
1810       g_assert_not_reached ();
1811       break;
1812   }
1813   gst_element_post_message (element, message);
1814
1815   GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posted %s message: %s",
1816       (type == GST_MESSAGE_ERROR ? "error" : "warning"), sent_text);
1817
1818   /* cleanup */
1819   g_error_free (gerror);
1820   g_free (sent_debug);
1821   g_free (sent_text);
1822 }
1823
1824 /**
1825  * gst_element_is_locked_state:
1826  * @element: a #GstElement.
1827  *
1828  * Checks if the state of an element is locked.
1829  * If the state of an element is locked, state changes of the parent don't
1830  * affect the element.
1831  * This way you can leave currently unused elements inside bins. Just lock their
1832  * state before changing the state from #GST_STATE_NULL.
1833  *
1834  * MT safe.
1835  *
1836  * Returns: TRUE, if the element's state is locked.
1837  */
1838 gboolean
1839 gst_element_is_locked_state (GstElement * element)
1840 {
1841   gboolean result;
1842
1843   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1844
1845   GST_OBJECT_LOCK (element);
1846   result = GST_ELEMENT_IS_LOCKED_STATE (element);
1847   GST_OBJECT_UNLOCK (element);
1848
1849   return result;
1850 }
1851
1852 /**
1853  * gst_element_set_locked_state:
1854  * @element: a #GstElement
1855  * @locked_state: TRUE to lock the element's state
1856  *
1857  * Locks the state of an element, so state changes of the parent don't affect
1858  * this element anymore.
1859  *
1860  * MT safe.
1861  *
1862  * Returns: TRUE if the state was changed, FALSE if bad parameters were given
1863  * or the elements state-locking needed no change.
1864  */
1865 gboolean
1866 gst_element_set_locked_state (GstElement * element, gboolean locked_state)
1867 {
1868   gboolean old;
1869
1870   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1871
1872   GST_OBJECT_LOCK (element);
1873   old = GST_ELEMENT_IS_LOCKED_STATE (element);
1874
1875   if (G_UNLIKELY (old == locked_state))
1876     goto was_ok;
1877
1878   if (locked_state) {
1879     GST_CAT_DEBUG (GST_CAT_STATES, "locking state of element %s",
1880         GST_ELEMENT_NAME (element));
1881     GST_OBJECT_FLAG_SET (element, GST_ELEMENT_FLAG_LOCKED_STATE);
1882   } else {
1883     GST_CAT_DEBUG (GST_CAT_STATES, "unlocking state of element %s",
1884         GST_ELEMENT_NAME (element));
1885     GST_OBJECT_FLAG_UNSET (element, GST_ELEMENT_FLAG_LOCKED_STATE);
1886   }
1887   GST_OBJECT_UNLOCK (element);
1888
1889   return TRUE;
1890
1891 was_ok:
1892   {
1893     GST_CAT_DEBUG (GST_CAT_STATES,
1894         "elements %s was already in locked state %d",
1895         GST_ELEMENT_NAME (element), old);
1896     GST_OBJECT_UNLOCK (element);
1897
1898     return FALSE;
1899   }
1900 }
1901
1902 /**
1903  * gst_element_sync_state_with_parent:
1904  * @element: a #GstElement.
1905  *
1906  * Tries to change the state of the element to the same as its parent.
1907  * If this function returns FALSE, the state of element is undefined.
1908  *
1909  * Returns: TRUE, if the element's state could be synced to the parent's state.
1910  *
1911  * MT safe.
1912  */
1913 gboolean
1914 gst_element_sync_state_with_parent (GstElement * element)
1915 {
1916   GstElement *parent;
1917   GstState target;
1918   GstStateChangeReturn ret;
1919
1920   g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1921
1922   if ((parent = GST_ELEMENT_CAST (gst_element_get_parent (element)))) {
1923     GstState parent_current, parent_pending;
1924
1925     GST_OBJECT_LOCK (parent);
1926     parent_current = GST_STATE (parent);
1927     parent_pending = GST_STATE_PENDING (parent);
1928     GST_OBJECT_UNLOCK (parent);
1929
1930     /* set to pending if there is one, else we set it to the current state of
1931      * the parent */
1932     if (parent_pending != GST_STATE_VOID_PENDING)
1933       target = parent_pending;
1934     else
1935       target = parent_current;
1936
1937     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
1938         "syncing state (%s) to parent %s %s (%s, %s)",
1939         gst_element_state_get_name (GST_STATE (element)),
1940         GST_ELEMENT_NAME (parent), gst_element_state_get_name (target),
1941         gst_element_state_get_name (parent_current),
1942         gst_element_state_get_name (parent_pending));
1943
1944     ret = gst_element_set_state (element, target);
1945     if (ret == GST_STATE_CHANGE_FAILURE)
1946       goto failed;
1947
1948     gst_object_unref (parent);
1949
1950     return TRUE;
1951   } else {
1952     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "element has no parent");
1953   }
1954   return FALSE;
1955
1956   /* ERROR */
1957 failed:
1958   {
1959     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
1960         "syncing state failed (%s)",
1961         gst_element_state_change_return_get_name (ret));
1962     gst_object_unref (parent);
1963     return FALSE;
1964   }
1965 }
1966
1967 /* MT safe */
1968 static GstStateChangeReturn
1969 gst_element_get_state_func (GstElement * element,
1970     GstState * state, GstState * pending, GstClockTime timeout)
1971 {
1972   GstStateChangeReturn ret = GST_STATE_CHANGE_FAILURE;
1973   GstState old_pending;
1974
1975   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "getting state, timeout %"
1976       GST_TIME_FORMAT, GST_TIME_ARGS (timeout));
1977
1978   GST_OBJECT_LOCK (element);
1979   ret = GST_STATE_RETURN (element);
1980   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "RETURN is %s",
1981       gst_element_state_change_return_get_name (ret));
1982
1983   /* we got an error, report immediately */
1984   if (ret == GST_STATE_CHANGE_FAILURE)
1985     goto done;
1986
1987   /* we got no_preroll, report immediately */
1988   if (ret == GST_STATE_CHANGE_NO_PREROLL)
1989     goto done;
1990
1991   /* no need to wait async if we are not async */
1992   if (ret != GST_STATE_CHANGE_ASYNC)
1993     goto done;
1994
1995   old_pending = GST_STATE_PENDING (element);
1996   if (old_pending != GST_STATE_VOID_PENDING) {
1997     gboolean signaled;
1998     guint32 cookie;
1999
2000     /* get cookie to detect state changes during waiting */
2001     cookie = element->state_cookie;
2002
2003     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2004         "waiting for element to commit state");
2005
2006     /* we have a pending state change, wait for it to complete */
2007     if (timeout != GST_CLOCK_TIME_NONE) {
2008       gint64 end_time;
2009       /* make timeout absolute */
2010       end_time = g_get_monotonic_time () + (timeout / 1000);
2011       signaled = GST_STATE_WAIT_UNTIL (element, end_time);
2012     } else {
2013       GST_STATE_WAIT (element);
2014       signaled = TRUE;
2015     }
2016
2017     if (!signaled) {
2018       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "timed out");
2019       /* timeout triggered */
2020       ret = GST_STATE_CHANGE_ASYNC;
2021     } else {
2022       if (cookie != element->state_cookie)
2023         goto interrupted;
2024
2025       /* could be success or failure */
2026       if (old_pending == GST_STATE (element)) {
2027         GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got success");
2028         ret = GST_STATE_CHANGE_SUCCESS;
2029       } else {
2030         GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got failure");
2031         ret = GST_STATE_CHANGE_FAILURE;
2032       }
2033     }
2034     /* if nothing is pending anymore we can return SUCCESS */
2035     if (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING) {
2036       GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "nothing pending");
2037       ret = GST_STATE_CHANGE_SUCCESS;
2038     }
2039   }
2040
2041 done:
2042   if (state)
2043     *state = GST_STATE (element);
2044   if (pending)
2045     *pending = GST_STATE_PENDING (element);
2046
2047   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2048       "state current: %s, pending: %s, result: %s",
2049       gst_element_state_get_name (GST_STATE (element)),
2050       gst_element_state_get_name (GST_STATE_PENDING (element)),
2051       gst_element_state_change_return_get_name (ret));
2052   GST_OBJECT_UNLOCK (element);
2053
2054   return ret;
2055
2056 interrupted:
2057   {
2058     if (state)
2059       *state = GST_STATE_VOID_PENDING;
2060     if (pending)
2061       *pending = GST_STATE_VOID_PENDING;
2062
2063     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "interruped");
2064
2065     GST_OBJECT_UNLOCK (element);
2066
2067     return GST_STATE_CHANGE_FAILURE;
2068   }
2069 }
2070
2071 /**
2072  * gst_element_get_state:
2073  * @element: a #GstElement to get the state of.
2074  * @state: (out) (allow-none): a pointer to #GstState to hold the state.
2075  *     Can be %NULL.
2076  * @pending: (out) (allow-none): a pointer to #GstState to hold the pending
2077  *     state. Can be %NULL.
2078  * @timeout: a #GstClockTime to specify the timeout for an async
2079  *           state change or %GST_CLOCK_TIME_NONE for infinite timeout.
2080  *
2081  * Gets the state of the element.
2082  *
2083  * For elements that performed an ASYNC state change, as reported by
2084  * gst_element_set_state(), this function will block up to the
2085  * specified timeout value for the state change to complete.
2086  * If the element completes the state change or goes into
2087  * an error, this function returns immediately with a return value of
2088  * %GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively.
2089  *
2090  * For elements that did not return %GST_STATE_CHANGE_ASYNC, this function
2091  * returns the current and pending state immediately.
2092  *
2093  * This function returns %GST_STATE_CHANGE_NO_PREROLL if the element
2094  * successfully changed its state but is not able to provide data yet.
2095  * This mostly happens for live sources that only produce data in
2096  * %GST_STATE_PLAYING. While the state change return is equivalent to
2097  * %GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that
2098  * some sink elements might not be able to complete their state change because
2099  * an element is not producing data to complete the preroll. When setting the
2100  * element to playing, the preroll will complete and playback will start.
2101  *
2102  * Returns: %GST_STATE_CHANGE_SUCCESS if the element has no more pending state
2103  *          and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the
2104  *          element is still performing a state change or
2105  *          %GST_STATE_CHANGE_FAILURE if the last state change failed.
2106  *
2107  * MT safe.
2108  */
2109 GstStateChangeReturn
2110 gst_element_get_state (GstElement * element,
2111     GstState * state, GstState * pending, GstClockTime timeout)
2112 {
2113   GstElementClass *oclass;
2114   GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2115
2116   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2117
2118   oclass = GST_ELEMENT_GET_CLASS (element);
2119
2120   if (oclass->get_state)
2121     result = (oclass->get_state) (element, state, pending, timeout);
2122
2123   return result;
2124 }
2125
2126 /**
2127  * gst_element_abort_state:
2128  * @element: a #GstElement to abort the state of.
2129  *
2130  * Abort the state change of the element. This function is used
2131  * by elements that do asynchronous state changes and find out
2132  * something is wrong.
2133  *
2134  * This function should be called with the STATE_LOCK held.
2135  *
2136  * MT safe.
2137  */
2138 void
2139 gst_element_abort_state (GstElement * element)
2140 {
2141   GstState pending;
2142
2143 #ifndef GST_DISABLE_GST_DEBUG
2144   GstState old_state;
2145 #endif
2146
2147   g_return_if_fail (GST_IS_ELEMENT (element));
2148
2149   GST_OBJECT_LOCK (element);
2150   pending = GST_STATE_PENDING (element);
2151
2152   if (pending == GST_STATE_VOID_PENDING ||
2153       GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2154     goto nothing_aborted;
2155
2156 #ifndef GST_DISABLE_GST_DEBUG
2157   old_state = GST_STATE (element);
2158
2159   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2160       "aborting state from %s to %s", gst_element_state_get_name (old_state),
2161       gst_element_state_get_name (pending));
2162 #endif
2163
2164   /* flag error */
2165   GST_STATE_RETURN (element) = GST_STATE_CHANGE_FAILURE;
2166
2167   GST_STATE_BROADCAST (element);
2168   GST_OBJECT_UNLOCK (element);
2169
2170   return;
2171
2172 nothing_aborted:
2173   {
2174     GST_OBJECT_UNLOCK (element);
2175     return;
2176   }
2177 }
2178
2179 /* Not static because GstBin has manual state handling too */
2180 void
2181 _priv_gst_element_state_changed (GstElement * element, GstState oldstate,
2182     GstState newstate, GstState pending)
2183 {
2184   GstElementClass *klass = GST_ELEMENT_GET_CLASS (element);
2185   GstMessage *message;
2186
2187   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2188       "notifying about state-changed %s to %s (%s pending)",
2189       gst_element_state_get_name (oldstate),
2190       gst_element_state_get_name (newstate),
2191       gst_element_state_get_name (pending));
2192
2193   if (klass->state_changed)
2194     klass->state_changed (element, oldstate, newstate, pending);
2195
2196   message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2197       oldstate, newstate, pending);
2198   gst_element_post_message (element, message);
2199 }
2200
2201 /**
2202  * gst_element_continue_state:
2203  * @element: a #GstElement to continue the state change of.
2204  * @ret: The previous state return value
2205  *
2206  * Commit the state change of the element and proceed to the next
2207  * pending state if any. This function is used
2208  * by elements that do asynchronous state changes.
2209  * The core will normally call this method automatically when an
2210  * element returned %GST_STATE_CHANGE_SUCCESS from the state change function.
2211  *
2212  * If after calling this method the element still has not reached
2213  * the pending state, the next state change is performed.
2214  *
2215  * This method is used internally and should normally not be called by plugins
2216  * or applications.
2217  *
2218  * Returns: The result of the commit state change.
2219  *
2220  * MT safe.
2221  */
2222 GstStateChangeReturn
2223 gst_element_continue_state (GstElement * element, GstStateChangeReturn ret)
2224 {
2225   GstStateChangeReturn old_ret;
2226   GstState old_state, old_next;
2227   GstState current, next, pending;
2228   GstStateChange transition;
2229
2230   GST_OBJECT_LOCK (element);
2231   old_ret = GST_STATE_RETURN (element);
2232   GST_STATE_RETURN (element) = ret;
2233   pending = GST_STATE_PENDING (element);
2234
2235   /* check if there is something to commit */
2236   if (pending == GST_STATE_VOID_PENDING)
2237     goto nothing_pending;
2238
2239   old_state = GST_STATE (element);
2240   /* this is the state we should go to next */
2241   old_next = GST_STATE_NEXT (element);
2242   /* update current state */
2243   current = GST_STATE (element) = old_next;
2244
2245   /* see if we reached the final state */
2246   if (pending == current)
2247     goto complete;
2248
2249   next = GST_STATE_GET_NEXT (current, pending);
2250   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2251
2252   GST_STATE_NEXT (element) = next;
2253   /* mark busy */
2254   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2255   GST_OBJECT_UNLOCK (element);
2256
2257   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2258       "committing state from %s to %s, pending %s, next %s",
2259       gst_element_state_get_name (old_state),
2260       gst_element_state_get_name (old_next),
2261       gst_element_state_get_name (pending), gst_element_state_get_name (next));
2262
2263   _priv_gst_element_state_changed (element, old_state, old_next, pending);
2264
2265   GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2266       "continue state change %s to %s, final %s",
2267       gst_element_state_get_name (current),
2268       gst_element_state_get_name (next), gst_element_state_get_name (pending));
2269
2270   ret = gst_element_change_state (element, transition);
2271
2272   return ret;
2273
2274 nothing_pending:
2275   {
2276     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "nothing pending");
2277     GST_OBJECT_UNLOCK (element);
2278     return ret;
2279   }
2280 complete:
2281   {
2282     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2283     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2284
2285     GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2286         "completed state change to %s", gst_element_state_get_name (pending));
2287     GST_OBJECT_UNLOCK (element);
2288
2289     /* don't post silly messages with the same state. This can happen
2290      * when an element state is changed to what it already was. For bins
2291      * this can be the result of a lost state, which we check with the
2292      * previous return value.
2293      * We do signal the cond though as a _get_state() might be blocking
2294      * on it. */
2295     if (old_state != old_next || old_ret == GST_STATE_CHANGE_ASYNC)
2296       _priv_gst_element_state_changed (element, old_state, old_next,
2297           GST_STATE_VOID_PENDING);
2298
2299     GST_STATE_BROADCAST (element);
2300
2301     return ret;
2302   }
2303 }
2304
2305 /**
2306  * gst_element_lost_state:
2307  * @element: a #GstElement the state is lost of
2308  *
2309  * Brings the element to the lost state. The current state of the
2310  * element is copied to the pending state so that any call to
2311  * gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC.
2312  *
2313  * An ASYNC_START message is posted. If the element was PLAYING, it will
2314  * go to PAUSED. The element will be restored to its PLAYING state by
2315  * the parent pipeline when it prerolls again.
2316  *
2317  * This is mostly used for elements that lost their preroll buffer
2318  * in the %GST_STATE_PAUSED or %GST_STATE_PLAYING state after a flush,
2319  * they will go to their pending state again when a new preroll buffer is
2320  * queued. This function can only be called when the element is currently
2321  * not in error or an async state change.
2322  *
2323  * This function is used internally and should normally not be called from
2324  * plugins or applications.
2325  */
2326 void
2327 gst_element_lost_state (GstElement * element)
2328 {
2329   GstState old_state, new_state;
2330   GstMessage *message;
2331
2332   g_return_if_fail (GST_IS_ELEMENT (element));
2333
2334   GST_OBJECT_LOCK (element);
2335   if (GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2336     goto nothing_lost;
2337
2338   if (GST_STATE_PENDING (element) != GST_STATE_VOID_PENDING)
2339     goto only_async_start;
2340
2341   old_state = GST_STATE (element);
2342
2343   /* when we were PLAYING, the new state is PAUSED. We will also not
2344    * automatically go to PLAYING but let the parent bin(s) set us to PLAYING
2345    * when we preroll. */
2346   if (old_state > GST_STATE_PAUSED)
2347     new_state = GST_STATE_PAUSED;
2348   else
2349     new_state = old_state;
2350
2351   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2352       "lost state of %s to %s", gst_element_state_get_name (old_state),
2353       gst_element_state_get_name (new_state));
2354
2355   GST_STATE (element) = new_state;
2356   GST_STATE_NEXT (element) = new_state;
2357   GST_STATE_PENDING (element) = new_state;
2358   GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2359   GST_OBJECT_UNLOCK (element);
2360
2361   _priv_gst_element_state_changed (element, new_state, new_state, new_state);
2362
2363   message = gst_message_new_async_start (GST_OBJECT_CAST (element));
2364   gst_element_post_message (element, message);
2365
2366   return;
2367
2368 nothing_lost:
2369   {
2370     GST_OBJECT_UNLOCK (element);
2371     return;
2372   }
2373 only_async_start:
2374   {
2375     GST_OBJECT_UNLOCK (element);
2376
2377     message = gst_message_new_async_start (GST_OBJECT_CAST (element));
2378     gst_element_post_message (element, message);
2379     return;
2380   }
2381 }
2382
2383 /**
2384  * gst_element_set_state:
2385  * @element: a #GstElement to change state of.
2386  * @state: the element's new #GstState.
2387  *
2388  * Sets the state of the element. This function will try to set the
2389  * requested state by going through all the intermediary states and calling
2390  * the class's state change function for each.
2391  *
2392  * This function can return #GST_STATE_CHANGE_ASYNC, in which case the
2393  * element will perform the remainder of the state change asynchronously in
2394  * another thread.
2395  * An application can use gst_element_get_state() to wait for the completion
2396  * of the state change or it can wait for a state change message on the bus.
2397  *
2398  * State changes to %GST_STATE_READY or %GST_STATE_NULL never return
2399  * #GST_STATE_CHANGE_ASYNC.
2400  *
2401  * Returns: Result of the state change using #GstStateChangeReturn.
2402  *
2403  * MT safe.
2404  */
2405 GstStateChangeReturn
2406 gst_element_set_state (GstElement * element, GstState state)
2407 {
2408   GstElementClass *oclass;
2409   GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2410
2411   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2412
2413   oclass = GST_ELEMENT_GET_CLASS (element);
2414
2415   if (oclass->set_state)
2416     result = (oclass->set_state) (element, state);
2417
2418   return result;
2419 }
2420
2421 /*
2422  * default set state function, calculates the next state based
2423  * on current state and calls the change_state function
2424  */
2425 static GstStateChangeReturn
2426 gst_element_set_state_func (GstElement * element, GstState state)
2427 {
2428   GstState current, next, old_pending;
2429   GstStateChangeReturn ret;
2430   GstStateChange transition;
2431   GstStateChangeReturn old_ret;
2432
2433   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2434
2435   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "set_state to %s",
2436       gst_element_state_get_name (state));
2437
2438   /* state lock is taken to protect the set_state() and get_state()
2439    * procedures, it does not lock any variables. */
2440   GST_STATE_LOCK (element);
2441
2442   /* now calculate how to get to the new state */
2443   GST_OBJECT_LOCK (element);
2444   old_ret = GST_STATE_RETURN (element);
2445   /* previous state change returned an error, remove all pending
2446    * and next states */
2447   if (old_ret == GST_STATE_CHANGE_FAILURE) {
2448     GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2449     GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2450     GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
2451   }
2452
2453   current = GST_STATE (element);
2454   next = GST_STATE_NEXT (element);
2455   old_pending = GST_STATE_PENDING (element);
2456
2457   /* this is the (new) state we should go to. TARGET is the last state we set on
2458    * the element. */
2459   if (state != GST_STATE_TARGET (element)) {
2460     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2461         "setting target state to %s", gst_element_state_get_name (state));
2462     GST_STATE_TARGET (element) = state;
2463     /* increment state cookie so that we can track each state change. We only do
2464      * this if this is actually a new state change. */
2465     element->state_cookie++;
2466   }
2467   GST_STATE_PENDING (element) = state;
2468
2469   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2470       "current %s, old_pending %s, next %s, old return %s",
2471       gst_element_state_get_name (current),
2472       gst_element_state_get_name (old_pending),
2473       gst_element_state_get_name (next),
2474       gst_element_state_change_return_get_name (old_ret));
2475
2476   /* if the element was busy doing a state change, we just update the
2477    * target state, it'll get to it async then. */
2478   if (old_pending != GST_STATE_VOID_PENDING) {
2479     /* upwards state change will happen ASYNC */
2480     if (old_pending <= state)
2481       goto was_busy;
2482     /* element is going to this state already */
2483     else if (next == state)
2484       goto was_busy;
2485     /* element was performing an ASYNC upward state change and
2486      * we request to go downward again. Start from the next pending
2487      * state then. */
2488     else if (next > state
2489         && GST_STATE_RETURN (element) == GST_STATE_CHANGE_ASYNC) {
2490       current = next;
2491     }
2492   }
2493   next = GST_STATE_GET_NEXT (current, state);
2494   /* now we store the next state */
2495   GST_STATE_NEXT (element) = next;
2496   /* mark busy, we need to check that there is actually a state change
2497    * to be done else we could accidentally override SUCCESS/NO_PREROLL and
2498    * the default element change_state function has no way to know what the
2499    * old value was... could consider this a FIXME...*/
2500   if (current != next)
2501     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2502
2503   transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2504
2505   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2506       "%s: setting state from %s to %s",
2507       (next != state ? "intermediate" : "final"),
2508       gst_element_state_get_name (current), gst_element_state_get_name (next));
2509
2510   /* now signal any waiters, they will error since the cookie was incremented */
2511   GST_STATE_BROADCAST (element);
2512
2513   GST_OBJECT_UNLOCK (element);
2514
2515   ret = gst_element_change_state (element, transition);
2516
2517   GST_STATE_UNLOCK (element);
2518
2519   GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "returned %s",
2520       gst_element_state_change_return_get_name (ret));
2521
2522   return ret;
2523
2524 was_busy:
2525   {
2526     GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2527     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2528         "element was busy with async state change");
2529     GST_OBJECT_UNLOCK (element);
2530
2531     GST_STATE_UNLOCK (element);
2532
2533     return GST_STATE_CHANGE_ASYNC;
2534   }
2535 }
2536
2537 /**
2538  * gst_element_change_state:
2539  * @element: a #GstElement
2540  * @transition: the requested transition
2541  *
2542  * Perform @transition on @element.
2543  *
2544  * This function must be called with STATE_LOCK held and is mainly used
2545  * internally.
2546  *
2547  * Returns: the #GstStateChangeReturn of the state transition.
2548  */
2549 GstStateChangeReturn
2550 gst_element_change_state (GstElement * element, GstStateChange transition)
2551 {
2552   GstElementClass *oclass;
2553   GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
2554
2555   oclass = GST_ELEMENT_GET_CLASS (element);
2556
2557   /* call the state change function so it can set the state */
2558   if (oclass->change_state)
2559     ret = (oclass->change_state) (element, transition);
2560   else
2561     ret = GST_STATE_CHANGE_FAILURE;
2562
2563   switch (ret) {
2564     case GST_STATE_CHANGE_FAILURE:
2565       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2566           "have FAILURE change_state return");
2567       /* state change failure */
2568       gst_element_abort_state (element);
2569       break;
2570     case GST_STATE_CHANGE_ASYNC:
2571     {
2572       GstState target;
2573
2574       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2575           "element will change state ASYNC");
2576
2577       target = GST_STATE_TARGET (element);
2578
2579       if (target > GST_STATE_READY)
2580         goto async;
2581
2582       /* else we just continue the state change downwards */
2583       GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2584           "forcing commit state %s <= %s",
2585           gst_element_state_get_name (target),
2586           gst_element_state_get_name (GST_STATE_READY));
2587
2588       ret = gst_element_continue_state (element, GST_STATE_CHANGE_SUCCESS);
2589       break;
2590     }
2591     case GST_STATE_CHANGE_SUCCESS:
2592       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2593           "element changed state SUCCESS");
2594       /* we can commit the state now which will proceeed to
2595        * the next state */
2596       ret = gst_element_continue_state (element, ret);
2597       break;
2598     case GST_STATE_CHANGE_NO_PREROLL:
2599       GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2600           "element changed state NO_PREROLL");
2601       /* we can commit the state now which will proceeed to
2602        * the next state */
2603       ret = gst_element_continue_state (element, ret);
2604       break;
2605     default:
2606       goto invalid_return;
2607   }
2608
2609   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit state change %d", ret);
2610
2611   return ret;
2612
2613 async:
2614   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit async state change %d",
2615       ret);
2616
2617   return ret;
2618
2619   /* ERROR */
2620 invalid_return:
2621   {
2622     GST_OBJECT_LOCK (element);
2623     /* somebody added a GST_STATE_ and forgot to do stuff here ! */
2624     g_critical ("%s: unknown return value %d from a state change function",
2625         GST_ELEMENT_NAME (element), ret);
2626
2627     /* we are in error now */
2628     ret = GST_STATE_CHANGE_FAILURE;
2629     GST_STATE_RETURN (element) = ret;
2630     GST_OBJECT_UNLOCK (element);
2631
2632     return ret;
2633   }
2634 }
2635
2636 /* gst_iterator_fold functions for pads_activate
2637  * Stop the iterator if activating one pad failed. */
2638 static gboolean
2639 activate_pads (const GValue * vpad, GValue * ret, gboolean * active)
2640 {
2641   GstPad *pad = g_value_get_object (vpad);
2642   gboolean cont = TRUE;
2643
2644   if (!(cont = gst_pad_set_active (pad, *active)))
2645     g_value_set_boolean (ret, FALSE);
2646
2647   return cont;
2648 }
2649
2650 /* returns false on error or early cutout of the fold, true if all
2651  * pads in @iter were (de)activated successfully. */
2652 static gboolean
2653 iterator_activate_fold_with_resync (GstIterator * iter,
2654     GstIteratorFoldFunction func, gpointer user_data)
2655 {
2656   GstIteratorResult ires;
2657   GValue ret = { 0 };
2658
2659   /* no need to unset this later, it's just a boolean */
2660   g_value_init (&ret, G_TYPE_BOOLEAN);
2661   g_value_set_boolean (&ret, TRUE);
2662
2663   while (1) {
2664     ires = gst_iterator_fold (iter, func, &ret, user_data);
2665     switch (ires) {
2666       case GST_ITERATOR_RESYNC:
2667         /* need to reset the result again */
2668         g_value_set_boolean (&ret, TRUE);
2669         gst_iterator_resync (iter);
2670         break;
2671       case GST_ITERATOR_DONE:
2672         /* all pads iterated, return collected value */
2673         goto done;
2674       default:
2675         /* iterator returned _ERROR or premature end with _OK,
2676          * mark an error and exit */
2677         g_value_set_boolean (&ret, FALSE);
2678         goto done;
2679     }
2680   }
2681 done:
2682   /* return collected value */
2683   return g_value_get_boolean (&ret);
2684 }
2685
2686 /* is called with STATE_LOCK
2687  *
2688  * Pads are activated from source pads to sinkpads.
2689  */
2690 static gboolean
2691 gst_element_pads_activate (GstElement * element, gboolean active)
2692 {
2693   GstIterator *iter;
2694   gboolean res;
2695
2696   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2697       "%s pads", active ? "activate" : "deactivate");
2698
2699   iter = gst_element_iterate_src_pads (element);
2700   res =
2701       iterator_activate_fold_with_resync (iter,
2702       (GstIteratorFoldFunction) activate_pads, &active);
2703   gst_iterator_free (iter);
2704   if (G_UNLIKELY (!res))
2705     goto src_failed;
2706
2707   iter = gst_element_iterate_sink_pads (element);
2708   res =
2709       iterator_activate_fold_with_resync (iter,
2710       (GstIteratorFoldFunction) activate_pads, &active);
2711   gst_iterator_free (iter);
2712   if (G_UNLIKELY (!res))
2713     goto sink_failed;
2714
2715   GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2716       "pad %sactivation successful", active ? "" : "de");
2717
2718   return TRUE;
2719
2720   /* ERRORS */
2721 src_failed:
2722   {
2723     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2724         "pad %sactivation failed", active ? "" : "de");
2725     return FALSE;
2726   }
2727 sink_failed:
2728   {
2729     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2730         "sink pads_activate failed");
2731     return FALSE;
2732   }
2733 }
2734
2735 /* is called with STATE_LOCK */
2736 static GstStateChangeReturn
2737 gst_element_change_state_func (GstElement * element, GstStateChange transition)
2738 {
2739   GstState state, next;
2740   GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
2741
2742   g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2743
2744   state = (GstState) GST_STATE_TRANSITION_CURRENT (transition);
2745   next = GST_STATE_TRANSITION_NEXT (transition);
2746
2747   /* if the element already is in the given state, we just return success */
2748   if (next == GST_STATE_VOID_PENDING || state == next)
2749     goto was_ok;
2750
2751   GST_CAT_LOG_OBJECT (GST_CAT_STATES, element,
2752       "default handler tries setting state from %s to %s (%04x)",
2753       gst_element_state_get_name (state),
2754       gst_element_state_get_name (next), transition);
2755
2756   switch (transition) {
2757     case GST_STATE_CHANGE_NULL_TO_READY:
2758       break;
2759     case GST_STATE_CHANGE_READY_TO_PAUSED:
2760       if (!gst_element_pads_activate (element, TRUE)) {
2761         result = GST_STATE_CHANGE_FAILURE;
2762       }
2763       break;
2764     case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
2765       break;
2766     case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
2767       break;
2768     case GST_STATE_CHANGE_PAUSED_TO_READY:
2769     case GST_STATE_CHANGE_READY_TO_NULL:
2770       /* deactivate pads in both cases, since they are activated on
2771          ready->paused but the element might not have made it to paused */
2772       if (!gst_element_pads_activate (element, FALSE)) {
2773         result = GST_STATE_CHANGE_FAILURE;
2774       }
2775       break;
2776     default:
2777       /* this will catch real but unhandled state changes;
2778        * can only be caused by:
2779        * - a new state was added
2780        * - somehow the element was asked to jump across an intermediate state
2781        */
2782       g_warning ("Unhandled state change from %s to %s",
2783           gst_element_state_get_name (state),
2784           gst_element_state_get_name (next));
2785       break;
2786   }
2787   return result;
2788
2789 was_ok:
2790   {
2791     GST_OBJECT_LOCK (element);
2792     result = GST_STATE_RETURN (element);
2793     GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2794         "element is already in the %s state",
2795         gst_element_state_get_name (state));
2796     GST_OBJECT_UNLOCK (element);
2797
2798     return result;
2799   }
2800 }
2801
2802 /**
2803  * gst_element_get_factory:
2804  * @element: a #GstElement to request the element factory of.
2805  *
2806  * Retrieves the factory that was used to create this element.
2807  *
2808  * Returns: (transfer none): the #GstElementFactory used for creating this
2809  *     element. no refcounting is needed.
2810  */
2811 GstElementFactory *
2812 gst_element_get_factory (GstElement * element)
2813 {
2814   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
2815
2816   return GST_ELEMENT_GET_CLASS (element)->elementfactory;
2817 }
2818
2819 static void
2820 gst_element_dispose (GObject * object)
2821 {
2822   GstElement *element = GST_ELEMENT_CAST (object);
2823   GstClock **clock_p;
2824   GstBus **bus_p;
2825   GstElementClass *oclass;
2826   GList *walk;
2827
2828   oclass = GST_ELEMENT_GET_CLASS (element);
2829
2830   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "dispose");
2831
2832   if (GST_STATE (element) != GST_STATE_NULL)
2833     goto not_null;
2834
2835   /* start by releasing all request pads, this might also remove some dynamic
2836    * pads */
2837   walk = element->pads;
2838   while (walk) {
2839     GstPad *pad = GST_PAD_CAST (walk->data);
2840
2841     walk = walk->next;
2842
2843     if (oclass->release_pad && GST_PAD_PAD_TEMPLATE (pad) &&
2844         GST_PAD_TEMPLATE_PRESENCE (GST_PAD_PAD_TEMPLATE (pad))
2845         == GST_PAD_REQUEST) {
2846       GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2847           "removing request pad %s:%s", GST_DEBUG_PAD_NAME (pad));
2848       oclass->release_pad (element, pad);
2849
2850       /* in case the release_pad function removed the next pad too */
2851       if (walk && g_list_position (element->pads, walk) == -1)
2852         walk = element->pads;
2853     }
2854   }
2855   /* remove the remaining pads */
2856   while (element->pads) {
2857     GstPad *pad = GST_PAD_CAST (element->pads->data);
2858     GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2859         "removing pad %s:%s", GST_DEBUG_PAD_NAME (pad));
2860     if (!gst_element_remove_pad (element, pad)) {
2861       /* only happens when someone unparented our pad.. */
2862       g_critical ("failed to remove pad %s:%s", GST_DEBUG_PAD_NAME (pad));
2863       break;
2864     }
2865   }
2866
2867   GST_OBJECT_LOCK (element);
2868   clock_p = &element->clock;
2869   bus_p = &element->bus;
2870   gst_object_replace ((GstObject **) clock_p, NULL);
2871   gst_object_replace ((GstObject **) bus_p, NULL);
2872   GST_OBJECT_UNLOCK (element);
2873
2874   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "parent class dispose");
2875
2876   G_OBJECT_CLASS (parent_class)->dispose (object);
2877
2878   return;
2879
2880   /* ERRORS */
2881 not_null:
2882   {
2883     gboolean is_locked;
2884
2885     is_locked = GST_ELEMENT_IS_LOCKED_STATE (element);
2886     g_critical
2887         ("\nTrying to dispose element %s, but it is in %s%s instead of the NULL"
2888         " state.\n"
2889         "You need to explicitly set elements to the NULL state before\n"
2890         "dropping the final reference, to allow them to clean up.\n"
2891         "This problem may also be caused by a refcounting bug in the\n"
2892         "application or some element.\n",
2893         GST_OBJECT_NAME (element),
2894         gst_element_state_get_name (GST_STATE (element)),
2895         is_locked ? " (locked)" : "");
2896     return;
2897   }
2898 }
2899
2900 static void
2901 gst_element_finalize (GObject * object)
2902 {
2903   GstElement *element = GST_ELEMENT_CAST (object);
2904
2905   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize");
2906
2907   g_cond_clear (&element->state_cond);
2908   g_rec_mutex_clear (&element->state_lock);
2909
2910   GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize parent");
2911
2912   G_OBJECT_CLASS (parent_class)->finalize (object);
2913 }
2914
2915 static void
2916 gst_element_set_bus_func (GstElement * element, GstBus * bus)
2917 {
2918   GstBus **bus_p;
2919
2920   g_return_if_fail (GST_IS_ELEMENT (element));
2921
2922   GST_CAT_DEBUG_OBJECT (GST_CAT_PARENTAGE, element, "setting bus to %p", bus);
2923
2924   GST_OBJECT_LOCK (element);
2925   bus_p = &GST_ELEMENT_BUS (element);
2926   gst_object_replace ((GstObject **) bus_p, GST_OBJECT_CAST (bus));
2927   GST_OBJECT_UNLOCK (element);
2928 }
2929
2930 /**
2931  * gst_element_set_bus:
2932  * @element: a #GstElement to set the bus of.
2933  * @bus: (transfer none): the #GstBus to set.
2934  *
2935  * Sets the bus of the element. Increases the refcount on the bus.
2936  * For internal use only, unless you're testing elements.
2937  *
2938  * MT safe.
2939  */
2940 void
2941 gst_element_set_bus (GstElement * element, GstBus * bus)
2942 {
2943   GstElementClass *oclass;
2944
2945   g_return_if_fail (GST_IS_ELEMENT (element));
2946
2947   oclass = GST_ELEMENT_GET_CLASS (element);
2948
2949   if (oclass->set_bus)
2950     oclass->set_bus (element, bus);
2951 }
2952
2953 /**
2954  * gst_element_get_bus:
2955  * @element: a #GstElement to get the bus of.
2956  *
2957  * Returns the bus of the element. Note that only a #GstPipeline will provide a
2958  * bus for the application.
2959  *
2960  * Returns: (transfer full): the element's #GstBus. unref after usage.
2961  *
2962  * MT safe.
2963  */
2964 GstBus *
2965 gst_element_get_bus (GstElement * element)
2966 {
2967   GstBus *result = NULL;
2968
2969   g_return_val_if_fail (GST_IS_ELEMENT (element), result);
2970
2971   GST_OBJECT_LOCK (element);
2972   if ((result = GST_ELEMENT_BUS (element)))
2973     gst_object_ref (result);
2974   GST_OBJECT_UNLOCK (element);
2975
2976   GST_CAT_DEBUG_OBJECT (GST_CAT_BUS, element, "got bus %" GST_PTR_FORMAT,
2977       result);
2978
2979   return result;
2980 }