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