gst/gstelement.c

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