2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2004 Wim Taymans <wim@fluendo.com>
5 * gstelement.c: The base element, all elements derive from this
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.
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.
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.
25 * @short_description: Abstract base class for all pipeline elements
26 * @see_also: #GstElementFactory, #GstPad
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.
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.
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().
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().
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.
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 * To get a string representation of a #GstState, use
60 * gst_element_state_get_name().
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
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().
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.
76 * Last reviewed on 2009-05-29 (0.10.24)
79 #include "gst_private.h"
82 #include <gobject/gvaluecollector.h>
84 #include "gstelement.h"
85 #include "gstenumtypes.h"
87 #include "gstmarshal.h"
93 #include "gst-i18n-lib.h"
95 /* Element signals and args */
111 extern void __gst_element_details_clear (GstElementDetails * dp);
112 extern void __gst_element_details_copy (GstElementDetails * dest,
113 const GstElementDetails * src);
115 static void gst_element_class_init (GstElementClass * klass);
116 static void gst_element_init (GstElement * element);
117 static void gst_element_base_class_init (gpointer g_class);
118 static void gst_element_base_class_finalize (gpointer g_class);
120 static void gst_element_dispose (GObject * object);
121 static void gst_element_finalize (GObject * object);
123 static GstStateChangeReturn gst_element_change_state_func (GstElement * element,
124 GstStateChange transition);
125 static GstStateChangeReturn gst_element_get_state_func (GstElement * element,
126 GstState * state, GstState * pending, GstClockTime timeout);
127 static GstStateChangeReturn gst_element_set_state_func (GstElement * element,
129 static void gst_element_set_bus_func (GstElement * element, GstBus * bus);
131 static gboolean gst_element_default_send_event (GstElement * element,
133 static gboolean gst_element_default_query (GstElement * element,
136 static GstPadTemplate
137 * gst_element_class_get_request_pad_template (GstElementClass *
138 element_class, const gchar * name);
140 #ifndef GST_DISABLE_LOADSAVE
141 static xmlNodePtr gst_element_save_thyself (GstObject * object,
143 static void gst_element_restore_thyself (GstObject * parent, xmlNodePtr self);
146 static GstObjectClass *parent_class = NULL;
147 static guint gst_element_signals[LAST_SIGNAL] = { 0 };
149 /* this is used in gstelementfactory.c:gst_element_register() */
150 GQuark _gst_elementclass_factory = 0;
153 gst_element_get_type (void)
155 static volatile gsize gst_element_type = 0;
157 if (g_once_init_enter (&gst_element_type)) {
159 static const GTypeInfo element_info = {
160 sizeof (GstElementClass),
161 gst_element_base_class_init,
162 gst_element_base_class_finalize,
163 (GClassInitFunc) gst_element_class_init,
168 (GInstanceInitFunc) gst_element_init,
172 _type = g_type_register_static (GST_TYPE_OBJECT, "GstElement",
173 &element_info, G_TYPE_FLAG_ABSTRACT);
175 _gst_elementclass_factory =
176 g_quark_from_static_string ("GST_ELEMENTCLASS_FACTORY");
177 g_once_init_leave (&gst_element_type, _type);
179 return gst_element_type;
183 gst_element_class_init (GstElementClass * klass)
185 GObjectClass *gobject_class;
186 GstObjectClass *gstobject_class;
188 gobject_class = (GObjectClass *) klass;
189 gstobject_class = (GstObjectClass *) klass;
191 parent_class = g_type_class_peek_parent (klass);
194 * GstElement::pad-added:
195 * @gstelement: the object which received the signal
196 * @new_pad: the pad that has been added
198 * a new #GstPad has been added to the element.
200 gst_element_signals[PAD_ADDED] =
201 g_signal_new ("pad-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
202 G_STRUCT_OFFSET (GstElementClass, pad_added), NULL, NULL,
203 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
205 * GstElement::pad-removed:
206 * @gstelement: the object which received the signal
207 * @old_pad: the pad that has been removed
209 * a #GstPad has been removed from the element
211 gst_element_signals[PAD_REMOVED] =
212 g_signal_new ("pad-removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
213 G_STRUCT_OFFSET (GstElementClass, pad_removed), NULL, NULL,
214 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
216 * GstElement::no-more-pads:
217 * @gstelement: the object which received the signal
219 * This signals that the element will not generate more dynamic pads.
221 gst_element_signals[NO_MORE_PADS] =
222 g_signal_new ("no-more-pads", G_TYPE_FROM_CLASS (klass),
223 G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstElementClass, no_more_pads), NULL,
224 NULL, gst_marshal_VOID__VOID, G_TYPE_NONE, 0);
226 gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_element_dispose);
227 gobject_class->finalize = GST_DEBUG_FUNCPTR (gst_element_finalize);
229 #ifndef GST_DISABLE_LOADSAVE
230 gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_element_save_thyself);
231 gstobject_class->restore_thyself =
232 GST_DEBUG_FUNCPTR (gst_element_restore_thyself);
235 klass->change_state = GST_DEBUG_FUNCPTR (gst_element_change_state_func);
236 klass->set_state = GST_DEBUG_FUNCPTR (gst_element_set_state_func);
237 klass->get_state = GST_DEBUG_FUNCPTR (gst_element_get_state_func);
238 klass->set_bus = GST_DEBUG_FUNCPTR (gst_element_set_bus_func);
239 klass->query = GST_DEBUG_FUNCPTR (gst_element_default_query);
240 klass->send_event = GST_DEBUG_FUNCPTR (gst_element_default_send_event);
241 klass->numpadtemplates = 0;
243 klass->elementfactory = NULL;
247 gst_element_base_class_init (gpointer g_class)
249 GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);
251 /* FIXME 0.11: Copy the element details and instead of clearing the
252 * pad template list copy the list and increase the refcount of
253 * the pad templates by one.
255 * This will make it possible to add pad templates and set element
256 * details in the class_init functions and is the real GObject way
258 * See http://bugzilla.gnome.org/show_bug.cgi?id=491501
260 memset (&element_class->details, 0, sizeof (GstElementDetails));
261 element_class->padtemplates = NULL;
263 /* set the factory, see gst_element_register() */
264 element_class->elementfactory =
265 g_type_get_qdata (G_TYPE_FROM_CLASS (element_class),
266 _gst_elementclass_factory);
267 GST_DEBUG ("type %s : factory %p", G_OBJECT_CLASS_NAME (element_class),
268 element_class->elementfactory);
272 gst_element_base_class_finalize (gpointer g_class)
274 GstElementClass *klass = GST_ELEMENT_CLASS (g_class);
276 g_list_foreach (klass->padtemplates, (GFunc) gst_object_unref, NULL);
277 g_list_free (klass->padtemplates);
278 __gst_element_details_clear (&klass->details);
282 gst_element_init (GstElement * element)
284 GST_STATE (element) = GST_STATE_NULL;
285 GST_STATE_TARGET (element) = GST_STATE_NULL;
286 GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
287 GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
288 GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
290 element->state_lock = g_new0 (GStaticRecMutex, 1);
291 g_static_rec_mutex_init (element->state_lock);
292 element->state_cond = g_cond_new ();
296 * gst_element_default_error:
297 * @object: a #GObject that signalled the error.
298 * @orig: the #GstObject that initiated the error.
299 * @error: the GError.
300 * @debug: an additional debug information string, or %NULL.
302 * A default error signal callback to attach to an element.
303 * The user data passed to the g_signal_connect is ignored.
305 * The default handler will simply print the error string using g_print.
310 gst_element_default_error (GObject * object, GstObject * source, GError * error,
313 gchar *name = gst_object_get_path_string (source);
315 g_print (_("ERROR: from element %s: %s\n"), name, error->message);
317 g_print (_("Additional debug info:\n%s\n"), debug);
323 * gst_element_release_request_pad:
324 * @element: a #GstElement to release the request pad of.
325 * @pad: the #GstPad to release.
327 * Makes the element free the previously requested pad as obtained
328 * with gst_element_get_request_pad().
330 * This does not unref the pad. If the pad was created by using
331 * gst_element_get_request_pad(), gst_element_release_request_pad() needs to be
332 * followed by gst_object_unref() to free the @pad.
337 gst_element_release_request_pad (GstElement * element, GstPad * pad)
339 GstElementClass *oclass;
341 g_return_if_fail (GST_IS_ELEMENT (element));
342 g_return_if_fail (GST_IS_PAD (pad));
344 oclass = GST_ELEMENT_GET_CLASS (element);
346 /* if the element implements a custom release function we call that, else we
347 * simply remove the pad from the element */
348 if (oclass->release_pad)
349 (oclass->release_pad) (element, pad);
351 gst_element_remove_pad (element, pad);
355 * gst_element_requires_clock:
356 * @element: a #GstElement to query
358 * Query if the element requires a clock.
360 * Returns: %TRUE if the element requires a clock
365 gst_element_requires_clock (GstElement * element)
369 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
371 result = (GST_ELEMENT_GET_CLASS (element)->set_clock != NULL);
377 * gst_element_provides_clock:
378 * @element: a #GstElement to query
380 * Query if the element provides a clock. A #GstClock provided by an
381 * element can be used as the global #GstClock for the pipeline.
382 * An element that can provide a clock is only required to do so in the PAUSED
383 * state, this means when it is fully negotiated and has allocated the resources
384 * to operate the clock.
386 * Returns: %TRUE if the element provides a clock
391 gst_element_provides_clock (GstElement * element)
395 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
397 result = (GST_ELEMENT_GET_CLASS (element)->provide_clock != NULL);
403 * gst_element_provide_clock:
404 * @element: a #GstElement to query
406 * Get the clock provided by the given element.
407 * <note>An element is only required to provide a clock in the PAUSED
408 * state. Some elements can provide a clock in other states.</note>
410 * Returns: the GstClock provided by the element or %NULL
411 * if no clock could be provided. Unref after usage.
416 gst_element_provide_clock (GstElement * element)
418 GstClock *result = NULL;
419 GstElementClass *oclass;
421 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
423 oclass = GST_ELEMENT_GET_CLASS (element);
425 if (oclass->provide_clock)
426 result = oclass->provide_clock (element);
432 * gst_element_set_clock:
433 * @element: a #GstElement to set the clock for.
434 * @clock: the #GstClock to set for the element.
436 * Sets the clock for the element. This function increases the
437 * refcount on the clock. Any previously set clock on the object
440 * Returns: %TRUE if the element accepted the clock. An element can refuse a
441 * clock when it, for example, is not able to slave its internal clock to the
442 * @clock or when it requires a specific clock to operate.
447 gst_element_set_clock (GstElement * element, GstClock * clock)
449 GstElementClass *oclass;
453 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
454 g_return_val_if_fail (clock == NULL || GST_IS_CLOCK (clock), FALSE);
456 oclass = GST_ELEMENT_GET_CLASS (element);
458 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element, "setting clock %p", clock);
460 if (oclass->set_clock)
461 res = oclass->set_clock (element, clock);
464 /* only update the clock pointer if the element accepted the clock */
465 GST_OBJECT_LOCK (element);
466 clock_p = &element->clock;
467 gst_object_replace ((GstObject **) clock_p, (GstObject *) clock);
468 GST_OBJECT_UNLOCK (element);
474 * gst_element_get_clock:
475 * @element: a #GstElement to get the clock of.
477 * Gets the currently configured clock of the element. This is the clock as was
478 * last set with gst_element_set_clock().
480 * Returns: the #GstClock of the element. unref after usage.
485 gst_element_get_clock (GstElement * element)
489 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
491 GST_OBJECT_LOCK (element);
492 if ((result = element->clock))
493 gst_object_ref (result);
494 GST_OBJECT_UNLOCK (element);
500 * gst_element_set_base_time:
501 * @element: a #GstElement.
502 * @time: the base time to set.
504 * Set the base time of an element. See gst_element_get_base_time().
509 gst_element_set_base_time (GstElement * element, GstClockTime time)
513 g_return_if_fail (GST_IS_ELEMENT (element));
515 GST_OBJECT_LOCK (element);
516 old = element->base_time;
517 element->base_time = time;
518 GST_OBJECT_UNLOCK (element);
520 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element,
521 "set base_time=%" GST_TIME_FORMAT ", old %" GST_TIME_FORMAT,
522 GST_TIME_ARGS (time), GST_TIME_ARGS (old));
526 * gst_element_get_base_time:
527 * @element: a #GstElement.
529 * Returns the base time of the element. The base time is the
530 * absolute time of the clock when this element was last put to
531 * PLAYING. Subtracting the base time from the clock time gives
532 * the running time of the element.
534 * Returns: the base time of the element.
539 gst_element_get_base_time (GstElement * element)
543 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_CLOCK_TIME_NONE);
545 GST_OBJECT_LOCK (element);
546 result = element->base_time;
547 GST_OBJECT_UNLOCK (element);
553 * gst_element_set_start_time:
554 * @element: a #GstElement.
555 * @time: the base time to set.
557 * Set the start time of an element. The start time of the element is the
558 * running time of the element when it last went to the PAUSED state. In READY
559 * or after a flushing seek, it is set to 0.
561 * Toplevel elements like #GstPipeline will manage the start_time and
562 * base_time on its children. Setting the start_time to #GST_CLOCK_TIME_NONE
563 * on such a toplevel element will disable the distribution of the base_time to
564 * the children and can be useful if the application manages the base_time
565 * itself, for example if you want to synchronize capture from multiple
566 * pipelines, and you can also ensure that the pipelines have the same clock.
573 gst_element_set_start_time (GstElement * element, GstClockTime time)
577 g_return_if_fail (GST_IS_ELEMENT (element));
579 GST_OBJECT_LOCK (element);
580 old = GST_ELEMENT_START_TIME (element);
581 GST_ELEMENT_START_TIME (element) = time;
582 GST_OBJECT_UNLOCK (element);
584 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element,
585 "set start_time=%" GST_TIME_FORMAT ", old %" GST_TIME_FORMAT,
586 GST_TIME_ARGS (time), GST_TIME_ARGS (old));
590 * gst_element_get_start_time:
591 * @element: a #GstElement.
593 * Returns the start time of the element. The start time is the
594 * running time of the clock when this element was last put to PAUSED.
596 * Usually the start_time is managed by a toplevel element such as
601 * Returns: the start time of the element.
606 gst_element_get_start_time (GstElement * element)
610 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_CLOCK_TIME_NONE);
612 GST_OBJECT_LOCK (element);
613 result = GST_ELEMENT_START_TIME (element);
614 GST_OBJECT_UNLOCK (element);
620 * gst_element_is_indexable:
621 * @element: a #GstElement.
623 * Queries if the element can be indexed.
625 * Returns: TRUE if the element can be indexed.
630 gst_element_is_indexable (GstElement * element)
634 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
636 result = (GST_ELEMENT_GET_CLASS (element)->set_index != NULL);
642 * gst_element_set_index:
643 * @element: a #GstElement.
644 * @index: a #GstIndex.
646 * Set @index on the element. The refcount of the index
647 * will be increased, any previously set index is unreffed.
652 gst_element_set_index (GstElement * element, GstIndex * index)
654 GstElementClass *oclass;
656 g_return_if_fail (GST_IS_ELEMENT (element));
657 g_return_if_fail (index == NULL || GST_IS_INDEX (index));
659 oclass = GST_ELEMENT_GET_CLASS (element);
661 if (oclass->set_index)
662 oclass->set_index (element, index);
666 * gst_element_get_index:
667 * @element: a #GstElement.
669 * Gets the index from the element.
671 * Returns: a #GstIndex or %NULL when no index was set on the
672 * element. unref after usage.
677 gst_element_get_index (GstElement * element)
679 GstElementClass *oclass;
680 GstIndex *result = NULL;
682 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
684 oclass = GST_ELEMENT_GET_CLASS (element);
686 if (oclass->get_index)
687 result = oclass->get_index (element);
693 * gst_element_add_pad:
694 * @element: a #GstElement to add the pad to.
695 * @pad: the #GstPad to add to the element.
697 * Adds a pad (link point) to @element. @pad's parent will be set to @element;
698 * see gst_object_set_parent() for refcounting information.
700 * Pads are not automatically activated so elements should perform the needed
701 * steps to activate the pad in case this pad is added in the PAUSED or PLAYING
702 * state. See gst_pad_set_active() for more information about activating pads.
704 * The pad and the element should be unlocked when calling this function.
706 * This function will emit the #GstElement::pad-added signal on the element.
708 * Returns: %TRUE if the pad could be added. This function can fail when
709 * a pad with the same name already existed or the pad already had another
715 gst_element_add_pad (GstElement * element, GstPad * pad)
720 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
721 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
723 /* locking pad to look at the name */
724 GST_OBJECT_LOCK (pad);
725 pad_name = g_strdup (GST_PAD_NAME (pad));
726 GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element, "adding pad '%s'",
727 GST_STR_NULL (pad_name));
728 flushing = GST_PAD_IS_FLUSHING (pad);
729 GST_OBJECT_UNLOCK (pad);
731 /* then check to see if there's already a pad by that name here */
732 GST_OBJECT_LOCK (element);
733 if (G_UNLIKELY (!gst_object_check_uniqueness (element->pads, pad_name)))
736 /* try to set the pad's parent */
737 if (G_UNLIKELY (!gst_object_set_parent (GST_OBJECT_CAST (pad),
738 GST_OBJECT_CAST (element))))
741 /* check for flushing pads */
742 if (flushing && (GST_STATE (element) > GST_STATE_READY ||
743 GST_STATE_NEXT (element) == GST_STATE_PAUSED)) {
744 g_warning ("adding flushing pad '%s' to running element '%s'",
745 GST_STR_NULL (pad_name), GST_ELEMENT_NAME (element));
747 GST_OBJECT_LOCK (pad);
748 GST_PAD_UNSET_FLUSHING (pad);
749 GST_OBJECT_UNLOCK (pad);
754 /* add it to the list */
755 switch (gst_pad_get_direction (pad)) {
757 element->srcpads = g_list_prepend (element->srcpads, pad);
758 element->numsrcpads++;
761 element->sinkpads = g_list_prepend (element->sinkpads, pad);
762 element->numsinkpads++;
767 element->pads = g_list_prepend (element->pads, pad);
769 element->pads_cookie++;
770 GST_OBJECT_UNLOCK (element);
772 /* emit the PAD_ADDED signal */
773 g_signal_emit (element, gst_element_signals[PAD_ADDED], 0, pad);
780 g_critical ("Padname %s is not unique in element %s, not adding",
781 pad_name, GST_ELEMENT_NAME (element));
782 GST_OBJECT_UNLOCK (element);
789 ("Pad %s already has parent when trying to add to element %s",
790 pad_name, GST_ELEMENT_NAME (element));
791 GST_OBJECT_UNLOCK (element);
797 GST_OBJECT_LOCK (pad);
799 ("Trying to add pad %s to element %s, but it has no direction",
800 GST_OBJECT_NAME (pad), GST_ELEMENT_NAME (element));
801 GST_OBJECT_UNLOCK (pad);
802 GST_OBJECT_UNLOCK (element);
808 * gst_element_remove_pad:
809 * @element: a #GstElement to remove pad from.
810 * @pad: the #GstPad to remove from the element.
812 * Removes @pad from @element. @pad will be destroyed if it has not been
813 * referenced elsewhere using gst_object_unparent().
815 * This function is used by plugin developers and should not be used
816 * by applications. Pads that were dynamically requested from elements
817 * with gst_element_get_request_pad() should be released with the
818 * gst_element_release_request_pad() function instead.
820 * Pads are not automatically deactivated so elements should perform the needed
821 * steps to deactivate the pad in case this pad is removed in the PAUSED or
822 * PLAYING state. See gst_pad_set_active() for more information about
825 * The pad and the element should be unlocked when calling this function.
827 * This function will emit the #GstElement::pad-removed signal on the element.
829 * Returns: %TRUE if the pad could be removed. Can return %FALSE if the
830 * pad does not belong to the provided element.
835 gst_element_remove_pad (GstElement * element, GstPad * pad)
839 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
840 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
842 /* locking pad to look at the name and parent */
843 GST_OBJECT_LOCK (pad);
844 GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element, "removing pad '%s'",
845 GST_STR_NULL (GST_PAD_NAME (pad)));
847 if (G_UNLIKELY (GST_PAD_PARENT (pad) != element))
849 GST_OBJECT_UNLOCK (pad);
852 if ((peer = gst_pad_get_peer (pad))) {
853 /* window for MT unsafeness, someone else could unlink here
854 * and then we call unlink with wrong pads. The unlink
855 * function would catch this and safely return failed. */
856 if (GST_PAD_IS_SRC (pad))
857 gst_pad_unlink (pad, peer);
859 gst_pad_unlink (peer, pad);
861 gst_object_unref (peer);
864 GST_OBJECT_LOCK (element);
865 /* remove it from the list */
866 switch (gst_pad_get_direction (pad)) {
868 element->srcpads = g_list_remove (element->srcpads, pad);
869 element->numsrcpads--;
872 element->sinkpads = g_list_remove (element->sinkpads, pad);
873 element->numsinkpads--;
876 g_critical ("Removing pad without direction???");
879 element->pads = g_list_remove (element->pads, pad);
881 element->pads_cookie++;
882 GST_OBJECT_UNLOCK (element);
884 /* emit the PAD_REMOVED signal before unparenting and losing the last ref. */
885 g_signal_emit (element, gst_element_signals[PAD_REMOVED], 0, pad);
887 gst_object_unparent (GST_OBJECT_CAST (pad));
894 /* FIXME, locking order? */
895 GST_OBJECT_LOCK (element);
896 g_critical ("Padname %s:%s does not belong to element %s when removing",
897 GST_DEBUG_PAD_NAME (pad), GST_ELEMENT_NAME (element));
898 GST_OBJECT_UNLOCK (element);
899 GST_OBJECT_UNLOCK (pad);
905 * gst_element_no_more_pads:
906 * @element: a #GstElement
908 * Use this function to signal that the element does not expect any more pads
909 * to show up in the current pipeline. This function should be called whenever
910 * pads have been added by the element itself. Elements with #GST_PAD_SOMETIMES
911 * pad templates use this in combination with autopluggers to figure out that
912 * the element is done initializing its pads.
914 * This function emits the #GstElement::no-more-pads signal.
919 gst_element_no_more_pads (GstElement * element)
921 g_return_if_fail (GST_IS_ELEMENT (element));
923 g_signal_emit (element, gst_element_signals[NO_MORE_PADS], 0);
927 pad_compare_name (GstPad * pad1, const gchar * name)
931 GST_OBJECT_LOCK (pad1);
932 result = strcmp (GST_PAD_NAME (pad1), name);
933 GST_OBJECT_UNLOCK (pad1);
939 * gst_element_get_static_pad:
940 * @element: a #GstElement to find a static pad of.
941 * @name: the name of the static #GstPad to retrieve.
943 * Retrieves a pad from @element by name. This version only retrieves
944 * already-existing (i.e. 'static') pads.
946 * Returns: the requested #GstPad if found, otherwise %NULL. unref after
952 gst_element_get_static_pad (GstElement * element, const gchar * name)
955 GstPad *result = NULL;
957 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
958 g_return_val_if_fail (name != NULL, NULL);
960 GST_OBJECT_LOCK (element);
962 g_list_find_custom (element->pads, name, (GCompareFunc) pad_compare_name);
964 result = GST_PAD_CAST (find->data);
965 gst_object_ref (result);
968 if (result == NULL) {
969 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "no such pad '%s' in element \"%s\"",
970 name, GST_ELEMENT_NAME (element));
972 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
973 GST_ELEMENT_NAME (element), name);
975 GST_OBJECT_UNLOCK (element);
981 gst_element_request_pad (GstElement * element, GstPadTemplate * templ,
984 GstPad *newpad = NULL;
985 GstElementClass *oclass;
987 oclass = GST_ELEMENT_GET_CLASS (element);
989 if (oclass->request_new_pad)
990 newpad = (oclass->request_new_pad) (element, templ, name);
993 gst_object_ref (newpad);
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.
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().
1007 * Returns: requested #GstPad if found, otherwise %NULL. Release after usage.
1010 gst_element_get_request_pad (GstElement * element, const gchar * name)
1012 GstPadTemplate *templ = NULL;
1014 const gchar *req_name = NULL;
1015 gboolean templ_found = FALSE;
1019 gchar *str, *endptr = NULL;
1020 GstElementClass *class;
1022 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1023 g_return_val_if_fail (name != NULL, NULL);
1025 class = GST_ELEMENT_GET_CLASS (element);
1027 /* if the name contains a %, we assume it's the complete template name. Get
1028 * the template and try to get a pad */
1029 if (strstr (name, "%")) {
1030 templ = gst_element_class_get_request_pad_template (class, name);
1035 /* there is no % in the name, try to find a matching template */
1036 list = gst_element_class_get_pad_template_list (class);
1037 while (!templ_found && list) {
1038 templ = (GstPadTemplate *) list->data;
1039 if (templ->presence == GST_PAD_REQUEST) {
1040 GST_CAT_DEBUG (GST_CAT_PADS, "comparing %s to %s", name,
1041 templ->name_template);
1042 /* see if we find an exact match */
1043 if (strcmp (name, templ->name_template) == 0) {
1048 /* Because of sanity checks in gst_pad_template_new(), we know that %s
1049 and %d, occurring at the end of the name_template, are the only
1051 else if ((str = strchr (templ->name_template, '%'))
1052 && strncmp (templ->name_template, name,
1053 str - templ->name_template) == 0
1054 && strlen (name) > str - templ->name_template) {
1055 data = name + (str - templ->name_template);
1056 if (*(str + 1) == 'd') {
1058 n = (gint) strtol (data, &endptr, 10);
1059 if (endptr && *endptr == '\0') {
1079 pad = gst_element_request_pad (element, templ, req_name);
1085 * gst_element_get_pad:
1086 * @element: a #GstElement.
1087 * @name: the name of the pad to retrieve.
1089 * Retrieves a pad from @element by name. Tries gst_element_get_static_pad()
1090 * first, then gst_element_get_request_pad().
1092 * Deprecated: This function is deprecated as it's unclear if the reference
1093 * to the result pad should be released with gst_object_unref() in case of a static pad
1094 * or gst_element_release_request_pad() in case of a request pad.
1095 * Use gst_element_get_static_pad() or gst_element_get_request_pad() instead.
1097 * Returns: the #GstPad if found, otherwise %NULL. Unref or Release after usage,
1098 * depending on the type of the pad.
1100 #ifndef GST_REMOVE_DEPRECATED
1102 gst_element_get_pad (GstElement * element, const gchar * name)
1106 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1107 g_return_val_if_fail (name != NULL, NULL);
1109 pad = gst_element_get_static_pad (element, name);
1111 pad = gst_element_get_request_pad (element, name);
1115 #endif /* GST_REMOVE_DEPRECATED */
1117 static GstIteratorItem
1118 iterate_pad (GstIterator * it, GstPad * pad)
1120 gst_object_ref (pad);
1121 return GST_ITERATOR_ITEM_PASS;
1124 static GstIterator *
1125 gst_element_iterate_pad_list (GstElement * element, GList ** padlist)
1127 GstIterator *result;
1129 GST_OBJECT_LOCK (element);
1130 gst_object_ref (element);
1131 result = gst_iterator_new_list (GST_TYPE_PAD,
1132 GST_OBJECT_GET_LOCK (element),
1133 &element->pads_cookie,
1136 (GstIteratorItemFunction) iterate_pad,
1137 (GstIteratorDisposeFunction) gst_object_unref);
1138 GST_OBJECT_UNLOCK (element);
1144 * gst_element_iterate_pads:
1145 * @element: a #GstElement to iterate pads of.
1147 * Retrieves an iterattor of @element's pads. The iterator should
1148 * be freed after usage.
1150 * Returns: the #GstIterator of #GstPad. Unref each pad after use.
1155 gst_element_iterate_pads (GstElement * element)
1157 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1159 return gst_element_iterate_pad_list (element, &element->pads);
1163 * gst_element_iterate_src_pads:
1164 * @element: a #GstElement.
1166 * Retrieves an iterator of @element's source pads.
1168 * Returns: the #GstIterator of #GstPad. Unref each pad after use.
1173 gst_element_iterate_src_pads (GstElement * element)
1175 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1177 return gst_element_iterate_pad_list (element, &element->srcpads);
1181 * gst_element_iterate_sink_pads:
1182 * @element: a #GstElement.
1184 * Retrieves an iterator of @element's sink pads.
1186 * Returns: the #GstIterator of #GstPad. Unref each pad after use.
1191 gst_element_iterate_sink_pads (GstElement * element)
1193 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1195 return gst_element_iterate_pad_list (element, &element->sinkpads);
1199 * gst_element_class_add_pad_template:
1200 * @klass: the #GstElementClass to add the pad template to.
1201 * @templ: a #GstPadTemplate to add to the element class.
1203 * Adds a padtemplate to an element class. This is mainly used in the _base_init
1204 * functions of classes.
1207 gst_element_class_add_pad_template (GstElementClass * klass,
1208 GstPadTemplate * templ)
1210 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1211 g_return_if_fail (GST_IS_PAD_TEMPLATE (templ));
1213 /* FIXME 0.11: allow replacing the pad templates by
1214 * calling this with the same name as an already existing pad
1215 * template. For this we _must_ _not_ ref the added pad template
1216 * a second time and _must_ document that this function takes
1217 * ownership of the pad template. Otherwise we will leak pad templates
1218 * or the caller unref's the pad template and it disappears */
1219 /* avoid registering pad templates with the same name */
1220 g_return_if_fail (gst_element_class_get_pad_template (klass,
1221 templ->name_template) == NULL);
1223 klass->padtemplates = g_list_append (klass->padtemplates,
1224 gst_object_ref (templ));
1225 klass->numpadtemplates++;
1229 * gst_element_class_set_details:
1230 * @klass: class to set details for
1231 * @details: details to set
1233 * Sets the detailed information for a #GstElementClass.
1234 * <note>This function is for use in _base_init functions only.</note>
1236 * The @details are copied.
1239 gst_element_class_set_details (GstElementClass * klass,
1240 const GstElementDetails * details)
1242 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1243 g_return_if_fail (GST_IS_ELEMENT_DETAILS (details));
1245 __gst_element_details_copy (&klass->details, details);
1249 * gst_element_class_set_details_simple:
1250 * @klass: class to set details for
1251 * @longname: The long English name of the element. E.g. "File Sink"
1252 * @classification: String describing the type of element, as an unordered list
1253 * separated with slashes ('/'). See draft-klass.txt of the design docs
1254 * for more details and common types. E.g: "Sink/File"
1255 * @description: Sentence describing the purpose of the element.
1256 * E.g: "Write stream to a file"
1257 * @author: Name and contact details of the author(s). Use \n to separate
1258 * multiple author details. E.g: "Joe Bloggs <joe.blogs at foo.com>"
1260 * Sets the detailed information for a #GstElementClass. Simpler version of
1261 * gst_element_class_set_details() that generates less linker overhead.
1262 * <note>This function is for use in _base_init functions only.</note>
1264 * The detail parameter strings are copied into the #GstElementDetails for
1265 * the element class.
1270 gst_element_class_set_details_simple (GstElementClass * klass,
1271 const gchar * longname, const gchar * classification,
1272 const gchar * description, const gchar * author)
1274 const GstElementDetails details =
1275 GST_ELEMENT_DETAILS ((gchar *) longname, (gchar *) classification,
1276 (gchar *) description, (gchar *) author);
1278 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1280 __gst_element_details_copy (&klass->details, &details);
1284 * gst_element_class_get_pad_template_list:
1285 * @element_class: a #GstElementClass to get pad templates of.
1287 * Retrieves a list of the pad templates associated with @element_class. The
1288 * list must not be modified by the calling code.
1289 * <note>If you use this function in the #GInstanceInitFunc of an object class
1290 * that has subclasses, make sure to pass the g_class parameter of the
1291 * #GInstanceInitFunc here.</note>
1293 * Returns: the #GList of padtemplates.
1296 gst_element_class_get_pad_template_list (GstElementClass * element_class)
1298 g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1300 return element_class->padtemplates;
1304 * gst_element_class_get_pad_template:
1305 * @element_class: a #GstElementClass to get the pad template of.
1306 * @name: the name of the #GstPadTemplate to get.
1308 * Retrieves a padtemplate from @element_class with the given name.
1309 * <note>If you use this function in the #GInstanceInitFunc of an object class
1310 * that has subclasses, make sure to pass the g_class parameter of the
1311 * #GInstanceInitFunc here.</note>
1313 * Returns: the #GstPadTemplate with the given name, or %NULL if none was found.
1314 * No unreferencing is necessary.
1317 gst_element_class_get_pad_template (GstElementClass * element_class,
1322 g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1323 g_return_val_if_fail (name != NULL, NULL);
1325 padlist = gst_element_class_get_pad_template_list (element_class);
1328 GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
1330 if (strcmp (padtempl->name_template, name) == 0)
1333 padlist = g_list_next (padlist);
1339 static GstPadTemplate *
1340 gst_element_class_get_request_pad_template (GstElementClass * element_class,
1343 GstPadTemplate *tmpl;
1345 tmpl = gst_element_class_get_pad_template (element_class, name);
1346 if (tmpl != NULL && tmpl->presence == GST_PAD_REQUEST)
1352 /* get a random pad on element of the given direction.
1353 * The pad is random in a sense that it is the first pad that is (optionaly) linked.
1356 gst_element_get_random_pad (GstElement * element, gboolean need_linked,
1357 GstPadDirection dir)
1359 GstPad *result = NULL;
1362 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "getting a random pad");
1366 GST_OBJECT_LOCK (element);
1367 pads = element->srcpads;
1370 GST_OBJECT_LOCK (element);
1371 pads = element->sinkpads;
1374 goto wrong_direction;
1376 for (; pads; pads = g_list_next (pads)) {
1377 GstPad *pad = GST_PAD_CAST (pads->data);
1379 GST_OBJECT_LOCK (pad);
1380 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "checking pad %s:%s",
1381 GST_DEBUG_PAD_NAME (pad));
1383 if (need_linked && !GST_PAD_IS_LINKED (pad)) {
1384 /* if we require a linked pad, and it is not linked, continue the
1386 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is not linked",
1387 GST_DEBUG_PAD_NAME (pad));
1388 GST_OBJECT_UNLOCK (pad);
1391 /* found a pad, stop search */
1392 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
1393 GST_DEBUG_PAD_NAME (pad));
1394 GST_OBJECT_UNLOCK (pad);
1400 gst_object_ref (result);
1402 GST_OBJECT_UNLOCK (element);
1406 /* ERROR handling */
1409 g_warning ("unknown pad direction %d", dir);
1415 gst_element_default_send_event (GstElement * element, GstEvent * event)
1417 gboolean result = FALSE;
1420 pad = GST_EVENT_IS_DOWNSTREAM (event) ?
1421 gst_element_get_random_pad (element, TRUE, GST_PAD_SRC) :
1422 gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1425 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1426 "pushing %s event to random %s pad %s:%s",
1427 GST_EVENT_TYPE_NAME (event),
1428 (GST_PAD_DIRECTION (pad) == GST_PAD_SRC ? "src" : "sink"),
1429 GST_DEBUG_PAD_NAME (pad));
1431 result = gst_pad_push_event (pad, event);
1432 gst_object_unref (pad);
1434 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "can't send %s event on element %s",
1435 GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1441 * gst_element_send_event:
1442 * @element: a #GstElement to send the event to.
1443 * @event: the #GstEvent to send to the element.
1445 * Sends an event to an element. If the element doesn't implement an
1446 * event handler, the event will be pushed on a random linked sink pad for
1447 * upstream events or a random linked source pad for downstream events.
1449 * This function takes owership of the provided event so you should
1450 * gst_event_ref() it if you want to reuse the event after this call.
1452 * Returns: %TRUE if the event was handled.
1457 gst_element_send_event (GstElement * element, GstEvent * event)
1459 GstElementClass *oclass;
1460 gboolean result = FALSE;
1462 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1463 g_return_val_if_fail (event != NULL, FALSE);
1465 oclass = GST_ELEMENT_GET_CLASS (element);
1467 GST_STATE_LOCK (element);
1468 if (oclass->send_event) {
1469 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send %s event on element %s",
1470 GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1471 result = oclass->send_event (element, event);
1473 result = gst_element_default_send_event (element, event);
1475 GST_STATE_UNLOCK (element);
1482 * @element: a #GstElement to send the event to.
1483 * @rate: The new playback rate
1484 * @format: The format of the seek values
1485 * @flags: The optional seek flags.
1486 * @cur_type: The type and flags for the new current position
1487 * @cur: The value of the new current position
1488 * @stop_type: The type and flags for the new stop position
1489 * @stop: The value of the new stop position
1491 * Sends a seek event to an element. See gst_event_new_seek() for the details of
1492 * the parameters. The seek event is sent to the element using
1493 * gst_element_send_event().
1495 * Returns: %TRUE if the event was handled.
1500 gst_element_seek (GstElement * element, gdouble rate, GstFormat format,
1501 GstSeekFlags flags, GstSeekType cur_type, gint64 cur,
1502 GstSeekType stop_type, gint64 stop)
1507 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1510 gst_event_new_seek (rate, format, flags, cur_type, cur, stop_type, stop);
1511 result = gst_element_send_event (element, event);
1517 * gst_element_get_query_types:
1518 * @element: a #GstElement to query
1520 * Get an array of query types from the element.
1521 * If the element doesn't implement a query types function,
1522 * the query will be forwarded to the peer of a random linked sink pad.
1524 * Returns: An array of #GstQueryType elements that should not
1525 * be freed or modified.
1529 const GstQueryType *
1530 gst_element_get_query_types (GstElement * element)
1532 GstElementClass *oclass;
1533 const GstQueryType *result = NULL;
1535 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1537 oclass = GST_ELEMENT_GET_CLASS (element);
1539 if (oclass->get_query_types) {
1540 result = oclass->get_query_types (element);
1542 GstPad *pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1545 GstPad *peer = gst_pad_get_peer (pad);
1548 result = gst_pad_get_query_types (peer);
1550 gst_object_unref (peer);
1552 gst_object_unref (pad);
1559 gst_element_default_query (GstElement * element, GstQuery * query)
1561 gboolean result = FALSE;
1564 pad = gst_element_get_random_pad (element, FALSE, GST_PAD_SRC);
1566 result = gst_pad_query (pad, query);
1568 gst_object_unref (pad);
1570 pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1572 GstPad *peer = gst_pad_get_peer (pad);
1575 result = gst_pad_query (peer, query);
1577 gst_object_unref (peer);
1579 gst_object_unref (pad);
1586 * gst_element_query:
1587 * @element: a #GstElement to perform the query on.
1588 * @query: the #GstQuery.
1590 * Performs a query on the given element.
1592 * For elements that don't implement a query handler, this function
1593 * forwards the query to a random srcpad or to the peer of a
1594 * random linked sinkpad of this element.
1596 * Returns: TRUE if the query could be performed.
1601 gst_element_query (GstElement * element, GstQuery * query)
1603 GstElementClass *oclass;
1604 gboolean result = FALSE;
1606 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1607 g_return_val_if_fail (query != NULL, FALSE);
1609 oclass = GST_ELEMENT_GET_CLASS (element);
1611 if (oclass->query) {
1612 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send query on element %s",
1613 GST_ELEMENT_NAME (element));
1614 result = oclass->query (element, query);
1616 result = gst_element_default_query (element, query);
1622 * gst_element_post_message:
1623 * @element: a #GstElement posting the message
1624 * @message: a #GstMessage to post
1626 * Post a message on the element's #GstBus. This function takes ownership of the
1627 * message; if you want to access the message after this call, you should add an
1628 * additional reference before calling.
1630 * Returns: %TRUE if the message was successfully posted. The function returns
1631 * %FALSE if the element did not have a bus.
1636 gst_element_post_message (GstElement * element, GstMessage * message)
1639 gboolean result = FALSE;
1641 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1642 g_return_val_if_fail (message != NULL, FALSE);
1644 GST_OBJECT_LOCK (element);
1647 if (G_UNLIKELY (bus == NULL))
1650 gst_object_ref (bus);
1651 GST_OBJECT_UNLOCK (element);
1653 /* we release the element lock when posting the message so that any
1654 * (synchronous) message handlers can operate on the element */
1655 result = gst_bus_post (bus, message);
1656 gst_object_unref (bus);
1663 GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element,
1664 "not posting message %p: no bus", message);
1665 GST_OBJECT_UNLOCK (element);
1666 gst_message_unref (message);
1672 * _gst_element_error_printf:
1673 * @format: the printf-like format to use, or %NULL
1675 * This function is only used internally by the gst_element_error() macro.
1677 * Returns: a newly allocated string, or %NULL if the format was %NULL or ""
1682 _gst_element_error_printf (const gchar * format, ...)
1692 va_start (args, format);
1693 buffer = g_strdup_vprintf (format, args);
1699 * gst_element_message_full:
1700 * @element: a #GstElement to send message from
1701 * @type: the #GstMessageType
1702 * @domain: the GStreamer GError domain this message belongs to
1703 * @code: the GError code belonging to the domain
1704 * @text: an allocated text string to be used as a replacement for the
1705 * default message connected to code, or %NULL
1706 * @debug: an allocated debug message to be used as a replacement for the
1707 * default debugging information, or %NULL
1708 * @file: the source code file where the error was generated
1709 * @function: the source code function where the error was generated
1710 * @line: the source code line where the error was generated
1712 * Post an error, warning or info message on the bus from inside an element.
1714 * @type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or
1715 * #GST_MESSAGE_INFO.
1719 void gst_element_message_full
1720 (GstElement * element, GstMessageType type,
1721 GQuark domain, gint code, gchar * text,
1722 gchar * debug, const gchar * file, const gchar * function, gint line)
1724 GError *gerror = NULL;
1728 gboolean has_debug = TRUE;
1729 GstMessage *message = NULL;
1732 GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element, "start");
1733 g_return_if_fail (GST_IS_ELEMENT (element));
1734 g_return_if_fail ((type == GST_MESSAGE_ERROR) ||
1735 (type == GST_MESSAGE_WARNING) || (type == GST_MESSAGE_INFO));
1737 /* check if we send the given text or the default error text */
1738 if ((text == NULL) || (text[0] == 0)) {
1739 /* text could have come from g_strdup_printf (""); */
1741 sent_text = gst_error_get_message (domain, code);
1745 /* construct a sent_debug with extra information from source */
1746 if ((debug == NULL) || (debug[0] == 0)) {
1747 /* debug could have come from g_strdup_printf (""); */
1751 name = gst_object_get_path_string (GST_OBJECT_CAST (element));
1753 sent_debug = g_strdup_printf ("%s(%d): %s (): %s:\n%s",
1754 file, line, function, name, debug);
1756 sent_debug = g_strdup_printf ("%s(%d): %s (): %s",
1757 file, line, function, name);
1761 /* create gerror and post message */
1762 GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posting message: %s",
1764 gerror = g_error_new_literal (domain, code, sent_text);
1767 case GST_MESSAGE_ERROR:
1769 gst_message_new_error (GST_OBJECT_CAST (element), gerror, sent_debug);
1771 case GST_MESSAGE_WARNING:
1772 message = gst_message_new_warning (GST_OBJECT_CAST (element), gerror,
1775 case GST_MESSAGE_INFO:
1776 message = gst_message_new_info (GST_OBJECT_CAST (element), gerror,
1780 g_assert_not_reached ();
1783 gst_element_post_message (element, message);
1785 GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posted %s message: %s",
1786 (type == GST_MESSAGE_ERROR ? "error" : "warning"), sent_text);
1789 g_error_free (gerror);
1790 g_free (sent_debug);
1795 * gst_element_is_locked_state:
1796 * @element: a #GstElement.
1798 * Checks if the state of an element is locked.
1799 * If the state of an element is locked, state changes of the parent don't
1800 * affect the element.
1801 * This way you can leave currently unused elements inside bins. Just lock their
1802 * state before changing the state from #GST_STATE_NULL.
1806 * Returns: TRUE, if the element's state is locked.
1809 gst_element_is_locked_state (GstElement * element)
1813 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1815 GST_OBJECT_LOCK (element);
1816 result = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
1817 GST_OBJECT_UNLOCK (element);
1823 * gst_element_set_locked_state:
1824 * @element: a #GstElement
1825 * @locked_state: TRUE to lock the element's state
1827 * Locks the state of an element, so state changes of the parent don't affect
1828 * this element anymore.
1832 * Returns: TRUE if the state was changed, FALSE if bad parameters were given
1833 * or the elements state-locking needed no change.
1836 gst_element_set_locked_state (GstElement * element, gboolean locked_state)
1840 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1842 GST_OBJECT_LOCK (element);
1843 old = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
1845 if (G_UNLIKELY (old == locked_state))
1849 GST_CAT_DEBUG (GST_CAT_STATES, "locking state of element %s",
1850 GST_ELEMENT_NAME (element));
1851 GST_OBJECT_FLAG_SET (element, GST_ELEMENT_LOCKED_STATE);
1853 GST_CAT_DEBUG (GST_CAT_STATES, "unlocking state of element %s",
1854 GST_ELEMENT_NAME (element));
1855 GST_OBJECT_FLAG_UNSET (element, GST_ELEMENT_LOCKED_STATE);
1857 GST_OBJECT_UNLOCK (element);
1863 GST_CAT_DEBUG (GST_CAT_STATES, "elements %s was already in locked state %d",
1864 GST_ELEMENT_NAME (element), old);
1865 GST_OBJECT_UNLOCK (element);
1872 * gst_element_sync_state_with_parent:
1873 * @element: a #GstElement.
1875 * Tries to change the state of the element to the same as its parent.
1876 * If this function returns FALSE, the state of element is undefined.
1878 * Returns: TRUE, if the element's state could be synced to the parent's state.
1883 gst_element_sync_state_with_parent (GstElement * element)
1887 GstStateChangeReturn ret;
1889 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1891 if ((parent = GST_ELEMENT_CAST (gst_element_get_parent (element)))) {
1892 GstState parent_current, parent_pending;
1894 GST_OBJECT_LOCK (parent);
1895 parent_current = GST_STATE (parent);
1896 parent_pending = GST_STATE_PENDING (parent);
1897 GST_OBJECT_UNLOCK (parent);
1899 /* set to pending if there is one, else we set it to the current state of
1901 if (parent_pending != GST_STATE_VOID_PENDING)
1902 target = parent_pending;
1904 target = parent_current;
1906 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
1907 "syncing state (%s) to parent %s %s (%s, %s)",
1908 gst_element_state_get_name (GST_STATE (element)),
1909 GST_ELEMENT_NAME (parent), gst_element_state_get_name (target),
1910 gst_element_state_get_name (parent_current),
1911 gst_element_state_get_name (parent_pending));
1913 ret = gst_element_set_state (element, target);
1914 if (ret == GST_STATE_CHANGE_FAILURE)
1917 gst_object_unref (parent);
1921 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "element has no parent");
1928 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
1929 "syncing state failed (%s)",
1930 gst_element_state_change_return_get_name (ret));
1931 gst_object_unref (parent);
1937 static GstStateChangeReturn
1938 gst_element_get_state_func (GstElement * element,
1939 GstState * state, GstState * pending, GstClockTime timeout)
1941 GstStateChangeReturn ret = GST_STATE_CHANGE_FAILURE;
1942 GstState old_pending;
1944 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "getting state, timeout %"
1945 GST_TIME_FORMAT, GST_TIME_ARGS (timeout));
1947 GST_OBJECT_LOCK (element);
1948 ret = GST_STATE_RETURN (element);
1949 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "RETURN is %s",
1950 gst_element_state_change_return_get_name (ret));
1952 /* we got an error, report immediatly */
1953 if (ret == GST_STATE_CHANGE_FAILURE)
1956 /* we got no_preroll, report immediatly */
1957 if (ret == GST_STATE_CHANGE_NO_PREROLL)
1960 /* no need to wait async if we are not async */
1961 if (ret != GST_STATE_CHANGE_ASYNC)
1964 old_pending = GST_STATE_PENDING (element);
1965 if (old_pending != GST_STATE_VOID_PENDING) {
1966 GTimeVal *timeval, abstimeout;
1969 if (timeout != GST_CLOCK_TIME_NONE) {
1970 glong add = timeout / 1000;
1975 /* make timeout absolute */
1976 g_get_current_time (&abstimeout);
1977 g_time_val_add (&abstimeout, add);
1978 timeval = &abstimeout;
1982 /* get cookie to detect state changes during waiting */
1983 cookie = element->state_cookie;
1985 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1986 "waiting for element to commit state");
1988 /* we have a pending state change, wait for it to complete */
1989 if (!GST_STATE_TIMED_WAIT (element, timeval)) {
1990 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "timed out");
1991 /* timeout triggered */
1992 ret = GST_STATE_CHANGE_ASYNC;
1994 if (cookie != element->state_cookie)
1997 /* could be success or failure */
1998 if (old_pending == GST_STATE (element)) {
1999 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got success");
2000 ret = GST_STATE_CHANGE_SUCCESS;
2002 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got failure");
2003 ret = GST_STATE_CHANGE_FAILURE;
2006 /* if nothing is pending anymore we can return SUCCESS */
2007 if (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING) {
2008 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "nothing pending");
2009 ret = GST_STATE_CHANGE_SUCCESS;
2015 *state = GST_STATE (element);
2017 *pending = GST_STATE_PENDING (element);
2019 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2020 "state current: %s, pending: %s, result: %s",
2021 gst_element_state_get_name (GST_STATE (element)),
2022 gst_element_state_get_name (GST_STATE_PENDING (element)),
2023 gst_element_state_change_return_get_name (ret));
2024 GST_OBJECT_UNLOCK (element);
2031 *state = GST_STATE_VOID_PENDING;
2033 *pending = GST_STATE_VOID_PENDING;
2035 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "interruped");
2037 GST_OBJECT_UNLOCK (element);
2039 return GST_STATE_CHANGE_FAILURE;
2044 * gst_element_get_state:
2045 * @element: a #GstElement to get the state of.
2046 * @state: a pointer to #GstState to hold the state. Can be %NULL.
2047 * @pending: a pointer to #GstState to hold the pending state.
2049 * @timeout: a #GstClockTime to specify the timeout for an async
2050 * state change or %GST_CLOCK_TIME_NONE for infinite timeout.
2052 * Gets the state of the element.
2054 * For elements that performed an ASYNC state change, as reported by
2055 * gst_element_set_state(), this function will block up to the
2056 * specified timeout value for the state change to complete.
2057 * If the element completes the state change or goes into
2058 * an error, this function returns immediately with a return value of
2059 * %GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively.
2061 * For elements that did not return %GST_STATE_CHANGE_ASYNC, this function
2062 * returns the current and pending state immediately.
2064 * This function returns %GST_STATE_CHANGE_NO_PREROLL if the element
2065 * successfully changed its state but is not able to provide data yet.
2066 * This mostly happens for live sources that only produce data in the PLAYING
2067 * state. While the state change return is equivalent to
2068 * %GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that
2069 * some sink elements might not be able to complete their state change because
2070 * an element is not producing data to complete the preroll. When setting the
2071 * element to playing, the preroll will complete and playback will start.
2073 * Returns: %GST_STATE_CHANGE_SUCCESS if the element has no more pending state
2074 * and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the
2075 * element is still performing a state change or
2076 * %GST_STATE_CHANGE_FAILURE if the last state change failed.
2080 GstStateChangeReturn
2081 gst_element_get_state (GstElement * element,
2082 GstState * state, GstState * pending, GstClockTime timeout)
2084 GstElementClass *oclass;
2085 GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2087 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2089 oclass = GST_ELEMENT_GET_CLASS (element);
2091 if (oclass->get_state)
2092 result = (oclass->get_state) (element, state, pending, timeout);
2098 * gst_element_abort_state:
2099 * @element: a #GstElement to abort the state of.
2101 * Abort the state change of the element. This function is used
2102 * by elements that do asynchronous state changes and find out
2103 * something is wrong.
2105 * This function should be called with the STATE_LOCK held.
2110 gst_element_abort_state (GstElement * element)
2114 #ifndef GST_DISABLE_GST_DEBUG
2118 g_return_if_fail (GST_IS_ELEMENT (element));
2120 GST_OBJECT_LOCK (element);
2121 pending = GST_STATE_PENDING (element);
2123 if (pending == GST_STATE_VOID_PENDING ||
2124 GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2125 goto nothing_aborted;
2127 #ifndef GST_DISABLE_GST_DEBUG
2128 old_state = GST_STATE (element);
2130 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2131 "aborting state from %s to %s", gst_element_state_get_name (old_state),
2132 gst_element_state_get_name (pending));
2136 GST_STATE_RETURN (element) = GST_STATE_CHANGE_FAILURE;
2138 GST_STATE_BROADCAST (element);
2139 GST_OBJECT_UNLOCK (element);
2145 GST_OBJECT_UNLOCK (element);
2151 * gst_element_continue_state:
2152 * @element: a #GstElement to continue the state change of.
2153 * @ret: The previous state return value
2155 * Commit the state change of the element and proceed to the next
2156 * pending state if any. This function is used
2157 * by elements that do asynchronous state changes.
2158 * The core will normally call this method automatically when an
2159 * element returned %GST_STATE_CHANGE_SUCCESS from the state change function.
2161 * If after calling this method the element still has not reached
2162 * the pending state, the next state change is performed.
2164 * This method is used internally and should normally not be called by plugins
2167 * Returns: The result of the commit state change.
2171 GstStateChangeReturn
2172 gst_element_continue_state (GstElement * element, GstStateChangeReturn ret)
2174 GstStateChangeReturn old_ret;
2175 GstState old_state, old_next;
2176 GstState current, next, pending;
2177 GstMessage *message;
2178 GstStateChange transition;
2180 GST_OBJECT_LOCK (element);
2181 old_ret = GST_STATE_RETURN (element);
2182 GST_STATE_RETURN (element) = ret;
2183 pending = GST_STATE_PENDING (element);
2185 /* check if there is something to commit */
2186 if (pending == GST_STATE_VOID_PENDING)
2187 goto nothing_pending;
2189 old_state = GST_STATE (element);
2190 /* this is the state we should go to next */
2191 old_next = GST_STATE_NEXT (element);
2192 /* update current state */
2193 current = GST_STATE (element) = old_next;
2195 /* see if we reached the final state */
2196 if (pending == current)
2199 next = GST_STATE_GET_NEXT (current, pending);
2200 transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2202 GST_STATE_NEXT (element) = next;
2204 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2205 GST_OBJECT_UNLOCK (element);
2207 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2208 "committing state from %s to %s, pending %s, next %s",
2209 gst_element_state_get_name (old_state),
2210 gst_element_state_get_name (old_next),
2211 gst_element_state_get_name (pending), gst_element_state_get_name (next));
2213 message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2214 old_state, old_next, pending);
2215 gst_element_post_message (element, message);
2217 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2218 "continue state change %s to %s, final %s",
2219 gst_element_state_get_name (current),
2220 gst_element_state_get_name (next), gst_element_state_get_name (pending));
2222 ret = gst_element_change_state (element, transition);
2228 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "nothing pending");
2229 GST_OBJECT_UNLOCK (element);
2234 GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2235 GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2237 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2238 "completed state change to %s", gst_element_state_get_name (pending));
2239 GST_OBJECT_UNLOCK (element);
2241 /* don't post silly messages with the same state. This can happen
2242 * when an element state is changed to what it already was. For bins
2243 * this can be the result of a lost state, which we check with the
2244 * previous return value.
2245 * We do signal the cond though as a _get_state() might be blocking
2247 if (old_state != old_next || old_ret == GST_STATE_CHANGE_ASYNC) {
2248 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2249 "posting state-changed %s to %s",
2250 gst_element_state_get_name (old_state),
2251 gst_element_state_get_name (old_next));
2253 gst_message_new_state_changed (GST_OBJECT_CAST (element), old_state,
2254 old_next, GST_STATE_VOID_PENDING);
2255 gst_element_post_message (element, message);
2258 GST_STATE_BROADCAST (element);
2265 * gst_element_lost_state_full:
2266 * @element: a #GstElement the state is lost of
2267 * @new_base_time: if a new base time should be distributed
2269 * Brings the element to the lost state. The current state of the
2270 * element is copied to the pending state so that any call to
2271 * gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC.
2273 * An ASYNC_START message is posted with indication to distribute a new
2274 * base_time to the element when @new_base_time is %TRUE.
2275 * If the element was PLAYING, it will go to PAUSED. The element
2276 * will be restored to its PLAYING state by the parent pipeline when it
2279 * This is mostly used for elements that lost their preroll buffer
2280 * in the %GST_STATE_PAUSED or %GST_STATE_PLAYING state after a flush,
2281 * they will go to their pending state again when a new preroll buffer is
2282 * queued. This function can only be called when the element is currently
2283 * not in error or an async state change.
2285 * This function is used internally and should normally not be called from
2286 * plugins or applications.
2293 gst_element_lost_state_full (GstElement * element, gboolean new_base_time)
2295 GstState old_state, new_state;
2296 GstMessage *message;
2298 g_return_if_fail (GST_IS_ELEMENT (element));
2300 GST_OBJECT_LOCK (element);
2301 if (GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2304 if (GST_STATE_PENDING (element) != GST_STATE_VOID_PENDING)
2305 goto only_async_start;
2307 old_state = GST_STATE (element);
2309 /* when we were PLAYING, the new state is PAUSED. We will also not
2310 * automatically go to PLAYING but let the parent bin(s) set us to PLAYING
2311 * when we preroll. */
2312 if (old_state > GST_STATE_PAUSED)
2313 new_state = GST_STATE_PAUSED;
2315 new_state = old_state;
2317 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2318 "lost state of %s to %s", gst_element_state_get_name (old_state),
2319 gst_element_state_get_name (new_state));
2321 GST_STATE (element) = new_state;
2322 GST_STATE_NEXT (element) = new_state;
2323 GST_STATE_PENDING (element) = new_state;
2324 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2326 GST_ELEMENT_START_TIME (element) = 0;
2327 GST_OBJECT_UNLOCK (element);
2329 message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2330 new_state, new_state, new_state);
2331 gst_element_post_message (element, message);
2334 gst_message_new_async_start (GST_OBJECT_CAST (element), new_base_time);
2335 gst_element_post_message (element, message);
2341 GST_OBJECT_UNLOCK (element);
2346 GST_OBJECT_UNLOCK (element);
2348 message = gst_message_new_async_start (GST_OBJECT_CAST (element), TRUE);
2349 gst_element_post_message (element, message);
2355 * gst_element_lost_state:
2356 * @element: a #GstElement the state is lost of
2358 * Brings the element to the lost state. This function calls
2359 * gst_element_lost_state_full() with the new_base_time set to %TRUE.
2361 * This function is used internally and should normally not be called from
2362 * plugins or applications.
2367 gst_element_lost_state (GstElement * element)
2369 gst_element_lost_state_full (element, TRUE);
2373 * gst_element_set_state:
2374 * @element: a #GstElement to change state of.
2375 * @state: the element's new #GstState.
2377 * Sets the state of the element. This function will try to set the
2378 * requested state by going through all the intermediary states and calling
2379 * the class's state change function for each.
2381 * This function can return #GST_STATE_CHANGE_ASYNC, in which case the
2382 * element will perform the remainder of the state change asynchronously in
2384 * An application can use gst_element_get_state() to wait for the completion
2385 * of the state change or it can wait for a state change message on the bus.
2387 * State changes to %GST_STATE_READY or %GST_STATE_NULL never return
2388 * #GST_STATE_CHANGE_ASYNC.
2390 * Returns: Result of the state change using #GstStateChangeReturn.
2394 GstStateChangeReturn
2395 gst_element_set_state (GstElement * element, GstState state)
2397 GstElementClass *oclass;
2398 GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2400 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2402 oclass = GST_ELEMENT_GET_CLASS (element);
2404 if (oclass->set_state)
2405 result = (oclass->set_state) (element, state);
2411 * default set state function, calculates the next state based
2412 * on current state and calls the change_state function
2414 static GstStateChangeReturn
2415 gst_element_set_state_func (GstElement * element, GstState state)
2417 GstState current, next, old_pending;
2418 GstStateChangeReturn ret;
2419 GstStateChange transition;
2420 GstStateChangeReturn old_ret;
2422 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2424 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "set_state to %s",
2425 gst_element_state_get_name (state));
2427 /* state lock is taken to protect the set_state() and get_state()
2428 * procedures, it does not lock any variables. */
2429 GST_STATE_LOCK (element);
2431 /* now calculate how to get to the new state */
2432 GST_OBJECT_LOCK (element);
2433 old_ret = GST_STATE_RETURN (element);
2434 /* previous state change returned an error, remove all pending
2435 * and next states */
2436 if (old_ret == GST_STATE_CHANGE_FAILURE) {
2437 GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2438 GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2439 GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
2442 current = GST_STATE (element);
2443 next = GST_STATE_NEXT (element);
2444 old_pending = GST_STATE_PENDING (element);
2446 /* this is the (new) state we should go to. TARGET is the last state we set on
2448 if (state != GST_STATE_TARGET (element)) {
2449 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2450 "setting target state to %s", gst_element_state_get_name (state));
2451 GST_STATE_TARGET (element) = state;
2452 /* increment state cookie so that we can track each state change. We only do
2453 * this if this is actually a new state change. */
2454 element->state_cookie++;
2456 GST_STATE_PENDING (element) = state;
2458 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2459 "current %s, old_pending %s, next %s, old return %s",
2460 gst_element_state_get_name (current),
2461 gst_element_state_get_name (old_pending),
2462 gst_element_state_get_name (next),
2463 gst_element_state_change_return_get_name (old_ret));
2465 /* if the element was busy doing a state change, we just update the
2466 * target state, it'll get to it async then. */
2467 if (old_pending != GST_STATE_VOID_PENDING) {
2468 /* upwards state change will happen ASYNC */
2469 if (old_pending <= state)
2471 /* element is going to this state already */
2472 else if (next == state)
2474 /* element was performing an ASYNC upward state change and
2475 * we request to go downward again. Start from the next pending
2477 else if (next > state
2478 && GST_STATE_RETURN (element) == GST_STATE_CHANGE_ASYNC) {
2482 next = GST_STATE_GET_NEXT (current, state);
2483 /* now we store the next state */
2484 GST_STATE_NEXT (element) = next;
2485 /* mark busy, we need to check that there is actually a state change
2486 * to be done else we could accidentally override SUCCESS/NO_PREROLL and
2487 * the default element change_state function has no way to know what the
2488 * old value was... could consider this a FIXME...*/
2489 if (current != next)
2490 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2492 transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2494 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2495 "%s: setting state from %s to %s",
2496 (next != state ? "intermediate" : "final"),
2497 gst_element_state_get_name (current), gst_element_state_get_name (next));
2499 /* now signal any waiters, they will error since the cookie was incremented */
2500 GST_STATE_BROADCAST (element);
2502 GST_OBJECT_UNLOCK (element);
2504 ret = gst_element_change_state (element, transition);
2506 GST_STATE_UNLOCK (element);
2508 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "returned %s",
2509 gst_element_state_change_return_get_name (ret));
2515 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2516 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2517 "element was busy with async state change");
2518 GST_OBJECT_UNLOCK (element);
2520 GST_STATE_UNLOCK (element);
2522 return GST_STATE_CHANGE_ASYNC;
2527 * gst_element_change_state:
2528 * @element: a #GstElement
2529 * @transition: the requested transition
2531 * Perform @transition on @element.
2533 * This function must be called with STATE_LOCK held and is mainly used
2536 * Returns: the #GstStateChangeReturn of the state transition.
2538 GstStateChangeReturn
2539 gst_element_change_state (GstElement * element, GstStateChange transition)
2541 GstElementClass *oclass;
2542 GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
2544 oclass = GST_ELEMENT_GET_CLASS (element);
2546 /* call the state change function so it can set the state */
2547 if (oclass->change_state)
2548 ret = (oclass->change_state) (element, transition);
2550 ret = GST_STATE_CHANGE_FAILURE;
2553 case GST_STATE_CHANGE_FAILURE:
2554 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2555 "have FAILURE change_state return");
2556 /* state change failure */
2557 gst_element_abort_state (element);
2559 case GST_STATE_CHANGE_ASYNC:
2563 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2564 "element will change state ASYNC");
2566 target = GST_STATE_TARGET (element);
2568 if (target > GST_STATE_READY)
2571 /* else we just continue the state change downwards */
2572 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2573 "forcing commit state %s <= %s",
2574 gst_element_state_get_name (target),
2575 gst_element_state_get_name (GST_STATE_READY));
2577 ret = gst_element_continue_state (element, GST_STATE_CHANGE_SUCCESS);
2580 case GST_STATE_CHANGE_SUCCESS:
2581 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2582 "element changed state SUCCESS");
2583 /* we can commit the state now which will proceeed to
2585 ret = gst_element_continue_state (element, ret);
2587 case GST_STATE_CHANGE_NO_PREROLL:
2588 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2589 "element changed state NO_PREROLL");
2590 /* we can commit the state now which will proceeed to
2592 ret = gst_element_continue_state (element, ret);
2595 goto invalid_return;
2598 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit state change %d", ret);
2603 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit async state change %d",
2611 GST_OBJECT_LOCK (element);
2612 /* somebody added a GST_STATE_ and forgot to do stuff here ! */
2613 g_critical ("%s: unknown return value %d from a state change function",
2614 GST_ELEMENT_NAME (element), ret);
2616 /* we are in error now */
2617 ret = GST_STATE_CHANGE_FAILURE;
2618 GST_STATE_RETURN (element) = ret;
2619 GST_OBJECT_UNLOCK (element);
2625 /* gst_iterator_fold functions for pads_activate
2626 * Note how we don't stop the iterator when we fail an activation. This is
2627 * probably a FIXME since when one pad activation fails, we don't want to
2628 * continue our state change. */
2630 activate_pads (GstPad * pad, GValue * ret, gboolean * active)
2632 if (!gst_pad_set_active (pad, *active))
2633 g_value_set_boolean (ret, FALSE);
2635 /* unref the object that was reffed for us by _fold */
2636 gst_object_unref (pad);
2640 /* set the caps on the pad to NULL */
2642 clear_caps (GstPad * pad, GValue * ret, gboolean * active)
2644 gst_pad_set_caps (pad, NULL);
2645 gst_object_unref (pad);
2649 /* returns false on error or early cutout (will never happen because the fold
2650 * function always returns TRUE, see FIXME above) of the fold, true if all
2651 * pads in @iter were (de)activated successfully. */
2653 iterator_activate_fold_with_resync (GstIterator * iter,
2654 GstIteratorFoldFunction func, gpointer user_data)
2656 GstIteratorResult ires;
2659 /* no need to unset this later, it's just a boolean */
2660 g_value_init (&ret, G_TYPE_BOOLEAN);
2661 g_value_set_boolean (&ret, TRUE);
2664 ires = gst_iterator_fold (iter, func, &ret, user_data);
2666 case GST_ITERATOR_RESYNC:
2667 /* need to reset the result again */
2668 g_value_set_boolean (&ret, TRUE);
2669 gst_iterator_resync (iter);
2671 case GST_ITERATOR_DONE:
2672 /* all pads iterated, return collected value */
2675 /* iterator returned _ERROR or premature end with _OK,
2676 * mark an error and exit */
2677 g_value_set_boolean (&ret, FALSE);
2682 /* return collected value */
2683 return g_value_get_boolean (&ret);
2686 /* is called with STATE_LOCK
2688 * Pads are activated from source pads to sinkpads.
2691 gst_element_pads_activate (GstElement * element, gboolean active)
2696 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2697 "pads_activate with active %d", active);
2699 iter = gst_element_iterate_src_pads (element);
2701 iterator_activate_fold_with_resync (iter,
2702 (GstIteratorFoldFunction) activate_pads, &active);
2703 gst_iterator_free (iter);
2704 if (G_UNLIKELY (!res))
2707 iter = gst_element_iterate_sink_pads (element);
2709 iterator_activate_fold_with_resync (iter,
2710 (GstIteratorFoldFunction) activate_pads, &active);
2711 gst_iterator_free (iter);
2712 if (G_UNLIKELY (!res))
2716 /* clear the caps on all pads, this should never fail */
2717 iter = gst_element_iterate_pads (element);
2719 iterator_activate_fold_with_resync (iter,
2720 (GstIteratorFoldFunction) clear_caps, &active);
2721 gst_iterator_free (iter);
2722 if (G_UNLIKELY (!res))
2726 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2727 "pads_activate successful");
2734 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2735 "source pads_activate failed");
2740 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2741 "sink pads_activate failed");
2746 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2747 "failed to clear caps on pads");
2752 /* is called with STATE_LOCK */
2753 static GstStateChangeReturn
2754 gst_element_change_state_func (GstElement * element, GstStateChange transition)
2756 GstState state, next;
2757 GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
2760 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2762 state = (GstState) GST_STATE_TRANSITION_CURRENT (transition);
2763 next = GST_STATE_TRANSITION_NEXT (transition);
2765 /* if the element already is in the given state, we just return success */
2766 if (next == GST_STATE_VOID_PENDING || state == next)
2769 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element,
2770 "default handler tries setting state from %s to %s (%04x)",
2771 gst_element_state_get_name (state),
2772 gst_element_state_get_name (next), transition);
2774 switch (transition) {
2775 case GST_STATE_CHANGE_NULL_TO_READY:
2777 case GST_STATE_CHANGE_READY_TO_PAUSED:
2778 if (!gst_element_pads_activate (element, TRUE)) {
2779 result = GST_STATE_CHANGE_FAILURE;
2782 case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
2784 case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
2786 case GST_STATE_CHANGE_PAUSED_TO_READY:
2787 case GST_STATE_CHANGE_READY_TO_NULL:
2788 /* deactivate pads in both cases, since they are activated on
2789 ready->paused but the element might not have made it to paused */
2790 if (!gst_element_pads_activate (element, FALSE)) {
2791 result = GST_STATE_CHANGE_FAILURE;
2793 gst_element_set_base_time (element, 0);
2796 /* In null state release the reference to the clock */
2797 GST_OBJECT_LOCK (element);
2798 clock_p = &element->clock;
2799 gst_object_replace ((GstObject **) clock_p, NULL);
2800 GST_OBJECT_UNLOCK (element);
2803 /* this will catch real but unhandled state changes;
2804 * can only be caused by:
2805 * - a new state was added
2806 * - somehow the element was asked to jump across an intermediate state
2808 g_warning ("Unhandled state change from %s to %s",
2809 gst_element_state_get_name (state),
2810 gst_element_state_get_name (next));
2817 GST_OBJECT_LOCK (element);
2818 result = GST_STATE_RETURN (element);
2819 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2820 "element is already in the %s state",
2821 gst_element_state_get_name (state));
2822 GST_OBJECT_UNLOCK (element);
2829 * gst_element_get_factory:
2830 * @element: a #GstElement to request the element factory of.
2832 * Retrieves the factory that was used to create this element.
2834 * Returns: the #GstElementFactory used for creating this element.
2835 * no refcounting is needed.
2838 gst_element_get_factory (GstElement * element)
2840 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
2842 return GST_ELEMENT_GET_CLASS (element)->elementfactory;
2846 gst_element_dispose (GObject * object)
2848 GstElement *element = GST_ELEMENT (object);
2852 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "dispose");
2854 if (GST_STATE (element) != GST_STATE_NULL)
2857 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2858 "removing %d pads", g_list_length (element->pads));
2859 /* first we break all our links with the outside */
2860 while (element->pads && element->pads->data) {
2861 /* don't call _remove_pad with NULL */
2862 gst_element_remove_pad (element, GST_PAD_CAST (element->pads->data));
2864 if (G_UNLIKELY (element->pads != 0)) {
2865 g_critical ("could not remove pads from element %s",
2866 GST_STR_NULL (GST_OBJECT_NAME (object)));
2869 GST_OBJECT_LOCK (element);
2870 clock_p = &element->clock;
2871 bus_p = &element->bus;
2872 gst_object_replace ((GstObject **) clock_p, NULL);
2873 gst_object_replace ((GstObject **) bus_p, NULL);
2874 GST_OBJECT_UNLOCK (element);
2876 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "parent class dispose");
2878 G_OBJECT_CLASS (parent_class)->dispose (object);
2885 gboolean is_locked = gst_element_is_locked_state (element);
2887 ("\nTrying to dispose element %s, but it is in %s%s instead of the NULL"
2889 "You need to explicitly set elements to the NULL state before\n"
2890 "dropping the final reference, to allow them to clean up.\n",
2891 GST_OBJECT_NAME (element),
2892 gst_element_state_get_name (GST_STATE (element)),
2893 is_locked ? " (locked)" : "");
2899 gst_element_finalize (GObject * object)
2901 GstElement *element = GST_ELEMENT (object);
2903 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize");
2905 GST_STATE_LOCK (element);
2906 if (element->state_cond)
2907 g_cond_free (element->state_cond);
2908 element->state_cond = NULL;
2909 GST_STATE_UNLOCK (element);
2910 g_static_rec_mutex_free (element->state_lock);
2911 g_free (element->state_lock);
2912 element->state_lock = NULL;
2914 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize parent");
2916 G_OBJECT_CLASS (parent_class)->finalize (object);
2919 #ifndef GST_DISABLE_LOADSAVE
2921 * gst_element_save_thyself:
2922 * @element: a #GstElement to save.
2923 * @parent: the xml parent node.
2925 * Saves the element as part of the given XML structure.
2927 * Returns: the new #xmlNodePtr.
2930 gst_element_save_thyself (GstObject * object, xmlNodePtr parent)
2933 GstElementClass *oclass;
2934 GParamSpec **specs, *spec;
2937 GValue value = { 0, };
2938 GstElement *element;
2940 g_return_val_if_fail (GST_IS_ELEMENT (object), parent);
2942 element = GST_ELEMENT (object);
2944 oclass = GST_ELEMENT_GET_CLASS (element);
2946 xmlNewChild (parent, NULL, (xmlChar *) "name",
2947 (xmlChar *) GST_ELEMENT_NAME (element));
2949 if (oclass->elementfactory != NULL) {
2950 GstElementFactory *factory = (GstElementFactory *) oclass->elementfactory;
2952 xmlNewChild (parent, NULL, (xmlChar *) "type",
2953 (xmlChar *) GST_PLUGIN_FEATURE (factory)->name);
2957 specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (object), &nspecs);
2959 for (i = 0; i < nspecs; i++) {
2961 if (spec->flags & G_PARAM_READABLE) {
2965 g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (spec));
2967 g_object_get_property (G_OBJECT (element), spec->name, &value);
2968 param = xmlNewChild (parent, NULL, (xmlChar *) "param", NULL);
2969 xmlNewChild (param, NULL, (xmlChar *) "name", (xmlChar *) spec->name);
2971 if (G_IS_PARAM_SPEC_STRING (spec))
2972 contents = g_value_dup_string (&value);
2973 else if (G_IS_PARAM_SPEC_ENUM (spec))
2974 contents = g_strdup_printf ("%d", g_value_get_enum (&value));
2975 else if (G_IS_PARAM_SPEC_INT64 (spec))
2976 contents = g_strdup_printf ("%" G_GINT64_FORMAT,
2977 g_value_get_int64 (&value));
2978 else if (GST_VALUE_HOLDS_STRUCTURE (&value)) {
2979 if (g_value_get_boxed (&value) != NULL) {
2980 contents = g_strdup_value_contents (&value);
2982 contents = g_strdup ("NULL");
2985 contents = g_strdup_value_contents (&value);
2987 xmlNewChild (param, NULL, (xmlChar *) "value", (xmlChar *) contents);
2990 g_value_unset (&value);
2996 pads = g_list_last (GST_ELEMENT_PADS (element));
2999 GstPad *pad = GST_PAD_CAST (pads->data);
3001 /* figure out if it's a direct pad or a ghostpad */
3002 if (GST_ELEMENT (GST_OBJECT_PARENT (pad)) == element) {
3003 xmlNodePtr padtag = xmlNewChild (parent, NULL, (xmlChar *) "pad", NULL);
3005 gst_object_save_thyself (GST_OBJECT_CAST (pad), padtag);
3007 pads = g_list_previous (pads);
3014 gst_element_restore_thyself (GstObject * object, xmlNodePtr self)
3016 xmlNodePtr children;
3017 GstElement *element;
3019 gchar *value = NULL;
3021 element = GST_ELEMENT (object);
3022 g_return_if_fail (element != NULL);
3025 children = self->xmlChildrenNode;
3027 if (!strcmp ((char *) children->name, "param")) {
3028 xmlNodePtr child = children->xmlChildrenNode;
3031 if (!strcmp ((char *) child->name, "name")) {
3032 name = (gchar *) xmlNodeGetContent (child);
3033 } else if (!strcmp ((char *) child->name, "value")) {
3034 value = (gchar *) xmlNodeGetContent (child);
3036 child = child->next;
3038 /* FIXME: can this just be g_object_set ? */
3039 gst_util_set_object_arg (G_OBJECT (element), name, value);
3040 /* g_object_set (G_OBJECT (element), name, value, NULL); */
3044 children = children->next;
3048 children = self->xmlChildrenNode;
3050 if (!strcmp ((char *) children->name, "pad")) {
3051 gst_pad_load_and_link (children, GST_OBJECT_CAST (element));
3053 children = children->next;
3056 if (GST_OBJECT_CLASS (parent_class)->restore_thyself)
3057 (GST_OBJECT_CLASS (parent_class)->restore_thyself) (object, self);
3059 #endif /* GST_DISABLE_LOADSAVE */
3062 gst_element_set_bus_func (GstElement * element, GstBus * bus)
3066 g_return_if_fail (GST_IS_ELEMENT (element));
3068 GST_CAT_DEBUG_OBJECT (GST_CAT_PARENTAGE, element, "setting bus to %p", bus);
3070 GST_OBJECT_LOCK (element);
3071 bus_p = &GST_ELEMENT_BUS (element);
3072 gst_object_replace ((GstObject **) bus_p, GST_OBJECT_CAST (bus));
3073 GST_OBJECT_UNLOCK (element);
3077 * gst_element_set_bus:
3078 * @element: a #GstElement to set the bus of.
3079 * @bus: the #GstBus to set.
3081 * Sets the bus of the element. Increases the refcount on the bus.
3082 * For internal use only, unless you're testing elements.
3087 gst_element_set_bus (GstElement * element, GstBus * bus)
3089 GstElementClass *oclass;
3091 g_return_if_fail (GST_IS_ELEMENT (element));
3093 oclass = GST_ELEMENT_GET_CLASS (element);
3095 if (oclass->set_bus)
3096 oclass->set_bus (element, bus);
3100 * gst_element_get_bus:
3101 * @element: a #GstElement to get the bus of.
3103 * Returns the bus of the element. Note that only a #GstPipeline will provide a
3104 * bus for the application.
3106 * Returns: the element's #GstBus. unref after usage.
3111 gst_element_get_bus (GstElement * element)
3113 GstBus *result = NULL;
3115 g_return_val_if_fail (GST_IS_ELEMENT (element), result);
3117 GST_OBJECT_LOCK (element);
3118 if ((result = GST_ELEMENT_BUS (element)))
3119 gst_object_ref (result);
3120 GST_OBJECT_UNLOCK (element);
3122 GST_CAT_DEBUG_OBJECT (GST_CAT_BUS, element, "got bus %" GST_PTR_FORMAT,