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