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