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 * An existing pad of an element can be retrieved by name with
45 * gst_element_get_static_pad(). A new dynamic pad can be created using
46 * gst_element_request_pad() with a #GstPadTemplate or
47 * gst_element_get_request_pad() with the template name such as "src_\%d".
48 * An iterator of all pads can be retrieved with gst_element_iterate_pads().
50 * Elements can be linked through their pads.
51 * If the link is straightforward, use the gst_element_link()
52 * convenience function to link two elements, or gst_element_link_many()
53 * for more elements in a row.
54 * Use gst_element_link_filtered() to link two elements constrained by
55 * a specified set of #GstCaps.
56 * For finer control, use gst_element_link_pads() and
57 * gst_element_link_pads_filtered() to specify the pads to link on
58 * each element by name.
60 * Each element has a state (see #GstState). You can get and set the state
61 * of an element with gst_element_get_state() and gst_element_set_state().
62 * Setting a state triggers a #GstStateChange. To get a string representation
63 * of a #GstState, use gst_element_state_get_name().
65 * You can get and set a #GstClock on an element using gst_element_get_clock()
66 * and gst_element_set_clock().
67 * Some elements can provide a clock for the pipeline if
68 * gst_element_provides_clock() returns %TRUE. With the
69 * gst_element_provide_clock() method one can retrieve the clock provided by
71 * Not all elements require a clock to operate correctly. If
72 * gst_element_requires_clock() returns %TRUE, a clock should be set on the
73 * element with gst_element_set_clock().
75 * Note that clock slection and distribution is normally handled by the
76 * toplevel #GstPipeline so the clock functions are only to be used in very
77 * specific situations.
79 * Last reviewed on 2009-05-29 (0.10.24)
82 /* FIXME 0.11: suppress warnings for deprecated API such as GStaticRecMutex
83 * with newer GLib versions (>= 2.31.0) */
84 #define GLIB_DISABLE_DEPRECATION_WARNINGS
85 #include "gst_private.h"
88 #include <gobject/gvaluecollector.h>
90 #include "gstelement.h"
91 #include "gstelementdetails.h"
92 #include "gstenumtypes.h"
94 #include "gstmarshal.h"
100 #include "gst-i18n-lib.h"
101 #include "glib-compat-private.h"
103 /* Element signals and args */
119 #ifdef GST_DISABLE_DEPRECATED
120 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
121 #include <libxml/parser.h>
122 xmlNodePtr gst_object_save_thyself (const GstObject * object,
124 GstObject *gst_object_load_thyself (xmlNodePtr parent);
125 void gst_pad_load_and_link (xmlNodePtr self, GstObject * parent);
129 static void gst_element_class_init (GstElementClass * klass);
130 static void gst_element_init (GstElement * element);
131 static void gst_element_base_class_init (gpointer g_class);
132 static void gst_element_base_class_finalize (gpointer g_class);
134 static void gst_element_dispose (GObject * object);
135 static void gst_element_finalize (GObject * object);
137 static GstStateChangeReturn gst_element_change_state_func (GstElement * element,
138 GstStateChange transition);
139 static GstStateChangeReturn gst_element_get_state_func (GstElement * element,
140 GstState * state, GstState * pending, GstClockTime timeout);
141 static GstStateChangeReturn gst_element_set_state_func (GstElement * element,
143 static void gst_element_set_bus_func (GstElement * element, GstBus * bus);
145 static gboolean gst_element_default_send_event (GstElement * element,
147 static gboolean gst_element_default_query (GstElement * element,
150 static GstPadTemplate
151 * gst_element_class_get_request_pad_template (GstElementClass *
152 element_class, const gchar * name);
154 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
155 static xmlNodePtr gst_element_save_thyself (GstObject * object,
157 static void gst_element_restore_thyself (GstObject * parent, xmlNodePtr self);
160 static GstObjectClass *parent_class = NULL;
161 static guint gst_element_signals[LAST_SIGNAL] = { 0 };
163 /* this is used in gstelementfactory.c:gst_element_register() */
164 GQuark _gst_elementclass_factory = 0;
167 gst_element_get_type (void)
169 static volatile gsize gst_element_type = 0;
171 if (g_once_init_enter (&gst_element_type)) {
173 static const GTypeInfo element_info = {
174 sizeof (GstElementClass),
175 gst_element_base_class_init,
176 gst_element_base_class_finalize,
177 (GClassInitFunc) gst_element_class_init,
182 (GInstanceInitFunc) gst_element_init,
186 _type = g_type_register_static (GST_TYPE_OBJECT, "GstElement",
187 &element_info, G_TYPE_FLAG_ABSTRACT);
189 _gst_elementclass_factory =
190 g_quark_from_static_string ("GST_ELEMENTCLASS_FACTORY");
191 g_once_init_leave (&gst_element_type, _type);
193 return gst_element_type;
197 gst_element_class_init (GstElementClass * klass)
199 GObjectClass *gobject_class = (GObjectClass *) klass;
200 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
201 GstObjectClass *gstobject_class = (GstObjectClass *) klass;
204 parent_class = g_type_class_peek_parent (klass);
207 * GstElement::pad-added:
208 * @gstelement: the object which received the signal
209 * @new_pad: the pad that has been added
211 * a new #GstPad has been added to the element. Note that this signal will
212 * usually be emitted from the context of the streaming thread. Also keep in
213 * mind that if you add new elements to the pipeline in the signal handler
214 * you will need to set them to the desired target state with
215 * gst_element_set_state() or gst_element_sync_state_with_parent().
217 gst_element_signals[PAD_ADDED] =
218 g_signal_new ("pad-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
219 G_STRUCT_OFFSET (GstElementClass, pad_added), NULL, NULL,
220 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
222 * GstElement::pad-removed:
223 * @gstelement: the object which received the signal
224 * @old_pad: the pad that has been removed
226 * a #GstPad has been removed from the element
228 gst_element_signals[PAD_REMOVED] =
229 g_signal_new ("pad-removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
230 G_STRUCT_OFFSET (GstElementClass, pad_removed), NULL, NULL,
231 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
233 * GstElement::no-more-pads:
234 * @gstelement: the object which received the signal
236 * This signals that the element will not generate more dynamic pads.
237 * Note that this signal will usually be emitted from the context of
238 * the streaming thread.
240 gst_element_signals[NO_MORE_PADS] =
241 g_signal_new ("no-more-pads", G_TYPE_FROM_CLASS (klass),
242 G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstElementClass, no_more_pads), NULL,
243 NULL, gst_marshal_VOID__VOID, G_TYPE_NONE, 0);
245 gobject_class->dispose = gst_element_dispose;
246 gobject_class->finalize = gst_element_finalize;
248 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
249 gstobject_class->save_thyself =
250 ((gpointer (*)(GstObject * object,
251 gpointer self)) * GST_DEBUG_FUNCPTR (gst_element_save_thyself));
252 gstobject_class->restore_thyself =
253 ((void (*)(GstObject * object,
254 gpointer self)) *GST_DEBUG_FUNCPTR (gst_element_restore_thyself));
257 klass->change_state = GST_DEBUG_FUNCPTR (gst_element_change_state_func);
258 klass->set_state = GST_DEBUG_FUNCPTR (gst_element_set_state_func);
259 klass->get_state = GST_DEBUG_FUNCPTR (gst_element_get_state_func);
260 klass->set_bus = GST_DEBUG_FUNCPTR (gst_element_set_bus_func);
261 klass->query = GST_DEBUG_FUNCPTR (gst_element_default_query);
262 klass->send_event = GST_DEBUG_FUNCPTR (gst_element_default_send_event);
263 klass->numpadtemplates = 0;
265 klass->elementfactory = NULL;
269 gst_element_base_class_init (gpointer g_class)
271 GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);
273 /* FIXME 0.11: Copy the element details and instead of clearing the
274 * pad template list copy the list and increase the refcount of
275 * the pad templates by one.
277 * This will make it possible to add pad templates and set element
278 * details in the class_init functions and is the real GObject way
280 * See http://bugzilla.gnome.org/show_bug.cgi?id=491501
282 memset (&element_class->details, 0, sizeof (GstElementDetails));
283 element_class->meta_data = NULL;
284 element_class->padtemplates = NULL;
286 /* set the factory, see gst_element_register() */
287 element_class->elementfactory =
288 g_type_get_qdata (G_TYPE_FROM_CLASS (element_class),
289 _gst_elementclass_factory);
290 GST_DEBUG ("type %s : factory %p", G_OBJECT_CLASS_NAME (element_class),
291 element_class->elementfactory);
295 gst_element_base_class_finalize (gpointer g_class)
297 GstElementClass *klass = GST_ELEMENT_CLASS (g_class);
299 g_list_foreach (klass->padtemplates, (GFunc) gst_object_unref, NULL);
300 g_list_free (klass->padtemplates);
301 __gst_element_details_clear (&klass->details);
302 if (klass->meta_data) {
303 gst_structure_free (klass->meta_data);
304 klass->meta_data = NULL;
309 gst_element_init (GstElement * element)
311 GST_STATE (element) = GST_STATE_NULL;
312 GST_STATE_TARGET (element) = GST_STATE_NULL;
313 GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
314 GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
315 GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
317 /* FIXME 0.11: Store this directly in the instance struct */
318 element->state_lock = g_slice_new (GStaticRecMutex);
319 g_static_rec_mutex_init (element->state_lock);
320 element->state_cond = g_cond_new ();
324 * gst_element_release_request_pad:
325 * @element: a #GstElement to release the request pad of.
326 * @pad: the #GstPad to release.
328 * Makes the element free the previously requested pad as obtained
329 * with gst_element_get_request_pad().
331 * This does not unref the pad. If the pad was created by using
332 * gst_element_get_request_pad(), gst_element_release_request_pad() needs to be
333 * followed by gst_object_unref() to free the @pad.
338 gst_element_release_request_pad (GstElement * element, GstPad * pad)
340 GstElementClass *oclass;
342 g_return_if_fail (GST_IS_ELEMENT (element));
343 g_return_if_fail (GST_IS_PAD (pad));
345 oclass = GST_ELEMENT_GET_CLASS (element);
347 /* if the element implements a custom release function we call that, else we
348 * simply remove the pad from the element */
349 if (oclass->release_pad)
350 (oclass->release_pad) (element, pad);
352 gst_element_remove_pad (element, pad);
356 * gst_element_requires_clock:
357 * @element: a #GstElement to query
359 * Query if the element requires a clock.
361 * Returns: %TRUE if the element requires a clock
366 gst_element_requires_clock (GstElement * element)
370 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
372 result = (GST_ELEMENT_GET_CLASS (element)->set_clock != NULL);
378 * gst_element_provides_clock:
379 * @element: a #GstElement to query
381 * Query if the element provides a clock. A #GstClock provided by an
382 * element can be used as the global #GstClock for the pipeline.
383 * An element that can provide a clock is only required to do so in the PAUSED
384 * state, this means when it is fully negotiated and has allocated the resources
385 * to operate the clock.
387 * Returns: %TRUE if the element provides a clock
392 gst_element_provides_clock (GstElement * element)
396 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
398 result = (GST_ELEMENT_GET_CLASS (element)->provide_clock != NULL);
404 * gst_element_provide_clock:
405 * @element: a #GstElement to query
407 * Get the clock provided by the given element.
408 * <note>An element is only required to provide a clock in the PAUSED
409 * state. Some elements can provide a clock in other states.</note>
411 * Returns: (transfer full): the GstClock provided by the element or %NULL
412 * if no clock could be provided. Unref after usage.
417 gst_element_provide_clock (GstElement * element)
419 GstClock *result = NULL;
420 GstElementClass *oclass;
422 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
424 oclass = GST_ELEMENT_GET_CLASS (element);
426 if (oclass->provide_clock)
427 result = oclass->provide_clock (element);
433 * gst_element_set_clock:
434 * @element: a #GstElement to set the clock for.
435 * @clock: the #GstClock to set for the element.
437 * Sets the clock for the element. This function increases the
438 * refcount on the clock. Any previously set clock on the object
441 * Returns: %TRUE if the element accepted the clock. An element can refuse a
442 * clock when it, for example, is not able to slave its internal clock to the
443 * @clock or when it requires a specific clock to operate.
448 gst_element_set_clock (GstElement * element, GstClock * clock)
450 GstElementClass *oclass;
454 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
455 g_return_val_if_fail (clock == NULL || GST_IS_CLOCK (clock), FALSE);
457 oclass = GST_ELEMENT_GET_CLASS (element);
459 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element, "setting clock %p", clock);
461 if (oclass->set_clock)
462 res = oclass->set_clock (element, clock);
465 /* only update the clock pointer if the element accepted the clock */
466 GST_OBJECT_LOCK (element);
467 clock_p = &element->clock;
468 gst_object_replace ((GstObject **) clock_p, (GstObject *) clock);
469 GST_OBJECT_UNLOCK (element);
475 * gst_element_get_clock:
476 * @element: a #GstElement to get the clock of.
478 * Gets the currently configured clock of the element. This is the clock as was
479 * last set with gst_element_set_clock().
481 * Returns: (transfer full): the #GstClock of the element. unref after usage.
486 gst_element_get_clock (GstElement * element)
490 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
492 GST_OBJECT_LOCK (element);
493 if ((result = element->clock))
494 gst_object_ref (result);
495 GST_OBJECT_UNLOCK (element);
501 * gst_element_set_base_time:
502 * @element: a #GstElement.
503 * @time: the base time to set.
505 * Set the base time of an element. See gst_element_get_base_time().
510 gst_element_set_base_time (GstElement * element, GstClockTime time)
514 g_return_if_fail (GST_IS_ELEMENT (element));
516 GST_OBJECT_LOCK (element);
517 old = element->base_time;
518 element->base_time = time;
519 GST_OBJECT_UNLOCK (element);
521 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element,
522 "set base_time=%" GST_TIME_FORMAT ", old %" GST_TIME_FORMAT,
523 GST_TIME_ARGS (time), GST_TIME_ARGS (old));
527 * gst_element_get_base_time:
528 * @element: a #GstElement.
530 * Returns the base time of the element. The base time is the
531 * absolute time of the clock when this element was last put to
532 * PLAYING. Subtracting the base time from the clock time gives
533 * the running time of the element.
535 * Returns: the base time of the element.
540 gst_element_get_base_time (GstElement * element)
544 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_CLOCK_TIME_NONE);
546 GST_OBJECT_LOCK (element);
547 result = element->base_time;
548 GST_OBJECT_UNLOCK (element);
554 * gst_element_set_start_time:
555 * @element: a #GstElement.
556 * @time: the base time to set.
558 * Set the start time of an element. The start time of the element is the
559 * running time of the element when it last went to the PAUSED state. In READY
560 * or after a flushing seek, it is set to 0.
562 * Toplevel elements like #GstPipeline will manage the start_time and
563 * base_time on its children. Setting the start_time to #GST_CLOCK_TIME_NONE
564 * on such a toplevel element will disable the distribution of the base_time to
565 * the children and can be useful if the application manages the base_time
566 * itself, for example if you want to synchronize capture from multiple
567 * pipelines, and you can also ensure that the pipelines have the same clock.
574 gst_element_set_start_time (GstElement * element, GstClockTime time)
578 g_return_if_fail (GST_IS_ELEMENT (element));
580 GST_OBJECT_LOCK (element);
581 old = GST_ELEMENT_START_TIME (element);
582 GST_ELEMENT_START_TIME (element) = time;
583 GST_OBJECT_UNLOCK (element);
585 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element,
586 "set start_time=%" GST_TIME_FORMAT ", old %" GST_TIME_FORMAT,
587 GST_TIME_ARGS (time), GST_TIME_ARGS (old));
591 * gst_element_get_start_time:
592 * @element: a #GstElement.
594 * Returns the start time of the element. The start time is the
595 * running time of the clock when this element was last put to PAUSED.
597 * Usually the start_time is managed by a toplevel element such as
602 * Returns: the start time of the element.
607 gst_element_get_start_time (GstElement * element)
611 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_CLOCK_TIME_NONE);
613 GST_OBJECT_LOCK (element);
614 result = GST_ELEMENT_START_TIME (element);
615 GST_OBJECT_UNLOCK (element);
621 * gst_element_is_indexable:
622 * @element: a #GstElement.
624 * Queries if the element can be indexed.
626 * Returns: TRUE if the element can be indexed.
631 gst_element_is_indexable (GstElement * element)
635 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
637 result = (GST_ELEMENT_GET_CLASS (element)->set_index != NULL);
643 * gst_element_set_index:
644 * @element: a #GstElement.
645 * @index: (transfer none): a #GstIndex.
647 * Set @index on the element. The refcount of the index
648 * will be increased, any previously set index is unreffed.
653 gst_element_set_index (GstElement * element, GstIndex * index)
655 GstElementClass *oclass;
657 g_return_if_fail (GST_IS_ELEMENT (element));
658 g_return_if_fail (index == NULL || GST_IS_INDEX (index));
660 oclass = GST_ELEMENT_GET_CLASS (element);
662 if (oclass->set_index)
663 oclass->set_index (element, index);
667 * gst_element_get_index:
668 * @element: a #GstElement.
670 * Gets the index from the element.
672 * Returns: (transfer full): a #GstIndex or %NULL when no index was set on the
673 * element. unref after usage.
678 gst_element_get_index (GstElement * element)
680 GstElementClass *oclass;
681 GstIndex *result = NULL;
683 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
685 oclass = GST_ELEMENT_GET_CLASS (element);
687 if (oclass->get_index)
688 result = oclass->get_index (element);
694 * gst_element_add_pad:
695 * @element: a #GstElement to add the pad to.
696 * @pad: (transfer full): the #GstPad to add to the element.
698 * Adds a pad (link point) to @element. @pad's parent will be set to @element;
699 * see gst_object_set_parent() for refcounting information.
701 * Pads are not automatically activated so elements should perform the needed
702 * steps to activate the pad in case this pad is added in the PAUSED or PLAYING
703 * state. See gst_pad_set_active() for more information about activating pads.
705 * The pad and the element should be unlocked when calling this function.
707 * This function will emit the #GstElement::pad-added signal on the element.
709 * Returns: %TRUE if the pad could be added. This function can fail when
710 * a pad with the same name already existed or the pad already had another
716 gst_element_add_pad (GstElement * element, GstPad * pad)
721 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
722 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
724 /* locking pad to look at the name */
725 GST_OBJECT_LOCK (pad);
726 pad_name = g_strdup (GST_PAD_NAME (pad));
727 GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element, "adding pad '%s'",
728 GST_STR_NULL (pad_name));
729 flushing = GST_PAD_IS_FLUSHING (pad);
730 GST_OBJECT_UNLOCK (pad);
732 /* then check to see if there's already a pad by that name here */
733 GST_OBJECT_LOCK (element);
734 if (G_UNLIKELY (!gst_object_check_uniqueness (element->pads, pad_name)))
737 /* try to set the pad's parent */
738 if (G_UNLIKELY (!gst_object_set_parent (GST_OBJECT_CAST (pad),
739 GST_OBJECT_CAST (element))))
742 /* check for flushing pads */
743 if (flushing && (GST_STATE (element) > GST_STATE_READY ||
744 GST_STATE_NEXT (element) == GST_STATE_PAUSED)) {
745 g_warning ("adding flushing pad '%s' to running element '%s', you need to "
746 "use gst_pad_set_active(pad,TRUE) before adding it.",
747 GST_STR_NULL (pad_name), GST_ELEMENT_NAME (element));
749 GST_OBJECT_LOCK (pad);
750 GST_PAD_UNSET_FLUSHING (pad);
751 GST_OBJECT_UNLOCK (pad);
756 /* add it to the list */
757 switch (gst_pad_get_direction (pad)) {
759 element->srcpads = g_list_prepend (element->srcpads, pad);
760 element->numsrcpads++;
763 element->sinkpads = g_list_prepend (element->sinkpads, pad);
764 element->numsinkpads++;
769 element->pads = g_list_prepend (element->pads, pad);
771 element->pads_cookie++;
772 GST_OBJECT_UNLOCK (element);
774 /* emit the PAD_ADDED signal */
775 g_signal_emit (element, gst_element_signals[PAD_ADDED], 0, pad);
782 g_critical ("Padname %s is not unique in element %s, not adding",
783 pad_name, GST_ELEMENT_NAME (element));
784 GST_OBJECT_UNLOCK (element);
791 ("Pad %s already has parent when trying to add to element %s",
792 pad_name, GST_ELEMENT_NAME (element));
793 GST_OBJECT_UNLOCK (element);
799 GST_OBJECT_LOCK (pad);
801 ("Trying to add pad %s to element %s, but it has no direction",
802 GST_OBJECT_NAME (pad), GST_ELEMENT_NAME (element));
803 GST_OBJECT_UNLOCK (pad);
804 GST_OBJECT_UNLOCK (element);
810 * gst_element_remove_pad:
811 * @element: a #GstElement to remove pad from.
812 * @pad: (transfer none): the #GstPad to remove from the element.
814 * Removes @pad from @element. @pad will be destroyed if it has not been
815 * referenced elsewhere using gst_object_unparent().
817 * This function is used by plugin developers and should not be used
818 * by applications. Pads that were dynamically requested from elements
819 * with gst_element_get_request_pad() should be released with the
820 * gst_element_release_request_pad() function instead.
822 * Pads are not automatically deactivated so elements should perform the needed
823 * steps to deactivate the pad in case this pad is removed in the PAUSED or
824 * PLAYING state. See gst_pad_set_active() for more information about
827 * The pad and the element should be unlocked when calling this function.
829 * This function will emit the #GstElement::pad-removed signal on the element.
831 * Returns: %TRUE if the pad could be removed. Can return %FALSE if the
832 * pad does not belong to the provided element.
837 gst_element_remove_pad (GstElement * element, GstPad * pad)
841 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
842 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
844 /* locking pad to look at the name and parent */
845 GST_OBJECT_LOCK (pad);
846 GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element, "removing pad '%s'",
847 GST_STR_NULL (GST_PAD_NAME (pad)));
849 if (G_UNLIKELY (GST_PAD_PARENT (pad) != element))
851 GST_OBJECT_UNLOCK (pad);
854 if ((peer = gst_pad_get_peer (pad))) {
855 /* window for MT unsafeness, someone else could unlink here
856 * and then we call unlink with wrong pads. The unlink
857 * function would catch this and safely return failed. */
858 if (GST_PAD_IS_SRC (pad))
859 gst_pad_unlink (pad, peer);
861 gst_pad_unlink (peer, pad);
863 gst_object_unref (peer);
866 GST_OBJECT_LOCK (element);
867 /* remove it from the list */
868 switch (gst_pad_get_direction (pad)) {
870 element->srcpads = g_list_remove (element->srcpads, pad);
871 element->numsrcpads--;
874 element->sinkpads = g_list_remove (element->sinkpads, pad);
875 element->numsinkpads--;
878 g_critical ("Removing pad without direction???");
881 element->pads = g_list_remove (element->pads, pad);
883 element->pads_cookie++;
884 GST_OBJECT_UNLOCK (element);
886 /* emit the PAD_REMOVED signal before unparenting and losing the last ref. */
887 g_signal_emit (element, gst_element_signals[PAD_REMOVED], 0, pad);
889 gst_object_unparent (GST_OBJECT_CAST (pad));
896 /* FIXME, locking order? */
897 GST_OBJECT_LOCK (element);
898 g_critical ("Padname %s:%s does not belong to element %s when removing",
899 GST_DEBUG_PAD_NAME (pad), GST_ELEMENT_NAME (element));
900 GST_OBJECT_UNLOCK (element);
901 GST_OBJECT_UNLOCK (pad);
907 * gst_element_no_more_pads:
908 * @element: a #GstElement
910 * Use this function to signal that the element does not expect any more pads
911 * to show up in the current pipeline. This function should be called whenever
912 * pads have been added by the element itself. Elements with #GST_PAD_SOMETIMES
913 * pad templates use this in combination with autopluggers to figure out that
914 * the element is done initializing its pads.
916 * This function emits the #GstElement::no-more-pads signal.
921 gst_element_no_more_pads (GstElement * element)
923 g_return_if_fail (GST_IS_ELEMENT (element));
925 g_signal_emit (element, gst_element_signals[NO_MORE_PADS], 0);
929 pad_compare_name (GstPad * pad1, const gchar * name)
933 GST_OBJECT_LOCK (pad1);
934 result = strcmp (GST_PAD_NAME (pad1), name);
935 GST_OBJECT_UNLOCK (pad1);
941 * gst_element_get_static_pad:
942 * @element: a #GstElement to find a static pad of.
943 * @name: the name of the static #GstPad to retrieve.
945 * Retrieves a pad from @element by name. This version only retrieves
946 * already-existing (i.e. 'static') pads.
948 * Returns: (transfer full): the requested #GstPad if found, otherwise %NULL.
954 gst_element_get_static_pad (GstElement * element, const gchar * name)
957 GstPad *result = NULL;
959 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
960 g_return_val_if_fail (name != NULL, NULL);
962 GST_OBJECT_LOCK (element);
964 g_list_find_custom (element->pads, name, (GCompareFunc) pad_compare_name);
966 result = GST_PAD_CAST (find->data);
967 gst_object_ref (result);
970 if (result == NULL) {
971 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "no such pad '%s' in element \"%s\"",
972 name, GST_ELEMENT_NAME (element));
974 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
975 GST_ELEMENT_NAME (element), name);
977 GST_OBJECT_UNLOCK (element);
983 _gst_element_request_pad (GstElement * element, GstPadTemplate * templ,
984 const gchar * name, const GstCaps * caps)
986 GstPad *newpad = NULL;
987 GstElementClass *oclass;
989 oclass = GST_ELEMENT_GET_CLASS (element);
991 #ifndef G_DISABLE_CHECKS
992 /* Some sanity checking here */
996 /* Is this the template name? */
997 if (strstr (name, "%") || !strchr (templ->name_template, '%')) {
998 g_return_val_if_fail (strcmp (name, templ->name_template) == 0, NULL);
1000 const gchar *str, *data;
1003 /* Otherwise check if it's a valid name for the name template */
1004 str = strchr (templ->name_template, '%');
1005 g_return_val_if_fail (str != NULL, NULL);
1006 g_return_val_if_fail (strncmp (templ->name_template, name,
1007 str - templ->name_template) == 0, NULL);
1008 g_return_val_if_fail (strlen (name) > str - templ->name_template, NULL);
1010 data = name + (str - templ->name_template);
1012 /* Can either be %s or %d or %u, do sanity checking for %d */
1013 if (*(str + 1) == 'd') {
1017 tmp = g_ascii_strtoll (data, &endptr, 10);
1018 g_return_val_if_fail (tmp >= G_MININT && tmp <= G_MAXINT
1019 && *endptr == '\0', NULL);
1020 } else if (*(str + 1) == 'u') {
1024 tmp = g_ascii_strtoull (data, &endptr, 10);
1025 g_return_val_if_fail (tmp <= G_MAXUINT && *endptr == '\0', NULL);
1029 pad = gst_element_get_static_pad (element, name);
1031 gst_object_unref (pad);
1032 /* FIXME 0.11: Change this to g_return_val_if_fail() */
1033 g_critical ("Element %s already has a pad named %s, the behaviour of "
1034 " gst_element_get_request_pad() for existing pads is undefined!",
1035 GST_ELEMENT_NAME (element), name);
1040 if (oclass->request_new_pad_full)
1041 newpad = (oclass->request_new_pad_full) (element, templ, name, caps);
1042 else if (oclass->request_new_pad)
1043 newpad = (oclass->request_new_pad) (element, templ, name);
1046 gst_object_ref (newpad);
1052 * gst_element_get_request_pad:
1053 * @element: a #GstElement to find a request pad of.
1054 * @name: the name of the request #GstPad to retrieve.
1056 * Retrieves a pad from the element by name (e.g. "src_\%d"). This version only
1057 * retrieves request pads. The pad should be released with
1058 * gst_element_release_request_pad().
1060 * This method is slow and will be deprecated in the future. New code should
1061 * use gst_element_request_pad() with the requested template.
1063 * Returns: (transfer full): requested #GstPad if found, otherwise %NULL.
1064 * Release after usage.
1067 gst_element_get_request_pad (GstElement * element, const gchar * name)
1069 GstPadTemplate *templ = NULL;
1071 const gchar *req_name = NULL;
1072 gboolean templ_found = FALSE;
1075 gchar *str, *endptr = NULL;
1076 GstElementClass *class;
1078 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1079 g_return_val_if_fail (name != NULL, NULL);
1081 class = GST_ELEMENT_GET_CLASS (element);
1083 /* if the name contains a %, we assume it's the complete template name. Get
1084 * the template and try to get a pad */
1085 if (strstr (name, "%")) {
1086 templ = gst_element_class_get_request_pad_template (class, name);
1091 /* there is no % in the name, try to find a matching template */
1092 list = class->padtemplates;
1093 while (!templ_found && list) {
1094 templ = (GstPadTemplate *) list->data;
1095 if (templ->presence == GST_PAD_REQUEST) {
1096 GST_CAT_DEBUG (GST_CAT_PADS, "comparing %s to %s", name,
1097 templ->name_template);
1098 /* see if we find an exact match */
1099 if (strcmp (name, templ->name_template) == 0) {
1104 /* Because of sanity checks in gst_pad_template_new(), we know that %s
1105 and %d and %u, occurring at the end of the name_template, are the only
1107 else if ((str = strchr (templ->name_template, '%'))
1108 && strncmp (templ->name_template, name,
1109 str - templ->name_template) == 0
1110 && strlen (name) > str - templ->name_template) {
1111 data = name + (str - templ->name_template);
1112 if (*(str + 1) == 'd') {
1116 tmp = strtol (data, &endptr, 10);
1117 if (tmp != G_MINLONG && tmp != G_MAXLONG && endptr &&
1123 } else if (*(str + 1) == 'u') {
1127 tmp = strtoul (data, &endptr, 10);
1128 if (tmp != G_MAXULONG && endptr && *endptr == '\0') {
1148 pad = _gst_element_request_pad (element, templ, req_name, NULL);
1154 * gst_element_request_pad:
1155 * @element: a #GstElement to find a request pad of.
1156 * @templ: a #GstPadTemplate of which we want a pad of.
1157 * @name: (transfer none) (allow-none): the name of the request #GstPad
1158 * to retrieve. Can be %NULL.
1159 * @caps: (transfer none) (allow-none): the caps of the pad we want to
1160 * request. Can be %NULL.
1162 * Retrieves a request pad from the element according to the provided template.
1163 * Pad templates can be looked up using
1164 * gst_element_factory_get_static_pad_templates().
1166 * If the @caps are specified and the element implements thew new
1167 * request_new_pad_full virtual method, the element will use them to select
1168 * which pad to create.
1170 * The pad should be released with gst_element_release_request_pad().
1172 * Returns: (transfer full): requested #GstPad if found, otherwise %NULL.
1173 * Release after usage.
1178 gst_element_request_pad (GstElement * element,
1179 GstPadTemplate * templ, const gchar * name, const GstCaps * caps)
1181 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1182 g_return_val_if_fail (templ != NULL, NULL);
1184 return _gst_element_request_pad (element, templ, name, caps);
1188 * gst_element_get_pad:
1189 * @element: a #GstElement.
1190 * @name: the name of the pad to retrieve.
1192 * Retrieves a pad from @element by name. Tries gst_element_get_static_pad()
1193 * first, then gst_element_get_request_pad().
1195 * Deprecated: This function is deprecated as it's unclear if the reference
1196 * to the result pad should be released with gst_object_unref() in case of a static pad
1197 * or gst_element_release_request_pad() in case of a request pad.
1198 * Use gst_element_get_static_pad() or gst_element_get_request_pad() instead.
1200 * Returns: (transfer full): the #GstPad if found, otherwise %NULL. Unref or Release after usage,
1201 * depending on the type of the pad.
1203 #ifndef GST_REMOVE_DEPRECATED
1204 #ifdef GST_DISABLE_DEPRECATED
1205 GstPad *gst_element_get_pad (GstElement * element, const gchar * name);
1208 gst_element_get_pad (GstElement * element, const gchar * name)
1212 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1213 g_return_val_if_fail (name != NULL, NULL);
1215 pad = gst_element_get_static_pad (element, name);
1217 pad = gst_element_get_request_pad (element, name);
1221 #endif /* GST_REMOVE_DEPRECATED */
1223 static GstIteratorItem
1224 iterate_pad (GstIterator * it, GstPad * pad)
1226 gst_object_ref (pad);
1227 return GST_ITERATOR_ITEM_PASS;
1230 static GstIterator *
1231 gst_element_iterate_pad_list (GstElement * element, GList ** padlist)
1233 GstIterator *result;
1235 GST_OBJECT_LOCK (element);
1236 gst_object_ref (element);
1237 result = gst_iterator_new_list (GST_TYPE_PAD,
1238 GST_OBJECT_GET_LOCK (element),
1239 &element->pads_cookie,
1242 (GstIteratorItemFunction) iterate_pad,
1243 (GstIteratorDisposeFunction) gst_object_unref);
1244 GST_OBJECT_UNLOCK (element);
1250 * gst_element_iterate_pads:
1251 * @element: a #GstElement to iterate pads of.
1253 * Retrieves an iterator of @element's pads. The iterator should
1254 * be freed after usage. Also more specialized iterators exists such as
1255 * gst_element_iterate_src_pads() or gst_element_iterate_sink_pads().
1257 * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1263 gst_element_iterate_pads (GstElement * element)
1265 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1267 return gst_element_iterate_pad_list (element, &element->pads);
1271 * gst_element_iterate_src_pads:
1272 * @element: a #GstElement.
1274 * Retrieves an iterator of @element's source pads.
1276 * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1282 gst_element_iterate_src_pads (GstElement * element)
1284 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1286 return gst_element_iterate_pad_list (element, &element->srcpads);
1290 * gst_element_iterate_sink_pads:
1291 * @element: a #GstElement.
1293 * Retrieves an iterator of @element's sink pads.
1295 * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
1301 gst_element_iterate_sink_pads (GstElement * element)
1303 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1305 return gst_element_iterate_pad_list (element, &element->sinkpads);
1309 * gst_element_class_add_pad_template:
1310 * @klass: the #GstElementClass to add the pad template to.
1311 * @templ: (transfer none): a #GstPadTemplate to add to the element class.
1313 * Adds a padtemplate to an element class. This is mainly used in the _base_init
1314 * functions of classes.
1317 gst_element_class_add_pad_template (GstElementClass * klass,
1318 GstPadTemplate * templ)
1320 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1321 g_return_if_fail (GST_IS_PAD_TEMPLATE (templ));
1323 /* FIXME 0.11: allow replacing the pad templates by
1324 * calling this with the same name as an already existing pad
1325 * template. For this we _must_ _not_ ref the added pad template
1326 * a second time and _must_ document that this function takes
1327 * ownership of the pad template. Otherwise we will leak pad templates
1328 * or the caller unref's the pad template and it disappears */
1329 /* avoid registering pad templates with the same name */
1330 g_return_if_fail (gst_element_class_get_pad_template (klass,
1331 templ->name_template) == NULL);
1333 klass->padtemplates = g_list_append (klass->padtemplates,
1334 gst_object_ref (templ));
1335 klass->numpadtemplates++;
1339 * gst_element_class_add_static_pad_template:
1340 * @klass: the #GstElementClass to add the pad template to.
1341 * @templ: (transfer none): a #GstStaticPadTemplate describing the pad
1342 * to add to the element class.
1344 * Adds a padtemplate to an element class. This is mainly used in the _base_init
1345 * functions of classes.
1350 gst_element_class_add_static_pad_template (GstElementClass * klass,
1351 GstStaticPadTemplate * templ)
1355 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1357 pt = gst_static_pad_template_get (templ);
1358 gst_element_class_add_pad_template (klass, pt);
1359 gst_object_unref (pt);
1363 gst_element_class_add_meta_data (GstElementClass * klass,
1364 const gchar * key, const gchar * value)
1366 if (!klass->meta_data) {
1367 /* FIXME: use a quark for "metadata" */
1368 klass->meta_data = gst_structure_empty_new ("metadata");
1371 gst_structure_set ((GstStructure *) klass->meta_data,
1372 key, G_TYPE_STRING, value, NULL);
1376 * gst_element_class_set_documentation_uri:
1377 * @klass: class to set details for
1378 * @uri: uri of element documentation
1380 * Set uri pointing to user documentation. Applications can use this to show
1381 * help for e.g. effects to users.
1386 gst_element_class_set_documentation_uri (GstElementClass * klass,
1389 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1391 gst_element_class_add_meta_data (klass, "doc-uri", uri);
1395 * gst_element_class_set_icon_name:
1396 * @klass: class to set details for
1397 * @name: name of an icon
1399 * Elements that bridge to certain other products can include an icon of that
1400 * used product. Application can show the icon in menus/selectors to help
1401 * identifying specific elements.
1406 gst_element_class_set_icon_name (GstElementClass * klass, const gchar * name)
1408 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1410 gst_element_class_add_meta_data (klass, "icon-name", name);
1413 /* FIXME-0.11: deprecate and remove gst_element_class_set_details*() */
1415 * gst_element_class_set_details:
1416 * @klass: class to set details for
1417 * @details: details to set
1419 * Sets the detailed information for a #GstElementClass.
1420 * <note>This function is for use in _base_init functions only.</note>
1422 * The @details are copied.
1424 * Deprecated: Use gst_element_class_set_details_simple() instead.
1426 #ifndef GST_REMOVE_DEPRECATED
1427 #ifdef GST_DISABLE_DEPRECATED
1428 void gst_element_class_set_details (GstElementClass * klass,
1429 const GstElementDetails * details);
1432 gst_element_class_set_details (GstElementClass * klass,
1433 const GstElementDetails * details)
1435 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1436 g_return_if_fail (GST_IS_ELEMENT_DETAILS (details));
1438 __gst_element_details_copy (&klass->details, details);
1443 * gst_element_class_set_details_simple:
1444 * @klass: class to set details for
1445 * @longname: The long English name of the element. E.g. "File Sink"
1446 * @classification: String describing the type of element, as an unordered list
1447 * separated with slashes ('/'). See draft-klass.txt of the design docs
1448 * for more details and common types. E.g: "Sink/File"
1449 * @description: Sentence describing the purpose of the element.
1450 * E.g: "Write stream to a file"
1451 * @author: Name and contact details of the author(s). Use \n to separate
1452 * multiple author details. E.g: "Joe Bloggs <joe.blogs at foo.com>"
1454 * Sets the detailed information for a #GstElementClass. Simpler version of
1455 * gst_element_class_set_details() that generates less linker overhead.
1456 * <note>This function is for use in _base_init functions only.</note>
1458 * The detail parameter strings are copied into the #GstElementDetails for
1459 * the element class.
1464 gst_element_class_set_details_simple (GstElementClass * klass,
1465 const gchar * longname, const gchar * classification,
1466 const gchar * description, const gchar * author)
1468 const GstElementDetails details =
1469 GST_ELEMENT_DETAILS ((gchar *) longname, (gchar *) classification,
1470 (gchar *) description, (gchar *) author);
1472 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1474 __gst_element_details_copy (&klass->details, &details);
1478 * gst_element_class_get_pad_template_list:
1479 * @element_class: a #GstElementClass to get pad templates of.
1481 * Retrieves a list of the pad templates associated with @element_class. The
1482 * list must not be modified by the calling code.
1483 * <note>If you use this function in the #GInstanceInitFunc of an object class
1484 * that has subclasses, make sure to pass the g_class parameter of the
1485 * #GInstanceInitFunc here.</note>
1487 * Returns: (transfer none) (element-type Gst.PadTemplate): the #GList of
1491 gst_element_class_get_pad_template_list (GstElementClass * element_class)
1493 g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1495 return element_class->padtemplates;
1499 * gst_element_class_get_pad_template:
1500 * @element_class: a #GstElementClass to get the pad template of.
1501 * @name: the name of the #GstPadTemplate to get.
1503 * Retrieves a padtemplate from @element_class with the given name.
1504 * <note>If you use this function in the #GInstanceInitFunc of an object class
1505 * that has subclasses, make sure to pass the g_class parameter of the
1506 * #GInstanceInitFunc here.</note>
1508 * Returns: (transfer none): the #GstPadTemplate with the given name, or %NULL
1509 * if none was found. No unreferencing is necessary.
1512 gst_element_class_get_pad_template (GstElementClass *
1513 element_class, const gchar * name)
1517 g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1518 g_return_val_if_fail (name != NULL, NULL);
1520 padlist = element_class->padtemplates;
1523 GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
1525 if (strcmp (padtempl->name_template, name) == 0)
1528 padlist = g_list_next (padlist);
1534 static GstPadTemplate *
1535 gst_element_class_get_request_pad_template (GstElementClass *
1536 element_class, const gchar * name)
1538 GstPadTemplate *tmpl;
1540 tmpl = gst_element_class_get_pad_template (element_class, name);
1541 if (tmpl != NULL && tmpl->presence == GST_PAD_REQUEST)
1547 /* get a random pad on element of the given direction.
1548 * The pad is random in a sense that it is the first pad that is (optionaly) linked.
1551 gst_element_get_random_pad (GstElement * element,
1552 gboolean need_linked, GstPadDirection dir)
1554 GstPad *result = NULL;
1557 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "getting a random pad");
1561 GST_OBJECT_LOCK (element);
1562 pads = element->srcpads;
1565 GST_OBJECT_LOCK (element);
1566 pads = element->sinkpads;
1569 goto wrong_direction;
1571 for (; pads; pads = g_list_next (pads)) {
1572 GstPad *pad = GST_PAD_CAST (pads->data);
1574 GST_OBJECT_LOCK (pad);
1575 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "checking pad %s:%s",
1576 GST_DEBUG_PAD_NAME (pad));
1578 if (need_linked && !GST_PAD_IS_LINKED (pad)) {
1579 /* if we require a linked pad, and it is not linked, continue the
1581 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is not linked",
1582 GST_DEBUG_PAD_NAME (pad));
1583 GST_OBJECT_UNLOCK (pad);
1586 /* found a pad, stop search */
1587 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
1588 GST_DEBUG_PAD_NAME (pad));
1589 GST_OBJECT_UNLOCK (pad);
1595 gst_object_ref (result);
1597 GST_OBJECT_UNLOCK (element);
1601 /* ERROR handling */
1604 g_warning ("unknown pad direction %d", dir);
1610 gst_element_default_send_event (GstElement * element, GstEvent * event)
1612 gboolean result = FALSE;
1615 pad = GST_EVENT_IS_DOWNSTREAM (event) ?
1616 gst_element_get_random_pad (element, TRUE, GST_PAD_SRC) :
1617 gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1620 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1621 "pushing %s event to random %s pad %s:%s",
1622 GST_EVENT_TYPE_NAME (event),
1623 (GST_PAD_DIRECTION (pad) == GST_PAD_SRC ? "src" : "sink"),
1624 GST_DEBUG_PAD_NAME (pad));
1626 result = gst_pad_push_event (pad, event);
1627 gst_object_unref (pad);
1629 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "can't send %s event on element %s",
1630 GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1631 gst_event_unref (event);
1637 * gst_element_send_event:
1638 * @element: a #GstElement to send the event to.
1639 * @event: (transfer full): the #GstEvent to send to the element.
1641 * Sends an event to an element. If the element doesn't implement an
1642 * event handler, the event will be pushed on a random linked sink pad for
1643 * upstream events or a random linked source pad for downstream events.
1645 * This function takes owership of the provided event so you should
1646 * gst_event_ref() it if you want to reuse the event after this call.
1648 * Returns: %TRUE if the event was handled.
1653 gst_element_send_event (GstElement * element, GstEvent * event)
1655 GstElementClass *oclass;
1656 gboolean result = FALSE;
1658 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1659 g_return_val_if_fail (event != NULL, FALSE);
1661 oclass = GST_ELEMENT_GET_CLASS (element);
1663 GST_STATE_LOCK (element);
1664 if (oclass->send_event) {
1665 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send %s event on element %s",
1666 GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1667 result = oclass->send_event (element, event);
1669 result = gst_element_default_send_event (element, event);
1671 GST_STATE_UNLOCK (element);
1678 * @element: a #GstElement to send the event to.
1679 * @rate: The new playback rate
1680 * @format: The format of the seek values
1681 * @flags: The optional seek flags.
1682 * @cur_type: The type and flags for the new current position
1683 * @cur: The value of the new current position
1684 * @stop_type: The type and flags for the new stop position
1685 * @stop: The value of the new stop position
1687 * Sends a seek event to an element. See gst_event_new_seek() for the details of
1688 * the parameters. The seek event is sent to the element using
1689 * gst_element_send_event().
1691 * Returns: %TRUE if the event was handled.
1696 gst_element_seek (GstElement * element, gdouble rate, GstFormat format,
1697 GstSeekFlags flags, GstSeekType cur_type, gint64 cur,
1698 GstSeekType stop_type, gint64 stop)
1703 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1706 gst_event_new_seek (rate, format, flags, cur_type, cur, stop_type, stop);
1707 result = gst_element_send_event (element, event);
1713 * gst_element_get_query_types:
1714 * @element: a #GstElement to query
1716 * Get an array of query types from the element.
1717 * If the element doesn't implement a query types function,
1718 * the query will be forwarded to the peer of a random linked sink pad.
1720 * Returns: An array of #GstQueryType elements that should not
1721 * be freed or modified.
1725 const GstQueryType *
1726 gst_element_get_query_types (GstElement * element)
1728 GstElementClass *oclass;
1729 const GstQueryType *result = NULL;
1731 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1733 oclass = GST_ELEMENT_GET_CLASS (element);
1735 if (oclass->get_query_types) {
1736 result = oclass->get_query_types (element);
1738 GstPad *pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1741 GstPad *peer = gst_pad_get_peer (pad);
1744 result = gst_pad_get_query_types (peer);
1746 gst_object_unref (peer);
1748 gst_object_unref (pad);
1755 gst_element_default_query (GstElement * element, GstQuery * query)
1757 gboolean result = FALSE;
1760 pad = gst_element_get_random_pad (element, FALSE, GST_PAD_SRC);
1762 result = gst_pad_query (pad, query);
1764 gst_object_unref (pad);
1766 pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1768 GstPad *peer = gst_pad_get_peer (pad);
1771 result = gst_pad_query (peer, query);
1773 gst_object_unref (peer);
1775 gst_object_unref (pad);
1782 * gst_element_query:
1783 * @element: a #GstElement to perform the query on.
1784 * @query: (transfer none): the #GstQuery.
1786 * Performs a query on the given element.
1788 * For elements that don't implement a query handler, this function
1789 * forwards the query to a random srcpad or to the peer of a
1790 * random linked sinkpad of this element.
1792 * Please note that some queries might need a running pipeline to work.
1794 * Returns: TRUE if the query could be performed.
1799 gst_element_query (GstElement * element, GstQuery * query)
1801 GstElementClass *oclass;
1802 gboolean result = FALSE;
1804 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1805 g_return_val_if_fail (query != NULL, FALSE);
1807 oclass = GST_ELEMENT_GET_CLASS (element);
1809 if (oclass->query) {
1810 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send query on element %s",
1811 GST_ELEMENT_NAME (element));
1812 result = oclass->query (element, query);
1814 result = gst_element_default_query (element, query);
1820 * gst_element_post_message:
1821 * @element: a #GstElement posting the message
1822 * @message: (transfer full): a #GstMessage to post
1824 * Post a message on the element's #GstBus. This function takes ownership of the
1825 * message; if you want to access the message after this call, you should add an
1826 * additional reference before calling.
1828 * Returns: %TRUE if the message was successfully posted. The function returns
1829 * %FALSE if the element did not have a bus.
1834 gst_element_post_message (GstElement * element, GstMessage * message)
1837 gboolean result = FALSE;
1839 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1840 g_return_val_if_fail (message != NULL, FALSE);
1842 GST_OBJECT_LOCK (element);
1845 if (G_UNLIKELY (bus == NULL))
1848 gst_object_ref (bus);
1849 GST_OBJECT_UNLOCK (element);
1851 /* we release the element lock when posting the message so that any
1852 * (synchronous) message handlers can operate on the element */
1853 result = gst_bus_post (bus, message);
1854 gst_object_unref (bus);
1861 GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element,
1862 "not posting message %p: no bus", message);
1863 GST_OBJECT_UNLOCK (element);
1864 gst_message_unref (message);
1870 * _gst_element_error_printf:
1871 * @format: the printf-like format to use, or %NULL
1873 * This function is only used internally by the gst_element_error() macro.
1875 * Returns: (transfer full): a newly allocated string, or %NULL if the format
1881 _gst_element_error_printf (const gchar * format, ...)
1891 va_start (args, format);
1892 buffer = g_strdup_vprintf (format, args);
1898 * gst_element_message_full:
1899 * @element: a #GstElement to send message from
1900 * @type: the #GstMessageType
1901 * @domain: the GStreamer GError domain this message belongs to
1902 * @code: the GError code belonging to the domain
1903 * @text: (allow-none) (transfer full): an allocated text string to be used
1904 * as a replacement for the default message connected to code,
1906 * @debug: (allow-none) (transfer full): an allocated debug message to be
1907 * used as a replacement for the default debugging information,
1909 * @file: the source code file where the error was generated
1910 * @function: the source code function where the error was generated
1911 * @line: the source code line where the error was generated
1913 * Post an error, warning or info message on the bus from inside an element.
1915 * @type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or
1916 * #GST_MESSAGE_INFO.
1920 void gst_element_message_full
1921 (GstElement * element, GstMessageType type,
1922 GQuark domain, gint code, gchar * text,
1923 gchar * debug, const gchar * file, const gchar * function, gint line)
1925 GError *gerror = NULL;
1929 gboolean has_debug = TRUE;
1930 GstMessage *message = NULL;
1933 GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element, "start");
1934 g_return_if_fail (GST_IS_ELEMENT (element));
1935 g_return_if_fail ((type == GST_MESSAGE_ERROR) ||
1936 (type == GST_MESSAGE_WARNING) || (type == GST_MESSAGE_INFO));
1938 /* check if we send the given text or the default error text */
1939 if ((text == NULL) || (text[0] == 0)) {
1940 /* text could have come from g_strdup_printf (""); */
1942 sent_text = gst_error_get_message (domain, code);
1946 /* construct a sent_debug with extra information from source */
1947 if ((debug == NULL) || (debug[0] == 0)) {
1948 /* debug could have come from g_strdup_printf (""); */
1952 name = gst_object_get_path_string (GST_OBJECT_CAST (element));
1954 sent_debug = g_strdup_printf ("%s(%d): %s (): %s:\n%s",
1955 file, line, function, name, debug);
1957 sent_debug = g_strdup_printf ("%s(%d): %s (): %s",
1958 file, line, function, name);
1962 /* create gerror and post message */
1963 GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posting message: %s",
1965 gerror = g_error_new_literal (domain, code, sent_text);
1968 case GST_MESSAGE_ERROR:
1970 gst_message_new_error (GST_OBJECT_CAST (element), gerror, sent_debug);
1972 case GST_MESSAGE_WARNING:
1973 message = gst_message_new_warning (GST_OBJECT_CAST (element), gerror,
1976 case GST_MESSAGE_INFO:
1977 message = gst_message_new_info (GST_OBJECT_CAST (element), gerror,
1981 g_assert_not_reached ();
1984 gst_element_post_message (element, message);
1986 GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posted %s message: %s",
1987 (type == GST_MESSAGE_ERROR ? "error" : "warning"), sent_text);
1990 g_error_free (gerror);
1991 g_free (sent_debug);
1996 * gst_element_is_locked_state:
1997 * @element: a #GstElement.
1999 * Checks if the state of an element is locked.
2000 * If the state of an element is locked, state changes of the parent don't
2001 * affect the element.
2002 * This way you can leave currently unused elements inside bins. Just lock their
2003 * state before changing the state from #GST_STATE_NULL.
2007 * Returns: TRUE, if the element's state is locked.
2010 gst_element_is_locked_state (GstElement * element)
2014 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2016 GST_OBJECT_LOCK (element);
2017 result = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
2018 GST_OBJECT_UNLOCK (element);
2024 * gst_element_set_locked_state:
2025 * @element: a #GstElement
2026 * @locked_state: TRUE to lock the element's state
2028 * Locks the state of an element, so state changes of the parent don't affect
2029 * this element anymore.
2033 * Returns: TRUE if the state was changed, FALSE if bad parameters were given
2034 * or the elements state-locking needed no change.
2037 gst_element_set_locked_state (GstElement * element, gboolean locked_state)
2041 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2043 GST_OBJECT_LOCK (element);
2044 old = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
2046 if (G_UNLIKELY (old == locked_state))
2050 GST_CAT_DEBUG (GST_CAT_STATES, "locking state of element %s",
2051 GST_ELEMENT_NAME (element));
2052 GST_OBJECT_FLAG_SET (element, GST_ELEMENT_LOCKED_STATE);
2054 GST_CAT_DEBUG (GST_CAT_STATES, "unlocking state of element %s",
2055 GST_ELEMENT_NAME (element));
2056 GST_OBJECT_FLAG_UNSET (element, GST_ELEMENT_LOCKED_STATE);
2058 GST_OBJECT_UNLOCK (element);
2064 GST_CAT_DEBUG (GST_CAT_STATES,
2065 "elements %s was already in locked state %d",
2066 GST_ELEMENT_NAME (element), old);
2067 GST_OBJECT_UNLOCK (element);
2074 * gst_element_sync_state_with_parent:
2075 * @element: a #GstElement.
2077 * Tries to change the state of the element to the same as its parent.
2078 * If this function returns FALSE, the state of element is undefined.
2080 * Returns: TRUE, if the element's state could be synced to the parent's state.
2085 gst_element_sync_state_with_parent (GstElement * element)
2089 GstStateChangeReturn ret;
2091 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2093 if ((parent = GST_ELEMENT_CAST (gst_element_get_parent (element)))) {
2094 GstState parent_current, parent_pending;
2096 GST_OBJECT_LOCK (parent);
2097 parent_current = GST_STATE (parent);
2098 parent_pending = GST_STATE_PENDING (parent);
2099 GST_OBJECT_UNLOCK (parent);
2101 /* set to pending if there is one, else we set it to the current state of
2103 if (parent_pending != GST_STATE_VOID_PENDING)
2104 target = parent_pending;
2106 target = parent_current;
2108 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2109 "syncing state (%s) to parent %s %s (%s, %s)",
2110 gst_element_state_get_name (GST_STATE (element)),
2111 GST_ELEMENT_NAME (parent), gst_element_state_get_name (target),
2112 gst_element_state_get_name (parent_current),
2113 gst_element_state_get_name (parent_pending));
2115 ret = gst_element_set_state (element, target);
2116 if (ret == GST_STATE_CHANGE_FAILURE)
2119 gst_object_unref (parent);
2123 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "element has no parent");
2130 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2131 "syncing state failed (%s)",
2132 gst_element_state_change_return_get_name (ret));
2133 gst_object_unref (parent);
2139 static GstStateChangeReturn
2140 gst_element_get_state_func (GstElement * element,
2141 GstState * state, GstState * pending, GstClockTime timeout)
2143 GstStateChangeReturn ret = GST_STATE_CHANGE_FAILURE;
2144 GstState old_pending;
2146 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "getting state, timeout %"
2147 GST_TIME_FORMAT, GST_TIME_ARGS (timeout));
2149 GST_OBJECT_LOCK (element);
2150 ret = GST_STATE_RETURN (element);
2151 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "RETURN is %s",
2152 gst_element_state_change_return_get_name (ret));
2154 /* we got an error, report immediately */
2155 if (ret == GST_STATE_CHANGE_FAILURE)
2158 /* we got no_preroll, report immediately */
2159 if (ret == GST_STATE_CHANGE_NO_PREROLL)
2162 /* no need to wait async if we are not async */
2163 if (ret != GST_STATE_CHANGE_ASYNC)
2166 old_pending = GST_STATE_PENDING (element);
2167 if (old_pending != GST_STATE_VOID_PENDING) {
2168 GTimeVal *timeval, abstimeout;
2171 if (timeout != GST_CLOCK_TIME_NONE) {
2172 glong add = timeout / 1000;
2177 /* make timeout absolute */
2178 g_get_current_time (&abstimeout);
2179 g_time_val_add (&abstimeout, add);
2180 timeval = &abstimeout;
2184 /* get cookie to detect state changes during waiting */
2185 cookie = element->state_cookie;
2187 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2188 "waiting for element to commit state");
2190 /* we have a pending state change, wait for it to complete */
2191 if (!GST_STATE_TIMED_WAIT (element, timeval)) {
2192 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "timed out");
2193 /* timeout triggered */
2194 ret = GST_STATE_CHANGE_ASYNC;
2196 if (cookie != element->state_cookie)
2199 /* could be success or failure */
2200 if (old_pending == GST_STATE (element)) {
2201 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got success");
2202 ret = GST_STATE_CHANGE_SUCCESS;
2204 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got failure");
2205 ret = GST_STATE_CHANGE_FAILURE;
2208 /* if nothing is pending anymore we can return SUCCESS */
2209 if (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING) {
2210 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "nothing pending");
2211 ret = GST_STATE_CHANGE_SUCCESS;
2217 *state = GST_STATE (element);
2219 *pending = GST_STATE_PENDING (element);
2221 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2222 "state current: %s, pending: %s, result: %s",
2223 gst_element_state_get_name (GST_STATE (element)),
2224 gst_element_state_get_name (GST_STATE_PENDING (element)),
2225 gst_element_state_change_return_get_name (ret));
2226 GST_OBJECT_UNLOCK (element);
2233 *state = GST_STATE_VOID_PENDING;
2235 *pending = GST_STATE_VOID_PENDING;
2237 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "interruped");
2239 GST_OBJECT_UNLOCK (element);
2241 return GST_STATE_CHANGE_FAILURE;
2246 * gst_element_get_state:
2247 * @element: a #GstElement to get the state of.
2248 * @state: (out) (allow-none): a pointer to #GstState to hold the state.
2250 * @pending: (out) (allow-none): a pointer to #GstState to hold the pending
2251 * state. Can be %NULL.
2252 * @timeout: a #GstClockTime to specify the timeout for an async
2253 * state change or %GST_CLOCK_TIME_NONE for infinite timeout.
2255 * Gets the state of the element.
2257 * For elements that performed an ASYNC state change, as reported by
2258 * gst_element_set_state(), this function will block up to the
2259 * specified timeout value for the state change to complete.
2260 * If the element completes the state change or goes into
2261 * an error, this function returns immediately with a return value of
2262 * %GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively.
2264 * For elements that did not return %GST_STATE_CHANGE_ASYNC, this function
2265 * returns the current and pending state immediately.
2267 * This function returns %GST_STATE_CHANGE_NO_PREROLL if the element
2268 * successfully changed its state but is not able to provide data yet.
2269 * This mostly happens for live sources that only produce data in
2270 * %GST_STATE_PLAYING. While the state change return is equivalent to
2271 * %GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that
2272 * some sink elements might not be able to complete their state change because
2273 * an element is not producing data to complete the preroll. When setting the
2274 * element to playing, the preroll will complete and playback will start.
2276 * Returns: %GST_STATE_CHANGE_SUCCESS if the element has no more pending state
2277 * and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the
2278 * element is still performing a state change or
2279 * %GST_STATE_CHANGE_FAILURE if the last state change failed.
2283 GstStateChangeReturn
2284 gst_element_get_state (GstElement * element,
2285 GstState * state, GstState * pending, GstClockTime timeout)
2287 GstElementClass *oclass;
2288 GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2290 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2292 oclass = GST_ELEMENT_GET_CLASS (element);
2294 if (oclass->get_state)
2295 result = (oclass->get_state) (element, state, pending, timeout);
2301 * gst_element_abort_state:
2302 * @element: a #GstElement to abort the state of.
2304 * Abort the state change of the element. This function is used
2305 * by elements that do asynchronous state changes and find out
2306 * something is wrong.
2308 * This function should be called with the STATE_LOCK held.
2313 gst_element_abort_state (GstElement * element)
2317 #ifndef GST_DISABLE_GST_DEBUG
2321 g_return_if_fail (GST_IS_ELEMENT (element));
2323 GST_OBJECT_LOCK (element);
2324 pending = GST_STATE_PENDING (element);
2326 if (pending == GST_STATE_VOID_PENDING ||
2327 GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2328 goto nothing_aborted;
2330 #ifndef GST_DISABLE_GST_DEBUG
2331 old_state = GST_STATE (element);
2333 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2334 "aborting state from %s to %s", gst_element_state_get_name (old_state),
2335 gst_element_state_get_name (pending));
2339 GST_STATE_RETURN (element) = GST_STATE_CHANGE_FAILURE;
2341 GST_STATE_BROADCAST (element);
2342 GST_OBJECT_UNLOCK (element);
2348 GST_OBJECT_UNLOCK (element);
2353 /* Not static because GstBin has manual state handling too */
2355 _priv_gst_element_state_changed (GstElement * element, GstState oldstate,
2356 GstState newstate, GstState pending)
2358 GstElementClass *klass = GST_ELEMENT_GET_CLASS (element);
2359 GstMessage *message;
2361 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2362 "notifying about state-changed %s to %s (%s pending)",
2363 gst_element_state_get_name (oldstate),
2364 gst_element_state_get_name (newstate),
2365 gst_element_state_get_name (pending));
2367 if (klass->state_changed)
2368 klass->state_changed (element, oldstate, newstate, pending);
2370 message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2371 oldstate, newstate, pending);
2372 gst_element_post_message (element, message);
2376 * gst_element_continue_state:
2377 * @element: a #GstElement to continue the state change of.
2378 * @ret: The previous state return value
2380 * Commit the state change of the element and proceed to the next
2381 * pending state if any. This function is used
2382 * by elements that do asynchronous state changes.
2383 * The core will normally call this method automatically when an
2384 * element returned %GST_STATE_CHANGE_SUCCESS from the state change function.
2386 * If after calling this method the element still has not reached
2387 * the pending state, the next state change is performed.
2389 * This method is used internally and should normally not be called by plugins
2392 * Returns: The result of the commit state change.
2396 GstStateChangeReturn
2397 gst_element_continue_state (GstElement * element, GstStateChangeReturn ret)
2399 GstStateChangeReturn old_ret;
2400 GstState old_state, old_next;
2401 GstState current, next, pending;
2402 GstStateChange transition;
2404 GST_OBJECT_LOCK (element);
2405 old_ret = GST_STATE_RETURN (element);
2406 GST_STATE_RETURN (element) = ret;
2407 pending = GST_STATE_PENDING (element);
2409 /* check if there is something to commit */
2410 if (pending == GST_STATE_VOID_PENDING)
2411 goto nothing_pending;
2413 old_state = GST_STATE (element);
2414 /* this is the state we should go to next */
2415 old_next = GST_STATE_NEXT (element);
2416 /* update current state */
2417 current = GST_STATE (element) = old_next;
2419 /* see if we reached the final state */
2420 if (pending == current)
2423 next = GST_STATE_GET_NEXT (current, pending);
2424 transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2426 GST_STATE_NEXT (element) = next;
2428 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2429 GST_OBJECT_UNLOCK (element);
2431 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2432 "committing state from %s to %s, pending %s, next %s",
2433 gst_element_state_get_name (old_state),
2434 gst_element_state_get_name (old_next),
2435 gst_element_state_get_name (pending), gst_element_state_get_name (next));
2437 _priv_gst_element_state_changed (element, old_state, old_next, pending);
2439 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2440 "continue state change %s to %s, final %s",
2441 gst_element_state_get_name (current),
2442 gst_element_state_get_name (next), gst_element_state_get_name (pending));
2444 ret = gst_element_change_state (element, transition);
2450 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "nothing pending");
2451 GST_OBJECT_UNLOCK (element);
2456 GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2457 GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2459 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2460 "completed state change to %s", gst_element_state_get_name (pending));
2461 GST_OBJECT_UNLOCK (element);
2463 /* don't post silly messages with the same state. This can happen
2464 * when an element state is changed to what it already was. For bins
2465 * this can be the result of a lost state, which we check with the
2466 * previous return value.
2467 * We do signal the cond though as a _get_state() might be blocking
2469 if (old_state != old_next || old_ret == GST_STATE_CHANGE_ASYNC)
2470 _priv_gst_element_state_changed (element, old_state, old_next,
2471 GST_STATE_VOID_PENDING);
2473 GST_STATE_BROADCAST (element);
2480 * gst_element_lost_state_full:
2481 * @element: a #GstElement the state is lost of
2482 * @new_base_time: if a new base time should be distributed
2484 * Brings the element to the lost state. The current state of the
2485 * element is copied to the pending state so that any call to
2486 * gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC.
2488 * An ASYNC_START message is posted with indication to distribute a new
2489 * base_time to the element when @new_base_time is %TRUE.
2490 * If the element was PLAYING, it will go to PAUSED. The element
2491 * will be restored to its PLAYING state by the parent pipeline when it
2494 * This is mostly used for elements that lost their preroll buffer
2495 * in the %GST_STATE_PAUSED or %GST_STATE_PLAYING state after a flush,
2496 * they will go to their pending state again when a new preroll buffer is
2497 * queued. This function can only be called when the element is currently
2498 * not in error or an async state change.
2500 * This function is used internally and should normally not be called from
2501 * plugins or applications.
2508 gst_element_lost_state_full (GstElement * element, gboolean new_base_time)
2510 GstState old_state, new_state;
2511 GstMessage *message;
2513 g_return_if_fail (GST_IS_ELEMENT (element));
2515 GST_OBJECT_LOCK (element);
2516 if (GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2519 if (GST_STATE_PENDING (element) != GST_STATE_VOID_PENDING)
2520 goto only_async_start;
2522 old_state = GST_STATE (element);
2524 /* when we were PLAYING, the new state is PAUSED. We will also not
2525 * automatically go to PLAYING but let the parent bin(s) set us to PLAYING
2526 * when we preroll. */
2527 if (old_state > GST_STATE_PAUSED)
2528 new_state = GST_STATE_PAUSED;
2530 new_state = old_state;
2532 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2533 "lost state of %s to %s", gst_element_state_get_name (old_state),
2534 gst_element_state_get_name (new_state));
2536 GST_STATE (element) = new_state;
2537 GST_STATE_NEXT (element) = new_state;
2538 GST_STATE_PENDING (element) = new_state;
2539 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2541 GST_ELEMENT_START_TIME (element) = 0;
2542 GST_OBJECT_UNLOCK (element);
2544 _priv_gst_element_state_changed (element, new_state, new_state, new_state);
2547 gst_message_new_async_start (GST_OBJECT_CAST (element), new_base_time);
2548 gst_element_post_message (element, message);
2554 GST_OBJECT_UNLOCK (element);
2559 GST_OBJECT_UNLOCK (element);
2561 message = gst_message_new_async_start (GST_OBJECT_CAST (element), TRUE);
2562 gst_element_post_message (element, message);
2568 * gst_element_lost_state:
2569 * @element: a #GstElement the state is lost of
2571 * Brings the element to the lost state. This function calls
2572 * gst_element_lost_state_full() with the new_base_time set to %TRUE.
2574 * This function is used internally and should normally not be called from
2575 * plugins or applications.
2580 gst_element_lost_state (GstElement * element)
2582 gst_element_lost_state_full (element, TRUE);
2586 * gst_element_set_state:
2587 * @element: a #GstElement to change state of.
2588 * @state: the element's new #GstState.
2590 * Sets the state of the element. This function will try to set the
2591 * requested state by going through all the intermediary states and calling
2592 * the class's state change function for each.
2594 * This function can return #GST_STATE_CHANGE_ASYNC, in which case the
2595 * element will perform the remainder of the state change asynchronously in
2597 * An application can use gst_element_get_state() to wait for the completion
2598 * of the state change or it can wait for a state change message on the bus.
2600 * State changes to %GST_STATE_READY or %GST_STATE_NULL never return
2601 * #GST_STATE_CHANGE_ASYNC.
2603 * Returns: Result of the state change using #GstStateChangeReturn.
2607 GstStateChangeReturn
2608 gst_element_set_state (GstElement * element, GstState state)
2610 GstElementClass *oclass;
2611 GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2613 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2615 oclass = GST_ELEMENT_GET_CLASS (element);
2617 if (oclass->set_state)
2618 result = (oclass->set_state) (element, state);
2624 * default set state function, calculates the next state based
2625 * on current state and calls the change_state function
2627 static GstStateChangeReturn
2628 gst_element_set_state_func (GstElement * element, GstState state)
2630 GstState current, next, old_pending;
2631 GstStateChangeReturn ret;
2632 GstStateChange transition;
2633 GstStateChangeReturn old_ret;
2635 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2637 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "set_state to %s",
2638 gst_element_state_get_name (state));
2640 /* state lock is taken to protect the set_state() and get_state()
2641 * procedures, it does not lock any variables. */
2642 GST_STATE_LOCK (element);
2644 /* now calculate how to get to the new state */
2645 GST_OBJECT_LOCK (element);
2646 old_ret = GST_STATE_RETURN (element);
2647 /* previous state change returned an error, remove all pending
2648 * and next states */
2649 if (old_ret == GST_STATE_CHANGE_FAILURE) {
2650 GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2651 GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2652 GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
2655 current = GST_STATE (element);
2656 next = GST_STATE_NEXT (element);
2657 old_pending = GST_STATE_PENDING (element);
2659 /* this is the (new) state we should go to. TARGET is the last state we set on
2661 if (state != GST_STATE_TARGET (element)) {
2662 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2663 "setting target state to %s", gst_element_state_get_name (state));
2664 GST_STATE_TARGET (element) = state;
2665 /* increment state cookie so that we can track each state change. We only do
2666 * this if this is actually a new state change. */
2667 element->state_cookie++;
2669 GST_STATE_PENDING (element) = state;
2671 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2672 "current %s, old_pending %s, next %s, old return %s",
2673 gst_element_state_get_name (current),
2674 gst_element_state_get_name (old_pending),
2675 gst_element_state_get_name (next),
2676 gst_element_state_change_return_get_name (old_ret));
2678 /* if the element was busy doing a state change, we just update the
2679 * target state, it'll get to it async then. */
2680 if (old_pending != GST_STATE_VOID_PENDING) {
2681 /* upwards state change will happen ASYNC */
2682 if (old_pending <= state)
2684 /* element is going to this state already */
2685 else if (next == state)
2687 /* element was performing an ASYNC upward state change and
2688 * we request to go downward again. Start from the next pending
2690 else if (next > state
2691 && GST_STATE_RETURN (element) == GST_STATE_CHANGE_ASYNC) {
2695 next = GST_STATE_GET_NEXT (current, state);
2696 /* now we store the next state */
2697 GST_STATE_NEXT (element) = next;
2698 /* mark busy, we need to check that there is actually a state change
2699 * to be done else we could accidentally override SUCCESS/NO_PREROLL and
2700 * the default element change_state function has no way to know what the
2701 * old value was... could consider this a FIXME...*/
2702 if (current != next)
2703 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2705 transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2707 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2708 "%s: setting state from %s to %s",
2709 (next != state ? "intermediate" : "final"),
2710 gst_element_state_get_name (current), gst_element_state_get_name (next));
2712 /* now signal any waiters, they will error since the cookie was incremented */
2713 GST_STATE_BROADCAST (element);
2715 GST_OBJECT_UNLOCK (element);
2717 ret = gst_element_change_state (element, transition);
2719 GST_STATE_UNLOCK (element);
2721 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "returned %s",
2722 gst_element_state_change_return_get_name (ret));
2728 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2729 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2730 "element was busy with async state change");
2731 GST_OBJECT_UNLOCK (element);
2733 GST_STATE_UNLOCK (element);
2735 return GST_STATE_CHANGE_ASYNC;
2740 * gst_element_change_state:
2741 * @element: a #GstElement
2742 * @transition: the requested transition
2744 * Perform @transition on @element.
2746 * This function must be called with STATE_LOCK held and is mainly used
2749 * Returns: the #GstStateChangeReturn of the state transition.
2751 GstStateChangeReturn
2752 gst_element_change_state (GstElement * element, GstStateChange transition)
2754 GstElementClass *oclass;
2755 GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
2757 oclass = GST_ELEMENT_GET_CLASS (element);
2759 /* call the state change function so it can set the state */
2760 if (oclass->change_state)
2761 ret = (oclass->change_state) (element, transition);
2763 ret = GST_STATE_CHANGE_FAILURE;
2766 case GST_STATE_CHANGE_FAILURE:
2767 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2768 "have FAILURE change_state return");
2769 /* state change failure */
2770 gst_element_abort_state (element);
2772 case GST_STATE_CHANGE_ASYNC:
2776 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2777 "element will change state ASYNC");
2779 target = GST_STATE_TARGET (element);
2781 if (target > GST_STATE_READY)
2784 /* else we just continue the state change downwards */
2785 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2786 "forcing commit state %s <= %s",
2787 gst_element_state_get_name (target),
2788 gst_element_state_get_name (GST_STATE_READY));
2790 ret = gst_element_continue_state (element, GST_STATE_CHANGE_SUCCESS);
2793 case GST_STATE_CHANGE_SUCCESS:
2794 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2795 "element changed state SUCCESS");
2796 /* we can commit the state now which will proceeed to
2798 ret = gst_element_continue_state (element, ret);
2800 case GST_STATE_CHANGE_NO_PREROLL:
2801 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2802 "element changed state NO_PREROLL");
2803 /* we can commit the state now which will proceeed to
2805 ret = gst_element_continue_state (element, ret);
2808 goto invalid_return;
2811 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit state change %d", ret);
2816 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit async state change %d",
2824 GST_OBJECT_LOCK (element);
2825 /* somebody added a GST_STATE_ and forgot to do stuff here ! */
2826 g_critical ("%s: unknown return value %d from a state change function",
2827 GST_ELEMENT_NAME (element), ret);
2829 /* we are in error now */
2830 ret = GST_STATE_CHANGE_FAILURE;
2831 GST_STATE_RETURN (element) = ret;
2832 GST_OBJECT_UNLOCK (element);
2838 /* gst_iterator_fold functions for pads_activate
2839 * Stop the iterator if activating one pad failed. */
2841 activate_pads (GstPad * pad, GValue * ret, gboolean * active)
2843 gboolean cont = TRUE;
2845 if (!(cont = gst_pad_set_active (pad, *active)))
2846 g_value_set_boolean (ret, FALSE);
2848 /* unref the object that was reffed for us by _fold */
2849 gst_object_unref (pad);
2853 /* set the caps on the pad to NULL */
2855 clear_caps (GstPad * pad, GValue * ret, gboolean * active)
2857 gst_pad_set_caps (pad, NULL);
2858 gst_object_unref (pad);
2862 /* returns false on error or early cutout of the fold, true if all
2863 * pads in @iter were (de)activated successfully. */
2865 iterator_activate_fold_with_resync (GstIterator * iter,
2866 GstIteratorFoldFunction func, gpointer user_data)
2868 GstIteratorResult ires;
2871 /* no need to unset this later, it's just a boolean */
2872 g_value_init (&ret, G_TYPE_BOOLEAN);
2873 g_value_set_boolean (&ret, TRUE);
2876 ires = gst_iterator_fold (iter, func, &ret, user_data);
2878 case GST_ITERATOR_RESYNC:
2879 /* need to reset the result again */
2880 g_value_set_boolean (&ret, TRUE);
2881 gst_iterator_resync (iter);
2883 case GST_ITERATOR_DONE:
2884 /* all pads iterated, return collected value */
2887 /* iterator returned _ERROR or premature end with _OK,
2888 * mark an error and exit */
2889 g_value_set_boolean (&ret, FALSE);
2894 /* return collected value */
2895 return g_value_get_boolean (&ret);
2898 /* is called with STATE_LOCK
2900 * Pads are activated from source pads to sinkpads.
2903 gst_element_pads_activate (GstElement * element, gboolean active)
2908 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2909 "pads_activate with active %d", active);
2911 iter = gst_element_iterate_src_pads (element);
2913 iterator_activate_fold_with_resync (iter,
2914 (GstIteratorFoldFunction) activate_pads, &active);
2915 gst_iterator_free (iter);
2916 if (G_UNLIKELY (!res))
2919 iter = gst_element_iterate_sink_pads (element);
2921 iterator_activate_fold_with_resync (iter,
2922 (GstIteratorFoldFunction) activate_pads, &active);
2923 gst_iterator_free (iter);
2924 if (G_UNLIKELY (!res))
2928 /* clear the caps on all pads, this should never fail */
2929 iter = gst_element_iterate_pads (element);
2931 iterator_activate_fold_with_resync (iter,
2932 (GstIteratorFoldFunction) clear_caps, &active);
2933 gst_iterator_free (iter);
2934 if (G_UNLIKELY (!res))
2938 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2939 "pads_activate successful");
2946 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2947 "source pads_activate failed");
2952 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2953 "sink pads_activate failed");
2958 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2959 "failed to clear caps on pads");
2964 /* is called with STATE_LOCK */
2965 static GstStateChangeReturn
2966 gst_element_change_state_func (GstElement * element, GstStateChange transition)
2968 GstState state, next;
2969 GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
2972 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2974 state = (GstState) GST_STATE_TRANSITION_CURRENT (transition);
2975 next = GST_STATE_TRANSITION_NEXT (transition);
2977 /* if the element already is in the given state, we just return success */
2978 if (next == GST_STATE_VOID_PENDING || state == next)
2981 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element,
2982 "default handler tries setting state from %s to %s (%04x)",
2983 gst_element_state_get_name (state),
2984 gst_element_state_get_name (next), transition);
2986 switch (transition) {
2987 case GST_STATE_CHANGE_NULL_TO_READY:
2989 case GST_STATE_CHANGE_READY_TO_PAUSED:
2990 if (!gst_element_pads_activate (element, TRUE)) {
2991 result = GST_STATE_CHANGE_FAILURE;
2994 case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
2996 case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
2998 case GST_STATE_CHANGE_PAUSED_TO_READY:
2999 case GST_STATE_CHANGE_READY_TO_NULL:
3000 /* deactivate pads in both cases, since they are activated on
3001 ready->paused but the element might not have made it to paused */
3002 if (!gst_element_pads_activate (element, FALSE)) {
3003 result = GST_STATE_CHANGE_FAILURE;
3005 gst_element_set_base_time (element, 0);
3008 /* In null state release the reference to the clock */
3009 GST_OBJECT_LOCK (element);
3010 clock_p = &element->clock;
3011 gst_object_replace ((GstObject **) clock_p, NULL);
3012 GST_OBJECT_UNLOCK (element);
3015 /* this will catch real but unhandled state changes;
3016 * can only be caused by:
3017 * - a new state was added
3018 * - somehow the element was asked to jump across an intermediate state
3020 g_warning ("Unhandled state change from %s to %s",
3021 gst_element_state_get_name (state),
3022 gst_element_state_get_name (next));
3029 GST_OBJECT_LOCK (element);
3030 result = GST_STATE_RETURN (element);
3031 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
3032 "element is already in the %s state",
3033 gst_element_state_get_name (state));
3034 GST_OBJECT_UNLOCK (element);
3041 * gst_element_get_factory:
3042 * @element: a #GstElement to request the element factory of.
3044 * Retrieves the factory that was used to create this element.
3046 * Returns: (transfer none): the #GstElementFactory used for creating this
3047 * element. no refcounting is needed.
3050 gst_element_get_factory (GstElement * element)
3052 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
3054 return GST_ELEMENT_GET_CLASS (element)->elementfactory;
3058 gst_element_dispose (GObject * object)
3060 GstElement *element = GST_ELEMENT_CAST (object);
3064 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "dispose");
3066 if (GST_STATE (element) != GST_STATE_NULL)
3069 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
3070 "removing %d pads", g_list_length (element->pads));
3071 /* first we break all our links with the outside */
3072 while (element->pads && element->pads->data) {
3073 /* don't call _remove_pad with NULL */
3074 gst_element_remove_pad (element, GST_PAD_CAST (element->pads->data));
3076 if (G_UNLIKELY (element->pads != NULL)) {
3077 g_critical ("could not remove pads from element %s",
3078 GST_STR_NULL (GST_OBJECT_NAME (object)));
3081 GST_OBJECT_LOCK (element);
3082 clock_p = &element->clock;
3083 bus_p = &element->bus;
3084 gst_object_replace ((GstObject **) clock_p, NULL);
3085 gst_object_replace ((GstObject **) bus_p, NULL);
3086 GST_OBJECT_UNLOCK (element);
3088 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "parent class dispose");
3090 G_OBJECT_CLASS (parent_class)->dispose (object);
3099 is_locked = GST_OBJECT_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
3101 ("\nTrying to dispose element %s, but it is in %s%s instead of the NULL"
3103 "You need to explicitly set elements to the NULL state before\n"
3104 "dropping the final reference, to allow them to clean up.\n"
3105 "This problem may also be caused by a refcounting bug in the\n"
3106 "application or some element.\n",
3107 GST_OBJECT_NAME (element),
3108 gst_element_state_get_name (GST_STATE (element)),
3109 is_locked ? " (locked)" : "");
3115 gst_element_finalize (GObject * object)
3117 GstElement *element = GST_ELEMENT_CAST (object);
3119 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize");
3121 GST_STATE_LOCK (element);
3122 if (element->state_cond)
3123 g_cond_free (element->state_cond);
3124 element->state_cond = NULL;
3125 GST_STATE_UNLOCK (element);
3126 g_static_rec_mutex_free (element->state_lock);
3127 g_slice_free (GStaticRecMutex, element->state_lock);
3128 element->state_lock = NULL;
3130 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize parent");
3132 G_OBJECT_CLASS (parent_class)->finalize (object);
3135 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
3137 * gst_element_save_thyself:
3138 * @element: a #GstElement to save.
3139 * @parent: the xml parent node.
3141 * Saves the element as part of the given XML structure.
3143 * Returns: the new #xmlNodePtr.
3146 gst_element_save_thyself (GstObject * object, xmlNodePtr parent)
3149 GstElementClass *oclass;
3150 GParamSpec **specs, *spec;
3153 GValue value = { 0, };
3154 GstElement *element;
3156 g_return_val_if_fail (GST_IS_ELEMENT (object), parent);
3158 element = GST_ELEMENT_CAST (object);
3160 oclass = GST_ELEMENT_GET_CLASS (element);
3162 xmlNewChild (parent, NULL, (xmlChar *) "name",
3163 (xmlChar *) GST_ELEMENT_NAME (element));
3165 if (oclass->elementfactory != NULL) {
3166 GstElementFactory *factory = (GstElementFactory *) oclass->elementfactory;
3168 xmlNewChild (parent, NULL, (xmlChar *) "type",
3169 (xmlChar *) GST_PLUGIN_FEATURE (factory)->name);
3173 specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (object), &nspecs);
3175 for (i = 0; i < nspecs; i++) {
3177 if (spec->flags & G_PARAM_READABLE) {
3181 g_value_init (&value, spec->value_type);
3183 g_object_get_property (G_OBJECT (element), spec->name, &value);
3184 param = xmlNewChild (parent, NULL, (xmlChar *) "param", NULL);
3185 xmlNewChild (param, NULL, (xmlChar *) "name", (xmlChar *) spec->name);
3187 if (G_IS_PARAM_SPEC_STRING (spec))
3188 contents = g_value_dup_string (&value);
3189 else if (G_IS_PARAM_SPEC_ENUM (spec))
3190 contents = g_strdup_printf ("%d", g_value_get_enum (&value));
3191 else if (G_IS_PARAM_SPEC_INT64 (spec))
3192 contents = g_strdup_printf ("%" G_GINT64_FORMAT,
3193 g_value_get_int64 (&value));
3194 else if (GST_VALUE_HOLDS_STRUCTURE (&value)) {
3195 if (g_value_get_boxed (&value) != NULL) {
3196 contents = g_strdup_value_contents (&value);
3198 contents = g_strdup ("NULL");
3201 contents = g_strdup_value_contents (&value);
3203 xmlNewChild (param, NULL, (xmlChar *) "value", (xmlChar *) contents);
3206 g_value_unset (&value);
3212 pads = g_list_last (GST_ELEMENT_PADS (element));
3215 GstPad *pad = GST_PAD_CAST (pads->data);
3217 /* figure out if it's a direct pad or a ghostpad */
3218 if (GST_ELEMENT_CAST (GST_OBJECT_PARENT (pad)) == element) {
3219 xmlNodePtr padtag = xmlNewChild (parent, NULL, (xmlChar *) "pad", NULL);
3221 gst_object_save_thyself (GST_OBJECT_CAST (pad), padtag);
3223 pads = g_list_previous (pads);
3230 gst_element_restore_thyself (GstObject * object, xmlNodePtr self)
3232 xmlNodePtr children;
3233 GstElement *element;
3235 gchar *value = NULL;
3237 element = GST_ELEMENT_CAST (object);
3238 g_return_if_fail (element != NULL);
3241 children = self->xmlChildrenNode;
3243 if (!strcmp ((char *) children->name, "param")) {
3244 xmlNodePtr child = children->xmlChildrenNode;
3247 if (!strcmp ((char *) child->name, "name")) {
3248 name = (gchar *) xmlNodeGetContent (child);
3249 } else if (!strcmp ((char *) child->name, "value")) {
3250 value = (gchar *) xmlNodeGetContent (child);
3252 child = child->next;
3254 /* FIXME: can this just be g_object_set ? */
3255 gst_util_set_object_arg (G_OBJECT (element), name, value);
3256 /* g_object_set (G_OBJECT (element), name, value, NULL); */
3260 children = children->next;
3264 children = self->xmlChildrenNode;
3266 if (!strcmp ((char *) children->name, "pad")) {
3267 gst_pad_load_and_link (children, GST_OBJECT_CAST (element));
3269 children = children->next;
3272 if (GST_OBJECT_CLASS (parent_class)->restore_thyself)
3273 (GST_OBJECT_CLASS (parent_class)->restore_thyself) (object, self);
3275 #endif /* GST_DISABLE_LOADSAVE */
3278 gst_element_set_bus_func (GstElement * element, GstBus * bus)
3282 g_return_if_fail (GST_IS_ELEMENT (element));
3284 GST_CAT_DEBUG_OBJECT (GST_CAT_PARENTAGE, element, "setting bus to %p", bus);
3286 GST_OBJECT_LOCK (element);
3287 bus_p = &GST_ELEMENT_BUS (element);
3288 gst_object_replace ((GstObject **) bus_p, GST_OBJECT_CAST (bus));
3289 GST_OBJECT_UNLOCK (element);
3293 * gst_element_set_bus:
3294 * @element: a #GstElement to set the bus of.
3295 * @bus: (transfer none): the #GstBus to set.
3297 * Sets the bus of the element. Increases the refcount on the bus.
3298 * For internal use only, unless you're testing elements.
3303 gst_element_set_bus (GstElement * element, GstBus * bus)
3305 GstElementClass *oclass;
3307 g_return_if_fail (GST_IS_ELEMENT (element));
3309 oclass = GST_ELEMENT_GET_CLASS (element);
3311 if (oclass->set_bus)
3312 oclass->set_bus (element, bus);
3316 * gst_element_get_bus:
3317 * @element: a #GstElement to get the bus of.
3319 * Returns the bus of the element. Note that only a #GstPipeline will provide a
3320 * bus for the application.
3322 * Returns: (transfer full): the element's #GstBus. unref after usage.
3327 gst_element_get_bus (GstElement * element)
3329 GstBus *result = NULL;
3331 g_return_val_if_fail (GST_IS_ELEMENT (element), result);
3333 GST_OBJECT_LOCK (element);
3334 if ((result = GST_ELEMENT_BUS (element)))
3335 gst_object_ref (result);
3336 GST_OBJECT_UNLOCK (element);
3338 GST_CAT_DEBUG_OBJECT (GST_CAT_BUS, element, "got bus %" GST_PTR_FORMAT,