gst/gstpad.c

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