gst/gstpad.c

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