configure.ac: comment about refining the xml deps
[platform/upstream/gstreamer.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
25  *                     other elements
26  * @see_also: #GstPadTemplate, #GstElement, #GstEvent
27  *
28  * A #GstElement is linked to other elements via "pads", which are extremely
29  * light-weight generic link points.
30  * After two pads are retrieved from an element with gst_element_get_pad(),
31  * the pads can be link with gst_pad_link(). (For quick links,
32  * you can also use gst_element_link(), which will make the obvious
33  * link for you if it's straightforward.)
34  *
35  * Pads are typically created from a #GstPadTemplate with
36  * gst_pad_new_from_template().
37  *
38  * Pads have #GstCaps attached to it to describe the media type they are
39  * capable of dealing with.  gst_pad_get_caps() and gst_pad_set_caps() are
40  * used to manipulate the caps 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_range() to push out
55  * or pull in a buffer.
56  *
57  * To send a #GstEvent on a pad, use gst_pad_send_event() and
58  * gst_pad_push_event().
59  *
60  * Last reviewed on 2006-07-06 (0.10.9)
61  */
62
63 #include "gst_private.h"
64
65 #include "gstpad.h"
66 #include "gstpadtemplate.h"
67 #include "gstenumtypes.h"
68 #include "gstmarshal.h"
69 #include "gstutils.h"
70 #include "gstinfo.h"
71 #include "gsterror.h"
72 #include "gstvalue.h"
73 #include "glib-compat-private.h"
74
75 GST_DEBUG_CATEGORY_STATIC (debug_dataflow);
76 #define GST_CAT_DEFAULT GST_CAT_PADS
77
78 /* Pad signals and args */
79 enum
80 {
81   PAD_LINKED,
82   PAD_UNLINKED,
83   PAD_REQUEST_LINK,
84   PAD_HAVE_DATA,
85   /* FILL ME */
86   LAST_SIGNAL
87 };
88
89 enum
90 {
91   PAD_PROP_0,
92   PAD_PROP_CAPS,
93   PAD_PROP_DIRECTION,
94   PAD_PROP_TEMPLATE,
95   /* FILL ME */
96 };
97
98 static void gst_pad_class_init (GstPadClass * klass);
99 static void gst_pad_init (GstPad * pad);
100 static void gst_pad_dispose (GObject * object);
101 static void gst_pad_finalize (GObject * object);
102 static void gst_pad_set_property (GObject * object, guint prop_id,
103     const GValue * value, GParamSpec * pspec);
104 static void gst_pad_get_property (GObject * object, guint prop_id,
105     GValue * value, GParamSpec * pspec);
106
107 static GstFlowReturn handle_pad_block (GstPad * pad);
108 static GstCaps *gst_pad_get_caps_unlocked (GstPad * pad);
109 static void gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ);
110 static gboolean gst_pad_activate_default (GstPad * pad);
111 static gboolean gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps);
112
113 #ifndef GST_DISABLE_LOADSAVE
114 static xmlNodePtr gst_pad_save_thyself (GstObject * object, xmlNodePtr parent);
115 #endif
116
117 static GstObjectClass *parent_class = NULL;
118 static guint gst_pad_signals[LAST_SIGNAL] = { 0 };
119
120 /* quarks for probe signals */
121 static GQuark buffer_quark;
122 static GQuark event_quark;
123
124 typedef struct
125 {
126   const gint ret;
127   const gchar *name;
128   GQuark quark;
129 } GstFlowQuarks;
130
131 static GstFlowQuarks flow_quarks[] = {
132   {GST_FLOW_CUSTOM_SUCCESS, "custom-success", 0},
133   {GST_FLOW_RESEND, "resend", 0},
134   {GST_FLOW_OK, "ok", 0},
135   {GST_FLOW_NOT_LINKED, "not-linked", 0},
136   {GST_FLOW_WRONG_STATE, "wrong-state", 0},
137   {GST_FLOW_UNEXPECTED, "unexpected", 0},
138   {GST_FLOW_NOT_NEGOTIATED, "not-negotiated", 0},
139   {GST_FLOW_ERROR, "error", 0},
140   {GST_FLOW_NOT_SUPPORTED, "not-supported", 0},
141   {GST_FLOW_CUSTOM_ERROR, "custom-error", 0},
142
143   {0, NULL, 0}
144 };
145
146 /**
147  * gst_flow_get_name:
148  * @ret: a #GstFlowReturn to get the name of.
149  *
150  * Gets a string representing the given flow return.
151  *
152  * Returns: a static string with the name of the flow return.
153  */
154 G_CONST_RETURN gchar *
155 gst_flow_get_name (GstFlowReturn ret)
156 {
157   gint i;
158
159   ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
160
161   for (i = 0; flow_quarks[i].name; i++) {
162     if (ret == flow_quarks[i].ret)
163       return flow_quarks[i].name;
164   }
165   return "unknown";
166 }
167
168 /**
169  * gst_flow_to_quark:
170  * @ret: a #GstFlowReturn to get the quark of.
171  *
172  * Get the unique quark for the given GstFlowReturn.
173  *
174  * Returns: the quark associated with the flow return or 0 if an
175  * invalid return was specified.
176  */
177 GQuark
178 gst_flow_to_quark (GstFlowReturn ret)
179 {
180   gint i;
181
182   ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
183
184   for (i = 0; flow_quarks[i].name; i++) {
185     if (ret == flow_quarks[i].ret)
186       return flow_quarks[i].quark;
187   }
188   return 0;
189 }
190
191 GType
192 gst_pad_get_type (void)
193 {
194   static GType gst_pad_type = 0;
195
196   if (G_UNLIKELY (gst_pad_type == 0)) {
197     static const GTypeInfo pad_info = {
198       sizeof (GstPadClass), NULL, NULL,
199       (GClassInitFunc) gst_pad_class_init, NULL, NULL,
200       sizeof (GstPad),
201       0,
202       (GInstanceInitFunc) gst_pad_init, NULL
203     };
204     gint i;
205
206     gst_pad_type = g_type_register_static (GST_TYPE_OBJECT, "GstPad",
207         &pad_info, 0);
208
209     buffer_quark = g_quark_from_static_string ("buffer");
210     event_quark = g_quark_from_static_string ("event");
211
212     for (i = 0; flow_quarks[i].name; i++) {
213       flow_quarks[i].quark = g_quark_from_static_string (flow_quarks[i].name);
214     }
215
216     GST_DEBUG_CATEGORY_INIT (debug_dataflow, "GST_DATAFLOW",
217         GST_DEBUG_BOLD | GST_DEBUG_FG_GREEN, "dataflow inside pads");
218   }
219   return gst_pad_type;
220 }
221
222 static gboolean
223 _gst_do_pass_data_accumulator (GSignalInvocationHint * ihint,
224     GValue * return_accu, const GValue * handler_return, gpointer dummy)
225 {
226   gboolean ret = g_value_get_boolean (handler_return);
227
228   GST_DEBUG ("accumulated %d", ret);
229   g_value_set_boolean (return_accu, ret);
230
231   return ret;
232 }
233
234 static gboolean
235 default_have_data (GstPad * pad, GstMiniObject * o)
236 {
237   return TRUE;
238 }
239
240 static void
241 gst_pad_class_init (GstPadClass * klass)
242 {
243   GObjectClass *gobject_class;
244   GstObjectClass *gstobject_class;
245
246   gobject_class = G_OBJECT_CLASS (klass);
247   gstobject_class = GST_OBJECT_CLASS (klass);
248
249   parent_class = g_type_class_peek_parent (klass);
250
251   gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_pad_dispose);
252   gobject_class->finalize = GST_DEBUG_FUNCPTR (gst_pad_finalize);
253   gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_pad_set_property);
254   gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_pad_get_property);
255
256   /**
257    * GstPad::linked:
258    * @pad: the pad that emitted the signal
259    * @peer: the peer pad that has been connected
260    *
261    * Signals that a pad has been linked to the peer pad.
262    */
263   gst_pad_signals[PAD_LINKED] =
264       g_signal_new ("linked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
265       G_STRUCT_OFFSET (GstPadClass, linked), NULL, NULL,
266       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
267   /**
268    * GstPad::unlinked:
269    * @pad: the pad that emitted the signal
270    * @peer: the peer pad that has been disconnected
271    *
272    * Signals that a pad has been unlinked from the peer pad.
273    */
274   gst_pad_signals[PAD_UNLINKED] =
275       g_signal_new ("unlinked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
276       G_STRUCT_OFFSET (GstPadClass, unlinked), NULL, NULL,
277       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
278   /**
279    * GstPad::request-link:
280    * @pad: the pad that emitted the signal
281    * @peer: the peer pad for which a connection is requested
282    *
283    * Signals that a pad connection has been requested.
284    */
285   gst_pad_signals[PAD_REQUEST_LINK] =
286       g_signal_new ("request-link", G_TYPE_FROM_CLASS (klass),
287       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstPadClass, request_link), NULL,
288       NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 0);
289
290   /**
291    * GstPad::have-data:
292    * @pad: the pad that emitted the signal
293    * @mini_obj: new data
294    *
295    * Signals that new data is available on the pad. This signal is used
296    * internally for implementing pad probes.
297    * See gst_pad_add_*_probe functions.
298    *
299    * Returns: %TRUE to keep the data, %FALSE to drop it
300    */
301   gst_pad_signals[PAD_HAVE_DATA] =
302       g_signal_new ("have-data", G_TYPE_FROM_CLASS (klass),
303       G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
304       G_STRUCT_OFFSET (GstPadClass, have_data),
305       _gst_do_pass_data_accumulator,
306       NULL, gst_marshal_BOOLEAN__POINTER, G_TYPE_BOOLEAN, 1,
307       GST_TYPE_MINI_OBJECT);
308
309   g_object_class_install_property (gobject_class, PAD_PROP_CAPS,
310       g_param_spec_boxed ("caps", "Caps", "The capabilities of the pad",
311           GST_TYPE_CAPS, G_PARAM_READABLE));
312   g_object_class_install_property (gobject_class, PAD_PROP_DIRECTION,
313       g_param_spec_enum ("direction", "Direction", "The direction of the pad",
314           GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,
315           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
316   /* FIXME, Make G_PARAM_CONSTRUCT_ONLY when we fix ghostpads. */
317   g_object_class_install_property (gobject_class, PAD_PROP_TEMPLATE,
318       g_param_spec_object ("template", "Template",
319           "The GstPadTemplate of this pad", GST_TYPE_PAD_TEMPLATE,
320           G_PARAM_READWRITE));
321
322 #ifndef GST_DISABLE_LOADSAVE
323   gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_pad_save_thyself);
324 #endif
325   gstobject_class->path_string_separator = ".";
326
327   klass->have_data = default_have_data;
328 }
329
330 static void
331 gst_pad_init (GstPad * pad)
332 {
333   GST_PAD_DIRECTION (pad) = GST_PAD_UNKNOWN;
334   GST_PAD_PEER (pad) = NULL;
335
336   GST_PAD_CHAINFUNC (pad) = NULL;
337
338   GST_PAD_LINKFUNC (pad) = NULL;
339
340   GST_PAD_CAPS (pad) = NULL;
341   GST_PAD_GETCAPSFUNC (pad) = NULL;
342
343   GST_PAD_ACTIVATEFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_activate_default);
344   GST_PAD_EVENTFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_event_default);
345   GST_PAD_QUERYTYPEFUNC (pad) =
346       GST_DEBUG_FUNCPTR (gst_pad_get_query_types_default);
347   GST_PAD_QUERYFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_query_default);
348   GST_PAD_INTLINKFUNC (pad) =
349       GST_DEBUG_FUNCPTR (gst_pad_get_internal_links_default);
350   GST_PAD_ACCEPTCAPSFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_acceptcaps_default);
351
352   pad->do_buffer_signals = 0;
353   pad->do_event_signals = 0;
354
355   GST_PAD_SET_FLUSHING (pad);
356
357   pad->preroll_lock = g_mutex_new ();
358   pad->preroll_cond = g_cond_new ();
359
360   pad->stream_rec_lock = g_new (GStaticRecMutex, 1);
361   g_static_rec_mutex_init (pad->stream_rec_lock);
362
363   pad->block_cond = g_cond_new ();
364 }
365
366 static void
367 gst_pad_dispose (GObject * object)
368 {
369   GstPad *pad = GST_PAD (object);
370
371   GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, pad, "dispose");
372
373   /* we don't hold a ref to the peer so we can just set the
374    * peer to NULL. */
375   GST_PAD_PEER (pad) = NULL;
376
377   /* clear the caps */
378   gst_caps_replace (&GST_PAD_CAPS (pad), NULL);
379
380   gst_pad_set_pad_template (pad, NULL);
381
382   G_OBJECT_CLASS (parent_class)->dispose (object);
383 }
384
385 static void
386 gst_pad_finalize (GObject * object)
387 {
388   GstPad *pad = GST_PAD (object);
389   GstTask *task;
390
391   /* in case the task is still around, clean it up */
392   if ((task = GST_PAD_TASK (pad))) {
393     gst_task_join (task);
394     GST_PAD_TASK (pad) = NULL;
395     gst_object_unref (task);
396   }
397
398   if (pad->stream_rec_lock) {
399     g_static_rec_mutex_free (pad->stream_rec_lock);
400     g_free (pad->stream_rec_lock);
401     pad->stream_rec_lock = NULL;
402   }
403   if (pad->preroll_lock) {
404     g_mutex_free (pad->preroll_lock);
405     g_cond_free (pad->preroll_cond);
406     pad->preroll_lock = NULL;
407     pad->preroll_cond = NULL;
408   }
409   if (pad->block_cond) {
410     g_cond_free (pad->block_cond);
411     pad->block_cond = NULL;
412   }
413
414   G_OBJECT_CLASS (parent_class)->finalize (object);
415 }
416
417 static void
418 gst_pad_set_property (GObject * object, guint prop_id,
419     const GValue * value, GParamSpec * pspec)
420 {
421   g_return_if_fail (GST_IS_PAD (object));
422
423   switch (prop_id) {
424     case PAD_PROP_DIRECTION:
425       GST_PAD_DIRECTION (object) = g_value_get_enum (value);
426       break;
427     case PAD_PROP_TEMPLATE:
428       gst_pad_set_pad_template (GST_PAD_CAST (object),
429           (GstPadTemplate *) g_value_get_object (value));
430       break;
431     default:
432       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
433       break;
434   }
435 }
436
437 static void
438 gst_pad_get_property (GObject * object, guint prop_id,
439     GValue * value, GParamSpec * pspec)
440 {
441   g_return_if_fail (GST_IS_PAD (object));
442
443   switch (prop_id) {
444     case PAD_PROP_CAPS:
445       GST_OBJECT_LOCK (object);
446       g_value_set_boxed (value, GST_PAD_CAPS (object));
447       GST_OBJECT_UNLOCK (object);
448       break;
449     case PAD_PROP_DIRECTION:
450       g_value_set_enum (value, GST_PAD_DIRECTION (object));
451       break;
452     case PAD_PROP_TEMPLATE:
453       g_value_set_object (value, GST_PAD_PAD_TEMPLATE (object));
454       break;
455     default:
456       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
457       break;
458   }
459 }
460
461 /**
462  * gst_pad_new:
463  * @name: the name of the new pad.
464  * @direction: the #GstPadDirection of the pad.
465  *
466  * Creates a new pad with the given name in the given direction.
467  * If name is NULL, a guaranteed unique name (across all pads)
468  * will be assigned.
469  * This function makes a copy of the name so you can safely free the name.
470  *
471  * Returns: a new #GstPad, or NULL in case of an error.
472  *
473  * MT safe.
474  */
475 GstPad *
476 gst_pad_new (const gchar * name, GstPadDirection direction)
477 {
478   return g_object_new (GST_TYPE_PAD,
479       "name", name, "direction", direction, NULL);
480 }
481
482 /**
483  * gst_pad_new_from_template:
484  * @templ: the pad template to use
485  * @name: the name of the element
486  *
487  * Creates a new pad with the given name from the given template.
488  * If name is NULL, a guaranteed unique name (across all pads)
489  * will be assigned.
490  * This function makes a copy of the name so you can safely free the name.
491  *
492  * Returns: a new #GstPad, or NULL in case of an error.
493  */
494 GstPad *
495 gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name)
496 {
497   g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
498
499   return g_object_new (GST_TYPE_PAD,
500       "name", name, "direction", templ->direction, "template", templ, NULL);
501 }
502
503 /**
504  * gst_pad_new_from_static_template:
505  * @templ: the #GstStaticPadTemplate to use
506  * @name: the name of the element
507  *
508  * Creates a new pad with the given name from the given static template.
509  * If name is NULL, a guaranteed unique name (across all pads)
510  * will be assigned.
511  * This function makes a copy of the name so you can safely free the name.
512  *
513  * Returns: a new #GstPad, or NULL in case of an error.
514  */
515 GstPad *
516 gst_pad_new_from_static_template (GstStaticPadTemplate * templ,
517     const gchar * name)
518 {
519   GstPad *pad;
520   GstPadTemplate *template;
521
522   template = gst_static_pad_template_get (templ);
523   pad = gst_pad_new_from_template (template, name);
524   gst_object_unref (template);
525   return pad;
526 }
527
528 /**
529  * gst_pad_get_direction:
530  * @pad: a #GstPad to get the direction of.
531  *
532  * Gets the direction of the pad. The direction of the pad is
533  * decided at construction time so this function does not take
534  * the LOCK.
535  *
536  * Returns: the #GstPadDirection of the pad.
537  *
538  * MT safe.
539  */
540 GstPadDirection
541 gst_pad_get_direction (GstPad * pad)
542 {
543   GstPadDirection result;
544
545   /* PAD_UNKNOWN is a little silly but we need some sort of
546    * error return value */
547   g_return_val_if_fail (GST_IS_PAD (pad), GST_PAD_UNKNOWN);
548
549   GST_OBJECT_LOCK (pad);
550   result = GST_PAD_DIRECTION (pad);
551   GST_OBJECT_UNLOCK (pad);
552
553   return result;
554 }
555
556 static gboolean
557 gst_pad_activate_default (GstPad * pad)
558 {
559   return gst_pad_activate_push (pad, TRUE);
560 }
561
562 static void
563 pre_activate (GstPad * pad, GstActivateMode new_mode)
564 {
565   switch (new_mode) {
566     case GST_ACTIVATE_PUSH:
567     case GST_ACTIVATE_PULL:
568       GST_OBJECT_LOCK (pad);
569       GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE %d, unset flushing",
570           new_mode);
571       GST_PAD_UNSET_FLUSHING (pad);
572       GST_PAD_ACTIVATE_MODE (pad) = new_mode;
573       GST_OBJECT_UNLOCK (pad);
574       break;
575     case GST_ACTIVATE_NONE:
576       GST_OBJECT_LOCK (pad);
577       GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE NONE, set flushing");
578       GST_PAD_SET_FLUSHING (pad);
579       /* unlock blocked pads so element can resume and stop */
580       GST_PAD_BLOCK_BROADCAST (pad);
581       GST_OBJECT_UNLOCK (pad);
582       break;
583   }
584 }
585
586 static void
587 post_activate (GstPad * pad, GstActivateMode new_mode)
588 {
589   switch (new_mode) {
590     case GST_ACTIVATE_PUSH:
591     case GST_ACTIVATE_PULL:
592       /* nop */
593       break;
594     case GST_ACTIVATE_NONE:
595       /* ensures that streaming stops */
596       GST_PAD_STREAM_LOCK (pad);
597       /* while we're at it set activation mode */
598       GST_OBJECT_LOCK (pad);
599       GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE %d", new_mode);
600       GST_PAD_ACTIVATE_MODE (pad) = new_mode;
601       GST_OBJECT_UNLOCK (pad);
602       GST_PAD_STREAM_UNLOCK (pad);
603       break;
604   }
605 }
606
607 /**
608  * gst_pad_set_active:
609  * @pad: the #GstPad to activate or deactivate.
610  * @active: whether or not the pad should be active.
611  *
612  * Activates or deactivates the given pad.
613  * Normally called from within core state change functions.
614  *
615  * If @active, makes sure the pad is active. If it is already active, either in
616  * push or pull mode, just return. Otherwise dispatches to the pad's activate
617  * function to perform the actual activation.
618  *
619  * If not @active, checks the pad's current mode and calls
620  * gst_pad_activate_push() or gst_pad_activate_pull(), as appropriate, with a
621  * FALSE argument.
622  *
623  * Returns: #TRUE if the operation was successful.
624  *
625  * MT safe.
626  */
627 gboolean
628 gst_pad_set_active (GstPad * pad, gboolean active)
629 {
630   GstActivateMode old;
631   gboolean ret = FALSE;
632
633   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
634
635   GST_OBJECT_LOCK (pad);
636   old = GST_PAD_ACTIVATE_MODE (pad);
637   GST_OBJECT_UNLOCK (pad);
638
639   if (active) {
640     switch (old) {
641       case GST_ACTIVATE_PUSH:
642       case GST_ACTIVATE_PULL:
643         ret = TRUE;
644         break;
645       case GST_ACTIVATE_NONE:
646         ret = (GST_PAD_ACTIVATEFUNC (pad)) (pad);
647         break;
648     }
649   } else {
650     switch (old) {
651       case GST_ACTIVATE_PUSH:
652         ret = gst_pad_activate_push (pad, FALSE);
653         break;
654       case GST_ACTIVATE_PULL:
655         ret = gst_pad_activate_pull (pad, FALSE);
656         break;
657       case GST_ACTIVATE_NONE:
658         ret = TRUE;
659         break;
660     }
661   }
662
663   if (!ret) {
664     GST_OBJECT_LOCK (pad);
665     if (!active) {
666       g_critical ("Failed to deactivate pad %s:%s, very bad",
667           GST_DEBUG_PAD_NAME (pad));
668     } else {
669       GST_WARNING ("Failed to activate pad %s:%s", GST_DEBUG_PAD_NAME (pad));
670     }
671     GST_OBJECT_UNLOCK (pad);
672   }
673
674   return ret;
675 }
676
677 /**
678  * gst_pad_activate_pull:
679  * @pad: the #GstPad to activate or deactivate.
680  * @active: whether or not the pad should be active.
681  *
682  * Activates or deactivates the given pad in pull mode via dispatching to the
683  * pad's activatepullfunc. For use from within pad activation functions only.
684  * When called on sink pads, will first proxy the call to the peer pad, which is
685  * expected to activate its internally linked pads from within its activate_pull
686  * function.
687  *
688  * If you don't know what this is, you probably don't want to call it.
689  *
690  * Returns: TRUE if the operation was successful.
691  *
692  * MT safe.
693  */
694 gboolean
695 gst_pad_activate_pull (GstPad * pad, gboolean active)
696 {
697   GstActivateMode old, new;
698   GstPad *peer;
699
700   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
701
702   GST_OBJECT_LOCK (pad);
703   old = GST_PAD_ACTIVATE_MODE (pad);
704   GST_OBJECT_UNLOCK (pad);
705
706   if (active) {
707     switch (old) {
708       case GST_ACTIVATE_PULL:
709         goto was_ok;
710       case GST_ACTIVATE_PUSH:
711         /* pad was activate in the wrong direction, deactivate it
712          * and reactivate it in pull mode */
713         if (G_UNLIKELY (!gst_pad_activate_push (pad, FALSE)))
714           goto deactivate_failed;
715         /* fallthrough, pad is deactivated now. */
716       case GST_ACTIVATE_NONE:
717         break;
718     }
719   } else {
720     switch (old) {
721       case GST_ACTIVATE_NONE:
722         goto was_ok;
723       case GST_ACTIVATE_PUSH:
724         /* pad was activated in the other direction, deactivate it
725          * in push mode, this should not happen... */
726         if (G_UNLIKELY (!gst_pad_activate_push (pad, FALSE)))
727           goto deactivate_failed;
728         /* everything is fine now */
729         goto was_ok;
730       case GST_ACTIVATE_PULL:
731         break;
732     }
733   }
734
735   if (gst_pad_get_direction (pad) == GST_PAD_SINK) {
736     if ((peer = gst_pad_get_peer (pad))) {
737       if (G_UNLIKELY (!gst_pad_activate_pull (peer, active)))
738         goto peer_failed;
739       gst_object_unref (peer);
740     } else {
741       goto not_linked;
742     }
743   } else {
744     if (G_UNLIKELY (GST_PAD_GETRANGEFUNC (pad) == NULL))
745       goto failure;             /* Can't activate pull on a src without a 
746                                    getrange function */
747   }
748
749   new = active ? GST_ACTIVATE_PULL : GST_ACTIVATE_NONE;
750   pre_activate (pad, new);
751
752   if (GST_PAD_ACTIVATEPULLFUNC (pad)) {
753     if (G_UNLIKELY (!GST_PAD_ACTIVATEPULLFUNC (pad) (pad, active)))
754       goto failure;
755   } else {
756     /* can happen for sinks of passthrough elements */
757   }
758
759   post_activate (pad, new);
760
761   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in pull mode",
762       active ? "activated" : "deactivated");
763
764   return TRUE;
765
766 was_ok:
767   {
768     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in pull mode",
769         active ? "activated" : "deactivated");
770     return TRUE;
771   }
772 deactivate_failed:
773   {
774     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
775         "failed to %s in switch to pull from mode %d",
776         (active ? "activate" : "deactivate"), old);
777     return FALSE;
778   }
779 peer_failed:
780   {
781     GST_OBJECT_LOCK (peer);
782     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
783         "activate_pull on peer (%s:%s) failed", GST_DEBUG_PAD_NAME (peer));
784     GST_OBJECT_UNLOCK (peer);
785     gst_object_unref (peer);
786     return FALSE;
787   }
788 not_linked:
789   {
790     GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "can't activate unlinked sink "
791         "pad in pull mode");
792     return FALSE;
793   }
794 failure:
795   {
796     GST_OBJECT_LOCK (pad);
797     GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in pull mode",
798         active ? "activate" : "deactivate");
799     GST_PAD_SET_FLUSHING (pad);
800     GST_PAD_ACTIVATE_MODE (pad) = old;
801     GST_OBJECT_UNLOCK (pad);
802     return FALSE;
803   }
804 }
805
806 /**
807  * gst_pad_activate_push:
808  * @pad: the #GstPad to activate or deactivate.
809  * @active: whether the pad should be active or not.
810  *
811  * Activates or deactivates the given pad in push mode via dispatching to the
812  * pad's activatepushfunc. For use from within pad activation functions only.
813  *
814  * If you don't know what this is, you probably don't want to call it.
815  *
816  * Returns: %TRUE if the operation was successful.
817  *
818  * MT safe.
819  */
820 gboolean
821 gst_pad_activate_push (GstPad * pad, gboolean active)
822 {
823   GstActivateMode old, new;
824
825   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
826   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "trying to set %s in push mode",
827       active ? "activated" : "deactivated");
828
829   GST_OBJECT_LOCK (pad);
830   old = GST_PAD_ACTIVATE_MODE (pad);
831   GST_OBJECT_UNLOCK (pad);
832
833   if (active) {
834     switch (old) {
835       case GST_ACTIVATE_PUSH:
836         goto was_ok;
837       case GST_ACTIVATE_PULL:
838         /* pad was activate in the wrong direction, deactivate it
839          * an reactivate it in push mode */
840         if (G_UNLIKELY (!gst_pad_activate_pull (pad, FALSE)))
841           goto deactivate_failed;
842         /* fallthrough, pad is deactivated now. */
843       case GST_ACTIVATE_NONE:
844         break;
845     }
846   } else {
847     switch (old) {
848       case GST_ACTIVATE_NONE:
849         goto was_ok;
850       case GST_ACTIVATE_PULL:
851         /* pad was activated in the other direction, deactivate it
852          * in pull mode, this should not happen... */
853         if (G_UNLIKELY (!gst_pad_activate_pull (pad, FALSE)))
854           goto deactivate_failed;
855         /* everything is fine now */
856         goto was_ok;
857       case GST_ACTIVATE_PUSH:
858         break;
859     }
860   }
861
862   new = active ? GST_ACTIVATE_PUSH : GST_ACTIVATE_NONE;
863   pre_activate (pad, new);
864
865   if (GST_PAD_ACTIVATEPUSHFUNC (pad)) {
866     if (G_UNLIKELY (!GST_PAD_ACTIVATEPUSHFUNC (pad) (pad, active))) {
867       goto failure;
868     }
869   } else {
870     /* quite ok, element relies on state change func to prepare itself */
871   }
872
873   post_activate (pad, new);
874
875   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in push mode",
876       active ? "activated" : "deactivated");
877   return TRUE;
878
879 was_ok:
880   {
881     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in push mode",
882         active ? "activated" : "deactivated");
883     return TRUE;
884   }
885 deactivate_failed:
886   {
887     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
888         "failed to %s in switch to push from mode %d",
889         (active ? "activate" : "deactivate"), old);
890     return FALSE;
891   }
892 failure:
893   {
894     GST_OBJECT_LOCK (pad);
895     GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in push mode",
896         active ? "activate" : "deactivate");
897     GST_PAD_SET_FLUSHING (pad);
898     GST_PAD_ACTIVATE_MODE (pad) = old;
899     GST_OBJECT_UNLOCK (pad);
900     return FALSE;
901   }
902 }
903
904 /**
905  * gst_pad_is_active:
906  * @pad: the #GstPad to query
907  *
908  * Query if a pad is active
909  *
910  * Returns: TRUE if the pad is active.
911  *
912  * MT safe.
913  */
914 gboolean
915 gst_pad_is_active (GstPad * pad)
916 {
917   gboolean result = FALSE;
918
919   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
920
921   GST_OBJECT_LOCK (pad);
922   result = GST_PAD_MODE_ACTIVATE (GST_PAD_ACTIVATE_MODE (pad));
923   GST_OBJECT_UNLOCK (pad);
924
925   return result;
926 }
927
928 /**
929  * gst_pad_set_blocked_async:
930  * @pad: the #GstPad to block or unblock
931  * @blocked: boolean indicating whether the pad should be blocked or unblocked
932  * @callback: #GstPadBlockCallback that will be called when the
933  *            operation succeeds
934  * @user_data: user data passed to the callback
935  *
936  * Blocks or unblocks the dataflow on a pad. The provided callback
937  * is called when the operation succeeds; this happens right before the next
938  * attempt at pushing a buffer on the pad.
939  *
940  * This can take a while as the pad can only become blocked when real dataflow
941  * is happening.
942  * When the pipeline is stalled, for example in PAUSED, this can
943  * take an indeterminate amount of time.
944  * You can pass NULL as the callback to make this call block. Be careful with
945  * this blocking call as it might not return for reasons stated above.
946  *
947  * Returns: TRUE if the pad could be blocked. This function can fail
948  *   if wrong parameters were passed or the pad was already in the
949  *   requested state.
950  *
951  * MT safe.
952  */
953 gboolean
954 gst_pad_set_blocked_async (GstPad * pad, gboolean blocked,
955     GstPadBlockCallback callback, gpointer user_data)
956 {
957   gboolean was_blocked = FALSE;
958
959   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
960
961   GST_OBJECT_LOCK (pad);
962
963   was_blocked = GST_PAD_IS_BLOCKED (pad);
964
965   if (G_UNLIKELY (was_blocked == blocked))
966     goto had_right_state;
967
968   if (blocked) {
969     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocking pad");
970
971     GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKED);
972     pad->block_callback = callback;
973     pad->block_data = user_data;
974     if (!callback) {
975       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for block");
976       GST_PAD_BLOCK_WAIT (pad);
977       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocked");
978     }
979   } else {
980     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocking pad");
981
982     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKED);
983
984     pad->block_callback = callback;
985     pad->block_data = user_data;
986
987     GST_PAD_BLOCK_BROADCAST (pad);
988     if (!callback) {
989       /* no callback, wait for the unblock to happen */
990       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for unblock");
991       GST_PAD_BLOCK_WAIT (pad);
992       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocked");
993     }
994   }
995   GST_OBJECT_UNLOCK (pad);
996
997   return TRUE;
998
999 had_right_state:
1000   {
1001     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
1002         "pad was in right state (%d)", was_blocked);
1003     GST_OBJECT_UNLOCK (pad);
1004
1005     return FALSE;
1006   }
1007 }
1008
1009 /**
1010  * gst_pad_set_blocked:
1011  * @pad: the #GstPad to block or unblock
1012  * @blocked: boolean indicating we should block or unblock
1013  *
1014  * Blocks or unblocks the dataflow on a pad. This function is
1015  * a shortcut for gst_pad_set_blocked_async() with a NULL
1016  * callback.
1017  *
1018  * Returns: TRUE if the pad could be blocked. This function can fail
1019  *   wrong parameters were passed or the pad was already in the
1020  *   requested state.
1021  *
1022  * MT safe.
1023  */
1024 gboolean
1025 gst_pad_set_blocked (GstPad * pad, gboolean blocked)
1026 {
1027   return gst_pad_set_blocked_async (pad, blocked, NULL, NULL);
1028 }
1029
1030 /**
1031  * gst_pad_is_blocked:
1032  * @pad: the #GstPad to query
1033  *
1034  * Checks if the pad is blocked or not. This function returns the
1035  * last requested state of the pad. It is not certain that the pad
1036  * is actually blocking at this point (see gst_pad_is_blocking()).
1037  *
1038  * Returns: TRUE if the pad is blocked.
1039  *
1040  * MT safe.
1041  */
1042 gboolean
1043 gst_pad_is_blocked (GstPad * pad)
1044 {
1045   gboolean result = FALSE;
1046
1047   g_return_val_if_fail (GST_IS_PAD (pad), result);
1048
1049   GST_OBJECT_LOCK (pad);
1050   result = GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_BLOCKED);
1051   GST_OBJECT_UNLOCK (pad);
1052
1053   return result;
1054 }
1055
1056 /**
1057  * gst_pad_is_blocking:
1058  * @pad: the #GstPad to query
1059  *
1060  * Checks if the pad is blocking or not. This is a guaranteed state
1061  * of whether the pad is actually blocking on a #GstBuffer or a #GstEvent.
1062  *
1063  * Returns: TRUE if the pad is blocking.
1064  *
1065  * MT safe.
1066  *
1067  * Since: 0.10.11
1068  */
1069 gboolean
1070 gst_pad_is_blocking (GstPad * pad)
1071 {
1072   gboolean result = FALSE;
1073
1074   g_return_val_if_fail (GST_IS_PAD (pad), result);
1075
1076   GST_OBJECT_LOCK (pad);
1077   /* the blocking flag is only valid if the pad is not flushing */
1078   result = GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_BLOCKING) &&
1079       !GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLUSHING);
1080   GST_OBJECT_UNLOCK (pad);
1081
1082   return result;
1083 }
1084
1085 /**
1086  * gst_pad_set_activate_function:
1087  * @pad: a #GstPad.
1088  * @activate: the #GstPadActivateFunction to set.
1089  *
1090  * Sets the given activate function for @pad. The activate function will
1091  * dispatch to gst_pad_activate_push() or gst_pad_activate_pull() to perform
1092  * the actual activation. Only makes sense to set on sink pads.
1093  *
1094  * Call this function if your sink pad can start a pull-based task.
1095  */
1096 void
1097 gst_pad_set_activate_function (GstPad * pad, GstPadActivateFunction activate)
1098 {
1099   g_return_if_fail (GST_IS_PAD (pad));
1100
1101   GST_PAD_ACTIVATEFUNC (pad) = activate;
1102   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatefunc set to %s",
1103       GST_DEBUG_FUNCPTR_NAME (activate));
1104 }
1105
1106 /**
1107  * gst_pad_set_activatepull_function:
1108  * @pad: a #GstPad.
1109  * @activatepull: the #GstPadActivateModeFunction to set.
1110  *
1111  * Sets the given activate_pull function for the pad. An activate_pull function
1112  * prepares the element and any upstream connections for pulling. See XXX
1113  * part-activation.txt for details.
1114  */
1115 void
1116 gst_pad_set_activatepull_function (GstPad * pad,
1117     GstPadActivateModeFunction activatepull)
1118 {
1119   g_return_if_fail (GST_IS_PAD (pad));
1120
1121   GST_PAD_ACTIVATEPULLFUNC (pad) = activatepull;
1122   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatepullfunc set to %s",
1123       GST_DEBUG_FUNCPTR_NAME (activatepull));
1124 }
1125
1126 /**
1127  * gst_pad_set_activatepush_function:
1128  * @pad: a #GstPad.
1129  * @activatepush: the #GstPadActivateModeFunction to set.
1130  *
1131  * Sets the given activate_push function for the pad. An activate_push function
1132  * prepares the element for pushing. See XXX part-activation.txt for details.
1133  */
1134 void
1135 gst_pad_set_activatepush_function (GstPad * pad,
1136     GstPadActivateModeFunction activatepush)
1137 {
1138   g_return_if_fail (GST_IS_PAD (pad));
1139
1140   GST_PAD_ACTIVATEPUSHFUNC (pad) = activatepush;
1141   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatepushfunc set to %s",
1142       GST_DEBUG_FUNCPTR_NAME (activatepush));
1143 }
1144
1145 /**
1146  * gst_pad_set_chain_function:
1147  * @pad: a sink #GstPad.
1148  * @chain: the #GstPadChainFunction to set.
1149  *
1150  * Sets the given chain function for the pad. The chain function is called to
1151  * process a #GstBuffer input buffer. see #GstPadChainFunction for more details.
1152  */
1153 void
1154 gst_pad_set_chain_function (GstPad * pad, GstPadChainFunction chain)
1155 {
1156   g_return_if_fail (GST_IS_PAD (pad));
1157   g_return_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK);
1158
1159   GST_PAD_CHAINFUNC (pad) = chain;
1160   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "chainfunc set to %s",
1161       GST_DEBUG_FUNCPTR_NAME (chain));
1162 }
1163
1164 /**
1165  * gst_pad_set_getrange_function:
1166  * @pad: a source #GstPad.
1167  * @get: the #GstPadGetRangeFunction to set.
1168  *
1169  * Sets the given getrange function for the pad. The getrange function is called to
1170  * produce a new #GstBuffer to start the processing pipeline. see
1171  * #GstPadGetRangeFunction for a description of the getrange function.
1172  */
1173 void
1174 gst_pad_set_getrange_function (GstPad * pad, GstPadGetRangeFunction get)
1175 {
1176   g_return_if_fail (GST_IS_PAD (pad));
1177   g_return_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC);
1178
1179   GST_PAD_GETRANGEFUNC (pad) = get;
1180
1181   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "getrangefunc set to %s",
1182       GST_DEBUG_FUNCPTR_NAME (get));
1183 }
1184
1185 /**
1186  * gst_pad_set_checkgetrange_function:
1187  * @pad: a source #GstPad.
1188  * @check: the #GstPadCheckGetRangeFunction to set.
1189  *
1190  * Sets the given checkgetrange function for the pad. Implement this function on
1191  * a pad if you dynamically support getrange based scheduling on the pad.
1192  */
1193 void
1194 gst_pad_set_checkgetrange_function (GstPad * pad,
1195     GstPadCheckGetRangeFunction check)
1196 {
1197   g_return_if_fail (GST_IS_PAD (pad));
1198   g_return_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC);
1199
1200   GST_PAD_CHECKGETRANGEFUNC (pad) = check;
1201
1202   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "checkgetrangefunc set to %s",
1203       GST_DEBUG_FUNCPTR_NAME (check));
1204 }
1205
1206 /**
1207  * gst_pad_set_event_function:
1208  * @pad: a source #GstPad.
1209  * @event: the #GstPadEventFunction to set.
1210  *
1211  * Sets the given event handler for the pad.
1212  */
1213 void
1214 gst_pad_set_event_function (GstPad * pad, GstPadEventFunction event)
1215 {
1216   g_return_if_fail (GST_IS_PAD (pad));
1217
1218   GST_PAD_EVENTFUNC (pad) = event;
1219
1220   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "eventfunc for set to %s",
1221       GST_DEBUG_FUNCPTR_NAME (event));
1222 }
1223
1224 /**
1225  * gst_pad_set_query_function:
1226  * @pad: a #GstPad of either direction.
1227  * @query: the #GstPadQueryFunction to set.
1228  *
1229  * Set the given query function for the pad.
1230  */
1231 void
1232 gst_pad_set_query_function (GstPad * pad, GstPadQueryFunction query)
1233 {
1234   g_return_if_fail (GST_IS_PAD (pad));
1235
1236   GST_PAD_QUERYFUNC (pad) = query;
1237
1238   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "queryfunc set to %s",
1239       GST_DEBUG_FUNCPTR_NAME (query));
1240 }
1241
1242 /**
1243  * gst_pad_set_query_type_function:
1244  * @pad: a #GstPad of either direction.
1245  * @type_func: the #GstPadQueryTypeFunction to set.
1246  *
1247  * Set the given query type function for the pad.
1248  */
1249 void
1250 gst_pad_set_query_type_function (GstPad * pad,
1251     GstPadQueryTypeFunction type_func)
1252 {
1253   g_return_if_fail (GST_IS_PAD (pad));
1254
1255   GST_PAD_QUERYTYPEFUNC (pad) = type_func;
1256
1257   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "querytypefunc set to %s",
1258       GST_DEBUG_FUNCPTR_NAME (type_func));
1259 }
1260
1261 /**
1262  * gst_pad_get_query_types:
1263  * @pad: a #GstPad.
1264  *
1265  * Get an array of supported queries that can be performed
1266  * on this pad.
1267  *
1268  * Returns: a zero-terminated array of #GstQueryType.
1269  */
1270 const GstQueryType *
1271 gst_pad_get_query_types (GstPad * pad)
1272 {
1273   GstPadQueryTypeFunction func;
1274
1275   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1276
1277   if (G_UNLIKELY ((func = GST_PAD_QUERYTYPEFUNC (pad)) == NULL))
1278     goto no_func;
1279
1280   return func (pad);
1281
1282 no_func:
1283   {
1284     return NULL;
1285   }
1286 }
1287
1288 static gboolean
1289 gst_pad_get_query_types_dispatcher (GstPad * pad, const GstQueryType ** data)
1290 {
1291   *data = gst_pad_get_query_types (pad);
1292
1293   return TRUE;
1294 }
1295
1296 /**
1297  * gst_pad_get_query_types_default:
1298  * @pad: a #GstPad.
1299  *
1300  * Invoke the default dispatcher for the query types on
1301  * the pad.
1302  *
1303  * Returns: an zero-terminated array of #GstQueryType, or NULL if none of the
1304  * internally-linked pads has a query types function.
1305  */
1306 const GstQueryType *
1307 gst_pad_get_query_types_default (GstPad * pad)
1308 {
1309   GstQueryType *result = NULL;
1310
1311   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1312
1313   gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
1314       gst_pad_get_query_types_dispatcher, &result);
1315
1316   return result;
1317 }
1318
1319 /**
1320  * gst_pad_set_internal_link_function:
1321  * @pad: a #GstPad of either direction.
1322  * @intlink: the #GstPadIntLinkFunction to set.
1323  *
1324  * Sets the given internal link function for the pad.
1325  */
1326 void
1327 gst_pad_set_internal_link_function (GstPad * pad, GstPadIntLinkFunction intlink)
1328 {
1329   g_return_if_fail (GST_IS_PAD (pad));
1330
1331   GST_PAD_INTLINKFUNC (pad) = intlink;
1332   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "internal link set to %s",
1333       GST_DEBUG_FUNCPTR_NAME (intlink));
1334 }
1335
1336 /**
1337  * gst_pad_set_link_function:
1338  * @pad: a #GstPad.
1339  * @link: the #GstPadLinkFunction to set.
1340  *
1341  * Sets the given link function for the pad. It will be called when
1342  * the pad is linked with another pad.
1343  *
1344  * The return value #GST_PAD_LINK_OK should be used when the connection can be
1345  * made.
1346  *
1347  * The return value #GST_PAD_LINK_REFUSED should be used when the connection
1348  * cannot be made for some reason.
1349  *
1350  * If @link is installed on a source pad, it should call the #GstPadLinkFunction
1351  * of the peer sink pad, if present.
1352  */
1353 void
1354 gst_pad_set_link_function (GstPad * pad, GstPadLinkFunction link)
1355 {
1356   g_return_if_fail (GST_IS_PAD (pad));
1357
1358   GST_PAD_LINKFUNC (pad) = link;
1359   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "linkfunc set to %s",
1360       GST_DEBUG_FUNCPTR_NAME (link));
1361 }
1362
1363 /**
1364  * gst_pad_set_unlink_function:
1365  * @pad: a #GstPad.
1366  * @unlink: the #GstPadUnlinkFunction to set.
1367  *
1368  * Sets the given unlink function for the pad. It will be called
1369  * when the pad is unlinked.
1370  */
1371 void
1372 gst_pad_set_unlink_function (GstPad * pad, GstPadUnlinkFunction unlink)
1373 {
1374   g_return_if_fail (GST_IS_PAD (pad));
1375
1376   GST_PAD_UNLINKFUNC (pad) = unlink;
1377   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "unlinkfunc set to %s",
1378       GST_DEBUG_FUNCPTR_NAME (unlink));
1379 }
1380
1381 /**
1382  * gst_pad_set_getcaps_function:
1383  * @pad: a #GstPad.
1384  * @getcaps: the #GstPadGetCapsFunction to set.
1385  *
1386  * Sets the given getcaps function for the pad. @getcaps should return the
1387  * allowable caps for a pad in the context of the element's state, its link to
1388  * other elements, and the devices or files it has opened. These caps must be a
1389  * subset of the pad template caps. In the NULL state with no links, @getcaps
1390  * should ideally return the same caps as the pad template. In rare
1391  * circumstances, an object property can affect the caps returned by @getcaps,
1392  * but this is discouraged.
1393  *
1394  * You do not need to call this function if @pad's allowed caps are always the
1395  * same as the pad template caps. This can only be true if the padtemplate
1396  * has fixed simple caps.
1397  *
1398  * For most filters, the caps returned by @getcaps is directly affected by the
1399  * allowed caps on other pads. For demuxers and decoders, the caps returned by
1400  * the srcpad's getcaps function is directly related to the stream data. Again,
1401  * @getcaps should return the most specific caps it reasonably can, since this
1402  * helps with autoplugging.
1403  *
1404  * Note that the return value from @getcaps is owned by the caller, so the caller
1405  * should unref the caps after usage.
1406  */
1407 void
1408 gst_pad_set_getcaps_function (GstPad * pad, GstPadGetCapsFunction getcaps)
1409 {
1410   g_return_if_fail (GST_IS_PAD (pad));
1411
1412   GST_PAD_GETCAPSFUNC (pad) = getcaps;
1413   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "getcapsfunc set to %s",
1414       GST_DEBUG_FUNCPTR_NAME (getcaps));
1415 }
1416
1417 /**
1418  * gst_pad_set_acceptcaps_function:
1419  * @pad: a #GstPad.
1420  * @acceptcaps: the #GstPadAcceptCapsFunction to set.
1421  *
1422  * Sets the given acceptcaps function for the pad.  The acceptcaps function
1423  * will be called to check if the pad can accept the given caps. Setting the
1424  * acceptcaps function to NULL restores the default behaviour of allowing 
1425  * any caps that matches the caps from gst_pad_get_caps.
1426  */
1427 void
1428 gst_pad_set_acceptcaps_function (GstPad * pad,
1429     GstPadAcceptCapsFunction acceptcaps)
1430 {
1431   g_return_if_fail (GST_IS_PAD (pad));
1432
1433   GST_PAD_ACCEPTCAPSFUNC (pad) = acceptcaps;
1434   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "acceptcapsfunc set to %s",
1435       GST_DEBUG_FUNCPTR_NAME (acceptcaps));
1436 }
1437
1438 /**
1439  * gst_pad_set_fixatecaps_function:
1440  * @pad: a #GstPad.
1441  * @fixatecaps: the #GstPadFixateCapsFunction to set.
1442  *
1443  * Sets the given fixatecaps function for the pad.  The fixatecaps function
1444  * will be called whenever the default values for a GstCaps needs to be
1445  * filled in.
1446  */
1447 void
1448 gst_pad_set_fixatecaps_function (GstPad * pad,
1449     GstPadFixateCapsFunction fixatecaps)
1450 {
1451   g_return_if_fail (GST_IS_PAD (pad));
1452
1453   GST_PAD_FIXATECAPSFUNC (pad) = fixatecaps;
1454   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "fixatecapsfunc set to %s",
1455       GST_DEBUG_FUNCPTR_NAME (fixatecaps));
1456 }
1457
1458 /**
1459  * gst_pad_set_setcaps_function:
1460  * @pad: a #GstPad.
1461  * @setcaps: the #GstPadSetCapsFunction to set.
1462  *
1463  * Sets the given setcaps function for the pad.  The setcaps function
1464  * will be called whenever a buffer with a new media type is pushed or
1465  * pulled from the pad. The pad/element needs to update its internal
1466  * structures to process the new media type. If this new type is not
1467  * acceptable, the setcaps function should return FALSE.
1468  */
1469 void
1470 gst_pad_set_setcaps_function (GstPad * pad, GstPadSetCapsFunction setcaps)
1471 {
1472   g_return_if_fail (GST_IS_PAD (pad));
1473
1474   GST_PAD_SETCAPSFUNC (pad) = setcaps;
1475   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "setcapsfunc set to %s",
1476       GST_DEBUG_FUNCPTR_NAME (setcaps));
1477 }
1478
1479 /**
1480  * gst_pad_set_bufferalloc_function:
1481  * @pad: a sink #GstPad.
1482  * @bufalloc: the #GstPadBufferAllocFunction to set.
1483  *
1484  * Sets the given bufferalloc function for the pad. Note that the
1485  * bufferalloc function can only be set on sinkpads.
1486  */
1487 void
1488 gst_pad_set_bufferalloc_function (GstPad * pad,
1489     GstPadBufferAllocFunction bufalloc)
1490 {
1491   g_return_if_fail (GST_IS_PAD (pad));
1492   g_return_if_fail (GST_PAD_IS_SINK (pad));
1493
1494   GST_PAD_BUFFERALLOCFUNC (pad) = bufalloc;
1495   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "bufferallocfunc set to %s",
1496       GST_DEBUG_FUNCPTR_NAME (bufalloc));
1497 }
1498
1499 /**
1500  * gst_pad_unlink:
1501  * @srcpad: the source #GstPad to unlink.
1502  * @sinkpad: the sink #GstPad to unlink.
1503  *
1504  * Unlinks the source pad from the sink pad. Will emit the "unlinked" signal on
1505  * both pads.
1506  *
1507  * Returns: TRUE if the pads were unlinked. This function returns FALSE if
1508  * the pads were not linked together.
1509  *
1510  * MT safe.
1511  */
1512 gboolean
1513 gst_pad_unlink (GstPad * srcpad, GstPad * sinkpad)
1514 {
1515   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1516   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1517
1518   GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinking %s:%s(%p) and %s:%s(%p)",
1519       GST_DEBUG_PAD_NAME (srcpad), srcpad,
1520       GST_DEBUG_PAD_NAME (sinkpad), sinkpad);
1521
1522   GST_OBJECT_LOCK (srcpad);
1523
1524   if (G_UNLIKELY (GST_PAD_DIRECTION (srcpad) != GST_PAD_SRC))
1525     goto not_srcpad;
1526
1527   GST_OBJECT_LOCK (sinkpad);
1528
1529   if (G_UNLIKELY (GST_PAD_DIRECTION (sinkpad) != GST_PAD_SINK))
1530     goto not_sinkpad;
1531
1532   if (G_UNLIKELY (GST_PAD_PEER (srcpad) != sinkpad))
1533     goto not_linked_together;
1534
1535   if (GST_PAD_UNLINKFUNC (srcpad)) {
1536     GST_PAD_UNLINKFUNC (srcpad) (srcpad);
1537   }
1538   if (GST_PAD_UNLINKFUNC (sinkpad)) {
1539     GST_PAD_UNLINKFUNC (sinkpad) (sinkpad);
1540   }
1541
1542   /* first clear peers */
1543   GST_PAD_PEER (srcpad) = NULL;
1544   GST_PAD_PEER (sinkpad) = NULL;
1545
1546   GST_OBJECT_UNLOCK (sinkpad);
1547   GST_OBJECT_UNLOCK (srcpad);
1548
1549   /* fire off a signal to each of the pads telling them
1550    * that they've been unlinked */
1551   g_signal_emit (G_OBJECT (srcpad), gst_pad_signals[PAD_UNLINKED], 0, sinkpad);
1552   g_signal_emit (G_OBJECT (sinkpad), gst_pad_signals[PAD_UNLINKED], 0, srcpad);
1553
1554   GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinked %s:%s and %s:%s",
1555       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1556
1557   return TRUE;
1558
1559 not_srcpad:
1560   {
1561     g_critical ("pad %s is not a source pad", GST_PAD_NAME (srcpad));
1562     GST_OBJECT_UNLOCK (srcpad);
1563     return FALSE;
1564   }
1565 not_sinkpad:
1566   {
1567     g_critical ("pad %s is not a sink pad", GST_PAD_NAME (sinkpad));
1568     GST_OBJECT_UNLOCK (sinkpad);
1569     GST_OBJECT_UNLOCK (srcpad);
1570     return FALSE;
1571   }
1572 not_linked_together:
1573   {
1574     /* we do not emit a warning in this case because unlinking cannot
1575      * be made MT safe.*/
1576     GST_OBJECT_UNLOCK (sinkpad);
1577     GST_OBJECT_UNLOCK (srcpad);
1578     return FALSE;
1579   }
1580 }
1581
1582 /**
1583  * gst_pad_is_linked:
1584  * @pad: pad to check
1585  *
1586  * Checks if a @pad is linked to another pad or not.
1587  *
1588  * Returns: TRUE if the pad is linked, FALSE otherwise.
1589  *
1590  * MT safe.
1591  */
1592 gboolean
1593 gst_pad_is_linked (GstPad * pad)
1594 {
1595   gboolean result;
1596
1597   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1598
1599   GST_OBJECT_LOCK (pad);
1600   result = (GST_PAD_PEER (pad) != NULL);
1601   GST_OBJECT_UNLOCK (pad);
1602
1603   return result;
1604 }
1605
1606 /* get the caps from both pads and see if the intersection
1607  * is not empty.
1608  *
1609  * This function should be called with the pad LOCK on both
1610  * pads
1611  */
1612 static gboolean
1613 gst_pad_link_check_compatible_unlocked (GstPad * src, GstPad * sink)
1614 {
1615   GstCaps *srccaps;
1616   GstCaps *sinkcaps;
1617   GstCaps *icaps;
1618
1619   srccaps = gst_pad_get_caps_unlocked (src);
1620   sinkcaps = gst_pad_get_caps_unlocked (sink);
1621
1622   GST_CAT_DEBUG (GST_CAT_CAPS, "src caps %" GST_PTR_FORMAT, srccaps);
1623   GST_CAT_DEBUG (GST_CAT_CAPS, "sink caps %" GST_PTR_FORMAT, sinkcaps);
1624
1625   /* if we have caps on both pads we can check the intersection. If one
1626    * of the caps is NULL, we return TRUE. */
1627   if (srccaps == NULL || sinkcaps == NULL)
1628     goto done;
1629
1630   icaps = gst_caps_intersect (srccaps, sinkcaps);
1631   gst_caps_unref (srccaps);
1632   gst_caps_unref (sinkcaps);
1633
1634   if (icaps == NULL)
1635     goto was_null;
1636
1637   GST_CAT_DEBUG (GST_CAT_CAPS,
1638       "intersection caps %p %" GST_PTR_FORMAT, icaps, icaps);
1639
1640   if (gst_caps_is_empty (icaps))
1641     goto was_empty;
1642
1643   gst_caps_unref (icaps);
1644
1645 done:
1646   return TRUE;
1647
1648   /* incompatible cases */
1649 was_null:
1650   {
1651     GST_CAT_DEBUG (GST_CAT_CAPS, "intersection gave NULL");
1652     return FALSE;
1653   }
1654 was_empty:
1655   {
1656     GST_CAT_DEBUG (GST_CAT_CAPS, "intersection is EMPTY");
1657     gst_caps_unref (icaps);
1658     return FALSE;
1659   }
1660 }
1661
1662 /* check if the grandparents of both pads are the same.
1663  * This check is required so that we don't try to link
1664  * pads from elements in different bins without ghostpads.
1665  *
1666  * The LOCK should be held on both pads
1667  */
1668 static gboolean
1669 gst_pad_link_check_hierarchy (GstPad * src, GstPad * sink)
1670 {
1671   GstObject *psrc, *psink;
1672
1673   psrc = GST_OBJECT_PARENT (src);
1674   psink = GST_OBJECT_PARENT (sink);
1675
1676   /* if one of the pads has no parent, we allow the link */
1677   if (G_UNLIKELY (psrc == NULL || psink == NULL))
1678     goto no_parent;
1679
1680   /* if the parents are the same, we have a loop */
1681   if (G_UNLIKELY (psrc == psink))
1682     goto same_parents;
1683
1684   /* if they both have a parent, we check the grandparents. We can not lock
1685    * the parent because we hold on the child (pad) and the locking order is
1686    * parent >> child. */
1687   psrc = GST_OBJECT_PARENT (psrc);
1688   psink = GST_OBJECT_PARENT (psink);
1689
1690   /* if they have grandparents but they are not the same */
1691   if (G_UNLIKELY (psrc != psink))
1692     goto wrong_grandparents;
1693
1694   return TRUE;
1695
1696   /* ERRORS */
1697 no_parent:
1698   {
1699     GST_CAT_DEBUG (GST_CAT_CAPS,
1700         "one of the pads has no parent %" GST_PTR_FORMAT " and %"
1701         GST_PTR_FORMAT, psrc, psink);
1702     return TRUE;
1703   }
1704 same_parents:
1705   {
1706     GST_CAT_DEBUG (GST_CAT_CAPS, "pads have same parent %" GST_PTR_FORMAT,
1707         psrc);
1708     return FALSE;
1709   }
1710 wrong_grandparents:
1711   {
1712     GST_CAT_DEBUG (GST_CAT_CAPS,
1713         "pads have different grandparents %" GST_PTR_FORMAT " and %"
1714         GST_PTR_FORMAT, psrc, psink);
1715     return FALSE;
1716   }
1717 }
1718
1719 /* FIXME leftover from an attempt at refactoring... */
1720 /* call with the two pads unlocked, when this function returns GST_PAD_LINK_OK,
1721  * the two pads will be locked in the srcpad, sinkpad order. */
1722 static GstPadLinkReturn
1723 gst_pad_link_prepare (GstPad * srcpad, GstPad * sinkpad)
1724 {
1725   /* generic checks */
1726   g_return_val_if_fail (GST_IS_PAD (srcpad), GST_PAD_LINK_REFUSED);
1727   g_return_val_if_fail (GST_IS_PAD (sinkpad), GST_PAD_LINK_REFUSED);
1728
1729   GST_CAT_INFO (GST_CAT_PADS, "trying to link %s:%s and %s:%s",
1730       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1731
1732   GST_OBJECT_LOCK (srcpad);
1733
1734   if (G_UNLIKELY (GST_PAD_DIRECTION (srcpad) != GST_PAD_SRC))
1735     goto not_srcpad;
1736
1737   if (G_UNLIKELY (GST_PAD_PEER (srcpad) != NULL))
1738     goto src_was_linked;
1739
1740   GST_OBJECT_LOCK (sinkpad);
1741
1742   if (G_UNLIKELY (GST_PAD_DIRECTION (sinkpad) != GST_PAD_SINK))
1743     goto not_sinkpad;
1744
1745   if (G_UNLIKELY (GST_PAD_PEER (sinkpad) != NULL))
1746     goto sink_was_linked;
1747
1748   /* check hierarchy, pads can only be linked if the grandparents
1749    * are the same. */
1750   if (!gst_pad_link_check_hierarchy (srcpad, sinkpad))
1751     goto wrong_hierarchy;
1752
1753   /* check pad caps for non-empty intersection */
1754   if (!gst_pad_link_check_compatible_unlocked (srcpad, sinkpad))
1755     goto no_format;
1756
1757   /* FIXME check pad scheduling for non-empty intersection */
1758
1759   return GST_PAD_LINK_OK;
1760
1761 not_srcpad:
1762   {
1763     g_critical ("pad %s is not a source pad", GST_PAD_NAME (srcpad));
1764     GST_OBJECT_UNLOCK (srcpad);
1765     return GST_PAD_LINK_WRONG_DIRECTION;
1766   }
1767 src_was_linked:
1768   {
1769     GST_CAT_INFO (GST_CAT_PADS, "src %s:%s was already linked to %s:%s",
1770         GST_DEBUG_PAD_NAME (srcpad),
1771         GST_DEBUG_PAD_NAME (GST_PAD_PEER (srcpad)));
1772     /* we do not emit a warning in this case because unlinking cannot
1773      * be made MT safe.*/
1774     GST_OBJECT_UNLOCK (srcpad);
1775     return GST_PAD_LINK_WAS_LINKED;
1776   }
1777 not_sinkpad:
1778   {
1779     g_critical ("pad %s is not a sink pad", GST_PAD_NAME (sinkpad));
1780     GST_OBJECT_UNLOCK (sinkpad);
1781     GST_OBJECT_UNLOCK (srcpad);
1782     return GST_PAD_LINK_WRONG_DIRECTION;
1783   }
1784 sink_was_linked:
1785   {
1786     GST_CAT_INFO (GST_CAT_PADS, "sink %s:%s was already linked to %s:%s",
1787         GST_DEBUG_PAD_NAME (sinkpad),
1788         GST_DEBUG_PAD_NAME (GST_PAD_PEER (sinkpad)));
1789     /* we do not emit a warning in this case because unlinking cannot
1790      * be made MT safe.*/
1791     GST_OBJECT_UNLOCK (sinkpad);
1792     GST_OBJECT_UNLOCK (srcpad);
1793     return GST_PAD_LINK_WAS_LINKED;
1794   }
1795 wrong_hierarchy:
1796   {
1797     GST_CAT_INFO (GST_CAT_PADS, "pads have wrong hierarchy");
1798     GST_OBJECT_UNLOCK (sinkpad);
1799     GST_OBJECT_UNLOCK (srcpad);
1800     return GST_PAD_LINK_WRONG_HIERARCHY;
1801   }
1802 no_format:
1803   {
1804     GST_CAT_INFO (GST_CAT_PADS, "caps are incompatible");
1805     GST_OBJECT_UNLOCK (sinkpad);
1806     GST_OBJECT_UNLOCK (srcpad);
1807     return GST_PAD_LINK_NOFORMAT;
1808   }
1809 }
1810
1811 /**
1812  * gst_pad_link:
1813  * @srcpad: the source #GstPad to link.
1814  * @sinkpad: the sink #GstPad to link.
1815  *
1816  * Links the source pad and the sink pad.
1817  *
1818  * Returns: A result code indicating if the connection worked or
1819  *          what went wrong.
1820  *
1821  * MT Safe.
1822  */
1823 GstPadLinkReturn
1824 gst_pad_link (GstPad * srcpad, GstPad * sinkpad)
1825 {
1826   GstPadLinkReturn result;
1827
1828   /* prepare will also lock the two pads */
1829   result = gst_pad_link_prepare (srcpad, sinkpad);
1830
1831   if (result != GST_PAD_LINK_OK)
1832     goto prepare_failed;
1833
1834   /* must set peers before calling the link function */
1835   GST_PAD_PEER (srcpad) = sinkpad;
1836   GST_PAD_PEER (sinkpad) = srcpad;
1837
1838   GST_OBJECT_UNLOCK (sinkpad);
1839   GST_OBJECT_UNLOCK (srcpad);
1840
1841   /* FIXME released the locks here, concurrent thread might link
1842    * something else. */
1843   if (GST_PAD_LINKFUNC (srcpad)) {
1844     /* this one will call the peer link function */
1845     result = GST_PAD_LINKFUNC (srcpad) (srcpad, sinkpad);
1846   } else if (GST_PAD_LINKFUNC (sinkpad)) {
1847     /* if no source link function, we need to call the sink link
1848      * function ourselves. */
1849     result = GST_PAD_LINKFUNC (sinkpad) (sinkpad, srcpad);
1850   } else {
1851     result = GST_PAD_LINK_OK;
1852   }
1853
1854   GST_OBJECT_LOCK (srcpad);
1855   GST_OBJECT_LOCK (sinkpad);
1856
1857   if (result == GST_PAD_LINK_OK) {
1858     GST_OBJECT_UNLOCK (sinkpad);
1859     GST_OBJECT_UNLOCK (srcpad);
1860
1861     /* fire off a signal to each of the pads telling them
1862      * that they've been linked */
1863     g_signal_emit (G_OBJECT (srcpad), gst_pad_signals[PAD_LINKED], 0, sinkpad);
1864     g_signal_emit (G_OBJECT (sinkpad), gst_pad_signals[PAD_LINKED], 0, srcpad);
1865
1866     GST_CAT_INFO (GST_CAT_PADS, "linked %s:%s and %s:%s, successful",
1867         GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1868   } else {
1869     GST_CAT_INFO (GST_CAT_PADS, "link between %s:%s and %s:%s failed",
1870         GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1871
1872     GST_PAD_PEER (srcpad) = NULL;
1873     GST_PAD_PEER (sinkpad) = NULL;
1874
1875     GST_OBJECT_UNLOCK (sinkpad);
1876     GST_OBJECT_UNLOCK (srcpad);
1877   }
1878   return result;
1879
1880 prepare_failed:
1881   {
1882     return result;
1883   }
1884 }
1885
1886 static void
1887 gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ)
1888 {
1889   GstPadTemplate **template_p;
1890
1891   /* this function would need checks if it weren't static */
1892
1893   GST_OBJECT_LOCK (pad);
1894   template_p = &pad->padtemplate;
1895   gst_object_replace ((GstObject **) template_p, (GstObject *) templ);
1896   GST_OBJECT_UNLOCK (pad);
1897
1898   if (templ)
1899     gst_pad_template_pad_created (templ, pad);
1900 }
1901
1902 /**
1903  * gst_pad_get_pad_template:
1904  * @pad: a #GstPad.
1905  *
1906  * Gets the template for @pad.
1907  *
1908  * Returns: the #GstPadTemplate from which this pad was instantiated, or %NULL
1909  * if this pad has no template.
1910  *
1911  * FIXME: currently returns an unrefcounted padtemplate.
1912  */
1913 GstPadTemplate *
1914 gst_pad_get_pad_template (GstPad * pad)
1915 {
1916   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1917
1918   return GST_PAD_PAD_TEMPLATE (pad);
1919 }
1920
1921
1922 /* should be called with the pad LOCK held */
1923 /* refs the caps, so caller is responsible for getting it unreffed */
1924 static GstCaps *
1925 gst_pad_get_caps_unlocked (GstPad * pad)
1926 {
1927   GstCaps *result = NULL;
1928
1929   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get pad caps");
1930
1931   if (GST_PAD_GETCAPSFUNC (pad)) {
1932     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
1933         "dispatching to pad getcaps function");
1934
1935     GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_GETCAPS);
1936     GST_OBJECT_UNLOCK (pad);
1937     result = GST_PAD_GETCAPSFUNC (pad) (pad);
1938     GST_OBJECT_LOCK (pad);
1939     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_GETCAPS);
1940
1941     if (result == NULL) {
1942       g_critical ("pad %s:%s returned NULL caps from getcaps function",
1943           GST_DEBUG_PAD_NAME (pad));
1944     } else {
1945       GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
1946           "pad getcaps returned %" GST_PTR_FORMAT, result);
1947 #ifndef G_DISABLE_ASSERT
1948       /* check that the returned caps are a real subset of the template caps */
1949       if (GST_PAD_PAD_TEMPLATE (pad)) {
1950         const GstCaps *templ_caps =
1951             GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
1952         if (!gst_caps_is_subset (result, templ_caps)) {
1953           GstCaps *temp;
1954
1955           GST_CAT_ERROR_OBJECT (GST_CAT_CAPS, pad,
1956               "pad returned caps %" GST_PTR_FORMAT
1957               " which are not a real subset of its template caps %"
1958               GST_PTR_FORMAT, result, templ_caps);
1959           g_warning
1960               ("pad %s:%s returned caps which are not a real "
1961               "subset of its template caps", GST_DEBUG_PAD_NAME (pad));
1962           temp = gst_caps_intersect (templ_caps, result);
1963           gst_caps_unref (result);
1964           result = temp;
1965         }
1966       }
1967 #endif
1968       goto done;
1969     }
1970   }
1971   if (GST_PAD_PAD_TEMPLATE (pad)) {
1972     GstPadTemplate *templ = GST_PAD_PAD_TEMPLATE (pad);
1973
1974     result = GST_PAD_TEMPLATE_CAPS (templ);
1975     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
1976         "using pad template %p with caps %p %" GST_PTR_FORMAT, templ, result,
1977         result);
1978
1979     result = gst_caps_ref (result);
1980     goto done;
1981   }
1982   if (GST_PAD_CAPS (pad)) {
1983     result = GST_PAD_CAPS (pad);
1984
1985     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
1986         "using pad caps %p %" GST_PTR_FORMAT, result, result);
1987
1988     result = gst_caps_ref (result);
1989     goto done;
1990   }
1991
1992   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "pad has no caps");
1993   result = gst_caps_new_empty ();
1994
1995 done:
1996   return result;
1997 }
1998
1999 /**
2000  * gst_pad_get_caps:
2001  * @pad: a  #GstPad to get the capabilities of.
2002  *
2003  * Gets the capabilities this pad can produce or consume.
2004  * Note that this method doesn't necessarily return the caps set by
2005  * gst_pad_set_caps() - use #GST_PAD_CAPS for that instead.
2006  * gst_pad_get_caps returns all possible caps a pad can operate with, using
2007  * the pad's get_caps function;
2008  * this returns the pad template caps if not explicitly set.
2009  *
2010  * Returns: a newly allocated copy of the #GstCaps of this pad.
2011  *
2012  * MT safe.
2013  */
2014 GstCaps *
2015 gst_pad_get_caps (GstPad * pad)
2016 {
2017   GstCaps *result = NULL;
2018
2019   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2020
2021   GST_OBJECT_LOCK (pad);
2022
2023   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get pad caps");
2024
2025   result = gst_pad_get_caps_unlocked (pad);
2026   GST_OBJECT_UNLOCK (pad);
2027
2028   return result;
2029 }
2030
2031 /**
2032  * gst_pad_peer_get_caps:
2033  * @pad: a  #GstPad to get the peer capabilities of.
2034  *
2035  * Gets the capabilities of the peer connected to this pad.
2036  *
2037  * Returns: the #GstCaps of the peer pad. This function returns a new caps, so use
2038  * gst_caps_unref to get rid of it. this function returns NULL if there is no
2039  * peer pad.
2040  */
2041 GstCaps *
2042 gst_pad_peer_get_caps (GstPad * pad)
2043 {
2044   GstPad *peerpad;
2045   GstCaps *result = NULL;
2046
2047   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2048
2049   GST_OBJECT_LOCK (pad);
2050
2051   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get peer caps");
2052
2053   peerpad = GST_PAD_PEER (pad);
2054   if (G_UNLIKELY (peerpad == NULL))
2055     goto no_peer;
2056
2057   gst_object_ref (peerpad);
2058   GST_OBJECT_UNLOCK (pad);
2059
2060   result = gst_pad_get_caps (peerpad);
2061
2062   gst_object_unref (peerpad);
2063
2064   return result;
2065
2066 no_peer:
2067   {
2068     GST_OBJECT_UNLOCK (pad);
2069     return NULL;
2070   }
2071 }
2072
2073 static gboolean
2074 fixate_value (GValue * dest, const GValue * src)
2075 {
2076   if (G_VALUE_TYPE (src) == GST_TYPE_INT_RANGE) {
2077     g_value_init (dest, G_TYPE_INT);
2078     g_value_set_int (dest, gst_value_get_int_range_min (src));
2079   } else if (G_VALUE_TYPE (src) == GST_TYPE_DOUBLE_RANGE) {
2080     g_value_init (dest, G_TYPE_DOUBLE);
2081     g_value_set_double (dest, gst_value_get_double_range_min (src));
2082   } else if (G_VALUE_TYPE (src) == GST_TYPE_FRACTION_RANGE) {
2083     gst_value_init_and_copy (dest, gst_value_get_fraction_range_min (src));
2084   } else if (G_VALUE_TYPE (src) == GST_TYPE_LIST) {
2085     GValue temp = { 0 };
2086
2087     gst_value_init_and_copy (&temp, gst_value_list_get_value (src, 0));
2088     if (!fixate_value (dest, &temp))
2089       gst_value_init_and_copy (dest, &temp);
2090     g_value_unset (&temp);
2091   } else if (G_VALUE_TYPE (src) == GST_TYPE_ARRAY) {
2092     gboolean res = FALSE;
2093     guint n;
2094
2095     g_value_init (dest, GST_TYPE_ARRAY);
2096     for (n = 0; n < gst_value_array_get_size (src); n++) {
2097       GValue kid = { 0 };
2098       const GValue *orig_kid = gst_value_array_get_value (src, n);
2099
2100       if (!fixate_value (&kid, orig_kid))
2101         gst_value_init_and_copy (&kid, orig_kid);
2102       else
2103         res = TRUE;
2104       gst_value_array_append_value (dest, &kid);
2105       g_value_unset (&kid);
2106     }
2107
2108     if (!res)
2109       g_value_unset (dest);
2110
2111     return res;
2112   } else {
2113     return FALSE;
2114   }
2115
2116   return TRUE;
2117 }
2118
2119 static gboolean
2120 gst_pad_default_fixate (GQuark field_id, const GValue * value, gpointer data)
2121 {
2122   GstStructure *s = data;
2123   GValue v = { 0 };
2124
2125   if (fixate_value (&v, value)) {
2126     gst_structure_id_set_value (s, field_id, &v);
2127     g_value_unset (&v);
2128   }
2129
2130   return TRUE;
2131 }
2132
2133 /**
2134  * gst_pad_fixate_caps:
2135  * @pad: a  #GstPad to fixate
2136  * @caps: the  #GstCaps to fixate
2137  *
2138  * Fixate a caps on the given pad. Modifies the caps in place, so you should
2139  * make sure that the caps are actually writable (see gst_caps_make_writable()).
2140  */
2141 void
2142 gst_pad_fixate_caps (GstPad * pad, GstCaps * caps)
2143 {
2144   GstPadFixateCapsFunction fixatefunc;
2145   guint n;
2146
2147   g_return_if_fail (GST_IS_PAD (pad));
2148   g_return_if_fail (caps != NULL);
2149
2150   if (gst_caps_is_fixed (caps))
2151     return;
2152
2153   fixatefunc = GST_PAD_FIXATECAPSFUNC (pad);
2154   if (fixatefunc) {
2155     fixatefunc (pad, caps);
2156   }
2157
2158   /* default fixation */
2159   for (n = 0; n < gst_caps_get_size (caps); n++) {
2160     GstStructure *s = gst_caps_get_structure (caps, n);
2161
2162     gst_structure_foreach (s, gst_pad_default_fixate, s);
2163   }
2164 }
2165
2166 /* Default accept caps implementation just checks against 
2167  * against the allowed caps for the pad */
2168 static gboolean
2169 gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps)
2170 {
2171   /* get the caps and see if it intersects to something
2172    * not empty */
2173   GstCaps *intersect;
2174   GstCaps *allowed;
2175   gboolean result = FALSE;
2176
2177   allowed = gst_pad_get_caps (pad);
2178   if (!allowed)
2179     goto nothing_allowed;
2180
2181   intersect = gst_caps_intersect (allowed, caps);
2182
2183   result = !gst_caps_is_empty (intersect);
2184   if (!result)
2185     GST_DEBUG_OBJECT (pad, "intersection gave empty caps");
2186
2187   gst_caps_unref (allowed);
2188   gst_caps_unref (intersect);
2189
2190   return result;
2191
2192   /* ERRORS */
2193 nothing_allowed:
2194   {
2195     GST_DEBUG_OBJECT (pad, "no caps allowed on the pad");
2196     return FALSE;
2197   }
2198 }
2199
2200 /**
2201  * gst_pad_accept_caps:
2202  * @pad: a #GstPad to check
2203  * @caps: a #GstCaps to check on the pad
2204  *
2205  * Check if the given pad accepts the caps.
2206  *
2207  * Returns: TRUE if the pad can accept the caps.
2208  */
2209 gboolean
2210 gst_pad_accept_caps (GstPad * pad, GstCaps * caps)
2211 {
2212   gboolean result;
2213   GstPadAcceptCapsFunction acceptfunc;
2214   GstCaps *existing = NULL;
2215
2216   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2217
2218   /* any pad can be unnegotiated */
2219   if (caps == NULL)
2220     return TRUE;
2221
2222   /* lock for checking the existing caps */
2223   GST_OBJECT_LOCK (pad);
2224   acceptfunc = GST_PAD_ACCEPTCAPSFUNC (pad);
2225   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "accept caps of %p", caps);
2226   /* The current caps on a pad are trivially acceptable */
2227   if (G_LIKELY ((existing = GST_PAD_CAPS (pad)))) {
2228     if (caps == existing || gst_caps_is_equal (caps, existing))
2229       goto is_same_caps;
2230   }
2231   GST_OBJECT_UNLOCK (pad);
2232
2233   if (G_LIKELY (acceptfunc)) {
2234     /* we can call the function */
2235     result = acceptfunc (pad, caps);
2236     GST_DEBUG_OBJECT (pad, "acceptfunc returned %d", result);
2237   } else {
2238     /* Only null if the element explicitly unset it */
2239     result = gst_pad_acceptcaps_default (pad, caps);
2240     GST_DEBUG_OBJECT (pad, "default acceptcaps returned %d", result);
2241   }
2242   return result;
2243
2244 is_same_caps:
2245   {
2246     GST_DEBUG_OBJECT (pad, "pad had same caps");
2247     GST_OBJECT_UNLOCK (pad);
2248     return TRUE;
2249   }
2250 }
2251
2252 /**
2253  * gst_pad_peer_accept_caps:
2254  * @pad: a  #GstPad to check the peer of
2255  * @caps: a #GstCaps to check on the pad
2256  *
2257  * Check if the peer of @pad accepts @caps. If @pad has no peer, this function
2258  * returns TRUE.
2259  *
2260  * Returns: TRUE if the peer of @pad can accept the caps or @pad has no peer.
2261  */
2262 gboolean
2263 gst_pad_peer_accept_caps (GstPad * pad, GstCaps * caps)
2264 {
2265   GstPad *peerpad;
2266   gboolean result;
2267
2268   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2269
2270   GST_OBJECT_LOCK (pad);
2271
2272   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "peer accept caps of (%p)", pad);
2273
2274   peerpad = GST_PAD_PEER (pad);
2275   if (G_UNLIKELY (peerpad == NULL))
2276     goto no_peer;
2277
2278   result = gst_pad_accept_caps (peerpad, caps);
2279   GST_OBJECT_UNLOCK (pad);
2280
2281   return result;
2282
2283 no_peer:
2284   {
2285     GST_OBJECT_UNLOCK (pad);
2286     return TRUE;
2287   }
2288 }
2289
2290 /**
2291  * gst_pad_set_caps:
2292  * @pad: a  #GstPad to set the capabilities of.
2293  * @caps: a #GstCaps to set.
2294  *
2295  * Sets the capabilities of this pad. The caps must be fixed. Any previous
2296  * caps on the pad will be unreffed. This function refs the caps so you should
2297  * unref if as soon as you don't need it anymore.
2298  * It is possible to set NULL caps, which will make the pad unnegotiated
2299  * again.
2300  *
2301  * Returns: TRUE if the caps could be set. FALSE if the caps were not fixed
2302  * or bad parameters were provided to this function.
2303  *
2304  * MT safe.
2305  */
2306 gboolean
2307 gst_pad_set_caps (GstPad * pad, GstCaps * caps)
2308 {
2309   GstPadSetCapsFunction setcaps;
2310   GstCaps *existing;
2311
2312   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2313   g_return_val_if_fail (caps == NULL || gst_caps_is_fixed (caps), FALSE);
2314
2315   GST_OBJECT_LOCK (pad);
2316   existing = GST_PAD_CAPS (pad);
2317   if (existing == caps)
2318     goto was_ok;
2319
2320   if (gst_caps_is_equal (caps, existing))
2321     goto setting_same_caps;
2322
2323   setcaps = GST_PAD_SETCAPSFUNC (pad);
2324
2325   /* call setcaps function to configure the pad only if the
2326    * caps is not NULL */
2327   if (setcaps != NULL && caps) {
2328     if (!GST_PAD_IS_IN_SETCAPS (pad)) {
2329       GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_SETCAPS);
2330       GST_OBJECT_UNLOCK (pad);
2331       if (!setcaps (pad, caps))
2332         goto could_not_set;
2333       GST_OBJECT_LOCK (pad);
2334       GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2335     } else {
2336       GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "pad was dispatching");
2337     }
2338   }
2339
2340   gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2341   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "caps %" GST_PTR_FORMAT, caps);
2342   GST_OBJECT_UNLOCK (pad);
2343
2344   g_object_notify (G_OBJECT (pad), "caps");
2345
2346   return TRUE;
2347
2348 was_ok:
2349   {
2350     GST_OBJECT_UNLOCK (pad);
2351     return TRUE;
2352   }
2353 setting_same_caps:
2354   {
2355     gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2356     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2357         "caps %" GST_PTR_FORMAT " same as existing, updating ptr only", caps);
2358     GST_OBJECT_UNLOCK (pad);
2359     return TRUE;
2360   }
2361
2362   /* ERRORS */
2363 could_not_set:
2364   {
2365     GST_OBJECT_LOCK (pad);
2366     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2367     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2368         "caps %" GST_PTR_FORMAT " could not be set", caps);
2369     GST_OBJECT_UNLOCK (pad);
2370
2371     return FALSE;
2372   }
2373 }
2374
2375 static gboolean
2376 gst_pad_configure_sink (GstPad * pad, GstCaps * caps)
2377 {
2378   GstPadSetCapsFunction setcaps;
2379   gboolean res;
2380
2381   setcaps = GST_PAD_SETCAPSFUNC (pad);
2382
2383   /* See if pad accepts the caps - only needed if 
2384    * no setcaps function */
2385   if (setcaps == NULL)
2386     if (!gst_pad_accept_caps (pad, caps))
2387       goto not_accepted;
2388
2389   /* set caps on pad if call succeeds */
2390   res = gst_pad_set_caps (pad, caps);
2391   /* no need to unref the caps here, set_caps takes a ref and
2392    * our ref goes away when we leave this function. */
2393
2394   return res;
2395
2396 not_accepted:
2397   {
2398     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2399         "caps %" GST_PTR_FORMAT " not accepted", caps);
2400     return FALSE;
2401   }
2402 }
2403
2404 /* returns TRUE if the src pad could be configured to accept the given caps */
2405 static gboolean
2406 gst_pad_configure_src (GstPad * pad, GstCaps * caps, gboolean dosetcaps)
2407 {
2408   GstPadSetCapsFunction setcaps;
2409   gboolean res;
2410
2411   setcaps = GST_PAD_SETCAPSFUNC (pad);
2412
2413   /* See if pad accepts the caps - only needed if 
2414    * no setcaps function */
2415   if (setcaps == NULL)
2416     if (!gst_pad_accept_caps (pad, caps))
2417       goto not_accepted;
2418
2419   if (dosetcaps)
2420     res = gst_pad_set_caps (pad, caps);
2421   else
2422     res = TRUE;
2423
2424   return res;
2425
2426 not_accepted:
2427   {
2428     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2429         "caps %" GST_PTR_FORMAT " not accepted", caps);
2430     return FALSE;
2431   }
2432 }
2433
2434 /**
2435  * gst_pad_get_pad_template_caps:
2436  * @pad: a #GstPad to get the template capabilities from.
2437  *
2438  * Gets the capabilities for @pad's template.
2439  *
2440  * Returns: the #GstCaps of this pad template. If you intend to keep a reference
2441  * on the caps, make a copy (see gst_caps_copy ()).
2442  */
2443 const GstCaps *
2444 gst_pad_get_pad_template_caps (GstPad * pad)
2445 {
2446   static GstStaticCaps anycaps = GST_STATIC_CAPS ("ANY");
2447
2448   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2449
2450   if (GST_PAD_PAD_TEMPLATE (pad))
2451     return GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
2452
2453   return gst_static_caps_get (&anycaps);
2454 }
2455
2456
2457 /**
2458  * gst_pad_get_peer:
2459  * @pad: a #GstPad to get the peer of.
2460  *
2461  * Gets the peer of @pad. This function refs the peer pad so
2462  * you need to unref it after use.
2463  *
2464  * Returns: the peer #GstPad. Unref after usage.
2465  *
2466  * MT safe.
2467  */
2468 GstPad *
2469 gst_pad_get_peer (GstPad * pad)
2470 {
2471   GstPad *result;
2472
2473   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2474
2475   GST_OBJECT_LOCK (pad);
2476   result = GST_PAD_PEER (pad);
2477   if (result)
2478     gst_object_ref (result);
2479   GST_OBJECT_UNLOCK (pad);
2480
2481   return result;
2482 }
2483
2484 /**
2485  * gst_pad_get_allowed_caps:
2486  * @pad: a #GstPad.
2487  *
2488  * Gets the capabilities of the allowed media types that can flow through
2489  * @pad and its peer.
2490  *
2491  * The allowed capabilities is calculated as the intersection of the results of
2492  * calling gst_pad_get_caps() on @pad and its peer. The caller owns a reference
2493  * on the resulting caps.
2494  *
2495  * Returns: the allowed #GstCaps of the pad link. Unref the caps when you no
2496  * longer need it. This function returns NULL when @pad has no peer.
2497  *
2498  * MT safe.
2499  */
2500 GstCaps *
2501 gst_pad_get_allowed_caps (GstPad * pad)
2502 {
2503   GstCaps *mycaps;
2504   GstCaps *caps;
2505   GstCaps *peercaps;
2506   GstPad *peer;
2507
2508   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2509
2510   GST_OBJECT_LOCK (pad);
2511
2512   peer = GST_PAD_PEER (pad);
2513   if (G_UNLIKELY (peer == NULL))
2514     goto no_peer;
2515
2516   GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting allowed caps");
2517
2518   gst_object_ref (peer);
2519   GST_OBJECT_UNLOCK (pad);
2520   mycaps = gst_pad_get_caps (pad);
2521
2522   peercaps = gst_pad_get_caps (peer);
2523   gst_object_unref (peer);
2524
2525   caps = gst_caps_intersect (mycaps, peercaps);
2526   gst_caps_unref (peercaps);
2527   gst_caps_unref (mycaps);
2528
2529   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "allowed caps %" GST_PTR_FORMAT,
2530       caps);
2531
2532   return caps;
2533
2534 no_peer:
2535   {
2536     GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
2537     GST_OBJECT_UNLOCK (pad);
2538
2539     return NULL;
2540   }
2541 }
2542
2543 /**
2544  * gst_pad_get_negotiated_caps:
2545  * @pad: a #GstPad.
2546  *
2547  * Gets the capabilities of the media type that currently flows through @pad
2548  * and its peer.
2549  *
2550  * This function can be used on both src and sinkpads. Note that srcpads are
2551  * always negotiated before sinkpads so it is possible that the negotiated caps
2552  * on the srcpad do not match the negotiated caps of the peer.
2553  *
2554  * Returns: the negotiated #GstCaps of the pad link.  Free the caps when
2555  * you no longer need it. This function returns NULL when the @pad has no
2556  * peer or is not negotiated yet.
2557  *
2558  * MT safe.
2559  */
2560 GstCaps *
2561 gst_pad_get_negotiated_caps (GstPad * pad)
2562 {
2563   GstCaps *caps;
2564   GstPad *peer;
2565
2566   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2567
2568   GST_OBJECT_LOCK (pad);
2569
2570   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2571     goto no_peer;
2572
2573   GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting negotiated caps");
2574
2575   caps = GST_PAD_CAPS (pad);
2576   if (caps)
2577     gst_caps_ref (caps);
2578   GST_OBJECT_UNLOCK (pad);
2579
2580   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "negotiated caps %" GST_PTR_FORMAT,
2581       caps);
2582
2583   return caps;
2584
2585 no_peer:
2586   {
2587     GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
2588     GST_OBJECT_UNLOCK (pad);
2589
2590     return NULL;
2591   }
2592 }
2593
2594 /* calls the buffer_alloc function on the given pad */
2595 static GstFlowReturn
2596 gst_pad_buffer_alloc_unchecked (GstPad * pad, guint64 offset, gint size,
2597     GstCaps * caps, GstBuffer ** buf)
2598 {
2599   GstFlowReturn ret;
2600   GstPadBufferAllocFunction bufferallocfunc;
2601
2602   GST_OBJECT_LOCK (pad);
2603   /* when the pad is flushing we cannot give a buffer */
2604   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
2605     goto flushing;
2606
2607   bufferallocfunc = pad->bufferallocfunc;
2608
2609   if (offset == GST_BUFFER_OFFSET_NONE) {
2610     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2611         "calling bufferallocfunc &%s (@%p) for size %d offset NONE",
2612         GST_DEBUG_FUNCPTR_NAME (bufferallocfunc), bufferallocfunc, size);
2613   } else {
2614     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2615         "calling bufferallocfunc &%s (@%p) of for size %d offset %"
2616         G_GUINT64_FORMAT, GST_DEBUG_FUNCPTR_NAME (bufferallocfunc),
2617         bufferallocfunc, size, offset);
2618   }
2619   GST_OBJECT_UNLOCK (pad);
2620
2621   /* G_LIKELY for now since most elements don't implement a buffer alloc
2622    * function and there is no default alloc proxy function as this is usually
2623    * not possible. */
2624   if (G_LIKELY (bufferallocfunc == NULL))
2625     goto fallback;
2626
2627   ret = bufferallocfunc (pad, offset, size, caps, buf);
2628   if (G_UNLIKELY (ret != GST_FLOW_OK))
2629     goto error;
2630   /* no error, but NULL buffer means fallback to the default */
2631   if (G_UNLIKELY (*buf == NULL))
2632     goto fallback;
2633
2634   /* If the buffer alloc function didn't set up the caps like it should,
2635    * do it for it */
2636   if (G_UNLIKELY (caps && (GST_BUFFER_CAPS (*buf) == NULL))) {
2637     GST_WARNING_OBJECT (pad,
2638         "Buffer allocation function did not set caps. Setting");
2639     gst_buffer_set_caps (*buf, caps);
2640   }
2641   return ret;
2642
2643 flushing:
2644   {
2645     /* pad was flushing */
2646     GST_OBJECT_UNLOCK (pad);
2647     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "pad was flushing");
2648     return GST_FLOW_WRONG_STATE;
2649   }
2650 error:
2651   {
2652     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2653         "alloc function returned error (%d) %s", ret, gst_flow_get_name (ret));
2654     return ret;
2655   }
2656 fallback:
2657   {
2658     /* fallback case, allocate a buffer of our own, add pad caps. */
2659     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "fallback buffer alloc");
2660
2661     *buf = gst_buffer_new_and_alloc (size);
2662     GST_BUFFER_OFFSET (*buf) = offset;
2663     gst_buffer_set_caps (*buf, caps);
2664
2665     return GST_FLOW_OK;
2666   }
2667 }
2668
2669 static GstFlowReturn
2670 gst_pad_alloc_buffer_full (GstPad * pad, guint64 offset, gint size,
2671     GstCaps * caps, GstBuffer ** buf, gboolean setcaps)
2672 {
2673   GstPad *peer;
2674   GstFlowReturn ret;
2675   gboolean caps_changed;
2676
2677   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
2678   g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
2679   g_return_val_if_fail (buf != NULL, GST_FLOW_ERROR);
2680
2681   GST_OBJECT_LOCK (pad);
2682   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
2683     if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
2684       goto flushed;
2685
2686   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2687     goto no_peer;
2688
2689   gst_object_ref (peer);
2690   GST_OBJECT_UNLOCK (pad);
2691
2692   ret = gst_pad_buffer_alloc_unchecked (peer, offset, size, caps, buf);
2693   gst_object_unref (peer);
2694
2695   if (G_UNLIKELY (ret != GST_FLOW_OK))
2696     goto peer_error;
2697
2698   /* FIXME, move capnego this into a base class? */
2699   caps = GST_BUFFER_CAPS (*buf);
2700
2701   /* Lock for checking caps, pretty pointless as the _pad_push() function might
2702    * change it concurrently, one of the problems with automatic caps setting in
2703    * pad_alloc_and_set_caps. Worst case, if does a check too much, but only when
2704    * there is heavy renegotiation going on in both directions. */
2705   GST_OBJECT_LOCK (pad);
2706   caps_changed = caps && caps != GST_PAD_CAPS (pad);
2707   GST_OBJECT_UNLOCK (pad);
2708
2709   /* we got a new datatype on the pad, see if it can handle it */
2710   if (G_UNLIKELY (caps_changed)) {
2711     GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
2712     if (G_UNLIKELY (!gst_pad_configure_src (pad, caps, setcaps)))
2713       goto not_negotiated;
2714   }
2715   return ret;
2716
2717 flushed:
2718   {
2719     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "pad block stopped by flush");
2720     GST_OBJECT_UNLOCK (pad);
2721     return ret;
2722   }
2723 no_peer:
2724   {
2725     /* pad has no peer */
2726     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2727         "called bufferallocfunc but had no peer");
2728     GST_OBJECT_UNLOCK (pad);
2729     return GST_FLOW_NOT_LINKED;
2730   }
2731 peer_error:
2732   {
2733     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2734         "alloc function returned error %s", gst_flow_get_name (ret));
2735     return ret;
2736   }
2737 not_negotiated:
2738   {
2739     gst_buffer_unref (*buf);
2740     *buf = NULL;
2741     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2742         "alloc function returned unacceptable buffer");
2743     return GST_FLOW_NOT_NEGOTIATED;
2744   }
2745 }
2746
2747 /**
2748  * gst_pad_alloc_buffer:
2749  * @pad: a source #GstPad
2750  * @offset: the offset of the new buffer in the stream
2751  * @size: the size of the new buffer
2752  * @caps: the caps of the new buffer
2753  * @buf: a newly allocated buffer
2754  *
2755  * Allocates a new, empty buffer optimized to push to pad @pad.  This
2756  * function only works if @pad is a source pad and has a peer.
2757  *
2758  * A new, empty #GstBuffer will be put in the @buf argument.
2759  * You need to check the caps of the buffer after performing this
2760  * function and renegotiate to the format if needed.
2761  *
2762  * Returns: a result code indicating success of the operation. Any
2763  * result code other than #GST_FLOW_OK is an error and @buf should
2764  * not be used.
2765  * An error can occur if the pad is not connected or when the downstream
2766  * peer elements cannot provide an acceptable buffer.
2767  *
2768  * MT safe.
2769  */
2770 GstFlowReturn
2771 gst_pad_alloc_buffer (GstPad * pad, guint64 offset, gint size, GstCaps * caps,
2772     GstBuffer ** buf)
2773 {
2774   return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, FALSE);
2775 }
2776
2777 /**
2778  * gst_pad_alloc_buffer_and_set_caps:
2779  * @pad: a source #GstPad
2780  * @offset: the offset of the new buffer in the stream
2781  * @size: the size of the new buffer
2782  * @caps: the caps of the new buffer
2783  * @buf: a newly allocated buffer
2784  *
2785  * In addition to the function gst_pad_alloc_buffer(), this function
2786  * automatically calls gst_pad_set_caps() when the caps of the
2787  * newly allocated buffer are different from the @pad caps.
2788  *
2789  * Returns: a result code indicating success of the operation. Any
2790  * result code other than #GST_FLOW_OK is an error and @buf should
2791  * not be used.
2792  * An error can occur if the pad is not connected or when the downstream
2793  * peer elements cannot provide an acceptable buffer.
2794  *
2795  * MT safe.
2796  */
2797 GstFlowReturn
2798 gst_pad_alloc_buffer_and_set_caps (GstPad * pad, guint64 offset, gint size,
2799     GstCaps * caps, GstBuffer ** buf)
2800 {
2801   return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, TRUE);
2802 }
2803
2804 /**
2805  * gst_pad_get_internal_links_default:
2806  * @pad: the #GstPad to get the internal links of.
2807  *
2808  * Gets a list of pads to which the given pad is linked to
2809  * inside of the parent element.
2810  * This is the default handler, and thus returns a list of all of the
2811  * pads inside the parent element with opposite direction.
2812  * The caller must free this list after use.
2813  *
2814  * Returns: a newly allocated #GList of pads, or NULL if the pad has no parent.
2815  *
2816  * Not MT safe.
2817  */
2818 GList *
2819 gst_pad_get_internal_links_default (GstPad * pad)
2820 {
2821   GList *res = NULL;
2822   GstElement *parent;
2823   GList *parent_pads;
2824   GstPadDirection direction;
2825
2826   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2827
2828   direction = pad->direction;
2829
2830   parent = GST_PAD_PARENT (pad);
2831   if (!parent)
2832     return NULL;
2833
2834   parent_pads = parent->pads;
2835
2836   while (parent_pads) {
2837     GstPad *parent_pad = GST_PAD_CAST (parent_pads->data);
2838
2839     if (parent_pad->direction != direction) {
2840       res = g_list_prepend (res, parent_pad);
2841     }
2842
2843     parent_pads = g_list_next (parent_pads);
2844   }
2845
2846   return res;
2847 }
2848
2849 /**
2850  * gst_pad_get_internal_links:
2851  * @pad: the #GstPad to get the internal links of.
2852  *
2853  * Gets a list of pads to which the given pad is linked to
2854  * inside of the parent element.
2855  * The caller must free this list after use.
2856  *
2857  * Returns: a newly allocated #GList of pads.
2858  *
2859  * Not MT safe.
2860  */
2861 GList *
2862 gst_pad_get_internal_links (GstPad * pad)
2863 {
2864   GList *res = NULL;
2865
2866   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2867
2868   if (GST_PAD_INTLINKFUNC (pad))
2869     res = GST_PAD_INTLINKFUNC (pad) (pad);
2870
2871   return res;
2872 }
2873
2874
2875 static gboolean
2876 gst_pad_event_default_dispatch (GstPad * pad, GstEvent * event)
2877 {
2878   GList *orig, *pads;
2879   gboolean result;
2880
2881   GST_INFO_OBJECT (pad, "Sending event %p (%s) to all internally linked pads",
2882       event, GST_EVENT_TYPE_NAME (event));
2883
2884   result = (GST_PAD_DIRECTION (pad) == GST_PAD_SINK);
2885
2886   orig = pads = gst_pad_get_internal_links (pad);
2887
2888   while (pads) {
2889     GstPad *eventpad = GST_PAD_CAST (pads->data);
2890
2891     pads = g_list_next (pads);
2892
2893     if (GST_PAD_DIRECTION (eventpad) == GST_PAD_SRC) {
2894       /* for each pad we send to, we should ref the event; it's up
2895        * to downstream to unref again when handled. */
2896       GST_LOG_OBJECT (pad, "Reffing and sending event %p (%s) to %s:%s",
2897           event, GST_EVENT_TYPE_NAME (event), GST_DEBUG_PAD_NAME (eventpad));
2898       gst_event_ref (event);
2899       gst_pad_push_event (eventpad, event);
2900     } else {
2901       /* we only send the event on one pad, multi-sinkpad elements
2902        * should implement a handler */
2903       GST_LOG_OBJECT (pad, "sending event %p (%s) to one sink pad %s:%s",
2904           event, GST_EVENT_TYPE_NAME (event), GST_DEBUG_PAD_NAME (eventpad));
2905       result = gst_pad_push_event (eventpad, event);
2906       goto done;
2907     }
2908   }
2909   /* we handled the incoming event so we unref once */
2910   GST_LOG_OBJECT (pad, "handled event %p, unreffing", event);
2911   gst_event_unref (event);
2912
2913 done:
2914   g_list_free (orig);
2915
2916   return result;
2917 }
2918
2919 /**
2920  * gst_pad_event_default:
2921  * @pad: a #GstPad to call the default event handler on.
2922  * @event: the #GstEvent to handle.
2923  *
2924  * Invokes the default event handler for the given pad. End-of-stream and
2925  * discontinuity events are handled specially, and then the event is sent to all
2926  * pads internally linked to @pad. Note that if there are many possible sink
2927  * pads that are internally linked to @pad, only one will be sent an event.
2928  * Multi-sinkpad elements should implement custom event handlers.
2929  *
2930  * Returns: TRUE if the event was sent succesfully.
2931  */
2932 gboolean
2933 gst_pad_event_default (GstPad * pad, GstEvent * event)
2934 {
2935   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2936   g_return_val_if_fail (event != NULL, FALSE);
2937
2938   switch (GST_EVENT_TYPE (event)) {
2939     case GST_EVENT_EOS:
2940     {
2941       GST_DEBUG_OBJECT (pad, "pausing task because of eos");
2942       gst_pad_pause_task (pad);
2943     }
2944       /* fall thru */
2945     default:
2946       break;
2947   }
2948
2949   return gst_pad_event_default_dispatch (pad, event);
2950 }
2951
2952 /**
2953  * gst_pad_dispatcher:
2954  * @pad: a #GstPad to dispatch.
2955  * @dispatch: the #GstDispatcherFunction to call.
2956  * @data: gpointer user data passed to the dispatcher function.
2957  *
2958  * Invokes the given dispatcher function on each respective peer of
2959  * all pads that are internally linked to the given pad.
2960  * The GstPadDispatcherFunction should return TRUE when no further pads
2961  * need to be processed.
2962  *
2963  * Returns: TRUE if one of the dispatcher functions returned TRUE.
2964  */
2965 gboolean
2966 gst_pad_dispatcher (GstPad * pad, GstPadDispatcherFunction dispatch,
2967     gpointer data)
2968 {
2969   gboolean res = FALSE;
2970   GList *int_pads, *orig;
2971
2972   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2973   g_return_val_if_fail (dispatch != NULL, FALSE);
2974
2975   orig = int_pads = gst_pad_get_internal_links (pad);
2976
2977   while (int_pads) {
2978     GstPad *int_pad = GST_PAD_CAST (int_pads->data);
2979     GstPad *int_peer = GST_PAD_PEER (int_pad);
2980
2981     if (int_peer) {
2982       res = dispatch (int_peer, data);
2983       if (res)
2984         break;
2985     }
2986     int_pads = g_list_next (int_pads);
2987   }
2988
2989   g_list_free (orig);
2990
2991   return res;
2992 }
2993
2994 /**
2995  * gst_pad_query:
2996  * @pad: a #GstPad to invoke the default query on.
2997  * @query: the #GstQuery to perform.
2998  *
2999  * Dispatches a query to a pad. The query should have been allocated by the
3000  * caller via one of the type-specific allocation functions in gstquery.h. The
3001  * element is responsible for filling the query with an appropriate response,
3002  * which should then be parsed with a type-specific query parsing function.
3003  *
3004  * Again, the caller is responsible for both the allocation and deallocation of
3005  * the query structure.
3006  *
3007  * Returns: TRUE if the query could be performed.
3008  */
3009 gboolean
3010 gst_pad_query (GstPad * pad, GstQuery * query)
3011 {
3012   GstPadQueryFunction func;
3013
3014   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3015   g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
3016
3017   GST_DEBUG_OBJECT (pad, "sending query %p", query);
3018
3019   if ((func = GST_PAD_QUERYFUNC (pad)) == NULL)
3020     goto no_func;
3021
3022   return func (pad, query);
3023
3024 no_func:
3025   {
3026     GST_DEBUG_OBJECT (pad, "had no query function");
3027     return FALSE;
3028   }
3029 }
3030
3031 /**
3032  * gst_pad_query_default:
3033  * @pad: a #GstPad to call the default query handler on.
3034  * @query: the #GstQuery to handle.
3035  *
3036  * Invokes the default query handler for the given pad. 
3037  * The query is sent to all pads internally linked to @pad. Note that 
3038  * if there are many possible sink pads that are internally linked to 
3039  * @pad, only one will be sent the query.
3040  * Multi-sinkpad elements should implement custom query handlers.
3041  *
3042  * Returns: TRUE if the query was performed succesfully.
3043  */
3044 gboolean
3045 gst_pad_query_default (GstPad * pad, GstQuery * query)
3046 {
3047   switch (GST_QUERY_TYPE (query)) {
3048     case GST_QUERY_POSITION:
3049     case GST_QUERY_SEEKING:
3050     case GST_QUERY_FORMATS:
3051     case GST_QUERY_LATENCY:
3052     case GST_QUERY_JITTER:
3053     case GST_QUERY_RATE:
3054     case GST_QUERY_CONVERT:
3055     default:
3056       return gst_pad_dispatcher
3057           (pad, (GstPadDispatcherFunction) gst_pad_query, query);
3058   }
3059 }
3060
3061 #ifndef GST_DISABLE_LOADSAVE
3062 /* FIXME: why isn't this on a GstElement ? */
3063 /**
3064  * gst_pad_load_and_link:
3065  * @self: an #xmlNodePtr to read the description from.
3066  * @parent: the #GstObject element that owns the pad.
3067  *
3068  * Reads the pad definition from the XML node and links the given pad
3069  * in the element to a pad of an element up in the hierarchy.
3070  */
3071 void
3072 gst_pad_load_and_link (xmlNodePtr self, GstObject * parent)
3073 {
3074   xmlNodePtr field = self->xmlChildrenNode;
3075   GstPad *pad = NULL, *targetpad;
3076   gchar *peer = NULL;
3077   gchar **split;
3078   GstElement *target;
3079   GstObject *grandparent;
3080   gchar *name = NULL;
3081
3082   while (field) {
3083     if (!strcmp ((char *) field->name, "name")) {
3084       name = (gchar *) xmlNodeGetContent (field);
3085       pad = gst_element_get_pad (GST_ELEMENT (parent), name);
3086       g_free (name);
3087     } else if (!strcmp ((char *) field->name, "peer")) {
3088       peer = (gchar *) xmlNodeGetContent (field);
3089     }
3090     field = field->next;
3091   }
3092   g_return_if_fail (pad != NULL);
3093
3094   if (peer == NULL)
3095     return;
3096
3097   split = g_strsplit (peer, ".", 2);
3098
3099   if (split[0] == NULL || split[1] == NULL) {
3100     GST_CAT_DEBUG_OBJECT (GST_CAT_XML, pad,
3101         "Could not parse peer '%s', leaving unlinked", peer);
3102
3103     g_free (peer);
3104     return;
3105   }
3106   g_free (peer);
3107
3108   g_return_if_fail (split[0] != NULL);
3109   g_return_if_fail (split[1] != NULL);
3110
3111   grandparent = gst_object_get_parent (parent);
3112
3113   if (grandparent && GST_IS_BIN (grandparent)) {
3114     target = gst_bin_get_by_name_recurse_up (GST_BIN (grandparent), split[0]);
3115   } else
3116     goto cleanup;
3117
3118   if (target == NULL)
3119     goto cleanup;
3120
3121   targetpad = gst_element_get_pad (target, split[1]);
3122
3123   if (targetpad == NULL)
3124     goto cleanup;
3125
3126   gst_pad_link (pad, targetpad);
3127
3128 cleanup:
3129   g_strfreev (split);
3130 }
3131
3132 /**
3133  * gst_pad_save_thyself:
3134  * @pad: a #GstPad to save.
3135  * @parent: the parent #xmlNodePtr to save the description in.
3136  *
3137  * Saves the pad into an xml representation.
3138  *
3139  * Returns: the #xmlNodePtr representation of the pad.
3140  */
3141 static xmlNodePtr
3142 gst_pad_save_thyself (GstObject * object, xmlNodePtr parent)
3143 {
3144   GstPad *pad;
3145   GstPad *peer;
3146
3147   g_return_val_if_fail (GST_IS_PAD (object), NULL);
3148
3149   pad = GST_PAD (object);
3150
3151   xmlNewChild (parent, NULL, (xmlChar *) "name",
3152       (xmlChar *) GST_PAD_NAME (pad));
3153
3154   if (GST_PAD_IS_SRC (pad)) {
3155     xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "source");
3156   } else if (GST_PAD_IS_SINK (pad)) {
3157     xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "sink");
3158   } else {
3159     xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "unknown");
3160   }
3161
3162   if (GST_PAD_PEER (pad) != NULL) {
3163     gchar *content;
3164
3165     peer = GST_PAD_PEER (pad);
3166     /* first check to see if the peer's parent's parent is the same */
3167     /* we just save it off */
3168     content = g_strdup_printf ("%s.%s",
3169         GST_OBJECT_NAME (GST_PAD_PARENT (peer)), GST_PAD_NAME (peer));
3170     xmlNewChild (parent, NULL, (xmlChar *) "peer", (xmlChar *) content);
3171     g_free (content);
3172   } else
3173     xmlNewChild (parent, NULL, (xmlChar *) "peer", NULL);
3174
3175   return parent;
3176 }
3177
3178 #if 0
3179 /**
3180  * gst_ghost_pad_save_thyself:
3181  * @pad: a ghost #GstPad to save.
3182  * @parent: the parent #xmlNodePtr to save the description in.
3183  *
3184  * Saves the ghost pad into an xml representation.
3185  *
3186  * Returns: the #xmlNodePtr representation of the pad.
3187  */
3188 xmlNodePtr
3189 gst_ghost_pad_save_thyself (GstPad * pad, xmlNodePtr parent)
3190 {
3191   xmlNodePtr self;
3192
3193   g_return_val_if_fail (GST_IS_GHOST_PAD (pad), NULL);
3194
3195   self = xmlNewChild (parent, NULL, (xmlChar *) "ghostpad", NULL);
3196   xmlNewChild (self, NULL, (xmlChar *) "name", (xmlChar *) GST_PAD_NAME (pad));
3197   xmlNewChild (self, NULL, (xmlChar *) "parent",
3198       (xmlChar *) GST_OBJECT_NAME (GST_PAD_PARENT (pad)));
3199
3200   /* FIXME FIXME FIXME! */
3201
3202   return self;
3203 }
3204 #endif /* 0 */
3205 #endif /* GST_DISABLE_LOADSAVE */
3206
3207 /*
3208  * should be called with pad OBJECT_LOCK and STREAM_LOCK held. 
3209  * GST_PAD_IS_BLOCKED (pad) == TRUE when this function is
3210  * called.
3211  *
3212  * This function perform the pad blocking when an event, buffer push
3213  * or buffer_alloc is performed on a _SRC_ pad. It blocks the
3214  * streaming thread after informing the pad has been blocked. 
3215  *
3216  * An application can with this method wait and block any streaming
3217  * thread and perform operations such as seeking or linking.
3218  *
3219  * Two methods are available for notifying the application of the
3220  * block: 
3221  * - the callback method, which happens in the STREAMING thread with
3222  *   the STREAM_LOCK held. With this method, the most usefull way of
3223  *   dealing with the callback is to post a message to the main thread
3224  *   where the pad block can then be handled outside of the streaming
3225  *   thread. With the last method one can perform all operations such
3226  *   as doing a state change, linking, unblocking, seeking etc on the
3227  *   pad.
3228  * - the GCond signal method, which makes any thread unblock when
3229  *   the pad block happens.
3230  *
3231  * During the actual blocking state, the GST_PAD_BLOCKING flag is set.
3232  * The GST_PAD_BLOCKING flag is unset when the pad was unblocked.
3233  *
3234  * MT safe.
3235  */
3236 static GstFlowReturn
3237 handle_pad_block (GstPad * pad)
3238 {
3239   GstPadBlockCallback callback;
3240   gpointer user_data;
3241   GstFlowReturn ret = GST_FLOW_OK;
3242
3243   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "signal block taken");
3244
3245   /* flushing, don't bother trying to block and return WRONG_STATE
3246    * right away */
3247   if (GST_PAD_IS_FLUSHING (pad))
3248     goto flushingnonref;
3249
3250   /* we grab an extra ref for the callbacks, this is probably not
3251    * needed (callback code does not have a ref and cannot unref). I
3252    * think this was done to make it possible to unref the element in
3253    * the callback, which is in the end totally impossible as it 
3254    * requires grabbing the STREAM_LOCK and OBJECT_LOCK which are
3255    * all taken when calling this function. */
3256   gst_object_ref (pad);
3257
3258   /* we either have a callback installed to notify the block or
3259    * some other thread is doing a GCond wait. */
3260   callback = pad->block_callback;
3261   if (callback) {
3262     /* there is a callback installed, call it. We release the
3263      * lock so that the callback can do something usefull with the
3264      * pad */
3265     user_data = pad->block_data;
3266     GST_OBJECT_UNLOCK (pad);
3267     callback (pad, TRUE, user_data);
3268     GST_OBJECT_LOCK (pad);
3269
3270     /* we released the lock, recheck flushing */
3271     if (GST_PAD_IS_FLUSHING (pad))
3272       goto flushing;
3273   } else {
3274     /* no callback, signal the thread that is doing a GCond wait
3275      * if any. */
3276     GST_PAD_BLOCK_BROADCAST (pad);
3277   }
3278
3279   /* OBJECT_LOCK could have been released when we did the callback, which
3280    * then could have made the pad unblock so we need to check the blocking
3281    * condition again.   */
3282   while (GST_PAD_IS_BLOCKED (pad)) {
3283     /* now we block the streaming thread. It can be unlocked when we 
3284      * deactivate the pad (which will also set the FLUSHING flag) or
3285      * when the pad is unblocked. A flushing event will also unblock
3286      * the pad after setting the FLUSHING flag. */
3287     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3288         "Waiting to be unblocked or set flushing");
3289     GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKING);
3290     GST_PAD_BLOCK_WAIT (pad);
3291     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKING);
3292
3293     /* see if we got unblocked by a flush or not */
3294     if (GST_PAD_IS_FLUSHING (pad))
3295       goto flushing;
3296   }
3297
3298   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "got unblocked");
3299
3300   /* when we get here, the pad is unblocked again and we perform
3301    * the needed unblock code. */
3302   callback = pad->block_callback;
3303   if (callback) {
3304     /* we need to call the callback */
3305     user_data = pad->block_data;
3306     GST_OBJECT_UNLOCK (pad);
3307     callback (pad, FALSE, user_data);
3308     GST_OBJECT_LOCK (pad);
3309   } else {
3310     /* we need to signal the thread waiting on the GCond */
3311     GST_PAD_BLOCK_BROADCAST (pad);
3312   }
3313
3314   gst_object_unref (pad);
3315
3316   return ret;
3317
3318 flushingnonref:
3319   {
3320     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad was flushing");
3321     return GST_FLOW_WRONG_STATE;
3322   }
3323 flushing:
3324   {
3325     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad became flushing");
3326     gst_object_unref (pad);
3327     return GST_FLOW_WRONG_STATE;
3328   }
3329 }
3330
3331 /**********************************************************************
3332  * Data passing functions
3333  */
3334
3335 static gboolean
3336 gst_pad_emit_have_data_signal (GstPad * pad, GstMiniObject * obj)
3337 {
3338   GValue ret = { 0 };
3339   GValue args[2] = { {0}, {0} };
3340   gboolean res;
3341   GQuark detail;
3342
3343   /* init */
3344   g_value_init (&ret, G_TYPE_BOOLEAN);
3345   g_value_set_boolean (&ret, TRUE);
3346   g_value_init (&args[0], GST_TYPE_PAD);
3347   g_value_set_object (&args[0], pad);
3348   g_value_init (&args[1], GST_TYPE_MINI_OBJECT);        // G_TYPE_POINTER);
3349   gst_value_set_mini_object (&args[1], obj);
3350
3351   if (GST_IS_EVENT (obj))
3352     detail = event_quark;
3353   else
3354     detail = buffer_quark;
3355
3356   /* actually emit */
3357   g_signal_emitv (args, gst_pad_signals[PAD_HAVE_DATA], detail, &ret);
3358   res = g_value_get_boolean (&ret);
3359
3360   /* clean up */
3361   g_value_unset (&ret);
3362   g_value_unset (&args[0]);
3363   g_value_unset (&args[1]);
3364
3365   return res;
3366 }
3367
3368 /* this is the chain function that does not perform the additional argument
3369  * checking for that little extra speed.
3370  */
3371 static inline GstFlowReturn
3372 gst_pad_chain_unchecked (GstPad * pad, GstBuffer * buffer)
3373 {
3374   GstCaps *caps;
3375   gboolean caps_changed;
3376   GstPadChainFunction chainfunc;
3377   GstFlowReturn ret;
3378   gboolean emit_signal;
3379
3380   GST_PAD_STREAM_LOCK (pad);
3381
3382   GST_OBJECT_LOCK (pad);
3383   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
3384     goto flushing;
3385
3386   caps = GST_BUFFER_CAPS (buffer);
3387   caps_changed = caps && caps != GST_PAD_CAPS (pad);
3388
3389   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3390   GST_OBJECT_UNLOCK (pad);
3391
3392   /* see if the signal should be emited, we emit before caps nego as
3393    * we might drop the buffer and do capsnego for nothing. */
3394   if (G_UNLIKELY (emit_signal)) {
3395     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (buffer)))
3396       goto dropping;
3397   }
3398
3399   /* we got a new datatype on the pad, see if it can handle it */
3400   if (G_UNLIKELY (caps_changed)) {
3401     GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
3402     if (G_UNLIKELY (!gst_pad_configure_sink (pad, caps)))
3403       goto not_negotiated;
3404   }
3405
3406   /* NOTE: we read the chainfunc unlocked.
3407    * we cannot hold the lock for the pad so we might send
3408    * the data to the wrong function. This is not really a
3409    * problem since functions are assigned at creation time
3410    * and don't change that often... */
3411   if (G_UNLIKELY ((chainfunc = GST_PAD_CHAINFUNC (pad)) == NULL))
3412     goto no_function;
3413
3414   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3415       "calling chainfunction &%s", GST_DEBUG_FUNCPTR_NAME (chainfunc));
3416
3417   ret = chainfunc (pad, buffer);
3418
3419   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3420       "called chainfunction &%s, returned %s",
3421       GST_DEBUG_FUNCPTR_NAME (chainfunc), gst_flow_get_name (ret));
3422
3423   GST_PAD_STREAM_UNLOCK (pad);
3424
3425   return ret;
3426
3427   /* ERRORS */
3428 flushing:
3429   {
3430     gst_buffer_unref (buffer);
3431     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3432         "pushing, but pad was flushing");
3433     GST_OBJECT_UNLOCK (pad);
3434     GST_PAD_STREAM_UNLOCK (pad);
3435     return GST_FLOW_WRONG_STATE;
3436   }
3437 dropping:
3438   {
3439     gst_buffer_unref (buffer);
3440     GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
3441     GST_PAD_STREAM_UNLOCK (pad);
3442     return GST_FLOW_OK;
3443   }
3444 not_negotiated:
3445   {
3446     gst_buffer_unref (buffer);
3447     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3448         "pushing buffer but pad did not accept");
3449     GST_PAD_STREAM_UNLOCK (pad);
3450     return GST_FLOW_NOT_NEGOTIATED;
3451   }
3452 no_function:
3453   {
3454     gst_buffer_unref (buffer);
3455     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3456         "pushing, but not chainhandler");
3457     GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
3458         ("push on pad %s:%s but it has no chainfunction",
3459             GST_DEBUG_PAD_NAME (pad)));
3460     GST_PAD_STREAM_UNLOCK (pad);
3461     return GST_FLOW_NOT_SUPPORTED;
3462   }
3463 }
3464
3465 /**
3466  * gst_pad_chain:
3467  * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
3468  * @buffer: the #GstBuffer to send, return GST_FLOW_ERROR if not.
3469  *
3470  * Chain a buffer to @pad.
3471  *
3472  * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
3473  *
3474  * If the caps on @buffer are different from the current caps on @pad, this
3475  * function will call any setcaps function (see gst_pad_set_setcaps_function())
3476  * installed on @pad. If the new caps are not acceptable for @pad, this function
3477  * returns #GST_FLOW_NOT_NEGOTIATED.
3478  *
3479  * The function proceeds calling the chain function installed on @pad (see
3480  * gst_pad_set_chain_function()) and the return value of that function is
3481  * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
3482  * chain function.
3483  *
3484  * In all cases, success or failure, the caller loses its reference to @buffer
3485  * after calling this function.
3486  *
3487  * Returns: a #GstFlowReturn from the pad.
3488  *
3489  * MT safe.
3490  */
3491 GstFlowReturn
3492 gst_pad_chain (GstPad * pad, GstBuffer * buffer)
3493 {
3494   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3495   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK,
3496       GST_FLOW_ERROR);
3497   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
3498
3499   return gst_pad_chain_unchecked (pad, buffer);
3500 }
3501
3502 /**
3503  * gst_pad_push:
3504  * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
3505  * @buffer: the #GstBuffer to push returns GST_FLOW_ERROR if not.
3506  *
3507  * Pushes a buffer to the peer of @pad.
3508  *
3509  * This function will call an installed pad block before triggering any
3510  * installed pad probes.
3511  *
3512  * If the caps on @buffer are different from the currently configured caps on
3513  * @pad, this function will call any installed setcaps function on @pad (see
3514  * gst_pad_set_setcaps_function()). In case of failure to renegotiate the new
3515  * format, this function returns #GST_FLOW_NOT_NEGOTIATED.
3516  *
3517  * The function proceeds calling gst_pad_chain() on the peer pad and returns the
3518  * value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will be
3519  * returned.
3520  *
3521  * In all cases, success or failure, the caller loses its reference to @buffer
3522  * after calling this function.
3523  *
3524  * Returns: a #GstFlowReturn from the peer pad.
3525  *
3526  * MT safe.
3527  */
3528 GstFlowReturn
3529 gst_pad_push (GstPad * pad, GstBuffer * buffer)
3530 {
3531   GstPad *peer;
3532   GstFlowReturn ret;
3533
3534   GstCaps *caps;
3535   gboolean caps_changed;
3536
3537   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3538   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC, GST_FLOW_ERROR);
3539   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
3540
3541   GST_OBJECT_LOCK (pad);
3542
3543   /* FIXME: this check can go away; pad_set_blocked could be implemented with
3544    * probes completely or probes with an extended pad block. */
3545   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
3546     if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
3547       goto flushed;
3548
3549   /* we emit signals on the pad arg, the peer will have a chance to
3550    * emit in the _chain() function */
3551   if (G_UNLIKELY (GST_PAD_DO_BUFFER_SIGNALS (pad) > 0)) {
3552     /* unlock before emitting */
3553     GST_OBJECT_UNLOCK (pad);
3554
3555     /* if the signal handler returned FALSE, it means we should just drop the
3556      * buffer */
3557     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (buffer)))
3558       goto dropped;
3559
3560     GST_OBJECT_LOCK (pad);
3561   }
3562
3563   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3564     goto not_linked;
3565
3566   /* take ref to peer pad before releasing the lock */
3567   gst_object_ref (peer);
3568
3569   /* Before pushing the buffer to the peer pad, ensure that caps 
3570    * are set on this pad */
3571   caps = GST_BUFFER_CAPS (buffer);
3572   caps_changed = caps && caps != GST_PAD_CAPS (pad);
3573
3574   GST_OBJECT_UNLOCK (pad);
3575
3576   /* we got a new datatype from the pad, it had better handle it */
3577   if (G_UNLIKELY (caps_changed)) {
3578     GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
3579     if (G_UNLIKELY (!gst_pad_configure_src (pad, caps, TRUE)))
3580       goto not_negotiated;
3581   }
3582
3583   ret = gst_pad_chain_unchecked (peer, buffer);
3584
3585   gst_object_unref (peer);
3586
3587   return ret;
3588
3589   /* ERROR recovery here */
3590 flushed:
3591   {
3592     gst_buffer_unref (buffer);
3593     GST_DEBUG_OBJECT (pad, "pad block stopped by flush");
3594     GST_OBJECT_UNLOCK (pad);
3595     return ret;
3596   }
3597 dropped:
3598   {
3599     gst_buffer_unref (buffer);
3600     GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
3601     return GST_FLOW_OK;
3602   }
3603 not_linked:
3604   {
3605     gst_buffer_unref (buffer);
3606     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3607         "pushing, but it was not linked");
3608     GST_OBJECT_UNLOCK (pad);
3609     return GST_FLOW_NOT_LINKED;
3610   }
3611 not_negotiated:
3612   {
3613     gst_buffer_unref (buffer);
3614     gst_object_unref (peer);
3615     GST_CAT_DEBUG_OBJECT (GST_CAT_SCHEDULING, pad,
3616         "element pushed buffer then refused to accept the caps");
3617     return GST_FLOW_NOT_NEGOTIATED;
3618   }
3619 }
3620
3621 /**
3622  * gst_pad_check_pull_range:
3623  * @pad: a sink #GstPad.
3624  *
3625  * Checks if a gst_pad_pull_range() can be performed on the peer
3626  * source pad. This function is used by plugins that want to check
3627  * if they can use random access on the peer source pad.
3628  *
3629  * The peer sourcepad can implement a custom #GstPadCheckGetRangeFunction
3630  * if it needs to perform some logic to determine if pull_range is
3631  * possible.
3632  *
3633  * Returns: a gboolean with the result.
3634  *
3635  * MT safe.
3636  */
3637 gboolean
3638 gst_pad_check_pull_range (GstPad * pad)
3639 {
3640   GstPad *peer;
3641   gboolean ret;
3642   GstPadCheckGetRangeFunction checkgetrangefunc;
3643
3644   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3645
3646   GST_OBJECT_LOCK (pad);
3647   if (GST_PAD_DIRECTION (pad) != GST_PAD_SINK)
3648     goto wrong_direction;
3649
3650   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3651     goto not_connected;
3652
3653   gst_object_ref (peer);
3654   GST_OBJECT_UNLOCK (pad);
3655
3656   /* see note in above function */
3657   if (G_LIKELY ((checkgetrangefunc = peer->checkgetrangefunc) == NULL)) {
3658     /* FIXME, kindoff ghetto */
3659     ret = GST_PAD_GETRANGEFUNC (peer) != NULL;
3660   } else {
3661     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3662         "calling checkgetrangefunc %s of peer pad %s:%s",
3663         GST_DEBUG_FUNCPTR_NAME (checkgetrangefunc), GST_DEBUG_PAD_NAME (peer));
3664
3665     ret = checkgetrangefunc (peer);
3666   }
3667
3668   gst_object_unref (peer);
3669
3670   return ret;
3671
3672   /* ERROR recovery here */
3673 wrong_direction:
3674   {
3675     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3676         "checking pull range, but pad must be a sinkpad");
3677     GST_OBJECT_UNLOCK (pad);
3678     return FALSE;
3679   }
3680 not_connected:
3681   {
3682     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3683         "checking pull range, but it was not linked");
3684     GST_OBJECT_UNLOCK (pad);
3685     return FALSE;
3686   }
3687 }
3688
3689 /**
3690  * gst_pad_get_range:
3691  * @pad: a src #GstPad, returns #GST_FLOW_ERROR if not.
3692  * @offset: The start offset of the buffer
3693  * @size: The length of the buffer
3694  * @buffer: a pointer to hold the #GstBuffer, returns #GST_FLOW_ERROR if %NULL.
3695  *
3696  * When @pad is flushing this function returns #GST_FLOW_WRONG_STATE
3697  * immediatly.
3698  *
3699  * Calls the getrange function of @pad, see #GstPadGetRangeFunction for a
3700  * description of a getrange function. If @pad has no getrange function
3701  * installed (see gst_pad_set_getrange_function()) this function returns
3702  * #GST_FLOW_NOT_SUPPORTED.
3703  *
3704  * @buffer's caps must either be unset or the same as what is already configured
3705  * on @pad. Renegotiation within a running pull-mode pipeline is not supported.
3706  *
3707  * Returns: a #GstFlowReturn from the pad.
3708  *
3709  * MT safe.
3710  */
3711 GstFlowReturn
3712 gst_pad_get_range (GstPad * pad, guint64 offset, guint size,
3713     GstBuffer ** buffer)
3714 {
3715   GstFlowReturn ret;
3716   GstPadGetRangeFunction getrangefunc;
3717   gboolean emit_signal;
3718
3719   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3720   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC, GST_FLOW_ERROR);
3721   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
3722
3723   GST_PAD_STREAM_LOCK (pad);
3724
3725   GST_OBJECT_LOCK (pad);
3726   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
3727     goto flushing;
3728
3729   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3730   GST_OBJECT_UNLOCK (pad);
3731
3732   if (G_UNLIKELY ((getrangefunc = GST_PAD_GETRANGEFUNC (pad)) == NULL))
3733     goto no_function;
3734
3735   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3736       "calling getrangefunc %s, offset %"
3737       G_GUINT64_FORMAT ", size %u",
3738       GST_DEBUG_FUNCPTR_NAME (getrangefunc), offset, size);
3739
3740   ret = getrangefunc (pad, offset, size, buffer);
3741
3742   /* can only fire the signal if we have a valid buffer */
3743   if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
3744     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
3745       goto dropping;
3746   }
3747
3748   GST_PAD_STREAM_UNLOCK (pad);
3749
3750   if (G_LIKELY (ret == GST_FLOW_OK)) {
3751     GstCaps *caps;
3752     gboolean caps_changed;
3753
3754     GST_OBJECT_LOCK (pad);
3755     /* Before pushing the buffer to the peer pad, ensure that caps 
3756      * are set on this pad */
3757     caps = GST_BUFFER_CAPS (*buffer);
3758     caps_changed = caps && caps != GST_PAD_CAPS (pad);
3759     GST_OBJECT_UNLOCK (pad);
3760
3761     /* we got a new datatype from the pad not supported in a running pull-mode
3762      * pipeline */
3763     if (G_UNLIKELY (caps_changed))
3764       goto not_negotiated;
3765   }
3766
3767   return ret;
3768
3769   /* ERRORS */
3770 flushing:
3771   {
3772     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3773         "pulling range, but pad was flushing");
3774     GST_OBJECT_UNLOCK (pad);
3775     GST_PAD_STREAM_UNLOCK (pad);
3776     return GST_FLOW_WRONG_STATE;
3777   }
3778 no_function:
3779   {
3780     GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
3781         ("pullrange on pad %s:%s but it has no getrangefunction",
3782             GST_DEBUG_PAD_NAME (pad)));
3783     GST_PAD_STREAM_UNLOCK (pad);
3784     return GST_FLOW_NOT_SUPPORTED;
3785   }
3786 dropping:
3787   {
3788     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3789         "Dropping data after FALSE probe return");
3790     GST_PAD_STREAM_UNLOCK (pad);
3791     gst_buffer_unref (*buffer);
3792     *buffer = NULL;
3793     return GST_FLOW_UNEXPECTED;
3794   }
3795 not_negotiated:
3796   {
3797     /* ideally we want to use the commented-out code, but currently demuxers and
3798      * typefind do not follow part-negotiation.txt. When switching into pull
3799      * mode, typefind should probably return the found caps from getcaps(), and
3800      * demuxers should do the setcaps(). */
3801
3802 #if 0
3803     gst_buffer_unref (*buffer);
3804     *buffer = NULL;
3805     GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
3806         "getrange returned buffer of different caps");
3807     return GST_FLOW_NOT_NEGOTIATED;
3808 #endif
3809     GST_CAT_DEBUG_OBJECT (GST_CAT_SCHEDULING, pad,
3810         "getrange returned buffer of different caps");
3811     return ret;
3812   }
3813 }
3814
3815
3816 /**
3817  * gst_pad_pull_range:
3818  * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
3819  * @offset: The start offset of the buffer
3820  * @size: The length of the buffer
3821  * @buffer: a pointer to hold the #GstBuffer, returns GST_FLOW_ERROR if %NULL.
3822  *
3823  * Pulls a buffer from the peer pad. 
3824  *
3825  * This function will first trigger the pad block signal if it was 
3826  * installed.
3827  *
3828  * When @pad is not linked #GST_FLOW_NOT_LINKED is returned else this
3829  * function returns the result of gst_pad_get_range() on the peer pad.
3830  * See gst_pad_get_range() for a list of return values and for the
3831  * semantics of the arguments of this function.
3832  *
3833  * @buffer's caps must either be unset or the same as what is already configured
3834  * on @pad. Renegotiation within a running pull-mode pipeline is not supported.
3835  *
3836  * Returns: a #GstFlowReturn from the peer pad.
3837  * When this function returns #GST_FLOW_OK, @buffer will contain a valid
3838  * #GstBuffer that should be freed with gst_buffer_unref() after usage.
3839  * @buffer may not be used or freed when any other return value than 
3840  * #GST_FLOW_OK is returned.
3841  *
3842  * MT safe.
3843  */
3844 GstFlowReturn
3845 gst_pad_pull_range (GstPad * pad, guint64 offset, guint size,
3846     GstBuffer ** buffer)
3847 {
3848   GstPad *peer;
3849   GstFlowReturn ret;
3850   gboolean emit_signal;
3851
3852   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3853   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK,
3854       GST_FLOW_ERROR);
3855   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
3856
3857   GST_OBJECT_LOCK (pad);
3858
3859   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
3860     handle_pad_block (pad);
3861
3862   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3863     goto not_connected;
3864
3865   /* signal emision for the pad, peer has chance to emit when
3866    * we call _get_range() */
3867   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3868
3869   gst_object_ref (peer);
3870   GST_OBJECT_UNLOCK (pad);
3871
3872   ret = gst_pad_get_range (peer, offset, size, buffer);
3873
3874   gst_object_unref (peer);
3875
3876   /* can only fire the signal if we have a valid buffer */
3877   if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
3878     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
3879       goto dropping;
3880   }
3881
3882   if (G_LIKELY (ret == GST_FLOW_OK)) {
3883     GstCaps *caps;
3884     gboolean caps_changed;
3885
3886     GST_OBJECT_LOCK (pad);
3887     /* Before pushing the buffer to the peer pad, ensure that caps 
3888      * are set on this pad */
3889     caps = GST_BUFFER_CAPS (*buffer);
3890     caps_changed = caps && caps != GST_PAD_CAPS (pad);
3891     GST_OBJECT_UNLOCK (pad);
3892
3893     /* we got a new datatype on the pad, see if it can handle it */
3894     if (G_UNLIKELY (caps_changed))
3895       goto not_negotiated;
3896   }
3897
3898   return ret;
3899
3900   /* ERROR recovery here */
3901 not_connected:
3902   {
3903     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3904         "pulling range, but it was not linked");
3905     GST_OBJECT_UNLOCK (pad);
3906     return GST_FLOW_NOT_LINKED;
3907   }
3908 dropping:
3909   {
3910     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3911         "Dropping data after FALSE probe return");
3912     gst_buffer_unref (*buffer);
3913     *buffer = NULL;
3914     return GST_FLOW_UNEXPECTED;
3915   }
3916 not_negotiated:
3917   {
3918     /* ideally we want to use the commented-out code, but currently demuxers and
3919      * typefind do not follow part-negotiation.txt. When switching into pull
3920      * mode, typefind should probably return the found caps from getcaps(), and
3921      * demuxers should do the setcaps(). */
3922
3923 #if 0
3924     gst_buffer_unref (*buffer);
3925     *buffer = NULL;
3926     GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
3927         "pullrange returned buffer of different caps");
3928     return GST_FLOW_NOT_NEGOTIATED;
3929 #endif
3930     GST_CAT_DEBUG_OBJECT (GST_CAT_SCHEDULING, pad,
3931         "pullrange returned buffer of different caps");
3932     return ret;
3933   }
3934 }
3935
3936 /**
3937  * gst_pad_push_event:
3938  * @pad: a #GstPad to push the event to.
3939  * @event: the #GstEvent to send to the pad.
3940  *
3941  * Sends the event to the peer of the given pad. This function is
3942  * mainly used by elements to send events to their peer
3943  * elements.
3944  *
3945  * This function takes owership of the provided event so you should
3946  * gst_event_ref() it if you want to reuse the event after this call.
3947  *
3948  * Returns: TRUE if the event was handled.
3949  *
3950  * MT safe.
3951  */
3952 gboolean
3953 gst_pad_push_event (GstPad * pad, GstEvent * event)
3954 {
3955   GstPad *peerpad;
3956   gboolean result;
3957
3958   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3959   g_return_val_if_fail (event != NULL, FALSE);
3960   g_return_val_if_fail (GST_IS_EVENT (event), FALSE);
3961
3962   GST_LOG_OBJECT (pad, "event: %s", GST_EVENT_TYPE_NAME (event));
3963
3964   GST_OBJECT_LOCK (pad);
3965
3966   /* Two checks to be made:
3967    * . (un)set the FLUSHING flag for flushing events,
3968    * . handle pad blocking */
3969   switch (GST_EVENT_TYPE (event)) {
3970     case GST_EVENT_FLUSH_START:
3971       GST_PAD_SET_FLUSHING (pad);
3972
3973       if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
3974         /* flush start will have set the FLUSHING flag and will then
3975          * unlock all threads doing a GCond wait on the blocking pad. This
3976          * will typically unblock the STREAMING thread blocked on a pad. */
3977         GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-start, "
3978             "doing block signal.");
3979         GST_PAD_BLOCK_BROADCAST (pad);
3980         goto flushed;
3981       }
3982       break;
3983     case GST_EVENT_FLUSH_STOP:
3984       GST_PAD_UNSET_FLUSHING (pad);
3985
3986       /* if we are blocked, flush away the FLUSH_STOP event */
3987       if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
3988         GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-stop");
3989         goto flushed;
3990       }
3991       break;
3992     default:
3993       while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
3994         /* block the event as long as the pad is blocked */
3995         if (handle_pad_block (pad) != GST_FLOW_OK)
3996           goto flushed;
3997       }
3998       break;
3999   }
4000
4001   if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
4002     GST_OBJECT_UNLOCK (pad);
4003
4004     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (event)))
4005       goto dropping;
4006
4007     GST_OBJECT_LOCK (pad);
4008   }
4009   peerpad = GST_PAD_PEER (pad);
4010   if (peerpad == NULL)
4011     goto not_linked;
4012
4013   GST_LOG_OBJECT (pad, "sending event %s to peerpad %" GST_PTR_FORMAT,
4014       GST_EVENT_TYPE_NAME (event), peerpad);
4015   gst_object_ref (peerpad);
4016   GST_OBJECT_UNLOCK (pad);
4017
4018   result = gst_pad_send_event (peerpad, event);
4019
4020   /* Note: we gave away ownership of the event at this point */
4021   GST_LOG_OBJECT (pad, "sent event to peerpad %" GST_PTR_FORMAT, peerpad);
4022   gst_object_unref (peerpad);
4023
4024   return result;
4025
4026   /* ERROR handling */
4027 dropping:
4028   {
4029     GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
4030     gst_event_unref (event);
4031     return FALSE;
4032   }
4033 not_linked:
4034   {
4035     GST_DEBUG_OBJECT (pad, "Dropping event because pad is not linked");
4036     gst_event_unref (event);
4037     GST_OBJECT_UNLOCK (pad);
4038     return FALSE;
4039   }
4040 flushed:
4041   {
4042     GST_DEBUG_OBJECT (pad,
4043         "Not forwarding event since we're flushing and blocking");
4044     gst_event_unref (event);
4045     GST_OBJECT_UNLOCK (pad);
4046     return TRUE;
4047   }
4048 }
4049
4050 /**
4051  * gst_pad_send_event:
4052  * @pad: a #GstPad to send the event to.
4053  * @event: the #GstEvent to send to the pad.
4054  *
4055  * Sends the event to the pad. This function can be used
4056  * by applications to send events in the pipeline.
4057  *
4058  * If @pad is a source pad, @event should be an upstream event. If @pad is a
4059  * sink pad, @event should be a downstream event. For example, you would not
4060  * send a #GST_EVENT_EOS on a src pad; EOS events only propagate downstream.
4061  * Furthermore, some downstream events have to be serialized with data flow,
4062  * like EOS, while some can travel out-of-band, like #GST_EVENT_FLUSH_START. If
4063  * the event needs to be serialized with data flow, this function will take the
4064  * pad's stream lock while calling its event function.
4065  *
4066  * To find out whether an event type is upstream, downstream, or downstream and
4067  * serialized, see #GstEventTypeFlags, gst_event_type_get_flags(),
4068  * #GST_EVENT_IS_UPSTREAM, #GST_EVENT_IS_DOWNSTREAM, and
4069  * #GST_EVENT_IS_SERIALIZED. Note that in practice that an application or plugin
4070  * doesn't need to bother itself with this information; the core handles all
4071  * necessary locks and checks.
4072  *
4073  * This function takes owership of the provided event so you should
4074  * gst_event_ref() it if you want to reuse the event after this call.
4075  *
4076  * Returns: TRUE if the event was handled.
4077  */
4078 gboolean
4079 gst_pad_send_event (GstPad * pad, GstEvent * event)
4080 {
4081   gboolean result = FALSE;
4082   GstPadEventFunction eventfunc;
4083   gboolean serialized, need_unlock = FALSE;
4084
4085   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4086   g_return_val_if_fail (event != NULL, FALSE);
4087
4088   GST_OBJECT_LOCK (pad);
4089   if (GST_PAD_IS_SINK (pad)) {
4090     if (G_UNLIKELY (!GST_EVENT_IS_DOWNSTREAM (event)))
4091       goto wrong_direction;
4092     serialized = GST_EVENT_IS_SERIALIZED (event);
4093   } else if (GST_PAD_IS_SRC (pad)) {
4094     if (G_UNLIKELY (!GST_EVENT_IS_UPSTREAM (event)))
4095       goto wrong_direction;
4096     /* events on srcpad never are serialized */
4097     serialized = FALSE;
4098   } else
4099     goto unknown_direction;
4100
4101   if (G_UNLIKELY (GST_EVENT_SRC (event) == NULL)) {
4102     GST_LOG_OBJECT (pad, "event had no source, setting pad as event source");
4103     GST_EVENT_SRC (event) = gst_object_ref (pad);
4104   }
4105
4106   /* pad signals */
4107   if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
4108     GST_OBJECT_UNLOCK (pad);
4109
4110     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (event)))
4111       goto dropping;
4112
4113     GST_OBJECT_LOCK (pad);
4114   }
4115
4116   switch (GST_EVENT_TYPE (event)) {
4117     case GST_EVENT_FLUSH_START:
4118       GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad,
4119           "have event type %d (FLUSH_START)", GST_EVENT_TYPE (event));
4120
4121       /* can't even accept a flush begin event when flushing */
4122       if (GST_PAD_IS_FLUSHING (pad))
4123         goto flushing;
4124       GST_PAD_SET_FLUSHING (pad);
4125       GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "set flush flag");
4126       break;
4127     case GST_EVENT_FLUSH_STOP:
4128       GST_PAD_UNSET_FLUSHING (pad);
4129       GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "cleared flush flag");
4130       GST_OBJECT_UNLOCK (pad);
4131       /* grab stream lock */
4132       GST_PAD_STREAM_LOCK (pad);
4133       need_unlock = TRUE;
4134       GST_OBJECT_LOCK (pad);
4135       break;
4136     default:
4137       GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "have event type %s",
4138           GST_EVENT_TYPE_NAME (event));
4139
4140       /* make this a little faster, no point in grabbing the lock
4141        * if the pad is allready flushing. */
4142       if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4143         goto flushing;
4144
4145       if (serialized) {
4146         /* lock order: STREAM_LOCK, LOCK, recheck flushing. */
4147         GST_OBJECT_UNLOCK (pad);
4148         GST_PAD_STREAM_LOCK (pad);
4149         need_unlock = TRUE;
4150         GST_OBJECT_LOCK (pad);
4151         if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4152           goto flushing;
4153       }
4154       break;
4155   }
4156   if (G_UNLIKELY ((eventfunc = GST_PAD_EVENTFUNC (pad)) == NULL))
4157     goto no_function;
4158
4159   GST_OBJECT_UNLOCK (pad);
4160
4161   result = eventfunc (pad, event);
4162
4163   if (need_unlock)
4164     GST_PAD_STREAM_UNLOCK (pad);
4165
4166   return result;
4167
4168   /* ERROR handling */
4169 wrong_direction:
4170   {
4171     g_warning ("pad %s:%s sending %s event in wrong direction",
4172         GST_DEBUG_PAD_NAME (pad), GST_EVENT_TYPE_NAME (event));
4173     GST_OBJECT_UNLOCK (pad);
4174     gst_event_unref (event);
4175     return FALSE;
4176   }
4177 unknown_direction:
4178   {
4179     g_warning ("pad %s:%s has invalid direction", GST_DEBUG_PAD_NAME (pad));
4180     GST_OBJECT_UNLOCK (pad);
4181     gst_event_unref (event);
4182     return FALSE;
4183   }
4184 no_function:
4185   {
4186     g_warning ("pad %s:%s has no event handler, file a bug.",
4187         GST_DEBUG_PAD_NAME (pad));
4188     GST_OBJECT_UNLOCK (pad);
4189     gst_event_unref (event);
4190     return FALSE;
4191   }
4192 flushing:
4193   {
4194     GST_OBJECT_UNLOCK (pad);
4195     if (need_unlock)
4196       GST_PAD_STREAM_UNLOCK (pad);
4197     GST_CAT_INFO_OBJECT (GST_CAT_EVENT, pad,
4198         "Received event on flushing pad. Discarding");
4199     gst_event_unref (event);
4200     return FALSE;
4201   }
4202 dropping:
4203   {
4204     GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
4205     gst_event_unref (event);
4206     return FALSE;
4207   }
4208 }
4209
4210 /**
4211  * gst_pad_set_element_private:
4212  * @pad: the #GstPad to set the private data of.
4213  * @priv: The private data to attach to the pad.
4214  *
4215  * Set the given private data gpointer on the pad.
4216  * This function can only be used by the element that owns the pad.
4217  * No locking is performed in this function.
4218  */
4219 void
4220 gst_pad_set_element_private (GstPad * pad, gpointer priv)
4221 {
4222   pad->element_private = priv;
4223 }
4224
4225 /**
4226  * gst_pad_get_element_private:
4227  * @pad: the #GstPad to get the private data of.
4228  *
4229  * Gets the private data of a pad.
4230  * No locking is performed in this function.
4231  *
4232  * Returns: a #gpointer to the private data.
4233  */
4234 gpointer
4235 gst_pad_get_element_private (GstPad * pad)
4236 {
4237   return pad->element_private;
4238 }
4239
4240 /**
4241  * gst_pad_start_task:
4242  * @pad: the #GstPad to start the task of
4243  * @func: the task function to call
4244  * @data: data passed to the task function
4245  *
4246  * Starts a task that repeatedly calls @func with @data. This function
4247  * is mostly used in pad activation functions to start the dataflow.
4248  * The #GST_PAD_STREAM_LOCK of @pad will automatically be acquired
4249  * before @func is called.
4250  *
4251  * Returns: a %TRUE if the task could be started.
4252  */
4253 gboolean
4254 gst_pad_start_task (GstPad * pad, GstTaskFunction func, gpointer data)
4255 {
4256   GstTask *task;
4257
4258   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4259   g_return_val_if_fail (func != NULL, FALSE);
4260
4261   GST_DEBUG_OBJECT (pad, "start task");
4262
4263   GST_OBJECT_LOCK (pad);
4264   task = GST_PAD_TASK (pad);
4265   if (task == NULL) {
4266     task = gst_task_create (func, data);
4267     gst_task_set_lock (task, GST_PAD_GET_STREAM_LOCK (pad));
4268     GST_PAD_TASK (pad) = task;
4269     GST_DEBUG_OBJECT (pad, "created task");
4270   }
4271   gst_task_start (task);
4272   GST_OBJECT_UNLOCK (pad);
4273
4274   return TRUE;
4275 }
4276
4277 /**
4278  * gst_pad_pause_task:
4279  * @pad: the #GstPad to pause the task of
4280  *
4281  * Pause the task of @pad. This function will also make sure that the
4282  * function executed by the task will effectively stop.
4283  *
4284  * Returns: a TRUE if the task could be paused or FALSE when the pad
4285  * has no task.
4286  */
4287 gboolean
4288 gst_pad_pause_task (GstPad * pad)
4289 {
4290   GstTask *task;
4291
4292   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4293
4294   GST_DEBUG_OBJECT (pad, "pause task");
4295
4296   GST_OBJECT_LOCK (pad);
4297   task = GST_PAD_TASK (pad);
4298   if (task == NULL)
4299     goto no_task;
4300   gst_task_pause (task);
4301   GST_OBJECT_UNLOCK (pad);
4302
4303   GST_PAD_STREAM_LOCK (pad);
4304   GST_PAD_STREAM_UNLOCK (pad);
4305
4306   return TRUE;
4307
4308 no_task:
4309   {
4310     GST_DEBUG_OBJECT (pad, "pad has no task");
4311     GST_OBJECT_UNLOCK (pad);
4312     return FALSE;
4313   }
4314 }
4315
4316 /**
4317  * gst_pad_stop_task:
4318  * @pad: the #GstPad to stop the task of
4319  *
4320  * Stop the task of @pad. This function will also make sure that the
4321  * function executed by the task will effectively stop if not called
4322  * from the GstTaskFunction.
4323  *
4324  * This function will deadlock if called from the GstTaskFunction of
4325  * the task. Use gst_task_pause() instead.
4326  *
4327  * Regardless of whether the pad has a task, the stream lock is acquired and
4328  * released so as to ensure that streaming through this pad has finished.
4329  *
4330  * Returns: a TRUE if the task could be stopped or FALSE on error.
4331  */
4332 gboolean
4333 gst_pad_stop_task (GstPad * pad)
4334 {
4335   GstTask *task;
4336
4337   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4338
4339   GST_DEBUG_OBJECT (pad, "stop task");
4340
4341   GST_OBJECT_LOCK (pad);
4342   task = GST_PAD_TASK (pad);
4343   if (task == NULL)
4344     goto no_task;
4345   GST_PAD_TASK (pad) = NULL;
4346   gst_task_stop (task);
4347   GST_OBJECT_UNLOCK (pad);
4348
4349   GST_PAD_STREAM_LOCK (pad);
4350   GST_PAD_STREAM_UNLOCK (pad);
4351
4352   if (!gst_task_join (task))
4353     goto join_failed;
4354
4355   gst_object_unref (task);
4356
4357   return TRUE;
4358
4359 no_task:
4360   {
4361     GST_DEBUG_OBJECT (pad, "no task");
4362     GST_OBJECT_UNLOCK (pad);
4363
4364     GST_PAD_STREAM_LOCK (pad);
4365     GST_PAD_STREAM_UNLOCK (pad);
4366
4367     /* this is not an error */
4368     return TRUE;
4369   }
4370 join_failed:
4371   {
4372     /* this is bad, possibly the application tried to join the task from
4373      * the task's thread. We install the task again so that it will be stopped
4374      * again from the right thread next time hopefully. */
4375     GST_OBJECT_LOCK (pad);
4376     GST_DEBUG_OBJECT (pad, "join failed");
4377     /* we can only install this task if there was no other task */
4378     if (GST_PAD_TASK (pad) == NULL)
4379       GST_PAD_TASK (pad) = task;
4380     GST_OBJECT_UNLOCK (pad);
4381
4382     return FALSE;
4383   }
4384 }