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