gst/gstelement.c

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