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