gst/gstpad.c

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