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