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 source #GstPad.
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
1958   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get pad caps");
1959
1960   if (GST_PAD_GETCAPSFUNC (pad)) {
1961     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
1962         "dispatching to pad getcaps function");
1963
1964     GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_GETCAPS);
1965     GST_OBJECT_UNLOCK (pad);
1966     result = GST_PAD_GETCAPSFUNC (pad) (pad);
1967     GST_OBJECT_LOCK (pad);
1968     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_GETCAPS);
1969
1970     if (result == NULL) {
1971       g_critical ("pad %s:%s returned NULL caps from getcaps function",
1972           GST_DEBUG_PAD_NAME (pad));
1973     } else {
1974       GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
1975           "pad getcaps returned %" GST_PTR_FORMAT, result);
1976 #ifndef G_DISABLE_ASSERT
1977       /* check that the returned caps are a real subset of the template caps */
1978       if (GST_PAD_PAD_TEMPLATE (pad)) {
1979         const GstCaps *templ_caps =
1980             GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
1981         if (!gst_caps_is_subset (result, templ_caps)) {
1982           GstCaps *temp;
1983
1984           GST_CAT_ERROR_OBJECT (GST_CAT_CAPS, pad,
1985               "pad returned caps %" GST_PTR_FORMAT
1986               " which are not a real subset of its template caps %"
1987               GST_PTR_FORMAT, result, templ_caps);
1988           g_warning
1989               ("pad %s:%s returned caps which are not a real "
1990               "subset of its template caps", GST_DEBUG_PAD_NAME (pad));
1991           temp = gst_caps_intersect (templ_caps, result);
1992           gst_caps_unref (result);
1993           result = temp;
1994         }
1995       }
1996 #endif
1997       goto done;
1998     }
1999   }
2000   if (GST_PAD_PAD_TEMPLATE (pad)) {
2001     GstPadTemplate *templ = GST_PAD_PAD_TEMPLATE (pad);
2002
2003     result = GST_PAD_TEMPLATE_CAPS (templ);
2004     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2005         "using pad template %p with caps %p %" GST_PTR_FORMAT, templ, result,
2006         result);
2007
2008     result = gst_caps_ref (result);
2009     goto done;
2010   }
2011   if (GST_PAD_CAPS (pad)) {
2012     result = GST_PAD_CAPS (pad);
2013
2014     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2015         "using pad caps %p %" GST_PTR_FORMAT, result, result);
2016
2017     result = gst_caps_ref (result);
2018     goto done;
2019   }
2020
2021   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "pad has no caps");
2022   result = gst_caps_new_empty ();
2023
2024 done:
2025   return result;
2026 }
2027
2028 /**
2029  * gst_pad_get_caps:
2030  * @pad: a  #GstPad to get the capabilities of.
2031  *
2032  * Gets the capabilities this pad can produce or consume.
2033  * Note that this method doesn't necessarily return the caps set by
2034  * gst_pad_set_caps() - use #GST_PAD_CAPS for that instead.
2035  * gst_pad_get_caps returns all possible caps a pad can operate with, using
2036  * the pad's get_caps function;
2037  * this returns the pad template caps if not explicitly set.
2038  *
2039  * Returns: a newly allocated copy of the #GstCaps of this pad.
2040  *
2041  * MT safe.
2042  */
2043 GstCaps *
2044 gst_pad_get_caps (GstPad * pad)
2045 {
2046   GstCaps *result = NULL;
2047
2048   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2049
2050   GST_OBJECT_LOCK (pad);
2051
2052   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get pad caps");
2053
2054   result = gst_pad_get_caps_unlocked (pad);
2055   GST_OBJECT_UNLOCK (pad);
2056
2057   return result;
2058 }
2059
2060 /**
2061  * gst_pad_peer_get_caps:
2062  * @pad: a  #GstPad to get the peer capabilities of.
2063  *
2064  * Gets the capabilities of the peer connected to this pad.
2065  *
2066  * Returns: the #GstCaps of the peer pad. This function returns a new caps, so
2067  * use gst_caps_unref to get rid of it. this function returns NULL if there is
2068  * no peer pad.
2069  */
2070 GstCaps *
2071 gst_pad_peer_get_caps (GstPad * pad)
2072 {
2073   GstPad *peerpad;
2074   GstCaps *result = NULL;
2075
2076   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2077
2078   GST_OBJECT_LOCK (pad);
2079
2080   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get peer caps");
2081
2082   peerpad = GST_PAD_PEER (pad);
2083   if (G_UNLIKELY (peerpad == NULL))
2084     goto no_peer;
2085
2086   gst_object_ref (peerpad);
2087   GST_OBJECT_UNLOCK (pad);
2088
2089   result = gst_pad_get_caps (peerpad);
2090
2091   gst_object_unref (peerpad);
2092
2093   return result;
2094
2095 no_peer:
2096   {
2097     GST_OBJECT_UNLOCK (pad);
2098     return NULL;
2099   }
2100 }
2101
2102 static gboolean
2103 fixate_value (GValue * dest, const GValue * src)
2104 {
2105   if (G_VALUE_TYPE (src) == GST_TYPE_INT_RANGE) {
2106     g_value_init (dest, G_TYPE_INT);
2107     g_value_set_int (dest, gst_value_get_int_range_min (src));
2108   } else if (G_VALUE_TYPE (src) == GST_TYPE_DOUBLE_RANGE) {
2109     g_value_init (dest, G_TYPE_DOUBLE);
2110     g_value_set_double (dest, gst_value_get_double_range_min (src));
2111   } else if (G_VALUE_TYPE (src) == GST_TYPE_FRACTION_RANGE) {
2112     gst_value_init_and_copy (dest, gst_value_get_fraction_range_min (src));
2113   } else if (G_VALUE_TYPE (src) == GST_TYPE_LIST) {
2114     GValue temp = { 0 };
2115
2116     gst_value_init_and_copy (&temp, gst_value_list_get_value (src, 0));
2117     if (!fixate_value (dest, &temp))
2118       gst_value_init_and_copy (dest, &temp);
2119     g_value_unset (&temp);
2120   } else if (G_VALUE_TYPE (src) == GST_TYPE_ARRAY) {
2121     gboolean res = FALSE;
2122     guint n;
2123
2124     g_value_init (dest, GST_TYPE_ARRAY);
2125     for (n = 0; n < gst_value_array_get_size (src); n++) {
2126       GValue kid = { 0 };
2127       const GValue *orig_kid = gst_value_array_get_value (src, n);
2128
2129       if (!fixate_value (&kid, orig_kid))
2130         gst_value_init_and_copy (&kid, orig_kid);
2131       else
2132         res = TRUE;
2133       gst_value_array_append_value (dest, &kid);
2134       g_value_unset (&kid);
2135     }
2136
2137     if (!res)
2138       g_value_unset (dest);
2139
2140     return res;
2141   } else {
2142     return FALSE;
2143   }
2144
2145   return TRUE;
2146 }
2147
2148 static gboolean
2149 gst_pad_default_fixate (GQuark field_id, const GValue * value, gpointer data)
2150 {
2151   GstStructure *s = data;
2152   GValue v = { 0 };
2153
2154   if (fixate_value (&v, value)) {
2155     gst_structure_id_set_value (s, field_id, &v);
2156     g_value_unset (&v);
2157   }
2158
2159   return TRUE;
2160 }
2161
2162 /**
2163  * gst_pad_fixate_caps:
2164  * @pad: a  #GstPad to fixate
2165  * @caps: the  #GstCaps to fixate
2166  *
2167  * Fixate a caps on the given pad. Modifies the caps in place, so you should
2168  * make sure that the caps are actually writable (see gst_caps_make_writable()).
2169  */
2170 void
2171 gst_pad_fixate_caps (GstPad * pad, GstCaps * caps)
2172 {
2173   GstPadFixateCapsFunction fixatefunc;
2174   guint n;
2175
2176   g_return_if_fail (GST_IS_PAD (pad));
2177   g_return_if_fail (caps != NULL);
2178
2179   if (gst_caps_is_fixed (caps))
2180     return;
2181
2182   fixatefunc = GST_PAD_FIXATECAPSFUNC (pad);
2183   if (fixatefunc) {
2184     fixatefunc (pad, caps);
2185   }
2186
2187   /* default fixation */
2188   for (n = 0; n < gst_caps_get_size (caps); n++) {
2189     GstStructure *s = gst_caps_get_structure (caps, n);
2190
2191     gst_structure_foreach (s, gst_pad_default_fixate, s);
2192   }
2193 }
2194
2195 /* Default accept caps implementation just checks against
2196  * against the allowed caps for the pad */
2197 static gboolean
2198 gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps)
2199 {
2200   /* get the caps and see if it intersects to something
2201    * not empty */
2202   GstCaps *intersect;
2203   GstCaps *allowed;
2204   gboolean result = FALSE;
2205
2206   allowed = gst_pad_get_caps (pad);
2207   if (!allowed)
2208     goto nothing_allowed;
2209
2210   intersect = gst_caps_intersect (allowed, caps);
2211
2212   result = !gst_caps_is_empty (intersect);
2213   if (!result)
2214     GST_DEBUG_OBJECT (pad, "intersection gave empty caps");
2215
2216   gst_caps_unref (allowed);
2217   gst_caps_unref (intersect);
2218
2219   return result;
2220
2221   /* ERRORS */
2222 nothing_allowed:
2223   {
2224     GST_DEBUG_OBJECT (pad, "no caps allowed on the pad");
2225     return FALSE;
2226   }
2227 }
2228
2229 /**
2230  * gst_pad_accept_caps:
2231  * @pad: a #GstPad to check
2232  * @caps: a #GstCaps to check on the pad
2233  *
2234  * Check if the given pad accepts the caps.
2235  *
2236  * Returns: TRUE if the pad can accept the caps.
2237  */
2238 gboolean
2239 gst_pad_accept_caps (GstPad * pad, GstCaps * caps)
2240 {
2241   gboolean result;
2242   GstPadAcceptCapsFunction acceptfunc;
2243   GstCaps *existing = NULL;
2244
2245   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2246
2247   /* any pad can be unnegotiated */
2248   if (caps == NULL)
2249     return TRUE;
2250
2251   /* lock for checking the existing caps */
2252   GST_OBJECT_LOCK (pad);
2253   acceptfunc = GST_PAD_ACCEPTCAPSFUNC (pad);
2254   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "accept caps of %p", caps);
2255   /* The current caps on a pad are trivially acceptable */
2256   if (G_LIKELY ((existing = GST_PAD_CAPS (pad)))) {
2257     if (caps == existing || gst_caps_is_equal (caps, existing))
2258       goto is_same_caps;
2259   }
2260   GST_OBJECT_UNLOCK (pad);
2261
2262   if (G_LIKELY (acceptfunc)) {
2263     /* we can call the function */
2264     result = acceptfunc (pad, caps);
2265     GST_DEBUG_OBJECT (pad, "acceptfunc returned %d", result);
2266   } else {
2267     /* Only null if the element explicitly unset it */
2268     result = gst_pad_acceptcaps_default (pad, caps);
2269     GST_DEBUG_OBJECT (pad, "default acceptcaps returned %d", result);
2270   }
2271   return result;
2272
2273 is_same_caps:
2274   {
2275     GST_DEBUG_OBJECT (pad, "pad had same caps");
2276     GST_OBJECT_UNLOCK (pad);
2277     return TRUE;
2278   }
2279 }
2280
2281 /**
2282  * gst_pad_peer_accept_caps:
2283  * @pad: a  #GstPad to check the peer of
2284  * @caps: a #GstCaps to check on the pad
2285  *
2286  * Check if the peer of @pad accepts @caps. If @pad has no peer, this function
2287  * returns TRUE.
2288  *
2289  * Returns: TRUE if the peer of @pad can accept the caps or @pad has no peer.
2290  */
2291 gboolean
2292 gst_pad_peer_accept_caps (GstPad * pad, GstCaps * caps)
2293 {
2294   GstPad *peerpad;
2295   gboolean result;
2296
2297   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2298
2299   GST_OBJECT_LOCK (pad);
2300
2301   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "peer accept caps of (%p)", pad);
2302
2303   peerpad = GST_PAD_PEER (pad);
2304   if (G_UNLIKELY (peerpad == NULL))
2305     goto no_peer;
2306
2307   result = gst_pad_accept_caps (peerpad, caps);
2308   GST_OBJECT_UNLOCK (pad);
2309
2310   return result;
2311
2312 no_peer:
2313   {
2314     GST_OBJECT_UNLOCK (pad);
2315     return TRUE;
2316   }
2317 }
2318
2319 /**
2320  * gst_pad_set_caps:
2321  * @pad: a  #GstPad to set the capabilities of.
2322  * @caps: a #GstCaps to set.
2323  *
2324  * Sets the capabilities of this pad. The caps must be fixed. Any previous
2325  * caps on the pad will be unreffed. This function refs the caps so you should
2326  * unref if as soon as you don't need it anymore.
2327  * It is possible to set NULL caps, which will make the pad unnegotiated
2328  * again.
2329  *
2330  * Returns: TRUE if the caps could be set. FALSE if the caps were not fixed
2331  * or bad parameters were provided to this function.
2332  *
2333  * MT safe.
2334  */
2335 gboolean
2336 gst_pad_set_caps (GstPad * pad, GstCaps * caps)
2337 {
2338   GstPadSetCapsFunction setcaps;
2339   GstCaps *existing;
2340
2341   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2342   g_return_val_if_fail (caps == NULL || gst_caps_is_fixed (caps), FALSE);
2343
2344   GST_OBJECT_LOCK (pad);
2345   existing = GST_PAD_CAPS (pad);
2346   if (existing == caps)
2347     goto was_ok;
2348
2349   if (gst_caps_is_equal (caps, existing))
2350     goto setting_same_caps;
2351
2352   setcaps = GST_PAD_SETCAPSFUNC (pad);
2353
2354   /* call setcaps function to configure the pad only if the
2355    * caps is not NULL */
2356   if (setcaps != NULL && caps) {
2357     if (!GST_PAD_IS_IN_SETCAPS (pad)) {
2358       GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_SETCAPS);
2359       GST_OBJECT_UNLOCK (pad);
2360       if (!setcaps (pad, caps))
2361         goto could_not_set;
2362       GST_OBJECT_LOCK (pad);
2363       GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2364     } else {
2365       GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "pad was dispatching");
2366     }
2367   }
2368
2369   gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2370   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "caps %" GST_PTR_FORMAT, caps);
2371   GST_OBJECT_UNLOCK (pad);
2372
2373   g_object_notify (G_OBJECT (pad), "caps");
2374
2375   return TRUE;
2376
2377 was_ok:
2378   {
2379     GST_OBJECT_UNLOCK (pad);
2380     return TRUE;
2381   }
2382 setting_same_caps:
2383   {
2384     gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2385     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2386         "caps %" GST_PTR_FORMAT " same as existing, updating ptr only", caps);
2387     GST_OBJECT_UNLOCK (pad);
2388     return TRUE;
2389   }
2390
2391   /* ERRORS */
2392 could_not_set:
2393   {
2394     GST_OBJECT_LOCK (pad);
2395     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2396     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2397         "caps %" GST_PTR_FORMAT " could not be set", caps);
2398     GST_OBJECT_UNLOCK (pad);
2399
2400     return FALSE;
2401   }
2402 }
2403
2404 static gboolean
2405 gst_pad_configure_sink (GstPad * pad, GstCaps * caps)
2406 {
2407   GstPadSetCapsFunction setcaps;
2408   gboolean res;
2409
2410   setcaps = GST_PAD_SETCAPSFUNC (pad);
2411
2412   /* See if pad accepts the caps - only needed if
2413    * no setcaps function */
2414   if (setcaps == NULL)
2415     if (!gst_pad_accept_caps (pad, caps))
2416       goto not_accepted;
2417
2418   /* set caps on pad if call succeeds */
2419   res = gst_pad_set_caps (pad, caps);
2420   /* no need to unref the caps here, set_caps takes a ref and
2421    * our ref goes away when we leave this function. */
2422
2423   return res;
2424
2425 not_accepted:
2426   {
2427     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2428         "caps %" GST_PTR_FORMAT " not accepted", caps);
2429     return FALSE;
2430   }
2431 }
2432
2433 /* returns TRUE if the src pad could be configured to accept the given caps */
2434 static gboolean
2435 gst_pad_configure_src (GstPad * pad, GstCaps * caps, gboolean dosetcaps)
2436 {
2437   GstPadSetCapsFunction setcaps;
2438   gboolean res;
2439
2440   setcaps = GST_PAD_SETCAPSFUNC (pad);
2441
2442   /* See if pad accepts the caps - only needed if
2443    * no setcaps function */
2444   if (setcaps == NULL)
2445     if (!gst_pad_accept_caps (pad, caps))
2446       goto not_accepted;
2447
2448   if (dosetcaps)
2449     res = gst_pad_set_caps (pad, caps);
2450   else
2451     res = TRUE;
2452
2453   return res;
2454
2455 not_accepted:
2456   {
2457     GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2458         "caps %" GST_PTR_FORMAT " not accepted", caps);
2459     return FALSE;
2460   }
2461 }
2462
2463 /**
2464  * gst_pad_get_pad_template_caps:
2465  * @pad: a #GstPad to get the template capabilities from.
2466  *
2467  * Gets the capabilities for @pad's template.
2468  *
2469  * Returns: the #GstCaps of this pad template. If you intend to keep a
2470  * reference on the caps, make a copy (see gst_caps_copy ()).
2471  */
2472 const GstCaps *
2473 gst_pad_get_pad_template_caps (GstPad * pad)
2474 {
2475   static GstStaticCaps anycaps = GST_STATIC_CAPS ("ANY");
2476
2477   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2478
2479   if (GST_PAD_PAD_TEMPLATE (pad))
2480     return GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
2481
2482   return gst_static_caps_get (&anycaps);
2483 }
2484
2485
2486 /**
2487  * gst_pad_get_peer:
2488  * @pad: a #GstPad to get the peer of.
2489  *
2490  * Gets the peer of @pad. This function refs the peer pad so
2491  * you need to unref it after use.
2492  *
2493  * Returns: the peer #GstPad. Unref after usage.
2494  *
2495  * MT safe.
2496  */
2497 GstPad *
2498 gst_pad_get_peer (GstPad * pad)
2499 {
2500   GstPad *result;
2501
2502   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2503
2504   GST_OBJECT_LOCK (pad);
2505   result = GST_PAD_PEER (pad);
2506   if (result)
2507     gst_object_ref (result);
2508   GST_OBJECT_UNLOCK (pad);
2509
2510   return result;
2511 }
2512
2513 /**
2514  * gst_pad_get_allowed_caps:
2515  * @pad: a #GstPad.
2516  *
2517  * Gets the capabilities of the allowed media types that can flow through
2518  * @pad and its peer.
2519  *
2520  * The allowed capabilities is calculated as the intersection of the results of
2521  * calling gst_pad_get_caps() on @pad and its peer. The caller owns a reference
2522  * on the resulting caps.
2523  *
2524  * Returns: the allowed #GstCaps of the pad link. Unref the caps when you no
2525  * longer need it. This function returns NULL when @pad has no peer.
2526  *
2527  * MT safe.
2528  */
2529 GstCaps *
2530 gst_pad_get_allowed_caps (GstPad * pad)
2531 {
2532   GstCaps *mycaps;
2533   GstCaps *caps;
2534   GstCaps *peercaps;
2535   GstPad *peer;
2536
2537   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2538
2539   GST_OBJECT_LOCK (pad);
2540
2541   peer = GST_PAD_PEER (pad);
2542   if (G_UNLIKELY (peer == NULL))
2543     goto no_peer;
2544
2545   GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting allowed caps");
2546
2547   gst_object_ref (peer);
2548   GST_OBJECT_UNLOCK (pad);
2549   mycaps = gst_pad_get_caps (pad);
2550
2551   peercaps = gst_pad_get_caps (peer);
2552   gst_object_unref (peer);
2553
2554   caps = gst_caps_intersect (mycaps, peercaps);
2555   gst_caps_unref (peercaps);
2556   gst_caps_unref (mycaps);
2557
2558   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "allowed caps %" GST_PTR_FORMAT,
2559       caps);
2560
2561   return caps;
2562
2563 no_peer:
2564   {
2565     GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
2566     GST_OBJECT_UNLOCK (pad);
2567
2568     return NULL;
2569   }
2570 }
2571
2572 /**
2573  * gst_pad_get_negotiated_caps:
2574  * @pad: a #GstPad.
2575  *
2576  * Gets the capabilities of the media type that currently flows through @pad
2577  * and its peer.
2578  *
2579  * This function can be used on both src and sinkpads. Note that srcpads are
2580  * always negotiated before sinkpads so it is possible that the negotiated caps
2581  * on the srcpad do not match the negotiated caps of the peer.
2582  *
2583  * Returns: the negotiated #GstCaps of the pad link.  Free the caps when
2584  * you no longer need it. This function returns NULL when the @pad has no
2585  * peer or is not negotiated yet.
2586  *
2587  * MT safe.
2588  */
2589 GstCaps *
2590 gst_pad_get_negotiated_caps (GstPad * pad)
2591 {
2592   GstCaps *caps;
2593   GstPad *peer;
2594
2595   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2596
2597   GST_OBJECT_LOCK (pad);
2598
2599   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2600     goto no_peer;
2601
2602   GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting negotiated caps");
2603
2604   caps = GST_PAD_CAPS (pad);
2605   if (caps)
2606     gst_caps_ref (caps);
2607   GST_OBJECT_UNLOCK (pad);
2608
2609   GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "negotiated caps %" GST_PTR_FORMAT,
2610       caps);
2611
2612   return caps;
2613
2614 no_peer:
2615   {
2616     GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
2617     GST_OBJECT_UNLOCK (pad);
2618
2619     return NULL;
2620   }
2621 }
2622
2623 /* calls the buffer_alloc function on the given pad */
2624 static GstFlowReturn
2625 gst_pad_buffer_alloc_unchecked (GstPad * pad, guint64 offset, gint size,
2626     GstCaps * caps, GstBuffer ** buf)
2627 {
2628   GstFlowReturn ret;
2629   GstPadBufferAllocFunction bufferallocfunc;
2630
2631   GST_OBJECT_LOCK (pad);
2632   /* when the pad is flushing we cannot give a buffer */
2633   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
2634     goto flushing;
2635
2636   bufferallocfunc = pad->bufferallocfunc;
2637
2638   if (offset == GST_BUFFER_OFFSET_NONE) {
2639     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2640         "calling bufferallocfunc &%s (@%p) for size %d offset NONE",
2641         GST_DEBUG_FUNCPTR_NAME (bufferallocfunc), bufferallocfunc, size);
2642   } else {
2643     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2644         "calling bufferallocfunc &%s (@%p) of for size %d offset %"
2645         G_GUINT64_FORMAT, GST_DEBUG_FUNCPTR_NAME (bufferallocfunc),
2646         bufferallocfunc, size, offset);
2647   }
2648   GST_OBJECT_UNLOCK (pad);
2649
2650   /* G_LIKELY for now since most elements don't implement a buffer alloc
2651    * function and there is no default alloc proxy function as this is usually
2652    * not possible. */
2653   if (G_LIKELY (bufferallocfunc == NULL))
2654     goto fallback;
2655
2656   ret = bufferallocfunc (pad, offset, size, caps, buf);
2657   if (G_UNLIKELY (ret != GST_FLOW_OK))
2658     goto error;
2659   /* no error, but NULL buffer means fallback to the default */
2660   if (G_UNLIKELY (*buf == NULL))
2661     goto fallback;
2662
2663   /* If the buffer alloc function didn't set up the caps like it should,
2664    * do it for it */
2665   if (G_UNLIKELY (caps && (GST_BUFFER_CAPS (*buf) == NULL))) {
2666     GST_WARNING_OBJECT (pad,
2667         "Buffer allocation function did not set caps. Setting");
2668     gst_buffer_set_caps (*buf, caps);
2669   }
2670   return ret;
2671
2672 flushing:
2673   {
2674     /* pad was flushing */
2675     GST_OBJECT_UNLOCK (pad);
2676     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "pad was flushing");
2677     return GST_FLOW_WRONG_STATE;
2678   }
2679 error:
2680   {
2681     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2682         "alloc function returned error (%d) %s", ret, gst_flow_get_name (ret));
2683     return ret;
2684   }
2685 fallback:
2686   {
2687     /* fallback case, allocate a buffer of our own, add pad caps. */
2688     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "fallback buffer alloc");
2689
2690     *buf = gst_buffer_new_and_alloc (size);
2691     GST_BUFFER_OFFSET (*buf) = offset;
2692     gst_buffer_set_caps (*buf, caps);
2693
2694     return GST_FLOW_OK;
2695   }
2696 }
2697
2698 static GstFlowReturn
2699 gst_pad_alloc_buffer_full (GstPad * pad, guint64 offset, gint size,
2700     GstCaps * caps, GstBuffer ** buf, gboolean setcaps)
2701 {
2702   GstPad *peer;
2703   GstFlowReturn ret;
2704   gboolean caps_changed;
2705
2706   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
2707   g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
2708   g_return_val_if_fail (buf != NULL, GST_FLOW_ERROR);
2709
2710   GST_DEBUG_OBJECT (pad, "offset %" G_GUINT64_FORMAT ", size %d", offset, size);
2711
2712   GST_OBJECT_LOCK (pad);
2713   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
2714     if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
2715       goto flushed;
2716
2717   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2718     goto no_peer;
2719
2720   gst_object_ref (peer);
2721   GST_OBJECT_UNLOCK (pad);
2722
2723   ret = gst_pad_buffer_alloc_unchecked (peer, offset, size, caps, buf);
2724   gst_object_unref (peer);
2725
2726   if (G_UNLIKELY (ret != GST_FLOW_OK))
2727     goto peer_error;
2728
2729   /* FIXME, move capnego this into a base class? */
2730   caps = GST_BUFFER_CAPS (*buf);
2731
2732   /* Lock for checking caps, pretty pointless as the _pad_push() function might
2733    * change it concurrently, one of the problems with automatic caps setting in
2734    * pad_alloc_and_set_caps. Worst case, if does a check too much, but only
2735    * when there is heavy renegotiation going on in both directions. */
2736   GST_OBJECT_LOCK (pad);
2737   caps_changed = caps && caps != GST_PAD_CAPS (pad);
2738   GST_OBJECT_UNLOCK (pad);
2739
2740   /* we got a new datatype on the pad, see if it can handle it */
2741   if (G_UNLIKELY (caps_changed)) {
2742     GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
2743     if (G_UNLIKELY (!gst_pad_configure_src (pad, caps, setcaps)))
2744       goto not_negotiated;
2745   }
2746   return ret;
2747
2748 flushed:
2749   {
2750     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "pad block stopped by flush");
2751     GST_OBJECT_UNLOCK (pad);
2752     return ret;
2753   }
2754 no_peer:
2755   {
2756     /* pad has no peer */
2757     GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2758         "called bufferallocfunc but had no peer");
2759     GST_OBJECT_UNLOCK (pad);
2760     return GST_FLOW_NOT_LINKED;
2761   }
2762 peer_error:
2763   {
2764     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2765         "alloc function returned error %s", gst_flow_get_name (ret));
2766     return ret;
2767   }
2768 not_negotiated:
2769   {
2770     gst_buffer_unref (*buf);
2771     *buf = NULL;
2772     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2773         "alloc function returned unacceptable buffer");
2774     return GST_FLOW_NOT_NEGOTIATED;
2775   }
2776 }
2777
2778 /**
2779  * gst_pad_alloc_buffer:
2780  * @pad: a source #GstPad
2781  * @offset: the offset of the new buffer in the stream
2782  * @size: the size of the new buffer
2783  * @caps: the caps of the new buffer
2784  * @buf: a newly allocated buffer
2785  *
2786  * Allocates a new, empty buffer optimized to push to pad @pad.  This
2787  * function only works if @pad is a source pad and has a peer.
2788  *
2789  * A new, empty #GstBuffer will be put in the @buf argument.
2790  * You need to check the caps of the buffer after performing this
2791  * function and renegotiate to the format if needed.
2792  *
2793  * Returns: a result code indicating success of the operation. Any
2794  * result code other than #GST_FLOW_OK is an error and @buf should
2795  * not be used.
2796  * An error can occur if the pad is not connected or when the downstream
2797  * peer elements cannot provide an acceptable buffer.
2798  *
2799  * MT safe.
2800  */
2801 GstFlowReturn
2802 gst_pad_alloc_buffer (GstPad * pad, guint64 offset, gint size, GstCaps * caps,
2803     GstBuffer ** buf)
2804 {
2805   return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, FALSE);
2806 }
2807
2808 /**
2809  * gst_pad_alloc_buffer_and_set_caps:
2810  * @pad: a source #GstPad
2811  * @offset: the offset of the new buffer in the stream
2812  * @size: the size of the new buffer
2813  * @caps: the caps of the new buffer
2814  * @buf: a newly allocated buffer
2815  *
2816  * In addition to the function gst_pad_alloc_buffer(), this function
2817  * automatically calls gst_pad_set_caps() when the caps of the
2818  * newly allocated buffer are different from the @pad caps.
2819  *
2820  * Returns: a result code indicating success of the operation. Any
2821  * result code other than #GST_FLOW_OK is an error and @buf should
2822  * not be used.
2823  * An error can occur if the pad is not connected or when the downstream
2824  * peer elements cannot provide an acceptable buffer.
2825  *
2826  * MT safe.
2827  */
2828 GstFlowReturn
2829 gst_pad_alloc_buffer_and_set_caps (GstPad * pad, guint64 offset, gint size,
2830     GstCaps * caps, GstBuffer ** buf)
2831 {
2832   return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, TRUE);
2833 }
2834
2835 /**
2836  * gst_pad_get_internal_links_default:
2837  * @pad: the #GstPad to get the internal links of.
2838  *
2839  * Gets a list of pads to which the given pad is linked to
2840  * inside of the parent element.
2841  * This is the default handler, and thus returns a list of all of the
2842  * pads inside the parent element with opposite direction.
2843  * The caller must free this list after use.
2844  *
2845  * Returns: a newly allocated #GList of pads, or NULL if the pad has no parent.
2846  *
2847  * Not MT safe.
2848  */
2849 GList *
2850 gst_pad_get_internal_links_default (GstPad * pad)
2851 {
2852   GList *res = NULL;
2853   GstElement *parent;
2854   GList *parent_pads;
2855   GstPadDirection direction;
2856
2857   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2858
2859   direction = pad->direction;
2860
2861   parent = GST_PAD_PARENT (pad);
2862   if (!parent)
2863     goto no_parent;
2864
2865   parent_pads = parent->pads;
2866
2867   while (parent_pads) {
2868     GstPad *parent_pad = GST_PAD_CAST (parent_pads->data);
2869
2870     if (parent_pad->direction != direction) {
2871       GST_DEBUG_OBJECT (pad, "adding pad %s:%s",
2872           GST_DEBUG_PAD_NAME (parent_pad));
2873       res = g_list_prepend (res, parent_pad);
2874     }
2875     parent_pads = g_list_next (parent_pads);
2876   }
2877   return res;
2878
2879 no_parent:
2880   {
2881     GST_DEBUG_OBJECT (pad, "no parent");
2882     return NULL;
2883   }
2884 }
2885
2886 /**
2887  * gst_pad_get_internal_links:
2888  * @pad: the #GstPad to get the internal links of.
2889  *
2890  * Gets a list of pads to which the given pad is linked to
2891  * inside of the parent element.
2892  * The caller must free this list after use.
2893  *
2894  * Returns: a newly allocated #GList of pads.
2895  *
2896  * Not MT safe.
2897  */
2898 GList *
2899 gst_pad_get_internal_links (GstPad * pad)
2900 {
2901   GList *res = NULL;
2902
2903   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2904
2905   if (GST_PAD_INTLINKFUNC (pad))
2906     res = GST_PAD_INTLINKFUNC (pad) (pad);
2907
2908   return res;
2909 }
2910
2911
2912 static gboolean
2913 gst_pad_event_default_dispatch (GstPad * pad, GstEvent * event)
2914 {
2915   GList *orig, *pads;
2916   gboolean result;
2917
2918   GST_INFO_OBJECT (pad, "Sending event %p (%s) to all internally linked pads",
2919       event, GST_EVENT_TYPE_NAME (event));
2920
2921   result = (GST_PAD_DIRECTION (pad) == GST_PAD_SINK);
2922
2923   orig = pads = gst_pad_get_internal_links (pad);
2924
2925   while (pads) {
2926     GstPad *eventpad = GST_PAD_CAST (pads->data);
2927
2928     pads = g_list_next (pads);
2929
2930     if (GST_PAD_DIRECTION (eventpad) == GST_PAD_SRC) {
2931       /* for each pad we send to, we should ref the event; it's up
2932        * to downstream to unref again when handled. */
2933       GST_LOG_OBJECT (pad, "Reffing and sending event %p (%s) to %s:%s",
2934           event, GST_EVENT_TYPE_NAME (event), GST_DEBUG_PAD_NAME (eventpad));
2935       gst_event_ref (event);
2936       gst_pad_push_event (eventpad, event);
2937     } else {
2938       /* we only send the event on one pad, multi-sinkpad elements
2939        * should implement a handler */
2940       GST_LOG_OBJECT (pad, "sending event %p (%s) to one sink pad %s:%s",
2941           event, GST_EVENT_TYPE_NAME (event), GST_DEBUG_PAD_NAME (eventpad));
2942       result = gst_pad_push_event (eventpad, event);
2943       goto done;
2944     }
2945   }
2946   /* we handled the incoming event so we unref once */
2947   GST_LOG_OBJECT (pad, "handled event %p, unreffing", event);
2948   gst_event_unref (event);
2949
2950 done:
2951   g_list_free (orig);
2952
2953   return result;
2954 }
2955
2956 /**
2957  * gst_pad_event_default:
2958  * @pad: a #GstPad to call the default event handler on.
2959  * @event: the #GstEvent to handle.
2960  *
2961  * Invokes the default event handler for the given pad. End-of-stream and
2962  * discontinuity events are handled specially, and then the event is sent to all
2963  * pads internally linked to @pad. Note that if there are many possible sink
2964  * pads that are internally linked to @pad, only one will be sent an event.
2965  * Multi-sinkpad elements should implement custom event handlers.
2966  *
2967  * Returns: TRUE if the event was sent succesfully.
2968  */
2969 gboolean
2970 gst_pad_event_default (GstPad * pad, GstEvent * event)
2971 {
2972   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2973   g_return_val_if_fail (event != NULL, FALSE);
2974
2975   switch (GST_EVENT_TYPE (event)) {
2976     case GST_EVENT_EOS:
2977     {
2978       GST_DEBUG_OBJECT (pad, "pausing task because of eos");
2979       gst_pad_pause_task (pad);
2980     }
2981       /* fall thru */
2982     default:
2983       break;
2984   }
2985
2986   return gst_pad_event_default_dispatch (pad, event);
2987 }
2988
2989 /**
2990  * gst_pad_dispatcher:
2991  * @pad: a #GstPad to dispatch.
2992  * @dispatch: the #GstDispatcherFunction to call.
2993  * @data: gpointer user data passed to the dispatcher function.
2994  *
2995  * Invokes the given dispatcher function on each respective peer of
2996  * all pads that are internally linked to the given pad.
2997  * The GstPadDispatcherFunction should return TRUE when no further pads
2998  * need to be processed.
2999  *
3000  * Returns: TRUE if one of the dispatcher functions returned TRUE.
3001  */
3002 gboolean
3003 gst_pad_dispatcher (GstPad * pad, GstPadDispatcherFunction dispatch,
3004     gpointer data)
3005 {
3006   gboolean res = FALSE;
3007   GList *int_pads, *orig;
3008
3009   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3010   g_return_val_if_fail (dispatch != NULL, FALSE);
3011
3012   orig = int_pads = gst_pad_get_internal_links (pad);
3013
3014   while (int_pads) {
3015     GstPad *int_pad = GST_PAD_CAST (int_pads->data);
3016     GstPad *int_peer = gst_pad_get_peer (int_pad);
3017
3018     if (int_peer) {
3019       GST_DEBUG_OBJECT (int_pad, "dispatching to peer %s:%s",
3020           GST_DEBUG_PAD_NAME (int_peer));
3021       res = dispatch (int_peer, data);
3022       gst_object_unref (int_peer);
3023       if (res)
3024         break;
3025     } else {
3026       GST_DEBUG_OBJECT (int_pad, "no peer");
3027     }
3028     int_pads = g_list_next (int_pads);
3029   }
3030   g_list_free (orig);
3031   GST_DEBUG_OBJECT (pad, "done, result %d", res);
3032
3033   return res;
3034 }
3035
3036 /**
3037  * gst_pad_query:
3038  * @pad: a #GstPad to invoke the default query on.
3039  * @query: the #GstQuery to perform.
3040  *
3041  * Dispatches a query to a pad. The query should have been allocated by the
3042  * caller via one of the type-specific allocation functions in gstquery.h. The
3043  * element is responsible for filling the query with an appropriate response,
3044  * which should then be parsed with a type-specific query parsing function.
3045  *
3046  * Again, the caller is responsible for both the allocation and deallocation of
3047  * the query structure.
3048  *
3049  * Returns: TRUE if the query could be performed.
3050  */
3051 gboolean
3052 gst_pad_query (GstPad * pad, GstQuery * query)
3053 {
3054   GstPadQueryFunction func;
3055
3056   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3057   g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
3058
3059   GST_DEBUG_OBJECT (pad, "sending query %p", query);
3060
3061   if ((func = GST_PAD_QUERYFUNC (pad)) == NULL)
3062     goto no_func;
3063
3064   return func (pad, query);
3065
3066 no_func:
3067   {
3068     GST_DEBUG_OBJECT (pad, "had no query function");
3069     return FALSE;
3070   }
3071 }
3072
3073 /**
3074  * gst_pad_query_default:
3075  * @pad: a #GstPad to call the default query handler on.
3076  * @query: the #GstQuery to handle.
3077  *
3078  * Invokes the default query handler for the given pad.
3079  * The query is sent to all pads internally linked to @pad. Note that
3080  * if there are many possible sink pads that are internally linked to
3081  * @pad, only one will be sent the query.
3082  * Multi-sinkpad elements should implement custom query handlers.
3083  *
3084  * Returns: TRUE if the query was performed succesfully.
3085  */
3086 gboolean
3087 gst_pad_query_default (GstPad * pad, GstQuery * query)
3088 {
3089   switch (GST_QUERY_TYPE (query)) {
3090     case GST_QUERY_POSITION:
3091     case GST_QUERY_SEEKING:
3092     case GST_QUERY_FORMATS:
3093     case GST_QUERY_LATENCY:
3094     case GST_QUERY_JITTER:
3095     case GST_QUERY_RATE:
3096     case GST_QUERY_CONVERT:
3097     default:
3098       return gst_pad_dispatcher
3099           (pad, (GstPadDispatcherFunction) gst_pad_query, query);
3100   }
3101 }
3102
3103 #ifndef GST_DISABLE_LOADSAVE
3104 /* FIXME: why isn't this on a GstElement ? */
3105 /**
3106  * gst_pad_load_and_link:
3107  * @self: an #xmlNodePtr to read the description from.
3108  * @parent: the #GstObject element that owns the pad.
3109  *
3110  * Reads the pad definition from the XML node and links the given pad
3111  * in the element to a pad of an element up in the hierarchy.
3112  */
3113 void
3114 gst_pad_load_and_link (xmlNodePtr self, GstObject * parent)
3115 {
3116   xmlNodePtr field = self->xmlChildrenNode;
3117   GstPad *pad = NULL, *targetpad;
3118   gchar *peer = NULL;
3119   gchar **split;
3120   GstElement *target;
3121   GstObject *grandparent;
3122   gchar *name = NULL;
3123
3124   while (field) {
3125     if (!strcmp ((char *) field->name, "name")) {
3126       name = (gchar *) xmlNodeGetContent (field);
3127       pad = gst_element_get_pad (GST_ELEMENT (parent), name);
3128       g_free (name);
3129     } else if (!strcmp ((char *) field->name, "peer")) {
3130       peer = (gchar *) xmlNodeGetContent (field);
3131     }
3132     field = field->next;
3133   }
3134   g_return_if_fail (pad != NULL);
3135
3136   if (peer == NULL)
3137     return;
3138
3139   split = g_strsplit (peer, ".", 2);
3140
3141   if (split[0] == NULL || split[1] == NULL) {
3142     GST_CAT_DEBUG_OBJECT (GST_CAT_XML, pad,
3143         "Could not parse peer '%s', leaving unlinked", peer);
3144
3145     g_free (peer);
3146     return;
3147   }
3148   g_free (peer);
3149
3150   g_return_if_fail (split[0] != NULL);
3151   g_return_if_fail (split[1] != NULL);
3152
3153   grandparent = gst_object_get_parent (parent);
3154
3155   if (grandparent && GST_IS_BIN (grandparent)) {
3156     target = gst_bin_get_by_name_recurse_up (GST_BIN (grandparent), split[0]);
3157   } else
3158     goto cleanup;
3159
3160   if (target == NULL)
3161     goto cleanup;
3162
3163   targetpad = gst_element_get_pad (target, split[1]);
3164
3165   if (targetpad == NULL)
3166     goto cleanup;
3167
3168   gst_pad_link (pad, targetpad);
3169
3170 cleanup:
3171   g_strfreev (split);
3172 }
3173
3174 /**
3175  * gst_pad_save_thyself:
3176  * @pad: a #GstPad to save.
3177  * @parent: the parent #xmlNodePtr to save the description in.
3178  *
3179  * Saves the pad into an xml representation.
3180  *
3181  * Returns: the #xmlNodePtr representation of the pad.
3182  */
3183 static xmlNodePtr
3184 gst_pad_save_thyself (GstObject * object, xmlNodePtr parent)
3185 {
3186   GstPad *pad;
3187   GstPad *peer;
3188
3189   g_return_val_if_fail (GST_IS_PAD (object), NULL);
3190
3191   pad = GST_PAD (object);
3192
3193   xmlNewChild (parent, NULL, (xmlChar *) "name",
3194       (xmlChar *) GST_PAD_NAME (pad));
3195
3196   if (GST_PAD_IS_SRC (pad)) {
3197     xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "source");
3198   } else if (GST_PAD_IS_SINK (pad)) {
3199     xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "sink");
3200   } else {
3201     xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "unknown");
3202   }
3203
3204   if (GST_PAD_PEER (pad) != NULL) {
3205     gchar *content;
3206
3207     peer = GST_PAD_PEER (pad);
3208     /* first check to see if the peer's parent's parent is the same */
3209     /* we just save it off */
3210     content = g_strdup_printf ("%s.%s",
3211         GST_OBJECT_NAME (GST_PAD_PARENT (peer)), GST_PAD_NAME (peer));
3212     xmlNewChild (parent, NULL, (xmlChar *) "peer", (xmlChar *) content);
3213     g_free (content);
3214   } else
3215     xmlNewChild (parent, NULL, (xmlChar *) "peer", NULL);
3216
3217   return parent;
3218 }
3219
3220 #if 0
3221 /**
3222  * gst_ghost_pad_save_thyself:
3223  * @pad: a ghost #GstPad to save.
3224  * @parent: the parent #xmlNodePtr to save the description in.
3225  *
3226  * Saves the ghost pad into an xml representation.
3227  *
3228  * Returns: the #xmlNodePtr representation of the pad.
3229  */
3230 xmlNodePtr
3231 gst_ghost_pad_save_thyself (GstPad * pad, xmlNodePtr parent)
3232 {
3233   xmlNodePtr self;
3234
3235   g_return_val_if_fail (GST_IS_GHOST_PAD (pad), NULL);
3236
3237   self = xmlNewChild (parent, NULL, (xmlChar *) "ghostpad", NULL);
3238   xmlNewChild (self, NULL, (xmlChar *) "name", (xmlChar *) GST_PAD_NAME (pad));
3239   xmlNewChild (self, NULL, (xmlChar *) "parent",
3240       (xmlChar *) GST_OBJECT_NAME (GST_PAD_PARENT (pad)));
3241
3242   /* FIXME FIXME FIXME! */
3243
3244   return self;
3245 }
3246 #endif /* 0 */
3247 #endif /* GST_DISABLE_LOADSAVE */
3248
3249 /*
3250  * should be called with pad OBJECT_LOCK and STREAM_LOCK held.
3251  * GST_PAD_IS_BLOCKED (pad) == TRUE when this function is
3252  * called.
3253  *
3254  * This function performs the pad blocking when an event, buffer push
3255  * or buffer_alloc is performed on a _SRC_ pad. It blocks the
3256  * streaming thread after informing the pad has been blocked.
3257  *
3258  * An application can with this method wait and block any streaming
3259  * thread and perform operations such as seeking or linking.
3260  *
3261  * Two methods are available for notifying the application of the
3262  * block:
3263  * - the callback method, which happens in the STREAMING thread with
3264  *   the STREAM_LOCK held. With this method, the most useful way of
3265  *   dealing with the callback is to post a message to the main thread
3266  *   where the pad block can then be handled outside of the streaming
3267  *   thread. With the last method one can perform all operations such
3268  *   as doing a state change, linking, unblocking, seeking etc on the
3269  *   pad.
3270  * - the GCond signal method, which makes any thread unblock when
3271  *   the pad block happens.
3272  *
3273  * During the actual blocking state, the GST_PAD_BLOCKING flag is set.
3274  * The GST_PAD_BLOCKING flag is unset when the pad was unblocked.
3275  *
3276  * MT safe.
3277  */
3278 static GstFlowReturn
3279 handle_pad_block (GstPad * pad)
3280 {
3281   GstPadBlockCallback callback;
3282   gpointer user_data;
3283   GstFlowReturn ret = GST_FLOW_OK;
3284
3285   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "signal block taken");
3286
3287   /* flushing, don't bother trying to block and return WRONG_STATE
3288    * right away */
3289   if (GST_PAD_IS_FLUSHING (pad))
3290     goto flushingnonref;
3291
3292   /* we grab an extra ref for the callbacks, this is probably not
3293    * needed (callback code does not have a ref and cannot unref). I
3294    * think this was done to make it possible to unref the element in
3295    * the callback, which is in the end totally impossible as it
3296    * requires grabbing the STREAM_LOCK and OBJECT_LOCK which are
3297    * all taken when calling this function. */
3298   gst_object_ref (pad);
3299
3300   /* we either have a callback installed to notify the block or
3301    * some other thread is doing a GCond wait. */
3302   callback = pad->block_callback;
3303   if (callback) {
3304     /* there is a callback installed, call it. We release the
3305      * lock so that the callback can do something usefull with the
3306      * pad */
3307     user_data = pad->block_data;
3308     GST_OBJECT_UNLOCK (pad);
3309     callback (pad, TRUE, user_data);
3310     GST_OBJECT_LOCK (pad);
3311
3312     /* we released the lock, recheck flushing */
3313     if (GST_PAD_IS_FLUSHING (pad))
3314       goto flushing;
3315   } else {
3316     /* no callback, signal the thread that is doing a GCond wait
3317      * if any. */
3318     GST_PAD_BLOCK_BROADCAST (pad);
3319   }
3320
3321   /* OBJECT_LOCK could have been released when we did the callback, which
3322    * then could have made the pad unblock so we need to check the blocking
3323    * condition again.   */
3324   while (GST_PAD_IS_BLOCKED (pad)) {
3325     /* now we block the streaming thread. It can be unlocked when we
3326      * deactivate the pad (which will also set the FLUSHING flag) or
3327      * when the pad is unblocked. A flushing event will also unblock
3328      * the pad after setting the FLUSHING flag. */
3329     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3330         "Waiting to be unblocked or set flushing");
3331     GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKING);
3332     GST_PAD_BLOCK_WAIT (pad);
3333     GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKING);
3334
3335     /* see if we got unblocked by a flush or not */
3336     if (GST_PAD_IS_FLUSHING (pad))
3337       goto flushing;
3338   }
3339
3340   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "got unblocked");
3341
3342   /* when we get here, the pad is unblocked again and we perform
3343    * the needed unblock code. */
3344   callback = pad->block_callback;
3345   if (callback) {
3346     /* we need to call the callback */
3347     user_data = pad->block_data;
3348     GST_OBJECT_UNLOCK (pad);
3349     callback (pad, FALSE, user_data);
3350     GST_OBJECT_LOCK (pad);
3351   } else {
3352     /* we need to signal the thread waiting on the GCond */
3353     GST_PAD_BLOCK_BROADCAST (pad);
3354   }
3355
3356   gst_object_unref (pad);
3357
3358   return ret;
3359
3360 flushingnonref:
3361   {
3362     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad was flushing");
3363     return GST_FLOW_WRONG_STATE;
3364   }
3365 flushing:
3366   {
3367     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad became flushing");
3368     gst_object_unref (pad);
3369     return GST_FLOW_WRONG_STATE;
3370   }
3371 }
3372
3373 /**********************************************************************
3374  * Data passing functions
3375  */
3376
3377 static gboolean
3378 gst_pad_emit_have_data_signal (GstPad * pad, GstMiniObject * obj)
3379 {
3380   GValue ret = { 0 };
3381   GValue args[2] = { {0}, {0} };
3382   gboolean res;
3383   GQuark detail;
3384
3385   /* init */
3386   g_value_init (&ret, G_TYPE_BOOLEAN);
3387   g_value_set_boolean (&ret, TRUE);
3388   g_value_init (&args[0], GST_TYPE_PAD);
3389   g_value_set_object (&args[0], pad);
3390   g_value_init (&args[1], GST_TYPE_MINI_OBJECT);
3391   gst_value_set_mini_object (&args[1], obj);
3392
3393   if (GST_IS_EVENT (obj))
3394     detail = event_quark;
3395   else
3396     detail = buffer_quark;
3397
3398   /* actually emit */
3399   g_signal_emitv (args, gst_pad_signals[PAD_HAVE_DATA], detail, &ret);
3400   res = g_value_get_boolean (&ret);
3401
3402   /* clean up */
3403   g_value_unset (&ret);
3404   g_value_unset (&args[0]);
3405   g_value_unset (&args[1]);
3406
3407   return res;
3408 }
3409
3410 /* this is the chain function that does not perform the additional argument
3411  * checking for that little extra speed.
3412  */
3413 static inline GstFlowReturn
3414 gst_pad_chain_unchecked (GstPad * pad, GstBuffer * buffer)
3415 {
3416   GstCaps *caps;
3417   gboolean caps_changed;
3418   GstPadChainFunction chainfunc;
3419   GstFlowReturn ret;
3420   gboolean emit_signal;
3421
3422   GST_PAD_STREAM_LOCK (pad);
3423
3424   GST_OBJECT_LOCK (pad);
3425   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
3426     goto flushing;
3427
3428   caps = GST_BUFFER_CAPS (buffer);
3429   caps_changed = caps && caps != GST_PAD_CAPS (pad);
3430
3431   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3432   GST_OBJECT_UNLOCK (pad);
3433
3434   /* see if the signal should be emited, we emit before caps nego as
3435    * we might drop the buffer and do capsnego for nothing. */
3436   if (G_UNLIKELY (emit_signal)) {
3437     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (buffer)))
3438       goto dropping;
3439   }
3440
3441   /* we got a new datatype on the pad, see if it can handle it */
3442   if (G_UNLIKELY (caps_changed)) {
3443     GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
3444     if (G_UNLIKELY (!gst_pad_configure_sink (pad, caps)))
3445       goto not_negotiated;
3446   }
3447
3448   /* NOTE: we read the chainfunc unlocked.
3449    * we cannot hold the lock for the pad so we might send
3450    * the data to the wrong function. This is not really a
3451    * problem since functions are assigned at creation time
3452    * and don't change that often... */
3453   if (G_UNLIKELY ((chainfunc = GST_PAD_CHAINFUNC (pad)) == NULL))
3454     goto no_function;
3455
3456   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3457       "calling chainfunction &%s", GST_DEBUG_FUNCPTR_NAME (chainfunc));
3458
3459   ret = chainfunc (pad, buffer);
3460
3461   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3462       "called chainfunction &%s, returned %s",
3463       GST_DEBUG_FUNCPTR_NAME (chainfunc), gst_flow_get_name (ret));
3464
3465   GST_PAD_STREAM_UNLOCK (pad);
3466
3467   return ret;
3468
3469   /* ERRORS */
3470 flushing:
3471   {
3472     gst_buffer_unref (buffer);
3473     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3474         "pushing, but pad was flushing");
3475     GST_OBJECT_UNLOCK (pad);
3476     GST_PAD_STREAM_UNLOCK (pad);
3477     return GST_FLOW_WRONG_STATE;
3478   }
3479 dropping:
3480   {
3481     gst_buffer_unref (buffer);
3482     GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
3483     GST_PAD_STREAM_UNLOCK (pad);
3484     return GST_FLOW_OK;
3485   }
3486 not_negotiated:
3487   {
3488     gst_buffer_unref (buffer);
3489     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3490         "pushing buffer but pad did not accept");
3491     GST_PAD_STREAM_UNLOCK (pad);
3492     return GST_FLOW_NOT_NEGOTIATED;
3493   }
3494 no_function:
3495   {
3496     gst_buffer_unref (buffer);
3497     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3498         "pushing, but not chainhandler");
3499     GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
3500         ("push on pad %s:%s but it has no chainfunction",
3501             GST_DEBUG_PAD_NAME (pad)));
3502     GST_PAD_STREAM_UNLOCK (pad);
3503     return GST_FLOW_NOT_SUPPORTED;
3504   }
3505 }
3506
3507 /**
3508  * gst_pad_chain:
3509  * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
3510  * @buffer: the #GstBuffer to send, return GST_FLOW_ERROR if not.
3511  *
3512  * Chain a buffer to @pad.
3513  *
3514  * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
3515  *
3516  * If the caps on @buffer are different from the current caps on @pad, this
3517  * function will call any setcaps function (see gst_pad_set_setcaps_function())
3518  * installed on @pad. If the new caps are not acceptable for @pad, this
3519  * function returns #GST_FLOW_NOT_NEGOTIATED.
3520  *
3521  * The function proceeds calling the chain function installed on @pad (see
3522  * gst_pad_set_chain_function()) and the return value of that function is
3523  * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
3524  * chain function.
3525  *
3526  * In all cases, success or failure, the caller loses its reference to @buffer
3527  * after calling this function.
3528  *
3529  * Returns: a #GstFlowReturn from the pad.
3530  *
3531  * MT safe.
3532  */
3533 GstFlowReturn
3534 gst_pad_chain (GstPad * pad, GstBuffer * buffer)
3535 {
3536   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3537   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK,
3538       GST_FLOW_ERROR);
3539   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
3540
3541   return gst_pad_chain_unchecked (pad, buffer);
3542 }
3543
3544 /**
3545  * gst_pad_push:
3546  * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
3547  * @buffer: the #GstBuffer to push returns GST_FLOW_ERROR if not.
3548  *
3549  * Pushes a buffer to the peer of @pad.
3550  *
3551  * This function will call an installed pad block before triggering any
3552  * installed pad probes.
3553  *
3554  * If the caps on @buffer are different from the currently configured caps on
3555  * @pad, this function will call any installed setcaps function on @pad (see
3556  * gst_pad_set_setcaps_function()). In case of failure to renegotiate the new
3557  * format, this function returns #GST_FLOW_NOT_NEGOTIATED.
3558  *
3559  * The function proceeds calling gst_pad_chain() on the peer pad and returns
3560  * the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will
3561  * be returned.
3562  *
3563  * In all cases, success or failure, the caller loses its reference to @buffer
3564  * after calling this function.
3565  *
3566  * Returns: a #GstFlowReturn from the peer pad.
3567  *
3568  * MT safe.
3569  */
3570 GstFlowReturn
3571 gst_pad_push (GstPad * pad, GstBuffer * buffer)
3572 {
3573   GstPad *peer;
3574   GstFlowReturn ret;
3575
3576   GstCaps *caps;
3577   gboolean caps_changed;
3578
3579   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3580   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC, GST_FLOW_ERROR);
3581   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
3582
3583   GST_OBJECT_LOCK (pad);
3584
3585   /* FIXME: this check can go away; pad_set_blocked could be implemented with
3586    * probes completely or probes with an extended pad block. */
3587   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
3588     if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
3589       goto flushed;
3590
3591   /* we emit signals on the pad arg, the peer will have a chance to
3592    * emit in the _chain() function */
3593   if (G_UNLIKELY (GST_PAD_DO_BUFFER_SIGNALS (pad) > 0)) {
3594     /* unlock before emitting */
3595     GST_OBJECT_UNLOCK (pad);
3596
3597     /* if the signal handler returned FALSE, it means we should just drop the
3598      * buffer */
3599     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (buffer)))
3600       goto dropped;
3601
3602     GST_OBJECT_LOCK (pad);
3603   }
3604
3605   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3606     goto not_linked;
3607
3608   /* take ref to peer pad before releasing the lock */
3609   gst_object_ref (peer);
3610
3611   /* Before pushing the buffer to the peer pad, ensure that caps
3612    * are set on this pad */
3613   caps = GST_BUFFER_CAPS (buffer);
3614   caps_changed = caps && caps != GST_PAD_CAPS (pad);
3615
3616   GST_OBJECT_UNLOCK (pad);
3617
3618   /* we got a new datatype from the pad, it had better handle it */
3619   if (G_UNLIKELY (caps_changed)) {
3620     GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
3621     if (G_UNLIKELY (!gst_pad_configure_src (pad, caps, TRUE)))
3622       goto not_negotiated;
3623   }
3624
3625   ret = gst_pad_chain_unchecked (peer, buffer);
3626
3627   gst_object_unref (peer);
3628
3629   return ret;
3630
3631   /* ERROR recovery here */
3632 flushed:
3633   {
3634     gst_buffer_unref (buffer);
3635     GST_DEBUG_OBJECT (pad, "pad block stopped by flush");
3636     GST_OBJECT_UNLOCK (pad);
3637     return ret;
3638   }
3639 dropped:
3640   {
3641     gst_buffer_unref (buffer);
3642     GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
3643     return GST_FLOW_OK;
3644   }
3645 not_linked:
3646   {
3647     gst_buffer_unref (buffer);
3648     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3649         "pushing, but it was not linked");
3650     GST_OBJECT_UNLOCK (pad);
3651     return GST_FLOW_NOT_LINKED;
3652   }
3653 not_negotiated:
3654   {
3655     gst_buffer_unref (buffer);
3656     gst_object_unref (peer);
3657     GST_CAT_DEBUG_OBJECT (GST_CAT_SCHEDULING, pad,
3658         "element pushed buffer then refused to accept the caps");
3659     return GST_FLOW_NOT_NEGOTIATED;
3660   }
3661 }
3662
3663 /**
3664  * gst_pad_check_pull_range:
3665  * @pad: a sink #GstPad.
3666  *
3667  * Checks if a gst_pad_pull_range() can be performed on the peer
3668  * source pad. This function is used by plugins that want to check
3669  * if they can use random access on the peer source pad.
3670  *
3671  * The peer sourcepad can implement a custom #GstPadCheckGetRangeFunction
3672  * if it needs to perform some logic to determine if pull_range is
3673  * possible.
3674  *
3675  * Returns: a gboolean with the result.
3676  *
3677  * MT safe.
3678  */
3679 gboolean
3680 gst_pad_check_pull_range (GstPad * pad)
3681 {
3682   GstPad *peer;
3683   gboolean ret;
3684   GstPadCheckGetRangeFunction checkgetrangefunc;
3685
3686   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3687
3688   GST_OBJECT_LOCK (pad);
3689   if (GST_PAD_DIRECTION (pad) != GST_PAD_SINK)
3690     goto wrong_direction;
3691
3692   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3693     goto not_connected;
3694
3695   gst_object_ref (peer);
3696   GST_OBJECT_UNLOCK (pad);
3697
3698   /* see note in above function */
3699   if (G_LIKELY ((checkgetrangefunc = peer->checkgetrangefunc) == NULL)) {
3700     /* FIXME, kindoff ghetto */
3701     ret = GST_PAD_GETRANGEFUNC (peer) != NULL;
3702     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3703         "no checkgetrangefunc, assuming %d", ret);
3704   } else {
3705     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3706         "calling checkgetrangefunc %s of peer pad %s:%s",
3707         GST_DEBUG_FUNCPTR_NAME (checkgetrangefunc), GST_DEBUG_PAD_NAME (peer));
3708
3709     ret = checkgetrangefunc (peer);
3710   }
3711
3712   gst_object_unref (peer);
3713
3714   return ret;
3715
3716   /* ERROR recovery here */
3717 wrong_direction:
3718   {
3719     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3720         "checking pull range, but pad must be a sinkpad");
3721     GST_OBJECT_UNLOCK (pad);
3722     return FALSE;
3723   }
3724 not_connected:
3725   {
3726     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3727         "checking pull range, but it was not linked");
3728     GST_OBJECT_UNLOCK (pad);
3729     return FALSE;
3730   }
3731 }
3732
3733 /**
3734  * gst_pad_get_range:
3735  * @pad: a src #GstPad, returns #GST_FLOW_ERROR if not.
3736  * @offset: The start offset of the buffer
3737  * @size: The length of the buffer
3738  * @buffer: a pointer to hold the #GstBuffer, returns #GST_FLOW_ERROR if %NULL.
3739  *
3740  * When @pad is flushing this function returns #GST_FLOW_WRONG_STATE
3741  * immediatly.
3742  *
3743  * Calls the getrange function of @pad, see #GstPadGetRangeFunction for a
3744  * description of a getrange function. If @pad has no getrange function
3745  * installed (see gst_pad_set_getrange_function()) this function returns
3746  * #GST_FLOW_NOT_SUPPORTED.
3747  *
3748  * @buffer's caps must either be unset or the same as what is already
3749  * configured on @pad. Renegotiation within a running pull-mode pipeline is not
3750  * supported.
3751  *
3752  * This is a lowlevel function. Usualy gst_pad_pull_range() is used.
3753  *
3754  * Returns: a #GstFlowReturn from the pad.
3755  *
3756  * MT safe.
3757  */
3758 GstFlowReturn
3759 gst_pad_get_range (GstPad * pad, guint64 offset, guint size,
3760     GstBuffer ** buffer)
3761 {
3762   GstFlowReturn ret;
3763   GstPadGetRangeFunction getrangefunc;
3764   gboolean emit_signal;
3765
3766   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3767   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC, GST_FLOW_ERROR);
3768   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
3769
3770   GST_PAD_STREAM_LOCK (pad);
3771
3772   GST_OBJECT_LOCK (pad);
3773   if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
3774     goto flushing;
3775
3776   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3777   GST_OBJECT_UNLOCK (pad);
3778
3779   if (G_UNLIKELY ((getrangefunc = GST_PAD_GETRANGEFUNC (pad)) == NULL))
3780     goto no_function;
3781
3782   GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3783       "calling getrangefunc %s, offset %"
3784       G_GUINT64_FORMAT ", size %u",
3785       GST_DEBUG_FUNCPTR_NAME (getrangefunc), offset, size);
3786
3787   ret = getrangefunc (pad, offset, size, buffer);
3788
3789   /* can only fire the signal if we have a valid buffer */
3790   if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
3791     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
3792       goto dropping;
3793   }
3794
3795   GST_PAD_STREAM_UNLOCK (pad);
3796
3797   if (G_LIKELY (ret == GST_FLOW_OK)) {
3798     GstCaps *caps;
3799     gboolean caps_changed;
3800
3801     GST_OBJECT_LOCK (pad);
3802     /* Before pushing the buffer to the peer pad, ensure that caps
3803      * are set on this pad */
3804     caps = GST_BUFFER_CAPS (*buffer);
3805     caps_changed = caps && caps != GST_PAD_CAPS (pad);
3806     GST_OBJECT_UNLOCK (pad);
3807
3808     /* we got a new datatype from the pad not supported in a running pull-mode
3809      * pipeline */
3810     if (G_UNLIKELY (caps_changed))
3811       goto not_negotiated;
3812   }
3813
3814   return ret;
3815
3816   /* ERRORS */
3817 flushing:
3818   {
3819     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3820         "pulling range, but pad was flushing");
3821     GST_OBJECT_UNLOCK (pad);
3822     GST_PAD_STREAM_UNLOCK (pad);
3823     return GST_FLOW_WRONG_STATE;
3824   }
3825 no_function:
3826   {
3827     GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
3828         ("pullrange on pad %s:%s but it has no getrangefunction",
3829             GST_DEBUG_PAD_NAME (pad)));
3830     GST_PAD_STREAM_UNLOCK (pad);
3831     return GST_FLOW_NOT_SUPPORTED;
3832   }
3833 dropping:
3834   {
3835     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3836         "Dropping data after FALSE probe return");
3837     GST_PAD_STREAM_UNLOCK (pad);
3838     gst_buffer_unref (*buffer);
3839     *buffer = NULL;
3840     return GST_FLOW_UNEXPECTED;
3841   }
3842 not_negotiated:
3843   {
3844     /* ideally we want to use the commented-out code, but currently demuxers
3845      * and typefind do not follow part-negotiation.txt. When switching into
3846      * pull mode, typefind should probably return the found caps from
3847      * getcaps(), and demuxers should do the setcaps(). */
3848
3849 #if 0
3850     gst_buffer_unref (*buffer);
3851     *buffer = NULL;
3852     GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
3853         "getrange returned buffer of different caps");
3854     return GST_FLOW_NOT_NEGOTIATED;
3855 #endif
3856     GST_CAT_DEBUG_OBJECT (GST_CAT_SCHEDULING, pad,
3857         "getrange returned buffer of different caps");
3858     return ret;
3859   }
3860 }
3861
3862
3863 /**
3864  * gst_pad_pull_range:
3865  * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
3866  * @offset: The start offset of the buffer
3867  * @size: The length of the buffer
3868  * @buffer: a pointer to hold the #GstBuffer, returns GST_FLOW_ERROR if %NULL.
3869  *
3870  * Pulls a @buffer from the peer pad.
3871  *
3872  * This function will first trigger the pad block signal if it was
3873  * installed.
3874  *
3875  * When @pad is not linked #GST_FLOW_NOT_LINKED is returned else this
3876  * function returns the result of gst_pad_get_range() on the peer pad.
3877  * See gst_pad_get_range() for a list of return values and for the
3878  * semantics of the arguments of this function.
3879  *
3880  * @buffer's caps must either be unset or the same as what is already
3881  * configured on @pad. Renegotiation within a running pull-mode pipeline is not
3882  * supported.
3883  *
3884  * Returns: a #GstFlowReturn from the peer pad.
3885  * When this function returns #GST_FLOW_OK, @buffer will contain a valid
3886  * #GstBuffer that should be freed with gst_buffer_unref() after usage.
3887  * @buffer may not be used or freed when any other return value than
3888  * #GST_FLOW_OK is returned.
3889  *
3890  * MT safe.
3891  */
3892 GstFlowReturn
3893 gst_pad_pull_range (GstPad * pad, guint64 offset, guint size,
3894     GstBuffer ** buffer)
3895 {
3896   GstPad *peer;
3897   GstFlowReturn ret;
3898   gboolean emit_signal;
3899
3900   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3901   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK,
3902       GST_FLOW_ERROR);
3903   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
3904
3905   GST_OBJECT_LOCK (pad);
3906
3907   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
3908     handle_pad_block (pad);
3909
3910   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3911     goto not_connected;
3912
3913   /* signal emision for the pad, peer has chance to emit when
3914    * we call _get_range() */
3915   emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3916
3917   gst_object_ref (peer);
3918   GST_OBJECT_UNLOCK (pad);
3919
3920   ret = gst_pad_get_range (peer, offset, size, buffer);
3921
3922   gst_object_unref (peer);
3923
3924   /* can only fire the signal if we have a valid buffer */
3925   if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
3926     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
3927       goto dropping;
3928   }
3929
3930   if (G_LIKELY (ret == GST_FLOW_OK)) {
3931     GstCaps *caps;
3932     gboolean caps_changed;
3933
3934     GST_OBJECT_LOCK (pad);
3935     /* Before pushing the buffer to the peer pad, ensure that caps
3936      * are set on this pad */
3937     caps = GST_BUFFER_CAPS (*buffer);
3938     caps_changed = caps && caps != GST_PAD_CAPS (pad);
3939     GST_OBJECT_UNLOCK (pad);
3940
3941     /* we got a new datatype on the pad, see if it can handle it */
3942     if (G_UNLIKELY (caps_changed))
3943       goto not_negotiated;
3944   }
3945
3946   return ret;
3947
3948   /* ERROR recovery here */
3949 not_connected:
3950   {
3951     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3952         "pulling range, but it was not linked");
3953     GST_OBJECT_UNLOCK (pad);
3954     return GST_FLOW_NOT_LINKED;
3955   }
3956 dropping:
3957   {
3958     GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3959         "Dropping data after FALSE probe return");
3960     gst_buffer_unref (*buffer);
3961     *buffer = NULL;
3962     return GST_FLOW_UNEXPECTED;
3963   }
3964 not_negotiated:
3965   {
3966     /* ideally we want to use the commented-out code, but currently demuxers
3967      * and typefind do not follow part-negotiation.txt. When switching into
3968      * pull mode, typefind should probably return the found caps from
3969      * getcaps(), and demuxers should do the setcaps(). */
3970
3971 #if 0
3972     gst_buffer_unref (*buffer);
3973     *buffer = NULL;
3974     GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
3975         "pullrange returned buffer of different caps");
3976     return GST_FLOW_NOT_NEGOTIATED;
3977 #endif
3978     GST_CAT_DEBUG_OBJECT (GST_CAT_SCHEDULING, pad,
3979         "pullrange returned buffer of different caps");
3980     return ret;
3981   }
3982 }
3983
3984 /**
3985  * gst_pad_push_event:
3986  * @pad: a #GstPad to push the event to.
3987  * @event: the #GstEvent to send to the pad.
3988  *
3989  * Sends the event to the peer of the given pad. This function is
3990  * mainly used by elements to send events to their peer
3991  * elements.
3992  *
3993  * This function takes owership of the provided event so you should
3994  * gst_event_ref() it if you want to reuse the event after this call.
3995  *
3996  * Returns: TRUE if the event was handled.
3997  *
3998  * MT safe.
3999  */
4000 gboolean
4001 gst_pad_push_event (GstPad * pad, GstEvent * event)
4002 {
4003   GstPad *peerpad;
4004   gboolean result;
4005
4006   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4007   g_return_val_if_fail (event != NULL, FALSE);
4008   g_return_val_if_fail (GST_IS_EVENT (event), FALSE);
4009
4010   GST_LOG_OBJECT (pad, "event: %s", GST_EVENT_TYPE_NAME (event));
4011
4012   GST_OBJECT_LOCK (pad);
4013
4014   /* Two checks to be made:
4015    * . (un)set the FLUSHING flag for flushing events,
4016    * . handle pad blocking */
4017   switch (GST_EVENT_TYPE (event)) {
4018     case GST_EVENT_FLUSH_START:
4019       GST_PAD_SET_FLUSHING (pad);
4020
4021       if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4022         /* flush start will have set the FLUSHING flag and will then
4023          * unlock all threads doing a GCond wait on the blocking pad. This
4024          * will typically unblock the STREAMING thread blocked on a pad. */
4025         GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-start, "
4026             "doing block signal.");
4027         GST_PAD_BLOCK_BROADCAST (pad);
4028         goto flushed;
4029       }
4030       break;
4031     case GST_EVENT_FLUSH_STOP:
4032       GST_PAD_UNSET_FLUSHING (pad);
4033
4034       /* if we are blocked, flush away the FLUSH_STOP event */
4035       if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4036         GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-stop");
4037         goto flushed;
4038       }
4039       break;
4040     default:
4041       while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4042         /* block the event as long as the pad is blocked */
4043         if (handle_pad_block (pad) != GST_FLOW_OK)
4044           goto flushed;
4045       }
4046       break;
4047   }
4048
4049   if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
4050     GST_OBJECT_UNLOCK (pad);
4051
4052     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (event)))
4053       goto dropping;
4054
4055     GST_OBJECT_LOCK (pad);
4056   }
4057   peerpad = GST_PAD_PEER (pad);
4058   if (peerpad == NULL)
4059     goto not_linked;
4060
4061   GST_LOG_OBJECT (pad, "sending event %s to peerpad %" GST_PTR_FORMAT,
4062       GST_EVENT_TYPE_NAME (event), peerpad);
4063   gst_object_ref (peerpad);
4064   GST_OBJECT_UNLOCK (pad);
4065
4066   result = gst_pad_send_event (peerpad, event);
4067
4068   /* Note: we gave away ownership of the event at this point */
4069   GST_LOG_OBJECT (pad, "sent event to peerpad %" GST_PTR_FORMAT, peerpad);
4070   gst_object_unref (peerpad);
4071
4072   return result;
4073
4074   /* ERROR handling */
4075 dropping:
4076   {
4077     GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
4078     gst_event_unref (event);
4079     return FALSE;
4080   }
4081 not_linked:
4082   {
4083     GST_DEBUG_OBJECT (pad, "Dropping event because pad is not linked");
4084     gst_event_unref (event);
4085     GST_OBJECT_UNLOCK (pad);
4086     return FALSE;
4087   }
4088 flushed:
4089   {
4090     GST_DEBUG_OBJECT (pad,
4091         "Not forwarding event since we're flushing and blocking");
4092     gst_event_unref (event);
4093     GST_OBJECT_UNLOCK (pad);
4094     return TRUE;
4095   }
4096 }
4097
4098 /**
4099  * gst_pad_send_event:
4100  * @pad: a #GstPad to send the event to.
4101  * @event: the #GstEvent to send to the pad.
4102  *
4103  * Sends the event to the pad. This function can be used
4104  * by applications to send events in the pipeline.
4105  *
4106  * If @pad is a source pad, @event should be an upstream event. If @pad is a
4107  * sink pad, @event should be a downstream event. For example, you would not
4108  * send a #GST_EVENT_EOS on a src pad; EOS events only propagate downstream.
4109  * Furthermore, some downstream events have to be serialized with data flow,
4110  * like EOS, while some can travel out-of-band, like #GST_EVENT_FLUSH_START. If
4111  * the event needs to be serialized with data flow, this function will take the
4112  * pad's stream lock while calling its event function.
4113  *
4114  * To find out whether an event type is upstream, downstream, or downstream and
4115  * serialized, see #GstEventTypeFlags, gst_event_type_get_flags(),
4116  * #GST_EVENT_IS_UPSTREAM, #GST_EVENT_IS_DOWNSTREAM, and
4117  * #GST_EVENT_IS_SERIALIZED. Note that in practice that an application or
4118  * plugin doesn't need to bother itself with this information; the core handles
4119  * all necessary locks and checks.
4120  *
4121  * This function takes owership of the provided event so you should
4122  * gst_event_ref() it if you want to reuse the event after this call.
4123  *
4124  * Returns: TRUE if the event was handled.
4125  */
4126 gboolean
4127 gst_pad_send_event (GstPad * pad, GstEvent * event)
4128 {
4129   gboolean result = FALSE;
4130   GstPadEventFunction eventfunc;
4131   gboolean serialized, need_unlock = FALSE;
4132
4133   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4134   g_return_val_if_fail (event != NULL, FALSE);
4135
4136   GST_OBJECT_LOCK (pad);
4137   if (GST_PAD_IS_SINK (pad)) {
4138     if (G_UNLIKELY (!GST_EVENT_IS_DOWNSTREAM (event)))
4139       goto wrong_direction;
4140     serialized = GST_EVENT_IS_SERIALIZED (event);
4141   } else if (GST_PAD_IS_SRC (pad)) {
4142     if (G_UNLIKELY (!GST_EVENT_IS_UPSTREAM (event)))
4143       goto wrong_direction;
4144     /* events on srcpad never are serialized */
4145     serialized = FALSE;
4146   } else
4147     goto unknown_direction;
4148
4149   if (G_UNLIKELY (GST_EVENT_SRC (event) == NULL)) {
4150     GST_LOG_OBJECT (pad, "event had no source, setting pad as event source");
4151     GST_EVENT_SRC (event) = gst_object_ref (pad);
4152   }
4153
4154   /* pad signals */
4155   if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
4156     GST_OBJECT_UNLOCK (pad);
4157
4158     if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (event)))
4159       goto dropping;
4160
4161     GST_OBJECT_LOCK (pad);
4162   }
4163
4164   switch (GST_EVENT_TYPE (event)) {
4165     case GST_EVENT_FLUSH_START:
4166       GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad,
4167           "have event type %d (FLUSH_START)", GST_EVENT_TYPE (event));
4168
4169       /* can't even accept a flush begin event when flushing */
4170       if (GST_PAD_IS_FLUSHING (pad))
4171         goto flushing;
4172       GST_PAD_SET_FLUSHING (pad);
4173       GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "set flush flag");
4174       break;
4175     case GST_EVENT_FLUSH_STOP:
4176       GST_PAD_UNSET_FLUSHING (pad);
4177       GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "cleared flush flag");
4178       GST_OBJECT_UNLOCK (pad);
4179       /* grab stream lock */
4180       GST_PAD_STREAM_LOCK (pad);
4181       need_unlock = TRUE;
4182       GST_OBJECT_LOCK (pad);
4183       break;
4184     default:
4185       GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "have event type %s",
4186           GST_EVENT_TYPE_NAME (event));
4187
4188       /* make this a little faster, no point in grabbing the lock
4189        * if the pad is allready flushing. */
4190       if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4191         goto flushing;
4192
4193       if (serialized) {
4194         /* lock order: STREAM_LOCK, LOCK, recheck flushing. */
4195         GST_OBJECT_UNLOCK (pad);
4196         GST_PAD_STREAM_LOCK (pad);
4197         need_unlock = TRUE;
4198         GST_OBJECT_LOCK (pad);
4199         if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4200           goto flushing;
4201       }
4202       break;
4203   }
4204   if (G_UNLIKELY ((eventfunc = GST_PAD_EVENTFUNC (pad)) == NULL))
4205     goto no_function;
4206
4207   GST_OBJECT_UNLOCK (pad);
4208
4209   result = eventfunc (pad, event);
4210
4211   if (need_unlock)
4212     GST_PAD_STREAM_UNLOCK (pad);
4213
4214   return result;
4215
4216   /* ERROR handling */
4217 wrong_direction:
4218   {
4219     g_warning ("pad %s:%s sending %s event in wrong direction",
4220         GST_DEBUG_PAD_NAME (pad), GST_EVENT_TYPE_NAME (event));
4221     GST_OBJECT_UNLOCK (pad);
4222     gst_event_unref (event);
4223     return FALSE;
4224   }
4225 unknown_direction:
4226   {
4227     g_warning ("pad %s:%s has invalid direction", GST_DEBUG_PAD_NAME (pad));
4228     GST_OBJECT_UNLOCK (pad);
4229     gst_event_unref (event);
4230     return FALSE;
4231   }
4232 no_function:
4233   {
4234     g_warning ("pad %s:%s has no event handler, file a bug.",
4235         GST_DEBUG_PAD_NAME (pad));
4236     GST_OBJECT_UNLOCK (pad);
4237     if (need_unlock)
4238       GST_PAD_STREAM_UNLOCK (pad);
4239     gst_event_unref (event);
4240     return FALSE;
4241   }
4242 flushing:
4243   {
4244     GST_OBJECT_UNLOCK (pad);
4245     if (need_unlock)
4246       GST_PAD_STREAM_UNLOCK (pad);
4247     GST_CAT_INFO_OBJECT (GST_CAT_EVENT, pad,
4248         "Received event on flushing pad. Discarding");
4249     gst_event_unref (event);
4250     return FALSE;
4251   }
4252 dropping:
4253   {
4254     GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
4255     gst_event_unref (event);
4256     return FALSE;
4257   }
4258 }
4259
4260 /**
4261  * gst_pad_set_element_private:
4262  * @pad: the #GstPad to set the private data of.
4263  * @priv: The private data to attach to the pad.
4264  *
4265  * Set the given private data gpointer on the pad.
4266  * This function can only be used by the element that owns the pad.
4267  * No locking is performed in this function.
4268  */
4269 void
4270 gst_pad_set_element_private (GstPad * pad, gpointer priv)
4271 {
4272   pad->element_private = priv;
4273 }
4274
4275 /**
4276  * gst_pad_get_element_private:
4277  * @pad: the #GstPad to get the private data of.
4278  *
4279  * Gets the private data of a pad.
4280  * No locking is performed in this function.
4281  *
4282  * Returns: a #gpointer to the private data.
4283  */
4284 gpointer
4285 gst_pad_get_element_private (GstPad * pad)
4286 {
4287   return pad->element_private;
4288 }
4289
4290 /**
4291  * gst_pad_start_task:
4292  * @pad: the #GstPad to start the task of
4293  * @func: the task function to call
4294  * @data: data passed to the task function
4295  *
4296  * Starts a task that repeatedly calls @func with @data. This function
4297  * is mostly used in pad activation functions to start the dataflow.
4298  * The #GST_PAD_STREAM_LOCK of @pad will automatically be acquired
4299  * before @func is called.
4300  *
4301  * Returns: a %TRUE if the task could be started.
4302  */
4303 gboolean
4304 gst_pad_start_task (GstPad * pad, GstTaskFunction func, gpointer data)
4305 {
4306   GstTask *task;
4307
4308   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4309   g_return_val_if_fail (func != NULL, FALSE);
4310
4311   GST_DEBUG_OBJECT (pad, "start task");
4312
4313   GST_OBJECT_LOCK (pad);
4314   task = GST_PAD_TASK (pad);
4315   if (task == NULL) {
4316     task = gst_task_create (func, data);
4317     gst_task_set_lock (task, GST_PAD_GET_STREAM_LOCK (pad));
4318     GST_PAD_TASK (pad) = task;
4319     GST_DEBUG_OBJECT (pad, "created task");
4320   }
4321   gst_task_start (task);
4322   GST_OBJECT_UNLOCK (pad);
4323
4324   return TRUE;
4325 }
4326
4327 /**
4328  * gst_pad_pause_task:
4329  * @pad: the #GstPad to pause the task of
4330  *
4331  * Pause the task of @pad. This function will also make sure that the
4332  * function executed by the task will effectively stop.
4333  *
4334  * Returns: a TRUE if the task could be paused or FALSE when the pad
4335  * has no task.
4336  */
4337 gboolean
4338 gst_pad_pause_task (GstPad * pad)
4339 {
4340   GstTask *task;
4341
4342   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4343
4344   GST_DEBUG_OBJECT (pad, "pause task");
4345
4346   GST_OBJECT_LOCK (pad);
4347   task = GST_PAD_TASK (pad);
4348   if (task == NULL)
4349     goto no_task;
4350   gst_task_pause (task);
4351   GST_OBJECT_UNLOCK (pad);
4352
4353   GST_PAD_STREAM_LOCK (pad);
4354   GST_PAD_STREAM_UNLOCK (pad);
4355
4356   return TRUE;
4357
4358 no_task:
4359   {
4360     GST_DEBUG_OBJECT (pad, "pad has no task");
4361     GST_OBJECT_UNLOCK (pad);
4362     return FALSE;
4363   }
4364 }
4365
4366 /**
4367  * gst_pad_stop_task:
4368  * @pad: the #GstPad to stop the task of
4369  *
4370  * Stop the task of @pad. This function will also make sure that the
4371  * function executed by the task will effectively stop if not called
4372  * from the GstTaskFunction.
4373  *
4374  * This function will deadlock if called from the GstTaskFunction of
4375  * the task. Use gst_task_pause() instead.
4376  *
4377  * Regardless of whether the pad has a task, the stream lock is acquired and
4378  * released so as to ensure that streaming through this pad has finished.
4379  *
4380  * Returns: a TRUE if the task could be stopped or FALSE on error.
4381  */
4382 gboolean
4383 gst_pad_stop_task (GstPad * pad)
4384 {
4385   GstTask *task;
4386
4387   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4388
4389   GST_DEBUG_OBJECT (pad, "stop task");
4390
4391   GST_OBJECT_LOCK (pad);
4392   task = GST_PAD_TASK (pad);
4393   if (task == NULL)
4394     goto no_task;
4395   GST_PAD_TASK (pad) = NULL;
4396   gst_task_stop (task);
4397   GST_OBJECT_UNLOCK (pad);
4398
4399   GST_PAD_STREAM_LOCK (pad);
4400   GST_PAD_STREAM_UNLOCK (pad);
4401
4402   if (!gst_task_join (task))
4403     goto join_failed;
4404
4405   gst_object_unref (task);
4406
4407   return TRUE;
4408
4409 no_task:
4410   {
4411     GST_DEBUG_OBJECT (pad, "no task");
4412     GST_OBJECT_UNLOCK (pad);
4413
4414     GST_PAD_STREAM_LOCK (pad);
4415     GST_PAD_STREAM_UNLOCK (pad);
4416
4417     /* this is not an error */
4418     return TRUE;
4419   }
4420 join_failed:
4421   {
4422     /* this is bad, possibly the application tried to join the task from
4423      * the task's thread. We install the task again so that it will be stopped
4424      * again from the right thread next time hopefully. */
4425     GST_OBJECT_LOCK (pad);
4426     GST_DEBUG_OBJECT (pad, "join failed");
4427     /* we can only install this task if there was no other task */
4428     if (GST_PAD_TASK (pad) == NULL)
4429       GST_PAD_TASK (pad) = task;
4430     GST_OBJECT_UNLOCK (pad);
4431
4432     return FALSE;
4433   }
4434 }