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() and
  58  * gst_pad_push_event().
  59  *
  60  * Last reviewed on 2006-07-06 (0.10.9)
  61  */
  62
  63 #include "gst_private.h"
  64
  65 #include "gstpad.h"
  66 #include "gstpadtemplate.h"
  67 #include "gstenumtypes.h"
  68 #include "gstmarshal.h"
  69 #include "gstutils.h"
  70 #include "gstinfo.h"
  71 #include "gsterror.h"
  72 #include "gstvalue.h"
  73 #include "glib-compat-private.h"
  74
  75 GST_DEBUG_CATEGORY_STATIC (debug_dataflow);
  76 #define GST_CAT_DEFAULT GST_CAT_PADS
  77
  78 /* Pad signals and args */
  79 enum
  80 {
  81   PAD_LINKED,
  82   PAD_UNLINKED,
  83   PAD_REQUEST_LINK,
  84   PAD_HAVE_DATA,
  85   /* FILL ME */
  86   LAST_SIGNAL
  87 };
  88
  89 enum
  90 {
  91   PAD_PROP_0,
  92   PAD_PROP_CAPS,
  93   PAD_PROP_DIRECTION,
  94   PAD_PROP_TEMPLATE,
  95   /* FILL ME */
  96 };
  97
  98 typedef struct _GstPadPushCache GstPadPushCache;
  99
 100 struct _GstPadPushCache
 101 {
 102   GstPad *peer;                 /* reffed peer pad */
 103   GstCaps *caps;                /* caps for this link */
 104   GstPadChainFunction chainfunc;
 105 };
 106
 107 static GstPadPushCache _pad_cache_invalid = { NULL, };
 108
 109 #define PAD_CACHE_INVALID (&_pad_cache_invalid)
 110
 111 #define GST_PAD_GET_PRIVATE(obj)  \
 112    (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GST_TYPE_PAD, GstPadPrivate))
 113
 114 #define GST_PAD_CHAINLISTFUNC(pad) ((pad)->abidata.ABI.priv->chainlistfunc)
 115
 116 struct _GstPadPrivate
 117 {
 118   GstPadChainListFunction chainlistfunc;
 119
 120   GstPadPushCache *cache_ptr;
 121 };
 122
 123 static void gst_pad_dispose (GObject * object);
 124 static void gst_pad_finalize (GObject * object);
 125 static void gst_pad_set_property (GObject * object, guint prop_id,
 126     const GValue * value, GParamSpec * pspec);
 127 static void gst_pad_get_property (GObject * object, guint prop_id,
 128     GValue * value, GParamSpec * pspec);
 129
 130 static GstFlowReturn handle_pad_block (GstPad * pad);
 131 static GstCaps *gst_pad_get_caps_unlocked (GstPad * pad);
 132 static void gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ);
 133 static gboolean gst_pad_activate_default (GstPad * pad);
 134 static gboolean gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps);
 135
 136 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
 137 #ifdef GST_DISABLE_DEPRECATED
 138 #include <libxml/parser.h>
 139 #endif
 140 static xmlNodePtr gst_pad_save_thyself (GstObject * object, xmlNodePtr parent);
 141 void gst_pad_load_and_link (xmlNodePtr self, GstObject * parent);
 142 #endif
 143
 144 /* Some deprecated stuff that we need inside here for
 145  * backwards compatibility */
 146 #ifdef GST_DISABLE_DEPRECATED
 147 #ifndef GST_REMOVE_DEPRECATED
 148 #define GST_PAD_INTLINKFUNC(pad)        (GST_PAD_CAST(pad)->intlinkfunc)
 149 GList *gst_pad_get_internal_links_default (GstPad * pad);
 150 #endif
 151 #endif
 152
 153 static GstObjectClass *parent_class = NULL;
 154 static guint gst_pad_signals[LAST_SIGNAL] = { 0 };
 155
 156 static GParamSpec *pspec_caps = NULL;
 157
 158 /* quarks for probe signals */
 159 static GQuark buffer_quark;
 160 static GQuark event_quark;
 161
 162 typedef struct
 163 {
 164   const gint ret;
 165   const gchar *name;
 166   GQuark quark;
 167 } GstFlowQuarks;
 168
 169 static GstFlowQuarks flow_quarks[] = {
 170   {GST_FLOW_CUSTOM_SUCCESS, "custom-success", 0},
 171   {GST_FLOW_RESEND, "resend", 0},
 172   {GST_FLOW_OK, "ok", 0},
 173   {GST_FLOW_NOT_LINKED, "not-linked", 0},
 174   {GST_FLOW_WRONG_STATE, "wrong-state", 0},
 175   {GST_FLOW_UNEXPECTED, "unexpected", 0},
 176   {GST_FLOW_NOT_NEGOTIATED, "not-negotiated", 0},
 177   {GST_FLOW_ERROR, "error", 0},
 178   {GST_FLOW_NOT_SUPPORTED, "not-supported", 0},
 179   {GST_FLOW_CUSTOM_ERROR, "custom-error", 0}
 180 };
 181
 182 /**
 183  * gst_flow_get_name:
 184  * @ret: a #GstFlowReturn to get the name of.
 185  *
 186  * Gets a string representing the given flow return.
 187  *
 188  * Returns: a static string with the name of the flow return.
 189  */
 190 G_CONST_RETURN gchar *
 191 gst_flow_get_name (GstFlowReturn ret)
 192 {
 193   gint i;
 194
 195   ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
 196
 197   for (i = 0; i < G_N_ELEMENTS (flow_quarks); i++) {
 198     if (ret == flow_quarks[i].ret)
 199       return flow_quarks[i].name;
 200   }
 201   return "unknown";
 202 }
 203
 204 /**
 205  * gst_flow_to_quark:
 206  * @ret: a #GstFlowReturn to get the quark of.
 207  *
 208  * Get the unique quark for the given GstFlowReturn.
 209  *
 210  * Returns: the quark associated with the flow return or 0 if an
 211  * invalid return was specified.
 212  */
 213 GQuark
 214 gst_flow_to_quark (GstFlowReturn ret)
 215 {
 216   gint i;
 217
 218   ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
 219
 220   for (i = 0; i < G_N_ELEMENTS (flow_quarks); i++) {
 221     if (ret == flow_quarks[i].ret)
 222       return flow_quarks[i].quark;
 223   }
 224   return 0;
 225 }
 226
 227 #define _do_init \
 228 { \
 229   gint i; \
 230   \
 231   buffer_quark = g_quark_from_static_string ("buffer"); \
 232   event_quark = g_quark_from_static_string ("event"); \
 233   \
 234   for (i = 0; i < G_N_ELEMENTS (flow_quarks); i++) {                    \
 235     flow_quarks[i].quark = g_quark_from_static_string (flow_quarks[i].name); \
 236   } \
 237   \
 238   GST_DEBUG_CATEGORY_INIT (debug_dataflow, "GST_DATAFLOW", \
 239       GST_DEBUG_BOLD | GST_DEBUG_FG_GREEN, "dataflow inside pads"); \
 240 }
 241
 242 G_DEFINE_TYPE_WITH_CODE (GstPad, gst_pad, GST_TYPE_OBJECT, _do_init);
 243
 244 static gboolean
 245 _gst_do_pass_data_accumulator (GSignalInvocationHint * ihint,
 246     GValue * return_accu, const GValue * handler_return, gpointer dummy)
 247 {
 248   gboolean ret = g_value_get_boolean (handler_return);
 249
 250   GST_DEBUG ("accumulated %d", ret);
 251   g_value_set_boolean (return_accu, ret);
 252
 253   return ret;
 254 }
 255
 256 static gboolean
 257 default_have_data (GstPad * pad, GstMiniObject * o)
 258 {
 259   return TRUE;
 260 }
 261
 262 static void
 263 gst_pad_class_init (GstPadClass * klass)
 264 {
 265   GObjectClass *gobject_class;
 266   GstObjectClass *gstobject_class;
 267
 268   gobject_class = G_OBJECT_CLASS (klass);
 269   gstobject_class = GST_OBJECT_CLASS (klass);
 270
 271   g_type_class_add_private (klass, sizeof (GstPadPrivate));
 272
 273   parent_class = g_type_class_peek_parent (klass);
 274
 275   gobject_class->dispose = gst_pad_dispose;
 276   gobject_class->finalize = gst_pad_finalize;
 277   gobject_class->set_property = gst_pad_set_property;
 278   gobject_class->get_property = gst_pad_get_property;
 279
 280   /**
 281    * GstPad::linked:
 282    * @pad: the pad that emitted the signal
 283    * @peer: the peer pad that has been connected
 284    *
 285    * Signals that a pad has been linked to the peer pad.
 286    */
 287   gst_pad_signals[PAD_LINKED] =
 288       g_signal_new ("linked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 289       G_STRUCT_OFFSET (GstPadClass, linked), NULL, NULL,
 290       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
 291   /**
 292    * GstPad::unlinked:
 293    * @pad: the pad that emitted the signal
 294    * @peer: the peer pad that has been disconnected
 295    *
 296    * Signals that a pad has been unlinked from the peer pad.
 297    */
 298   gst_pad_signals[PAD_UNLINKED] =
 299       g_signal_new ("unlinked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 300       G_STRUCT_OFFSET (GstPadClass, unlinked), NULL, NULL,
 301       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
 302   /**
 303    * GstPad::request-link:
 304    * @pad: the pad that emitted the signal
 305    * @peer: the peer pad for which a connection is requested
 306    *
 307    * Signals that a pad connection has been requested.
 308    */
 309   gst_pad_signals[PAD_REQUEST_LINK] =
 310       g_signal_new ("request-link", G_TYPE_FROM_CLASS (klass),
 311       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstPadClass, request_link), NULL,
 312       NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 0);
 313
 314   /**
 315    * GstPad::have-data:
 316    * @pad: the pad that emitted the signal
 317    * @mini_obj: new data
 318    *
 319    * Signals that new data is available on the pad. This signal is used
 320    * internally for implementing pad probes.
 321    * See gst_pad_add_*_probe functions.
 322    *
 323    * Returns: %TRUE to keep the data, %FALSE to drop it
 324    */
 325   gst_pad_signals[PAD_HAVE_DATA] =
 326       g_signal_new ("have-data", G_TYPE_FROM_CLASS (klass),
 327       G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
 328       G_STRUCT_OFFSET (GstPadClass, have_data),
 329       _gst_do_pass_data_accumulator,
 330       NULL, gst_marshal_BOOLEAN__POINTER, G_TYPE_BOOLEAN, 1,
 331       GST_TYPE_MINI_OBJECT);
 332
 333   pspec_caps = g_param_spec_boxed ("caps", "Caps",
 334       "The capabilities of the pad", GST_TYPE_CAPS,
 335       G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 336   g_object_class_install_property (gobject_class, PAD_PROP_CAPS, pspec_caps);
 337
 338   g_object_class_install_property (gobject_class, PAD_PROP_DIRECTION,
 339       g_param_spec_enum ("direction", "Direction", "The direction of the pad",
 340           GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,
 341           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 342   /* FIXME, Make G_PARAM_CONSTRUCT_ONLY when we fix ghostpads. */
 343   g_object_class_install_property (gobject_class, PAD_PROP_TEMPLATE,
 344       g_param_spec_object ("template", "Template",
 345           "The GstPadTemplate of this pad", GST_TYPE_PAD_TEMPLATE,
 346           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 347
 348 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
 349   gstobject_class->save_thyself =
 350       ((gpointer (*)(GstObject * object,
 351               gpointer self)) * GST_DEBUG_FUNCPTR (gst_pad_save_thyself));
 352 #endif
 353   gstobject_class->path_string_separator = ".";
 354
 355   /* Register common function pointer descriptions */
 356   GST_DEBUG_REGISTER_FUNCPTR (gst_pad_activate_default);
 357   GST_DEBUG_REGISTER_FUNCPTR (gst_pad_event_default);
 358   GST_DEBUG_REGISTER_FUNCPTR (gst_pad_get_query_types_default);
 359   GST_DEBUG_REGISTER_FUNCPTR (gst_pad_query_default);
 360 #ifndef GST_REMOVE_DEPRECATED
 361   GST_DEBUG_REGISTER_FUNCPTR (gst_pad_get_internal_links_default);
 362 #endif
 363   GST_DEBUG_REGISTER_FUNCPTR (gst_pad_iterate_internal_links_default);
 364   GST_DEBUG_REGISTER_FUNCPTR (gst_pad_acceptcaps_default);
 365
 366   klass->have_data = default_have_data;
 367 }
 368
 369 static void
 370 gst_pad_init (GstPad * pad)
 371 {
 372   pad->abidata.ABI.priv = GST_PAD_GET_PRIVATE (pad);
 373
 374   GST_PAD_DIRECTION (pad) = GST_PAD_UNKNOWN;
 375   GST_PAD_PEER (pad) = NULL;
 376
 377   GST_PAD_CHAINFUNC (pad) = NULL;
 378
 379   GST_PAD_LINKFUNC (pad) = NULL;
 380
 381   GST_PAD_CAPS (pad) = NULL;
 382   GST_PAD_GETCAPSFUNC (pad) = NULL;
 383
 384   GST_PAD_ACTIVATEFUNC (pad) = gst_pad_activate_default;
 385   GST_PAD_EVENTFUNC (pad) = gst_pad_event_default;
 386   GST_PAD_QUERYTYPEFUNC (pad) = gst_pad_get_query_types_default;
 387   GST_PAD_QUERYFUNC (pad) = gst_pad_query_default;
 388 #ifndef GST_REMOVE_DEPRECATED
 389   GST_PAD_INTLINKFUNC (pad) = gst_pad_get_internal_links_default;
 390 #endif
 391   GST_PAD_ITERINTLINKFUNC (pad) = gst_pad_iterate_internal_links_default;
 392
 393   GST_PAD_ACCEPTCAPSFUNC (pad) = gst_pad_acceptcaps_default;
 394
 395   pad->do_buffer_signals = 0;
 396   pad->do_event_signals = 0;
 397
 398   GST_PAD_SET_FLUSHING (pad);
 399
 400   pad->preroll_lock = g_mutex_new ();
 401   pad->preroll_cond = g_cond_new ();
 402
 403   /* FIXME 0.11: Store this directly in the instance struct */
 404   pad->stream_rec_lock = g_slice_new (GStaticRecMutex);
 405   g_static_rec_mutex_init (pad->stream_rec_lock);
 406
 407   pad->block_cond = g_cond_new ();
 408 }
 409
 410 static void
 411 gst_pad_dispose (GObject * object)
 412 {
 413   GstPad *pad = GST_PAD_CAST (object);
 414   GstPad *peer;
 415
 416   GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, pad, "dispose");
 417
 418   /* unlink the peer pad */
 419   if ((peer = gst_pad_get_peer (pad))) {
 420     /* window for MT unsafeness, someone else could unlink here
 421      * and then we call unlink with wrong pads. The unlink
 422      * function would catch this and safely return failed. */
 423     if (GST_PAD_IS_SRC (pad))
 424       gst_pad_unlink (pad, peer);
 425     else
 426       gst_pad_unlink (peer, pad);
 427
 428     gst_object_unref (peer);
 429   }
 430
 431   /* clear the caps */
 432   gst_caps_replace (&GST_PAD_CAPS (pad), NULL);
 433
 434   gst_pad_set_pad_template (pad, NULL);
 435
 436   if (pad->block_destroy_data && pad->block_data) {
 437     pad->block_destroy_data (pad->block_data);
 438     pad->block_data = NULL;
 439   }
 440
 441   G_OBJECT_CLASS (parent_class)->dispose (object);
 442 }
 443
 444 static void
 445 gst_pad_finalize (GObject * object)
 446 {
 447   GstPad *pad = GST_PAD_CAST (object);
 448   GstTask *task;
 449
 450   /* in case the task is still around, clean it up */
 451   if ((task = GST_PAD_TASK (pad))) {
 452     gst_task_join (task);
 453     GST_PAD_TASK (pad) = NULL;
 454     gst_object_unref (task);
 455   }
 456
 457   if (pad->stream_rec_lock) {
 458     g_static_rec_mutex_free (pad->stream_rec_lock);
 459     g_slice_free (GStaticRecMutex, pad->stream_rec_lock);
 460     pad->stream_rec_lock = NULL;
 461   }
 462   if (pad->preroll_lock) {
 463     g_mutex_free (pad->preroll_lock);
 464     g_cond_free (pad->preroll_cond);
 465     pad->preroll_lock = NULL;
 466     pad->preroll_cond = NULL;
 467   }
 468   if (pad->block_cond) {
 469     g_cond_free (pad->block_cond);
 470     pad->block_cond = NULL;
 471   }
 472
 473   G_OBJECT_CLASS (parent_class)->finalize (object);
 474 }
 475
 476 static void
 477 gst_pad_set_property (GObject * object, guint prop_id,
 478     const GValue * value, GParamSpec * pspec)
 479 {
 480   g_return_if_fail (GST_IS_PAD (object));
 481
 482   switch (prop_id) {
 483     case PAD_PROP_DIRECTION:
 484       GST_PAD_DIRECTION (object) = g_value_get_enum (value);
 485       break;
 486     case PAD_PROP_TEMPLATE:
 487       gst_pad_set_pad_template (GST_PAD_CAST (object),
 488           (GstPadTemplate *) g_value_get_object (value));
 489       break;
 490     default:
 491       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 492       break;
 493   }
 494 }
 495
 496 static void
 497 gst_pad_get_property (GObject * object, guint prop_id,
 498     GValue * value, GParamSpec * pspec)
 499 {
 500   g_return_if_fail (GST_IS_PAD (object));
 501
 502   switch (prop_id) {
 503     case PAD_PROP_CAPS:
 504       GST_OBJECT_LOCK (object);
 505       g_value_set_boxed (value, GST_PAD_CAPS (object));
 506       GST_OBJECT_UNLOCK (object);
 507       break;
 508     case PAD_PROP_DIRECTION:
 509       g_value_set_enum (value, GST_PAD_DIRECTION (object));
 510       break;
 511     case PAD_PROP_TEMPLATE:
 512       g_value_set_object (value, GST_PAD_PAD_TEMPLATE (object));
 513       break;
 514     default:
 515       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 516       break;
 517   }
 518 }
 519
 520 /**
 521  * gst_pad_new:
 522  * @name: the name of the new pad.
 523  * @direction: the #GstPadDirection of the pad.
 524  *
 525  * Creates a new pad with the given name in the given direction.
 526  * If name is NULL, a guaranteed unique name (across all pads)
 527  * will be assigned.
 528  * This function makes a copy of the name so you can safely free the name.
 529  *
 530  * Returns: a new #GstPad, or NULL in case of an error.
 531  *
 532  * MT safe.
 533  */
 534 GstPad *
 535 gst_pad_new (const gchar * name, GstPadDirection direction)
 536 {
 537   return g_object_new (GST_TYPE_PAD,
 538       "name", name, "direction", direction, NULL);
 539 }
 540
 541 /**
 542  * gst_pad_new_from_template:
 543  * @templ: the pad template to use
 544  * @name: the name of the element
 545  *
 546  * Creates a new pad with the given name from the given template.
 547  * If name is NULL, a guaranteed unique name (across all pads)
 548  * will be assigned.
 549  * This function makes a copy of the name so you can safely free the name.
 550  *
 551  * Returns: a new #GstPad, or NULL in case of an error.
 552  */
 553 GstPad *
 554 gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name)
 555 {
 556   g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
 557
 558   return g_object_new (GST_TYPE_PAD,
 559       "name", name, "direction", templ->direction, "template", templ, NULL);
 560 }
 561
 562 /**
 563  * gst_pad_new_from_static_template:
 564  * @templ: the #GstStaticPadTemplate to use
 565  * @name: the name of the element
 566  *
 567  * Creates a new pad with the given name from the given static template.
 568  * If name is NULL, a guaranteed unique name (across all pads)
 569  * will be assigned.
 570  * This function makes a copy of the name so you can safely free the name.
 571  *
 572  * Returns: a new #GstPad, or NULL in case of an error.
 573  */
 574 GstPad *
 575 gst_pad_new_from_static_template (GstStaticPadTemplate * templ,
 576     const gchar * name)
 577 {
 578   GstPad *pad;
 579   GstPadTemplate *template;
 580
 581   template = gst_static_pad_template_get (templ);
 582   pad = gst_pad_new_from_template (template, name);
 583   gst_object_unref (template);
 584   return pad;
 585 }
 586
 587 /**
 588  * gst_pad_get_direction:
 589  * @pad: a #GstPad to get the direction of.
 590  *
 591  * Gets the direction of the pad. The direction of the pad is
 592  * decided at construction time so this function does not take
 593  * the LOCK.
 594  *
 595  * Returns: the #GstPadDirection of the pad.
 596  *
 597  * MT safe.
 598  */
 599 GstPadDirection
 600 gst_pad_get_direction (GstPad * pad)
 601 {
 602   GstPadDirection result;
 603
 604   /* PAD_UNKNOWN is a little silly but we need some sort of
 605    * error return value */
 606   g_return_val_if_fail (GST_IS_PAD (pad), GST_PAD_UNKNOWN);
 607
 608   result = GST_PAD_DIRECTION (pad);
 609
 610   return result;
 611 }
 612
 613 static gboolean
 614 gst_pad_activate_default (GstPad * pad)
 615 {
 616   return gst_pad_activate_push (pad, TRUE);
 617 }
 618
 619 static void
 620 pre_activate (GstPad * pad, GstActivateMode new_mode)
 621 {
 622   switch (new_mode) {
 623     case GST_ACTIVATE_PUSH:
 624     case GST_ACTIVATE_PULL:
 625       GST_OBJECT_LOCK (pad);
 626       GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE %d, unset flushing",
 627           new_mode);
 628       GST_PAD_UNSET_FLUSHING (pad);
 629       GST_PAD_ACTIVATE_MODE (pad) = new_mode;
 630       GST_OBJECT_UNLOCK (pad);
 631       break;
 632     case GST_ACTIVATE_NONE:
 633       GST_OBJECT_LOCK (pad);
 634       GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE NONE, set flushing");
 635       _priv_gst_pad_invalidate_cache (pad);
 636       GST_PAD_SET_FLUSHING (pad);
 637       GST_PAD_ACTIVATE_MODE (pad) = new_mode;
 638       /* unlock blocked pads so element can resume and stop */
 639       GST_PAD_BLOCK_BROADCAST (pad);
 640       GST_OBJECT_UNLOCK (pad);
 641       break;
 642   }
 643 }
 644
 645 static void
 646 post_activate (GstPad * pad, GstActivateMode new_mode)
 647 {
 648   switch (new_mode) {
 649     case GST_ACTIVATE_PUSH:
 650     case GST_ACTIVATE_PULL:
 651       /* nop */
 652       break;
 653     case GST_ACTIVATE_NONE:
 654       /* ensures that streaming stops */
 655       GST_PAD_STREAM_LOCK (pad);
 656       GST_DEBUG_OBJECT (pad, "stopped streaming");
 657       GST_PAD_STREAM_UNLOCK (pad);
 658       break;
 659   }
 660 }
 661
 662 /**
 663  * gst_pad_set_active:
 664  * @pad: the #GstPad to activate or deactivate.
 665  * @active: whether or not the pad should be active.
 666  *
 667  * Activates or deactivates the given pad.
 668  * Normally called from within core state change functions.
 669  *
 670  * If @active, makes sure the pad is active. If it is already active, either in
 671  * push or pull mode, just return. Otherwise dispatches to the pad's activate
 672  * function to perform the actual activation.
 673  *
 674  * If not @active, checks the pad's current mode and calls
 675  * gst_pad_activate_push() or gst_pad_activate_pull(), as appropriate, with a
 676  * FALSE argument.
 677  *
 678  * Returns: #TRUE if the operation was successful.
 679  *
 680  * MT safe.
 681  */
 682 gboolean
 683 gst_pad_set_active (GstPad * pad, gboolean active)
 684 {
 685   GstActivateMode old;
 686   gboolean ret = FALSE;
 687
 688   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 689
 690   GST_OBJECT_LOCK (pad);
 691   old = GST_PAD_ACTIVATE_MODE (pad);
 692   GST_OBJECT_UNLOCK (pad);
 693
 694   if (active) {
 695     switch (old) {
 696       case GST_ACTIVATE_PUSH:
 697         GST_DEBUG_OBJECT (pad, "activating pad from push");
 698         ret = TRUE;
 699         break;
 700       case GST_ACTIVATE_PULL:
 701         GST_DEBUG_OBJECT (pad, "activating pad from pull");
 702         ret = TRUE;
 703         break;
 704       case GST_ACTIVATE_NONE:
 705         GST_DEBUG_OBJECT (pad, "activating pad from none");
 706         ret = (GST_PAD_ACTIVATEFUNC (pad)) (pad);
 707         break;
 708     }
 709   } else {
 710     switch (old) {
 711       case GST_ACTIVATE_PUSH:
 712         GST_DEBUG_OBJECT (pad, "deactivating pad from push");
 713         ret = gst_pad_activate_push (pad, FALSE);
 714         break;
 715       case GST_ACTIVATE_PULL:
 716         GST_DEBUG_OBJECT (pad, "deactivating pad from pull");
 717         ret = gst_pad_activate_pull (pad, FALSE);
 718         break;
 719       case GST_ACTIVATE_NONE:
 720         GST_DEBUG_OBJECT (pad, "deactivating pad from none");
 721         ret = TRUE;
 722         break;
 723     }
 724   }
 725
 726   if (!ret) {
 727     GST_OBJECT_LOCK (pad);
 728     if (!active) {
 729       g_critical ("Failed to deactivate pad %s:%s, very bad",
 730           GST_DEBUG_PAD_NAME (pad));
 731     } else {
 732       GST_WARNING_OBJECT (pad, "Failed to activate pad");
 733     }
 734     GST_OBJECT_UNLOCK (pad);
 735   }
 736
 737   return ret;
 738 }
 739
 740 /**
 741  * gst_pad_activate_pull:
 742  * @pad: the #GstPad to activate or deactivate.
 743  * @active: whether or not the pad should be active.
 744  *
 745  * Activates or deactivates the given pad in pull mode via dispatching to the
 746  * pad's activatepullfunc. For use from within pad activation functions only.
 747  * When called on sink pads, will first proxy the call to the peer pad, which
 748  * is expected to activate its internally linked pads from within its
 749  * activate_pull function.
 750  *
 751  * If you don't know what this is, you probably don't want to call it.
 752  *
 753  * Returns: TRUE if the operation was successful.
 754  *
 755  * MT safe.
 756  */
 757 gboolean
 758 gst_pad_activate_pull (GstPad * pad, gboolean active)
 759 {
 760   GstActivateMode old, new;
 761   GstPad *peer;
 762
 763   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 764
 765   GST_OBJECT_LOCK (pad);
 766   old = GST_PAD_ACTIVATE_MODE (pad);
 767   GST_OBJECT_UNLOCK (pad);
 768
 769   if (active) {
 770     switch (old) {
 771       case GST_ACTIVATE_PULL:
 772         GST_DEBUG_OBJECT (pad, "activating pad from pull, was ok");
 773         goto was_ok;
 774       case GST_ACTIVATE_PUSH:
 775         GST_DEBUG_OBJECT (pad,
 776             "activating pad from push, deactivate push first");
 777         /* pad was activate in the wrong direction, deactivate it
 778          * and reactivate it in pull mode */
 779         if (G_UNLIKELY (!gst_pad_activate_push (pad, FALSE)))
 780           goto deactivate_failed;
 781         /* fallthrough, pad is deactivated now. */
 782       case GST_ACTIVATE_NONE:
 783         GST_DEBUG_OBJECT (pad, "activating pad from none");
 784         break;
 785     }
 786   } else {
 787     switch (old) {
 788       case GST_ACTIVATE_NONE:
 789         GST_DEBUG_OBJECT (pad, "deactivating pad from none, was ok");
 790         goto was_ok;
 791       case GST_ACTIVATE_PUSH:
 792         GST_DEBUG_OBJECT (pad, "deactivating pad from push, weird");
 793         /* pad was activated in the other direction, deactivate it
 794          * in push mode, this should not happen... */
 795         if (G_UNLIKELY (!gst_pad_activate_push (pad, FALSE)))
 796           goto deactivate_failed;
 797         /* everything is fine now */
 798         goto was_ok;
 799       case GST_ACTIVATE_PULL:
 800         GST_DEBUG_OBJECT (pad, "deactivating pad from pull");
 801         break;
 802     }
 803   }
 804
 805   if (gst_pad_get_direction (pad) == GST_PAD_SINK) {
 806     if ((peer = gst_pad_get_peer (pad))) {
 807       GST_DEBUG_OBJECT (pad, "calling peer");
 808       if (G_UNLIKELY (!gst_pad_activate_pull (peer, active)))
 809         goto peer_failed;
 810       gst_object_unref (peer);
 811     } else {
 812       /* there is no peer, this is only fatal when we activate. When we
 813        * deactivate, we must assume the application has unlinked the peer and
 814        * will deactivate it eventually. */
 815       if (active)
 816         goto not_linked;
 817       else
 818         GST_DEBUG_OBJECT (pad, "deactivating unlinked pad");
 819     }
 820   } else {
 821     if (G_UNLIKELY (GST_PAD_GETRANGEFUNC (pad) == NULL))
 822       goto failure;             /* Can't activate pull on a src without a
 823                                    getrange function */
 824   }
 825
 826   new = active ? GST_ACTIVATE_PULL : GST_ACTIVATE_NONE;
 827   pre_activate (pad, new);
 828
 829   if (GST_PAD_ACTIVATEPULLFUNC (pad)) {
 830     if (G_UNLIKELY (!GST_PAD_ACTIVATEPULLFUNC (pad) (pad, active)))
 831       goto failure;
 832   } else {
 833     /* can happen for sinks of passthrough elements */
 834   }
 835
 836   post_activate (pad, new);
 837
 838   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in pull mode",
 839       active ? "activated" : "deactivated");
 840
 841   return TRUE;
 842
 843 was_ok:
 844   {
 845     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in pull mode",
 846         active ? "activated" : "deactivated");
 847     return TRUE;
 848   }
 849 deactivate_failed:
 850   {
 851     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
 852         "failed to %s in switch to pull from mode %d",
 853         (active ? "activate" : "deactivate"), old);
 854     return FALSE;
 855   }
 856 peer_failed:
 857   {
 858     GST_OBJECT_LOCK (peer);
 859     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
 860         "activate_pull on peer (%s:%s) failed", GST_DEBUG_PAD_NAME (peer));
 861     GST_OBJECT_UNLOCK (peer);
 862     gst_object_unref (peer);
 863     return FALSE;
 864   }
 865 not_linked:
 866   {
 867     GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "can't activate unlinked sink "
 868         "pad in pull mode");
 869     return FALSE;
 870   }
 871 failure:
 872   {
 873     GST_OBJECT_LOCK (pad);
 874     GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in pull mode",
 875         active ? "activate" : "deactivate");
 876     _priv_gst_pad_invalidate_cache (pad);
 877     GST_PAD_SET_FLUSHING (pad);
 878     GST_PAD_ACTIVATE_MODE (pad) = old;
 879     GST_OBJECT_UNLOCK (pad);
 880     return FALSE;
 881   }
 882 }
 883
 884 /**
 885  * gst_pad_activate_push:
 886  * @pad: the #GstPad to activate or deactivate.
 887  * @active: whether the pad should be active or not.
 888  *
 889  * Activates or deactivates the given pad in push mode via dispatching to the
 890  * pad's activatepushfunc. For use from within pad activation functions only.
 891  *
 892  * If you don't know what this is, you probably don't want to call it.
 893  *
 894  * Returns: %TRUE if the operation was successful.
 895  *
 896  * MT safe.
 897  */
 898 gboolean
 899 gst_pad_activate_push (GstPad * pad, gboolean active)
 900 {
 901   GstActivateMode old, new;
 902
 903   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 904   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "trying to set %s in push mode",
 905       active ? "activated" : "deactivated");
 906
 907   GST_OBJECT_LOCK (pad);
 908   old = GST_PAD_ACTIVATE_MODE (pad);
 909   GST_OBJECT_UNLOCK (pad);
 910
 911   if (active) {
 912     switch (old) {
 913       case GST_ACTIVATE_PUSH:
 914         GST_DEBUG_OBJECT (pad, "activating pad from push, was ok");
 915         goto was_ok;
 916       case GST_ACTIVATE_PULL:
 917         GST_DEBUG_OBJECT (pad,
 918             "activating pad from push, deactivating pull first");
 919         /* pad was activate in the wrong direction, deactivate it
 920          * an reactivate it in push mode */
 921         if (G_UNLIKELY (!gst_pad_activate_pull (pad, FALSE)))
 922           goto deactivate_failed;
 923         /* fallthrough, pad is deactivated now. */
 924       case GST_ACTIVATE_NONE:
 925         GST_DEBUG_OBJECT (pad, "activating pad from none");
 926         break;
 927     }
 928   } else {
 929     switch (old) {
 930       case GST_ACTIVATE_NONE:
 931         GST_DEBUG_OBJECT (pad, "deactivating pad from none, was ok");
 932         goto was_ok;
 933       case GST_ACTIVATE_PULL:
 934         GST_DEBUG_OBJECT (pad, "deactivating pad from pull, weird");
 935         /* pad was activated in the other direction, deactivate it
 936          * in pull mode, this should not happen... */
 937         if (G_UNLIKELY (!gst_pad_activate_pull (pad, FALSE)))
 938           goto deactivate_failed;
 939         /* everything is fine now */
 940         goto was_ok;
 941       case GST_ACTIVATE_PUSH:
 942         GST_DEBUG_OBJECT (pad, "deactivating pad from push");
 943         break;
 944     }
 945   }
 946
 947   new = active ? GST_ACTIVATE_PUSH : GST_ACTIVATE_NONE;
 948   pre_activate (pad, new);
 949
 950   if (GST_PAD_ACTIVATEPUSHFUNC (pad)) {
 951     if (G_UNLIKELY (!GST_PAD_ACTIVATEPUSHFUNC (pad) (pad, active))) {
 952       goto failure;
 953     }
 954   } else {
 955     /* quite ok, element relies on state change func to prepare itself */
 956   }
 957
 958   post_activate (pad, new);
 959
 960   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in push mode",
 961       active ? "activated" : "deactivated");
 962   return TRUE;
 963
 964 was_ok:
 965   {
 966     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in push mode",
 967         active ? "activated" : "deactivated");
 968     return TRUE;
 969   }
 970 deactivate_failed:
 971   {
 972     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
 973         "failed to %s in switch to push from mode %d",
 974         (active ? "activate" : "deactivate"), old);
 975     return FALSE;
 976   }
 977 failure:
 978   {
 979     GST_OBJECT_LOCK (pad);
 980     GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in push mode",
 981         active ? "activate" : "deactivate");
 982     _priv_gst_pad_invalidate_cache (pad);
 983     GST_PAD_SET_FLUSHING (pad);
 984     GST_PAD_ACTIVATE_MODE (pad) = old;
 985     GST_OBJECT_UNLOCK (pad);
 986     return FALSE;
 987   }
 988 }
 989
 990 /**
 991  * gst_pad_is_active:
 992  * @pad: the #GstPad to query
 993  *
 994  * Query if a pad is active
 995  *
 996  * Returns: TRUE if the pad is active.
 997  *
 998  * MT safe.
 999  */
1000 gboolean
1001 gst_pad_is_active (GstPad * pad)
1002 {
1003   gboolean result = FALSE;
1004
1005   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1006
1007   GST_OBJECT_LOCK (pad);
1008   result = GST_PAD_MODE_ACTIVATE (GST_PAD_ACTIVATE_MODE (pad));
1009   GST_OBJECT_UNLOCK (pad);
1010
1011   return result;
1012 }
1013
1014 /**
1015  * gst_pad_set_blocked_async_full:
1016  * @pad: the #GstPad to block or unblock
1017  * @blocked: boolean indicating whether the pad should be blocked or unblocked
1018  * @callback: #GstPadBlockCallback that will be called when the
1019  *            operation succeeds
1020  * @user_data: user data passed to the callback
1021  * @destroy_data: #GDestroyNotify for user_data
1022  *
1023  * Blocks or unblocks the dataflow on a pad. The provided callback
1024  * is called when the operation succeeds; this happens right before the next
1025  * attempt at pushing a buffer on the pad.
1026  *
1027  * This can take a while as the pad can only become blocked when real dataflow
1028  * is happening.
1029  * When the pipeline is stalled, for example in PAUSED, this can
1030  * take an indeterminate amount of time.
1031  * You can pass NULL as the callback to make this call block. Be careful with
1032  * this blocking call as it might not return for reasons stated above.
1033  *
1034  * Returns: TRUE if the pad could be blocked. This function can fail if the
1035  * wrong parameters were passed or the pad was already in the requested state.
1036  *
1037  * MT safe.
1038  *
1039  * Since: 0.10.23
1040  */
1041 gboolean
1042 gst_pad_set_blocked_async_full (GstPad * pad, gboolean blocked,
1043     GstPadBlockCallback callback, gpointer user_data,
1044     GDestroyNotify destroy_data)
1045 {
1046   gboolean was_blocked = FALSE;
1047
1048   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1049
1050   GST_OBJECT_LOCK (pad);
1051
1052   was_blocked = GST_PAD_IS_BLOCKED (pad);
1053
1054   if (G_UNLIKELY (was_blocked == blocked))
1055     goto had_right_state;
1056
1057   if (blocked) {
1058     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocking pad");
1059
1060     _priv_gst_pad_invalidate_cache (pad);
1061     GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKED);
1062
1063     if (pad->block_destroy_data && pad->block_data)
1064       pad->block_destroy_data (pad->block_data);
1065
1066     pad->block_callback = callback;
1067     pad->block_data = user_data;
1068     pad->block_destroy_data = destroy_data;
1069     pad->abidata.ABI.block_callback_called = FALSE;
1070     if (!callback) {
1071       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for block");
1072       GST_PAD_BLOCK_WAIT (pad);
1073       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocked");
1074     }
1075   } else {
1076     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocking pad");
1077
1078     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKED);
1079
1080     if (pad->block_destroy_data && pad->block_data)
1081       pad->block_destroy_data (pad->block_data);
1082
1083     pad->block_callback = callback;
1084     pad->block_data = user_data;
1085     pad->block_destroy_data = destroy_data;
1086     pad->abidata.ABI.block_callback_called = FALSE;
1087
1088     GST_PAD_BLOCK_BROADCAST (pad);
1089     if (!callback) {
1090       /* no callback, wait for the unblock to happen */
1091       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for unblock");
1092       GST_PAD_BLOCK_WAIT (pad);
1093       GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocked");
1094     }
1095   }
1096   GST_OBJECT_UNLOCK (pad);
1097
1098   return TRUE;
1099
1100 had_right_state:
1101   {
1102     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
1103         "pad was in right state (%d)", was_blocked);
1104     GST_OBJECT_UNLOCK (pad);
1105
1106     return FALSE;
1107   }
1108 }
1109
1110 /**
1111  * gst_pad_set_blocked_async:
1112  * @pad: the #GstPad to block or unblock
1113  * @blocked: boolean indicating whether the pad should be blocked or unblocked
1114  * @callback: #GstPadBlockCallback that will be called when the
1115  *            operation succeeds
1116  * @user_data: user data passed to the callback
1117  *
1118  * Blocks or unblocks the dataflow on a pad. The provided callback
1119  * is called when the operation succeeds; this happens right before the next
1120  * attempt at pushing a buffer on the pad.
1121  *
1122  * This can take a while as the pad can only become blocked when real dataflow
1123  * is happening.
1124  * When the pipeline is stalled, for example in PAUSED, this can
1125  * take an indeterminate amount of time.
1126  * You can pass NULL as the callback to make this call block. Be careful with
1127  * this blocking call as it might not return for reasons stated above.
1128  *
1129  * Returns: TRUE if the pad could be blocked. This function can fail if the
1130  * wrong parameters were passed or the pad was already in the requested state.
1131  *
1132  * MT safe.
1133  */
1134 gboolean
1135 gst_pad_set_blocked_async (GstPad * pad, gboolean blocked,
1136     GstPadBlockCallback callback, gpointer user_data)
1137 {
1138   return gst_pad_set_blocked_async_full (pad, blocked,
1139       callback, user_data, NULL);
1140 }
1141
1142 /**
1143  * gst_pad_set_blocked:
1144  * @pad: the #GstPad to block or unblock
1145  * @blocked: boolean indicating we should block or unblock
1146  *
1147  * Blocks or unblocks the dataflow on a pad. This function is
1148  * a shortcut for gst_pad_set_blocked_async() with a NULL
1149  * callback.
1150  *
1151  * Returns: TRUE if the pad could be blocked. This function can fail if the
1152  * wrong parameters were passed or the pad was already in the requested state.
1153  *
1154  * MT safe.
1155  */
1156 gboolean
1157 gst_pad_set_blocked (GstPad * pad, gboolean blocked)
1158 {
1159   return gst_pad_set_blocked_async (pad, blocked, NULL, NULL);
1160 }
1161
1162 /**
1163  * gst_pad_is_blocked:
1164  * @pad: the #GstPad to query
1165  *
1166  * Checks if the pad is blocked or not. This function returns the
1167  * last requested state of the pad. It is not certain that the pad
1168  * is actually blocking at this point (see gst_pad_is_blocking()).
1169  *
1170  * Returns: TRUE if the pad is blocked.
1171  *
1172  * MT safe.
1173  */
1174 gboolean
1175 gst_pad_is_blocked (GstPad * pad)
1176 {
1177   gboolean result = FALSE;
1178
1179   g_return_val_if_fail (GST_IS_PAD (pad), result);
1180
1181   GST_OBJECT_LOCK (pad);
1182   result = GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_BLOCKED);
1183   GST_OBJECT_UNLOCK (pad);
1184
1185   return result;
1186 }
1187
1188 /**
1189  * gst_pad_is_blocking:
1190  * @pad: the #GstPad to query
1191  *
1192  * Checks if the pad is blocking or not. This is a guaranteed state
1193  * of whether the pad is actually blocking on a #GstBuffer or a #GstEvent.
1194  *
1195  * Returns: TRUE if the pad is blocking.
1196  *
1197  * MT safe.
1198  *
1199  * Since: 0.10.11
1200  */
1201 gboolean
1202 gst_pad_is_blocking (GstPad * pad)
1203 {
1204   gboolean result = FALSE;
1205
1206   g_return_val_if_fail (GST_IS_PAD (pad), result);
1207
1208   GST_OBJECT_LOCK (pad);
1209   /* the blocking flag is only valid if the pad is not flushing */
1210   result = GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_BLOCKING) &&
1211       !GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLUSHING);
1212   GST_OBJECT_UNLOCK (pad);
1213
1214   return result;
1215 }
1216
1217 /**
1218  * gst_pad_set_activate_function:
1219  * @pad: a #GstPad.
1220  * @activate: the #GstPadActivateFunction to set.
1221  *
1222  * Sets the given activate function for @pad. The activate function will
1223  * dispatch to gst_pad_activate_push() or gst_pad_activate_pull() to perform
1224  * the actual activation. Only makes sense to set on sink pads.
1225  *
1226  * Call this function if your sink pad can start a pull-based task.
1227  */
1228 void
1229 gst_pad_set_activate_function (GstPad * pad, GstPadActivateFunction activate)
1230 {
1231   g_return_if_fail (GST_IS_PAD (pad));
1232
1233   GST_PAD_ACTIVATEFUNC (pad) = activate;
1234   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatefunc set to %s",
1235       GST_DEBUG_FUNCPTR_NAME (activate));
1236 }
1237
1238 /**
1239  * gst_pad_set_activatepull_function:
1240  * @pad: a #GstPad.
1241  * @activatepull: the #GstPadActivateModeFunction to set.
1242  *
1243  * Sets the given activate_pull function for the pad. An activate_pull function
1244  * prepares the element and any upstream connections for pulling. See XXX
1245  * part-activation.txt for details.
1246  */
1247 void
1248 gst_pad_set_activatepull_function (GstPad * pad,
1249     GstPadActivateModeFunction activatepull)
1250 {
1251   g_return_if_fail (GST_IS_PAD (pad));
1252
1253   GST_PAD_ACTIVATEPULLFUNC (pad) = activatepull;
1254   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatepullfunc set to %s",
1255       GST_DEBUG_FUNCPTR_NAME (activatepull));
1256 }
1257
1258 /**
1259  * gst_pad_set_activatepush_function:
1260  * @pad: a #GstPad.
1261  * @activatepush: the #GstPadActivateModeFunction to set.
1262  *
1263  * Sets the given activate_push function for the pad. An activate_push function
1264  * prepares the element for pushing. See XXX part-activation.txt for details.
1265  */
1266 void
1267 gst_pad_set_activatepush_function (GstPad * pad,
1268     GstPadActivateModeFunction activatepush)
1269 {
1270   g_return_if_fail (GST_IS_PAD (pad));
1271
1272   GST_PAD_ACTIVATEPUSHFUNC (pad) = activatepush;
1273   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatepushfunc set to %s",
1274       GST_DEBUG_FUNCPTR_NAME (activatepush));
1275 }
1276
1277 /**
1278  * gst_pad_set_chain_function:
1279  * @pad: a sink #GstPad.
1280  * @chain: the #GstPadChainFunction to set.
1281  *
1282  * Sets the given chain function for the pad. The chain function is called to
1283  * process a #GstBuffer input buffer. see #GstPadChainFunction for more details.
1284  */
1285 void
1286 gst_pad_set_chain_function (GstPad * pad, GstPadChainFunction chain)
1287 {
1288   g_return_if_fail (GST_IS_PAD (pad));
1289   g_return_if_fail (GST_PAD_IS_SINK (pad));
1290
1291   GST_PAD_CHAINFUNC (pad) = chain;
1292   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "chainfunc set to %s",
1293       GST_DEBUG_FUNCPTR_NAME (chain));
1294 }
1295
1296 /**
1297  * gst_pad_set_chain_list_function:
1298  * @pad: a sink #GstPad.
1299  * @chainlist: the #GstPadChainListFunction to set.
1300  *
1301  * Sets the given chain list function for the pad. The chainlist function is
1302  * called to process a #GstBufferList input buffer list. See
1303  * #GstPadChainListFunction for more details.
1304  *
1305  * Since: 0.10.24
1306  */
1307 void
1308 gst_pad_set_chain_list_function (GstPad * pad,
1309     GstPadChainListFunction chainlist)
1310 {
1311   g_return_if_fail (GST_IS_PAD (pad));
1312   g_return_if_fail (GST_PAD_IS_SINK (pad));
1313
1314   GST_PAD_CHAINLISTFUNC (pad) = chainlist;
1315   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "chainlistfunc set to %s",
1316       GST_DEBUG_FUNCPTR_NAME (chainlist));
1317 }
1318
1319 /**
1320  * gst_pad_set_getrange_function:
1321  * @pad: a source #GstPad.
1322  * @get: the #GstPadGetRangeFunction to set.
1323  *
1324  * Sets the given getrange function for the pad. The getrange function is
1325  * called to produce a new #GstBuffer to start the processing pipeline. see
1326  * #GstPadGetRangeFunction for a description of the getrange function.
1327  */
1328 void
1329 gst_pad_set_getrange_function (GstPad * pad, GstPadGetRangeFunction get)
1330 {
1331   g_return_if_fail (GST_IS_PAD (pad));
1332   g_return_if_fail (GST_PAD_IS_SRC (pad));
1333
1334   GST_PAD_GETRANGEFUNC (pad) = get;
1335
1336   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "getrangefunc set to %s",
1337       GST_DEBUG_FUNCPTR_NAME (get));
1338 }
1339
1340 /**
1341  * gst_pad_set_checkgetrange_function:
1342  * @pad: a source #GstPad.
1343  * @check: the #GstPadCheckGetRangeFunction to set.
1344  *
1345  * Sets the given checkgetrange function for the pad. Implement this function
1346  * on a pad if you dynamically support getrange based scheduling on the pad.
1347  */
1348 void
1349 gst_pad_set_checkgetrange_function (GstPad * pad,
1350     GstPadCheckGetRangeFunction check)
1351 {
1352   g_return_if_fail (GST_IS_PAD (pad));
1353   g_return_if_fail (GST_PAD_IS_SRC (pad));
1354
1355   GST_PAD_CHECKGETRANGEFUNC (pad) = check;
1356
1357   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "checkgetrangefunc set to %s",
1358       GST_DEBUG_FUNCPTR_NAME (check));
1359 }
1360
1361 /**
1362  * gst_pad_set_event_function:
1363  * @pad: a #GstPad of either direction.
1364  * @event: the #GstPadEventFunction to set.
1365  *
1366  * Sets the given event handler for the pad.
1367  */
1368 void
1369 gst_pad_set_event_function (GstPad * pad, GstPadEventFunction event)
1370 {
1371   g_return_if_fail (GST_IS_PAD (pad));
1372
1373   GST_PAD_EVENTFUNC (pad) = event;
1374
1375   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "eventfunc for set to %s",
1376       GST_DEBUG_FUNCPTR_NAME (event));
1377 }
1378
1379 /**
1380  * gst_pad_set_query_function:
1381  * @pad: a #GstPad of either direction.
1382  * @query: the #GstPadQueryFunction to set.
1383  *
1384  * Set the given query function for the pad.
1385  */
1386 void
1387 gst_pad_set_query_function (GstPad * pad, GstPadQueryFunction query)
1388 {
1389   g_return_if_fail (GST_IS_PAD (pad));
1390
1391   GST_PAD_QUERYFUNC (pad) = query;
1392
1393   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "queryfunc set to %s",
1394       GST_DEBUG_FUNCPTR_NAME (query));
1395 }
1396
1397 /**
1398  * gst_pad_set_query_type_function:
1399  * @pad: a #GstPad of either direction.
1400  * @type_func: the #GstPadQueryTypeFunction to set.
1401  *
1402  * Set the given query type function for the pad.
1403  */
1404 void
1405 gst_pad_set_query_type_function (GstPad * pad,
1406     GstPadQueryTypeFunction type_func)
1407 {
1408   g_return_if_fail (GST_IS_PAD (pad));
1409
1410   GST_PAD_QUERYTYPEFUNC (pad) = type_func;
1411
1412   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "querytypefunc set to %s",
1413       GST_DEBUG_FUNCPTR_NAME (type_func));
1414 }
1415
1416 /**
1417  * gst_pad_get_query_types:
1418  * @pad: a #GstPad.
1419  *
1420  * Get an array of supported queries that can be performed
1421  * on this pad.
1422  *
1423  * Returns: a zero-terminated array of #GstQueryType.
1424  */
1425 const GstQueryType *
1426 gst_pad_get_query_types (GstPad * pad)
1427 {
1428   GstPadQueryTypeFunction func;
1429
1430   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1431
1432   if (G_UNLIKELY ((func = GST_PAD_QUERYTYPEFUNC (pad)) == NULL))
1433     goto no_func;
1434
1435   return func (pad);
1436
1437 no_func:
1438   {
1439     return NULL;
1440   }
1441 }
1442
1443 static gboolean
1444 gst_pad_get_query_types_dispatcher (GstPad * pad, const GstQueryType ** data)
1445 {
1446   *data = gst_pad_get_query_types (pad);
1447
1448   return TRUE;
1449 }
1450
1451 /**
1452  * gst_pad_get_query_types_default:
1453  * @pad: a #GstPad.
1454  *
1455  * Invoke the default dispatcher for the query types on
1456  * the pad.
1457  *
1458  * Returns: an zero-terminated array of #GstQueryType, or NULL if none of the
1459  * internally-linked pads has a query types function.
1460  */
1461 const GstQueryType *
1462 gst_pad_get_query_types_default (GstPad * pad)
1463 {
1464   GstQueryType *result = NULL;
1465
1466   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1467
1468   gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
1469       gst_pad_get_query_types_dispatcher, &result);
1470
1471   return result;
1472 }
1473
1474 /**
1475  * gst_pad_set_iterate_internal_links_function:
1476  * @pad: a #GstPad of either direction.
1477  * @iterintlink: the #GstPadIterIntLinkFunction to set.
1478  *
1479  * Sets the given internal link iterator function for the pad.
1480  *
1481  * Since: 0.10.21
1482  */
1483 void
1484 gst_pad_set_iterate_internal_links_function (GstPad * pad,
1485     GstPadIterIntLinkFunction iterintlink)
1486 {
1487   g_return_if_fail (GST_IS_PAD (pad));
1488
1489   GST_PAD_ITERINTLINKFUNC (pad) = iterintlink;
1490   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "internal link iterator set to %s",
1491       GST_DEBUG_FUNCPTR_NAME (iterintlink));
1492 }
1493
1494 /**
1495  * gst_pad_set_internal_link_function:
1496  * @pad: a #GstPad of either direction.
1497  * @intlink: the #GstPadIntLinkFunction to set.
1498  *
1499  * Sets the given internal link function for the pad.
1500  *
1501  * Deprecated: Use the thread-safe gst_pad_set_iterate_internal_links_function()
1502  */
1503 #ifndef GST_REMOVE_DEPRECATED
1504 #ifdef GST_DISABLE_DEPRECATED
1505 void
1506 gst_pad_set_internal_link_function (GstPad * pad,
1507     GstPadIntLinkFunction intlink);
1508 #endif
1509 void
1510 gst_pad_set_internal_link_function (GstPad * pad, GstPadIntLinkFunction intlink)
1511 {
1512   g_return_if_fail (GST_IS_PAD (pad));
1513
1514   GST_PAD_INTLINKFUNC (pad) = intlink;
1515   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "internal link set to %s",
1516       GST_DEBUG_FUNCPTR_NAME (intlink));
1517 }
1518 #endif /* GST_REMOVE_DEPRECATED */
1519
1520 /**
1521  * gst_pad_set_link_function:
1522  * @pad: a #GstPad.
1523  * @link: the #GstPadLinkFunction to set.
1524  *
1525  * Sets the given link function for the pad. It will be called when
1526  * the pad is linked with another pad.
1527  *
1528  * The return value #GST_PAD_LINK_OK should be used when the connection can be
1529  * made.
1530  *
1531  * The return value #GST_PAD_LINK_REFUSED should be used when the connection
1532  * cannot be made for some reason.
1533  *
1534  * If @link is installed on a source pad, it should call the #GstPadLinkFunction
1535  * of the peer sink pad, if present.
1536  */
1537 void
1538 gst_pad_set_link_function (GstPad * pad, GstPadLinkFunction link)
1539 {
1540   g_return_if_fail (GST_IS_PAD (pad));
1541
1542   GST_PAD_LINKFUNC (pad) = link;
1543   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "linkfunc set to %s",
1544       GST_DEBUG_FUNCPTR_NAME (link));
1545 }
1546
1547 /**
1548  * gst_pad_set_unlink_function:
1549  * @pad: a #GstPad.
1550  * @unlink: the #GstPadUnlinkFunction to set.
1551  *
1552  * Sets the given unlink function for the pad. It will be called
1553  * when the pad is unlinked.
1554  */
1555 void
1556 gst_pad_set_unlink_function (GstPad * pad, GstPadUnlinkFunction unlink)
1557 {
1558   g_return_if_fail (GST_IS_PAD (pad));
1559
1560   GST_PAD_UNLINKFUNC (pad) = unlink;
1561   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "unlinkfunc set to %s",
1562       GST_DEBUG_FUNCPTR_NAME (unlink));
1563 }
1564
1565 /**
1566  * gst_pad_set_getcaps_function:
1567  * @pad: a #GstPad.
1568  * @getcaps: the #GstPadGetCapsFunction to set.
1569  *
1570  * Sets the given getcaps function for the pad. @getcaps should return the
1571  * allowable caps for a pad in the context of the element's state, its link to
1572  * other elements, and the devices or files it has opened. These caps must be a
1573  * subset of the pad template caps. In the NULL state with no links, @getcaps
1574  * should ideally return the same caps as the pad template. In rare
1575  * circumstances, an object property can affect the caps returned by @getcaps,
1576  * but this is discouraged.
1577  *
1578  * You do not need to call this function if @pad's allowed caps are always the
1579  * same as the pad template caps. This can only be true if the padtemplate
1580  * has fixed simple caps.
1581  *
1582  * For most filters, the caps returned by @getcaps is directly affected by the
1583  * allowed caps on other pads. For demuxers and decoders, the caps returned by
1584  * the srcpad's getcaps function is directly related to the stream data. Again,
1585  * @getcaps should return the most specific caps it reasonably can, since this
1586  * helps with autoplugging.
1587  *
1588  * Note that the return value from @getcaps is owned by the caller, so the
1589  * caller should unref the caps after usage.
1590  */
1591 void
1592 gst_pad_set_getcaps_function (GstPad * pad, GstPadGetCapsFunction getcaps)
1593 {
1594   g_return_if_fail (GST_IS_PAD (pad));
1595
1596   GST_PAD_GETCAPSFUNC (pad) = getcaps;
1597   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "getcapsfunc set to %s",
1598       GST_DEBUG_FUNCPTR_NAME (getcaps));
1599 }
1600
1601 /**
1602  * gst_pad_set_acceptcaps_function:
1603  * @pad: a #GstPad.
1604  * @acceptcaps: the #GstPadAcceptCapsFunction to set.
1605  *
1606  * Sets the given acceptcaps function for the pad.  The acceptcaps function
1607  * will be called to check if the pad can accept the given caps. Setting the
1608  * acceptcaps function to NULL restores the default behaviour of allowing
1609  * any caps that matches the caps from gst_pad_get_caps().
1610  */
1611 void
1612 gst_pad_set_acceptcaps_function (GstPad * pad,
1613     GstPadAcceptCapsFunction acceptcaps)
1614 {
1615   g_return_if_fail (GST_IS_PAD (pad));
1616
1617   GST_PAD_ACCEPTCAPSFUNC (pad) = acceptcaps;
1618   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "acceptcapsfunc set to %s",
1619       GST_DEBUG_FUNCPTR_NAME (acceptcaps));
1620 }
1621
1622 /**
1623  * gst_pad_set_fixatecaps_function:
1624  * @pad: a #GstPad.
1625  * @fixatecaps: the #GstPadFixateCapsFunction to set.
1626  *
1627  * Sets the given fixatecaps function for the pad.  The fixatecaps function
1628  * will be called whenever the default values for a GstCaps needs to be
1629  * filled in.
1630  */
1631 void
1632 gst_pad_set_fixatecaps_function (GstPad * pad,
1633     GstPadFixateCapsFunction fixatecaps)
1634 {
1635   g_return_if_fail (GST_IS_PAD (pad));
1636
1637   GST_PAD_FIXATECAPSFUNC (pad) = fixatecaps;
1638   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "fixatecapsfunc set to %s",
1639       GST_DEBUG_FUNCPTR_NAME (fixatecaps));
1640 }
1641
1642 /**
1643  * gst_pad_set_setcaps_function:
1644  * @pad: a #GstPad.
1645  * @setcaps: the #GstPadSetCapsFunction to set.
1646  *
1647  * Sets the given setcaps function for the pad.  The setcaps function
1648  * will be called whenever a buffer with a new media type is pushed or
1649  * pulled from the pad. The pad/element needs to update its internal
1650  * structures to process the new media type. If this new type is not
1651  * acceptable, the setcaps function should return FALSE.
1652  */
1653 void
1654 gst_pad_set_setcaps_function (GstPad * pad, GstPadSetCapsFunction setcaps)
1655 {
1656   g_return_if_fail (GST_IS_PAD (pad));
1657
1658   GST_PAD_SETCAPSFUNC (pad) = setcaps;
1659   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "setcapsfunc set to %s",
1660       GST_DEBUG_FUNCPTR_NAME (setcaps));
1661 }
1662
1663 /**
1664  * gst_pad_set_bufferalloc_function:
1665  * @pad: a sink #GstPad.
1666  * @bufalloc: the #GstPadBufferAllocFunction to set.
1667  *
1668  * Sets the given bufferalloc function for the pad. Note that the
1669  * bufferalloc function can only be set on sinkpads.
1670  */
1671 void
1672 gst_pad_set_bufferalloc_function (GstPad * pad,
1673     GstPadBufferAllocFunction bufalloc)
1674 {
1675   g_return_if_fail (GST_IS_PAD (pad));
1676   g_return_if_fail (GST_PAD_IS_SINK (pad));
1677
1678   GST_PAD_BUFFERALLOCFUNC (pad) = bufalloc;
1679   GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "bufferallocfunc set to %s",
1680       GST_DEBUG_FUNCPTR_NAME (bufalloc));
1681 }
1682
1683 /**
1684  * gst_pad_unlink:
1685  * @srcpad: the source #GstPad to unlink.
1686  * @sinkpad: the sink #GstPad to unlink.
1687  *
1688  * Unlinks the source pad from the sink pad. Will emit the #GstPad::unlinked
1689  * signal on both pads.
1690  *
1691  * Returns: TRUE if the pads were unlinked. This function returns FALSE if
1692  * the pads were not linked together.
1693  *
1694  * MT safe.
1695  */
1696 gboolean
1697 gst_pad_unlink (GstPad * srcpad, GstPad * sinkpad)
1698 {
1699   gboolean result = FALSE;
1700   GstElement *parent = NULL;
1701
1702   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1703   g_return_val_if_fail (GST_PAD_IS_SRC (srcpad), FALSE);
1704   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1705   g_return_val_if_fail (GST_PAD_IS_SINK (sinkpad), FALSE);
1706
1707   GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinking %s:%s(%p) and %s:%s(%p)",
1708       GST_DEBUG_PAD_NAME (srcpad), srcpad,
1709       GST_DEBUG_PAD_NAME (sinkpad), sinkpad);
1710
1711   /* We need to notify the parent before taking any pad locks as the bin in
1712    * question might be waiting for a lock on the pad while holding its lock
1713    * that our message will try to take. */
1714   if ((parent = GST_ELEMENT_CAST (gst_pad_get_parent (srcpad)))) {
1715     if (GST_IS_ELEMENT (parent)) {
1716       gst_element_post_message (parent,
1717           gst_message_new_structure_change (GST_OBJECT_CAST (sinkpad),
1718               GST_STRUCTURE_CHANGE_TYPE_PAD_UNLINK, parent, TRUE));
1719     } else {
1720       gst_object_unref (parent);
1721       parent = NULL;
1722     }
1723   }
1724
1725   GST_OBJECT_LOCK (srcpad);
1726
1727   GST_OBJECT_LOCK (sinkpad);
1728
1729   if (G_UNLIKELY (GST_PAD_PEER (srcpad) != sinkpad))
1730     goto not_linked_together;
1731
1732   if (GST_PAD_UNLINKFUNC (srcpad)) {
1733     GST_PAD_UNLINKFUNC (srcpad) (srcpad);
1734   }
1735   if (GST_PAD_UNLINKFUNC (sinkpad)) {
1736     GST_PAD_UNLINKFUNC (sinkpad) (sinkpad);
1737   }
1738
1739   _priv_gst_pad_invalidate_cache (srcpad);
1740
1741   /* first clear peers */
1742   GST_PAD_PEER (srcpad) = NULL;
1743   GST_PAD_PEER (sinkpad) = NULL;
1744
1745   GST_OBJECT_UNLOCK (sinkpad);
1746   GST_OBJECT_UNLOCK (srcpad);
1747
1748   /* fire off a signal to each of the pads telling them
1749    * that they've been unlinked */
1750   g_signal_emit (srcpad, gst_pad_signals[PAD_UNLINKED], 0, sinkpad);
1751   g_signal_emit (sinkpad, gst_pad_signals[PAD_UNLINKED], 0, srcpad);
1752
1753   GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinked %s:%s and %s:%s",
1754       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1755
1756   result = TRUE;
1757
1758 done:
1759   if (parent != NULL) {
1760     gst_element_post_message (parent,
1761         gst_message_new_structure_change (GST_OBJECT_CAST (sinkpad),
1762             GST_STRUCTURE_CHANGE_TYPE_PAD_UNLINK, parent, FALSE));
1763     gst_object_unref (parent);
1764   }
1765   return result;
1766
1767   /* ERRORS */
1768 not_linked_together:
1769   {
1770     /* we do not emit a warning in this case because unlinking cannot
1771      * be made MT safe.*/
1772     GST_OBJECT_UNLOCK (sinkpad);
1773     GST_OBJECT_UNLOCK (srcpad);
1774     goto done;
1775   }
1776 }
1777
1778 /**
1779  * gst_pad_is_linked:
1780  * @pad: pad to check
1781  *
1782  * Checks if a @pad is linked to another pad or not.
1783  *
1784  * Returns: TRUE if the pad is linked, FALSE otherwise.
1785  *
1786  * MT safe.
1787  */
1788 gboolean
1789 gst_pad_is_linked (GstPad * pad)
1790 {
1791   gboolean result;
1792
1793   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1794
1795   GST_OBJECT_LOCK (pad);
1796   result = (GST_PAD_PEER (pad) != NULL);
1797   GST_OBJECT_UNLOCK (pad);
1798
1799   return result;
1800 }
1801
1802 /* get the caps from both pads and see if the intersection
1803  * is not empty.
1804  *
1805  * This function should be called with the pad LOCK on both
1806  * pads
1807  */
1808 static gboolean
1809 gst_pad_link_check_compatible_unlocked (GstPad * src, GstPad * sink,
1810     GstPadLinkCheck flags)
1811 {
1812   GstCaps *srccaps = NULL;
1813   GstCaps *sinkcaps = NULL;
1814   gboolean compatible = FALSE;
1815
1816   if (!(flags & (GST_PAD_LINK_CHECK_CAPS | GST_PAD_LINK_CHECK_TEMPLATE_CAPS)))
1817     return TRUE;
1818
1819   /* Doing the expensive caps checking takes priority over only checking the template caps */
1820   if (flags & GST_PAD_LINK_CHECK_CAPS) {
1821     srccaps = gst_pad_get_caps_unlocked (src);
1822     sinkcaps = gst_pad_get_caps_unlocked (sink);
1823   } else {
1824     /* If one of the two pads doesn't have a template, consider the intersection
1825      * as valid.*/
1826     if (G_UNLIKELY ((GST_PAD_PAD_TEMPLATE (src) == NULL)
1827             || (GST_PAD_PAD_TEMPLATE (sink) == NULL))) {
1828       compatible = TRUE;
1829       goto done;
1830     }
1831     srccaps = gst_caps_ref (GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (src)));
1832     sinkcaps =
1833         gst_caps_ref (GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (sink)));
1834   }
1835
1836   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, src, "src caps %" GST_PTR_FORMAT,
1837       srccaps);
1838   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, sink, "sink caps %" GST_PTR_FORMAT,
1839       sinkcaps);
1840
1841   /* if we have caps on both pads we can check the intersection. If one
1842    * of the caps is NULL, we return TRUE. */
1843   if (G_UNLIKELY (srccaps == NULL || sinkcaps == NULL)) {
1844     if (srccaps)
1845       gst_caps_unref (srccaps);
1846     if (sinkcaps)
1847       gst_caps_unref (sinkcaps);
1848     goto done;
1849   }
1850
1851   compatible = gst_caps_can_intersect (srccaps, sinkcaps);
1852   gst_caps_unref (srccaps);
1853   gst_caps_unref (sinkcaps);
1854
1855 done:
1856   GST_CAT_DEBUG (GST_CAT_CAPS, "caps are %scompatible",
1857       (compatible ? "" : "not"));
1858
1859   return compatible;
1860 }
1861
1862 /* check if the grandparents of both pads are the same.
1863  * This check is required so that we don't try to link
1864  * pads from elements in different bins without ghostpads.
1865  *
1866  * The LOCK should be held on both pads
1867  */
1868 static gboolean
1869 gst_pad_link_check_hierarchy (GstPad * src, GstPad * sink)
1870 {
1871   GstObject *psrc, *psink;
1872
1873   psrc = GST_OBJECT_PARENT (src);
1874   psink = GST_OBJECT_PARENT (sink);
1875
1876   /* if one of the pads has no parent, we allow the link */
1877   if (G_UNLIKELY (psrc == NULL || psink == NULL))
1878     goto no_parent;
1879
1880   /* only care about parents that are elements */
1881   if (G_UNLIKELY (!GST_IS_ELEMENT (psrc) || !GST_IS_ELEMENT (psink)))
1882     goto no_element_parent;
1883
1884   /* if the parents are the same, we have a loop */
1885   if (G_UNLIKELY (psrc == psink))
1886     goto same_parents;
1887
1888   /* if they both have a parent, we check the grandparents. We can not lock
1889    * the parent because we hold on the child (pad) and the locking order is
1890    * parent >> child. */
1891   psrc = GST_OBJECT_PARENT (psrc);
1892   psink = GST_OBJECT_PARENT (psink);
1893
1894   /* if they have grandparents but they are not the same */
1895   if (G_UNLIKELY (psrc != psink))
1896     goto wrong_grandparents;
1897
1898   return TRUE;
1899
1900   /* ERRORS */
1901 no_parent:
1902   {
1903     GST_CAT_DEBUG (GST_CAT_CAPS,
1904         "one of the pads has no parent %" GST_PTR_FORMAT " and %"
1905         GST_PTR_FORMAT, psrc, psink);
1906     return TRUE;
1907   }
1908 no_element_parent:
1909   {
1910     GST_CAT_DEBUG (GST_CAT_CAPS,
1911         "one of the pads has no element parent %" GST_PTR_FORMAT " and %"
1912         GST_PTR_FORMAT, psrc, psink);
1913     return TRUE;
1914   }
1915 same_parents:
1916   {
1917     GST_CAT_DEBUG (GST_CAT_CAPS, "pads have same parent %" GST_PTR_FORMAT,
1918         psrc);
1919     return FALSE;
1920   }
1921 wrong_grandparents:
1922   {
1923     GST_CAT_DEBUG (GST_CAT_CAPS,
1924         "pads have different grandparents %" GST_PTR_FORMAT " and %"
1925         GST_PTR_FORMAT, psrc, psink);
1926     return FALSE;
1927   }
1928 }
1929
1930 /* FIXME leftover from an attempt at refactoring... */
1931 /* call with the two pads unlocked, when this function returns GST_PAD_LINK_OK,
1932  * the two pads will be locked in the srcpad, sinkpad order. */
1933 static GstPadLinkReturn
1934 gst_pad_link_prepare (GstPad * srcpad, GstPad * sinkpad, GstPadLinkCheck flags)
1935 {
1936   GST_CAT_INFO (GST_CAT_PADS, "trying to link %s:%s and %s:%s",
1937       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1938
1939   GST_OBJECT_LOCK (srcpad);
1940
1941   if (G_UNLIKELY (GST_PAD_PEER (srcpad) != NULL))
1942     goto src_was_linked;
1943
1944   GST_OBJECT_LOCK (sinkpad);
1945
1946   if (G_UNLIKELY (GST_PAD_PEER (sinkpad) != NULL))
1947     goto sink_was_linked;
1948
1949   /* check hierarchy, pads can only be linked if the grandparents
1950    * are the same. */
1951   if ((flags & GST_PAD_LINK_CHECK_HIERARCHY)
1952       && !gst_pad_link_check_hierarchy (srcpad, sinkpad))
1953     goto wrong_hierarchy;
1954
1955   /* check pad caps for non-empty intersection */
1956   if (!gst_pad_link_check_compatible_unlocked (srcpad, sinkpad, flags))
1957     goto no_format;
1958
1959   /* FIXME check pad scheduling for non-empty intersection */
1960
1961   return GST_PAD_LINK_OK;
1962
1963 src_was_linked:
1964   {
1965     GST_CAT_INFO (GST_CAT_PADS, "src %s:%s was already linked to %s:%s",
1966         GST_DEBUG_PAD_NAME (srcpad),
1967         GST_DEBUG_PAD_NAME (GST_PAD_PEER (srcpad)));
1968     /* we do not emit a warning in this case because unlinking cannot
1969      * be made MT safe.*/
1970     GST_OBJECT_UNLOCK (srcpad);
1971     return GST_PAD_LINK_WAS_LINKED;
1972   }
1973 sink_was_linked:
1974   {
1975     GST_CAT_INFO (GST_CAT_PADS, "sink %s:%s was already linked to %s:%s",
1976         GST_DEBUG_PAD_NAME (sinkpad),
1977         GST_DEBUG_PAD_NAME (GST_PAD_PEER (sinkpad)));
1978     /* we do not emit a warning in this case because unlinking cannot
1979      * be made MT safe.*/
1980     GST_OBJECT_UNLOCK (sinkpad);
1981     GST_OBJECT_UNLOCK (srcpad);
1982     return GST_PAD_LINK_WAS_LINKED;
1983   }
1984 wrong_hierarchy:
1985   {
1986     GST_CAT_INFO (GST_CAT_PADS, "pads have wrong hierarchy");
1987     GST_OBJECT_UNLOCK (sinkpad);
1988     GST_OBJECT_UNLOCK (srcpad);
1989     return GST_PAD_LINK_WRONG_HIERARCHY;
1990   }
1991 no_format:
1992   {
1993     GST_CAT_INFO (GST_CAT_PADS, "caps are incompatible");
1994     GST_OBJECT_UNLOCK (sinkpad);
1995     GST_OBJECT_UNLOCK (srcpad);
1996     return GST_PAD_LINK_NOFORMAT;
1997   }
1998 }
1999
2000 /**
2001  * gst_pad_can_link:
2002  * @srcpad: the source #GstPad.
2003  * @sinkpad: the sink #GstPad.
2004  *
2005  * Checks if the source pad and the sink pad are compatible so they can be
2006  * linked.
2007  *
2008  * Returns: TRUE if the pads can be linked.
2009  */
2010 gboolean
2011 gst_pad_can_link (GstPad * srcpad, GstPad * sinkpad)
2012 {
2013   GstPadLinkReturn result;
2014
2015   /* generic checks */
2016   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
2017   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
2018
2019   GST_CAT_INFO (GST_CAT_PADS, "check if %s:%s can link with %s:%s",
2020       GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
2021
2022   /* gst_pad_link_prepare does everything for us, we only release the locks
2023    * on the pads that it gets us. If this function returns !OK the locks are not
2024    * taken anymore. */
2025   result = gst_pad_link_prepare (srcpad, sinkpad, GST_PAD_LINK_CHECK_DEFAULT);
2026   if (result != GST_PAD_LINK_OK)
2027     goto done;
2028
2029   GST_OBJECT_UNLOCK (srcpad);
2030   GST_OBJECT_UNLOCK (sinkpad);
2031
2032 done:
2033   return result == GST_PAD_LINK_OK;
2034 }
2035
2036 /**
2037  * gst_pad_link_full:
2038  * @srcpad: the source #GstPad to link.
2039  * @sinkpad: the sink #GstPad to link.
2040  * @flags: the checks to validate when linking
2041  *
2042  * Links the source pad and the sink pad.
2043  *
2044  * This variant of #gst_pad_link provides a more granular control on the
2045  * checks being done when linking. While providing some considerable speedups
2046  * the caller of this method must be aware that wrong usage of those flags
2047  * can cause severe issues. Refer to the documentation of #GstPadLinkCheck
2048  * for more information.
2049  *
2050  * MT Safe.
2051  *
2052  * Returns: A result code indicating if the connection worked or
2053  *          what went wrong.
2054  *
2055  * Since: 0.10.30
2056  */
2057 GstPadLinkReturn
2058 gst_pad_link_full (GstPad * srcpad, GstPad * sinkpad, GstPadLinkCheck flags)
2059 {
2060   GstPadLinkReturn result;
2061   GstElement *parent;
2062
2063   g_return_val_if_fail (GST_IS_PAD (srcpad), GST_PAD_LINK_REFUSED);
2064   g_return_val_if_fail (GST_PAD_IS_SRC (srcpad), GST_PAD_LINK_WRONG_DIRECTION);
2065   g_return_val_if_fail (GST_IS_PAD (sinkpad), GST_PAD_LINK_REFUSED);
2066   g_return_val_if_fail (GST_PAD_IS_SINK (sinkpad),
2067       GST_PAD_LINK_WRONG_DIRECTION);
2068
2069   /* Notify the parent early. See gst_pad_unlink for details. */
2070   if ((parent = GST_ELEMENT_CAST (gst_pad_get_parent (srcpad)))) {
2071     if (GST_IS_ELEMENT (parent)) {
2072       gst_element_post_message (parent,
2073           gst_message_new_structure_change (GST_OBJECT_CAST (sinkpad),
2074               GST_STRUCTURE_CHANGE_TYPE_PAD_LINK, parent, TRUE));
2075     } else {
2076       gst_object_unref (parent);
2077       parent = NULL;
2078     }
2079   }
2080
2081   /* prepare will also lock the two pads */
2082   result = gst_pad_link_prepare (srcpad, sinkpad, flags);
2083
2084   if (result != GST_PAD_LINK_OK)
2085     goto done;
2086
2087   /* must set peers before calling the link function */
2088   GST_PAD_PEER (srcpad) = sinkpad;
2089   GST_PAD_PEER (sinkpad) = srcpad;
2090
2091   GST_OBJECT_UNLOCK (sinkpad);
2092   GST_OBJECT_UNLOCK (srcpad);
2093
2094   /* FIXME released the locks here, concurrent thread might link
2095    * something else. */
2096   if (GST_PAD_LINKFUNC (srcpad)) {
2097     /* this one will call the peer link function */
2098     result = GST_PAD_LINKFUNC (srcpad) (srcpad, sinkpad);
2099   } else if (GST_PAD_LINKFUNC (sinkpad)) {
2100     /* if no source link function, we need to call the sink link
2101      * function ourselves. */
2102     result = GST_PAD_LINKFUNC (sinkpad) (sinkpad, srcpad);
2103   } else {
2104     result = GST_PAD_LINK_OK;
2105   }
2106
2107   GST_OBJECT_LOCK (srcpad);
2108   GST_OBJECT_LOCK (sinkpad);
2109
2110   if (result == GST_PAD_LINK_OK) {
2111     GST_OBJECT_UNLOCK (sinkpad);
2112     GST_OBJECT_UNLOCK (srcpad);
2113
2114     /* fire off a signal to each of the pads telling them
2115      * that they've been linked */
2116     g_signal_emit (srcpad, gst_pad_signals[PAD_LINKED], 0, sinkpad);
2117     g_signal_emit (sinkpad, gst_pad_signals[PAD_LINKED], 0, srcpad);
2118
2119     GST_CAT_INFO (GST_CAT_PADS, "linked %s:%s and %s:%s, successful",
2120         GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
2121   } else {
2122     GST_CAT_INFO (GST_CAT_PADS, "link between %s:%s and %s:%s failed",
2123         GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
2124
2125     GST_PAD_PEER (srcpad) = NULL;
2126     GST_PAD_PEER (sinkpad) = NULL;
2127
2128     GST_OBJECT_UNLOCK (sinkpad);
2129     GST_OBJECT_UNLOCK (srcpad);
2130   }
2131
2132 done:
2133   if (parent) {
2134     gst_element_post_message (parent,
2135         gst_message_new_structure_change (GST_OBJECT_CAST (sinkpad),
2136             GST_STRUCTURE_CHANGE_TYPE_PAD_LINK, parent, FALSE));
2137     gst_object_unref (parent);
2138   }
2139
2140   return result;
2141 }
2142
2143 /**
2144  * gst_pad_link:
2145  * @srcpad: the source #GstPad to link.
2146  * @sinkpad: the sink #GstPad to link.
2147  *
2148  * Links the source pad and the sink pad.
2149  *
2150  * Returns: A result code indicating if the connection worked or
2151  *          what went wrong.
2152  *
2153  * MT Safe.
2154  */
2155 GstPadLinkReturn
2156 gst_pad_link (GstPad * srcpad, GstPad * sinkpad)
2157 {
2158   return gst_pad_link_full (srcpad, sinkpad, GST_PAD_LINK_CHECK_DEFAULT);
2159 }
2160
2161 static void
2162 gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ)
2163 {
2164   GstPadTemplate **template_p;
2165
2166   /* this function would need checks if it weren't static */
2167
2168   GST_OBJECT_LOCK (pad);
2169   template_p = &pad->padtemplate;
2170   gst_object_replace ((GstObject **) template_p, (GstObject *) templ);
2171   GST_OBJECT_UNLOCK (pad);
2172
2173   if (templ)
2174     gst_pad_template_pad_created (templ, pad);
2175 }
2176
2177 /**
2178  * gst_pad_get_pad_template:
2179  * @pad: a #GstPad.
2180  *
2181  * Gets the template for @pad.
2182  *
2183  * Returns: the #GstPadTemplate from which this pad was instantiated, or %NULL
2184  * if this pad has no template.
2185  *
2186  * FIXME: currently returns an unrefcounted padtemplate.
2187  */
2188 GstPadTemplate *
2189 gst_pad_get_pad_template (GstPad * pad)
2190 {
2191   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2192
2193   return GST_PAD_PAD_TEMPLATE (pad);
2194 }
2195
2196
2197 /* should be called with the pad LOCK held */
2198 /* refs the caps, so caller is responsible for getting it unreffed */
2199 static GstCaps *
2200 gst_pad_get_caps_unlocked (GstPad * pad)
2201 {
2202   GstCaps *result = NULL;
2203   GstPadTemplate *templ;
2204
2205   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get pad caps");
2206
2207   if (GST_PAD_GETCAPSFUNC (pad)) {
2208     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2209         "dispatching to pad getcaps function");
2210
2211     GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_GETCAPS);
2212     GST_OBJECT_UNLOCK (pad);
2213     result = GST_PAD_GETCAPSFUNC (pad) (pad);
2214     GST_OBJECT_LOCK (pad);
2215     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_GETCAPS);
2216
2217     if (result == NULL) {
2218       g_critical ("pad %s:%s returned NULL caps from getcaps function",
2219           GST_DEBUG_PAD_NAME (pad));
2220     } else {
2221       GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2222           "pad getcaps returned %" GST_PTR_FORMAT, result);
2223 #ifndef G_DISABLE_ASSERT
2224       /* check that the returned caps are a real subset of the template caps */
2225       if (GST_PAD_PAD_TEMPLATE (pad)) {
2226         const GstCaps *templ_caps =
2227             GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
2228         if (!gst_caps_is_subset (result, templ_caps)) {
2229           GstCaps *temp;
2230
2231           GST_CAT_ERROR_OBJECT (GST_CAT_CAPS, pad,
2232               "pad returned caps %" GST_PTR_FORMAT
2233               " which are not a real subset of its template caps %"
2234               GST_PTR_FORMAT, result, templ_caps);
2235           g_warning
2236               ("pad %s:%s returned caps which are not a real "
2237               "subset of its template caps", GST_DEBUG_PAD_NAME (pad));
2238           temp = gst_caps_intersect (templ_caps, result);
2239           gst_caps_unref (result);
2240           result = temp;
2241         }
2242       }
2243 #endif
2244       goto done;
2245     }
2246   }
2247   if ((templ = GST_PAD_PAD_TEMPLATE (pad))) {
2248     result = GST_PAD_TEMPLATE_CAPS (templ);
2249     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2250         "using pad template %p with caps %p %" GST_PTR_FORMAT, templ, result,
2251         result);
2252
2253     result = gst_caps_ref (result);
2254     goto done;
2255   }
2256   if ((result = GST_PAD_CAPS (pad))) {
2257     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2258         "using pad caps %p %" GST_PTR_FORMAT, result, result);
2259
2260     result = gst_caps_ref (result);
2261     goto done;
2262   }
2263
2264   /* this almost never happens */
2265   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "pad has no caps");
2266   result = gst_caps_new_empty ();
2267
2268 done:
2269   return result;
2270 }
2271
2272 /* FIXME-0.11: what about making this the default and using
2273  * gst_caps_make_writable() explicitely where needed
2274  */
2275 /**
2276  * gst_pad_get_caps_reffed:
2277  * @pad: a  #GstPad to get the capabilities of.
2278  *
2279  * Gets the capabilities this pad can produce or consume. Preferred function if
2280  * one only wants to read or intersect the caps.
2281  *
2282  * Returns: the caps of the pad with incremented ref-count.
2283  *
2284  * Since: 0.10.26
2285  */
2286 GstCaps *
2287 gst_pad_get_caps_reffed (GstPad * pad)
2288 {
2289   GstCaps *result = NULL;
2290
2291   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2292
2293   GST_OBJECT_LOCK (pad);
2294
2295   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get pad caps");
2296
2297   result = gst_pad_get_caps_unlocked (pad);
2298
2299   GST_OBJECT_UNLOCK (pad);
2300
2301   return result;
2302 }
2303
2304 /**
2305  * gst_pad_get_caps:
2306  * @pad: a  #GstPad to get the capabilities of.
2307  *
2308  * Gets the capabilities this pad can produce or consume.
2309  * Note that this method doesn't necessarily return the caps set by
2310  * gst_pad_set_caps() - use GST_PAD_CAPS() for that instead.
2311  * gst_pad_get_caps returns all possible caps a pad can operate with, using
2312  * the pad's get_caps function;
2313  * this returns the pad template caps if not explicitly set.
2314  *
2315  * Returns: a newly allocated copy of the #GstCaps of this pad.
2316  *
2317  * MT safe.
2318  */
2319 GstCaps *
2320 gst_pad_get_caps (GstPad * pad)
2321 {
2322   GstCaps *result = gst_pad_get_caps_reffed (pad);
2323
2324   /* be sure that we have a copy */
2325   if (G_LIKELY (result))
2326     result = gst_caps_make_writable (result);
2327
2328   return result;
2329 }
2330
2331 /* FIXME-0.11: what about making this the default and using
2332  * gst_caps_make_writable() explicitely where needed
2333  */
2334 /**
2335  * gst_pad_peer_get_caps_reffed:
2336  * @pad: a  #GstPad to get the capabilities of.
2337  *
2338  * Gets the capabilities of the peer connected to this pad. Preferred function
2339  * if one only wants to read or intersect the caps.
2340  *
2341  * Returns: the caps of the pad with incremented ref-count.
2342  *
2343  * Since: 0.10.26
2344  */
2345 GstCaps *
2346 gst_pad_peer_get_caps_reffed (GstPad * pad)
2347 {
2348   GstPad *peerpad;
2349   GstCaps *result = NULL;
2350
2351   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2352
2353   GST_OBJECT_LOCK (pad);
2354
2355   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get peer caps");
2356
2357   peerpad = GST_PAD_PEER (pad);
2358   if (G_UNLIKELY (peerpad == NULL))
2359     goto no_peer;
2360
2361   gst_object_ref (peerpad);
2362   GST_OBJECT_UNLOCK (pad);
2363
2364   result = gst_pad_get_caps_reffed (peerpad);
2365
2366   gst_object_unref (peerpad);
2367
2368   return result;
2369
2370 no_peer:
2371   {
2372     GST_OBJECT_UNLOCK (pad);
2373     return NULL;
2374   }
2375 }
2376
2377 /**
2378  * gst_pad_peer_get_caps:
2379  * @pad: a  #GstPad to get the peer capabilities of.
2380  *
2381  * Gets the capabilities of the peer connected to this pad. Similar to
2382  * gst_pad_get_caps().
2383  *
2384  * Returns: a newly allocated copy of the #GstCaps of the peer pad. Use
2385  * gst_caps_unref() to get rid of it. This function returns %NULL if there is
2386  * no peer pad.
2387  */
2388 GstCaps *
2389 gst_pad_peer_get_caps (GstPad * pad)
2390 {
2391   GstPad *peerpad;
2392   GstCaps *result = NULL;
2393
2394   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2395
2396   GST_OBJECT_LOCK (pad);
2397
2398   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get peer caps");
2399
2400   peerpad = GST_PAD_PEER (pad);
2401   if (G_UNLIKELY (peerpad == NULL))
2402     goto no_peer;
2403
2404   gst_object_ref (peerpad);
2405   GST_OBJECT_UNLOCK (pad);
2406
2407   result = gst_pad_get_caps (peerpad);
2408
2409   gst_object_unref (peerpad);
2410
2411   return result;
2412
2413 no_peer:
2414   {
2415     GST_OBJECT_UNLOCK (pad);
2416     return NULL;
2417   }
2418 }
2419
2420 static gboolean
2421 fixate_value (GValue * dest, const GValue * src)
2422 {
2423   if (G_VALUE_TYPE (src) == GST_TYPE_INT_RANGE) {
2424     g_value_init (dest, G_TYPE_INT);
2425     g_value_set_int (dest, gst_value_get_int_range_min (src));
2426   } else if (G_VALUE_TYPE (src) == GST_TYPE_DOUBLE_RANGE) {
2427     g_value_init (dest, G_TYPE_DOUBLE);
2428     g_value_set_double (dest, gst_value_get_double_range_min (src));
2429   } else if (G_VALUE_TYPE (src) == GST_TYPE_FRACTION_RANGE) {
2430     gst_value_init_and_copy (dest, gst_value_get_fraction_range_min (src));
2431   } else if (G_VALUE_TYPE (src) == GST_TYPE_LIST) {
2432     GValue temp = { 0 };
2433
2434     /* list could be empty */
2435     if (gst_value_list_get_size (src) <= 0)
2436       return FALSE;
2437
2438     gst_value_init_and_copy (&temp, gst_value_list_get_value (src, 0));
2439
2440     if (!fixate_value (dest, &temp))
2441       gst_value_init_and_copy (dest, &temp);
2442     g_value_unset (&temp);
2443   } else if (G_VALUE_TYPE (src) == GST_TYPE_ARRAY) {
2444     gboolean res = FALSE;
2445     guint n, len;
2446
2447     len = gst_value_array_get_size (src);
2448     g_value_init (dest, GST_TYPE_ARRAY);
2449     for (n = 0; n < len; n++) {
2450       GValue kid = { 0 };
2451       const GValue *orig_kid = gst_value_array_get_value (src, n);
2452
2453       if (!fixate_value (&kid, orig_kid))
2454         gst_value_init_and_copy (&kid, orig_kid);
2455       else
2456         res = TRUE;
2457       gst_value_array_append_value (dest, &kid);
2458       g_value_unset (&kid);
2459     }
2460
2461     if (!res)
2462       g_value_unset (dest);
2463
2464     return res;
2465   } else {
2466     return FALSE;
2467   }
2468
2469   return TRUE;
2470 }
2471
2472 static gboolean
2473 gst_pad_default_fixate (GQuark field_id, const GValue * value, gpointer data)
2474 {
2475   GstStructure *s = data;
2476   GValue v = { 0 };
2477
2478   if (fixate_value (&v, value)) {
2479     gst_structure_id_set_value (s, field_id, &v);
2480     g_value_unset (&v);
2481   }
2482
2483   return TRUE;
2484 }
2485
2486 /**
2487  * gst_pad_fixate_caps:
2488  * @pad: a  #GstPad to fixate
2489  * @caps: the  #GstCaps to fixate
2490  *
2491  * Fixate a caps on the given pad. Modifies the caps in place, so you should
2492  * make sure that the caps are actually writable (see gst_caps_make_writable()).
2493  */
2494 void
2495 gst_pad_fixate_caps (GstPad * pad, GstCaps * caps)
2496 {
2497   GstPadFixateCapsFunction fixatefunc;
2498   GstStructure *s;
2499
2500   g_return_if_fail (GST_IS_PAD (pad));
2501   g_return_if_fail (caps != NULL);
2502   g_return_if_fail (!gst_caps_is_empty (caps));
2503   /* FIXME-0.11: do not allow fixating any-caps
2504    * g_return_if_fail (!gst_caps_is_any (caps));
2505    */
2506
2507   if (gst_caps_is_fixed (caps) || gst_caps_is_any (caps))
2508     return;
2509
2510   fixatefunc = GST_PAD_FIXATECAPSFUNC (pad);
2511   if (fixatefunc) {
2512     fixatefunc (pad, caps);
2513   }
2514
2515   /* default fixation */
2516   gst_caps_truncate (caps);
2517   s = gst_caps_get_structure (caps, 0);
2518   gst_structure_foreach (s, gst_pad_default_fixate, s);
2519 }
2520
2521 /* Default accept caps implementation just checks against
2522  * against the allowed caps for the pad */
2523 static gboolean
2524 gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps)
2525 {
2526   /* get the caps and see if it intersects to something not empty */
2527   GstCaps *allowed;
2528   gboolean result = FALSE;
2529
2530   GST_DEBUG_OBJECT (pad, "caps %" GST_PTR_FORMAT, caps);
2531
2532   allowed = gst_pad_get_caps_reffed (pad);
2533   if (!allowed)
2534     goto nothing_allowed;
2535
2536   GST_DEBUG_OBJECT (pad, "allowed caps %" GST_PTR_FORMAT, allowed);
2537
2538   result = gst_caps_can_intersect (allowed, caps);
2539
2540   gst_caps_unref (allowed);
2541
2542   return result;
2543
2544   /* ERRORS */
2545 nothing_allowed:
2546   {
2547     GST_DEBUG_OBJECT (pad, "no caps allowed on the pad");
2548     return FALSE;
2549   }
2550 }
2551
2552 /**
2553  * gst_pad_accept_caps:
2554  * @pad: a #GstPad to check
2555  * @caps: a #GstCaps to check on the pad
2556  *
2557  * Check if the given pad accepts the caps.
2558  *
2559  * Returns: TRUE if the pad can accept the caps.
2560  */
2561 gboolean
2562 gst_pad_accept_caps (GstPad * pad, GstCaps * caps)
2563 {
2564   gboolean result;
2565   GstPadAcceptCapsFunction acceptfunc;
2566   GstCaps *existing = NULL;
2567
2568   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2569
2570   /* any pad can be unnegotiated */
2571   if (caps == NULL)
2572     return TRUE;
2573
2574   /* lock for checking the existing caps */
2575   GST_OBJECT_LOCK (pad);
2576   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "accept caps of %p", caps);
2577   /* The current caps on a pad are trivially acceptable */
2578   if (G_LIKELY ((existing = GST_PAD_CAPS (pad)))) {
2579     if (caps == existing || gst_caps_is_equal (caps, existing))
2580       goto is_same_caps;
2581   }
2582   acceptfunc = GST_PAD_ACCEPTCAPSFUNC (pad);
2583   GST_OBJECT_UNLOCK (pad);
2584
2585   if (G_LIKELY (acceptfunc)) {
2586     /* we can call the function */
2587     result = acceptfunc (pad, caps);
2588     GST_DEBUG_OBJECT (pad, "acceptfunc returned %d", result);
2589   } else {
2590     /* Only null if the element explicitly unset it */
2591     result = gst_pad_acceptcaps_default (pad, caps);
2592     GST_DEBUG_OBJECT (pad, "default acceptcaps returned %d", result);
2593   }
2594   return result;
2595
2596 is_same_caps:
2597   {
2598     GST_DEBUG_OBJECT (pad, "pad had same caps");
2599     GST_OBJECT_UNLOCK (pad);
2600     return TRUE;
2601   }
2602 }
2603
2604 /**
2605  * gst_pad_peer_accept_caps:
2606  * @pad: a  #GstPad to check the peer of
2607  * @caps: a #GstCaps to check on the pad
2608  *
2609  * Check if the peer of @pad accepts @caps. If @pad has no peer, this function
2610  * returns TRUE.
2611  *
2612  * Returns: TRUE if the peer of @pad can accept the caps or @pad has no peer.
2613  */
2614 gboolean
2615 gst_pad_peer_accept_caps (GstPad * pad, GstCaps * caps)
2616 {
2617   GstPad *peerpad;
2618   gboolean result;
2619
2620   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2621
2622   GST_OBJECT_LOCK (pad);
2623
2624   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "peer accept caps of (%p)", pad);
2625
2626   peerpad = GST_PAD_PEER (pad);
2627   if (G_UNLIKELY (peerpad == NULL))
2628     goto no_peer;
2629
2630   gst_object_ref (peerpad);
2631   /* release lock before calling external methods but keep ref to pad */
2632   GST_OBJECT_UNLOCK (pad);
2633
2634   result = gst_pad_accept_caps (peerpad, caps);
2635
2636   gst_object_unref (peerpad);
2637
2638   return result;
2639
2640 no_peer:
2641   {
2642     GST_OBJECT_UNLOCK (pad);
2643     return TRUE;
2644   }
2645 }
2646
2647 /**
2648  * gst_pad_set_caps:
2649  * @pad: a  #GstPad to set the capabilities of.
2650  * @caps: a #GstCaps to set.
2651  *
2652  * Sets the capabilities of this pad. The caps must be fixed. Any previous
2653  * caps on the pad will be unreffed. This function refs the caps so you should
2654  * unref if as soon as you don't need it anymore.
2655  * It is possible to set NULL caps, which will make the pad unnegotiated
2656  * again.
2657  *
2658  * Returns: TRUE if the caps could be set. FALSE if the caps were not fixed
2659  * or bad parameters were provided to this function.
2660  *
2661  * MT safe.
2662  */
2663 gboolean
2664 gst_pad_set_caps (GstPad * pad, GstCaps * caps)
2665 {
2666   GstPadSetCapsFunction setcaps;
2667   GstCaps *existing;
2668
2669   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2670   g_return_val_if_fail (caps == NULL || gst_caps_is_fixed (caps), FALSE);
2671
2672   GST_OBJECT_LOCK (pad);
2673   existing = GST_PAD_CAPS (pad);
2674   if (existing == caps)
2675     goto was_ok;
2676
2677   if (gst_caps_is_equal (caps, existing))
2678     goto setting_same_caps;
2679
2680   setcaps = GST_PAD_SETCAPSFUNC (pad);
2681
2682   /* call setcaps function to configure the pad only if the
2683    * caps is not NULL */
2684   if (setcaps != NULL && caps) {
2685     if (!GST_PAD_IS_IN_SETCAPS (pad)) {
2686       GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_SETCAPS);
2687       GST_OBJECT_UNLOCK (pad);
2688       if (!setcaps (pad, caps))
2689         goto could_not_set;
2690       GST_OBJECT_LOCK (pad);
2691       GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2692     } else {
2693       GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "pad was dispatching");
2694     }
2695   }
2696
2697   gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2698   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "caps %p %" GST_PTR_FORMAT, caps,
2699       caps);
2700   GST_OBJECT_UNLOCK (pad);
2701
2702 #if GLIB_CHECK_VERSION(2,26,0)
2703   g_object_notify_by_pspec ((GObject *) pad, pspec_caps);
2704 #else
2705   g_object_notify ((GObject *) pad, "caps");
2706 #endif
2707
2708   return TRUE;
2709
2710 was_ok:
2711   {
2712     GST_OBJECT_UNLOCK (pad);
2713     return TRUE;
2714   }
2715 setting_same_caps:
2716   {
2717     gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2718     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2719         "caps %p %" GST_PTR_FORMAT " same as existing, updating ptr only", caps,
2720         caps);
2721     GST_OBJECT_UNLOCK (pad);
2722     return TRUE;
2723   }
2724
2725   /* ERRORS */
2726 could_not_set:
2727   {
2728     GST_OBJECT_LOCK (pad);
2729     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2730     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2731         "caps %" GST_PTR_FORMAT " could not be set", caps);
2732     GST_OBJECT_UNLOCK (pad);
2733
2734     return FALSE;
2735   }
2736 }
2737
2738 static gboolean
2739 gst_pad_configure_sink (GstPad * pad, GstCaps * caps)
2740 {
2741   gboolean res;
2742
2743   /* See if pad accepts the caps */
2744   if (!gst_caps_can_intersect (caps, gst_pad_get_pad_template_caps (pad)))
2745     goto not_accepted;
2746
2747   /* set caps on pad if call succeeds */
2748   res = gst_pad_set_caps (pad, caps);
2749   /* no need to unref the caps here, set_caps takes a ref and
2750    * our ref goes away when we leave this function. */
2751
2752   return res;
2753
2754 not_accepted:
2755   {
2756     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2757         "caps %" GST_PTR_FORMAT " not accepted", caps);
2758     return FALSE;
2759   }
2760 }
2761
2762 /* returns TRUE if the src pad could be configured to accept the given caps */
2763 static gboolean
2764 gst_pad_configure_src (GstPad * pad, GstCaps * caps, gboolean dosetcaps)
2765 {
2766   gboolean res;
2767
2768   if (dosetcaps) {
2769     /* See if pad accepts the caps */
2770     if (!gst_pad_accept_caps (pad, caps))
2771       goto not_accepted;
2772
2773     res = gst_pad_set_caps (pad, caps);
2774   } else {
2775     res = TRUE;
2776   }
2777   return res;
2778
2779 not_accepted:
2780   {
2781     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2782         "caps %" GST_PTR_FORMAT " not accepted", caps);
2783     return FALSE;
2784   }
2785 }
2786
2787 /**
2788  * gst_pad_get_pad_template_caps:
2789  * @pad: a #GstPad to get the template capabilities from.
2790  *
2791  * Gets the capabilities for @pad's template.
2792  *
2793  * Returns: the #GstCaps of this pad template. If you intend to keep a
2794  * reference on the caps, make a copy (see gst_caps_copy ()).
2795  */
2796 const GstCaps *
2797 gst_pad_get_pad_template_caps (GstPad * pad)
2798 {
2799   static GstStaticCaps anycaps = GST_STATIC_CAPS ("ANY");
2800
2801   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2802
2803   if (GST_PAD_PAD_TEMPLATE (pad))
2804     return GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
2805
2806   return gst_static_caps_get (&anycaps);
2807 }
2808
2809 /**
2810  * gst_pad_get_peer:
2811  * @pad: a #GstPad to get the peer of.
2812  *
2813  * Gets the peer of @pad. This function refs the peer pad so
2814  * you need to unref it after use.
2815  *
2816  * Returns: the peer #GstPad. Unref after usage.
2817  *
2818  * MT safe.
2819  */
2820 GstPad *
2821 gst_pad_get_peer (GstPad * pad)
2822 {
2823   GstPad *result;
2824
2825   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2826
2827   GST_OBJECT_LOCK (pad);
2828   result = GST_PAD_PEER (pad);
2829   if (result)
2830     gst_object_ref (result);
2831   GST_OBJECT_UNLOCK (pad);
2832
2833   return result;
2834 }
2835
2836 /**
2837  * gst_pad_get_allowed_caps:
2838  * @pad: a #GstPad.
2839  *
2840  * Gets the capabilities of the allowed media types that can flow through
2841  * @pad and its peer.
2842  *
2843  * The allowed capabilities is calculated as the intersection of the results of
2844  * calling gst_pad_get_caps() on @pad and its peer. The caller owns a reference
2845  * on the resulting caps.
2846  *
2847  * Returns: the allowed #GstCaps of the pad link. Unref the caps when you no
2848  * longer need it. This function returns NULL when @pad has no peer.
2849  *
2850  * MT safe.
2851  */
2852 GstCaps *
2853 gst_pad_get_allowed_caps (GstPad * pad)
2854 {
2855   GstCaps *mycaps;
2856   GstCaps *caps;
2857   GstCaps *peercaps;
2858   GstPad *peer;
2859
2860   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2861
2862   GST_OBJECT_LOCK (pad);
2863
2864   peer = GST_PAD_PEER (pad);
2865   if (G_UNLIKELY (peer == NULL))
2866     goto no_peer;
2867
2868   GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting allowed caps");
2869
2870   gst_object_ref (peer);
2871   GST_OBJECT_UNLOCK (pad);
2872   mycaps = gst_pad_get_caps_reffed (pad);
2873
2874   peercaps = gst_pad_get_caps_reffed (peer);
2875   gst_object_unref (peer);
2876
2877   caps = gst_caps_intersect (mycaps, peercaps);
2878   gst_caps_unref (peercaps);
2879   gst_caps_unref (mycaps);
2880
2881   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "allowed caps %" GST_PTR_FORMAT,
2882       caps);
2883
2884   return caps;
2885
2886 no_peer:
2887   {
2888     GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
2889     GST_OBJECT_UNLOCK (pad);
2890
2891     return NULL;
2892   }
2893 }
2894
2895 /**
2896  * gst_pad_get_negotiated_caps:
2897  * @pad: a #GstPad.
2898  *
2899  * Gets the capabilities of the media type that currently flows through @pad
2900  * and its peer.
2901  *
2902  * This function can be used on both src and sinkpads. Note that srcpads are
2903  * always negotiated before sinkpads so it is possible that the negotiated caps
2904  * on the srcpad do not match the negotiated caps of the peer.
2905  *
2906  * Returns: the negotiated #GstCaps of the pad link.  Unref the caps when
2907  * you no longer need it. This function returns NULL when the @pad has no
2908  * peer or is not negotiated yet.
2909  *
2910  * MT safe.
2911  */
2912 GstCaps *
2913 gst_pad_get_negotiated_caps (GstPad * pad)
2914 {
2915   GstCaps *caps;
2916   GstPad *peer;
2917
2918   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2919
2920   GST_OBJECT_LOCK (pad);
2921
2922   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2923     goto no_peer;
2924
2925   GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting negotiated caps");
2926
2927   caps = GST_PAD_CAPS (pad);
2928   if (caps)
2929     gst_caps_ref (caps);
2930   GST_OBJECT_UNLOCK (pad);
2931
2932   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "negotiated caps %" GST_PTR_FORMAT,
2933       caps);
2934
2935   return caps;
2936
2937 no_peer:
2938   {
2939     GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
2940     GST_OBJECT_UNLOCK (pad);
2941
2942     return NULL;
2943   }
2944 }
2945
2946 /* calls the buffer_alloc function on the given pad */
2947 static GstFlowReturn
2948 gst_pad_buffer_alloc_unchecked (GstPad * pad, guint64 offset, gint size,
2949     GstCaps * caps, GstBuffer ** buf)
2950 {
2951   GstFlowReturn ret;
2952   GstPadBufferAllocFunction bufferallocfunc;
2953
2954   GST_OBJECT_LOCK (pad);
2955   /* when the pad is flushing we cannot give a buffer */
2956   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
2957     goto flushing;
2958
2959   bufferallocfunc = pad->bufferallocfunc;
2960
2961   if (offset == GST_BUFFER_OFFSET_NONE) {
2962     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2963         "calling bufferallocfunc &%s (@%p) for size %d offset NONE",
2964         GST_DEBUG_FUNCPTR_NAME (bufferallocfunc), bufferallocfunc, size);
2965   } else {
2966     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2967         "calling bufferallocfunc &%s (@%p) of for size %d offset %"
2968         G_GUINT64_FORMAT, GST_DEBUG_FUNCPTR_NAME (bufferallocfunc),
2969         bufferallocfunc, size, offset);
2970   }
2971   GST_OBJECT_UNLOCK (pad);
2972
2973   /* G_LIKELY for now since most elements don't implement a buffer alloc
2974    * function and there is no default alloc proxy function as this is usually
2975    * not possible. */
2976   if (G_LIKELY (bufferallocfunc == NULL))
2977     goto fallback;
2978
2979   ret = bufferallocfunc (pad, offset, size, caps, buf);
2980
2981   if (G_UNLIKELY (ret != GST_FLOW_OK))
2982     goto error;
2983
2984   /* no error, but NULL buffer means fallback to the default */
2985   if (G_UNLIKELY (*buf == NULL))
2986     goto fallback;
2987
2988   /* If the buffer alloc function didn't set up the caps like it should,
2989    * do it for it */
2990   if (G_UNLIKELY (caps && (GST_BUFFER_CAPS (*buf) == NULL))) {
2991     GST_WARNING_OBJECT (pad,
2992         "Buffer allocation function did not set caps. Setting");
2993     gst_buffer_set_caps (*buf, caps);
2994   }
2995   return ret;
2996
2997 flushing:
2998   {
2999     /* pad was flushing */
3000     GST_OBJECT_UNLOCK (pad);
3001     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "pad was flushing");
3002     return GST_FLOW_WRONG_STATE;
3003   }
3004 error:
3005   {
3006     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
3007         "alloc function returned error (%d) %s", ret, gst_flow_get_name (ret));
3008     return ret;
3009   }
3010 fallback:
3011   {
3012     /* fallback case, allocate a buffer of our own, add pad caps. */
3013     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "fallback buffer alloc");
3014
3015     if ((*buf = gst_buffer_try_new_and_alloc (size))) {
3016       GST_BUFFER_OFFSET (*buf) = offset;
3017       gst_buffer_set_caps (*buf, caps);
3018       return GST_FLOW_OK;
3019     } else {
3020       GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
3021           "out of memory allocating %d bytes", size);
3022       return GST_FLOW_ERROR;
3023     }
3024   }
3025 }
3026
3027 /* FIXME 0.11: size should be unsigned */
3028 static GstFlowReturn
3029 gst_pad_alloc_buffer_full (GstPad * pad, guint64 offset, gint size,
3030     GstCaps * caps, GstBuffer ** buf, gboolean setcaps)
3031 {
3032   GstPad *peer;
3033   GstFlowReturn ret;
3034   GstCaps *newcaps;
3035   gboolean caps_changed;
3036
3037   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3038   g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
3039   g_return_val_if_fail (buf != NULL, GST_FLOW_ERROR);
3040   g_return_val_if_fail (size >= 0, GST_FLOW_ERROR);
3041
3042   GST_DEBUG_OBJECT (pad, "offset %" G_GUINT64_FORMAT ", size %d, caps %"
3043       GST_PTR_FORMAT, offset, size, caps);
3044
3045   GST_OBJECT_LOCK (pad);
3046   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
3047     if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
3048       goto flushed;
3049
3050   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3051     goto no_peer;
3052
3053   gst_object_ref (peer);
3054   GST_OBJECT_UNLOCK (pad);
3055
3056   ret = gst_pad_buffer_alloc_unchecked (peer, offset, size, caps, buf);
3057   gst_object_unref (peer);
3058
3059   if (G_UNLIKELY (ret != GST_FLOW_OK))
3060     goto peer_error;
3061
3062   /* FIXME, move capnego this into a base class? */
3063   newcaps = GST_BUFFER_CAPS (*buf);
3064
3065   /* Lock for checking caps, pretty pointless as the _pad_push() function might
3066    * change it concurrently, one of the problems with automatic caps setting in
3067    * pad_alloc_and_set_caps. Worst case, if does a check too much, but only
3068    * when there is heavy renegotiation going on in both directions. */
3069   GST_OBJECT_LOCK (pad);
3070   caps_changed = newcaps && newcaps != GST_PAD_CAPS (pad);
3071   GST_OBJECT_UNLOCK (pad);
3072
3073   /* we got a new datatype on the pad, see if it can handle it */
3074   if (G_UNLIKELY (caps_changed)) {
3075     GST_DEBUG_OBJECT (pad,
3076         "caps changed from %" GST_PTR_FORMAT " to %p %" GST_PTR_FORMAT,
3077         GST_PAD_CAPS (pad), newcaps, newcaps);
3078     if (G_UNLIKELY (!gst_pad_configure_src (pad, newcaps, setcaps)))
3079       goto not_negotiated;
3080   }
3081
3082   /* sanity check (only if caps are the same) */
3083   if (G_LIKELY (newcaps == caps) && G_UNLIKELY (GST_BUFFER_SIZE (*buf) < size))
3084     goto wrong_size_fallback;
3085
3086   return ret;
3087
3088 flushed:
3089   {
3090     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "pad block stopped by flush");
3091     GST_OBJECT_UNLOCK (pad);
3092     return ret;
3093   }
3094 no_peer:
3095   {
3096     /* pad has no peer */
3097     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
3098         "called bufferallocfunc but had no peer");
3099     GST_OBJECT_UNLOCK (pad);
3100     return GST_FLOW_NOT_LINKED;
3101   }
3102 peer_error:
3103   {
3104     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3105         "alloc function returned error %s", gst_flow_get_name (ret));
3106     return ret;
3107   }
3108 not_negotiated:
3109   {
3110     gst_buffer_unref (*buf);
3111     *buf = NULL;
3112     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3113         "alloc function returned unacceptable buffer");
3114     return GST_FLOW_NOT_NEGOTIATED;
3115   }
3116 wrong_size_fallback:
3117   {
3118     GST_CAT_ERROR_OBJECT (GST_CAT_PADS, pad, "buffer returned by alloc "
3119         "function is too small (%u < %d), doing fallback buffer alloc",
3120         GST_BUFFER_SIZE (*buf), size);
3121
3122     gst_buffer_unref (*buf);
3123
3124     if ((*buf = gst_buffer_try_new_and_alloc (size))) {
3125       GST_BUFFER_OFFSET (*buf) = offset;
3126       gst_buffer_set_caps (*buf, caps);
3127       return GST_FLOW_OK;
3128     } else {
3129       GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
3130           "out of memory allocating %d bytes", size);
3131       return GST_FLOW_ERROR;
3132     }
3133   }
3134 }
3135
3136 /**
3137  * gst_pad_alloc_buffer:
3138  * @pad: a source #GstPad
3139  * @offset: the offset of the new buffer in the stream
3140  * @size: the size of the new buffer
3141  * @caps: the caps of the new buffer
3142  * @buf: a newly allocated buffer
3143  *
3144  * Allocates a new, empty buffer optimized to push to pad @pad.  This
3145  * function only works if @pad is a source pad and has a peer.
3146  *
3147  * A new, empty #GstBuffer will be put in the @buf argument.
3148  * You need to check the caps of the buffer after performing this
3149  * function and renegotiate to the format if needed. If the caps changed, it is
3150  * possible that the buffer returned in @buf is not of the right size for the
3151  * new format, @buf needs to be unreffed and reallocated if this is the case.
3152  *
3153  * Returns: a result code indicating success of the operation. Any
3154  * result code other than #GST_FLOW_OK is an error and @buf should
3155  * not be used.
3156  * An error can occur if the pad is not connected or when the downstream
3157  * peer elements cannot provide an acceptable buffer.
3158  *
3159  * MT safe.
3160  */
3161
3162 /* FIXME 0.11: size should be unsigned */
3163 GstFlowReturn
3164 gst_pad_alloc_buffer (GstPad * pad, guint64 offset, gint size, GstCaps * caps,
3165     GstBuffer ** buf)
3166 {
3167   return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, FALSE);
3168 }
3169
3170 /**
3171  * gst_pad_alloc_buffer_and_set_caps:
3172  * @pad: a source #GstPad
3173  * @offset: the offset of the new buffer in the stream
3174  * @size: the size of the new buffer
3175  * @caps: the caps of the new buffer
3176  * @buf: a newly allocated buffer
3177  *
3178  * In addition to the function gst_pad_alloc_buffer(), this function
3179  * automatically calls gst_pad_set_caps() when the caps of the
3180  * newly allocated buffer are different from the @pad caps.
3181  *
3182  * After a renegotiation, the size of the new buffer returned in @buf could
3183  * be of the wrong size for the new format and must be unreffed an reallocated
3184  * in that case.
3185  *
3186  * Returns: a result code indicating success of the operation. Any
3187  * result code other than #GST_FLOW_OK is an error and @buf should
3188  * not be used.
3189  * An error can occur if the pad is not connected or when the downstream
3190  * peer elements cannot provide an acceptable buffer.
3191  *
3192  * MT safe.
3193  */
3194
3195 /* FIXME 0.11: size should be unsigned */
3196 GstFlowReturn
3197 gst_pad_alloc_buffer_and_set_caps (GstPad * pad, guint64 offset, gint size,
3198     GstCaps * caps, GstBuffer ** buf)
3199 {
3200   return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, TRUE);
3201 }
3202
3203
3204 #ifndef GST_REMOVE_DEPRECATED
3205 typedef struct
3206 {
3207   GList *list;
3208   guint32 cookie;
3209 } IntLinkIterData;
3210
3211 static void
3212 int_link_iter_data_free (IntLinkIterData * data)
3213 {
3214   g_list_free (data->list);
3215   g_slice_free (IntLinkIterData, data);
3216 }
3217 #endif
3218
3219 static GstIteratorItem
3220 iterate_pad (GstIterator * it, GstPad * pad)
3221 {
3222   gst_object_ref (pad);
3223   return GST_ITERATOR_ITEM_PASS;
3224 }
3225
3226 /**
3227  * gst_pad_iterate_internal_links_default:
3228  * @pad: the #GstPad to get the internal links of.
3229  *
3230  * Iterate the list of pads to which the given pad is linked to inside of
3231  * the parent element.
3232  * This is the default handler, and thus returns an iterator of all of the
3233  * pads inside the parent element with opposite direction.
3234  *
3235  * The caller must free this iterator after use with gst_iterator_free().
3236  *
3237  * Returns: a #GstIterator of #GstPad, or NULL if @pad has no parent. Unref each
3238  * returned pad with gst_object_unref().
3239  *
3240  * Since: 0.10.21
3241  */
3242 GstIterator *
3243 gst_pad_iterate_internal_links_default (GstPad * pad)
3244 {
3245   GstIterator *res;
3246   GList **padlist;
3247   guint32 *cookie;
3248   GMutex *lock;
3249   gpointer owner;
3250   GstIteratorDisposeFunction dispose;
3251
3252   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3253
3254 #ifndef GST_REMOVE_DEPRECATED
3255   /* when we get here, the default handler for the iterate links is called,
3256    * which means that the user has not installed a custom one. We first check if
3257    * there is maybe a custom legacy function we can call. */
3258   if (GST_PAD_INTLINKFUNC (pad) &&
3259       GST_PAD_INTLINKFUNC (pad) != gst_pad_get_internal_links_default) {
3260     IntLinkIterData *data;
3261
3262     /* make an iterator for the list. We can't protect the list with a
3263      * cookie. If we would take the cookie of the parent element, we need to
3264      * have a parent, which is not required for GST_PAD_INTLINKFUNC(). We could
3265      * cache the per-pad list and invalidate the list when a new call to
3266      * INTLINKFUNC() returned a different list but then this would only work if
3267      * two concurrent iterators were used and the last iterator would still be
3268      * thread-unsafe. Just don't use this method anymore. */
3269     data = g_slice_new (IntLinkIterData);
3270     data->list = GST_PAD_INTLINKFUNC (pad) (pad);
3271     data->cookie = 0;
3272
3273     GST_WARNING_OBJECT (pad, "Making unsafe iterator");
3274
3275     cookie = &data->cookie;
3276     padlist = &data->list;
3277     owner = data;
3278     dispose = (GstIteratorDisposeFunction) int_link_iter_data_free;
3279     /* reuse the pad lock, it's all we have here */
3280     lock = GST_OBJECT_GET_LOCK (pad);
3281   } else
3282 #endif
3283   {
3284     GstElement *parent;
3285
3286     GST_OBJECT_LOCK (pad);
3287     parent = GST_PAD_PARENT (pad);
3288     if (!parent || !GST_IS_ELEMENT (parent))
3289       goto no_parent;
3290
3291     gst_object_ref (parent);
3292     GST_OBJECT_UNLOCK (pad);
3293
3294     if (pad->direction == GST_PAD_SRC)
3295       padlist = &parent->sinkpads;
3296     else
3297       padlist = &parent->srcpads;
3298
3299     GST_DEBUG_OBJECT (pad, "Making iterator");
3300
3301     cookie = &parent->pads_cookie;
3302     owner = parent;
3303     dispose = (GstIteratorDisposeFunction) gst_object_unref;
3304     lock = GST_OBJECT_GET_LOCK (parent);
3305   }
3306
3307   res = gst_iterator_new_list (GST_TYPE_PAD,
3308       lock, cookie, padlist, owner, (GstIteratorItemFunction) iterate_pad,
3309       dispose);
3310
3311   return res;
3312
3313   /* ERRORS */
3314 no_parent:
3315   {
3316     GST_OBJECT_UNLOCK (pad);
3317     GST_DEBUG_OBJECT (pad, "no parent element");
3318     return NULL;
3319   }
3320 }
3321
3322 /**
3323  * gst_pad_iterate_internal_links:
3324  * @pad: the GstPad to get the internal links of.
3325  *
3326  * Gets an iterator for the pads to which the given pad is linked to inside
3327  * of the parent element.
3328  *
3329  * Each #GstPad element yielded by the iterator will have its refcount increased,
3330  * so unref after use.
3331  *
3332  * Returns: a new #GstIterator of #GstPad or %NULL when the pad does not have an
3333  * iterator function configured. Use gst_iterator_free() after usage.
3334  *
3335  * Since: 0.10.21
3336  */
3337 GstIterator *
3338 gst_pad_iterate_internal_links (GstPad * pad)
3339 {
3340   GstIterator *res = NULL;
3341
3342   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3343
3344   if (GST_PAD_ITERINTLINKFUNC (pad))
3345     res = GST_PAD_ITERINTLINKFUNC (pad) (pad);
3346
3347   return res;
3348 }
3349
3350 #ifndef GST_REMOVE_DEPRECATED
3351 static void
3352 add_unref_pad_to_list (GstPad * pad, GList ** list)
3353 {
3354   *list = g_list_prepend (*list, pad);
3355   gst_object_unref (pad);
3356 }
3357 #endif
3358
3359 /**
3360  * gst_pad_get_internal_links_default:
3361  * @pad: the #GstPad to get the internal links of.
3362  *
3363  * Gets a list of pads to which the given pad is linked to
3364  * inside of the parent element.
3365  * This is the default handler, and thus returns a list of all of the
3366  * pads inside the parent element with opposite direction.
3367  *
3368  * The caller must free this list after use with g_list_free().
3369  *
3370  * Returns: a newly allocated #GList of pads, or NULL if the pad has no parent.
3371  *
3372  * Not MT safe.
3373  *
3374  * Deprecated: This function does not ref the pads in the list so that they
3375  * could become invalid by the time the application accesses them. It's also
3376  * possible that the list changes while handling the pads, which the caller of
3377  * this function is unable to know. Use the thread-safe
3378  * gst_pad_iterate_internal_links_default() instead.
3379  */
3380 #ifndef GST_REMOVE_DEPRECATED
3381 GList *
3382 gst_pad_get_internal_links_default (GstPad * pad)
3383 {
3384   GList *res = NULL;
3385   GstElement *parent;
3386
3387   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3388
3389   GST_WARNING_OBJECT (pad, "Unsafe internal links used");
3390
3391   /* when we get here, the default handler for get_internal_links is called,
3392    * which means that the user has not installed a custom one. We first check if
3393    * there is maybe a custom iterate function we can call. */
3394   if (GST_PAD_ITERINTLINKFUNC (pad) &&
3395       GST_PAD_ITERINTLINKFUNC (pad) != gst_pad_iterate_internal_links_default) {
3396     GstIterator *it;
3397     GstIteratorResult ires;
3398     gboolean done = FALSE;
3399
3400     it = gst_pad_iterate_internal_links (pad);
3401     /* loop over the iterator and put all elements into a list, we also
3402      * immediatly unref them, which is bad. */
3403     do {
3404       ires = gst_iterator_foreach (it, (GFunc) add_unref_pad_to_list, &res);
3405       switch (ires) {
3406         case GST_ITERATOR_OK:
3407         case GST_ITERATOR_DONE:
3408         case GST_ITERATOR_ERROR:
3409           done = TRUE;
3410           break;
3411         case GST_ITERATOR_RESYNC:
3412           /* restart, discard previous list */
3413           gst_iterator_resync (it);
3414           g_list_free (res);
3415           res = NULL;
3416           break;
3417       }
3418     } while (!done);
3419
3420     gst_iterator_free (it);
3421   } else {
3422     /* lock pad, check and ref parent */
3423     GST_OBJECT_LOCK (pad);
3424     parent = GST_PAD_PARENT (pad);
3425     if (!parent || !GST_IS_ELEMENT (parent))
3426       goto no_parent;
3427
3428     parent = gst_object_ref (parent);
3429     GST_OBJECT_UNLOCK (pad);
3430
3431     /* now lock the parent while we copy the pads */
3432     GST_OBJECT_LOCK (parent);
3433     if (pad->direction == GST_PAD_SRC)
3434       res = g_list_copy (parent->sinkpads);
3435     else
3436       res = g_list_copy (parent->srcpads);
3437     GST_OBJECT_UNLOCK (parent);
3438
3439     gst_object_unref (parent);
3440   }
3441
3442   /* At this point pads can be changed and unreffed. Nothing we can do about it
3443    * because for compatibility reasons this function cannot ref the pads or
3444    * notify the app that the list changed. */
3445
3446   return res;
3447
3448 no_parent:
3449   {
3450     GST_DEBUG_OBJECT (pad, "no parent");
3451     GST_OBJECT_UNLOCK (pad);
3452     return NULL;
3453   }
3454 }
3455 #endif /* GST_REMOVE_DEPRECATED */
3456
3457 /**
3458  * gst_pad_get_internal_links:
3459  * @pad: the #GstPad to get the internal links of.
3460  *
3461  * Gets a list of pads to which the given pad is linked to
3462  * inside of the parent element.
3463  * The caller must free this list after use.
3464  *
3465  * Not MT safe.
3466  *
3467  * Returns: a newly allocated #GList of pads, free with g_list_free().
3468  *
3469  * Deprecated: This function does not ref the pads in the list so that they
3470  * could become invalid by the time the application accesses them. It's also
3471  * possible that the list changes while handling the pads, which the caller of
3472  * this function is unable to know. Use the thread-safe
3473  * gst_pad_iterate_internal_links() instead.
3474  */
3475 #ifndef GST_REMOVE_DEPRECATED
3476 #ifdef GST_DISABLE_DEPRECATED
3477 GList *gst_pad_get_internal_links (GstPad * pad);
3478 #endif
3479 GList *
3480 gst_pad_get_internal_links (GstPad * pad)
3481 {
3482   GList *res = NULL;
3483
3484   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3485
3486   GST_WARNING_OBJECT (pad, "Calling unsafe internal links");
3487
3488   if (GST_PAD_INTLINKFUNC (pad))
3489     res = GST_PAD_INTLINKFUNC (pad) (pad);
3490
3491   return res;
3492 }
3493 #endif /* GST_REMOVE_DEPRECATED */
3494
3495 static gboolean
3496 gst_pad_event_default_dispatch (GstPad * pad, GstEvent * event)
3497 {
3498   gboolean result = FALSE;
3499   GstIterator *iter;
3500   gboolean done = FALSE;
3501   gpointer item;
3502   GstPad *eventpad;
3503   GList *pushed_pads = NULL;
3504
3505   GST_INFO_OBJECT (pad, "Sending event %p (%s) to all internally linked pads",
3506       event, GST_EVENT_TYPE_NAME (event));
3507
3508   iter = gst_pad_iterate_internal_links (pad);
3509
3510   if (!iter)
3511     goto no_iter;
3512
3513   while (!done) {
3514     switch (gst_iterator_next (iter, &item)) {
3515       case GST_ITERATOR_OK:
3516         eventpad = GST_PAD_CAST (item);
3517
3518         /* if already pushed,  skip */
3519         if (g_list_find (pushed_pads, eventpad)) {
3520           gst_object_unref (item);
3521           break;
3522         }
3523
3524         if (GST_PAD_IS_SRC (eventpad)) {
3525           /* for each pad we send to, we should ref the event; it's up
3526            * to downstream to unref again when handled. */
3527           GST_LOG_OBJECT (pad, "Reffing and sending event %p (%s) to %s:%s",
3528               event, GST_EVENT_TYPE_NAME (event),
3529               GST_DEBUG_PAD_NAME (eventpad));
3530           gst_event_ref (event);
3531           result |= gst_pad_push_event (eventpad, event);
3532         } else {
3533           /* we only send the event on one pad, multi-sinkpad elements
3534            * should implement a handler */
3535           GST_LOG_OBJECT (pad, "sending event %p (%s) to one sink pad %s:%s",
3536               event, GST_EVENT_TYPE_NAME (event),
3537               GST_DEBUG_PAD_NAME (eventpad));
3538           result = gst_pad_push_event (eventpad, event);
3539           done = TRUE;
3540           event = NULL;
3541         }
3542
3543         pushed_pads = g_list_prepend (pushed_pads, eventpad);
3544
3545         gst_object_unref (item);
3546         break;
3547       case GST_ITERATOR_RESYNC:
3548         /* FIXME, if we want to reset the result value we need to remember which
3549          * pads pushed with which result */
3550         gst_iterator_resync (iter);
3551         break;
3552       case GST_ITERATOR_ERROR:
3553         GST_ERROR_OBJECT (pad, "Could not iterate over internally linked pads");
3554         done = TRUE;
3555         break;
3556       case GST_ITERATOR_DONE:
3557         done = TRUE;
3558         break;
3559     }
3560   }
3561   gst_iterator_free (iter);
3562
3563 no_iter:
3564
3565   /* If this is a sinkpad and we don't have pads to send the event to, we
3566    * return TRUE. This is so that when using the default handler on a sink
3567    * element, we don't fail to push it. */
3568   if (!pushed_pads)
3569     result = GST_PAD_IS_SINK (pad);
3570
3571   g_list_free (pushed_pads);
3572
3573   /* we handled the incoming event so we unref once */
3574   if (event) {
3575     GST_LOG_OBJECT (pad, "handled event %p, unreffing", event);
3576     gst_event_unref (event);
3577   }
3578
3579   return result;
3580 }
3581
3582 /**
3583  * gst_pad_event_default:
3584  * @pad: a #GstPad to call the default event handler on.
3585  * @event: the #GstEvent to handle.
3586  *
3587  * Invokes the default event handler for the given pad. End-of-stream and
3588  * discontinuity events are handled specially, and then the event is sent to all
3589  * pads internally linked to @pad. Note that if there are many possible sink
3590  * pads that are internally linked to @pad, only one will be sent an event.
3591  * Multi-sinkpad elements should implement custom event handlers.
3592  *
3593  * Returns: TRUE if the event was sent succesfully.
3594  */
3595 gboolean
3596 gst_pad_event_default (GstPad * pad, GstEvent * event)
3597 {
3598   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3599   g_return_val_if_fail (event != NULL, FALSE);
3600
3601   GST_LOG_OBJECT (pad, "default event handler");
3602
3603   switch (GST_EVENT_TYPE (event)) {
3604     case GST_EVENT_EOS:
3605     {
3606       GST_DEBUG_OBJECT (pad, "pausing task because of eos");
3607       gst_pad_pause_task (pad);
3608     }
3609       /* fall thru */
3610     default:
3611       break;
3612   }
3613
3614   return gst_pad_event_default_dispatch (pad, event);
3615 }
3616
3617 /**
3618  * gst_pad_dispatcher:
3619  * @pad: a #GstPad to dispatch.
3620  * @dispatch: the #GstPadDispatcherFunction to call.
3621  * @data: gpointer user data passed to the dispatcher function.
3622  *
3623  * Invokes the given dispatcher function on each respective peer of
3624  * all pads that are internally linked to the given pad.
3625  * The GstPadDispatcherFunction should return TRUE when no further pads
3626  * need to be processed.
3627  *
3628  * Returns: TRUE if one of the dispatcher functions returned TRUE.
3629  */
3630 gboolean
3631 gst_pad_dispatcher (GstPad * pad, GstPadDispatcherFunction dispatch,
3632     gpointer data)
3633 {
3634   gboolean res = FALSE;
3635   GstIterator *iter = NULL;
3636   gboolean done = FALSE;
3637   gpointer item;
3638
3639   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3640   g_return_val_if_fail (dispatch != NULL, FALSE);
3641
3642   iter = gst_pad_iterate_internal_links (pad);
3643
3644   if (!iter)
3645     goto no_iter;
3646
3647   while (!done) {
3648     switch (gst_iterator_next (iter, &item)) {
3649       case GST_ITERATOR_OK:
3650       {
3651         GstPad *int_pad = GST_PAD_CAST (item);
3652         GstPad *int_peer = gst_pad_get_peer (int_pad);
3653
3654         if (int_peer) {
3655           GST_DEBUG_OBJECT (int_pad, "dispatching to peer %s:%s",
3656               GST_DEBUG_PAD_NAME (int_peer));
3657           done = res = dispatch (int_peer, data);
3658           gst_object_unref (int_peer);
3659         } else {
3660           GST_DEBUG_OBJECT (int_pad, "no peer");
3661         }
3662       }
3663         gst_object_unref (item);
3664         break;
3665       case GST_ITERATOR_RESYNC:
3666         gst_iterator_resync (iter);
3667         break;
3668       case GST_ITERATOR_ERROR:
3669         done = TRUE;
3670         GST_ERROR_OBJECT (pad, "Could not iterate internally linked pads");
3671         break;
3672       case GST_ITERATOR_DONE:
3673         done = TRUE;
3674         break;
3675     }
3676   }
3677   gst_iterator_free (iter);
3678
3679   GST_DEBUG_OBJECT (pad, "done, result %d", res);
3680
3681 no_iter:
3682
3683   return res;
3684 }
3685
3686 /**
3687  * gst_pad_query:
3688  * @pad: a #GstPad to invoke the default query on.
3689  * @query: the #GstQuery to perform.
3690  *
3691  * Dispatches a query to a pad. The query should have been allocated by the
3692  * caller via one of the type-specific allocation functions. The element that
3693  * the pad belongs to is responsible for filling the query with an appropriate
3694  * response, which should then be parsed with a type-specific query parsing
3695  * function.
3696  *
3697  * Again, the caller is responsible for both the allocation and deallocation of
3698  * the query structure.
3699  *
3700  * Please also note that some queries might need a running pipeline to work.
3701  *
3702  * Returns: TRUE if the query could be performed.
3703  */
3704 gboolean
3705 gst_pad_query (GstPad * pad, GstQuery * query)
3706 {
3707   GstPadQueryFunction func;
3708
3709   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3710   g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
3711
3712   GST_DEBUG_OBJECT (pad, "sending query %p", query);
3713
3714   if ((func = GST_PAD_QUERYFUNC (pad)) == NULL)
3715     goto no_func;
3716
3717   return func (pad, query);
3718
3719 no_func:
3720   {
3721     GST_DEBUG_OBJECT (pad, "had no query function");
3722     return FALSE;
3723   }
3724 }
3725
3726 /**
3727  * gst_pad_peer_query:
3728  * @pad: a #GstPad to invoke the peer query on.
3729  * @query: the #GstQuery to perform.
3730  *
3731  * Performs gst_pad_query() on the peer of @pad.
3732  *
3733  * The caller is responsible for both the allocation and deallocation of
3734  * the query structure.
3735  *
3736  * Returns: TRUE if the query could be performed. This function returns %FALSE
3737  * if @pad has no peer.
3738  *
3739  * Since: 0.10.15
3740  */
3741 gboolean
3742 gst_pad_peer_query (GstPad * pad, GstQuery * query)
3743 {
3744   GstPad *peerpad;
3745   gboolean result;
3746
3747   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3748   g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
3749
3750   GST_OBJECT_LOCK (pad);
3751
3752   GST_DEBUG_OBJECT (pad, "peer query");
3753
3754   peerpad = GST_PAD_PEER (pad);
3755   if (G_UNLIKELY (peerpad == NULL))
3756     goto no_peer;
3757
3758   gst_object_ref (peerpad);
3759   GST_OBJECT_UNLOCK (pad);
3760
3761   result = gst_pad_query (peerpad, query);
3762
3763   gst_object_unref (peerpad);
3764
3765   return result;
3766
3767   /* ERRORS */
3768 no_peer:
3769   {
3770     GST_WARNING_OBJECT (pad, "pad has no peer");
3771     GST_OBJECT_UNLOCK (pad);
3772     return FALSE;
3773   }
3774 }
3775
3776 /**
3777  * gst_pad_query_default:
3778  * @pad: a #GstPad to call the default query handler on.
3779  * @query: the #GstQuery to handle.
3780  *
3781  * Invokes the default query handler for the given pad.
3782  * The query is sent to all pads internally linked to @pad. Note that
3783  * if there are many possible sink pads that are internally linked to
3784  * @pad, only one will be sent the query.
3785  * Multi-sinkpad elements should implement custom query handlers.
3786  *
3787  * Returns: TRUE if the query was performed succesfully.
3788  */
3789 gboolean
3790 gst_pad_query_default (GstPad * pad, GstQuery * query)
3791 {
3792   switch (GST_QUERY_TYPE (query)) {
3793     case GST_QUERY_POSITION:
3794     case GST_QUERY_SEEKING:
3795     case GST_QUERY_FORMATS:
3796     case GST_QUERY_LATENCY:
3797     case GST_QUERY_JITTER:
3798     case GST_QUERY_RATE:
3799     case GST_QUERY_CONVERT:
3800     default:
3801       return gst_pad_dispatcher
3802           (pad, (GstPadDispatcherFunction) gst_pad_query, query);
3803   }
3804 }
3805
3806 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
3807 /* FIXME: why isn't this on a GstElement ? */
3808 /**
3809  * gst_pad_load_and_link:
3810  * @self: an #xmlNodePtr to read the description from.
3811  * @parent: the #GstObject element that owns the pad.
3812  *
3813  * Reads the pad definition from the XML node and links the given pad
3814  * in the element to a pad of an element up in the hierarchy.
3815  */
3816 void
3817 gst_pad_load_and_link (xmlNodePtr self, GstObject * parent)
3818 {
3819   xmlNodePtr field = self->xmlChildrenNode;
3820   GstPad *pad = NULL, *targetpad;
3821   GstPadTemplate *tmpl;
3822   gchar *peer = NULL;
3823   gchar **split;
3824   GstElement *target;
3825   GstObject *grandparent;
3826   gchar *name = NULL;
3827
3828   while (field) {
3829     if (!strcmp ((char *) field->name, "name")) {
3830       name = (gchar *) xmlNodeGetContent (field);
3831       pad = gst_element_get_static_pad (GST_ELEMENT (parent), name);
3832       if ((!pad) || ((tmpl = gst_pad_get_pad_template (pad))
3833               && (GST_PAD_REQUEST == GST_PAD_TEMPLATE_PRESENCE (tmpl))))
3834         pad = gst_element_get_request_pad (GST_ELEMENT (parent), name);
3835       g_free (name);
3836     } else if (!strcmp ((char *) field->name, "peer")) {
3837       peer = (gchar *) xmlNodeGetContent (field);
3838     }
3839     field = field->next;
3840   }
3841   g_return_if_fail (pad != NULL);
3842
3843   if (peer == NULL)
3844     return;
3845
3846   split = g_strsplit (peer, ".", 2);
3847
3848   if (split[0] == NULL || split[1] == NULL) {
3849     GST_CAT_DEBUG_OBJECT (GST_CAT_XML, pad,
3850         "Could not parse peer '%s', leaving unlinked", peer);
3851
3852     g_free (peer);
3853     return;
3854   }
3855   g_free (peer);
3856
3857   g_return_if_fail (split[0] != NULL);
3858   g_return_if_fail (split[1] != NULL);
3859
3860   grandparent = gst_object_get_parent (parent);
3861
3862   if (grandparent && GST_IS_BIN (grandparent)) {
3863     target = gst_bin_get_by_name_recurse_up (GST_BIN (grandparent), split[0]);
3864   } else
3865     goto cleanup;
3866
3867   if (target == NULL)
3868     goto cleanup;
3869
3870   targetpad = gst_element_get_static_pad (target, split[1]);
3871   if (!targetpad)
3872     targetpad = gst_element_get_request_pad (target, split[1]);
3873
3874   if (targetpad == NULL)
3875     goto cleanup;
3876
3877   if (gst_pad_get_direction (pad) == GST_PAD_SRC)
3878     gst_pad_link (pad, targetpad);
3879   else
3880     gst_pad_link (targetpad, pad);
3881
3882 cleanup:
3883   g_strfreev (split);
3884 }
3885
3886 /**
3887  * gst_pad_save_thyself:
3888  * @pad: a #GstPad to save.
3889  * @parent: the parent #xmlNodePtr to save the description in.
3890  *
3891  * Saves the pad into an xml representation.
3892  *
3893  * Returns: the #xmlNodePtr representation of the pad.
3894  */
3895 static xmlNodePtr
3896 gst_pad_save_thyself (GstObject * object, xmlNodePtr parent)
3897 {
3898   GstPad *pad;
3899   GstPad *peer;
3900
3901   g_return_val_if_fail (GST_IS_PAD (object), NULL);
3902
3903   pad = GST_PAD_CAST (object);
3904
3905   xmlNewChild (parent, NULL, (xmlChar *) "name",
3906       (xmlChar *) GST_PAD_NAME (pad));
3907
3908   if (GST_PAD_IS_SRC (pad)) {
3909     xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "source");
3910   } else if (GST_PAD_IS_SINK (pad)) {
3911     xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "sink");
3912   } else {
3913     xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "unknown");
3914   }
3915
3916   if (GST_PAD_PEER (pad) != NULL) {
3917     gchar *content;
3918
3919     peer = GST_PAD_PEER (pad);
3920     /* first check to see if the peer's parent's parent is the same */
3921     /* we just save it off */
3922     content = g_strdup_printf ("%s.%s",
3923         GST_OBJECT_NAME (GST_PAD_PARENT (peer)), GST_PAD_NAME (peer));
3924     xmlNewChild (parent, NULL, (xmlChar *) "peer", (xmlChar *) content);
3925     g_free (content);
3926   } else
3927     xmlNewChild (parent, NULL, (xmlChar *) "peer", NULL);
3928
3929   return parent;
3930 }
3931
3932 #if 0
3933 /**
3934  * gst_ghost_pad_save_thyself:
3935  * @pad: a ghost #GstPad to save.
3936  * @parent: the parent #xmlNodePtr to save the description in.
3937  *
3938  * Saves the ghost pad into an xml representation.
3939  *
3940  * Returns: the #xmlNodePtr representation of the pad.
3941  */
3942 xmlNodePtr
3943 gst_ghost_pad_save_thyself (GstPad * pad, xmlNodePtr parent)
3944 {
3945   xmlNodePtr self;
3946
3947   g_return_val_if_fail (GST_IS_GHOST_PAD (pad), NULL);
3948
3949   self = xmlNewChild (parent, NULL, (xmlChar *) "ghostpad", NULL);
3950   xmlNewChild (self, NULL, (xmlChar *) "name", (xmlChar *) GST_PAD_NAME (pad));
3951   xmlNewChild (self, NULL, (xmlChar *) "parent",
3952       (xmlChar *) GST_OBJECT_NAME (GST_PAD_PARENT (pad)));
3953
3954   /* FIXME FIXME FIXME! */
3955
3956   return self;
3957 }
3958 #endif /* 0 */
3959 #endif /* GST_DISABLE_LOADSAVE */
3960
3961 /*
3962  * should be called with pad OBJECT_LOCK and STREAM_LOCK held.
3963  * GST_PAD_IS_BLOCKED (pad) == TRUE when this function is
3964  * called.
3965  *
3966  * This function performs the pad blocking when an event, buffer push
3967  * or buffer_alloc is performed on a _SRC_ pad. It blocks the
3968  * streaming thread after informing the pad has been blocked.
3969  *
3970  * An application can with this method wait and block any streaming
3971  * thread and perform operations such as seeking or linking.
3972  *
3973  * Two methods are available for notifying the application of the
3974  * block:
3975  * - the callback method, which happens in the STREAMING thread with
3976  *   the STREAM_LOCK held. With this method, the most useful way of
3977  *   dealing with the callback is to post a message to the main thread
3978  *   where the pad block can then be handled outside of the streaming
3979  *   thread. With the last method one can perform all operations such
3980  *   as doing a state change, linking, unblocking, seeking etc on the
3981  *   pad.
3982  * - the GCond signal method, which makes any thread unblock when
3983  *   the pad block happens.
3984  *
3985  * During the actual blocking state, the GST_PAD_BLOCKING flag is set.
3986  * The GST_PAD_BLOCKING flag is unset when the pad was unblocked.
3987  *
3988  * MT safe.
3989  */
3990 static GstFlowReturn
3991 handle_pad_block (GstPad * pad)
3992 {
3993   GstPadBlockCallback callback;
3994   gpointer user_data;
3995   GstFlowReturn ret = GST_FLOW_OK;
3996
3997   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "signal block taken");
3998
3999   /* flushing, don't bother trying to block and return WRONG_STATE
4000    * right away */
4001   if (GST_PAD_IS_FLUSHING (pad))
4002     goto flushingnonref;
4003
4004   /* we grab an extra ref for the callbacks, this is probably not
4005    * needed (callback code does not have a ref and cannot unref). I
4006    * think this was done to make it possible to unref the element in
4007    * the callback, which is in the end totally impossible as it
4008    * requires grabbing the STREAM_LOCK and OBJECT_LOCK which are
4009    * all taken when calling this function. */
4010   gst_object_ref (pad);
4011
4012   while (GST_PAD_IS_BLOCKED (pad)) {
4013     do {
4014       /* we either have a callback installed to notify the block or
4015        * some other thread is doing a GCond wait. */
4016       callback = pad->block_callback;
4017       pad->abidata.ABI.block_callback_called = TRUE;
4018       if (callback) {
4019         /* there is a callback installed, call it. We release the
4020          * lock so that the callback can do something usefull with the
4021          * pad */
4022         user_data = pad->block_data;
4023         GST_OBJECT_UNLOCK (pad);
4024         callback (pad, TRUE, user_data);
4025         GST_OBJECT_LOCK (pad);
4026
4027         /* we released the lock, recheck flushing */
4028         if (GST_PAD_IS_FLUSHING (pad))
4029           goto flushing;
4030       } else {
4031         /* no callback, signal the thread that is doing a GCond wait
4032          * if any. */
4033         GST_PAD_BLOCK_BROADCAST (pad);
4034       }
4035     } while (pad->abidata.ABI.block_callback_called == FALSE
4036         && GST_PAD_IS_BLOCKED (pad));
4037
4038     /* OBJECT_LOCK could have been released when we did the callback, which
4039      * then could have made the pad unblock so we need to check the blocking
4040      * condition again.   */
4041     if (!GST_PAD_IS_BLOCKED (pad))
4042       break;
4043
4044     /* now we block the streaming thread. It can be unlocked when we
4045      * deactivate the pad (which will also set the FLUSHING flag) or
4046      * when the pad is unblocked. A flushing event will also unblock
4047      * the pad after setting the FLUSHING flag. */
4048     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4049         "Waiting to be unblocked or set flushing");
4050     GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKING);
4051     GST_PAD_BLOCK_WAIT (pad);
4052     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKING);
4053
4054     /* see if we got unblocked by a flush or not */
4055     if (GST_PAD_IS_FLUSHING (pad))
4056       goto flushing;
4057   }
4058
4059   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "got unblocked");
4060
4061   /* when we get here, the pad is unblocked again and we perform
4062    * the needed unblock code. */
4063   callback = pad->block_callback;
4064   if (callback) {
4065     /* we need to call the callback */
4066     user_data = pad->block_data;
4067     GST_OBJECT_UNLOCK (pad);
4068     callback (pad, FALSE, user_data);
4069     GST_OBJECT_LOCK (pad);
4070   } else {
4071     /* we need to signal the thread waiting on the GCond */
4072     GST_PAD_BLOCK_BROADCAST (pad);
4073   }
4074
4075   gst_object_unref (pad);
4076
4077   return ret;
4078
4079 flushingnonref:
4080   {
4081     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad was flushing");
4082     return GST_FLOW_WRONG_STATE;
4083   }
4084 flushing:
4085   {
4086     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad became flushing");
4087     gst_object_unref (pad);
4088     return GST_FLOW_WRONG_STATE;
4089   }
4090 }
4091
4092 /**********************************************************************
4093  * Data passing functions
4094  */
4095
4096 static gboolean
4097 gst_pad_emit_have_data_signal (GstPad * pad, GstMiniObject * obj)
4098 {
4099   GValue ret = { 0 };
4100   GValue args[2] = { {0}, {0} };
4101   gboolean res;
4102   GQuark detail;
4103
4104   /* init */
4105   g_value_init (&ret, G_TYPE_BOOLEAN);
4106   g_value_set_boolean (&ret, TRUE);
4107   g_value_init (&args[0], GST_TYPE_PAD);
4108   g_value_set_object (&args[0], pad);
4109   g_value_init (&args[1], GST_TYPE_MINI_OBJECT);
4110   gst_value_set_mini_object (&args[1], obj);
4111
4112   if (GST_IS_EVENT (obj))
4113     detail = event_quark;
4114   else
4115     detail = buffer_quark;
4116
4117   /* actually emit */
4118   g_signal_emitv (args, gst_pad_signals[PAD_HAVE_DATA], detail, &ret);
4119   res = g_value_get_boolean (&ret);
4120
4121   /* clean up */
4122   g_value_unset (&ret);
4123   g_value_unset (&args[0]);
4124   g_value_unset (&args[1]);
4125
4126   return res;
4127 }
4128
4129 static void
4130 gst_pad_data_unref (gboolean is_buffer, void *data)
4131 {
4132   if (G_LIKELY (is_buffer)) {
4133     gst_buffer_unref (data);
4134   } else {
4135     gst_buffer_list_unref (data);
4136   }
4137 }
4138
4139 static GstCaps *
4140 gst_pad_data_get_caps (gboolean is_buffer, void *data)
4141 {
4142   GstCaps *caps;
4143
4144   if (G_LIKELY (is_buffer)) {
4145     caps = GST_BUFFER_CAPS (data);
4146   } else {
4147     GstBuffer *buf;
4148
4149     if ((buf = gst_buffer_list_get (GST_BUFFER_LIST_CAST (data), 0, 0)))
4150       caps = GST_BUFFER_CAPS (buf);
4151     else
4152       caps = NULL;
4153   }
4154   return caps;
4155 }
4156
4157 /* this is the chain function that does not perform the additional argument
4158  * checking for that little extra speed.
4159  */
4160 static inline GstFlowReturn
4161 gst_pad_chain_data_unchecked (GstPad * pad, gboolean is_buffer, void *data,
4162     GstPadPushCache * cache)
4163 {
4164   GstCaps *caps;
4165   gboolean caps_changed;
4166   GstFlowReturn ret;
4167   gboolean emit_signal;
4168
4169   GST_PAD_STREAM_LOCK (pad);
4170
4171   GST_OBJECT_LOCK (pad);
4172   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4173     goto flushing;
4174
4175   caps = gst_pad_data_get_caps (is_buffer, data);
4176   caps_changed = caps && caps != GST_PAD_CAPS (pad);
4177
4178   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
4179   GST_OBJECT_UNLOCK (pad);
4180
4181   /* see if the signal should be emited, we emit before caps nego as
4182    * we might drop the buffer and do capsnego for nothing. */
4183   if (G_UNLIKELY (emit_signal)) {
4184     cache = NULL;
4185     if (G_LIKELY (is_buffer)) {
4186       if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (data)))
4187         goto dropping;
4188     } else {
4189       /* chain all groups in the buffer list one by one to avoid problems with
4190        * buffer probes that push buffers or events */
4191       goto chain_groups;
4192     }
4193   }
4194
4195   /* we got a new datatype on the pad, see if it can handle it */
4196   if (G_UNLIKELY (caps_changed)) {
4197     GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
4198     if (G_UNLIKELY (!gst_pad_configure_sink (pad, caps)))
4199       goto not_negotiated;
4200   }
4201
4202   /* NOTE: we read the chainfunc unlocked.
4203    * we cannot hold the lock for the pad so we might send
4204    * the data to the wrong function. This is not really a
4205    * problem since functions are assigned at creation time
4206    * and don't change that often... */
4207   if (G_LIKELY (is_buffer)) {
4208     GstPadChainFunction chainfunc;
4209
4210     if (G_UNLIKELY ((chainfunc = GST_PAD_CHAINFUNC (pad)) == NULL))
4211       goto no_function;
4212
4213     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4214         "calling chainfunction &%s", GST_DEBUG_FUNCPTR_NAME (chainfunc));
4215
4216     if (cache) {
4217       cache->peer = gst_object_ref (pad);
4218       cache->caps = caps ? gst_caps_ref (caps) : NULL;
4219       cache->chainfunc = chainfunc;
4220     }
4221
4222     ret = chainfunc (pad, GST_BUFFER_CAST (data));
4223
4224     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4225         "called chainfunction &%s, returned %s",
4226         GST_DEBUG_FUNCPTR_NAME (chainfunc), gst_flow_get_name (ret));
4227   } else {
4228     GstPadChainListFunction chainlistfunc;
4229
4230     if (G_UNLIKELY ((chainlistfunc = GST_PAD_CHAINLISTFUNC (pad)) == NULL))
4231       goto chain_groups;
4232
4233     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4234         "calling chainlistfunction &%s",
4235         GST_DEBUG_FUNCPTR_NAME (chainlistfunc));
4236
4237     ret = chainlistfunc (pad, GST_BUFFER_LIST_CAST (data));
4238
4239     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4240         "called chainlistfunction &%s, returned %s",
4241         GST_DEBUG_FUNCPTR_NAME (chainlistfunc), gst_flow_get_name (ret));
4242   }
4243
4244   GST_PAD_STREAM_UNLOCK (pad);
4245
4246   return ret;
4247
4248 chain_groups:
4249   {
4250     GstBufferList *list;
4251     GstBufferListIterator *it;
4252     GstBuffer *group;
4253
4254     GST_PAD_STREAM_UNLOCK (pad);
4255
4256     GST_INFO_OBJECT (pad, "chaining each group in list as a merged buffer");
4257
4258     list = GST_BUFFER_LIST_CAST (data);
4259     it = gst_buffer_list_iterate (list);
4260
4261     if (gst_buffer_list_iterator_next_group (it)) {
4262       do {
4263         group = gst_buffer_list_iterator_merge_group (it);
4264         if (group == NULL) {
4265           group = gst_buffer_new ();
4266           GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "chaining empty group");
4267         } else {
4268           GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "chaining group");
4269         }
4270         ret = gst_pad_chain_data_unchecked (pad, TRUE, group, NULL);
4271       } while (ret == GST_FLOW_OK && gst_buffer_list_iterator_next_group (it));
4272     } else {
4273       GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "chaining empty group");
4274       ret = gst_pad_chain_data_unchecked (pad, TRUE, gst_buffer_new (), NULL);
4275     }
4276
4277     gst_buffer_list_iterator_free (it);
4278     gst_buffer_list_unref (list);
4279
4280     return ret;
4281   }
4282
4283   /* ERRORS */
4284 flushing:
4285   {
4286     gst_pad_data_unref (is_buffer, data);
4287     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4288         "pushing, but pad was flushing");
4289     GST_OBJECT_UNLOCK (pad);
4290     GST_PAD_STREAM_UNLOCK (pad);
4291     return GST_FLOW_WRONG_STATE;
4292   }
4293 dropping:
4294   {
4295     gst_pad_data_unref (is_buffer, data);
4296     GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
4297     GST_PAD_STREAM_UNLOCK (pad);
4298     return GST_FLOW_OK;
4299   }
4300 not_negotiated:
4301   {
4302     gst_pad_data_unref (is_buffer, data);
4303     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4304         "pushing data but pad did not accept");
4305     GST_PAD_STREAM_UNLOCK (pad);
4306     return GST_FLOW_NOT_NEGOTIATED;
4307   }
4308 no_function:
4309   {
4310     gst_pad_data_unref (is_buffer, data);
4311     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4312         "pushing, but not chainhandler");
4313     GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
4314         ("push on pad %s:%s but it has no chainfunction",
4315             GST_DEBUG_PAD_NAME (pad)));
4316     GST_PAD_STREAM_UNLOCK (pad);
4317     return GST_FLOW_NOT_SUPPORTED;
4318   }
4319 }
4320
4321 /**
4322  * gst_pad_chain:
4323  * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
4324  * @buffer: the #GstBuffer to send, return GST_FLOW_ERROR if not.
4325  *
4326  * Chain a buffer to @pad.
4327  *
4328  * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
4329  *
4330  * If the caps on @buffer are different from the current caps on @pad, this
4331  * function will call any setcaps function (see gst_pad_set_setcaps_function())
4332  * installed on @pad. If the new caps are not acceptable for @pad, this
4333  * function returns #GST_FLOW_NOT_NEGOTIATED.
4334  *
4335  * The function proceeds calling the chain function installed on @pad (see
4336  * gst_pad_set_chain_function()) and the return value of that function is
4337  * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
4338  * chain function.
4339  *
4340  * In all cases, success or failure, the caller loses its reference to @buffer
4341  * after calling this function.
4342  *
4343  * Returns: a #GstFlowReturn from the pad.
4344  *
4345  * MT safe.
4346  */
4347 GstFlowReturn
4348 gst_pad_chain (GstPad * pad, GstBuffer * buffer)
4349 {
4350   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4351   g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
4352   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
4353
4354   return gst_pad_chain_data_unchecked (pad, TRUE, buffer, NULL);
4355 }
4356
4357 /**
4358  * gst_pad_chain_list:
4359  * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
4360  * @list: the #GstBufferList to send, return GST_FLOW_ERROR if not.
4361  *
4362  * Chain a bufferlist to @pad.
4363  *
4364  * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
4365  *
4366  * If the caps on the first buffer of @list are different from the current
4367  * caps on @pad, this function will call any setcaps function
4368  * (see gst_pad_set_setcaps_function()) installed on @pad. If the new caps
4369  * are not acceptable for @pad, this function returns #GST_FLOW_NOT_NEGOTIATED.
4370  *
4371  * The function proceeds calling the chainlist function installed on @pad (see
4372  * gst_pad_set_chain_list_function()) and the return value of that function is
4373  * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
4374  * chainlist function.
4375  *
4376  * In all cases, success or failure, the caller loses its reference to @list
4377  * after calling this function.
4378  *
4379  * MT safe.
4380  *
4381  * Returns: a #GstFlowReturn from the pad.
4382  *
4383  * Since: 0.10.24
4384  */
4385 GstFlowReturn
4386 gst_pad_chain_list (GstPad * pad, GstBufferList * list)
4387 {
4388   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4389   g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
4390   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), GST_FLOW_ERROR);
4391
4392   return gst_pad_chain_data_unchecked (pad, FALSE, list, NULL);
4393 }
4394
4395 static GstFlowReturn
4396 gst_pad_push_data (GstPad * pad, gboolean is_buffer, void *data,
4397     GstPadPushCache * cache)
4398 {
4399   GstPad *peer;
4400   GstFlowReturn ret;
4401   GstCaps *caps;
4402   gboolean caps_changed;
4403
4404   GST_OBJECT_LOCK (pad);
4405
4406   /* FIXME: this check can go away; pad_set_blocked could be implemented with
4407    * probes completely or probes with an extended pad block. */
4408   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
4409     if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
4410       goto flushed;
4411
4412   /* we emit signals on the pad arg, the peer will have a chance to
4413    * emit in the _chain() function */
4414   if (G_UNLIKELY (GST_PAD_DO_BUFFER_SIGNALS (pad) > 0)) {
4415     cache = NULL;
4416     /* unlock before emitting */
4417     GST_OBJECT_UNLOCK (pad);
4418
4419     if (G_LIKELY (is_buffer)) {
4420       /* if the signal handler returned FALSE, it means we should just drop the
4421        * buffer */
4422       if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (data)))
4423         goto dropped;
4424     } else {
4425       /* push all buffers in the list */
4426       goto push_groups;
4427     }
4428     GST_OBJECT_LOCK (pad);
4429   }
4430
4431   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
4432     goto not_linked;
4433
4434   /* Before pushing the buffer to the peer pad, ensure that caps
4435    * are set on this pad */
4436   caps = gst_pad_data_get_caps (is_buffer, data);
4437   caps_changed = caps && caps != GST_PAD_CAPS (pad);
4438
4439   /* take ref to peer pad before releasing the lock */
4440   gst_object_ref (peer);
4441   GST_OBJECT_UNLOCK (pad);
4442
4443   /* we got a new datatype from the pad, it had better handle it */
4444   if (G_UNLIKELY (caps_changed)) {
4445     GST_DEBUG_OBJECT (pad,
4446         "caps changed from %" GST_PTR_FORMAT " to %p %" GST_PTR_FORMAT,
4447         GST_PAD_CAPS (pad), caps, caps);
4448     if (G_UNLIKELY (!gst_pad_set_caps (pad, caps)))
4449       goto not_negotiated;
4450   }
4451
4452   ret = gst_pad_chain_data_unchecked (peer, is_buffer, data, cache);
4453
4454   gst_object_unref (peer);
4455
4456   return ret;
4457
4458 push_groups:
4459   {
4460     GstBufferList *list;
4461     GstBufferListIterator *it;
4462     GstBuffer *group;
4463
4464     GST_INFO_OBJECT (pad, "pushing each group in list as a merged buffer");
4465
4466     list = GST_BUFFER_LIST_CAST (data);
4467     it = gst_buffer_list_iterate (list);
4468
4469     if (gst_buffer_list_iterator_next_group (it)) {
4470       do {
4471         group = gst_buffer_list_iterator_merge_group (it);
4472         if (group == NULL) {
4473           group = gst_buffer_new ();
4474           GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "pushing empty group");
4475         } else {
4476           GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "pushing group");
4477         }
4478         ret = gst_pad_push_data (pad, TRUE, group, NULL);
4479       } while (ret == GST_FLOW_OK && gst_buffer_list_iterator_next_group (it));
4480     } else {
4481       GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "pushing empty group");
4482       ret = gst_pad_push_data (pad, TRUE, gst_buffer_new (), NULL);
4483     }
4484
4485     gst_buffer_list_iterator_free (it);
4486     gst_buffer_list_unref (list);
4487
4488     return ret;
4489   }
4490
4491   /* ERROR recovery here */
4492 flushed:
4493   {
4494     gst_pad_data_unref (is_buffer, data);
4495     GST_DEBUG_OBJECT (pad, "pad block stopped by flush");
4496     GST_OBJECT_UNLOCK (pad);
4497     return ret;
4498   }
4499 dropped:
4500   {
4501     gst_pad_data_unref (is_buffer, data);
4502     GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
4503     return GST_FLOW_OK;
4504   }
4505 not_linked:
4506   {
4507     gst_pad_data_unref (is_buffer, data);
4508     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4509         "pushing, but it was not linked");
4510     GST_OBJECT_UNLOCK (pad);
4511     return GST_FLOW_NOT_LINKED;
4512   }
4513 not_negotiated:
4514   {
4515     gst_pad_data_unref (is_buffer, data);
4516     gst_object_unref (peer);
4517     GST_CAT_DEBUG_OBJECT (GST_CAT_SCHEDULING, pad,
4518         "element pushed data then refused to accept the caps");
4519     return GST_FLOW_NOT_NEGOTIATED;
4520   }
4521 }
4522
4523 static inline GstPadPushCache *
4524 pad_take_cache (GstPad * pad, gpointer * cache_ptr)
4525 {
4526   GstPadPushCache *cache;
4527
4528   /* try to get the cached data */
4529   do {
4530     cache = g_atomic_pointer_get (cache_ptr);
4531     /* now try to replace the pointer with NULL to mark that we are busy
4532      * with it */
4533   } while (!g_atomic_pointer_compare_and_exchange (cache_ptr, cache, NULL));
4534
4535   /* we could have a leftover invalid entry */
4536   if (G_UNLIKELY (cache == PAD_CACHE_INVALID))
4537     cache = NULL;
4538
4539   return cache;
4540 }
4541
4542 static inline void
4543 pad_free_cache (GstPadPushCache * cache)
4544 {
4545   gst_object_unref (cache->peer);
4546   if (cache->caps)
4547     gst_caps_unref (cache->caps);
4548   g_slice_free (GstPadPushCache, cache);
4549 }
4550
4551 static inline void
4552 pad_put_cache (GstPad * pad, GstPadPushCache * cache, gpointer * cache_ptr)
4553 {
4554   /* put it back */
4555   if (!g_atomic_pointer_compare_and_exchange (cache_ptr, NULL, cache)) {
4556     /* something changed, clean up our cache */
4557     pad_free_cache (cache);
4558   }
4559 }
4560
4561 /* must be called with the pad lock */
4562 void
4563 _priv_gst_pad_invalidate_cache (GstPad * pad)
4564 {
4565   GstPadPushCache *cache;
4566   gpointer *cache_ptr;
4567
4568   GST_LOG_OBJECT (pad, "Invalidating pad cache");
4569
4570   /* we hold the pad lock here so we can get the peer and it stays
4571    * alive during this call */
4572   if (GST_PAD_IS_SINK (pad)) {
4573     if (!(pad = GST_PAD_PEER (pad)))
4574       return;
4575   }
4576
4577   cache_ptr = (gpointer *) & pad->abidata.ABI.priv->cache_ptr;
4578
4579   /* try to get the cached data */
4580   do {
4581     cache = g_atomic_pointer_get (cache_ptr);
4582     /* now try to replace the pointer with INVALID. If nothing is busy with this
4583      * caps, we get the cache and clean it up. If something is busy, we replace
4584      * with INVALID so that when the function finishes and tries to put the
4585      * cache back, it'll fail and cleanup */
4586   } while (!g_atomic_pointer_compare_and_exchange (cache_ptr, cache,
4587           PAD_CACHE_INVALID));
4588
4589   if (G_LIKELY (cache && cache != PAD_CACHE_INVALID))
4590     pad_free_cache (cache);
4591 }
4592
4593 /**
4594  * gst_pad_push:
4595  * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
4596  * @buffer: the #GstBuffer to push returns GST_FLOW_ERROR if not.
4597  *
4598  * Pushes a buffer to the peer of @pad.
4599  *
4600  * This function will call an installed pad block before triggering any
4601  * installed pad probes.
4602  *
4603  * If the caps on @buffer are different from the currently configured caps on
4604  * @pad, this function will call any installed setcaps function on @pad (see
4605  * gst_pad_set_setcaps_function()). In case of failure to renegotiate the new
4606  * format, this function returns #GST_FLOW_NOT_NEGOTIATED.
4607  *
4608  * The function proceeds calling gst_pad_chain() on the peer pad and returns
4609  * the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will
4610  * be returned.
4611  *
4612  * In all cases, success or failure, the caller loses its reference to @buffer
4613  * after calling this function.
4614  *
4615  * Returns: a #GstFlowReturn from the peer pad.
4616  *
4617  * MT safe.
4618  */
4619 GstFlowReturn
4620 gst_pad_push (GstPad * pad, GstBuffer * buffer)
4621 {
4622   GstPadPushCache *cache;
4623   GstFlowReturn ret;
4624   gpointer *cache_ptr;
4625   GstPad *peer;
4626   GstCaps *caps;
4627
4628   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4629   g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4630   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
4631
4632   cache_ptr = (gpointer *) & pad->abidata.ABI.priv->cache_ptr;
4633
4634   cache = pad_take_cache (pad, cache_ptr);
4635
4636   if (G_UNLIKELY (cache == NULL))
4637     goto slow_path;
4638
4639   /* check caps */
4640   caps = GST_BUFFER_CAPS (buffer);
4641   if (G_UNLIKELY (caps && caps != cache->caps)) {
4642     pad_free_cache (cache);
4643     goto slow_path;
4644   }
4645
4646   peer = cache->peer;
4647
4648   GST_PAD_STREAM_LOCK (peer);
4649
4650   ret = cache->chainfunc (peer, buffer);
4651
4652   GST_PAD_STREAM_UNLOCK (peer);
4653
4654   pad_put_cache (pad, cache, cache_ptr);
4655
4656   return ret;
4657
4658   /* slow path */
4659 slow_path:
4660   {
4661     GstPadPushCache scache = { NULL, };
4662
4663     GST_LOG_OBJECT (pad, "Taking slow path");
4664
4665     ret = gst_pad_push_data (pad, TRUE, buffer, &scache);
4666
4667     if (scache.peer) {
4668       GstPadPushCache *ncache;
4669
4670       GST_LOG_OBJECT (pad, "Caching push data");
4671
4672       /* make cache structure */
4673       ncache = g_slice_new (GstPadPushCache);
4674       *ncache = scache;
4675
4676       pad_put_cache (pad, ncache, cache_ptr);
4677     }
4678     return ret;
4679   }
4680 }
4681
4682 /**
4683  * gst_pad_push_list:
4684  * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
4685  * @list: the #GstBufferList to push returns GST_FLOW_ERROR if not.
4686  *
4687  * Pushes a buffer list to the peer of @pad.
4688  *
4689  * This function will call an installed pad block before triggering any
4690  * installed pad probes.
4691  *
4692  * If the caps on the first buffer in the first group of @list are different
4693  * from the currently configured caps on @pad, this function will call any
4694  * installed setcaps function on @pad (see gst_pad_set_setcaps_function()). In
4695  * case of failure to renegotiate the new format, this function returns
4696  * #GST_FLOW_NOT_NEGOTIATED.
4697  *
4698  * If there are any probes installed on @pad every group of the buffer list
4699  * will be merged into a normal #GstBuffer and pushed via gst_pad_push and the
4700  * buffer list will be unreffed.
4701  *
4702  * The function proceeds calling the chain function on the peer pad and returns
4703  * the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will
4704  * be returned. If the peer pad does not have any installed chainlist function
4705  * every group buffer of the list will be merged into a normal #GstBuffer and
4706  * chained via gst_pad_chain().
4707  *
4708  * In all cases, success or failure, the caller loses its reference to @list
4709  * after calling this function.
4710  *
4711  * Returns: a #GstFlowReturn from the peer pad.
4712  *
4713  * MT safe.
4714  *
4715  * Since: 0.10.24
4716  */
4717 GstFlowReturn
4718 gst_pad_push_list (GstPad * pad, GstBufferList * list)
4719 {
4720   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4721   g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4722   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), GST_FLOW_ERROR);
4723
4724   return gst_pad_push_data (pad, FALSE, list, NULL);
4725 }
4726
4727 /**
4728  * gst_pad_check_pull_range:
4729  * @pad: a sink #GstPad.
4730  *
4731  * Checks if a gst_pad_pull_range() can be performed on the peer
4732  * source pad. This function is used by plugins that want to check
4733  * if they can use random access on the peer source pad.
4734  *
4735  * The peer sourcepad can implement a custom #GstPadCheckGetRangeFunction
4736  * if it needs to perform some logic to determine if pull_range is
4737  * possible.
4738  *
4739  * Returns: a gboolean with the result.
4740  *
4741  * MT safe.
4742  */
4743 gboolean
4744 gst_pad_check_pull_range (GstPad * pad)
4745 {
4746   GstPad *peer;
4747   gboolean ret;
4748   GstPadCheckGetRangeFunction checkgetrangefunc;
4749
4750   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4751
4752   GST_OBJECT_LOCK (pad);
4753   if (!GST_PAD_IS_SINK (pad))
4754     goto wrong_direction;
4755
4756   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
4757     goto not_connected;
4758
4759   gst_object_ref (peer);
4760   GST_OBJECT_UNLOCK (pad);
4761
4762   /* see note in above function */
4763   if (G_LIKELY ((checkgetrangefunc = peer->checkgetrangefunc) == NULL)) {
4764     /* FIXME, kindoff ghetto */
4765     ret = GST_PAD_GETRANGEFUNC (peer) != NULL;
4766     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4767         "no checkgetrangefunc, assuming %d", ret);
4768   } else {
4769     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4770         "calling checkgetrangefunc %s of peer pad %s:%s",
4771         GST_DEBUG_FUNCPTR_NAME (checkgetrangefunc), GST_DEBUG_PAD_NAME (peer));
4772
4773     ret = checkgetrangefunc (peer);
4774   }
4775
4776   gst_object_unref (peer);
4777
4778   return ret;
4779
4780   /* ERROR recovery here */
4781 wrong_direction:
4782   {
4783     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4784         "checking pull range, but pad must be a sinkpad");
4785     GST_OBJECT_UNLOCK (pad);
4786     return FALSE;
4787   }
4788 not_connected:
4789   {
4790     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4791         "checking pull range, but it was not linked");
4792     GST_OBJECT_UNLOCK (pad);
4793     return FALSE;
4794   }
4795 }
4796
4797 static GstFlowReturn
4798 gst_pad_get_range_unchecked (GstPad * pad, guint64 offset, guint size,
4799     GstBuffer ** buffer)
4800 {
4801   GstFlowReturn ret;
4802   GstPadGetRangeFunction getrangefunc;
4803   gboolean emit_signal;
4804   GstCaps *caps;
4805   gboolean caps_changed;
4806
4807   GST_PAD_STREAM_LOCK (pad);
4808
4809   GST_OBJECT_LOCK (pad);
4810   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4811     goto flushing;
4812
4813   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
4814   GST_OBJECT_UNLOCK (pad);
4815
4816   if (G_UNLIKELY ((getrangefunc = GST_PAD_GETRANGEFUNC (pad)) == NULL))
4817     goto no_function;
4818
4819   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4820       "calling getrangefunc %s, offset %"
4821       G_GUINT64_FORMAT ", size %u",
4822       GST_DEBUG_FUNCPTR_NAME (getrangefunc), offset, size);
4823
4824   ret = getrangefunc (pad, offset, size, buffer);
4825
4826   /* can only fire the signal if we have a valid buffer */
4827   if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
4828     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
4829       goto dropping;
4830   }
4831
4832   GST_PAD_STREAM_UNLOCK (pad);
4833
4834   if (G_UNLIKELY (ret != GST_FLOW_OK))
4835     goto get_range_failed;
4836
4837   GST_OBJECT_LOCK (pad);
4838   /* Before pushing the buffer to the peer pad, ensure that caps
4839    * are set on this pad */
4840   caps = GST_BUFFER_CAPS (*buffer);
4841   caps_changed = caps && caps != GST_PAD_CAPS (pad);
4842   GST_OBJECT_UNLOCK (pad);
4843
4844   if (G_UNLIKELY (caps_changed)) {
4845     GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
4846     /* this should usually work because the element produced the buffer */
4847     if (G_UNLIKELY (!gst_pad_configure_src (pad, caps, TRUE)))
4848       goto not_negotiated;
4849   }
4850   return ret;
4851
4852   /* ERRORS */
4853 flushing:
4854   {
4855     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4856         "pulling range, but pad was flushing");
4857     GST_OBJECT_UNLOCK (pad);
4858     GST_PAD_STREAM_UNLOCK (pad);
4859     return GST_FLOW_WRONG_STATE;
4860   }
4861 no_function:
4862   {
4863     GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
4864         ("pullrange on pad %s:%s but it has no getrangefunction",
4865             GST_DEBUG_PAD_NAME (pad)));
4866     GST_PAD_STREAM_UNLOCK (pad);
4867     return GST_FLOW_NOT_SUPPORTED;
4868   }
4869 dropping:
4870   {
4871     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4872         "Dropping data after FALSE probe return");
4873     GST_PAD_STREAM_UNLOCK (pad);
4874     gst_buffer_unref (*buffer);
4875     *buffer = NULL;
4876     return GST_FLOW_UNEXPECTED;
4877   }
4878 get_range_failed:
4879   {
4880     *buffer = NULL;
4881     GST_CAT_LEVEL_LOG (GST_CAT_SCHEDULING,
4882         (ret >= GST_FLOW_UNEXPECTED) ? GST_LEVEL_INFO : GST_LEVEL_WARNING,
4883         pad, "getrange failed, flow: %s", gst_flow_get_name (ret));
4884     return ret;
4885   }
4886 not_negotiated:
4887   {
4888     gst_buffer_unref (*buffer);
4889     *buffer = NULL;
4890     GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
4891         "getrange returned buffer of unaccaptable caps");
4892     return GST_FLOW_NOT_NEGOTIATED;
4893   }
4894 }
4895
4896 /**
4897  * gst_pad_get_range:
4898  * @pad: a src #GstPad, returns #GST_FLOW_ERROR if not.
4899  * @offset: The start offset of the buffer
4900  * @size: The length of the buffer
4901  * @buffer: a pointer to hold the #GstBuffer, returns #GST_FLOW_ERROR if %NULL.
4902  *
4903  * When @pad is flushing this function returns #GST_FLOW_WRONG_STATE
4904  * immediatly and @buffer is %NULL.
4905  *
4906  * Calls the getrange function of @pad, see #GstPadGetRangeFunction for a
4907  * description of a getrange function. If @pad has no getrange function
4908  * installed (see gst_pad_set_getrange_function()) this function returns
4909  * #GST_FLOW_NOT_SUPPORTED.
4910  *
4911  * This is a lowlevel function. Usualy gst_pad_pull_range() is used.
4912  *
4913  * Returns: a #GstFlowReturn from the pad.
4914  *
4915  * MT safe.
4916  */
4917 GstFlowReturn
4918 gst_pad_get_range (GstPad * pad, guint64 offset, guint size,
4919     GstBuffer ** buffer)
4920 {
4921   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4922   g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4923   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
4924
4925   return gst_pad_get_range_unchecked (pad, offset, size, buffer);
4926 }
4927
4928 /**
4929  * gst_pad_pull_range:
4930  * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
4931  * @offset: The start offset of the buffer
4932  * @size: The length of the buffer
4933  * @buffer: a pointer to hold the #GstBuffer, returns GST_FLOW_ERROR if %NULL.
4934  *
4935  * Pulls a @buffer from the peer pad.
4936  *
4937  * This function will first trigger the pad block signal if it was
4938  * installed.
4939  *
4940  * When @pad is not linked #GST_FLOW_NOT_LINKED is returned else this
4941  * function returns the result of gst_pad_get_range() on the peer pad.
4942  * See gst_pad_get_range() for a list of return values and for the
4943  * semantics of the arguments of this function.
4944  *
4945  * @buffer's caps must either be unset or the same as what is already
4946  * configured on @pad. Renegotiation within a running pull-mode pipeline is not
4947  * supported.
4948  *
4949  * Returns: a #GstFlowReturn from the peer pad.
4950  * When this function returns #GST_FLOW_OK, @buffer will contain a valid
4951  * #GstBuffer that should be freed with gst_buffer_unref() after usage.
4952  * @buffer may not be used or freed when any other return value than
4953  * #GST_FLOW_OK is returned.
4954  *
4955  * MT safe.
4956  */
4957 GstFlowReturn
4958 gst_pad_pull_range (GstPad * pad, guint64 offset, guint size,
4959     GstBuffer ** buffer)
4960 {
4961   GstPad *peer;
4962   GstFlowReturn ret;
4963   gboolean emit_signal;
4964   GstCaps *caps;
4965   gboolean caps_changed;
4966
4967   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4968   g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
4969   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
4970
4971   GST_OBJECT_LOCK (pad);
4972
4973   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
4974     handle_pad_block (pad);
4975
4976   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
4977     goto not_connected;
4978
4979   /* signal emision for the pad, peer has chance to emit when
4980    * we call _get_range() */
4981   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
4982
4983   gst_object_ref (peer);
4984   GST_OBJECT_UNLOCK (pad);
4985
4986   ret = gst_pad_get_range_unchecked (peer, offset, size, buffer);
4987
4988   gst_object_unref (peer);
4989
4990   if (G_UNLIKELY (ret != GST_FLOW_OK))
4991     goto pull_range_failed;
4992
4993   /* can only fire the signal if we have a valid buffer */
4994   if (G_UNLIKELY (emit_signal)) {
4995     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
4996       goto dropping;
4997   }
4998
4999   GST_OBJECT_LOCK (pad);
5000   /* Before pushing the buffer to the peer pad, ensure that caps
5001    * are set on this pad */
5002   caps = GST_BUFFER_CAPS (*buffer);
5003   caps_changed = caps && caps != GST_PAD_CAPS (pad);
5004   GST_OBJECT_UNLOCK (pad);
5005
5006   /* we got a new datatype on the pad, see if it can handle it */
5007   if (G_UNLIKELY (caps_changed)) {
5008     GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
5009     if (G_UNLIKELY (!gst_pad_configure_sink (pad, caps)))
5010       goto not_negotiated;
5011   }
5012   return ret;
5013
5014   /* ERROR recovery here */
5015 not_connected:
5016   {
5017     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
5018         "pulling range, but it was not linked");
5019     GST_OBJECT_UNLOCK (pad);
5020     return GST_FLOW_NOT_LINKED;
5021   }
5022 pull_range_failed:
5023   {
5024     *buffer = NULL;
5025     GST_CAT_LEVEL_LOG (GST_CAT_SCHEDULING,
5026         (ret >= GST_FLOW_UNEXPECTED) ? GST_LEVEL_INFO : GST_LEVEL_WARNING,
5027         pad, "pullrange failed, flow: %s", gst_flow_get_name (ret));
5028     return ret;
5029   }
5030 dropping:
5031   {
5032     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
5033         "Dropping data after FALSE probe return");
5034     gst_buffer_unref (*buffer);
5035     *buffer = NULL;
5036     return GST_FLOW_UNEXPECTED;
5037   }
5038 not_negotiated:
5039   {
5040     gst_buffer_unref (*buffer);
5041     *buffer = NULL;
5042     GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
5043         "pullrange returned buffer of different caps");
5044     return GST_FLOW_NOT_NEGOTIATED;
5045   }
5046 }
5047
5048 /**
5049  * gst_pad_push_event:
5050  * @pad: a #GstPad to push the event to.
5051  * @event: the #GstEvent to send to the pad.
5052  *
5053  * Sends the event to the peer of the given pad. This function is
5054  * mainly used by elements to send events to their peer
5055  * elements.
5056  *
5057  * This function takes owership of the provided event so you should
5058  * gst_event_ref() it if you want to reuse the event after this call.
5059  *
5060  * Returns: TRUE if the event was handled.
5061  *
5062  * MT safe.
5063  */
5064 gboolean
5065 gst_pad_push_event (GstPad * pad, GstEvent * event)
5066 {
5067   GstPad *peerpad;
5068   gboolean result;
5069
5070   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5071   g_return_val_if_fail (event != NULL, FALSE);
5072   g_return_val_if_fail (GST_IS_EVENT (event), FALSE);
5073
5074   GST_LOG_OBJECT (pad, "event: %s", GST_EVENT_TYPE_NAME (event));
5075
5076   GST_OBJECT_LOCK (pad);
5077
5078   /* Two checks to be made:
5079    * . (un)set the FLUSHING flag for flushing events,
5080    * . handle pad blocking */
5081   switch (GST_EVENT_TYPE (event)) {
5082     case GST_EVENT_FLUSH_START:
5083       _priv_gst_pad_invalidate_cache (pad);
5084       GST_PAD_SET_FLUSHING (pad);
5085
5086       if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
5087         /* flush start will have set the FLUSHING flag and will then
5088          * unlock all threads doing a GCond wait on the blocking pad. This
5089          * will typically unblock the STREAMING thread blocked on a pad. */
5090         GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-start, "
5091             "doing block signal.");
5092         GST_PAD_BLOCK_BROADCAST (pad);
5093         goto flushed;
5094       }
5095       break;
5096     case GST_EVENT_FLUSH_STOP:
5097       GST_PAD_UNSET_FLUSHING (pad);
5098
5099       /* if we are blocked, flush away the FLUSH_STOP event */
5100       if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
5101         GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-stop");
5102         goto flushed;
5103       }
5104       break;
5105     default:
5106       while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
5107         /* block the event as long as the pad is blocked */
5108         if (handle_pad_block (pad) != GST_FLOW_OK)
5109           goto flushed;
5110       }
5111       break;
5112   }
5113
5114   if (G_UNLIKELY (GST_EVENT_SRC (event) == NULL)) {
5115     GST_LOG_OBJECT (pad, "event had no source, setting pad as event source");
5116     GST_EVENT_SRC (event) = gst_object_ref (pad);
5117   }
5118
5119   if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
5120     GST_OBJECT_UNLOCK (pad);
5121
5122     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (event)))
5123       goto dropping;
5124
5125     GST_OBJECT_LOCK (pad);
5126   }
5127   peerpad = GST_PAD_PEER (pad);
5128   if (peerpad == NULL)
5129     goto not_linked;
5130
5131   GST_LOG_OBJECT (pad, "sending event %s to peerpad %" GST_PTR_FORMAT,
5132       GST_EVENT_TYPE_NAME (event), peerpad);
5133   gst_object_ref (peerpad);
5134   GST_OBJECT_UNLOCK (pad);
5135
5136   result = gst_pad_send_event (peerpad, event);
5137
5138   /* Note: we gave away ownership of the event at this point */
5139   GST_LOG_OBJECT (pad, "sent event to peerpad %" GST_PTR_FORMAT ", result %d",
5140       peerpad, result);
5141   gst_object_unref (peerpad);
5142
5143   return result;
5144
5145   /* ERROR handling */
5146 dropping:
5147   {
5148     GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
5149     gst_event_unref (event);
5150     return FALSE;
5151   }
5152 not_linked:
5153   {
5154     GST_DEBUG_OBJECT (pad, "Dropping event because pad is not linked");
5155     gst_event_unref (event);
5156     GST_OBJECT_UNLOCK (pad);
5157     return FALSE;
5158   }
5159 flushed:
5160   {
5161     GST_DEBUG_OBJECT (pad,
5162         "Not forwarding event since we're flushing and blocking");
5163     gst_event_unref (event);
5164     GST_OBJECT_UNLOCK (pad);
5165     return TRUE;
5166   }
5167 }
5168
5169 /**
5170  * gst_pad_send_event:
5171  * @pad: a #GstPad to send the event to.
5172  * @event: the #GstEvent to send to the pad.
5173  *
5174  * Sends the event to the pad. This function can be used
5175  * by applications to send events in the pipeline.
5176  *
5177  * If @pad is a source pad, @event should be an upstream event. If @pad is a
5178  * sink pad, @event should be a downstream event. For example, you would not
5179  * send a #GST_EVENT_EOS on a src pad; EOS events only propagate downstream.
5180  * Furthermore, some downstream events have to be serialized with data flow,
5181  * like EOS, while some can travel out-of-band, like #GST_EVENT_FLUSH_START. If
5182  * the event needs to be serialized with data flow, this function will take the
5183  * pad's stream lock while calling its event function.
5184  *
5185  * To find out whether an event type is upstream, downstream, or downstream and
5186  * serialized, see #GstEventTypeFlags, gst_event_type_get_flags(),
5187  * #GST_EVENT_IS_UPSTREAM, #GST_EVENT_IS_DOWNSTREAM, and
5188  * #GST_EVENT_IS_SERIALIZED. Note that in practice that an application or
5189  * plugin doesn't need to bother itself with this information; the core handles
5190  * all necessary locks and checks.
5191  *
5192  * This function takes owership of the provided event so you should
5193  * gst_event_ref() it if you want to reuse the event after this call.
5194  *
5195  * Returns: TRUE if the event was handled.
5196  */
5197 gboolean
5198 gst_pad_send_event (GstPad * pad, GstEvent * event)
5199 {
5200   gboolean result = FALSE;
5201   GstPadEventFunction eventfunc;
5202   gboolean serialized, need_unlock = FALSE;
5203
5204   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5205   g_return_val_if_fail (event != NULL, FALSE);
5206
5207   GST_OBJECT_LOCK (pad);
5208   if (GST_PAD_IS_SINK (pad)) {
5209     if (G_UNLIKELY (!GST_EVENT_IS_DOWNSTREAM (event)))
5210       goto wrong_direction;
5211     serialized = GST_EVENT_IS_SERIALIZED (event);
5212   } else if (GST_PAD_IS_SRC (pad)) {
5213     if (G_UNLIKELY (!GST_EVENT_IS_UPSTREAM (event)))
5214       goto wrong_direction;
5215     /* events on srcpad never are serialized */
5216     serialized = FALSE;
5217   } else
5218     goto unknown_direction;
5219
5220   if (G_UNLIKELY (GST_EVENT_SRC (event) == NULL)) {
5221     GST_LOG_OBJECT (pad, "event had no source, setting pad as event source");
5222     GST_EVENT_SRC (event) = gst_object_ref (pad);
5223   }
5224
5225   /* pad signals */
5226   if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
5227     GST_OBJECT_UNLOCK (pad);
5228
5229     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (event)))
5230       goto dropping;
5231
5232     GST_OBJECT_LOCK (pad);
5233   }
5234
5235   switch (GST_EVENT_TYPE (event)) {
5236     case GST_EVENT_FLUSH_START:
5237       GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad,
5238           "have event type %d (FLUSH_START)", GST_EVENT_TYPE (event));
5239
5240       /* can't even accept a flush begin event when flushing */
5241       if (GST_PAD_IS_FLUSHING (pad))
5242         goto flushing;
5243
5244       _priv_gst_pad_invalidate_cache (pad);
5245       GST_PAD_SET_FLUSHING (pad);
5246       GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "set flush flag");
5247       break;
5248     case GST_EVENT_FLUSH_STOP:
5249       if (G_LIKELY (GST_PAD_ACTIVATE_MODE (pad) != GST_ACTIVATE_NONE)) {
5250         GST_PAD_UNSET_FLUSHING (pad);
5251         GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "cleared flush flag");
5252       }
5253       GST_OBJECT_UNLOCK (pad);
5254       /* grab stream lock */
5255       GST_PAD_STREAM_LOCK (pad);
5256       need_unlock = TRUE;
5257       GST_OBJECT_LOCK (pad);
5258       break;
5259     default:
5260       GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "have event type %s",
5261           GST_EVENT_TYPE_NAME (event));
5262
5263       /* make this a little faster, no point in grabbing the lock
5264        * if the pad is allready flushing. */
5265       if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
5266         goto flushing;
5267
5268       if (serialized) {
5269         /* lock order: STREAM_LOCK, LOCK, recheck flushing. */
5270         GST_OBJECT_UNLOCK (pad);
5271         GST_PAD_STREAM_LOCK (pad);
5272         need_unlock = TRUE;
5273         GST_OBJECT_LOCK (pad);
5274         if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
5275           goto flushing;
5276       }
5277       break;
5278   }
5279   if (G_UNLIKELY ((eventfunc = GST_PAD_EVENTFUNC (pad)) == NULL))
5280     goto no_function;
5281
5282   GST_OBJECT_UNLOCK (pad);
5283
5284   result = eventfunc (pad, event);
5285
5286   if (need_unlock)
5287     GST_PAD_STREAM_UNLOCK (pad);
5288
5289   GST_DEBUG_OBJECT (pad, "sent event, result %d", result);
5290
5291   return result;
5292
5293   /* ERROR handling */
5294 wrong_direction:
5295   {
5296     g_warning ("pad %s:%s sending %s event in wrong direction",
5297         GST_DEBUG_PAD_NAME (pad), GST_EVENT_TYPE_NAME (event));
5298     GST_OBJECT_UNLOCK (pad);
5299     gst_event_unref (event);
5300     return FALSE;
5301   }
5302 unknown_direction:
5303   {
5304     g_warning ("pad %s:%s has invalid direction", GST_DEBUG_PAD_NAME (pad));
5305     GST_OBJECT_UNLOCK (pad);
5306     gst_event_unref (event);
5307     return FALSE;
5308   }
5309 no_function:
5310   {
5311     g_warning ("pad %s:%s has no event handler, file a bug.",
5312         GST_DEBUG_PAD_NAME (pad));
5313     GST_OBJECT_UNLOCK (pad);
5314     if (need_unlock)
5315       GST_PAD_STREAM_UNLOCK (pad);
5316     gst_event_unref (event);
5317     return FALSE;
5318   }
5319 flushing:
5320   {
5321     GST_OBJECT_UNLOCK (pad);
5322     if (need_unlock)
5323       GST_PAD_STREAM_UNLOCK (pad);
5324     GST_CAT_INFO_OBJECT (GST_CAT_EVENT, pad,
5325         "Received event on flushing pad. Discarding");
5326     gst_event_unref (event);
5327     return FALSE;
5328   }
5329 dropping:
5330   {
5331     GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
5332     gst_event_unref (event);
5333     return FALSE;
5334   }
5335 }
5336
5337 /**
5338  * gst_pad_set_element_private:
5339  * @pad: the #GstPad to set the private data of.
5340  * @priv: The private data to attach to the pad.
5341  *
5342  * Set the given private data gpointer on the pad.
5343  * This function can only be used by the element that owns the pad.
5344  * No locking is performed in this function.
5345  */
5346 void
5347 gst_pad_set_element_private (GstPad * pad, gpointer priv)
5348 {
5349   pad->element_private = priv;
5350 }
5351
5352 /**
5353  * gst_pad_get_element_private:
5354  * @pad: the #GstPad to get the private data of.
5355  *
5356  * Gets the private data of a pad.
5357  * No locking is performed in this function.
5358  *
5359  * Returns: a #gpointer to the private data.
5360  */
5361 gpointer
5362 gst_pad_get_element_private (GstPad * pad)
5363 {
5364   return pad->element_private;
5365 }
5366
5367 static void
5368 do_stream_status (GstPad * pad, GstStreamStatusType type,
5369     GThread * thread, GstTask * task)
5370 {
5371   GstElement *parent;
5372
5373   GST_DEBUG_OBJECT (pad, "doing stream-status %d", type);
5374
5375   if ((parent = GST_ELEMENT_CAST (gst_pad_get_parent (pad)))) {
5376     if (GST_IS_ELEMENT (parent)) {
5377       GstMessage *message;
5378       GValue value = { 0 };
5379
5380       if (type == GST_STREAM_STATUS_TYPE_ENTER) {
5381         gchar *tname, *ename, *pname;
5382
5383         /* create a good task name */
5384         ename = gst_element_get_name (parent);
5385         pname = gst_pad_get_name (pad);
5386         tname = g_strdup_printf ("%s:%s", ename, pname);
5387         g_free (ename);
5388         g_free (pname);
5389
5390         gst_object_set_name (GST_OBJECT_CAST (task), tname);
5391         g_free (tname);
5392       }
5393
5394       message = gst_message_new_stream_status (GST_OBJECT_CAST (pad),
5395           type, parent);
5396
5397       g_value_init (&value, GST_TYPE_TASK);
5398       g_value_set_object (&value, task);
5399       gst_message_set_stream_status_object (message, &value);
5400       g_value_unset (&value);
5401
5402       GST_DEBUG_OBJECT (pad, "posting stream-status %d", type);
5403       gst_element_post_message (parent, message);
5404     }
5405     gst_object_unref (parent);
5406   }
5407 }
5408
5409 static void
5410 pad_enter_thread (GstTask * task, GThread * thread, gpointer user_data)
5411 {
5412   do_stream_status (GST_PAD_CAST (user_data), GST_STREAM_STATUS_TYPE_ENTER,
5413       thread, task);
5414 }
5415
5416 static void
5417 pad_leave_thread (GstTask * task, GThread * thread, gpointer user_data)
5418 {
5419   do_stream_status (GST_PAD_CAST (user_data), GST_STREAM_STATUS_TYPE_LEAVE,
5420       thread, task);
5421 }
5422
5423 static GstTaskThreadCallbacks thr_callbacks = {
5424   pad_enter_thread,
5425   pad_leave_thread,
5426 };
5427
5428 /**
5429  * gst_pad_start_task:
5430  * @pad: the #GstPad to start the task of
5431  * @func: the task function to call
5432  * @data: data passed to the task function
5433  *
5434  * Starts a task that repeatedly calls @func with @data. This function
5435  * is mostly used in pad activation functions to start the dataflow.
5436  * The #GST_PAD_STREAM_LOCK of @pad will automatically be acquired
5437  * before @func is called.
5438  *
5439  * Returns: a %TRUE if the task could be started.
5440  */
5441 gboolean
5442 gst_pad_start_task (GstPad * pad, GstTaskFunction func, gpointer data)
5443 {
5444   GstTask *task;
5445   gboolean res;
5446
5447   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5448   g_return_val_if_fail (func != NULL, FALSE);
5449
5450   GST_DEBUG_OBJECT (pad, "start task");
5451
5452   GST_OBJECT_LOCK (pad);
5453   task = GST_PAD_TASK (pad);
5454   if (task == NULL) {
5455     task = gst_task_create (func, data);
5456     gst_task_set_lock (task, GST_PAD_GET_STREAM_LOCK (pad));
5457     gst_task_set_thread_callbacks (task, &thr_callbacks, pad, NULL);
5458     GST_DEBUG_OBJECT (pad, "created task");
5459     GST_PAD_TASK (pad) = task;
5460     gst_object_ref (task);
5461     /* release lock to post the message */
5462     GST_OBJECT_UNLOCK (pad);
5463
5464     do_stream_status (pad, GST_STREAM_STATUS_TYPE_CREATE, NULL, task);
5465
5466     gst_object_unref (task);
5467
5468     GST_OBJECT_LOCK (pad);
5469     /* nobody else is supposed to have changed the pad now */
5470     if (GST_PAD_TASK (pad) != task)
5471       goto concurrent_stop;
5472   }
5473   res = gst_task_set_state (task, GST_TASK_STARTED);
5474   GST_OBJECT_UNLOCK (pad);
5475
5476   return res;
5477
5478   /* ERRORS */
5479 concurrent_stop:
5480   {
5481     GST_OBJECT_UNLOCK (pad);
5482     return TRUE;
5483   }
5484 }
5485
5486 /**
5487  * gst_pad_pause_task:
5488  * @pad: the #GstPad to pause the task of
5489  *
5490  * Pause the task of @pad. This function will also wait until the
5491  * function executed by the task is finished if this function is not
5492  * called from the task function.
5493  *
5494  * Returns: a TRUE if the task could be paused or FALSE when the pad
5495  * has no task.
5496  */
5497 gboolean
5498 gst_pad_pause_task (GstPad * pad)
5499 {
5500   GstTask *task;
5501   gboolean res;
5502
5503   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5504
5505   GST_DEBUG_OBJECT (pad, "pause task");
5506
5507   GST_OBJECT_LOCK (pad);
5508   task = GST_PAD_TASK (pad);
5509   if (task == NULL)
5510     goto no_task;
5511   res = gst_task_set_state (task, GST_TASK_PAUSED);
5512   GST_OBJECT_UNLOCK (pad);
5513
5514   /* wait for task function to finish, this lock is recursive so it does nothing
5515    * when the pause is called from the task itself */
5516   GST_PAD_STREAM_LOCK (pad);
5517   GST_PAD_STREAM_UNLOCK (pad);
5518
5519   return res;
5520
5521 no_task:
5522   {
5523     GST_DEBUG_OBJECT (pad, "pad has no task");
5524     GST_OBJECT_UNLOCK (pad);
5525     return FALSE;
5526   }
5527 }
5528
5529 /**
5530  * gst_pad_stop_task:
5531  * @pad: the #GstPad to stop the task of
5532  *
5533  * Stop the task of @pad. This function will also make sure that the
5534  * function executed by the task will effectively stop if not called
5535  * from the GstTaskFunction.
5536  *
5537  * This function will deadlock if called from the GstTaskFunction of
5538  * the task. Use gst_task_pause() instead.
5539  *
5540  * Regardless of whether the pad has a task, the stream lock is acquired and
5541  * released so as to ensure that streaming through this pad has finished.
5542  *
5543  * Returns: a TRUE if the task could be stopped or FALSE on error.
5544  */
5545 gboolean
5546 gst_pad_stop_task (GstPad * pad)
5547 {
5548   GstTask *task;
5549   gboolean res;
5550
5551   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5552
5553   GST_DEBUG_OBJECT (pad, "stop task");
5554
5555   GST_OBJECT_LOCK (pad);
5556   task = GST_PAD_TASK (pad);
5557   if (task == NULL)
5558     goto no_task;
5559   GST_PAD_TASK (pad) = NULL;
5560   res = gst_task_set_state (task, GST_TASK_STOPPED);
5561   GST_OBJECT_UNLOCK (pad);
5562
5563   GST_PAD_STREAM_LOCK (pad);
5564   GST_PAD_STREAM_UNLOCK (pad);
5565
5566   if (!gst_task_join (task))
5567     goto join_failed;
5568
5569   gst_object_unref (task);
5570
5571   return res;
5572
5573 no_task:
5574   {
5575     GST_DEBUG_OBJECT (pad, "no task");
5576     GST_OBJECT_UNLOCK (pad);
5577
5578     GST_PAD_STREAM_LOCK (pad);
5579     GST_PAD_STREAM_UNLOCK (pad);
5580
5581     /* this is not an error */
5582     return TRUE;
5583   }
5584 join_failed:
5585   {
5586     /* this is bad, possibly the application tried to join the task from
5587      * the task's thread. We install the task again so that it will be stopped
5588      * again from the right thread next time hopefully. */
5589     GST_OBJECT_LOCK (pad);
5590     GST_DEBUG_OBJECT (pad, "join failed");
5591     /* we can only install this task if there was no other task */
5592     if (GST_PAD_TASK (pad) == NULL)
5593       GST_PAD_TASK (pad) = task;
5594     GST_OBJECT_UNLOCK (pad);
5595
5596     return FALSE;
5597   }
5598 }