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