gst/gstelement.c

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