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