gst/gstelement.c

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