gst/gstelement.c

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