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