gst/gstbin.c: Some documentation updates.
[glsdk/gstreamer0-10.git] / gst / gstpad.c
1 /* GStreamer
2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3  *                    2000 Wim Taymans <wtay@chello.be>
4  *
5  * gstpad.c: Pads for linking elements together
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Library General Public
9  * License as published by the Free Software Foundation; either
10  * version 2 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Library General Public License for more details.
16  *
17  * You should have received a copy of the GNU Library General Public
18  * License along with this library; if not, write to the
19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20  * Boston, MA 02111-1307, USA.
21  */
22 /**
23  * SECTION:gstpad
24  * @short_description: Object contained by elements that allows links to other elements
25  * @see_also: #GstPadTemplate, #GstElement, #GstEvent
26  *
27  * A #GstElement is linked to other elements via "pads", which are extremely 
28  * light-weight generic link points. 
29  * After two pads are retrieved from an element with gst_element_get_pad(), 
30  * the pads can be link with gst_pad_link(). (For quick links,
31  * you can also use gst_element_link(), which will make the obvious
32  * link for you if it's straightforward.)
33  *
34  * Pads are typically created from a #GstPadTemplate with 
35  * gst_pad_new_from_template().
36  *
37  * Pads have #GstCaps attached to it to describe the media type they are capable
38  * of dealing with. 
39  * gst_pad_get_caps() and gst_pad_try_set_caps() are used to manipulate the caps
40  * of the pads. 
41  * Pads created from a pad template cannot set capabilities that are 
42  * incompatible with the pad template capabilities.
43  *
44  * Pads without pad templates can be created with gst_pad_new(),
45  * which takes a direction and a name as an argument.  If the name is NULL,
46  * then a guaranteed unique name will be assigned to it.
47  *
48  * gst_pad_get_parent() will retrieve the #GstElement that owns the pad.
49  *
50  * A #GstElement creating a pad will typically use the various 
51  * gst_pad_set_*_function() calls to register callbacks for various events 
52  * on the pads.
53  *
54  * GstElements will use gst_pad_push() and gst_pad_pull() to push out 
55  * or pull in a buffer.
56  * gst_pad_select() and gst_pad_selectv() are used by plugins to wait for the
57  * first incoming buffer or event on any of the given set of pads.
58  *
59  * To send a #GstEvent on a pad, use gst_pad_send_event().
60  *
61  * Last reviewed on December 13th, 2002 (0.5.0.1)
62  */
64 #include "gst_private.h"
66 #include "gstpad.h"
67 #include "gstpadtemplate.h"
68 #include "gstenumtypes.h"
69 #include "gstmarshal.h"
70 #include "gstutils.h"
71 #include "gstinfo.h"
72 #include "gsterror.h"
73 #include "gstvalue.h"
75 GST_DEBUG_CATEGORY_STATIC (debug_dataflow);
76 #define DEBUG_DATA(obj,data,notice) G_STMT_START{\
77   if (!data) { \
78     GST_CAT_DEBUG_OBJECT (debug_dataflow, obj, "NULL data value"); \
79   } else if (GST_IS_EVENT (data)) { \
80     GST_CAT_DEBUG_OBJECT (debug_dataflow, obj, "%s event %p (type %d, refcount %d)", notice, data, \
81         GST_EVENT_TYPE (data), GST_DATA_REFCOUNT_VALUE (data)); \
82   } else { \
83     GST_CAT_LOG_OBJECT (debug_dataflow, obj, "%s buffer %p (size %u, refcount %d)", notice, data, \
84         GST_BUFFER_SIZE (data), GST_BUFFER_REFCOUNT_VALUE (data)); \
85   } \
86 }G_STMT_END
87 #define GST_CAT_DEFAULT GST_CAT_PADS
89 /* Pad signals and args */
90 enum
91 {
92   PAD_LINKED,
93   PAD_UNLINKED,
94   PAD_REQUEST_LINK,
95   PAD_HAVE_DATA,
96   /* FILL ME */
97   LAST_SIGNAL
98 };
100 enum
102   PAD_PROP_0,
103   PAD_PROP_CAPS,
104   PAD_PROP_DIRECTION,
105   PAD_PROP_TEMPLATE,
106   /* FILL ME */
107 };
109 GType _gst_pad_type = 0;
111 static void gst_pad_class_init (GstPadClass * klass);
112 static void gst_pad_init (GstPad * pad);
113 static void gst_pad_dispose (GObject * object);
114 static void gst_pad_finalize (GObject * object);
115 static void gst_pad_set_property (GObject * object, guint prop_id,
116     const GValue * value, GParamSpec * pspec);
117 static void gst_pad_get_property (GObject * object, guint prop_id,
118     GValue * value, GParamSpec * pspec);
120 static GstCaps *gst_pad_get_caps_unlocked (GstPad * pad);
121 static void gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ);
122 static gboolean gst_pad_activate_default (GstPad * pad);
124 #ifndef GST_DISABLE_LOADSAVE
125 static xmlNodePtr gst_pad_save_thyself (GstObject * object, xmlNodePtr parent);
126 #endif
128 static GstObjectClass *parent_class = NULL;
129 static guint gst_pad_signals[LAST_SIGNAL] = { 0 };
131 static GQuark buffer_quark;
132 static GQuark event_quark;
134 GType
135 gst_pad_get_type (void)
137   if (!_gst_pad_type) {
138     static const GTypeInfo pad_info = {
139       sizeof (GstPadClass), NULL, NULL,
140       (GClassInitFunc) gst_pad_class_init, NULL, NULL,
141       sizeof (GstPad),
142       0,
143       (GInstanceInitFunc) gst_pad_init, NULL
144     };
146     _gst_pad_type = g_type_register_static (GST_TYPE_OBJECT, "GstPad",
147         &pad_info, 0);
149     buffer_quark = g_quark_from_static_string ("buffer");
150     event_quark = g_quark_from_static_string ("event");
152     GST_DEBUG_CATEGORY_INIT (debug_dataflow, "GST_DATAFLOW",
153         GST_DEBUG_BOLD | GST_DEBUG_FG_GREEN, "dataflow inside pads");
154   }
155   return _gst_pad_type;
158 static gboolean
159 _gst_do_pass_data_accumulator (GSignalInvocationHint * ihint,
160     GValue * return_accu, const GValue * handler_return, gpointer dummy)
162   gboolean ret = g_value_get_boolean (handler_return);
164   GST_DEBUG ("accumulated %d", ret);
165   g_value_set_boolean (return_accu, ret);
167   return ret;
170 static gboolean
171 default_have_data (GstPad * pad, GstMiniObject * o)
173   return TRUE;
176 static void
177 gst_pad_class_init (GstPadClass * klass)
179   GObjectClass *gobject_class;
182   GstObjectClass *gstobject_class;
184   gobject_class = (GObjectClass *) klass;
185   gstobject_class = (GstObjectClass *) klass;
187   parent_class = g_type_class_ref (GST_TYPE_OBJECT);
189   gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_pad_dispose);
190   gobject_class->finalize = GST_DEBUG_FUNCPTR (gst_pad_finalize);
191   gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_pad_set_property);
192   gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_pad_get_property);
194   /**
195    * GstPad::linked:
196    * @pad: the pad that emitted the signal
197    * @peer: the peer pad that has been connected
198    *
199    * Signals that a pad has been linked to the peer pad.
200    */
201   gst_pad_signals[PAD_LINKED] =
202       g_signal_new ("linked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
203       G_STRUCT_OFFSET (GstPadClass, linked), NULL, NULL,
204       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
205   /**
206    * GstPad::unlinked:
207    * @pad: the pad that emitted the signal
208    * @peer: the peer pad that has been disconnected
209    *
210    * Signals that a pad has been unlinked from the peer pad.
211    */
212   gst_pad_signals[PAD_UNLINKED] =
213       g_signal_new ("unlinked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
214       G_STRUCT_OFFSET (GstPadClass, unlinked), NULL, NULL,
215       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
216   /**
217    * GstPad::request-link:
218    * @pad: the pad that emitted the signal
219    * @peer: the peer pad for which a connection is requested
220    *
221    * Signals that a pad connection has been requested.
222    */
223   gst_pad_signals[PAD_REQUEST_LINK] =
224       g_signal_new ("request-link", G_TYPE_FROM_CLASS (klass),
225       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstPadClass, request_link), NULL,
226       NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 0);
228   /**
229    * GstPad::have-data:
230    * @pad: the pad that emitted the signal
231    * @mini_obj: new data
232    *
233    * Signals that new data is available on the pad. This signal is used
234    * internally for implementing pad probes.
235    * See gst_pad_add_*_probe functions.
236    *
237    * Returns: %TRUE to keep the data, %FALSE to drop it
238    */
239   gst_pad_signals[PAD_HAVE_DATA] =
240       g_signal_new ("have-data", G_TYPE_FROM_CLASS (klass),
241       G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
242       G_STRUCT_OFFSET (GstPadClass, have_data),
243       _gst_do_pass_data_accumulator,
244       NULL, gst_marshal_BOOLEAN__POINTER, G_TYPE_BOOLEAN, 1,
245       GST_TYPE_MINI_OBJECT);
247   g_object_class_install_property (G_OBJECT_CLASS (klass), PAD_PROP_CAPS,
248       g_param_spec_boxed ("caps", "Caps", "The capabilities of the pad",
249           GST_TYPE_CAPS, G_PARAM_READABLE));
250   g_object_class_install_property (G_OBJECT_CLASS (klass), PAD_PROP_DIRECTION,
251       g_param_spec_enum ("direction", "Direction", "The direction of the pad",
252           GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,
253           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
254   g_object_class_install_property (G_OBJECT_CLASS (klass), PAD_PROP_TEMPLATE,
255       g_param_spec_object ("template", "Template",
256           "The GstPadTemplate of this pad", GST_TYPE_PAD_TEMPLATE,
257           G_PARAM_READWRITE));
259 #ifndef GST_DISABLE_LOADSAVE
260   gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_pad_save_thyself);
261 #endif
262   gstobject_class->path_string_separator = ".";
264   klass->have_data = default_have_data;
267 static void
268 gst_pad_init (GstPad * pad)
270   pad->direction = GST_PAD_UNKNOWN;
271   pad->peer = NULL;
273   pad->chainfunc = NULL;
275   pad->caps = NULL;
277   pad->linkfunc = NULL;
278   pad->getcapsfunc = NULL;
280   pad->activatefunc = gst_pad_activate_default;
281   pad->eventfunc = gst_pad_event_default;
282   pad->querytypefunc = gst_pad_get_query_types_default;
283   pad->queryfunc = gst_pad_query_default;
284   pad->intlinkfunc = gst_pad_get_internal_links_default;
286   pad->do_buffer_signals = 0;
287   pad->do_event_signals = 0;
289   GST_PAD_UNSET_FLUSHING (pad);
291   pad->preroll_lock = g_mutex_new ();
292   pad->preroll_cond = g_cond_new ();
294   pad->stream_rec_lock = g_new (GStaticRecMutex, 1);
295   g_static_rec_mutex_init (pad->stream_rec_lock);
297   pad->block_cond = g_cond_new ();
300 static void
301 gst_pad_dispose (GObject * object)
303   GstPad *pad = GST_PAD (object);
305   GST_CAT_DEBUG (GST_CAT_REFCOUNTING, "dispose %s:%s",
306       GST_DEBUG_PAD_NAME (pad));
308   /* we don't hold a ref to the peer so we can just set the
309    * peer to NULL. */
310   GST_PAD_PEER (pad) = NULL;
312   /* clear the caps */
313   gst_caps_replace (&GST_PAD_CAPS (pad), NULL);
315   gst_pad_set_pad_template (pad, NULL);
317   G_OBJECT_CLASS (parent_class)->dispose (object);
320 static void
321 gst_pad_finalize (GObject * object)
323   GstPad *pad = GST_PAD (object);
324   GstTask *task;
326   /* in case the task is still around, clean it up */
327   if ((task = GST_PAD_TASK (pad))) {
328     gst_task_join (task);
329     GST_PAD_TASK (pad) = NULL;
330     gst_object_unref (task);
331   }
333   if (pad->stream_rec_lock) {
334     g_static_rec_mutex_free (pad->stream_rec_lock);
335     g_free (pad->stream_rec_lock);
336     pad->stream_rec_lock = NULL;
337   }
338   if (pad->preroll_lock) {
339     g_mutex_free (pad->preroll_lock);
340     g_cond_free (pad->preroll_cond);
341     pad->preroll_lock = NULL;
342     pad->preroll_cond = NULL;
343   }
344   if (pad->block_cond) {
345     g_cond_free (pad->block_cond);
346     pad->block_cond = NULL;
347   }
349   G_OBJECT_CLASS (parent_class)->finalize (object);
352 static void
353 gst_pad_set_property (GObject * object, guint prop_id,
354     const GValue * value, GParamSpec * pspec)
356   g_return_if_fail (GST_IS_PAD (object));
358   switch (prop_id) {
359     case PAD_PROP_DIRECTION:
360       GST_PAD_DIRECTION (object) = g_value_get_enum (value);
361       break;
362     case PAD_PROP_TEMPLATE:
363       gst_pad_set_pad_template (GST_PAD_CAST (object),
364           (GstPadTemplate *) g_value_dup_object (value));
365       break;
366     default:
367       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
368       break;
369   }
372 static void
373 gst_pad_get_property (GObject * object, guint prop_id,
374     GValue * value, GParamSpec * pspec)
376   g_return_if_fail (GST_IS_PAD (object));
378   switch (prop_id) {
379     case PAD_PROP_CAPS:
380       g_value_set_boxed (value, GST_PAD_CAPS (object));
381       break;
382     case PAD_PROP_DIRECTION:
383       g_value_set_enum (value, GST_PAD_DIRECTION (object));
384       break;
385     case PAD_PROP_TEMPLATE:
386       g_value_set_object (value, GST_PAD_TEMPLATE (object));
387       break;
388     default:
389       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
390       break;
391   }
394 /**
395  * gst_pad_new:
396  * @name: the name of the new pad.
397  * @direction: the #GstPadDirection of the pad.
398  *
399  * Creates a new pad with the given name in the given direction.
400  * If name is NULL, a guaranteed unique name (across all pads) 
401  * will be assigned.
402  * This function makes a copy of the name so you can safely free the name.
403  *
404  * Returns: a new #GstPad, or NULL in case of an error.
405  *
406  * MT safe.
407  */
408 GstPad *
409 gst_pad_new (const gchar * name, GstPadDirection direction)
411   return g_object_new (GST_TYPE_PAD,
412       "name", name, "direction", direction, NULL);
415 /**
416  * gst_pad_new_from_template:
417  * @templ: the pad template to use
418  * @name: the name of the element
419  *
420  * Creates a new pad with the given name from the given template.
421  * If name is NULL, a guaranteed unique name (across all pads) 
422  * will be assigned.
423  * This function makes a copy of the name so you can safely free the name.
424  *
425  * Returns: a new #GstPad, or NULL in case of an error.
426  */
427 GstPad *
428 gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name)
430   g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
432   return g_object_new (GST_TYPE_PAD,
433       "name", name, "direction", templ->direction, "template", templ, NULL);
436 /**
437  * gst_pad_get_direction:
438  * @pad: a #GstPad to get the direction of.
439  *
440  * Gets the direction of the pad. The direction of the pad is
441  * decided at construction time so this function does not take 
442  * the LOCK.
443  *
444  * Returns: the #GstPadDirection of the pad.
445  *
446  * MT safe.
447  */
448 GstPadDirection
449 gst_pad_get_direction (GstPad * pad)
451   GstPadDirection result;
453   /* PAD_UNKNOWN is a little silly but we need some sort of
454    * error return value */
455   g_return_val_if_fail (GST_IS_PAD (pad), GST_PAD_UNKNOWN);
457   GST_LOCK (pad);
458   result = GST_PAD_DIRECTION (pad);
459   GST_UNLOCK (pad);
461   return result;
464 static gboolean
465 gst_pad_activate_default (GstPad * pad)
467   return gst_pad_activate_push (pad, TRUE);
470 static void
471 pre_activate_switch (GstPad * pad, gboolean new_active)
473   if (new_active) {
474     return;
475   } else {
476     GST_LOCK (pad);
477     GST_PAD_SET_FLUSHING (pad);
478     /* unlock blocked pads so element can resume and stop */
479     GST_PAD_BLOCK_SIGNAL (pad);
480     GST_UNLOCK (pad);
481   }
484 static void
485 post_activate_switch (GstPad * pad, gboolean new_active)
487   if (new_active) {
488     GST_LOCK (pad);
489     GST_PAD_UNSET_FLUSHING (pad);
490     GST_UNLOCK (pad);
491   } else {
492     /* make streaming stop */
493     GST_STREAM_LOCK (pad);
494     GST_STREAM_UNLOCK (pad);
495   }
498 /**
499  * gst_pad_set_active:
500  * @pad: the #GstPad to activate or deactivate.
501  * @active: whether or not the pad should be active.
502  *
503  * Activates or deactivates the given pad. Must be called with the %GST_STATE_LOCK.
504  * Normally called from within core state change functions.
505  *
506  * If @active, makes sure the pad is active. If it is already active, either in
507  * push or pull mode, just return. Otherwise dispatches to the pad's activate
508  * function to perform the actual activation.
509  *
510  * If not @active, checks the pad's current mode and calls
511  * gst_pad_activate_push() or gst_pad_activate_pull(), as appropriate, with a
512  * FALSE argument.
513  *
514  * Returns: TRUE if the operation was successfull.
515  *
516  * MT safe. Must be called with %GST_STATE_LOCK.
517  */
518 gboolean
519 gst_pad_set_active (GstPad * pad, gboolean active)
521   GstActivateMode old;
522   gboolean ret = FALSE;
524   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
526   GST_LOCK (pad);
527   old = GST_PAD_ACTIVATE_MODE (pad);
528   GST_UNLOCK (pad);
530   if (active) {
531     switch (old) {
532       case GST_ACTIVATE_PUSH:
533       case GST_ACTIVATE_PULL:
534         ret = TRUE;
535         break;
536       case GST_ACTIVATE_NONE:
537         ret = (GST_PAD_ACTIVATEFUNC (pad)) (pad);
538         break;
539     }
540   } else {
541     switch (old) {
542       case GST_ACTIVATE_PUSH:
543         ret = gst_pad_activate_push (pad, FALSE);
544         break;
545       case GST_ACTIVATE_PULL:
546         ret = gst_pad_activate_pull (pad, FALSE);
547         break;
548       case GST_ACTIVATE_NONE:
549         ret = TRUE;
550         break;
551     }
552   }
554   return ret;
557 /**
558  * gst_pad_activate_pull:
559  * @pad: the #GstPad to activate or deactivate.
560  * @active: whether or not the pad should be active.
561  *
562  * Activates or deactivates the given pad in pull mode via dispatching to the
563  * pad's activatepullfunc. For use from within pad activation functions only.
564  * When called on sink pads, will first proxy the call to the peer pad, which is
565  * expected to activate its internally linked pads from within its activate_pull
566  * function.
567  *
568  * If you don't know what this is, you probably don't want to call it.
569  *
570  * Returns: TRUE if the operation was successfull.
571  *
572  * MT safe.
573  */
574 gboolean
575 gst_pad_activate_pull (GstPad * pad, gboolean active)
577   GstActivateMode old;
579   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
581   GST_LOCK (pad);
582   old = GST_PAD_ACTIVATE_MODE (pad);
583   GST_UNLOCK (pad);
585   if ((active && old == GST_ACTIVATE_PULL)
586       || (!active && old == GST_ACTIVATE_NONE))
587     goto was_ok;
589   if (active) {
590     g_return_val_if_fail (old == GST_ACTIVATE_NONE, FALSE);
591   } else {
592     g_return_val_if_fail (old == GST_ACTIVATE_PULL, FALSE);
593   }
595   if (gst_pad_get_direction (pad) == GST_PAD_SINK) {
596     GstPad *peer = gst_pad_get_peer (pad);
598     if (peer) {
599       if (!gst_pad_activate_pull (peer, active)) {
600         GST_LOCK (peer);
601         GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
602             "activate_pull on peer (%s:%s) failed", GST_DEBUG_PAD_NAME (peer));
603         GST_UNLOCK (peer);
604         gst_object_unref (peer);
605         goto failure;
606       }
607     }
608   }
610   pre_activate_switch (pad, active);
612   if (GST_PAD_ACTIVATEPULLFUNC (pad)) {
613     if (GST_PAD_ACTIVATEPULLFUNC (pad) (pad, active)) {
614       goto success;
615     } else {
616       goto failure;
617     }
618   } else {
619     /* can happen for sinks of passthrough elements */
620     goto success;
621   }
623 was_ok:
624   {
625     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in pull mode",
626         active ? "activated" : "deactivated");
627     return TRUE;
628   }
630 success:
631   {
632     GST_LOCK (pad);
633     GST_PAD_ACTIVATE_MODE (pad) =
634         active ? GST_ACTIVATE_PULL : GST_ACTIVATE_NONE;
635     GST_UNLOCK (pad);
636     post_activate_switch (pad, active);
638     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in pull mode",
639         active ? "activated" : "deactivated");
640     return TRUE;
641   }
643 failure:
644   {
645     GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in pull mode",
646         active ? "activate" : "deactivate");
647     return FALSE;
648   }
651 /**
652  * gst_pad_activate_push:
653  * @pad: the #GstPad to activate or deactivate.
654  * @active: whether or not the pad should be active.
655  *
656  * Activates or deactivates the given pad in push mode via dispatching to the
657  * pad's activatepushfunc. For use from within pad activation functions only.
658  *
659  * If you don't know what this is, you probably don't want to call it.
660  *
661  * Returns: TRUE if the operation was successfull.
662  *
663  * MT safe.
664  */
665 gboolean
666 gst_pad_activate_push (GstPad * pad, gboolean active)
668   GstActivateMode old;
670   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
671   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "trying to set %s in push mode",
672       active ? "activated" : "deactivated");
674   GST_LOCK (pad);
675   old = GST_PAD_ACTIVATE_MODE (pad);
676   GST_UNLOCK (pad);
678   if ((active && old == GST_ACTIVATE_PUSH)
679       || (!active && old == GST_ACTIVATE_NONE))
680     goto was_ok;
682   if (active) {
683     g_return_val_if_fail (old == GST_ACTIVATE_NONE, FALSE);
684   } else {
685     g_return_val_if_fail (old == GST_ACTIVATE_PUSH, FALSE);
686   }
688   pre_activate_switch (pad, active);
690   if (GST_PAD_ACTIVATEPUSHFUNC (pad)) {
691     if (GST_PAD_ACTIVATEPUSHFUNC (pad) (pad, active)) {
692       goto success;
693     } else {
694       goto failure;
695     }
696   } else {
697     /* quite ok, element relies on state change func to prepare itself */
698     goto success;
699   }
701 was_ok:
702   {
703     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in push mode",
704         active ? "activated" : "deactivated");
705     return TRUE;
706   }
708 success:
709   {
710     GST_LOCK (pad);
711     GST_PAD_ACTIVATE_MODE (pad) =
712         active ? GST_ACTIVATE_PUSH : GST_ACTIVATE_NONE;
713     GST_UNLOCK (pad);
714     post_activate_switch (pad, active);
716     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in push mode",
717         active ? "activated" : "deactivated");
718     return TRUE;
719   }
721 failure:
722   {
723     GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in push mode",
724         active ? "activate" : "deactivate");
725     return FALSE;
726   }
729 /**
730  * gst_pad_is_active:
731  * @pad: the #GstPad to query
732  *
733  * Query if a pad is active
734  *
735  * Returns: TRUE if the pad is active.
736  *
737  * MT safe.
738  */
739 gboolean
740 gst_pad_is_active (GstPad * pad)
742   gboolean result = FALSE;
744   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
746   GST_LOCK (pad);
747   result = GST_PAD_MODE_ACTIVATE (GST_PAD_ACTIVATE_MODE (pad));
748   GST_UNLOCK (pad);
750   return result;
753 /**
754  * gst_pad_set_blocked_async:
755  * @pad: the #GstPad to block or unblock
756  * @blocked: boolean indicating we should block or unblock
757  * @callback: #GstPadBlockCallback that will be called when the
758  *            operation succeeds.
759  * @user_data: user data passed to the callback
760  *
761  * Blocks or unblocks the dataflow on a pad. The provided callback
762  * is called when the operation succeeds. This can take a while as
763  * the pad can only become blocked when real dataflow is happening.
764  * When the pipeline is stalled, for example in PAUSED, this can
765  * take an indeterminate amount of time.
766  * You can pass NULL as the callback to make this call block. Be
767  * carefull with this blocking call as it might not return for
768  * reasons stated above.
769  *
770  * Returns: TRUE if the pad could be blocked. This function can fail
771  *   if wrong parameters were passed or the pad was already in the 
772  *   requested state.
773  *
774  * MT safe.
775  */
776 gboolean
777 gst_pad_set_blocked_async (GstPad * pad, gboolean blocked,
778     GstPadBlockCallback callback, gpointer user_data)
780   gboolean was_blocked;
782   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
784   GST_LOCK (pad);
786   was_blocked = GST_PAD_IS_BLOCKED (pad);
788   if (G_UNLIKELY (was_blocked == blocked))
789     goto had_right_state;
791   if (blocked) {
792     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocking pad %s:%s",
793         GST_DEBUG_PAD_NAME (pad));
795     GST_FLAG_SET (pad, GST_PAD_BLOCKED);
796     pad->block_callback = callback;
797     pad->block_data = user_data;
798     if (!callback) {
799       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for block");
800       GST_PAD_BLOCK_WAIT (pad);
801       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocked");
802     }
803   } else {
804     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocking pad %s:%s",
805         GST_DEBUG_PAD_NAME (pad));
807     GST_FLAG_UNSET (pad, GST_PAD_BLOCKED);
809     pad->block_callback = callback;
810     pad->block_data = user_data;
812     if (callback) {
813       GST_PAD_BLOCK_SIGNAL (pad);
814     } else {
815       GST_PAD_BLOCK_SIGNAL (pad);
816       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for unblock");
817       GST_PAD_BLOCK_WAIT (pad);
818       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocked");
819     }
820   }
821   GST_UNLOCK (pad);
823   return TRUE;
825 had_right_state:
826   {
827     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
828         "pad %s:%s was in right state", GST_DEBUG_PAD_NAME (pad));
829     GST_UNLOCK (pad);
830     return FALSE;
831   }
834 /**
835  * gst_pad_set_blocked:
836  * @pad: the #GstPad to block or unblock
837  * @blocked: boolean indicating we should block or unblock
838  *
839  * Blocks or unblocks the dataflow on a pad. This function is
840  * a shortcut for @gst_pad_set_blocked_async() with a NULL
841  * callback.
842  *
843  * Returns: TRUE if the pad could be blocked. This function can fail
844  *   wrong parameters were passed or the pad was already in the 
845  *   requested state.
846  *
847  * MT safe.
848  */
849 gboolean
850 gst_pad_set_blocked (GstPad * pad, gboolean blocked)
852   return gst_pad_set_blocked_async (pad, blocked, NULL, NULL);
855 /**
856  * gst_pad_is_blocked:
857  * @pad: the #GstPad to query 
858  *
859  * Checks if the pad is blocked or not. This function returns the
860  * last requested state of the pad. It is not certain that the pad
861  * is actually blocked at this point.
862  *
863  * Returns: TRUE if the pad is blocked.
864  *
865  * MT safe.
866  */
867 gboolean
868 gst_pad_is_blocked (GstPad * pad)
870   gboolean result = FALSE;
872   g_return_val_if_fail (GST_IS_PAD (pad), result);
874   GST_LOCK (pad);
875   result = GST_FLAG_IS_SET (pad, GST_PAD_BLOCKED);
876   GST_UNLOCK (pad);
878   return result;
881 /**
882  * gst_pad_set_activate_function:
883  * @pad: a sink #GstPad.
884  * @activate: the #GstPadActivateFunction to set.
885  *
886  * Sets the given activate function for the pad. The activate function will
887  * dispatch to activate_push or activate_pull to perform the actual activation.
888  * Only makes sense to set on sink pads.
889  *
890  * Call this function if your sink pad can start a pull-based task.
891  */
892 void
893 gst_pad_set_activate_function (GstPad * pad, GstPadActivateFunction activate)
895   g_return_if_fail (GST_IS_PAD (pad));
897   GST_PAD_ACTIVATEFUNC (pad) = activate;
898   GST_CAT_DEBUG (GST_CAT_PADS, "activatefunc for %s:%s set to %s",
899       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (activate));
902 /**
903  * gst_pad_set_activatepull_function:
904  * @pad: a sink #GstPad.
905  * @activatepull: the #GstPadActivateModeFunction to set.
906  *
907  * Sets the given activate_pull function for the pad. An activate_pull function
908  * prepares the element and any upstream connections for pulling. See XXX
909  * part-activation.txt for details.
910  */
911 void
912 gst_pad_set_activatepull_function (GstPad * pad,
913     GstPadActivateModeFunction activatepull)
915   g_return_if_fail (GST_IS_PAD (pad));
917   GST_PAD_ACTIVATEPULLFUNC (pad) = activatepull;
918   GST_CAT_DEBUG (GST_CAT_PADS, "activatepullfunc for %s:%s set to %s",
919       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (activatepull));
922 /**
923  * gst_pad_set_activatepush_function:
924  * @pad: a sink #GstPad.
925  * @activatepush: the #GstPadActivateModeFunction to set.
926  *
927  * Sets the given activate_push function for the pad. An activate_push function
928  * prepares the element for pushing. See XXX part-activation.txt for details.
929  */
930 void
931 gst_pad_set_activatepush_function (GstPad * pad,
932     GstPadActivateModeFunction activatepush)
934   g_return_if_fail (GST_IS_PAD (pad));
936   GST_PAD_ACTIVATEPUSHFUNC (pad) = activatepush;
937   GST_CAT_DEBUG (GST_CAT_PADS, "activatepushfunc for %s:%s set to %s",
938       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (activatepush));
941 /**
942  * gst_pad_set_chain_function:
943  * @pad: a sink #GstPad.
944  * @chain: the #GstPadChainFunction to set.
945  *
946  * Sets the given chain function for the pad. The chain function is called to
947  * process a #GstBuffer input buffer.
948  */
949 void
950 gst_pad_set_chain_function (GstPad * pad, GstPadChainFunction chain)
952   g_return_if_fail (GST_IS_PAD (pad));
953   g_return_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK);
955   GST_PAD_CHAINFUNC (pad) = chain;
956   GST_CAT_DEBUG (GST_CAT_PADS, "chainfunc for %s:%s set to %s",
957       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (chain));
960 /**
961  * gst_pad_set_getrange_function:
962  * @pad: a source #GstPad.
963  * @get: the #GstPadGetRangeFunction to set.
964  *
965  * Sets the given getrange function for the pad. The getrange function is called to
966  * produce a new #GstBuffer to start the processing pipeline. Getrange functions cannot
967  * return %NULL.
968  */
969 void
970 gst_pad_set_getrange_function (GstPad * pad, GstPadGetRangeFunction get)
972   g_return_if_fail (GST_IS_PAD (pad));
973   g_return_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC);
975   GST_PAD_GETRANGEFUNC (pad) = get;
977   GST_CAT_DEBUG (GST_CAT_PADS, "getrangefunc for %s:%s  set to %s",
978       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (get));
981 /**
982  * gst_pad_set_checkgetrange_function:
983  * @pad: a source #GstPad.
984  * @check: the #GstPadCheckGetRangeFunction to set.
985  *
986  * Sets the given checkgetrange function for the pad. Implement this function on
987  * a pad if you dynamically support getrange based scheduling on the pad.
988  */
989 void
990 gst_pad_set_checkgetrange_function (GstPad * pad,
991     GstPadCheckGetRangeFunction check)
993   g_return_if_fail (GST_IS_PAD (pad));
994   g_return_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC);
996   GST_PAD_CHECKGETRANGEFUNC (pad) = check;
998   GST_CAT_DEBUG (GST_CAT_PADS, "checkgetrangefunc for %s:%s  set to %s",
999       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (check));
1002 /**
1003  * gst_pad_set_event_function:
1004  * @pad: a source #GstPad.
1005  * @event: the #GstPadEventFunction to set.
1006  *
1007  * Sets the given event handler for the pad.
1008  */
1009 void
1010 gst_pad_set_event_function (GstPad * pad, GstPadEventFunction event)
1012   g_return_if_fail (GST_IS_PAD (pad));
1014   GST_PAD_EVENTFUNC (pad) = event;
1016   GST_CAT_DEBUG (GST_CAT_PADS, "eventfunc for %s:%s  set to %s",
1017       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (event));
1020 /**
1021  * gst_pad_set_query_function:
1022  * @pad: a #GstPad of either direction.
1023  * @query: the #GstPadQueryFunction to set.
1024  *
1025  * Set the given query function for the pad.
1026  */
1027 void
1028 gst_pad_set_query_function (GstPad * pad, GstPadQueryFunction query)
1030   g_return_if_fail (GST_IS_PAD (pad));
1032   GST_PAD_QUERYFUNC (pad) = query;
1034   GST_CAT_DEBUG (GST_CAT_PADS, "queryfunc for %s:%s  set to %s",
1035       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (query));
1038 /**
1039  * gst_pad_set_query_type_function:
1040  * @pad: a #GstPad of either direction.
1041  * @type_func: the #GstPadQueryTypeFunction to set.
1042  *
1043  * Set the given query type function for the pad.
1044  */
1045 void
1046 gst_pad_set_query_type_function (GstPad * pad,
1047     GstPadQueryTypeFunction type_func)
1049   g_return_if_fail (GST_IS_PAD (pad));
1051   GST_PAD_QUERYTYPEFUNC (pad) = type_func;
1053   GST_CAT_DEBUG (GST_CAT_PADS, "querytypefunc for %s:%s  set to %s",
1054       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (type_func));
1057 /**
1058  * gst_pad_get_query_types:
1059  * @pad: a #GstPad.
1060  *
1061  * Get an array of supported queries that can be performed
1062  * on this pad.
1063  *
1064  * Returns: a zero-terminated array of #GstQueryType.
1065  */
1066 const GstQueryType *
1067 gst_pad_get_query_types (GstPad * pad)
1069   GstPadQueryTypeFunction func;
1071   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1073   if (G_UNLIKELY ((func = GST_PAD_QUERYTYPEFUNC (pad)) == NULL))
1074     goto no_func;
1076   return func (pad);
1078 no_func:
1079   {
1080     return NULL;
1081   }
1084 static gboolean
1085 gst_pad_get_query_types_dispatcher (GstPad * pad, const GstQueryType ** data)
1087   *data = gst_pad_get_query_types (pad);
1089   return TRUE;
1092 /**
1093  * gst_pad_get_query_types_default:
1094  * @pad: a #GstPad.
1095  *
1096  * Invoke the default dispatcher for the query types on
1097  * the pad.
1098  *
1099  * Returns: an zero-terminated array of #GstQueryType, or NULL if none of the
1100  * internally-linked pads has a query types function.
1101  */
1102 const GstQueryType *
1103 gst_pad_get_query_types_default (GstPad * pad)
1105   GstQueryType *result = NULL;
1107   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1109   gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
1110       gst_pad_get_query_types_dispatcher, &result);
1112   return result;
1115 /**
1116  * gst_pad_set_internal_link_function:
1117  * @pad: a #GstPad of either direction.
1118  * @intlink: the #GstPadIntLinkFunction to set.
1119  *
1120  * Sets the given internal link function for the pad.
1121  */
1122 void
1123 gst_pad_set_internal_link_function (GstPad * pad, GstPadIntLinkFunction intlink)
1125   g_return_if_fail (GST_IS_PAD (pad));
1127   GST_PAD_INTLINKFUNC (pad) = intlink;
1128   GST_CAT_DEBUG (GST_CAT_PADS, "internal link for %s:%s  set to %s",
1129       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (intlink));
1132 /**
1133  * gst_pad_set_link_function:
1134  * @pad: a #GstPad.
1135  * @link: the #GstPadLinkFunction to set.
1136  * 
1137  * Sets the given link function for the pad. It will be called when the pad is
1138  * linked or relinked with caps. The caps passed to the link function is
1139  * the caps for the connnection. It can contain a non fixed caps.
1140  * 
1141  * The return value GST_PAD_LINK_OK should be used when the connection can be
1142  * made.
1143  * 
1144  * The return value GST_PAD_LINK_REFUSED should be used when the connection
1145  * cannot be made for some reason.
1146  */
1147 void
1148 gst_pad_set_link_function (GstPad * pad, GstPadLinkFunction link)
1150   g_return_if_fail (GST_IS_PAD (pad));
1152   GST_PAD_LINKFUNC (pad) = link;
1153   GST_CAT_DEBUG (GST_CAT_PADS, "linkfunc for %s:%s set to %s",
1154       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (link));
1157 /**
1158  * gst_pad_set_unlink_function:
1159  * @pad: a #GstPad.
1160  * @unlink: the #GstPadUnlinkFunction to set.
1161  *
1162  * Sets the given unlink function for the pad. It will be called
1163  * when the pad is unlinked.
1164  */
1165 void
1166 gst_pad_set_unlink_function (GstPad * pad, GstPadUnlinkFunction unlink)
1168   g_return_if_fail (GST_IS_PAD (pad));
1170   GST_PAD_UNLINKFUNC (pad) = unlink;
1171   GST_CAT_DEBUG (GST_CAT_PADS, "unlinkfunc for %s:%s set to %s",
1172       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (unlink));
1175 /**
1176  * gst_pad_set_getcaps_function:
1177  * @pad: a #GstPad.
1178  * @getcaps: the #GstPadGetCapsFunction to set.
1179  * 
1180  * Sets the given getcaps function for the pad. @getcaps should return the
1181  * allowable caps for a pad in the context of the element's state, its link to
1182  * other elements, and the devices or files it has opened. These caps must be a
1183  * subset of the pad template caps. In the NULL state with no links, @getcaps
1184  * should ideally return the same caps as the pad template. In rare
1185  * circumstances, an object property can affect the caps returned by @getcaps,
1186  * but this is discouraged.
1187  *
1188  * You do not need to call this function if @pad's allowed caps are always the
1189  * same as the pad template caps. This can only be true if the padtemplate 
1190  * has fixed simple caps.
1191  *
1192  * For most filters, the caps returned by @getcaps is directly affected by the
1193  * allowed caps on other pads. For demuxers and decoders, the caps returned by
1194  * the srcpad's getcaps function is directly related to the stream data. Again,
1195  * @getcaps should return the most specific caps it reasonably can, since this
1196  * helps with autoplugging. 
1197  *
1198  * Note that the return value from @getcaps is owned by the caller, so the caller
1199  * should unref the caps after usage.
1200  */
1201 void
1202 gst_pad_set_getcaps_function (GstPad * pad, GstPadGetCapsFunction getcaps)
1204   g_return_if_fail (GST_IS_PAD (pad));
1206   GST_PAD_GETCAPSFUNC (pad) = getcaps;
1207   GST_CAT_DEBUG (GST_CAT_PADS, "getcapsfunc for %s:%s set to %s",
1208       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (getcaps));
1211 /**
1212  * gst_pad_set_acceptcaps_function:
1213  * @pad: a #GstPad.
1214  * @acceptcaps: the #GstPadAcceptCapsFunction to set.
1215  *
1216  * Sets the given acceptcaps function for the pad.  The acceptcaps function
1217  * will be called to check if the pad can accept the given caps.
1218  */
1219 void
1220 gst_pad_set_acceptcaps_function (GstPad * pad,
1221     GstPadAcceptCapsFunction acceptcaps)
1223   g_return_if_fail (GST_IS_PAD (pad));
1225   GST_PAD_ACCEPTCAPSFUNC (pad) = acceptcaps;
1226   GST_CAT_DEBUG (GST_CAT_PADS, "acceptcapsfunc for %s:%s set to %s",
1227       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (acceptcaps));
1230 /**
1231  * gst_pad_set_fixatecaps_function:
1232  * @pad: a #GstPad.
1233  * @fixatecaps: the #GstPadFixateCapsFunction to set.
1234  *
1235  * Sets the given fixatecaps function for the pad.  The fixatecaps function
1236  * will be called whenever the default values for a GstCaps needs to be
1237  * filled in.
1238  */
1239 void
1240 gst_pad_set_fixatecaps_function (GstPad * pad,
1241     GstPadFixateCapsFunction fixatecaps)
1243   g_return_if_fail (GST_IS_PAD (pad));
1245   GST_PAD_FIXATECAPSFUNC (pad) = fixatecaps;
1246   GST_CAT_DEBUG (GST_CAT_PADS, "fixatecapsfunc for %s:%s set to %s",
1247       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (fixatecaps));
1250 /**
1251  * gst_pad_set_setcaps_function:
1252  * @pad: a #GstPad.
1253  * @setcaps: the #GstPadSetCapsFunction to set.
1254  *
1255  * Sets the given setcaps function for the pad.  The setcaps function
1256  * will be called whenever a buffer with a new media type is pushed or
1257  * pulled from the pad. The pad/element needs to update it's internal
1258  * structures to process the new media type. If this new type is not
1259  * acceptable, the setcaps function should return FALSE.
1260  */
1261 void
1262 gst_pad_set_setcaps_function (GstPad * pad, GstPadSetCapsFunction setcaps)
1264   g_return_if_fail (GST_IS_PAD (pad));
1266   GST_PAD_SETCAPSFUNC (pad) = setcaps;
1267   GST_CAT_DEBUG (GST_CAT_PADS, "setcapsfunc for %s:%s set to %s",
1268       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (setcaps));
1271 /**
1272  * gst_pad_set_bufferalloc_function:
1273  * @pad: a sink #GstPad.
1274  * @bufalloc: the #GstPadBufferAllocFunction to set.
1275  *
1276  * Sets the given bufferalloc function for the pad. Note that the
1277  * bufferalloc function can only be set on sinkpads.
1278  */
1279 void
1280 gst_pad_set_bufferalloc_function (GstPad * pad,
1281     GstPadBufferAllocFunction bufalloc)
1283   g_return_if_fail (GST_IS_PAD (pad));
1284   g_return_if_fail (GST_PAD_IS_SINK (pad));
1286   GST_PAD_BUFFERALLOCFUNC (pad) = bufalloc;
1287   GST_CAT_DEBUG (GST_CAT_PADS, "bufferallocfunc for %s:%s set to %s",
1288       GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (bufalloc));
1291 /**
1292  * gst_pad_unlink:
1293  * @srcpad: the source #GstPad to unlink.
1294  * @sinkpad: the sink #GstPad to unlink.
1295  *
1296  * Unlinks the source pad from the sink pad. Will emit the "unlinked" signal on
1297  * both pads.
1298  *
1299  * Returns: TRUE if the pads were unlinked. This function returns FALSE if
1300  * the pads were not linked together.
1301  *
1302  * MT safe.
1303  */
1304 gboolean
1305 gst_pad_unlink (GstPad * srcpad, GstPad * sinkpad)
1307   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1308   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1310   GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinking %s:%s(%p) and %s:%s(%p)",
1311       GST_DEBUG_PAD_NAME (srcpad), srcpad,
1312       GST_DEBUG_PAD_NAME (sinkpad), sinkpad);
1314   GST_LOCK (srcpad);
1316   if (G_UNLIKELY (GST_PAD_DIRECTION (srcpad) != GST_PAD_SRC))
1317     goto not_srcpad;
1319   GST_LOCK (sinkpad);
1321   if (G_UNLIKELY (GST_PAD_DIRECTION (sinkpad) != GST_PAD_SINK))
1322     goto not_sinkpad;
1324   if (G_UNLIKELY (GST_PAD_PEER (srcpad) != sinkpad))
1325     goto not_linked_together;
1327   if (GST_PAD_UNLINKFUNC (srcpad)) {
1328     GST_PAD_UNLINKFUNC (srcpad) (srcpad);
1329   }
1330   if (GST_PAD_UNLINKFUNC (sinkpad)) {
1331     GST_PAD_UNLINKFUNC (sinkpad) (sinkpad);
1332   }
1334   /* first clear peers */
1335   GST_PAD_PEER (srcpad) = NULL;
1336   GST_PAD_PEER (sinkpad) = NULL;
1338   GST_UNLOCK (sinkpad);
1339   GST_UNLOCK (srcpad);
1341   /* fire off a signal to each of the pads telling them 
1342    * that they've been unlinked */
1343   g_signal_emit (G_OBJECT (srcpad), gst_pad_signals[PAD_UNLINKED], 0, sinkpad);
1344   g_signal_emit (G_OBJECT (sinkpad), gst_pad_signals[PAD_UNLINKED], 0, srcpad);
1346   GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinked %s:%s and %s:%s",
1347       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1349   return TRUE;
1351 not_srcpad:
1352   {
1353     g_critical ("pad %s is not a source pad", GST_PAD_NAME (srcpad));
1354     GST_UNLOCK (srcpad);
1355     return FALSE;
1356   }
1357 not_sinkpad:
1358   {
1359     g_critical ("pad %s is not a sink pad", GST_PAD_NAME (sinkpad));
1360     GST_UNLOCK (sinkpad);
1361     GST_UNLOCK (srcpad);
1362     return FALSE;
1363   }
1364 not_linked_together:
1365   {
1366     /* we do not emit a warning in this case because unlinking cannot
1367      * be made MT safe.*/
1368     GST_UNLOCK (sinkpad);
1369     GST_UNLOCK (srcpad);
1370     return FALSE;
1371   }
1374 /**
1375  * gst_pad_is_linked:
1376  * @pad: pad to check
1377  *
1378  * Checks if a @pad is linked to another pad or not.
1379  *
1380  * Returns: TRUE if the pad is linked, FALSE otherwise.
1381  *
1382  * MT safe.
1383  */
1384 gboolean
1385 gst_pad_is_linked (GstPad * pad)
1387   gboolean result;
1389   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1391   GST_LOCK (pad);
1392   result = (GST_PAD_PEER (pad) != NULL);
1393   GST_UNLOCK (pad);
1395   return result;
1398 /* get the caps from both pads and see if the intersection
1399  * is not empty.
1400  *
1401  * This function should be called with the pad LOCK on both
1402  * pads
1403  */
1404 static gboolean
1405 gst_pad_link_check_compatible_unlocked (GstPad * src, GstPad * sink)
1407   GstCaps *srccaps;
1408   GstCaps *sinkcaps;
1410   srccaps = gst_pad_get_caps_unlocked (src);
1411   sinkcaps = gst_pad_get_caps_unlocked (sink);
1412   GST_CAT_DEBUG (GST_CAT_CAPS, " src caps %" GST_PTR_FORMAT, srccaps);
1413   GST_CAT_DEBUG (GST_CAT_CAPS, "sink caps %" GST_PTR_FORMAT, sinkcaps);
1415   /* if we have caps on both pads we can check the intersection */
1416   if (srccaps && sinkcaps) {
1417     GstCaps *icaps;
1419     icaps = gst_caps_intersect (srccaps, sinkcaps);
1420     gst_caps_unref (srccaps);
1421     gst_caps_unref (sinkcaps);
1423     GST_CAT_DEBUG (GST_CAT_CAPS,
1424         "intersection caps %p %" GST_PTR_FORMAT, icaps, icaps);
1426     if (!icaps || gst_caps_is_empty (icaps)) {
1427       GST_CAT_DEBUG (GST_CAT_CAPS, "intersection is empty");
1428       gst_caps_unref (icaps);
1429       return FALSE;
1430     }
1431     gst_caps_unref (icaps);
1432   }
1434   return TRUE;
1437 /* check if the grandparents of both pads are the same.
1438  * This check is required so that we don't try to link
1439  * pads from elements in different bins without ghostpads.
1440  *
1441  * The LOCK should be helt on both pads
1442  */
1443 static gboolean
1444 gst_pad_link_check_hierarchy (GstPad * src, GstPad * sink)
1446   GstObject *psrc, *psink;
1447   gboolean res = TRUE;
1449   psrc = GST_OBJECT_PARENT (src);
1450   psink = GST_OBJECT_PARENT (sink);
1452   /* if one of the pads has no parent, we allow the link */
1453   if (psrc && psink) {
1454     /* if the parents are the same, we have a loop */
1455     if (psrc == psink) {
1456       GST_CAT_DEBUG (GST_CAT_CAPS, "pads have same parent %" GST_PTR_FORMAT,
1457           psrc);
1458       res = FALSE;
1459       goto done;
1460     }
1461     /* if they both have a parent, we check the grandparents */
1462     psrc = gst_object_get_parent (psrc);
1463     psink = gst_object_get_parent (psink);
1465     if (psrc != psink) {
1466       /* if they have grandparents but they are not the same */
1467       GST_CAT_DEBUG (GST_CAT_CAPS,
1468           "pads have different grandparents %" GST_PTR_FORMAT " and %"
1469           GST_PTR_FORMAT, psrc, psink);
1470       res = FALSE;
1471     }
1472     if (psrc)
1473       gst_object_unref (psrc);
1474     if (psink)
1475       gst_object_unref (psink);
1476   }
1477 done:
1478   return res;
1481 /* FIXME leftover from an attempt at refactoring... */
1482 /* call with the two pads unlocked */
1483 static GstPadLinkReturn
1484 gst_pad_link_prepare (GstPad * srcpad, GstPad * sinkpad)
1486   /* generic checks */
1487   g_return_val_if_fail (GST_IS_PAD (srcpad), GST_PAD_LINK_REFUSED);
1488   g_return_val_if_fail (GST_IS_PAD (sinkpad), GST_PAD_LINK_REFUSED);
1490   GST_CAT_INFO (GST_CAT_PADS, "trying to link %s:%s and %s:%s",
1491       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1493   GST_LOCK (srcpad);
1495   if (G_UNLIKELY (GST_PAD_DIRECTION (srcpad) != GST_PAD_SRC))
1496     goto not_srcpad;
1498   if (G_UNLIKELY (GST_PAD_PEER (srcpad) != NULL))
1499     goto src_was_linked;
1501   GST_LOCK (sinkpad);
1503   if (G_UNLIKELY (GST_PAD_DIRECTION (sinkpad) != GST_PAD_SINK))
1504     goto not_sinkpad;
1506   if (G_UNLIKELY (GST_PAD_PEER (sinkpad) != NULL))
1507     goto sink_was_linked;
1509   /* check hierarchy, pads can only be linked if the grandparents
1510    * are the same. */
1511   if (!gst_pad_link_check_hierarchy (srcpad, sinkpad))
1512     goto wrong_hierarchy;
1514   /* check pad caps for non-empty intersection */
1515   if (!gst_pad_link_check_compatible_unlocked (srcpad, sinkpad))
1516     goto no_format;
1518   /* FIXME check pad scheduling for non-empty intersection */
1520   return GST_PAD_LINK_OK;
1522 not_srcpad:
1523   {
1524     g_critical ("pad %s is not a source pad", GST_PAD_NAME (srcpad));
1525     GST_UNLOCK (srcpad);
1526     return GST_PAD_LINK_WRONG_DIRECTION;
1527   }
1528 src_was_linked:
1529   {
1530     GST_CAT_INFO (GST_CAT_PADS, "src %s:%s was linked",
1531         GST_DEBUG_PAD_NAME (srcpad));
1532     /* we do not emit a warning in this case because unlinking cannot
1533      * be made MT safe.*/
1534     GST_UNLOCK (srcpad);
1535     return GST_PAD_LINK_WAS_LINKED;
1536   }
1537 not_sinkpad:
1538   {
1539     g_critical ("pad %s is not a sink pad", GST_PAD_NAME (sinkpad));
1540     GST_UNLOCK (sinkpad);
1541     GST_UNLOCK (srcpad);
1542     return GST_PAD_LINK_WRONG_DIRECTION;
1543   }
1544 sink_was_linked:
1545   {
1546     GST_CAT_INFO (GST_CAT_PADS, "sink %s:%s was linked",
1547         GST_DEBUG_PAD_NAME (sinkpad));
1548     /* we do not emit a warning in this case because unlinking cannot
1549      * be made MT safe.*/
1550     GST_UNLOCK (sinkpad);
1551     GST_UNLOCK (srcpad);
1552     return GST_PAD_LINK_WAS_LINKED;
1553   }
1554 wrong_hierarchy:
1555   {
1556     GST_CAT_INFO (GST_CAT_PADS, "pads have wrong hierarchy");
1557     GST_UNLOCK (sinkpad);
1558     GST_UNLOCK (srcpad);
1559     return GST_PAD_LINK_WRONG_HIERARCHY;
1560   }
1561 no_format:
1562   {
1563     GST_CAT_INFO (GST_CAT_PADS, "caps are incompatible");
1564     GST_UNLOCK (sinkpad);
1565     GST_UNLOCK (srcpad);
1566     return GST_PAD_LINK_NOFORMAT;
1567   }
1570 /**
1571  * gst_pad_link:
1572  * @srcpad: the source #GstPad to link.
1573  * @sinkpad: the sink #GstPad to link.
1574  *
1575  * Links the source pad and the sink pad.
1576  *
1577  * Returns: A result code indicating if the connection worked or
1578  *          what went wrong.
1579  *
1580  * MT Safe.
1581  */
1582 GstPadLinkReturn
1583 gst_pad_link (GstPad * srcpad, GstPad * sinkpad)
1585   GstPadLinkReturn result;
1587   /* prepare will also lock the two pads */
1588   result = gst_pad_link_prepare (srcpad, sinkpad);
1590   if (result != GST_PAD_LINK_OK)
1591     goto prepare_failed;
1593   GST_UNLOCK (sinkpad);
1594   GST_UNLOCK (srcpad);
1596   /* FIXME released the locks here, concurrent thread might link
1597    * something else. */
1598   if (GST_PAD_LINKFUNC (srcpad)) {
1599     /* this one will call the peer link function */
1600     result = GST_PAD_LINKFUNC (srcpad) (srcpad, sinkpad);
1601   } else if (GST_PAD_LINKFUNC (sinkpad)) {
1602     /* if no source link function, we need to call the sink link
1603      * function ourselves. */
1604     result = GST_PAD_LINKFUNC (sinkpad) (sinkpad, srcpad);
1605   } else {
1606     result = GST_PAD_LINK_OK;
1607   }
1609   GST_LOCK (srcpad);
1610   GST_LOCK (sinkpad);
1612   if (result == GST_PAD_LINK_OK) {
1613     GST_PAD_PEER (srcpad) = sinkpad;
1614     GST_PAD_PEER (sinkpad) = srcpad;
1616     GST_UNLOCK (sinkpad);
1617     GST_UNLOCK (srcpad);
1619     /* fire off a signal to each of the pads telling them
1620      * that they've been linked */
1621     g_signal_emit (G_OBJECT (srcpad), gst_pad_signals[PAD_LINKED], 0, sinkpad);
1622     g_signal_emit (G_OBJECT (sinkpad), gst_pad_signals[PAD_LINKED], 0, srcpad);
1624     GST_CAT_INFO (GST_CAT_PADS, "linked %s:%s and %s:%s, successful",
1625         GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1626   } else {
1627     GST_CAT_INFO (GST_CAT_PADS, "link between %s:%s and %s:%s failed",
1628         GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1630     GST_UNLOCK (sinkpad);
1631     GST_UNLOCK (srcpad);
1632   }
1633   return result;
1635 prepare_failed:
1636   {
1637     return result;
1638   }
1641 static void
1642 gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ)
1644   /* this function would need checks if it weren't static */
1646   GST_LOCK (pad);
1647   gst_object_replace ((GstObject **) & pad->padtemplate, (GstObject *) templ);
1648   GST_UNLOCK (pad);
1650   if (templ)
1651     gst_pad_template_pad_created (templ, pad);
1654 /**
1655  * gst_pad_get_pad_template:
1656  * @pad: a #GstPad.
1657  *
1658  * Gets the template for @pad.
1659  *
1660  * Returns: the #GstPadTemplate from which this pad was instantiated, or %NULL
1661  * if this pad has no template.
1662  *
1663  * FIXME: currently returns an unrefcounted padtemplate.
1664  */
1665 GstPadTemplate *
1666 gst_pad_get_pad_template (GstPad * pad)
1668   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1670   return GST_PAD_PAD_TEMPLATE (pad);
1674 /* should be called with the pad LOCK held */
1675 /* refs the caps, so caller is responsible for getting it unreffed */
1676 static GstCaps *
1677 gst_pad_get_caps_unlocked (GstPad * pad)
1679   GstCaps *result = NULL;
1681   GST_CAT_DEBUG (GST_CAT_CAPS, "get pad caps of %s:%s (%p)",
1682       GST_DEBUG_PAD_NAME (pad), pad);
1684   if (GST_PAD_GETCAPSFUNC (pad)) {
1685     GST_CAT_DEBUG (GST_CAT_CAPS, "dispatching to pad getcaps function");
1687     GST_FLAG_SET (pad, GST_PAD_IN_GETCAPS);
1688     GST_UNLOCK (pad);
1689     result = GST_PAD_GETCAPSFUNC (pad) (pad);
1690     GST_LOCK (pad);
1691     GST_FLAG_UNSET (pad, GST_PAD_IN_GETCAPS);
1693     if (result == NULL) {
1694       g_critical ("pad %s:%s returned NULL caps from getcaps function",
1695           GST_DEBUG_PAD_NAME (pad));
1696     } else {
1697       GST_CAT_DEBUG (GST_CAT_CAPS,
1698           "pad getcaps %s:%s returned %" GST_PTR_FORMAT,
1699           GST_DEBUG_PAD_NAME (pad), result);
1700 #ifndef G_DISABLE_ASSERT
1701       /* check that the returned caps are a real subset of the template caps */
1702       if (GST_PAD_PAD_TEMPLATE (pad)) {
1703         const GstCaps *templ_caps =
1704             GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
1705         if (!gst_caps_is_subset (result, templ_caps)) {
1706           GstCaps *temp;
1708           GST_CAT_ERROR_OBJECT (GST_CAT_CAPS, pad,
1709               "pad returned caps %" GST_PTR_FORMAT
1710               " which are not a real subset of its template caps %"
1711               GST_PTR_FORMAT, result, templ_caps);
1712           g_warning
1713               ("pad %s:%s returned caps that are not a real subset of its template caps",
1714               GST_DEBUG_PAD_NAME (pad));
1715           temp = gst_caps_intersect (templ_caps, result);
1716           gst_caps_unref (result);
1717           result = temp;
1718         }
1719       }
1720 #endif
1721       goto done;
1722     }
1723   }
1724   if (GST_PAD_PAD_TEMPLATE (pad)) {
1725     GstPadTemplate *templ = GST_PAD_PAD_TEMPLATE (pad);
1727     result = GST_PAD_TEMPLATE_CAPS (templ);
1728     GST_CAT_DEBUG (GST_CAT_CAPS,
1729         "using pad template %p with caps %p %" GST_PTR_FORMAT, templ, result,
1730         result);
1732     result = gst_caps_ref (result);
1733     goto done;
1734   }
1735   if (GST_PAD_CAPS (pad)) {
1736     result = GST_PAD_CAPS (pad);
1738     GST_CAT_DEBUG (GST_CAT_CAPS,
1739         "using pad caps %p %" GST_PTR_FORMAT, result, result);
1741     result = gst_caps_ref (result);
1742     goto done;
1743   }
1745   GST_CAT_DEBUG (GST_CAT_CAPS, "pad has no caps");
1746   result = gst_caps_new_empty ();
1748 done:
1749   return result;
1752 /**
1753  * gst_pad_get_caps:
1754  * @pad: a  #GstPad to get the capabilities of.
1755  *
1756  * Gets the capabilities this pad can produce or consume.
1757  * Note that this method doesn't necessarily returns the caps set by
1758  * #gst_pad_set_caps - use #GST_PAD_CAPS for that instead.
1759  * gst_pad_get_caps returns all possible caps a pad can operate with, using
1760  * the pad's get_caps function;
1761  * this returns the pad template caps if not explicitly set.
1762  *
1763  * Returns: a newly allocated copy of the #GstCaps of this pad.
1764  *
1765  * MT safe.
1766  */
1767 GstCaps *
1768 gst_pad_get_caps (GstPad * pad)
1770   GstCaps *result = NULL;
1772   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1774   GST_LOCK (pad);
1776   GST_CAT_DEBUG (GST_CAT_CAPS, "get pad caps of %s:%s (%p)",
1777       GST_DEBUG_PAD_NAME (pad), pad);
1779   if (G_UNLIKELY (GST_PAD_IS_IN_GETCAPS (pad)))
1780     goto was_dispatching;
1782   result = gst_pad_get_caps_unlocked (pad);
1783   GST_UNLOCK (pad);
1785   return result;
1787 was_dispatching:
1788   {
1789     GST_CAT_DEBUG (GST_CAT_CAPS,
1790         "pad %s:%s is already dispatching!", GST_DEBUG_PAD_NAME (pad));
1791     g_warning ("pad %s:%s recursively called getcaps!",
1792         GST_DEBUG_PAD_NAME (pad));
1793     GST_UNLOCK (pad);
1794     return NULL;
1795   }
1798 /**
1799  * gst_pad_peer_get_caps:
1800  * @pad: a  #GstPad to get the peer capabilities of.
1801  *
1802  * Gets the capabilities of the peer connected to this pad.
1803  *
1804  * Returns: the #GstCaps of the peer pad. This function returns a new caps, so use 
1805  * gst_caps_unref to get rid of it. this function returns NULL if there is no
1806  * peer pad or when this function is called recursively from a getcaps function.
1807  */
1808 GstCaps *
1809 gst_pad_peer_get_caps (GstPad * pad)
1811   GstPad *peerpad;
1812   GstCaps *result = NULL;
1814   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1816   GST_LOCK (pad);
1818   GST_CAT_DEBUG (GST_CAT_CAPS, "get peer caps of %s:%s (%p)",
1819       GST_DEBUG_PAD_NAME (pad), pad);
1821   peerpad = GST_PAD_PEER (pad);
1822   if (G_UNLIKELY (peerpad == NULL))
1823     goto no_peer;
1825   if (G_UNLIKELY (GST_PAD_IS_IN_GETCAPS (peerpad)))
1826     goto was_dispatching;
1828   gst_object_ref (peerpad);
1829   GST_UNLOCK (pad);
1831   result = gst_pad_get_caps (peerpad);
1833   gst_object_unref (peerpad);
1835   return result;
1837 no_peer:
1838   {
1839     GST_UNLOCK (pad);
1840     return NULL;
1841   }
1842 was_dispatching:
1843   {
1844     GST_CAT_DEBUG (GST_CAT_CAPS,
1845         "pad %s:%s is already dispatching!", GST_DEBUG_PAD_NAME (pad));
1846     g_warning ("pad %s:%s recursively called getcaps!",
1847         GST_DEBUG_PAD_NAME (pad));
1848     GST_UNLOCK (pad);
1849     return NULL;
1850   }
1853 static gboolean
1854 fixate_value (GValue * dest, const GValue * src)
1856   if (G_VALUE_TYPE (src) == GST_TYPE_INT_RANGE) {
1857     g_value_init (dest, G_TYPE_INT);
1858     g_value_set_int (dest, gst_value_get_int_range_min (src));
1859   } else if (G_VALUE_TYPE (src) == GST_TYPE_DOUBLE_RANGE) {
1860     g_value_init (dest, G_TYPE_DOUBLE);
1861     g_value_set_double (dest, gst_value_get_double_range_min (src));
1862   } else if (G_VALUE_TYPE (src) == GST_TYPE_LIST) {
1863     GValue temp = { 0 };
1865     gst_value_init_and_copy (&temp, gst_value_list_get_value (src, 0));
1866     if (!fixate_value (dest, &temp))
1867       gst_value_init_and_copy (dest, &temp);
1868     g_value_unset (&temp);
1869   } else if (G_VALUE_TYPE (src) == GST_TYPE_ARRAY) {
1870     gboolean res = FALSE;
1871     gint n;
1873     g_value_init (dest, GST_TYPE_ARRAY);
1874     for (n = 0; n < gst_value_list_get_size (src); n++) {
1875       GValue kid = { 0 };
1876       const GValue *orig_kid = gst_value_list_get_value (src, n);
1878       if (!fixate_value (&kid, orig_kid))
1879         gst_value_init_and_copy (&kid, orig_kid);
1880       else
1881         res = TRUE;
1882       gst_value_list_append_value (dest, &kid);
1883       g_value_unset (&kid);
1884     }
1886     if (!res)
1887       g_value_unset (dest);
1889     return res;
1890   } else {
1891     return FALSE;
1892   }
1894   return TRUE;
1897 static gboolean
1898 gst_pad_default_fixate (GQuark field_id, const GValue * value, gpointer data)
1900   GstStructure *s = data;
1901   GValue v = { 0 };
1903   if (fixate_value (&v, value)) {
1904     gst_structure_id_set_value (s, field_id, &v);
1905     g_value_unset (&v);
1906   }
1908   return TRUE;
1911 /**
1912  * gst_pad_fixate_caps:
1913  * @pad: a  #GstPad to fixate
1914  * @caps: the  #GstCaps to fixate
1915  *
1916  * Fixate a caps on the given pad. Modifies the caps in place, so you should
1917  * make sure that the caps are actually writable (see gst_caps_make_writable()).
1918  */
1919 void
1920 gst_pad_fixate_caps (GstPad * pad, GstCaps * caps)
1922   GstPadFixateCapsFunction fixatefunc;
1923   gint n;
1925   g_return_if_fail (GST_IS_PAD (pad));
1926   g_return_if_fail (caps != NULL);
1928   if (gst_caps_is_fixed (caps))
1929     return;
1931   fixatefunc = GST_PAD_FIXATECAPSFUNC (pad);
1932   if (fixatefunc) {
1933     fixatefunc (pad, caps);
1934   }
1936   /* default fixation */
1937   for (n = 0; n < gst_caps_get_size (caps); n++) {
1938     GstStructure *s = gst_caps_get_structure (caps, n);
1940     gst_structure_foreach (s, gst_pad_default_fixate, s);
1941   }
1944 /**
1945  * gst_pad_accept_caps:
1946  * @pad: a #GstPad to check
1947  * @caps: a #GstCaps to check on the pad
1948  *
1949  * Check if the given pad accepts the caps.
1950  *
1951  * Returns: TRUE if the pad can accept the caps.
1952  */
1953 gboolean
1954 gst_pad_accept_caps (GstPad * pad, GstCaps * caps)
1956   gboolean result;
1957   GstPadAcceptCapsFunction acceptfunc;
1959   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1961   /* any pad can be unnegotiated */
1962   if (caps == NULL)
1963     return TRUE;
1965   GST_LOCK (pad);
1966   acceptfunc = GST_PAD_ACCEPTCAPSFUNC (pad);
1968   GST_CAT_DEBUG (GST_CAT_CAPS, "pad accept caps of %s:%s (%p)",
1969       GST_DEBUG_PAD_NAME (pad), pad);
1970   GST_UNLOCK (pad);
1972   if (acceptfunc) {
1973     /* we can call the function */
1974     result = acceptfunc (pad, caps);
1975   } else {
1976     /* else see get the caps and see if it intersects to something
1977      * not empty */
1978     GstCaps *intersect;
1979     GstCaps *allowed;
1981     allowed = gst_pad_get_caps (pad);
1982     if (allowed) {
1983       intersect = gst_caps_intersect (allowed, caps);
1985       result = !gst_caps_is_empty (intersect);
1987       gst_caps_unref (allowed);
1988       gst_caps_unref (intersect);
1989     } else {
1990       result = FALSE;
1991     }
1992   }
1993   return result;
1996 /**
1997  * gst_pad_peer_accept_caps:
1998  * @pad: a  #GstPad to check
1999  * @caps: a #GstCaps to check on the pad
2000  *
2001  * Check if the given pad accepts the caps.
2002  *
2003  * Returns: TRUE if the pad can accept the caps.
2004  */
2005 gboolean
2006 gst_pad_peer_accept_caps (GstPad * pad, GstCaps * caps)
2008   GstPad *peerpad;
2009   gboolean result;
2011   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2013   GST_LOCK (pad);
2015   GST_CAT_DEBUG (GST_CAT_CAPS, "peer accept caps of %s:%s (%p)",
2016       GST_DEBUG_PAD_NAME (pad), pad);
2018   peerpad = GST_PAD_PEER (pad);
2019   if (G_UNLIKELY (peerpad == NULL))
2020     goto no_peer;
2022   result = gst_pad_accept_caps (peerpad, caps);
2023   GST_UNLOCK (pad);
2025   return result;
2027 no_peer:
2028   {
2029     GST_UNLOCK (pad);
2030     return TRUE;
2031   }
2034 /**
2035  * gst_pad_set_caps:
2036  * @pad: a  #GstPad to set the capabilities of.
2037  * @caps: a #GstCaps to set.
2038  *
2039  * Sets the capabilities of this pad. The caps must be fixed. Any previous
2040  * caps on the pad will be unreffed. This function refs the caps so you should
2041  * unref if as soon as you don't need it anymore.
2042  * It is possible to set NULL caps, which will make the pad unnegotiated
2043  * again.
2044  *
2045  * Returns: TRUE if the caps could be set. FALSE if the caps were not fixed
2046  * or bad parameters were provided to this function.
2047  *
2048  * MT safe.
2049  */
2050 gboolean
2051 gst_pad_set_caps (GstPad * pad, GstCaps * caps)
2053   GstPadSetCapsFunction setcaps;
2054   GstCaps *existing;
2056   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2057   g_return_val_if_fail (caps == NULL || gst_caps_is_fixed (caps), FALSE);
2059   GST_LOCK (pad);
2060   setcaps = GST_PAD_SETCAPSFUNC (pad);
2062   existing = GST_PAD_CAPS (pad);
2063   if (caps == existing)
2064     goto setting_same_caps;
2065   else if (caps && existing && gst_caps_is_equal (caps, existing))
2066     goto setting_same_caps;
2068   /* call setcaps function to configure the pad */
2069   if (setcaps != NULL && caps) {
2070     if (!GST_PAD_IS_IN_SETCAPS (pad)) {
2071       GST_FLAG_SET (pad, GST_PAD_IN_SETCAPS);
2072       GST_UNLOCK (pad);
2073       if (!setcaps (pad, caps))
2074         goto could_not_set;
2075       GST_LOCK (pad);
2076       GST_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2077     } else {
2078       GST_CAT_DEBUG (GST_CAT_CAPS, "pad %s:%s was dispatching",
2079           GST_DEBUG_PAD_NAME (pad));
2080     }
2081   }
2083   gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2084   GST_CAT_DEBUG (GST_CAT_CAPS, "%s:%s caps %" GST_PTR_FORMAT,
2085       GST_DEBUG_PAD_NAME (pad), caps);
2086   GST_UNLOCK (pad);
2088   g_object_notify (G_OBJECT (pad), "caps");
2090   return TRUE;
2092 setting_same_caps:
2093   {
2094     GST_UNLOCK (pad);
2095     gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2096     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2097         "caps %" GST_PTR_FORMAT " same as existing, updating ptr only", caps);
2098     return TRUE;
2099   }
2100 /* errors */
2101 could_not_set:
2102   {
2103     GST_LOCK (pad);
2104     GST_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2105     GST_CAT_DEBUG (GST_CAT_CAPS,
2106         "pad %s:%s, caps %" GST_PTR_FORMAT " could not be set",
2107         GST_DEBUG_PAD_NAME (pad), caps);
2108     GST_UNLOCK (pad);
2110     return FALSE;
2111   }
2114 static gboolean
2115 gst_pad_configure_sink (GstPad * pad, GstCaps * caps)
2117   GstPadAcceptCapsFunction acceptcaps;
2118   GstPadSetCapsFunction setcaps;
2119   gboolean res;
2121   acceptcaps = GST_PAD_ACCEPTCAPSFUNC (pad);
2122   setcaps = GST_PAD_SETCAPSFUNC (pad);
2124   /* See if pad accepts the caps, by calling acceptcaps, only
2125    * needed if no setcaps function */
2126   if (setcaps == NULL && acceptcaps != NULL) {
2127     if (!acceptcaps (pad, caps))
2128       goto not_accepted;
2129   }
2130   /* set caps on pad if call succeeds */
2131   res = gst_pad_set_caps (pad, caps);
2132   /* no need to unref the caps here, set_caps takes a ref and
2133    * our ref goes away when we leave this function. */
2135   return res;
2137 not_accepted:
2138   {
2139     GST_CAT_DEBUG (GST_CAT_CAPS, "caps %" GST_PTR_FORMAT " not accepted", caps);
2140     return FALSE;
2141   }
2144 /* returns TRUE if the src pad could be configured to accept the given caps */
2145 static gboolean
2146 gst_pad_configure_src (GstPad * pad, GstCaps * caps)
2148   GstPadAcceptCapsFunction acceptcaps;
2149   GstPadSetCapsFunction setcaps;
2150   gboolean res;
2152   acceptcaps = GST_PAD_ACCEPTCAPSFUNC (pad);
2153   setcaps = GST_PAD_SETCAPSFUNC (pad);
2155   /* See if pad accepts the caps, by calling acceptcaps, only
2156    * needed if no setcaps function */
2157   if (setcaps == NULL && acceptcaps != NULL) {
2158     if (!acceptcaps (pad, caps))
2159       goto not_accepted;
2160   }
2161   /* set caps on pad if call succeeds */
2162   res = gst_pad_set_caps (pad, caps);
2163   /* no need to unref the caps here, set_caps takes a ref and
2164    * our ref goes away when we leave this function. */
2166   return res;
2168 not_accepted:
2169   {
2170     GST_CAT_DEBUG (GST_CAT_CAPS, "caps %" GST_PTR_FORMAT " not accepted", caps);
2171     return FALSE;
2172   }
2175 /**
2176  * gst_pad_get_pad_template_caps:
2177  * @pad: a #GstPad to get the template capabilities from.
2178  *
2179  * Gets the capabilities for @pad's template.
2180  *
2181  * Returns: the #GstCaps of this pad template. If you intend to keep a reference
2182  * on the caps, make a copy (see gst_caps_copy ()).
2183  */
2184 const GstCaps *
2185 gst_pad_get_pad_template_caps (GstPad * pad)
2187   static GstStaticCaps anycaps = GST_STATIC_CAPS ("ANY");
2189   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2191   if (GST_PAD_PAD_TEMPLATE (pad))
2192     return GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
2194   return gst_static_caps_get (&anycaps);
2198 /**
2199  * gst_pad_get_peer:
2200  * @pad: a #GstPad to get the peer of.
2201  *
2202  * Gets the peer of @pad. This function refs the peer pad so
2203  * you need to unref it after use.
2204  *
2205  * Returns: the peer #GstPad. Unref after usage.
2206  *
2207  * MT safe.
2208  */
2209 GstPad *
2210 gst_pad_get_peer (GstPad * pad)
2212   GstPad *result;
2214   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2216   GST_LOCK (pad);
2217   result = GST_PAD_PEER (pad);
2218   if (result)
2219     gst_object_ref (result);
2220   GST_UNLOCK (pad);
2222   return result;
2225 /**
2226  * gst_pad_get_allowed_caps:
2227  * @srcpad: a #GstPad, it must a a source pad.
2228  *
2229  * Gets the capabilities of the allowed media types that can flow through
2230  * @srcpad and its peer. The pad must be a source pad.
2231  * The caller must free the resulting caps.
2232  *
2233  * Returns: the allowed #GstCaps of the pad link.  Free the caps when
2234  * you no longer need it. This function returns NULL when the @srcpad has no
2235  * peer.
2236  *
2237  * MT safe.
2238  */
2239 GstCaps *
2240 gst_pad_get_allowed_caps (GstPad * srcpad)
2242   GstCaps *mycaps;
2243   GstCaps *caps;
2244   GstCaps *peercaps;
2245   GstPad *peer;
2247   g_return_val_if_fail (GST_IS_PAD (srcpad), NULL);
2248   g_return_val_if_fail (GST_PAD_IS_SRC (srcpad), NULL);
2250   GST_LOCK (srcpad);
2252   peer = GST_PAD_PEER (srcpad);
2253   if (G_UNLIKELY (peer == NULL))
2254     goto no_peer;
2256   GST_CAT_DEBUG (GST_CAT_PROPERTIES, "%s:%s: getting allowed caps",
2257       GST_DEBUG_PAD_NAME (srcpad));
2259   gst_object_ref (peer);
2260   GST_UNLOCK (srcpad);
2261   mycaps = gst_pad_get_caps (srcpad);
2263   peercaps = gst_pad_get_caps (peer);
2264   gst_object_unref (peer);
2266   caps = gst_caps_intersect (mycaps, peercaps);
2267   gst_caps_unref (peercaps);
2268   gst_caps_unref (mycaps);
2270   GST_CAT_DEBUG (GST_CAT_CAPS, "allowed caps %" GST_PTR_FORMAT, caps);
2272   return caps;
2274 no_peer:
2275   {
2276     GST_CAT_DEBUG (GST_CAT_PROPERTIES, "%s:%s: no peer",
2277         GST_DEBUG_PAD_NAME (srcpad));
2278     GST_UNLOCK (srcpad);
2280     return NULL;
2281   }
2284 /**
2285  * gst_pad_get_negotiated_caps:
2286  * @pad: a #GstPad.
2287  *
2288  * Gets the capabilities of the media type that currently flows through @pad
2289  * and its peer.
2290  *
2291  * This function can be used on both src and sinkpads. Note that srcpads are
2292  * always negotiated before sinkpads so it is possible that the negotiated caps
2293  * on the srcpad do not match the negotiated caps of the peer.
2294  *
2295  * Returns: the negotiated #GstCaps of the pad link.  Free the caps when
2296  * you no longer need it. This function returns NULL when the @pad has no
2297  * peer or is not negotiated yet.
2298  *
2299  * MT safe.
2300  */
2301 GstCaps *
2302 gst_pad_get_negotiated_caps (GstPad * pad)
2304   GstCaps *caps;
2305   GstPad *peer;
2307   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2309   GST_LOCK (pad);
2311   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2312     goto no_peer;
2314   GST_CAT_DEBUG (GST_CAT_PROPERTIES, "%s:%s: getting negotiated caps",
2315       GST_DEBUG_PAD_NAME (pad));
2317   caps = GST_PAD_CAPS (pad);
2318   if (caps)
2319     gst_caps_ref (caps);
2320   GST_UNLOCK (pad);
2322   GST_CAT_DEBUG (GST_CAT_CAPS, "negotiated caps %" GST_PTR_FORMAT, caps);
2324   return caps;
2326 no_peer:
2327   {
2328     GST_CAT_DEBUG (GST_CAT_PROPERTIES, "%s:%s: no peer",
2329         GST_DEBUG_PAD_NAME (pad));
2330     GST_UNLOCK (pad);
2332     return NULL;
2333   }
2336 /**
2337  * gst_pad_alloc_buffer:
2338  * @pad: a source #GstPad
2339  * @offset: the offset of the new buffer in the stream
2340  * @size: the size of the new buffer
2341  * @caps: the caps of the new buffer
2342  * @buf: a newly allocated buffer
2343  *
2344  * Allocates a new, empty buffer optimized to push to pad @pad.  This
2345  * function only works if @pad is a source pad and has a peer.
2346  *
2347  * You need to check the caps of the buffer after performing this
2348  * function and renegotiate to the format if needed.
2349  *
2350  * A new, empty #GstBuffer will be put in the @buf argument.
2351  *
2352  * Returns: a result code indicating success of the operation. Any
2353  * result code other than GST_FLOW_OK is an error and @buf should
2354  * not be used.
2355  * An error can occur if the pad is not connected or when the downstream
2356  * peer elements cannot provide an acceptable buffer.
2357  *
2358  * MT safe.
2359  */
2360 GstFlowReturn
2361 gst_pad_alloc_buffer (GstPad * pad, guint64 offset, gint size, GstCaps * caps,
2362     GstBuffer ** buf)
2364   GstPad *peer;
2365   GstFlowReturn ret;
2366   GstPadBufferAllocFunction bufferallocfunc;
2367   gboolean caps_changed;
2369   GST_DEBUG_OBJECT (pad, "offset %" G_GUINT64_FORMAT, offset);
2371   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
2372   g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
2373   g_return_val_if_fail (buf != NULL, GST_FLOW_ERROR);
2375   GST_LOCK (pad);
2376   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2377     goto no_peer;
2379   gst_object_ref (peer);
2380   GST_UNLOCK (pad);
2382   if (G_LIKELY ((bufferallocfunc = peer->bufferallocfunc) == NULL))
2383     goto fallback;
2385   GST_LOCK (peer);
2386   /* when the peer is flushing we cannot give a buffer */
2387   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (peer)))
2388     goto flushing;
2390   GST_CAT_DEBUG (GST_CAT_PADS,
2391       "calling bufferallocfunc &%s (@%p) of peer pad %s:%s for size %d ...",
2392       GST_DEBUG_FUNCPTR_NAME (bufferallocfunc),
2393       &bufferallocfunc, GST_DEBUG_PAD_NAME (peer), size);
2394   if (offset == GST_BUFFER_OFFSET_NONE)
2395     GST_CAT_DEBUG (GST_CAT_PADS, "... and offset NONE");
2396   else
2397     GST_CAT_DEBUG (GST_CAT_PADS, "... and offset %" G_GUINT64_FORMAT, offset);
2398   GST_UNLOCK (peer);
2400   ret = bufferallocfunc (peer, offset, size, caps, buf);
2402   if (G_UNLIKELY (ret != GST_FLOW_OK))
2403     goto peer_error;
2404   if (G_UNLIKELY (*buf == NULL))
2405     goto fallback;
2407   /* If the buffer alloc function didn't set up the caps like it should,
2408    * do it for it */
2409   if (caps && (GST_BUFFER_CAPS (*buf) == NULL)) {
2410     GST_WARNING ("Buffer allocation function for pad % " GST_PTR_FORMAT
2411         " did not set up caps. Setting", peer);
2413     gst_buffer_set_caps (*buf, caps);
2414   }
2416 do_caps:
2417   gst_object_unref (peer);
2419   /* FIXME, move capnego this into a base class? */
2420   caps = GST_BUFFER_CAPS (*buf);
2421   caps_changed = caps && caps != GST_PAD_CAPS (pad);
2422   /* we got a new datatype on the pad, see if it can handle it */
2423   if (G_UNLIKELY (caps_changed)) {
2424     GST_DEBUG ("caps changed to %" GST_PTR_FORMAT, caps);
2425     if (G_UNLIKELY (!gst_pad_configure_src (pad, caps)))
2426       goto not_negotiated;
2427   }
2428   return ret;
2430 no_peer:
2431   {
2432     /* pad has no peer */
2433     GST_CAT_DEBUG (GST_CAT_PADS,
2434         "%s:%s called bufferallocfunc but had no peer",
2435         GST_DEBUG_PAD_NAME (pad));
2436     GST_UNLOCK (pad);
2437     return GST_FLOW_NOT_LINKED;
2438   }
2439 flushing:
2440   {
2441     /* peer was flushing */
2442     GST_UNLOCK (peer);
2443     gst_object_unref (peer);
2444     GST_CAT_DEBUG (GST_CAT_PADS,
2445         "%s:%s called bufferallocfunc but peer was flushing",
2446         GST_DEBUG_PAD_NAME (pad));
2447     return GST_FLOW_WRONG_STATE;
2448   }
2449   /* fallback case, allocate a buffer of our own, add pad caps. */
2450 fallback:
2451   {
2452     GST_CAT_DEBUG (GST_CAT_PADS,
2453         "%s:%s fallback buffer alloc", GST_DEBUG_PAD_NAME (pad));
2454     *buf = gst_buffer_new_and_alloc (size);
2455     GST_BUFFER_OFFSET (*buf) = offset;
2456     gst_buffer_set_caps (*buf, caps);
2458     ret = GST_FLOW_OK;
2460     goto do_caps;
2461   }
2462 not_negotiated:
2463   {
2464     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2465         "alloc function retured unacceptable buffer");
2466     return GST_FLOW_NOT_NEGOTIATED;
2467   }
2468 peer_error:
2469   {
2470     gst_object_unref (peer);
2471     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2472         "alloc function retured error %d", ret);
2473     return ret;
2474   }
2477 /**
2478  * gst_pad_get_internal_links_default:
2479  * @pad: the #GstPad to get the internal links of.
2480  *
2481  * Gets a list of pads to which the given pad is linked to
2482  * inside of the parent element.
2483  * This is the default handler, and thus returns a list of all of the
2484  * pads inside the parent element with opposite direction.
2485  * The caller must free this list after use.
2486  *
2487  * Returns: a newly allocated #GList of pads, or NULL if the pad has no parent.
2488  *
2489  * Not MT safe.
2490  */
2491 GList *
2492 gst_pad_get_internal_links_default (GstPad * pad)
2494   GList *res = NULL;
2495   GstElement *parent;
2496   GList *parent_pads;
2497   GstPadDirection direction;
2499   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2501   direction = pad->direction;
2503   parent = GST_PAD_PARENT (pad);
2504   if (!parent)
2505     return NULL;
2507   parent_pads = parent->pads;
2509   while (parent_pads) {
2510     GstPad *parent_pad = GST_PAD_CAST (parent_pads->data);
2512     if (parent_pad->direction != direction) {
2513       res = g_list_prepend (res, parent_pad);
2514     }
2516     parent_pads = g_list_next (parent_pads);
2517   }
2519   return res;
2522 /**
2523  * gst_pad_get_internal_links:
2524  * @pad: the #GstPad to get the internal links of.
2525  *
2526  * Gets a list of pads to which the given pad is linked to
2527  * inside of the parent element.
2528  * The caller must free this list after use.
2529  *
2530  * Returns: a newly allocated #GList of pads.
2531  *
2532  * Not MT safe.
2533  */
2534 GList *
2535 gst_pad_get_internal_links (GstPad * pad)
2537   GList *res = NULL;
2539   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2541   if (GST_PAD_INTLINKFUNC (pad))
2542     res = GST_PAD_INTLINKFUNC (pad) (pad);
2544   return res;
2548 static gboolean
2549 gst_pad_event_default_dispatch (GstPad * pad, GstEvent * event)
2551   GList *orig, *pads;
2552   gboolean result;
2554   GST_INFO_OBJECT (pad, "Sending event %p to all internally linked pads",
2555       event);
2557   result = (GST_PAD_DIRECTION (pad) == GST_PAD_SINK);
2559   orig = pads = gst_pad_get_internal_links (pad);
2561   while (pads) {
2562     GstPad *eventpad = GST_PAD_CAST (pads->data);
2564     pads = g_list_next (pads);
2566     /* for all of the internally-linked pads that are actually linked */
2567     if (GST_PAD_IS_LINKED (eventpad)) {
2568       if (GST_PAD_DIRECTION (eventpad) == GST_PAD_SRC) {
2569         /* for each pad we send to, we should ref the event; it's up
2570          * to downstream to unref again when handled. */
2571         GST_LOG_OBJECT (pad, "Reffing and sending event %p to %s:%s", event,
2572             GST_DEBUG_PAD_NAME (eventpad));
2573         gst_event_ref (event);
2574         gst_pad_push_event (eventpad, event);
2575       } else {
2576         /* we only send the event on one pad, multi-sinkpad elements
2577          * should implement a handler */
2578         GST_LOG_OBJECT (pad, "sending event %p to one sink pad %s:%s", event,
2579             GST_DEBUG_PAD_NAME (eventpad));
2580         result = gst_pad_push_event (eventpad, event);
2581         goto done;
2582       }
2583     }
2584   }
2585   /* we handled the incoming event so we unref once */
2586   GST_LOG_OBJECT (pad, "handled event %p, unreffing", event);
2587   gst_event_unref (event);
2589 done:
2590   g_list_free (orig);
2592   return result;
2595 /**
2596  * gst_pad_event_default:
2597  * @pad: a #GstPad to call the default event handler on.
2598  * @event: the #GstEvent to handle.
2599  *
2600  * Invokes the default event handler for the given pad. End-of-stream and
2601  * discontinuity events are handled specially, and then the event is sent to all
2602  * pads internally linked to @pad. Note that if there are many possible sink
2603  * pads that are internally linked to @pad, only one will be sent an event.
2604  * Multi-sinkpad elements should implement custom event handlers.
2605  *
2606  * Returns: TRUE if the event was sent succesfully.
2607  */
2608 gboolean
2609 gst_pad_event_default (GstPad * pad, GstEvent * event)
2611   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2612   g_return_val_if_fail (event != NULL, FALSE);
2614   switch (GST_EVENT_TYPE (event)) {
2615     case GST_EVENT_EOS:
2616     {
2617       GST_DEBUG_OBJECT (pad, "pausing task because of eos");
2618       gst_pad_pause_task (pad);
2619     }
2620     default:
2621       break;
2622   }
2624   return gst_pad_event_default_dispatch (pad, event);
2627 /**
2628  * gst_pad_dispatcher:
2629  * @pad: a #GstPad to dispatch.
2630  * @dispatch: the #GstDispatcherFunction to call.
2631  * @data: gpointer user data passed to the dispatcher function.
2632  *
2633  * Invokes the given dispatcher function on all pads that are 
2634  * internally linked to the given pad. 
2635  * The GstPadDispatcherFunction should return TRUE when no further pads 
2636  * need to be processed.
2637  *
2638  * Returns: TRUE if one of the dispatcher functions returned TRUE.
2639  */
2640 gboolean
2641 gst_pad_dispatcher (GstPad * pad, GstPadDispatcherFunction dispatch,
2642     gpointer data)
2644   gboolean res = FALSE;
2645   GList *int_pads, *orig;
2647   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2648   g_return_val_if_fail (dispatch != NULL, FALSE);
2650   orig = int_pads = gst_pad_get_internal_links (pad);
2652   while (int_pads) {
2653     GstPad *int_pad = GST_PAD_CAST (int_pads->data);
2654     GstPad *int_peer = GST_PAD_PEER (int_pad);
2656     if (int_peer) {
2657       res = dispatch (int_peer, data);
2658       if (res)
2659         break;
2660     }
2661     int_pads = g_list_next (int_pads);
2662   }
2664   g_list_free (orig);
2666   return res;
2669 /**
2670  * gst_pad_query:
2671  * @pad: a #GstPad to invoke the default query on.
2672  * @query: the #GstQuery to perform.
2673  *
2674  * Dispatches a query to a pad. The query should have been allocated by the
2675  * caller via one of the type-specific allocation functions in gstquery.h. The
2676  * element is responsible for filling the query with an appropriate response,
2677  * which should then be parsed with a type-specific query parsing function.
2678  *
2679  * Again, the caller is responsible for both the allocation and deallocation of
2680  * the query structure.
2681  *
2682  * Returns: TRUE if the query could be performed.
2683  */
2684 gboolean
2685 gst_pad_query (GstPad * pad, GstQuery * query)
2687   GstPadQueryFunction func;
2689   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2690   g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
2692   GST_DEBUG ("sending query %p to pad %s:%s", query, GST_DEBUG_PAD_NAME (pad));
2694   if ((func = GST_PAD_QUERYFUNC (pad)) == NULL)
2695     goto no_func;
2697   return func (pad, query);
2699 no_func:
2700   {
2701     GST_DEBUG ("pad had no query function");
2702     return FALSE;
2703   }
2706 gboolean
2707 gst_pad_query_default (GstPad * pad, GstQuery * query)
2709   switch (GST_QUERY_TYPE (query)) {
2710     case GST_QUERY_POSITION:
2711     case GST_QUERY_SEEKING:
2712     case GST_QUERY_FORMATS:
2713     case GST_QUERY_LATENCY:
2714     case GST_QUERY_JITTER:
2715     case GST_QUERY_RATE:
2716     case GST_QUERY_CONVERT:
2717     default:
2718       return gst_pad_dispatcher
2719           (pad, (GstPadDispatcherFunction) gst_pad_query, query);
2720   }
2723 #ifndef GST_DISABLE_LOADSAVE
2724 /* FIXME: why isn't this on a GstElement ? */
2725 /**
2726  * gst_pad_load_and_link:
2727  * @self: an #xmlNodePtr to read the description from.
2728  * @parent: the #GstObject element that owns the pad.
2729  *
2730  * Reads the pad definition from the XML node and links the given pad
2731  * in the element to a pad of an element up in the hierarchy.
2732  */
2733 void
2734 gst_pad_load_and_link (xmlNodePtr self, GstObject * parent)
2736   xmlNodePtr field = self->xmlChildrenNode;
2737   GstPad *pad = NULL, *targetpad;
2738   gchar *peer = NULL;
2739   gchar **split;
2740   GstElement *target;
2741   GstObject *grandparent;
2742   gchar *name = NULL;
2744   while (field) {
2745     if (!strcmp ((char *) field->name, "name")) {
2746       name = (gchar *) xmlNodeGetContent (field);
2747       pad = gst_element_get_pad (GST_ELEMENT (parent), name);
2748       g_free (name);
2749     } else if (!strcmp ((char *) field->name, "peer")) {
2750       peer = (gchar *) xmlNodeGetContent (field);
2751     }
2752     field = field->next;
2753   }
2754   g_return_if_fail (pad != NULL);
2756   if (peer == NULL)
2757     return;
2759   split = g_strsplit (peer, ".", 2);
2761   if (split[0] == NULL || split[1] == NULL) {
2762     GST_CAT_DEBUG (GST_CAT_XML,
2763         "Could not parse peer '%s' for pad %s:%s, leaving unlinked",
2764         peer, GST_DEBUG_PAD_NAME (pad));
2766     g_free (peer);
2767     return;
2768   }
2769   g_free (peer);
2771   g_return_if_fail (split[0] != NULL);
2772   g_return_if_fail (split[1] != NULL);
2774   grandparent = gst_object_get_parent (parent);
2776   if (grandparent && GST_IS_BIN (grandparent)) {
2777     target = gst_bin_get_by_name_recurse_up (GST_BIN (grandparent), split[0]);
2778   } else
2779     goto cleanup;
2781   if (target == NULL)
2782     goto cleanup;
2784   targetpad = gst_element_get_pad (target, split[1]);
2786   if (targetpad == NULL)
2787     goto cleanup;
2789   gst_pad_link (pad, targetpad);
2791 cleanup:
2792   g_strfreev (split);
2795 /**
2796  * gst_pad_save_thyself:
2797  * @pad: a #GstPad to save.
2798  * @parent: the parent #xmlNodePtr to save the description in.
2799  *
2800  * Saves the pad into an xml representation.
2801  *
2802  * Returns: the #xmlNodePtr representation of the pad.
2803  */
2804 static xmlNodePtr
2805 gst_pad_save_thyself (GstObject * object, xmlNodePtr parent)
2807   GstPad *pad;
2808   GstPad *peer;
2810   g_return_val_if_fail (GST_IS_PAD (object), NULL);
2812   pad = GST_PAD (object);
2814   xmlNewChild (parent, NULL, (xmlChar *) "name",
2815       (xmlChar *) GST_PAD_NAME (pad));
2816   if (GST_PAD_PEER (pad) != NULL) {
2817     gchar *content;
2819     peer = GST_PAD_PEER (pad);
2820     /* first check to see if the peer's parent's parent is the same */
2821     /* we just save it off */
2822     content = g_strdup_printf ("%s.%s",
2823         GST_OBJECT_NAME (GST_PAD_PARENT (peer)), GST_PAD_NAME (peer));
2824     xmlNewChild (parent, NULL, (xmlChar *) "peer", (xmlChar *) content);
2825     g_free (content);
2826   } else
2827     xmlNewChild (parent, NULL, (xmlChar *) "peer", NULL);
2829   return parent;
2832 #if 0
2833 /**
2834  * gst_ghost_pad_save_thyself:
2835  * @pad: a ghost #GstPad to save.
2836  * @parent: the parent #xmlNodePtr to save the description in.
2837  *
2838  * Saves the ghost pad into an xml representation.
2839  *
2840  * Returns: the #xmlNodePtr representation of the pad.
2841  */
2842 xmlNodePtr
2843 gst_ghost_pad_save_thyself (GstPad * pad, xmlNodePtr parent)
2845   xmlNodePtr self;
2847   g_return_val_if_fail (GST_IS_GHOST_PAD (pad), NULL);
2849   self = xmlNewChild (parent, NULL, (xmlChar *) "ghostpad", NULL);
2850   xmlNewChild (self, NULL, (xmlChar *) "name", (xmlChar *) GST_PAD_NAME (pad));
2851   xmlNewChild (self, NULL, (xmlChar *) "parent",
2852       (xmlChar *) GST_OBJECT_NAME (GST_PAD_PARENT (pad)));
2854   /* FIXME FIXME FIXME! */
2856   return self;
2858 #endif /* 0 */
2859 #endif /* GST_DISABLE_LOADSAVE */
2861 /* 
2862  * should be called with pad lock held 
2863  *
2864  * MT safe.
2865  */
2866 static void
2867 handle_pad_block (GstPad * pad)
2869   GstPadBlockCallback callback;
2870   gpointer user_data;
2872   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2873       "signal block taken on pad %s:%s", GST_DEBUG_PAD_NAME (pad));
2875   /* need to grab extra ref for the callbacks */
2876   gst_object_ref (pad);
2878   callback = pad->block_callback;
2879   if (callback) {
2880     user_data = pad->block_data;
2881     GST_UNLOCK (pad);
2882     callback (pad, TRUE, user_data);
2883     GST_LOCK (pad);
2884   } else {
2885     GST_PAD_BLOCK_SIGNAL (pad);
2886   }
2888   while (GST_PAD_IS_BLOCKED (pad))
2889     GST_PAD_BLOCK_WAIT (pad);
2891   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "got unblocked");
2893   callback = pad->block_callback;
2894   if (callback) {
2895     user_data = pad->block_data;
2896     GST_UNLOCK (pad);
2897     callback (pad, FALSE, user_data);
2898     GST_LOCK (pad);
2899   } else {
2900     GST_PAD_BLOCK_SIGNAL (pad);
2901   }
2903   gst_object_unref (pad);
2906 /**********************************************************************
2907  * Data passing functions
2908  */
2910 static gboolean
2911 gst_pad_emit_have_data_signal (GstPad * pad, GstMiniObject * obj)
2913   GValue ret = { 0 };
2914   GValue args[2] = { {0}, {0} };
2915   gboolean res;
2916   GQuark detail;
2918   /* init */
2919   g_value_init (&ret, G_TYPE_BOOLEAN);
2920   g_value_set_boolean (&ret, TRUE);
2921   g_value_init (&args[0], GST_TYPE_PAD);
2922   g_value_set_object (&args[0], pad);
2923   g_value_init (&args[1], GST_TYPE_MINI_OBJECT);        // G_TYPE_POINTER);
2924   gst_value_set_mini_object (&args[1], obj);
2926   if (GST_IS_EVENT (obj))
2927     detail = event_quark;
2928   else
2929     detail = buffer_quark;
2931   /* actually emit */
2932   g_signal_emitv (args, gst_pad_signals[PAD_HAVE_DATA], detail, &ret);
2933   res = g_value_get_boolean (&ret);
2935   /* clean up */
2936   g_value_unset (&ret);
2937   g_value_unset (&args[0]);
2938   g_value_unset (&args[1]);
2940   return res;
2943 /**
2944  * gst_pad_chain:
2945  * @pad: a sink #GstPad.
2946  * @buffer: the #GstBuffer to send.
2947  *
2948  * Chain a buffer to @pad.
2949  *
2950  * Returns: a #GstFlowReturn from the pad.
2951  *
2952  * MT safe.
2953  */
2954 GstFlowReturn
2955 gst_pad_chain (GstPad * pad, GstBuffer * buffer)
2957   GstCaps *caps;
2958   gboolean caps_changed;
2959   GstPadChainFunction chainfunc;
2960   GstFlowReturn ret;
2961   gboolean emit_signal;
2963   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
2964   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK,
2965       GST_FLOW_ERROR);
2966   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
2967   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
2969   GST_STREAM_LOCK (pad);
2971   GST_LOCK (pad);
2972   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
2973     goto flushing;
2975   caps = GST_BUFFER_CAPS (buffer);
2976   caps_changed = caps && caps != GST_PAD_CAPS (pad);
2978   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
2979   GST_UNLOCK (pad);
2981   /* see if the signal should be emited, we emit before caps nego as
2982    * we might drop the buffer and do capsnego for nothing. */
2983   if (G_UNLIKELY (emit_signal)) {
2984     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (buffer)))
2985       goto dropping;
2986   }
2988   /* we got a new datatype on the pad, see if it can handle it */
2989   if (G_UNLIKELY (caps_changed)) {
2990     GST_DEBUG ("caps changed to %" GST_PTR_FORMAT, caps);
2991     if (G_UNLIKELY (!gst_pad_configure_sink (pad, caps)))
2992       goto not_negotiated;
2993   }
2995   /* NOTE: we read the chainfunc unlocked.
2996    * we cannot hold the lock for the pad so we might send
2997    * the data to the wrong function. This is not really a
2998    * problem since functions are assigned at creation time
2999    * and don't change that often... */
3000   if (G_UNLIKELY ((chainfunc = GST_PAD_CHAINFUNC (pad)) == NULL))
3001     goto no_function;
3003   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3004       "calling chainfunction &%s of pad %s:%s",
3005       GST_DEBUG_FUNCPTR_NAME (chainfunc), GST_DEBUG_PAD_NAME (pad));
3007   ret = chainfunc (pad, buffer);
3009   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3010       "called chainfunction &%s of pad %s:%s, returned %d",
3011       GST_DEBUG_FUNCPTR_NAME (chainfunc), GST_DEBUG_PAD_NAME (pad), ret);
3013   GST_STREAM_UNLOCK (pad);
3015   return ret;
3017   /* ERRORS */
3018 flushing:
3019   {
3020     gst_buffer_unref (buffer);
3021     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3022         "pushing, but pad was flushing");
3023     GST_UNLOCK (pad);
3024     GST_STREAM_UNLOCK (pad);
3025     return GST_FLOW_WRONG_STATE;
3026   }
3027 dropping:
3028   {
3029     gst_buffer_unref (buffer);
3030     GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
3031     GST_STREAM_UNLOCK (pad);
3032     return GST_FLOW_OK;
3033   }
3034 not_negotiated:
3035   {
3036     gst_buffer_unref (buffer);
3037     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3038         "pushing buffer but pad did not accept");
3039     GST_STREAM_UNLOCK (pad);
3040     return GST_FLOW_NOT_NEGOTIATED;
3041   }
3042 no_function:
3043   {
3044     gst_buffer_unref (buffer);
3045     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3046         "pushing, but not chainhandler");
3047     GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
3048         ("push on pad %s:%s but it has no chainfunction",
3049             GST_DEBUG_PAD_NAME (pad)));
3050     GST_STREAM_UNLOCK (pad);
3051     return GST_FLOW_ERROR;
3052   }
3055 /**
3056  * gst_pad_push:
3057  * @pad: a source #GstPad.
3058  * @buffer: the #GstBuffer to push.
3059  *
3060  * Pushes a buffer to the peer of @pad. @pad must be linked.
3061  *
3062  * Returns: a #GstFlowReturn from the peer pad.
3063  *
3064  * MT safe.
3065  */
3066 GstFlowReturn
3067 gst_pad_push (GstPad * pad, GstBuffer * buffer)
3069   GstPad *peer;
3070   GstFlowReturn ret;
3071   gboolean emit_signal;
3073   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3074   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC, GST_FLOW_ERROR);
3075   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
3076   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
3078   GST_LOCK (pad);
3079   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
3080     handle_pad_block (pad);
3082   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3083     goto not_linked;
3085   /* we emit signals on the pad areg, the peer will have a chance to
3086    * emit in the _chain() function */
3087   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3089   gst_object_ref (peer);
3090   GST_UNLOCK (pad);
3092   if (G_UNLIKELY (emit_signal)) {
3093     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (buffer)))
3094       goto dropping;
3095   }
3097   ret = gst_pad_chain (peer, buffer);
3099   gst_object_unref (peer);
3101   return ret;
3103   /* ERROR recovery here */
3104 not_linked:
3105   {
3106     gst_buffer_unref (buffer);
3107     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3108         "pushing, but it was not linked");
3109     GST_UNLOCK (pad);
3110     return GST_FLOW_NOT_LINKED;
3111   }
3112 dropping:
3113   {
3114     gst_buffer_unref (buffer);
3115     gst_object_unref (peer);
3116     GST_DEBUG ("Dropping buffer due to FALSE probe return");
3117     return GST_FLOW_OK;
3118   }
3121 /**
3122  * gst_pad_check_pull_range:
3123  * @pad: a sink #GstPad.
3124  *
3125  * Checks if a #gst_pad_pull_range() can be performed on the peer
3126  * source pad. This function is used by plugins that want to check
3127  * if they can use random access on the peer source pad. 
3128  *
3129  * The peer sourcepad can implement a custom #GstPadCheckGetRangeFunction
3130  * if it needs to perform some logic to determine if pull_range is
3131  * possible.
3132  *
3133  * Returns: a gboolean with the result.
3134  *
3135  * MT safe.
3136  */
3137 gboolean
3138 gst_pad_check_pull_range (GstPad * pad)
3140   GstPad *peer;
3141   gboolean ret;
3142   GstPadCheckGetRangeFunction checkgetrangefunc;
3144   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3146   GST_LOCK (pad);
3147   if (GST_PAD_DIRECTION (pad) != GST_PAD_SINK)
3148     goto wrong_direction;
3150   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3151     goto not_connected;
3153   gst_object_ref (peer);
3154   GST_UNLOCK (pad);
3156   /* see note in above function */
3157   if (G_LIKELY ((checkgetrangefunc = peer->checkgetrangefunc) == NULL)) {
3158     /* FIXME, kindoff ghetto */
3159     ret = GST_PAD_GETRANGEFUNC (peer) != NULL;
3160   } else {
3161     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3162         "calling checkgetrangefunc %s of peer pad %s:%s",
3163         GST_DEBUG_FUNCPTR_NAME (checkgetrangefunc), GST_DEBUG_PAD_NAME (peer));
3165     ret = checkgetrangefunc (peer);
3166   }
3168   gst_object_unref (peer);
3170   return ret;
3172   /* ERROR recovery here */
3173 wrong_direction:
3174   {
3175     GST_UNLOCK (pad);
3176     return FALSE;
3177   }
3178 not_connected:
3179   {
3180     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3181         "checking pull range, but it was not linked");
3182     GST_UNLOCK (pad);
3183     return FALSE;
3184   }
3187 /**
3188  * gst_pad_get_range:
3189  * @pad: a src #GstPad.
3190  * @offset: The start offset of the buffer
3191  * @size: The length of the buffer
3192  * @buffer: a pointer to hold the #GstBuffer.
3193  *
3194  * Calls the getrange function of @pad. 
3195  *
3196  * Returns: a #GstFlowReturn from the pad.
3197  *
3198  * MT safe.
3199  */
3200 GstFlowReturn
3201 gst_pad_get_range (GstPad * pad, guint64 offset, guint size,
3202     GstBuffer ** buffer)
3204   GstFlowReturn ret;
3205   GstPadGetRangeFunction getrangefunc;
3206   gboolean emit_signal;
3208   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3209   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC, GST_FLOW_ERROR);
3210   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
3212   GST_STREAM_LOCK (pad);
3214   GST_LOCK (pad);
3215   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
3216     goto flushing;
3218   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3219   GST_UNLOCK (pad);
3221   if (G_UNLIKELY ((getrangefunc = GST_PAD_GETRANGEFUNC (pad)) == NULL))
3222     goto no_function;
3224   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3225       "calling getrangefunc %s of peer pad %s:%s, offset %"
3226       G_GUINT64_FORMAT ", size %u",
3227       GST_DEBUG_FUNCPTR_NAME (getrangefunc), GST_DEBUG_PAD_NAME (pad),
3228       offset, size);
3230   ret = getrangefunc (pad, offset, size, buffer);
3232   /* can only fire the signal if we have a valid buffer */
3233   if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
3234     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
3235       goto dropping;
3236   }
3238   GST_STREAM_UNLOCK (pad);
3240   return ret;
3242   /* ERRORS */
3243 flushing:
3244   {
3245     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3246         "pulling range, but pad was flushing");
3247     GST_UNLOCK (pad);
3248     GST_STREAM_UNLOCK (pad);
3249     return GST_FLOW_WRONG_STATE;
3250   }
3251 no_function:
3252   {
3253     GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
3254         ("pullrange on pad %s:%s but it has no getrangefunction",
3255             GST_DEBUG_PAD_NAME (pad)));
3256     GST_STREAM_UNLOCK (pad);
3257     return GST_FLOW_ERROR;
3258   }
3259 dropping:
3260   {
3261     GST_DEBUG ("Dropping data after FALSE probe return");
3262     GST_STREAM_UNLOCK (pad);
3263     gst_buffer_unref (*buffer);
3264     *buffer = NULL;
3265     return GST_FLOW_UNEXPECTED;
3266   }
3270 /**
3271  * gst_pad_pull_range:
3272  * @pad: a sink #GstPad.
3273  * @offset: The start offset of the buffer
3274  * @size: The length of the buffer
3275  * @buffer: a pointer to hold the #GstBuffer.
3276  *
3277  * Pulls a buffer from the peer pad. @pad must be a linked
3278  * sinkpad.
3279  *
3280  * Returns: a #GstFlowReturn from the peer pad.
3281  *
3282  * MT safe.
3283  */
3284 GstFlowReturn
3285 gst_pad_pull_range (GstPad * pad, guint64 offset, guint size,
3286     GstBuffer ** buffer)
3288   GstPad *peer;
3289   GstFlowReturn ret;
3290   gboolean emit_signal;
3292   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3293   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK,
3294       GST_FLOW_ERROR);
3295   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
3297   GST_LOCK (pad);
3299   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
3300     handle_pad_block (pad);
3302   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3303     goto not_connected;
3305   /* signal emision for the pad, peer has chance to emit when
3306    * we call _get_range() */
3307   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3309   gst_object_ref (peer);
3310   GST_UNLOCK (pad);
3312   ret = gst_pad_get_range (peer, offset, size, buffer);
3314   gst_object_unref (peer);
3316   /* can only fire the signal if we have a valid buffer */
3317   if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
3318     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
3319       goto dropping;
3320   }
3321   return ret;
3323   /* ERROR recovery here */
3324 not_connected:
3325   {
3326     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3327         "pulling range, but it was not linked");
3328     GST_UNLOCK (pad);
3329     return GST_FLOW_NOT_LINKED;
3330   }
3331 dropping:
3332   {
3333     GST_DEBUG ("Dropping data after FALSE probe return");
3334     gst_buffer_unref (*buffer);
3335     *buffer = NULL;
3336     return GST_FLOW_UNEXPECTED;
3337   }
3340 /**
3341  * gst_pad_push_event:
3342  * @pad: a #GstPad to push the event to.
3343  * @event: the #GstEvent to send to the pad.
3344  *
3345  * Sends the event to the peer of the given pad. This function is
3346  * mainly used by elements to send events to their peer
3347  * elements.
3348  *
3349  * Returns: TRUE if the event was handled.
3350  *
3351  * MT safe.
3352  */
3353 gboolean
3354 gst_pad_push_event (GstPad * pad, GstEvent * event)
3356   GstPad *peerpad;
3357   gboolean result;
3358   gboolean emit_signal;
3360   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3361   g_return_val_if_fail (event != NULL, FALSE);
3363   GST_LOCK (pad);
3364   peerpad = GST_PAD_PEER (pad);
3365   if (peerpad == NULL)
3366     goto not_linked;
3368   emit_signal = GST_PAD_DO_EVENT_SIGNALS (pad) > 0;
3370   gst_object_ref (peerpad);
3371   GST_UNLOCK (pad);
3373   if (G_UNLIKELY (emit_signal)) {
3374     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (event)))
3375       goto dropping;
3376   }
3378   result = gst_pad_send_event (peerpad, event);
3380   gst_object_unref (peerpad);
3382   return result;
3384   /* ERROR handling */
3385 not_linked:
3386   {
3387     gst_event_unref (event);
3388     GST_UNLOCK (pad);
3389     return FALSE;
3390   }
3391 dropping:
3392   {
3393     GST_DEBUG ("Dropping event after FALSE probe return");
3394     gst_object_unref (peerpad);
3395     gst_event_unref (event);
3396     return FALSE;
3397   }
3400 /**
3401  * gst_pad_send_event:
3402  * @pad: a #GstPad to send the event to.
3403  * @event: the #GstEvent to send to the pad.
3404  *
3405  * Sends the event to the pad. This function can be used
3406  * by applications to send events in the pipeline.
3407  *
3408  * Returns: TRUE if the event was handled.
3409  */
3410 gboolean
3411 gst_pad_send_event (GstPad * pad, GstEvent * event)
3413   gboolean result = FALSE;
3414   GstPadEventFunction eventfunc;
3415   gboolean emit_signal;
3417   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3418   g_return_val_if_fail (event != NULL, FALSE);
3420   GST_LOCK (pad);
3422   if (GST_PAD_IS_SINK (pad) && !GST_EVENT_IS_DOWNSTREAM (event))
3423     goto wrong_direction;
3424   if (GST_PAD_IS_SRC (pad) && !GST_EVENT_IS_UPSTREAM (event))
3425     goto wrong_direction;
3427   if (GST_EVENT_SRC (event) == NULL)
3428     GST_EVENT_SRC (event) = gst_object_ref (pad);
3430   switch (GST_EVENT_TYPE (event)) {
3431     case GST_EVENT_FLUSH_START:
3432       GST_CAT_DEBUG (GST_CAT_EVENT,
3433           "have event type %d (FLUSH_START) on pad %s:%s",
3434           GST_EVENT_TYPE (event), GST_DEBUG_PAD_NAME (pad));
3436       /* can't even accept a flush begin event when flushing */
3437       if (GST_PAD_IS_FLUSHING (pad))
3438         goto flushing;
3439       GST_PAD_SET_FLUSHING (pad);
3440       GST_CAT_DEBUG (GST_CAT_EVENT, "set flush flag");
3441       break;
3442     case GST_EVENT_FLUSH_STOP:
3443       GST_PAD_UNSET_FLUSHING (pad);
3444       GST_CAT_DEBUG (GST_CAT_EVENT, "cleared flush flag");
3445       break;
3446     default:
3447       GST_CAT_DEBUG (GST_CAT_EVENT, "have event type %d on pad %s:%s",
3448           GST_EVENT_TYPE (event), GST_DEBUG_PAD_NAME (pad));
3450       if (GST_PAD_IS_FLUSHING (pad))
3451         goto flushing;
3452       break;
3453   }
3455   if ((eventfunc = GST_PAD_EVENTFUNC (pad)) == NULL)
3456     goto no_function;
3458   emit_signal = GST_PAD_DO_EVENT_SIGNALS (pad) > 0;
3460   gst_object_ref (pad);
3461   GST_UNLOCK (pad);
3463   if (G_UNLIKELY (emit_signal)) {
3464     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (event)))
3465       goto dropping;
3466   }
3468   result = eventfunc (GST_PAD_CAST (pad), event);
3470   gst_object_unref (pad);
3472   return result;
3474   /* ERROR handling */
3475 wrong_direction:
3476   {
3477     g_warning ("pad %s:%s sending event in wrong direction",
3478         GST_DEBUG_PAD_NAME (pad));
3479     GST_UNLOCK (pad);
3480     gst_event_unref (event);
3481     return FALSE;
3482   }
3483 no_function:
3484   {
3485     g_warning ("pad %s:%s has no event handler, file a bug.",
3486         GST_DEBUG_PAD_NAME (pad));
3487     GST_UNLOCK (pad);
3488     gst_event_unref (event);
3489     return FALSE;
3490   }
3491 flushing:
3492   {
3493     GST_UNLOCK (pad);
3494     GST_CAT_DEBUG (GST_CAT_EVENT, "Received event on flushing pad. Discarding");
3495     gst_event_unref (event);
3496     return FALSE;
3497   }
3498 dropping:
3499   {
3500     GST_DEBUG ("Dropping event after FALSE probe return");
3501     gst_object_unref (pad);
3502     gst_event_unref (event);
3503     return FALSE;
3504   }
3507 /**
3508  * gst_pad_set_element_private:
3509  * @pad: the #GstPad to set the private data of.
3510  * @priv: The private data to attach to the pad.
3511  *
3512  * Set the given private data gpointer on the pad. 
3513  * This function can only be used by the element that owns the pad.
3514  */
3515 void
3516 gst_pad_set_element_private (GstPad * pad, gpointer priv)
3518   pad->element_private = priv;
3521 /**
3522  * gst_pad_get_element_private:
3523  * @pad: the #GstPad to get the private data of.
3524  *
3525  * Gets the private data of a pad.
3526  *
3527  * Returns: a #gpointer to the private data.
3528  */
3529 gpointer
3530 gst_pad_get_element_private (GstPad * pad)
3532   return pad->element_private;
3535 /**
3536  * gst_pad_start_task:
3537  * @pad: the #GstPad to start the task of
3538  * @func: the task function to call
3539  * @data: data passed to the task function
3540  *
3541  * Starts a task that repeadedly calls @func with @data. This function
3542  * is nostly used in the pad activation function to start the
3543  * dataflow. This function will automatically acauire the STREAM_LOCK of
3544  * the pad before calling @func.
3545  *
3546  * Returns: a TRUE if the task could be started. 
3547  */
3548 gboolean
3549 gst_pad_start_task (GstPad * pad, GstTaskFunction func, gpointer data)
3551   GstTask *task;
3553   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3554   g_return_val_if_fail (func != NULL, FALSE);
3556   GST_LOCK (pad);
3557   task = GST_PAD_TASK (pad);
3558   if (task == NULL) {
3559     task = gst_task_create (func, data);
3560     gst_task_set_lock (task, GST_STREAM_GET_LOCK (pad));
3561     GST_PAD_TASK (pad) = task;
3562   }
3563   gst_task_start (task);
3564   GST_UNLOCK (pad);
3566   return TRUE;
3569 /**
3570  * gst_pad_pause_task:
3571  * @pad: the #GstPad to pause the task of
3572  *
3573  * Pause the task of @pad. This function will also make sure that the 
3574  * function executed by the task will effectively stop.
3575  *
3576  * Returns: a TRUE if the task could be paused or FALSE when the pad
3577  * has no task.
3578  */
3579 gboolean
3580 gst_pad_pause_task (GstPad * pad)
3582   GstTask *task;
3584   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3586   GST_LOCK (pad);
3587   task = GST_PAD_TASK (pad);
3588   if (task == NULL)
3589     goto no_task;
3590   gst_task_pause (task);
3591   GST_UNLOCK (pad);
3593   GST_STREAM_LOCK (pad);
3594   GST_STREAM_UNLOCK (pad);
3596   return TRUE;
3598 no_task:
3599   {
3600     GST_UNLOCK (pad);
3601     return TRUE;
3602   }
3605 /**
3606  * gst_pad_stop_task:
3607  * @pad: the #GstPad to stop the task of
3608  *
3609  * Stop the task of @pad. This function will also make sure that the 
3610  * function executed by the task will effectively stop if not called
3611  * from the GstTaskFunction.
3612  *
3613  * This function will deadlock if called from the GstTaskFunction of
3614  * the task. Use #gst_task_pause() instead.
3615  *
3616  * Returns: a TRUE if the task could be stopped or FALSE when the pad
3617  * has no task.
3618  */
3619 gboolean
3620 gst_pad_stop_task (GstPad * pad)
3622   GstTask *task;
3624   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3626   GST_LOCK (pad);
3627   task = GST_PAD_TASK (pad);
3628   if (task == NULL)
3629     goto no_task;
3630   GST_PAD_TASK (pad) = NULL;
3631   gst_task_stop (task);
3632   GST_UNLOCK (pad);
3634   GST_STREAM_LOCK (pad);
3635   GST_STREAM_UNLOCK (pad);
3637   gst_task_join (task);
3639   gst_object_unref (task);
3641   return TRUE;
3643 no_task:
3644   {
3645     GST_UNLOCK (pad);
3646     return TRUE;
3647   }